release: 0.96.0 (feature/e28-design-constitution)

chore(release): 0.96.0 — the design constitution
E28: one action list per object, keyboard reorder, touch drawers and player controls, the table pager, plus four deep-review fix rounds (playlist sync locking, player restart and focus behaviour).
2026-09-27 22:46:39 +02:00 · 2026-09-27 22:46:39 +02:00 · 2026-09-27 22:34:14 +02:00 · 2026-09-27 22:34:14 +02:00 · 2026-09-27 21:56:24 +02:00 · 2026-09-27 21:56:23 +02:00
564 changed files with 39548 additions and 13201 deletions
@@ -1,22 +1,50 @@
 # Server-side mirror of the local `siftlode check` gate (E1 S3 / DX-1), so `main` is always green
-# independent of any one machine. Two parallel jobs match the two local lanes:
+# independent of any one machine. Two jobs match the two local lanes:
 #   frontend — tsc (3 projects) + eslint + prettier --check + knip + vitest
 #   backend  — ruff + the full pytest suite (pure-logic + the DB-backed lane) against a real Postgres
 #
+# They are declared side by side but they DO NOT run in parallel: the lab has a single act_runner
+# with one slot, so they queue. Measured across runs #86-#91 — the backend job starts at the exact
+# second the frontend one ends, every time, and the pair costs ~4 + ~6 = **~10 minutes from the
+# push**. Anything that waits on this gate has to budget for the sum, not the max; the ops
+# `release` read-back timed out on its first real run for believing otherwise.
+#
 # Runner: the lab act_runner (LXC 115) mounts the Docker socket, so service containers work. The backend
 # runs pytest NATIVELY against a `postgres` service (not the local docker-compose.test.yml, whose
 # bind-mount is unreliable under a mounted-socket runner); fidelity is kept by installing the SAME pinned
 # requirements, Postgres 16, and ffmpeg, and by setting SIFTLODE_TEST_REQUIRE_DB=1 so a DB/ffmpeg that
-# failed to come up is a hard error, never a silent skip. node 22 matches the prod build image
-# (Dockerfile `node:22-alpine`).
+# failed to come up is a hard error, never a silent skip.
+#
+# The frontend container's node major is NOT free: it must equal the prod build image's and the dev
+# machine's, because vitest/tsc read the engine's own Intl and web-API implementations and those split
+# between majors. `.nvmrc` is the single source of truth and
+# `frontend/src/lib/nodeEngine.contract.test.ts` fails this gate if any of them drift apart.
 name: gate

-on: [push, pull_request]
+# Branch pushes only. A release pushes `main` and then the `v<ver>` tag, and a bare `on: [push]`
+# treated the tag as a second push of the IDENTICAL commit — every release ran this whole gate
+# twice, to the same verdict, for nothing (runs #81-#90 are five such pairs). `branches: ['**']`
+# keeps every branch covered and drops tag refs.
+#
+# It has to be `branches`, NOT the `tags-ignore` this obviously wants to be. Gitea's matchPushEvent
+# requires EVERY named filter to match, and each one bails on the wrong ref kind: `tags-ignore`
+# starts with `if !refName.IsTag() { break }`, so a filter meant to skip tags rejects every BRANCH
+# push and the gate stops running entirely. `branches` bails the same way on a tag, which is the
+# direction we want. (Measured in go-gitea v1.27.3 modules/actions/workflows.go, not assumed — it
+# differs from GitHub, where `tags-ignore` alone leaves branches unfiltered.)
+#
+# If that filter were ever wrong the gate would not run at all — which is why `siftlode release`
+# now ends by reading the verdict back for the sha it pushed, and says so out loud when there is
+# no run for it. A gate that silently stops running is the failure this repo already lived through.
+on:
+  push:
+    branches: ["**"]
+  pull_request:

 jobs:
  frontend:
    runs-on: ubuntu-latest
-    container: node:22-bookworm
+    container: node:24-bookworm
    defaults:
      run:
        working-directory: frontend
@@ -34,7 +62,11 @@ jobs:
    # A combined python+node image: python 3.12 (matches the prod Dockerfile) for the tests, and node
    # so the JS actions (checkout) run. actions/setup-python is NOT usable here — the runner can't reach
    # GitHub's python-versions download, so it must be baked into the image.
-    container: nikolaik/python-nodejs:python3.12-nodejs20
+    #
+    # This node runs the checkout action, never our code, so it is deliberately OUTSIDE the engine
+    # contract the frontend job is held to — it tracks `.nvmrc` as hygiene (node 20 went EOL in April
+    # 2026), but a missing upstream tag here must never be able to block the gate.
+    container: nikolaik/python-nodejs:python3.12-nodejs24
    services:
      postgres:
        image: postgres:16-alpine
@@ -61,6 +93,22 @@ jobs:
        run: python -m ruff check --config backend/ruff.toml backend scripts
      - name: ruff format --check
        run: python -m ruff format --check --config backend/ruff.toml backend scripts
+      # The ninth lane (E27 S3). Run from backend/ so it resolves exactly as the local lane does —
+      # pyrightconfig.json's include/extraPaths are relative to the config, but the baseline is
+      # found relative to the working directory. New errors fail; the ~200 pre-existing ones are in
+      # .basedpyright/baseline.json and burn down epic by epic. Matching is per (file, rule, column
+      # span) plus a count, so a new error of the SAME shape in a file where a sibling was just
+      # fixed is absorbed — burn the hot files down first.
+      #
+      # The second step is not redundant. basedpyright TIGHTENS the baseline in place when the count
+      # drops, with no --writebaseline, and CI throws its workspace away — so without this a
+      # burn-down is green here and red on the developer's `siftlode check`, which has the same
+      # guard. Two gates over one tree must not answer differently.
+      - name: basedpyright
+        run: python -m basedpyright --project pyrightconfig.json
+        working-directory: backend
+      - name: basedpyright baseline is committed
+        run: git diff --exit-code -- backend/.basedpyright/baseline.json
      - name: pytest
        run: python -m pytest
        working-directory: backend
@@ -37,3 +37,7 @@ backups/
 Thumbs.db
 .idea/
 .vscode/
+
+# TypeScript incremental build artifacts — machine-local, absolute-path-bearing, and no gate lane
+# reads or regenerates them, so a committed one is stale from the commit that adds it.
+*.tsbuildinfo
@@ -0,0 +1 @@
+24
@@ -0,0 +1 @@
+3.12
@@ -7,17 +7,18 @@ worse than no rule — if you change how the code works, change this file in the

 Siftlode is a self-hosted YouTube reader (+ a local Plex browser/player and a download center). It is a
 **modular monolith**: one Postgres, one FastAPI process (uvicorn + APScheduler), one worker process
-(yt-dlp/ffmpeg), one PO-token sidecar. React 18 + react-query frontend with a router-free navigation
-provider.
+(yt-dlp/ffmpeg), one PO-token sidecar. React 19 (with the React Compiler) + react-query frontend, with a
+router-free navigation provider.

 ## The gate — never merge or ship red

-The local gate is **ruff (`check` + `format --check`) + typecheck (3 tsc projects) + eslint + prettier
+The local gate is **ruff (`check` + `format --check`) + basedpyright (backend) + typecheck (3 tsc projects) + eslint + prettier
 --check + knip + vitest + pytest**. It runs on every `publish`, which **refuses to build on failure — there is deliberately no
 `--skip` flag.** Run it and get it green **before** any merge, release, or handing work to review.

 - Full gate (agents with the private ops dispatcher): `siftlode check`.
 - Directly, without the dispatcher: `cd frontend && npm run typecheck && npm run lint && npm run knip && npm run test`, plus backend `ruff check backend` + `ruff format --check backend` and `pytest` (the DB-lane needs Postgres).
+- **The backend type lane runs in the test image, not on the host** — `requirements.lock` cannot be installed on Windows (uvloop), and a type checker without the real packages reports nonsense. It fails on NEW errors only; the pre-existing ones sit in `backend/.basedpyright/baseline.json` and burn down epic by epic. Fixed some? Regenerate with `--writebaseline`.
 - New DB-backed test? It must actually run, not silently skip — assume `SIFTLODE_TEST_REQUIRE_DB=1`.

 ## Workflow
@@ -45,11 +46,13 @@ how it gets built. Concretely:
  behind each option and the weight of the decision. These decision points are where the product owner
  engages with the build and learns from it, so make them understandable — a reasoned menu, not a bare one.
 - **Mockups for design/UX decisions.** For any visual or interaction choice, show mockup options to
-  choose from before building.
+  choose from before building. How the UI looks and behaves is decided in
+  [`docs/DESIGN.md`](docs/DESIGN.md) (its variants render in the dev-only `/design-lab`): build to it,
+  and change it only through its decision log.
 - **Challenge unsound requests.** If a request is technically ill-advised and you can back it with real
  arguments, push back or propose an alternative — don't comply blindly.
 - **Verify UI in the browser before calling it done.** tsc/unit/DOM tests miss visual and interaction
-  bugs; do a real visual check of any UI change.
+  bugs; do a real visual check of any UI change, and run DESIGN.md's four-step Conformance check.
 - **Be terse everywhere else.** Outside those decision points, lead with the answer or decision. During
  implementation and debugging especially: no restating the same point reworded, no filler.

@@ -57,7 +60,7 @@ how it gets built. Concretely:

 `routes/*` (HTTP only: validation, auth-dependency, serialization) → domain packages `sync/`, `plex/`,
 `downloads/`, `youtube/`, `issues/` (shared by routes + scheduler + worker) → flat core (`auth`, `quota`,
-`sysconfig`, `state`, `audit`, `notifications`, `userscope`, `realtime`, `ratelimit`, `progress`,
+`sysconfig`, `state`, `audit`, `notifications`, `userscope`, `realtime`, `ratelimit`, `bodylimit`, `progress`,
 `security`, `logs`, `logsink`, `diagnostics`, `debugsession`) → `models/db/config`. **Dependency direction is one-way: core never imports routes.**
 Frontend: `main.tsx` provider tree → `App.tsx` shell → `moduleRegistry` route-chunks → module
 components → the **platform layer `components/ui/`** (domain-free primitives: the popover engine and
@@ -74,29 +77,37 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory

 ## Canonical patterns — when you have a choice, pick THIS

-| Area                    | Use                                                          | Not                                                    |
-| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------ |
-| ORM                     | SQLAlchemy 2.0 `select()`                                    | `db.query(...)`                                        |
-| Request body            | a Pydantic model                                             | `payload: dict`                                        |
-| Ownership check         | `owned_or_404` / `get_or_404`                                | ad-hoc `_own_playlist`/`_owned`/`_own_job`             |
-| Admin gate import       | `app.auth`                                                   | the `app.routes.admin` re-export                       |
-| Upstream failure status | `422` with JSON detail                                       | `502` (reserve 502 for raw byte-proxies)               |
-| User-facing error       | structured `detail` (`{code, reason}`)                       | a bare English string under a bilingual UI             |
-| Mutation response       | `{"ok": true, …}` (`{"deleted": id}`), test-held             | a bare `{"unsubscribed"}`/`{"cleared": n}`, no `ok`    |
-| Transaction commit      | the handler commits; helpers `flush` (test-held list)        | helpers that commit (only `quota` owns its session)    |
-| Admin knob storage      | `sysconfig` (values)                                         | env / `app_state` / `scheduler_settings` scatter       |
-| Job status word         | the `downloads/status.py` StrEnum                            | loose `"canceled"`/`"cancelled"` literals              |
-| Current time            | inline `datetime.now(timezone.utc)`                          | new `now_utc`/`_now` helpers                           |
-| FE per-account state    | `usePref`                                                    | raw `readAccount`/`writeAccount` or bespoke hooks      |
-| FE action button        | `ui/Button` — pick a `SIZES` rung                            | a hand-rolled `<button className="px-3 py-2 …">`       |
-| FE keyboard shortcut    | a row in `lib/keymap.ts` + `dispatch()`                      | a private `keydown` listener with its own key literals |
-| FE 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 control              | `SegmentedToggle`; a long or user's list: `FilterSelect`     | a native `<select>` (lint-enforced)                    |
-| FE loading/empty/error  | `QueryState` / `StateMessage`                                | ad-hoc conditionals                                    |
-| FE failed write         | `meta.failTitle`, else `notifyActionError(err, title)`       | a bare `catch {}` or `notify()` with no error attached |
-| FE network call         | `req`/`uploadReq`/`beacon`, or `lib/http.ts` `send` (public pages) | a bare `fetch`/`XMLHttpRequest`/`WebSocket` (lint-enforced) |
-| FE diagnostics          | `lib/log.ts` (`log.info("event.code", msg, attrs)`); a filter change → `lib/filterLog.ts`, a player → `lib/mediaLog.ts` | `console.*` (lint-enforced); a value only a higher level may carry, logged unguarded |
+| Area                                 | Use                                                                                                                     | Not                                                                                  |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| ORM                                  | SQLAlchemy 2.0 `select()`                                                                                               | `db.query(...)`                                                                      |
+| Request body                         | a Pydantic model                                                                                                        | `payload: dict`                                                                      |
+| Request SIZE                         | nothing — `bodylimit` caps every route (SEC-20); need more? add a ceiling to `ROUTE_MAX_BODY_BYTES`                     | `capped_body` on a route that does not read raw bytes itself                         |
+| Ownership check                      | `owned_or_404` / `get_or_404`                                                                                           | ad-hoc `_own_playlist`/`_owned`/`_own_job`                                           |
+| Admin gate import                    | `app.auth`                                                                                                              | the `app.routes.admin` re-export                                                     |
+| Upstream failure status              | `422` with JSON detail                                                                                                  | `502` (reserve 502 for raw byte-proxies)                                             |
+| User-facing error                    | structured `detail` (`{code, reason}`)                                                                                  | a bare English string under a bilingual UI                                           |
+| Mutation response                    | `{"ok": true, …}` (`{"deleted": id}`), test-held                                                                        | a bare `{"unsubscribed"}`/`{"cleared": n}`, no `ok`                                  |
+| Transaction commit                   | the handler commits; helpers `flush` (test-held list)                                                                   | helpers that commit (only `quota` owns its session)                                  |
+| Admin knob storage                   | `sysconfig` (values)                                                                                                    | env / `app_state` / `scheduler_settings` scatter                                     |
+| Job status word                      | the `downloads/status.py` StrEnum                                                                                       | loose `"canceled"`/`"cancelled"` literals                                            |
+| Current time                         | inline `datetime.now(timezone.utc)`                                                                                     | new `now_utc`/`_now` helpers                                                         |
+| FE per-account state                 | `usePref`                                                                                                               | raw `readAccount`/`writeAccount` or bespoke hooks                                    |
+| FE button                            | `ui/Button` (a `SIZES` rung) · `IconButton` · `Pressable` (a clickable card/row) · `Chip` · `DragHandle`                | a raw `<button>` or `FocusSafeButton` outside the control primitives (lint-enforced) |
+| 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 text field / checkbox / slider    | `ui/Input` · `Textarea` · `InnerInput` in a `fieldClass` frame · `Checkbox`/`CheckRow` · `Slider`                       | a raw `<input>`/`<textarea>` anywhere but those primitives (lint-enforced)           |
+| FE glass surface                     | a role: `SURFACE.panel` / `card` / `menu` / `popover` / `tooltip` (`ui/surfaces.ts`)                                    | a bare `glass`/`glass-card`/`glass-menu` beside a hand-picked radius (lint-enforced) |
+| FE static label / button-like link   | `Badge` (flat, no edge) · `LinkButton` / `IconLink`                                                                     | a glass pill that reads as a chip; an `<a>` hand-painted like a button               |
+| FE control                           | `SegmentedToggle`; a long or user's list: `FilterSelect`                                                                | a native `<select>` (lint-enforced)                                                  |
+| FE loading/empty/error               | `QueryState` / `StateMessage`                                                                                           | ad-hoc conditionals                                                                  |
+| FE failed write                      | `meta.failTitle`, else `notifyActionError(err, title)`                                                                  | a bare `catch {}` or `notify()` with no error attached                               |
+| FE network call                      | `req`/`uploadReq`/`beacon`, or `lib/http.ts` `send` (public pages)                                                      | a bare `fetch`/`XMLHttpRequest`/`WebSocket` (lint-enforced)                          |
+| FE diagnostics                       | `lib/log.ts` (`log.info("event.code", msg, attrs)`); a filter change → `lib/filterLog.ts`, a player → `lib/mediaLog.ts` | `console.*` (lint-enforced); a value only a higher level may carry, logged unguarded |
+| FE state that MIRRORS a prop/query   | derive it, or hold a draft (`draft ?? server`)                                                                          | a copy an effect re-syncs — that paints the stale value first                        |
+| FE state reset on a key change       | adjust it DURING render against a remembered key                                                                        | `useEffect(() => setX(init), [key])`                                                 |
+| FE effect that must not re-subscribe | `useEffectEvent` (React 19.2+), else a latest-value ref                                                                 | an excused dep list asserting the same thing in prose                                |
+| FE hook suppression                  | an inline `eslint-disable-next-line` NAMING the invariant                                                               | `eslint-suppressions.json` (deliberately absent — E27 S2)                            |

 ## House rules that bite (learned from real bugs)

@@ -10,7 +10,9 @@ ARG GIT_SHA=unknown
 ARG BUILD_DATE=

 # Stage 1: build the frontend SPA
-FROM node:22-alpine AS frontend
+# The major is pinned to `.nvmrc` and held there by frontend/src/lib/nodeEngine.contract.test.ts:
+# this image, the CI gate's image and the dev machine must be ONE engine (see that test for why).
+FROM node:24-alpine AS frontend
 WORKDIR /fe
 # Deps first, keyed on the lockfile, so editing app source never re-resolves node_modules.
 COPY frontend/package.json frontend/package-lock.json ./
@@ -1 +1 @@
-0.93.0
+0.96.0
@@ -0,0 +1,231 @@
+"""The global request-body cap (SEC-20).
+
+**The hole.** FastAPI reads a declared body IN FULL before auth or any other dependency runs — the
+body parameter has to be parsed to be passed in. So `POST /auth/password-login` drains a 32 MiB
+upload from an anonymous caller and only then answers 401. 70 of the 72 body-declaring routes behave
+the same way: one unauthenticated client can spend the process's memory and time at will.
+
+**Why a middleware and not `capped_body` on every route.** `routes/_common.py:capped_body` is the
+right tool where a route genuinely takes bulk bytes, and the two routes that use it use it
+correctly. But putting it on all 70 others would (a) fight the canonical "Request body → a Pydantic
+model" row, since capping means taking the body as raw bytes and parsing it by hand, and (b) leave
+the NEXT route added uncovered, because nothing would remind its author. A default that has to be
+opted into is not a default. This module inverts it: the cap applies to everything, and the few
+routes that need more opt OUT, in one list, next to the code that reads it.
+
+**Why raw ASGI and not `@app.middleware("http")`.** Starlette's BaseHTTPMiddleware cannot wrap
+`receive`, so it can only read `Content-Length` — which a client may omit entirely (chunked) or
+simply understate. The bytes have to be counted as they arrive, which is the same rule `capped_body`
+already applies per-route, and counting needs the receive channel.
+
+**Why the refusal is byte-identical to `capped_body`'s.** Two shapes for one fact is how the
+`cancelled`/`canceled` bug happened. The 413 body here is built through the same `JSONResponse`
+FastAPI renders `HTTPException(413, {"code": "too_large"})` with — not a hand-rolled `json.dumps`,
+whose default separators differ by two bytes — and `tests/test_body_limit.py` compares the RAW BYTES
+of the two against each other rather than against a literal, so they cannot drift apart. The same
+reasoning decides where the middleware is registered (`main.py`): just inside CORS, so this 413
+carries the same headers `capped_body`'s does.
+
+**No admin knob, deliberately.** The ceiling is a constant, not a `sysconfig` value: an attacker-
+facing limit that an admin can raise from the UI is a limit that can be raised by whoever gets the
+admin session, and nobody has asked to tune it. If a self-hoster ever needs a different ceiling it
+belongs in `config.py` (env, set before the process starts), not in the database.
+"""
+
+import re
+
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from app import debugsession
+from app.config import settings
+
+# 1 MiB. The largest body any route on the default ceiling legitimately takes is 512 KiB (the client
+# log sink, `routes/diagnostics.py:BODY_MAX_BYTES`), so this leaves 2x headroom — a ceiling that
+# refuses a legitimate request would be a worse bug than the one this module fixes. That ratio is
+# the load-bearing fact, so `test_body_limit.py` holds it rather than the figure above.
+DEFAULT_MAX_BODY_BYTES = 1024 * 1024
+
+# The routes that need MORE than the default, as (method, path TEMPLATE) → their own ceiling. The
+# template, not a concrete path, so the list reads like the route decorators it mirrors and
+# `test_body_limit.py` can assert that each one still resolves to a real route: a renamed route
+# fails the gate instead of silently losing its allowance in prod.
+#
+# These are RAISED CEILINGS, NOT EXEMPTIONS, and the difference is the whole point. An exemption
+# would mean "this route is counted by something else" — which is only true when the route's own
+# limit applies to the bytes as they ARRIVE. That, in turn, is only true of a route with NO DECLARED
+# BODY PARAMETER: FastAPI parses and spools a declared body BEFORE the first dependency runs, so a
+# route that declares one has already stored the bytes by the time its own cap — or its auth — gets
+# a say.
+#
+# Both listed routes now satisfy that. The screenshot route always did (`capped_body` streams it,
+# and the owner check resolves first). The upload route did NOT until P1: it declared
+# `file: UploadFile = File(...)`, so an anonymous caller could make the process write the whole
+# per-file allowance to temp before `require_human` refused them — this middleware bounded that
+# number but could not stop the writing. It now reads its own body from a dependency declared after
+# the auth one, so its in-handler cap measures bytes as they arrive, like everything else here.
+#
+# That rule is no longer only written here: `test_body_limit.py` parses the routes and fails the
+# gate if any route in this dict declares a body parameter. A comment could not have stopped the
+# defect it describes; the test can.
+#
+# A route belongs here ONLY IF ITS OWN CAP IS LARGER THAN THE DEFAULT. That is why
+# `POST /api/diagnostics/events` is absent: its `capped_body` limit is 512 KiB, already below the
+# default, so listing it could only widen what it accepts.
+ROUTE_MAX_BODY_BYTES: dict[tuple[str, str], int] = {
+    # Ingesting a local file. The body IS the file since P1 — no multipart envelope to allow for —
+    # so this ceiling and the route's own cap count exactly the same bytes. `sysconfig`'s
+    # `download_upload_max_bytes` is bounded by this same constant (see sysconfig.SPECS), so an
+    # admin can only ever LOWER the route's cap below the edge, never raise it past one.
+    #
+    # WHICH LAYER ANSWERS, measured rather than assumed (deep-review round 1):
+    #   * knob LOWERED (an override below the default) — the route's cap is the smaller number, so
+    #     `capped_stream_to` trips first and answers 422 `upload_too_large` carrying the admin's own
+    #     figure, after draining the rest of the body so the client can read it.
+    #   * knob at the DEFAULT — the two numbers are EQUAL, and the edge always wins: a declared
+    #     Content-Length over the cap is refused here before a byte is read, and an undeclared body
+    #     trips this counter on the same chunk the route would have tripped on. The route's 422 is
+    #     unreachable in that configuration, and no amount of headroom would change it — the
+    #     declared-length check fires first for any body big enough to matter, and the route's drain
+    #     pushes the count past the edge for the rest.
+    #
+    # So this 413 is a refusal a real user meets on a default install, not a theoretical edge, and
+    # it has to be as readable as the route's own: the client localizes `too_large` (`errors.tooLarge`)
+    # exactly as it does `upload_too_large`, and the upload dialog refuses an over-cap file before
+    # sending it at all, off the `upload_max_bytes` that `GET /api/downloads/usage` reports.
+    ("POST", "/api/downloads/upload"): settings.download_upload_max_bytes,
+    ("POST", "/api/debug-sessions/{sid}/screenshots"): debugsession.SCREENSHOT_MAX_BYTES,
+}
+
+# The refusal, byte-for-byte what `capped_body`'s `HTTPException(413, {"code": "too_large"})` renders
+# as — built through the same JSONResponse so the separators match too, and asserted against a real
+# route's raw bytes in `test_body_limit.py` rather than against a literal here.
+TOO_LARGE_BODY = JSONResponse({"detail": {"code": "too_large"}}, status_code=413).body
+
+_PATH_PARAM = re.compile(r"\{[^/{}]+\}")
+
+
+def template_to_regex(template: str) -> re.Pattern[str]:
+    """`/api/debug-sessions/{sid}/screenshots` → a regex matching one concrete path.
+
+    A path parameter matches `[^/]+` — one segment, never across a `/`, so `{sid}` cannot swallow a
+    deeper path and hand an exemption to a route that was never granted one.
+    """
+    literals = [re.escape(part) for part in _PATH_PARAM.split(template)]
+    return re.compile("^" + "[^/]+".join(literals) + "$")
+
+
+def _declared_length(scope: Scope) -> int | None:
+    """The `Content-Length` header as an int, or None when absent or unparseable (a chunked body has
+    none, and a malformed one is not a number we may trust — both fall through to counting)."""
+    for name, value in scope.get("headers", ()):
+        if name == b"content-length":
+            try:
+                return int(value)
+            except ValueError:
+                # silent-ok: a malformed Content-Length is the caller's doing, not a fault of ours,
+                # and it is about to be answered anyway — returning None drops the request into the
+                # counting path, which refuses on the real bytes. Logging it would hand an anonymous
+                # client a free line in our log for every request it cares to malform.
+                return None
+    return None
+
+
+async def _send_too_large(send: Send) -> None:
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 413,
+            "headers": [
+                (b"content-type", b"application/json"),
+                (b"content-length", str(len(TOO_LARGE_BODY)).encode()),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": TOO_LARGE_BODY})
+
+
+class BodyLimitMiddleware:
+    """Refuses any request body over its route's ceiling, before the application sees it.
+
+    Registered just inside CORS in `main.py` — so the 413 is decorated like every other response
+    and a browser can actually read it — but outside the session, the setup gate and every auth
+    dependency, none of which run for a request that is already too large.
+
+    Every request gets a finite ceiling: `ROUTE_MAX_BODY_BYTES` raises it for the two routes that
+    genuinely take bulk bytes, and there is no path that skips counting altogether.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        limit: int = DEFAULT_MAX_BODY_BYTES,
+        routes: dict[tuple[str, str], int] | None = None,
+    ) -> None:
+        self.app = app
+        self.limit = limit
+        self._routes = tuple(
+            (method, template_to_regex(path), cap)
+            for (method, path), cap in (ROUTE_MAX_BODY_BYTES if routes is None else routes).items()
+        )
+
+    def limit_for(self, method: str, path: str) -> int:
+        """This request's ceiling: the route's own if it has one, else the global default. Every
+        request gets a finite number — there is no path through here that is simply not counted."""
+        for m, rx, cap in self._routes:
+            if m == method and rx.match(path):
+                return cap
+        return self.limit
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        limit = self.limit_for(scope.get("method", ""), scope.get("path", ""))
+
+        declared = _declared_length(scope)
+        if declared is not None and declared > limit:
+            # Refused on the declaration alone: nothing downstream is called, and not one byte of
+            # the body is read.
+            await _send_too_large(send)
+            return
+
+        seen = 0
+        refused = False
+        started = False
+
+        async def counting_receive() -> Message:
+            nonlocal seen, refused
+            message = await receive()
+            if message["type"] != "http.request":
+                return message
+            seen += len(message.get("body", b""))
+            if seen > limit:
+                # The app is blocked on this receive, so it has not answered yet. Telling it the
+                # client went away is the only in-band way to stop it reading: `request.stream()`
+                # turns an `http.disconnect` into ClientDisconnect, which unwinds the handler. Our
+                # own 413 goes out below, once the app has finished unwinding.
+                refused = True
+                return {"type": "http.disconnect"}
+            return message
+
+        async def guarded_send(message: Message) -> None:
+            nonlocal started
+            if refused and not started:
+                return  # discard the app's answer to the disconnect; the 413 below is the response
+            started = True
+            await send(message)
+
+        try:
+            await self.app(scope, counting_receive, guarded_send)
+        except Exception:  # noqa: BLE001 — only swallowed when WE caused it, see below
+            # ClientDisconnect (or whatever a handler raises on a truncated read) is the expected
+            # consequence of the disconnect we just faked, and the caller must get the 413 rather
+            # than a 500. Anything raised when we did NOT refuse is a real failure and is re-raised
+            # untouched.
+            if not refused:
+                raise
+
+        if refused and not started:
+            await _send_too_large(send)
@@ -1,7 +1,7 @@
 from pathlib import Path
 from typing import Literal, get_args, get_origin

-from pydantic import ValidationInfo, field_validator, model_validator
+from pydantic import Field, ValidationInfo, field_validator, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict

 # Shipped placeholder; production must override it. Used by the startup guard below.
@@ -247,7 +247,11 @@ class Settings(BaseSettings):
    # Per-file cap for local uploads (E7). Unlike a download (whose size is unknown until the worker
    # finishes), an upload's size is known at ingest, so this bounds a single file directly; the
    # user's overall byte footprint is still governed by download_default_max_bytes.
-    download_upload_max_bytes: int = 524_288_000  # 500 MiB
+    # ge=1: this number is also the EDGE ceiling (`bodylimit.ROUTE_MAX_BODY_BYTES`), where 0 is a
+    # real limit of zero rather than the route's "no per-file cap" sentinel — an instance set to 0
+    # would refuse every upload, including the admin page's own way back. To lift the cap in
+    # practice, set a large number.
+    download_upload_max_bytes: int = Field(default=524_288_000, ge=1)  # 500 MiB
    # Retention: an asset expires this many days after its last access; the GC job then
    # deletes it (once no job references it) after an additional grace window.
    download_retention_days: int = 30
@@ -1,6 +1,6 @@
 from collections.abc import Iterator

-from sqlalchemy import create_engine
+from sqlalchemy import create_engine, text
 from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker

 from app.config import settings
@@ -12,7 +12,9 @@ class Base(DeclarativeBase):

 # Pool sized above the sync-endpoint threadpool (~40) so a burst of short DB sessions can't starve on
 # checkout. The image proxies deliberately DON'T hold a connection during their slow external fetch
-# (see routes/plex/), so this headroom is only for the many brief sessions, not long ones.
+# (see routes/plex/), so this headroom is only for the many brief sessions, not long ones. The one
+# long hold — a playlist sync's advisory claim, for a whole push — opens its own unpooled connection
+# (sync/playlists.py `_claim_engine`) instead of drawing a third one from here.
 engine = create_engine(
    settings.database_url,
    pool_pre_ping=True,
@@ -34,3 +36,50 @@ def get_db() -> Iterator[Session]:
        yield db
    finally:
        db.close()
+
+
+def release_read_connection(db: Session) -> None:
+    """End a request's READ transaction so its pooled connection goes back BEFORE a long await.
+
+    SQLAlchemy 2.0 autobegins on the first SELECT, so a request that has merely authenticated is
+    already holding one of the connections above — `idle in transaction` to Postgres, and nothing
+    times it out. A route that then awaits something slow (a request body still arriving, an
+    external fetch) pins it for the whole wait, which is precisely the invariant the pool is sized
+    on in the comment above. Measured: the next checkout after this call reuses the very backend
+    that was released, and a 1.8 s upload goes from one sustained `idle in transaction` to none.
+
+    Every route that reads its own body from a dependency needs this, and `test_body_limit.py`
+    holds that — the three that do are the ones with a raised (or self-imposed) body ceiling, and
+    they got here one at a time, which is how the upload route ended up the only one fixed.
+
+    The caller must have NOTHING PENDING, and that is checked rather than described. The session is
+    shared with every dependency that ran before, so a rollback here would silently discard a write
+    one of them staged — `service.enqueue` already learned that lesson the expensive way and uses a
+    SAVEPOINT for it. CLAUDE.md: a rule stated in a comment must also be enforced in code.
+
+    TWO checks, because the obvious one is blind to the shapes this codebase actually writes in.
+    `db.new`/`deleted`/`dirty` hold only UNFLUSHED unit-of-work: the moment a helper calls
+    `db.flush()` — CLAUDE.md's canonical split is "the handler commits; helpers flush" — the object
+    is persistent with no unflushed history and all three sets are empty again, and Core DML
+    (`db.execute(update(...))`) never enters them at all. Measured: after `add`+`flush` the sets are
+    empty, the old check passed, and the rollback lost the row. So the transaction is asked
+    directly. Postgres assigns a transaction id on the first WRITE and never for a read, so
+    `pg_current_xact_id_if_assigned()` is NULL for exactly the state this function is safe in — and
+    it sees a raw `text("UPDATE …")` too, which no session-level bookkeeping would.
+    """
+    if db.new or db.deleted or db.dirty:
+        raise RuntimeError(
+            "release_read_connection() with pending work: something ahead of this dependency "
+            "staged a write, which ending the transaction would discard. Commit it first, or do "
+            "it after the await."
+        )
+    if (
+        db.in_transaction()
+        and db.execute(text("SELECT pg_current_xact_id_if_assigned()")).scalar() is not None
+    ):
+        raise RuntimeError(
+            "release_read_connection() on a transaction that has already WRITTEN: something ahead "
+            "of this dependency flushed a row or ran an UPDATE/INSERT/DELETE, which ending the "
+            "transaction would discard. Commit it first, or do it after the await."
+        )
+    db.rollback()
@@ -25,7 +25,7 @@ from app.downloads.jobdb import (
 )
 from app.downloads.stated import StatedFailure
 from app.downloads.status import JobStatus
-from app.models import DownloadJob, MediaAsset
+from app.models import DISPLAY_TEXT_MAX, DownloadJob, MediaAsset
 from app.notifications import create_notification
 from app.titles import normalize_title

@@ -597,7 +597,7 @@ def _download(
            }
            if job and not job.display_name and meta.title:
                # display_name is VARCHAR(255) — clip a long title (see _fill_asset_meta_early).
-                fields["display_name"] = meta.title[:255]
+                fields["display_name"] = meta.title[:DISPLAY_TEXT_MAX]
            # Atomic terminal write: finalizes ONLY while the row is still running, so a child that
            # finishes just after a route cancel/pause can't resurrect it (see finalize_if_running).
            finalized = service.finalize_if_running(db, job_id, **fields)
@@ -20,7 +20,7 @@ from app.downloads import credentials
 from app.downloads import edit as editmod
 from app.downloads import formats, mediakind, quota, storage
 from app.downloads.status import HOLDING, JobStatus
-from app.models import Channel, DownloadJob, MediaAsset, Video
+from app.models import DISPLAY_TEXT_MAX, Channel, DownloadJob, MediaAsset, Video


 class EditError(Exception):
@@ -179,7 +179,7 @@ def enqueue(
        profile_id=profile_id,
        profile_snapshot=spec,
        display_name=display_name
-        or (asset.title[:255] if asset.status == "ready" and asset.title else None),
+        or (asset.title[:DISPLAY_TEXT_MAX] if asset.status == "ready" and asset.title else None),
        status="queued",
        queue_pos=next_queue_pos(db),
    )
@@ -198,10 +198,13 @@ def enqueue(


 def _clip_title(source_title: str | None, display_name: str | None) -> str:
+    # Clipped to DISPLAY_TEXT_MAX, not to a literal: this feeds `DownloadJob.display_name` through
+    # `enqueue_edit`, the same column `display_text` guards. A machine-made title, so it is clipped
+    # rather than run through `display_text` — blank here means "no title", not None.
    if display_name:
-        return display_name[:255]
+        return display_name[:DISPLAY_TEXT_MAX]
    base = source_title or "Clip"
-    return f"{base} (clip)"[:255]
+    return f"{base} (clip)"[:DISPLAY_TEXT_MAX]


 def enqueue_edit(
@@ -255,7 +258,7 @@ def enqueue_edit(
        source_asset_id=src_asset.id,
        edit_spec=spec,
        profile_snapshot={},
-        display_name=display_name or asset.title,
+        display_name=display_name or asset.title[:DISPLAY_TEXT_MAX],
        status="queued",
        queue_pos=next_queue_pos(db),
    )
@@ -25,7 +25,7 @@ from sqlalchemy.orm import Session
 from app.config import settings
 from app.downloads import edit as editmod
 from app.downloads import mediakind, probe, quota, service, storage
-from app.models import DownloadJob, MediaAsset
+from app.models import DownloadJob, MediaAsset, display_text


 def _title_from_filename(filename: str) -> str:
@@ -99,7 +99,7 @@ def ingest_upload(
            source_kind="upload",
            source_ref=ref,
            profile_snapshot={},
-            display_name=(display_name or "").strip() or None,
+            display_name=display_text(display_name),
            status="done",
            progress=100,
            queue_pos=service.next_queue_pos(db),
@@ -3,7 +3,7 @@ before a line of this was written (plans/e16-debug-issue.md, S0).

 Configured by an admin (sysconfig `issues_gitea_url` / `_repo` / `_token`, the token encrypted at
 rest). The repository must be PRIVATE: an issue carries its reporter's log — page titles, filter
-values, at Teljes what they typed into search — and a public repository would publish it. That is
+values, at Teljes (TRACE) what they typed into search — and a public repository would publish it. That is
 checked on every send, not only in the admin's "test connection", because a repository can be made
 public after the fact.

@@ -154,9 +154,22 @@ def check(db: Session) -> dict:


 def preview(db: Session, text: str) -> str:
-    """The body as Gitea itself will render it (its markdown flavour, its sanitiser)."""
-    with _client(_settings(db)) as (client, repo):
-        r = _call(client, "POST", "/markdown", json={"Text": text, "Mode": "gfm", "Context": repo})
+    """The body as Gitea itself will render it (its markdown flavour, its sanitiser).
+
+    **No `Context`, deliberately — a repository context here does not fail the call, it kills the
+    tracker.** With one, Gitea's post-processor turns every hex-shaped word into a commit link, and
+    on the API's render path the commit checker it asks is nil: the whole Gitea process segfaults
+    and restarts, taking the git server (and, here, the container registry) down with it. Every
+    report carries hex — a tab id, a request id — so this was not an edge case but the only case.
+    Measured on throwaway instances (2026-09-20): `{"Mode": "gfm", "Context": "<repo>"}` with
+    `5645b1c0ae01` in the text crashes 1.26.4 and 1.27.1 and is fixed in 1.27.3 — but a self-hoster
+    runs whatever version they run, so the payload stays safe here rather than relying on theirs.
+    Dropping `Context` is not a downgrade of the preview: measured against the same body, the HTML
+    keeps its tables, its task lists and its highlighted code blocks. It only stops resolving
+    repo-relative links (a hash, a `#123`), which the issue page itself still resolves.
+    """
+    with _client(_settings(db)) as (client, _repo):
+        r = _call(client, "POST", "/markdown", json={"Text": text, "Mode": "gfm"})
    return r.text


@@ -466,7 +466,6 @@ _THIRD_PARTY_LEVELS = {
    "httpx": "WARNING",
    "httpcore": "WARNING",
    "asyncio": "WARNING",
-    "multipart": "WARNING",
    "PIL": "WARNING",
    "alembic": "INFO",
    # uvicorn's own startup/shutdown/WebSocket lines are worth keeping; its ACCESS log is not —
@@ -23,6 +23,7 @@ from fastapi.staticfiles import StaticFiles
 from sqlalchemy.exc import DataError
 from starlette.middleware.sessions import SessionMiddleware

+from app import bodylimit
 from app import logsink
 from app import state
 from app import sysconfig
@@ -189,15 +190,6 @@ app.add_middleware(
    https_only=settings.session_https_only,  # Secure flag when served over HTTPS (prod)
 )

-if settings.frontend_origin:
-    app.add_middleware(
-        CORSMiddleware,
-        allow_origins=[settings.frontend_origin],
-        allow_credentials=True,
-        allow_methods=["*"],
-        allow_headers=["*"],
-    )
-
 # Paths reachable while the instance is unconfigured (setup mode). Everything else under /api or
 # /auth is locked until the wizard finishes; static/SPA always loads so the wizard page can render.
 _SETUP_OPEN_PREFIXES = ("/api/setup", "/api/version")
@@ -217,6 +209,34 @@ async def setup_gate(request, call_next):
    return await call_next(request)


+# SEC-20 — the global request-body cap (app/bodylimit.py). FastAPI reads a declared body IN FULL
+# before the first dependency, so without this the anonymous login route is a free memory/time sink.
+#
+# WHERE it sits is the whole design, and it is pinned by `test_body_limit.py` rather than by this
+# comment, because `add_middleware` inverts the reading order (last registered = OUTERMOST) and a
+# stack described in prose drifts. Registered here it lands directly INSIDE CORS and directly
+# OUTSIDE the setup gate, which is the narrowest position that satisfies both constraints:
+#
+#   * inside CORS and the security headers, so the 413 is decorated like every other response. A
+#     refusal the browser drops for a missing Access-Control-Allow-Origin is no better than a hang,
+#     and `capped_body`'s 413 one layer down IS decorated — two shapes for one fact is exactly what
+#     bodylimit.py exists to avoid.
+#   * outside the setup gate, the session and every auth dependency under the router — none of which
+#     run for a body that is already too large. The setup gate matters specifically: on an instance
+#     that is not yet configured it opens a DB session per request, which is precisely the anonymous
+#     pre-auth work SEC-20 exists to remove.
+app.add_middleware(bodylimit.BodyLimitMiddleware)
+
+if settings.frontend_origin:
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=[settings.frontend_origin],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+
@app.middleware("http")
 async def static_cache_headers(request, call_next):
    """Long-cache the content-hashed SPA bundles. Vite hashes their filename, so a given
@@ -259,7 +279,8 @@ async def security_headers(request, call_next):

 # The access log (app/logs.py): request id, route template, status, duration — one line, never a
 # query string. Registered LAST so it is the OUTERMOST http middleware and therefore times the whole
-# request, including what the three above do. Being outermost also puts it OUTSIDE SessionMiddleware,
+# request, including what every layer above does — the body cap included, so a 413 is still logged
+# with its request id and duration. Being outermost also puts it OUTSIDE SessionMiddleware,
 # which is why the account comes from `request.state.user_id` (set by the auth dependency, the one
 # place a session is actually resolved into an account) rather than from `request.session`.
 app.middleware("http")(log_requests)
@@ -23,6 +23,34 @@ from sqlalchemy.dialects.postgresql import JSONB, TSVECTOR
 from sqlalchemy.orm import Mapped, mapped_column, relationship, validates

 from app.db import Base
+
+# Every user-supplied display string in this schema shares one width, and it lives HERE so the
+# columns below are declared with it rather than with a literal: a name a person typed goes into
+# `User.display_name` (their Google profile name), `DownloadJob.display_name` and
+# `DownloadJob.display_uploader`. A value wider than the column is a psycopg DataError, which
+# `main.py` re-raises for everything but the NUL case — i.e. a bare 500 for a name somebody pasted.
+DISPLAY_TEXT_MAX = 255
+
+
+def display_text(raw: str | None) -> str | None:
+    """A user-supplied display string on its way into one of those columns: stripped, truncated,
+    blank -> None.
+
+    One definition because there are SIX writers and they had drifted: `POST /api/downloads`,
+    `POST /api/downloads/edit`, `POST /api/downloads/upload`, the metadata PATCH's two fields, and
+    the Google sign-in callback. Only the PATCH truncated. Truncating is the right answer rather
+    than refusing: the name is a label on work the user has already done — a file already
+    transferred, an account already authenticated — and losing its tail is not worth failing the
+    request over.
+
+    `test_upload.py` holds both halves: that every route assigning one of these fields goes through
+    this helper (parsed, not grepped), and that each of those routes truncates rather than 500s. A
+    sweep is exactly the kind of thing that gets done five-sixths of the way, which is how this
+    ended up being written twice.
+    """
+    return (raw or "").strip()[:DISPLAY_TEXT_MAX] or None
+
+
 from app.utils import canonical_email


@@ -114,7 +142,7 @@ class User(Base, TimestampMixin, CanonicalEmailMixin):
    # not cleared eagerly — it simply stops counting).
    diagnostics_level: Mapped[str | None] = mapped_column(String(8))
    diagnostics_until: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-    display_name: Mapped[str | None] = mapped_column(String(255))
+    display_name: Mapped[str | None] = mapped_column(String(DISPLAY_TEXT_MAX))
    avatar_url: Mapped[str | None] = mapped_column(String(1024))
    role: Mapped[str] = mapped_column(String(16), default="user", server_default="user")
    # The user's own YouTube channel id, resolved lazily (channels.list?mine=true) and
@@ -953,11 +981,11 @@ class DownloadJob(Base, TimestampMixin, UpdatedAtMixin):
        ForeignKey("download_profiles.id", ondelete="SET NULL")
    )
    profile_snapshot: Mapped[dict] = mapped_column(JSON)
-    display_name: Mapped[str | None] = mapped_column(String(255))
+    display_name: Mapped[str | None] = mapped_column(String(DISPLAY_TEXT_MAX))
    # Per-user display overrides + extras (like display_name — metadata only, never the file).
    # `display_uploader`/`display_uploader_url` override the asset's auto channel name/link;
    # `extra_links` is an optional list of extra reference URLs shown on the card + watch page.
-    display_uploader: Mapped[str | None] = mapped_column(String(255))
+    display_uploader: Mapped[str | None] = mapped_column(String(DISPLAY_TEXT_MAX))
    display_uploader_url: Mapped[str | None] = mapped_column(Text)
    extra_links: Mapped[list | None] = mapped_column(JSON)
    status: Mapped[str] = mapped_column(
@@ -32,6 +32,7 @@ window still took the full 145 s and emitted the whole track), so windows are ex
 zero-based clock and shifted back to absolute time here with `shift_vtt`.
 """

+import codecs
 import json
 import re
 import subprocess
@@ -217,7 +218,11 @@ _FULL_END_S = 1_000_000_000.0  # stand-in for "to the end of the file" (JSON can


 def cache_key(rating_key: str, sub_ord: int) -> str:
-    return f"sub_{rating_key}_{sub_ord}"
+    # Versioned whenever `decode_subtitle` changes what a track decodes to — `sub2_` when legacy code
+    # pages were cached as U+FFFD, `sub3_` when a stray byte, an untagged file or Serbian still went
+    # to the wrong code page. The cache has no eviction, so every track is read again once rather
+    # than a broken one being served for good; the older files are just left behind.
+    return f"sub3_{rating_key}_{sub_ord}"


 def _vtt_path(key: str) -> Path:
@@ -904,15 +909,90 @@ def _full_pass_start(rating_key: str, targets: dict[int, int]) -> float:
    return max(0.0, float(f"{min(ends) - WINDOW_PRE_S:.3f}"))


+# The legacy code page a subtitle in this language (Plex's ISO 639-2 `languageCode`) was most likely
+# saved in. Serbian sits here, not with Cyrillic: its releases are overwhelmingly Latin script in
+# Windows-1250, like Croatian and Bosnian.
+_CP1250 = {
+    "hun",
+    "ces",
+    "cze",
+    "pol",
+    "slk",
+    "slo",
+    "slv",
+    "hrv",
+    "bos",
+    "srp",
+    "ron",
+    "rum",
+    "sqi",
+    "alb",
+}
+_CP1251 = {"rus", "ukr", "bel", "bul", "mkd", "mac"}
+# Western European languages keep Windows-1252 (cp1250 has no à/è/ñ). An UNTAGGED file falls to
+# Windows-1250: its ASCII and á/é/í/ó/ö/ú/ü match Windows-1252 byte for byte, and it also gets ő/ű
+# right, which Windows-1252 turns into õ/û — the library this reads is mostly Hungarian.
+_CP1252 = {
+    "eng",
+    "fre",
+    "fra",
+    "ger",
+    "deu",
+    "spa",
+    "ita",
+    "por",
+    "dut",
+    "nld",
+    "swe",
+    "dan",
+    "nor",
+    "fin",
+    "ice",
+    "isl",
+    "cat",
+}
+# A file that is almost all valid UTF-8 is UTF-8 with a few stray bytes (a pasted Windows-1252 quote),
+# not a legacy file: accents in a legacy code page are nearly never valid UTF-8 sequences, so a real
+# legacy file has hardly any. At least this many valid multi-byte characters per invalid byte.
+_UTF8_VALID_PER_STRAY = 10
+
+
+def decode_subtitle(raw: bytes, language_code: str | None) -> str:
+    """A sidecar subtitle file as text. SubRip carries no charset, and a Hungarian release is
+    typically Windows-1250: decoded as UTF-8 with `replace`, every ő/ű/é came out as U+FFFD (found
+    live, 1391 of them in one episode). So: a BOM decides; else valid UTF-8 stays UTF-8 (a legacy
+    code page with accents is almost never valid UTF-8), and so does NEARLY valid UTF-8 — one stray
+    byte must not send a whole UTF-8 file to a legacy code page; else the language's legacy code page."""
+    if raw.startswith(codecs.BOM_UTF8):
+        return raw[len(codecs.BOM_UTF8) :].decode("utf-8", "replace")
+    if raw.startswith((codecs.BOM_UTF16_LE, codecs.BOM_UTF16_BE)):
+        return raw.decode("utf-16", "replace")
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        # silent-ok: not strictly UTF-8 — nearly-UTF-8 or a legacy code page, told apart below.
+        pass
+    lenient = raw.decode("utf-8", "replace")
+    stray = lenient.count("�")
+    valid = sum(1 for ch in lenient if ch > "" and ch != "�")
+    if valid >= stray * _UTF8_VALID_PER_STRAY:
+        return lenient
+    lang = (language_code or "").lower()
+    legacy = "cp1251" if lang in _CP1251 else "cp1252" if lang in _CP1252 else "cp1250"
+    return raw.decode(legacy, "replace")
+
+
 def _sidecar_vtt(db: Session, stream: dict) -> str:
-    """An external subtitle file, fetched through Plex and converted to WebVTT."""
+    """An external subtitle file, fetched through Plex and converted to WebVTT. Its bytes are made
+    UTF-8 first (`decode_subtitle`), on the ffmpeg path too: ffmpeg reads a text subtitle as UTF-8."""
    with PlexClient(db) as plex:
        raw = plex.raw_get(stream["key"])
+    text = decode_subtitle(raw, stream.get("languageCode"))
    codec = (stream.get("codec") or stream.get("format") or "").lower()
    if codec in ("srt", "subrip", ""):
-        return srt_to_vtt(raw.decode("utf-8", "replace"))
+        return srt_to_vtt(text)
    with tempfile.NamedTemporaryFile(suffix="." + (codec or "sub"), delete=False) as fh:
-        fh.write(raw)
+        fh.write(text.encode("utf-8"))
        tmp = fh.name
    try:
        return ffmpeg_to_vtt(tmp, None)
@@ -6,7 +6,7 @@ and "fetch a row this user owns or 404" idioms have one definition, one status c
 one existence-leak policy.
 """

-from typing import Any, TypeVar
+from typing import IO, Any, TypeVar

 from fastapi import HTTPException, Request
 from sqlalchemy.orm import Session
@@ -28,10 +28,13 @@ def not_found(what: str = "generic") -> HTTPException:
    return HTTPException(status_code=404, detail={"code": "not_found", "reason": what})


-def get_or_404(db: Session, model: type[M], id_: Any, *, what: str = "generic") -> M:
+def get_or_404(
+    db: Session, model: type[M], id_: Any, *, what: str = "generic", lock: bool = False
+) -> M:
    """Fetch a row by primary key or raise 404. Replaces the `db.get(Model, id); if None: 404`
-    idiom repeated across routes."""
-    obj = db.get(model, id_)
+    idiom repeated across routes. `lock` takes it FOR UPDATE (bypassing the identity map), so two
+    requests that read-then-write its children (a playlist's item positions) run one after the other."""
+    obj = db.get(model, id_, with_for_update=True if lock else None)
    if obj is None:
        raise not_found(what)
    return obj
@@ -45,12 +48,13 @@ def owned_or_404(
    *,
    owner_attr: str = "user_id",
    what: str = "generic",
+    lock: bool = False,
 ) -> M:
-    """Fetch a row by primary key that `user` owns, or raise 404. A row owned by someone
+    """Fetch a row by primary key that `user` owns, or raise 404 (`lock`: see `get_or_404`). A row owned by someone
    else 404s (NOT 403) on purpose — a 403 would confirm the id exists to a stranger.
    It replaced the near-identical per-route ownership helpers, and is called directly — a thin
    `_own_x` wrapper around it is the ad-hoc shape CLAUDE.md's patterns table rules out."""
-    obj = get_or_404(db, model, id_, what=what)
+    obj = get_or_404(db, model, id_, what=what, lock=lock)
    if getattr(obj, owner_attr) != user.id:
        raise not_found(what)
    return obj
@@ -79,6 +83,47 @@ async def capped_body(request: Request, limit: int) -> bytes:
    return bytes(body)


+async def capped_stream_to(
+    request: Request, out: IO[bytes], limit: int, refusal: HTTPException
+) -> int:
+    """`capped_body`'s sibling for a body too large to hold: the same counting rule, written
+    straight to `out` instead of accumulated, returning the size.
+
+    Two deliberate differences from `capped_body`. It never builds a `bytearray` — the upload route
+    admits 500 MiB by default, so holding the body would trade a disk problem for a memory one. And
+    the refusal is the CALLER'S, passed in rather than assumed: `capped_body`'s flat 413 is right
+    for a screenshot, while the upload route answers 422 `upload_too_large` carrying the admin
+    knob's own number, which is what its dialog shows the user. One counting rule, two answers,
+    neither of them a second copy of the loop.
+
+    The caller owns `out` and owns cleaning it up: a body refused half-way has already written what
+    arrived before the limit was passed.
+
+    **The refusal DRAINS the rest of the body before it is raised, and that is not politeness.**
+    Answering mid-upload and closing the connection is what the client sees as a network failure,
+    not as a refusal: the browser's XHR fires `onerror` before it can read the response, so a file
+    over the limit reported itself as "the server couldn't be reached" instead of naming the limit —
+    measured in a real browser, not reasoned about. Reading the remainder to nowhere lets the client
+    finish sending, read the 422 and say the true thing.
+
+    The bytes are discarded, never written, and the whole request is already bounded by
+    `bodylimit`'s per-route ceiling — so the worst case is bandwidth an authenticated caller was
+    sending anyway, against the old behaviour which wrote exactly those bytes to disk."""
+    size = 0
+    over = False
+    async for chunk in request.stream():
+        size += len(chunk)
+        if over:
+            continue  # draining — see the docstring; counted, not stored
+        if size > limit:
+            over = True
+            continue
+        out.write(chunk)
+    if over:
+        raise refusal
+    return size
+
+
 def issue_refused(exc: gitea.GiteaError) -> HTTPException:
    """The refusal an issue-tracker failure (E16) answers as — the send, the preview and the
    admin's connection test alike. Literal reasons, one per case: the frontend's contract test reads
@@ -39,7 +39,7 @@ from app.auth import (
 )
 from app.config import settings
 from app.db import SessionLocal, get_db
-from app.models import AuthToken, DemoWhitelist, Invite, OAuthToken, User
+from app.models import AuthToken, DemoWhitelist, Invite, OAuthToken, User, display_text
 from app.ratelimit import RateLimiter, client_key
 from app.security import encrypt, hash_password, hash_token, verify_password
 from app.utils import canonical_email, valid_email
@@ -472,7 +472,7 @@ async def callback(
    if email:
        user.google_email = email
    _sync_google_email(db, user, email)
-    user.display_name = userinfo.get("name")
+    user.display_name = display_text(userinfo.get("name"))
    user.avatar_url = userinfo.get("picture")
    # ADMIN_EMAILS (env) is the bootstrap admin list and always wins, so the configured admin can't
    # be locked out. Everyone else's role is managed in the admin UI and stored in the DB, so a
@@ -594,7 +594,7 @@ def _complete_link(
    if linked_email:
        user.google_email = linked_email  # see the sign-in callback: the other half of the identity
    if not user.display_name:
-        user.display_name = userinfo.get("name")
+        user.display_name = display_text(userinfo.get("name"))
    if not user.avatar_url:
        user.avatar_url = userinfo.get("picture")
    _store_token(db, user, token)
@@ -28,7 +28,7 @@ from app.models import (
 from app.routes._common import get_or_404, not_found, owned_or_404, youtube_refusal
 from app.sync.explore import explore_ingest_page
 from app.sync.runner import backfill_channel_now, run_recent_backfill
-from app.sync.subscriptions import apply_channel_details
+from app.sync.subscriptions import apply_channel_details, details_stale
 from app.utils import iso
 from app.youtube.client import YouTubeClient, YouTubeError
 from app.refusal import refused
@@ -190,7 +190,7 @@ def discover_channels(
                quota.attribute(user.id, quota.QuotaAction.CHANNELS_DISCOVER),
                YouTubeClient(db, user) as yt,
            ):
-                apply_channel_details(db, yt.get_channels(need))
+                apply_channel_details(db, yt.get_channels(need), need)
            db.commit()
            # Match _discovery_rows' ORDER BY exactly: video-count DESC, then title (NULLs LAST,
            # as Postgres orders them — coercing NULL→"" would wrongly float untitled channels up).
@@ -296,17 +296,20 @@ def channel_detail(
    """One channel's "About" detail for the channel page header/About tab, plus this user's
    relationship to it (subscribed / explored) and how many of its videos are in the catalog.
    Lazily fills the About metadata (view count, join date, banner, links) the first time it's
-    needed — a stub, or a channel last enriched before those fields existed (published_at is a
-    reliable sentinel: every real channel has a creation date). The enrich uses the API key
-    (1 unit, cached after), so it's skipped for the quota-less demo account."""
+    needed (a stub) and refreshes it once it is stale (`DETAILS_MAX_AGE`), which is how a channel nobody subscribes to (an explored one, outside the
+    subscription import) gets a banner that still resolves. The enrich uses the API key (1 unit,
+    cached after), so it's skipped for the quota-less demo account."""
    channel = get_or_404(db, Channel, channel_id, what="channel")
-    if channel.published_at is None and not user.is_demo:
+    # No `published_at is None` sentinel: a terminated channel never gets one, so it re-fetched on
+    # every view; rows enriched before that field existed are long past DETAILS_MAX_AGE anyway.
+    stale = details_stale(channel, datetime.now(timezone.utc))
+    if stale and not user.is_demo:
        try:
            with (
                quota.attribute(user.id, quota.QuotaAction.CHANNELS_DISCOVER),
                YouTubeClient(db, user) as yt,
            ):
-                apply_channel_details(db, yt.get_channels([channel_id]))
+                apply_channel_details(db, yt.get_channels([channel_id]), [channel_id])
            db.commit()
            channel = db.get(Channel, channel_id)
        except YouTubeError as exc:
@@ -412,12 +415,10 @@ def explore_channel(
            YouTubeClient(db, user) as yt,
        ):
            # Enrich for the About panel + the uploads playlist id (needed to ingest videos).
-            if (
-                channel.details_synced_at is None
-                or channel.uploads_playlist_id is None
-                or channel.published_at is None
-            ):
-                apply_channel_details(db, yt.get_channels([channel_id]))
+            # Stale, not "a field is missing": a terminated channel never gets an uploads playlist
+            # or a creation date, and asking again on every explore would spend quota on a miss.
+            if details_stale(channel, datetime.now(timezone.utc)):
+                apply_channel_details(db, yt.get_channels([channel_id]), [channel_id])
                db.commit()
                channel = db.get(Channel, channel_id)
            result = explore_ingest_page(db, yt, channel, page_token)
@@ -590,7 +591,7 @@ def subscribe(
        # must not block recording the subscription the user asked for.
        if channel.details_synced_at is None:
            try:
-                apply_channel_details(db, yt.get_channels([channel_id]))
+                apply_channel_details(db, yt.get_channels([channel_id]), [channel_id])
            except YouTubeError as exc:
                log.warning(
                    "subscribe: stub enrich failed: %s",
@@ -22,7 +22,7 @@ from sqlalchemy.orm import Session
 from app import audit, debugsession, logs, logsink
 from app.audit import AuditAction
 from app.auth import require_human
-from app.db import get_db
+from app.db import get_db, release_read_connection
 from app.issues import bundle, gitea
 from app.ratelimit import RateLimiter
 from app.refusal import refused
@@ -335,7 +335,13 @@ def _upload_target(
    return owned_or_404(db, DebugSession, sid, user, what="debug_session")


-async def _image_body(request: Request) -> bytes:
+async def _image_body(request: Request, db: Session = Depends(get_db)) -> bytes:
+    # The owner check above has already run, and it was a SELECT — so this session is holding a
+    # pooled connection `idle in transaction` and would hold it for the whole 10 MiB upload, from a
+    # client that may be on a phone. Hand it back first; the handler's own work re-takes one. The
+    # `session` object the handler holds is expired by this and reloads on its next attribute read,
+    # which is the correct moment to touch the database again.
+    release_read_connection(db)
    return await capped_body(request, debugsession.SCREENSHOT_MAX_BYTES)


@@ -31,7 +31,7 @@ from sqlalchemy.orm import Session

 from app import debugsession, diagnostics, logs, logsink
 from app.auth import current_user
-from app.db import get_db
+from app.db import get_db, release_read_connection
 from app.models import DebugSession, LogEvent, User
 from app.ratelimit import RateLimiter
 from app.routes._common import capped_body
@@ -73,7 +73,7 @@ class ClientEventsIn(BaseModel):
    events: list[ClientEvent] = Field(max_length=EVENTS_MAX)


-async def _parsed_events(request: Request) -> ClientEventsIn:
+async def _parsed_events(request: Request, db: Session = Depends(get_db)) -> ClientEventsIn:
    """The body as the model — parsed only after the size cap, which is why this is a dependency and
    not a plain body parameter (FastAPI reads a declared body in full before anything else runs).

@@ -83,6 +83,10 @@ async def _parsed_events(request: Request) -> ClientEventsIn:
    media_type = request.headers.get("content-type", "").split(";")[0].strip().lower()
    if media_type != "application/json" and not media_type.endswith("+json"):
        raise HTTPException(status_code=415, detail={"code": "json_required"})
+    # `current_user` resolved above on a SELECT, so this session is holding a pooled connection.
+    # Give it back before awaiting the body — the sink is a background beacon and its sender may be
+    # on a link far slower than the 512 KiB suggests. See `db.release_read_connection`.
+    release_read_connection(db)
    raw = await capped_body(request, BODY_MAX_BYTES)
    try:
        return ClientEventsIn.model_validate_json(raw)
@@ -9,11 +9,13 @@ serves finished files (range-aware, with the user's custom display name), and sh
 import os
 import re
 import tempfile
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from urllib.parse import parse_qs, urlparse
+from urllib.parse import parse_qs, unquote, urlparse

-from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
+from fastapi import APIRouter, Depends, HTTPException, Request
 from fastapi.responses import FileResponse
 from pydantic import BaseModel
 from sqlalchemy import func, select
@@ -22,7 +24,7 @@ from sqlalchemy.orm import Session
 from app import audit, sysconfig
 from app.auth import admin_user, require_human
 from app.config import settings
-from app.db import get_db
+from app.db import get_db, release_read_connection
 from app.downloads import credentials as dlcreds
 from app.downloads import edit as editmod
 from app.downloads import links as linksmod
@@ -37,8 +39,9 @@ from app.models import (
    DownloadShare,
    MediaAsset,
    User,
+    display_text,
 )
-from app.routes._common import get_or_404, not_found, owned_or_404
+from app.routes._common import capped_stream_to, get_or_404, not_found, owned_or_404
 from app.security import hash_password
 from app.userscope import is_messageable_user, messageable_clauses
 from app.utils import iso
@@ -398,7 +401,7 @@ def enqueue_download(
                status_code=422, detail={"code": "url_blocked", "reason": e.reason}
            ) from e
    spec, profile_id = _resolve_spec(db, user, body.profile_id, body.spec)
-    display_name = (body.display_name or "").strip() or None
+    display_name = display_text(body.display_name)
    try:
        job = service.enqueue(db, user.id, source_kind, source_ref, spec, profile_id, display_name)
    except quota.QuotaExceeded as e:
@@ -406,61 +409,119 @@ def enqueue_download(
    return _serialize_job(db, job)


-# Read the upload in 1 MiB chunks so a large file never sits fully in memory, and the size cap is
-# enforced on the ACTUAL bytes read (a client-set Content-Length can't be trusted to gate it).
-_UPLOAD_CHUNK = 1024 * 1024
+# The upload's filename and display name travel as HEADERS, not as multipart parts. That is not a
+# style choice: a DECLARED body parameter (`file: UploadFile = File(...)`) is read and spooled by
+# FastAPI *before the first dependency runs*, so `require_human` could not gate it and an anonymous
+# caller could make the process write the whole per-file allowance to temp, per request (P1; SEC-20
+# bounded the number but could not stop the writing). Reading the body ourselves, from a dependency
+# declared AFTER the auth one, is the only shape that closes it — the same one
+# `POST /api/debug-sessions/{sid}/screenshots` uses, and `test_body_limit.py` now enforces it for
+# every route with a raised ceiling rather than leaving it to a comment like this one.
+#
+# Headers are latin-1 on the wire, so both are percent-encoded by the client and unquoted here; a
+# Hungarian filename would otherwise be unsendable.
+UPLOAD_FILENAME_HEADER = "x-upload-filename"
+UPLOAD_DISPLAY_NAME_HEADER = "x-upload-display-name"


-@router.post("/upload")
-def upload_download(
-    file: UploadFile = File(...),
-    display_name: str | None = Form(None),
+@dataclass(frozen=True)
+class SpooledUpload:
+    """What the body dependency hands the handler: the bytes already on disk, plus the two names
+    that came alongside them."""
+
+    path: Path
+    size: int
+    user_id: int
+    filename: str
+    display_name: str | None
+
+
+def _header_text(request: Request, name: str) -> str:
+    """One percent-encoded header, decoded. A header that is not valid UTF-8 once unquoted is the
+    caller's doing, not a server fault — it degrades to empty rather than 500ing, and the route's
+    own fallback names the file."""
+    raw = request.headers.get(name, "")
+    try:
+        return unquote(raw, errors="strict").strip()
+    except (UnicodeDecodeError, ValueError):
+        # silent-ok: a mis-encoded header is the caller's own malformed request, and this one is
+        # cosmetic — it names the file. Refusing the upload over it would fail a 500 MiB transfer on
+        # a label; logging it would hand any client a free log line per request.
+        return ""
+
+
+async def spool_upload(
+    request: Request,
    user: User = Depends(require_human),
    db: Session = Depends(get_db),
-) -> dict:
-    """Ingest a local file into the caller's library (E7 S5). Any file type is accepted; media
-    (video/audio) gets the full function set, a generic file is download-only. The file is streamed
-    to a temp path under the download volume (enforcing the per-file cap as it goes), then handed to
-    the non-yt-dlp ingest which probes + places it and returns an already-`done` job.
+) -> AsyncIterator[SpooledUpload]:
+    """Stream the request body to a staging temp file, enforcing the per-file cap as it arrives.

-    A sync (threadpool) handler on purpose: the ingest does blocking work — an ffprobe of up to 30s
-    plus sync DB writes — so it must NOT run on the event loop. `file.file` is the sync file object
-    Starlette spools the multipart body into."""
+    `user` is taken but unused: it is the whole point. Dependencies resolve in declaration order, so
+    naming `require_human` here makes the auth check a precondition of reading the body at all — a
+    stranger is refused before a byte moves. The `yield` shape owns the temp file's life: ingest
+    MOVES it into place on success (the unlink is then a no-op), and on any other exit — cap hit,
+    empty, quota, probe or move error, a client that vanished mid-upload — it is removed."""
    cap = sysconfig.get_int(db, "download_upload_max_bytes")
+    user_id = user.id
+    # Hand the pooled connection back BEFORE the transfer starts — see `db.release_read_connection`
+    # for why, and for the precondition it enforces. Everything this dependency still needs is
+    # already an int or a header in hand: touching an ORM attribute below would reload `user` and
+    # check a connection straight back out.
+    release_read_connection(db)
    staging = Path(settings.download_root) / ".staging" / "uploads"
    staging.mkdir(parents=True, exist_ok=True)
    fd, tmp = tempfile.mkstemp(dir=str(staging))
    tmp_path = Path(tmp)
    try:
-        size = 0
        with os.fdopen(fd, "wb") as out:
-            while chunk := file.file.read(_UPLOAD_CHUNK):
-                size += len(chunk)
-                if cap and size > cap:
-                    raise HTTPException(
-                        status_code=422, detail={"code": "upload_too_large", "limit": cap}
-                    )
-                out.write(chunk)
-        if size == 0:
-            raise HTTPException(status_code=400, detail={"code": "upload_empty"})
-        try:
-            job = uploadmod.ingest_upload(
-                db,
-                user.id,
-                filename=file.filename or "upload",
-                src_path=tmp_path,
-                size=size,
-                display_name=(display_name or "").strip() or None,
+            size = await capped_stream_to(
+                request,
+                out,
+                cap,
+                HTTPException(status_code=422, detail={"code": "upload_too_large", "limit": cap}),
            )
-        except quota.QuotaExceeded as e:
-            raise HTTPException(status_code=422, detail=_quota_detail(e))
-        return _serialize_job(db, job)
+        yield SpooledUpload(
+            path=tmp_path,
+            size=size,
+            user_id=user_id,
+            filename=_header_text(request, UPLOAD_FILENAME_HEADER) or "upload",
+            display_name=display_text(_header_text(request, UPLOAD_DISPLAY_NAME_HEADER)),
+        )
    finally:
-        # Ingest MOVES the temp file into place on success (unlink is then a no-op); on any early exit
-        # — cap hit, empty, quota, probe/move error — this removes the abandoned staging file.
        tmp_path.unlink(missing_ok=True)


+@router.post("/upload")
+def upload_download(
+    upload: SpooledUpload = Depends(spool_upload),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Ingest a local file into the caller's library (E7 S5). Any file type is accepted; media
+    (video/audio) gets the full function set, a generic file is download-only. The body IS the file
+    (see the header note above); `spool_upload` has already authenticated the caller and streamed it
+    to a temp path under the download volume, so what is left here is the non-yt-dlp ingest which
+    probes + places it and returns an already-`done` job.
+
+    A sync (threadpool) handler on purpose: the ingest does blocking work — an ffprobe of up to 30s
+    plus sync DB writes — so it must NOT run on the event loop. The streaming half is async because
+    reading the body is; keeping them in separate callables is what lets each run where it belongs."""
+    if upload.size == 0:
+        raise HTTPException(status_code=400, detail={"code": "upload_empty"})
+    try:
+        job = uploadmod.ingest_upload(
+            db,
+            upload.user_id,
+            filename=upload.filename,
+            src_path=upload.path,
+            size=upload.size,
+            display_name=upload.display_name,
+        )
+    except quota.QuotaExceeded as e:
+        raise HTTPException(status_code=422, detail=_quota_detail(e))
+    return _serialize_job(db, job)
+
+
 class EnqueueEditIn(BaseModel):
    source_job_id: int = 0
    edit_spec: dict
@@ -480,7 +541,7 @@ def enqueue_edit(
    if source_job.status != "done" or source_job.asset_id is None:
        raise refused(409, "edit_unfinished")
    spec = body.edit_spec
-    display_name = (body.display_name or "").strip() or None
+    display_name = display_text(body.display_name)
    try:
        job = service.enqueue_edit(db, user.id, source_job, spec, display_name)
    except quota.QuotaExceeded as e:
@@ -516,7 +577,20 @@ def list_downloads(

@router.get("/usage")
 def my_usage(user: User = Depends(require_human), db: Session = Depends(get_db)) -> dict:
-    return quota.usage(db, user.id)
+    """The caller's download quota, plus the per-file upload cap.
+
+    The cap rides here rather than in `quota.usage` because it is not a quota value — it is a
+    `sysconfig` knob about one route — and this is the route layer, where composing the two is the
+    job. The upload dialog needs it to refuse an over-cap file BEFORE sending it: both server-side
+    caps answer too late to be pleasant (the edge ceiling refuses the request outright, see
+    `bodylimit.ROUTE_MAX_BODY_BYTES`), and making the user push 600 MB up the wire to be told the
+    limit is 500 is a bad answer even when it is a correct one. It is a convenience, not the
+    boundary: the caps stay where they are and still refuse a client that ignores this.
+    """
+    return {
+        **quota.usage(db, user.id),
+        "upload_max_bytes": sysconfig.get_int(db, "download_upload_max_bytes"),
+    }


 # Priority when a source has several jobs (e.g. a done one plus a fresh queued one).
@@ -611,9 +685,9 @@ def update_download_meta(
    job = owned_or_404(db, DownloadJob, job_id, user, what="download")
    sent = body.model_fields_set
    if "display_name" in sent:
-        job.display_name = ((body.display_name or "").strip())[:255] or None
+        job.display_name = display_text(body.display_name)
    if "display_uploader" in sent:
-        job.display_uploader = ((body.display_uploader or "").strip())[:255] or None
+        job.display_uploader = display_text(body.display_uploader)
    if "display_uploader_url" in sent:
        job.display_uploader_url = _clean_url(body.display_uploader_url)
    if "extra_links" in sent:
@@ -4,9 +4,8 @@ mirror the user's own YouTube playlists in (`/sync-youtube`) and push/revert loc
 out (`/{id}/push-plan`, `/{id}/revert-youtube`), behind the optional write scope."""

 from fastapi import APIRouter, Depends, HTTPException
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from sqlalchemy import func, select, and_
-from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session, aliased

 from app import quota
@@ -15,14 +14,18 @@ from app.db import get_db
 from app.feedquery import feed_columns, serialize
 from app.models import Channel, Playlist, PlaylistItem, User, Video, VideoState
 from app.sync.playlists import (
+    PlaylistGone,
+    lock_playlists,
    merge_playlist,
    plan_merge,
    recompute_dirty,
+    pull_user_playlists,
    repull_playlist,
-    sync_user_playlists,
+    sync_claim,
+    user_sync_claim,
 )
 from app.ratelimit import RateLimiter
-from app.routes._common import get_or_404, owned_or_404, youtube_refusal
+from app.routes._common import get_or_404, not_found, owned_or_404, youtube_refusal
 from app.youtube.client import YouTubeClient, YouTubeError

 router = APIRouter(prefix="/api/playlists", tags=["playlists"])
@@ -79,7 +82,10 @@ def _next_playlist_position(db: Session, user_id: int) -> int:


 def _next_item_position(db: Session, playlist_id: int) -> int:
-    """Append position for a new item at the end of a playlist."""
+    """Append position for a new item at the end of a playlist. Locks the playlist row first: two
+    adds (two tabs, the rail and the page) otherwise both read the same max and land on one
+    position, and the list's order between them is then arbitrary."""
+    lock_playlists(db, playlist_id)
    return (
        db.scalar(
            select(func.coalesce(func.max(PlaylistItem.position), -1)).where(
@@ -92,7 +98,10 @@ def _next_item_position(db: Session, playlist_id: int) -> int:

 def _add_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool) -> bool:
    """Append a video to a playlist if not already present (idempotent). Returns whether it
-    was added. `mark_dirty` recomputes the YouTube-sync dirty flag (skip for Watch later)."""
+    was added. `mark_dirty` recomputes the YouTube-sync dirty flag (skip for Watch later).
+    Locked BEFORE the presence check: two adds of one video both saw "absent" and the second one's
+    insert hit uq_playlist_video as a 500."""
+    lock_playlists(db, pl.id)
    exists = db.scalar(
        select(PlaylistItem).where(
            PlaylistItem.playlist_id == pl.id, PlaylistItem.video_id == video_id
@@ -113,6 +122,7 @@ def _add_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool) ->
 def _remove_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool) -> bool:
    """Remove a video from a playlist if present (idempotent). Returns whether it was removed.
    `mark_dirty` recomputes the YouTube-sync dirty flag (skip for Watch later)."""
+    lock_playlists(db, pl.id)
    item = db.scalar(
        select(PlaylistItem).where(
            PlaylistItem.playlist_id == pl.id, PlaylistItem.video_id == video_id
@@ -321,13 +331,18 @@ def sync_youtube(
    Also runs automatically on the scheduler; this is the manual 'sync now'."""
    if not has_read_scope(user):
        raise _refused(403, "youtube_read_scope")
-    _check_pull_cooldown(user)
-    try:
-        with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
-            return {"ok": True, **sync_user_playlists(db, user)}
-    except YouTubeError as exc:
-        db.rollback()
-        raise youtube_refusal(exc)
+    with user_sync_claim(db, user.id) as free:
+        if not free:
+            # Another run (the scheduler, another tab) is pulling right now: "0 synced" would lie.
+            raise _refused(409, "sync_all_busy")
+        # After the claim, like the re-pull's: a refused attempt must not spend one of the pulls.
+        _check_pull_cooldown(user)
+        try:
+            with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
+                return {"ok": True, **pull_user_playlists(db, user)}
+        except YouTubeError as exc:
+            db.rollback()
+            raise youtube_refusal(exc)


@router.post("/{playlist_id}/revert-youtube")
@@ -344,13 +359,20 @@ def revert_youtube(
        raise _refused(400, "not_on_youtube")
    if not has_read_scope(user):
        raise _refused(403, "youtube_read_scope")
-    _check_pull_cooldown(user)
-    try:
-        with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
-            return {"ok": True, **repull_playlist(db, user, pl)}
-    except YouTubeError as exc:
-        db.rollback()
-        raise youtube_refusal(exc)
+    with sync_claim(db, pl.id) as free:
+        if not free:
+            raise _refused(409, "sync_busy")
+        # The cooldown is spent only by a pull that runs: checked after the claim, so clicking
+        # Revert while a push is in flight does not use up the three pulls per ten minutes.
+        _check_pull_cooldown(user)
+        try:
+            with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
+                return {"ok": True, **repull_playlist(db, user, pl)}
+        except PlaylistGone:
+            raise not_found("playlist")
+        except YouTubeError as exc:
+            db.rollback()
+            raise youtube_refusal(exc)


 def _pushable(db: Session, user: User, playlist_id: int) -> Playlist:
@@ -392,25 +414,32 @@ def push(
    neither side loses an item). Refuses if the estimated quota exceeds what's left today, so a
    big sync can't strand half-applied. Write scope required (require_write_scope)."""
    pl = _pushable(db, user, playlist_id)
-    try:
-        with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PUSH):
-            # Read the live playlist ONCE (linked playlists only) and share it with both the
-            # plan and the merge, halving read-quota and closing the second read→write TOCTOU
-            # window. A fresh export (no yt_playlist_id) reads nothing.
-            live = None
-            if pl.yt_playlist_id:
-                with YouTubeClient(db, user) as yt:
-                    live = (
-                        list(yt.iter_playlist_items_with_ids(pl.yt_playlist_id)),
-                        yt.get_playlist_snippet(pl.yt_playlist_id),
-                    )
-            plan = plan_merge(db, user, pl, live=live)
-            if plan["units_estimate"] > quota.remaining_today(db):
-                raise _refused(429, "quota_exceeded")
-            return {"ok": True, **merge_playlist(db, user, pl, live=live)}
-    except YouTubeError as exc:
-        db.rollback()
-        raise youtube_refusal(exc)
+    # One sync of a list at a time, across tabs, devices and the scheduler (`sync_claim`): the
+    # client's own in-flight flag only covers the menus of one page.
+    with sync_claim(db, pl.id) as free:
+        if not free:
+            raise _refused(409, "sync_busy")
+        try:
+            with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PUSH):
+                # Read the live playlist ONCE (linked playlists only) and share it with both the
+                # plan and the merge, halving read-quota and closing the second read→write TOCTOU
+                # window. A fresh export (no yt_playlist_id) reads nothing.
+                live = None
+                if pl.yt_playlist_id:
+                    with YouTubeClient(db, user) as yt:
+                        live = (
+                            list(yt.iter_playlist_items_with_ids(pl.yt_playlist_id)),
+                            yt.get_playlist_snippet(pl.yt_playlist_id),
+                        )
+                plan = plan_merge(db, user, pl, live=live)
+                if plan["units_estimate"] > quota.remaining_today(db):
+                    raise _refused(429, "quota_exceeded")
+                return {"ok": True, **merge_playlist(db, user, pl, live=live)}
+        except PlaylistGone:
+            raise not_found("playlist")
+        except YouTubeError as exc:
+            db.rollback()
+            raise youtube_refusal(exc)


@router.get("/{playlist_id}")
@@ -427,7 +456,8 @@ def get_playlist(
        .join(Channel, Channel.id == Video.channel_id)
        .outerjoin(state, and_(state.video_id == Video.id, state.user_id == user.id))
        .where(PlaylistItem.playlist_id == pl.id)
-        .order_by(PlaylistItem.position)
+        # `id` breaks a position tie the same way on every read (the renumbering add does too).
+        .order_by(PlaylistItem.position, PlaylistItem.id)
    ).all()
    return {
        "id": pl.id,
@@ -451,7 +481,8 @@ def rename_playlist(
    user: User = Depends(current_user),
    db: Session = Depends(get_db),
 ) -> dict:
-    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
+    # Locked: the new name moves `dirty`, which the scheduled mirror refresh reads under this lock.
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist", lock=True)
    if "name" in body.model_fields_set:
        name = (body.name or "").strip()
        if not name:
@@ -491,33 +522,65 @@ def delete_playlist(
    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
    if pl.kind == "watch_later":
        raise _refused(400, "watch_later_undeletable")
-    if on_youtube:
-        if not pl.yt_playlist_id:
-            raise _refused(400, "not_on_youtube")
-        if not has_write_scope(user):
-            raise _refused(403, "youtube_editing_off")
-        try:
-            with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_DELETE):
-                with YouTubeClient(db, user) as yt:
-                    yt.delete_playlist(pl.yt_playlist_id)
-        except YouTubeError as exc:
-            raise youtube_refusal(exc)
-    db.delete(pl)  # items cascade
-    db.commit()
+    # Not in the middle of a sync of it (`sync_claim`): a push that read the list before the delete
+    # and wrote YouTube after it planned from no items at all, so it emptied the YouTube playlist a
+    # local-only delete means to keep. The push checks for a vanished list too (`PlaylistGone`);
+    # this refuses the delete while a sync runs rather than race it.
+    with sync_claim(db, pl.id) as free:
+        if not free:
+            raise _refused(409, "sync_busy")
+        if on_youtube:
+            if not pl.yt_playlist_id:
+                raise _refused(400, "not_on_youtube")
+            if not has_write_scope(user):
+                raise _refused(403, "youtube_editing_off")
+            try:
+                with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_DELETE):
+                    with YouTubeClient(db, user) as yt:
+                        yt.delete_playlist(pl.yt_playlist_id)
+            except YouTubeError as exc:
+                raise youtube_refusal(exc)
+        # The playlist first, as every item write: the cascade deletes the items before the list row.
+        lock_playlists(db, pl.id)
+        db.delete(pl)  # items cascade
+        db.commit()
    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: VideoRefIn,
+    body: AddItemIn,
    user: User = Depends(current_user),
    db: Session = Depends(get_db),
 ) -> dict:
    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
    video_id = body.video_id
    get_or_404(db, Video, video_id, what="video")
-    _add_item(db, pl, video_id, mark_dirty=True)
+    added = _add_item(db, pl, video_id, mark_dirty=False)
+    if added and body.position is not None:
+        # Renumber the whole list with the new row at `position` (clamped to the end): positions
+        # can have gaps after removals, so "index N" is only meaningful over the ordered rows.
+        rows = list(
+            db.execute(
+                select(PlaylistItem)
+                .where(PlaylistItem.playlist_id == pl.id)
+                .order_by(PlaylistItem.position, PlaylistItem.id)
+            ).scalars()
+        )
+        new = next(r for r in rows if r.video_id == video_id)
+        rows.remove(new)
+        rows.insert(min(body.position, len(rows)), new)
+        for pos, row in enumerate(rows):
+            row.position = pos
+    recompute_dirty(db, pl)
    db.commit()
    return {"ok": True, "playlist_id": pl.id, "video_id": video_id}

@@ -562,6 +625,8 @@ def move_item(
        raise HTTPException(
            status_code=400, detail={"code": "playlist_move", "reason": "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)
    item = db.scalar(
        select(PlaylistItem).where(
            PlaylistItem.playlist_id == src.id, PlaylistItem.video_id == video_id
@@ -581,20 +646,11 @@ def move_item(
    if already 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 is not a lock: a second tab's add or the scheduler's YouTube merge can insert
-        # the same (playlist, video) in between, and uq_playlist_video then refuses the re-parent.
-        # That is the already-present outcome arriving late, not a failure — answer it the same way
-        # instead of a raw 500.
-        try:
-            with db.begin_nested():
-                item.playlist_id = dst.id
-                item.position = _next_item_position(db, dst.id)
-                db.flush()
-            dst_changed = True
-        # silent-ok: the conflict IS the answer — the target already holds the video, which is the
-        # idempotent outcome; the savepoint put the row back in the source list, dropped below.
-        except IntegrityError:
-            pass
+        # 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.
+        item.playlist_id = dst.id
+        item.position = _next_item_position(db, dst.id)
+        dst_changed = True
    if not dst_changed:
        db.delete(item)
    # The source always changed; the target only when the row landed in it. `_touch` on a target
@@ -619,7 +675,8 @@ def reorder_items(
    user: User = Depends(current_user),
    db: Session = Depends(get_db),
 ) -> dict:
-    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist")
+    # Locked: a concurrent add between reading the items and writing the order would collide.
+    pl = owned_or_404(db, Playlist, playlist_id, user, what="playlist", lock=True)
    order = body.video_ids
    items = {
        it.video_id: it
@@ -3,8 +3,10 @@
 from datetime import datetime, timezone

 from fastapi import APIRouter, Depends
-from pydantic import BaseModel
-from sqlalchemy import delete, func, select, update
+from typing import Annotated
+
+from pydantic import BaseModel, Field, model_validator
+from sqlalchemy import delete, func, select
 from sqlalchemy.orm import Session

 from app.auth import current_user
@@ -217,7 +219,8 @@ def playlist_add_item(
    user: User = Depends(current_user),
    db: Session = Depends(get_db),
 ) -> dict:
-    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
+    # Locked (like every add / reorder here): two adds otherwise read the same max position.
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist", lock=True)
    it = by_rating_key(db, PlexItem, body.item_rating_key)
    if it is None:
        raise not_found("item")
@@ -249,7 +252,9 @@ def playlist_remove_item(
    user: User = Depends(current_user),
    db: Session = Depends(get_db),
 ) -> dict:
-    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
+    # Locked like the adds and the reorder: the list row first, then its items — a remove that
+    # locked an item row before a reorder locked the list deadlocked against it.
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist", lock=True)
    it = by_rating_key(db, PlexItem, item_rating_key)
    if it is not None:
        db.execute(
@@ -285,16 +290,75 @@ def _items_by_rks(db: Session, rks: list) -> list[PlexItem]:
    return out


+class PlexItemAddBulkIn(PlexItemKeysIn):
+    # Where each key goes back (E28 S3e2, the list page's "Undo" of a removal): an index over the
+    # ORDERED rows, one per key. The two-call shape (append, then send the whole order) leaves the rows
+    # at the end whenever the second call fails, and the order it sends would overwrite anything
+    # another tab changed in between.
+    positions: list[Annotated[int, Field(ge=0)]] | None = None
+
+    @model_validator(mode="after")
+    def _one_position_per_key(self):
+        if self.positions is not None and len(self.positions) != len(self.item_rating_keys):
+            raise ValueError("positions must pair one-to-one with item_rating_keys")
+        return self
+
+
+def _insert_at(db: Session, pid: int, placed: list[tuple[int, PlexItem]]) -> int:
+    """Insert new rows at their indices (ascending, so each index is where the row stood when the
+    rows before it were back), renumber the whole list 0..n-1, and say how many were added. An item
+    already in the list does not move: the add stays idempotent."""
+    rows = list(
+        db.execute(
+            select(PlexPlaylistItem)
+            .where(PlexPlaylistItem.playlist_id == pid)
+            .order_by(PlexPlaylistItem.position, PlexPlaylistItem.id)
+        ).scalars()
+    )
+    present = {r.item_id for r in rows}
+    added = 0
+    for at, it in sorted(placed, key=lambda p: p[0]):
+        if it.id in present:
+            continue
+        row = PlexPlaylistItem(playlist_id=pid, item_id=it.id, position=0)
+        db.add(row)
+        rows.insert(min(at, len(rows)), row)
+        present.add(it.id)
+        added += 1
+    for i, r in enumerate(rows):
+        r.position = i
+    return added
+
+
@router.post("/playlists/{pid}/items/bulk")
 def playlist_add_bulk(
    pid: int,
-    body: PlexItemKeysIn,
+    body: PlexItemAddBulkIn,
    user: User = Depends(current_user),
    db: Session = Depends(get_db),
 ) -> dict:
    """Append many items at once (a whole season/show). Already-present items are skipped; the input
-    order is preserved for the newly-added ones. Returns how many were added + the new total."""
-    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
+    order is preserved for the newly-added ones. With `positions`, each key is put back at its index
+    instead of appended. Returns how many were added + the new total."""
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist", lock=True)
+    if body.positions is not None:
+        by_rk = {it.rating_key: it for it in _items_by_rks(db, body.item_rating_keys)}
+        placed = [
+            (at, by_rk[str(rk)])
+            for rk, at in zip(body.item_rating_keys, body.positions, strict=True)
+            if str(rk) in by_rk
+        ]
+        added = _insert_at(db, pid, placed)
+        if added:
+            pl.updated_at = datetime.now(timezone.utc)
+        db.commit()
+        total = (
+            db.scalar(
+                select(func.count(PlexPlaylistItem.id)).where(PlexPlaylistItem.playlist_id == pid)
+            )
+            or 0
+        )
+        return {"ok": True, "added": added, "item_count": total}
    items = _items_by_rks(db, body.item_rating_keys)
    existing = set(
        db.execute(
@@ -337,7 +401,7 @@ def playlist_remove_bulk(
 ) -> dict:
    """Remove many items at once (a whole season/show, or a multi-select). Returns how many were
    removed + the new total."""
-    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist", lock=True)
    ids = [it.id for it in _items_by_rks(db, body.item_rating_keys)]
    removed = 0
    if ids:
@@ -367,7 +431,7 @@ def reorder_playlist(
    db: Session = Depends(get_db),
 ) -> dict:
    """Set the playlist order from an explicit list of item rating_keys (0-based positions)."""
-    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
+    pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist", lock=True)
    order = body.item_rating_keys
    id_by_rk = {
        it.rating_key: it.id
@@ -375,14 +439,27 @@ def reorder_playlist(
            select(PlexItem).where(PlexItem.rating_key.in_(order or [""]))
        ).scalars()
    }
-    for pos, rk in enumerate(order):
-        iid = id_by_rk.get(rk)
-        if iid is not None:
-            db.execute(
-                update(PlexPlaylistItem)
-                .where(PlexPlaylistItem.playlist_id == pid, PlexPlaylistItem.item_id == iid)
-                .values(position=pos)
-            )
+    rows = {
+        r.item_id: r
+        for r in db.execute(
+            select(PlexPlaylistItem).where(PlexPlaylistItem.playlist_id == pid)
+        ).scalars()
+    }
+    pos = 0
+    seen: set[int] = set()
+    for rk in order:
+        row = rows.get(id_by_rk.get(rk, -1))
+        if row is not None and row.item_id not in seen:
+            row.position = pos
+            pos += 1
+            seen.add(row.item_id)
+    # Rows the payload omitted (added in another tab meanwhile) keep their relative order after
+    # the given ones, so no two rows share a position (the YouTube reorder does the same).
+    for row in sorted(
+        (r for iid, r in rows.items() if iid not in seen), key=lambda r: (r.position, r.id)
+    ):
+        row.position = pos
+        pos += 1
    pl.updated_at = datetime.now(timezone.utc)
    db.commit()
    return {"ok": True}
@@ -130,7 +130,7 @@ def _ingest_candidates(
        try:
            with quota.attribute(user.id, quota.QuotaAction.CHANNELS_DISCOVER):
                details = yt.get_channels(new_channel_ids)
-            apply_channel_details(db, details)
+            apply_channel_details(db, details, new_channel_ids)
            db.commit()
        except YouTubeError:
            # The stubs remain and the details can be backfilled later — but until they are, those
@@ -8,13 +8,15 @@ ingested (with a stub channel) so the mirror is faithful."""

 import hashlib
 import json
-from collections.abc import Callable
+from collections.abc import Callable, Iterator
+from contextlib import AbstractContextManager, contextmanager
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import TypeVar

-from sqlalchemy import delete, select
+from sqlalchemy import Engine, create_engine, delete, func, select
 from sqlalchemy.orm import Session
+from sqlalchemy.pool import NullPool

 from app import logs, progress, quota
 from app.auth import has_read_scope
@@ -27,6 +29,87 @@ log = logs.get_logger(__name__)
 # Cost of a single YouTube write op (playlists/playlistItems insert/update/delete).
 WRITE_UNIT_COST = 50

+# The advisory-lock namespaces ("PL" per playlist, "PU" per user), so a key cannot meet another
+# feature's lock on the same number (Postgres keeps the two-int keys apart from the one-bigint ones).
+_SYNC_LOCK_NS = 0x504C
+_USER_SYNC_LOCK_NS = 0x5055
+
+# The claims' own connections, outside the app pool: a claim is held for a whole push (seconds of
+# YouTube calls) beside the request's pooled session and quota's, so a burst of pushes drawing a
+# third pooled connection each ran the pool dry and stalled every other request for pool_timeout.
+# NullPool opens one per claim and closes it after, so a lock can never ride back into a pool either.
+_claim_engines: dict[str, Engine] = {}
+
+
+def _claim_engine(db: Session) -> Engine:
+    url = db.get_bind().engine.url
+    key = url.render_as_string(hide_password=False)
+    eng = _claim_engines.get(key)
+    if eng is None:
+        eng = _claim_engines[key] = create_engine(url, poolclass=NullPool, hide_parameters=True)
+    return eng
+
+
+@contextmanager
+def _advisory_claim(db: Session, ns: int, key: int) -> Iterator[bool]:
+    """Try a session-level advisory lock for the block on a connection of its own; yields whether it
+    was free. It survives the block's commits, and a crashed worker's lock dies with its connection
+    — no claim column that a crash leaves stuck."""
+    conn = _claim_engine(db).connect()
+    held = False
+    try:
+        held = bool(conn.scalar(select(func.pg_try_advisory_lock(ns, key))))
+        conn.commit()
+        yield held
+    finally:
+        try:
+            if held:
+                conn.scalar(select(func.pg_advisory_unlock(ns, key)))
+                conn.commit()
+        finally:
+            conn.close()
+
+
+def sync_claim(db: Session, playlist_id: int) -> AbstractContextManager[bool]:
+    """Claim one playlist's YouTube sync (push, re-pull, the scheduled mirror refresh) for the block;
+    yields whether it was free. A push reads YouTube, then writes both sides for seconds and commits
+    step by step, so a row lock ends at its first commit and two tabs (or a push and the scheduler)
+    interleave into a doubled YouTube item or a baseline recorded over the other's writes."""
+    return _advisory_claim(db, _SYNC_LOCK_NS, playlist_id)
+
+
+class PlaylistGone(Exception):
+    """The list a sync was working on was deleted meanwhile (another tab, the mirror drop). Its
+    items went with it, so a plan made now reads "every item removed here" — and would delete them
+    all from the YouTube playlist the reader chose to keep. The route answers 404."""
+
+
+def lock_playlists(db: Session, *playlist_ids: int) -> set[int]:
+    """Row-lock playlists before touching their items, several in id order. Every item write takes
+    the PLAYLIST first — the route edits, a push, a re-pull, the scheduled mirror refresh and a
+    delete alike: a writer that locked an item row first and the playlist second (a push's item
+    replace beside a remove) deadlocks against one that went the other way, and the loser is a
+    500. The rows are re-read, so `dirty`, the name and the sync baseline are the ones a finished
+    writer committed. Held to the caller's next commit — so no commit may come between this and
+    the write it guards. Returns the ids it found: a list deleted meanwhile is not among them."""
+    rows = db.scalars(
+        select(Playlist)
+        .where(Playlist.id.in_(sorted(set(playlist_ids))))
+        .order_by(Playlist.id)
+        .with_for_update()
+        .execution_options(populate_existing=True)
+    ).all()  # consumed: rows fetched are what refreshes the loaded objects
+    return {pl.id for pl in rows}
+
+
+def _lock_or_gone(db: Session, pl: Playlist) -> None:
+    """`lock_playlists` for a sync that goes on to write YouTube or the items: a list deleted since
+    it was read raises `PlaylistGone` (rolled back) instead of being planned as an empty one."""
+    pl_id = pl.id  # read first: the rollback expires `pl`, and its row is gone
+    if pl_id not in lock_playlists(db, pl_id):
+        db.rollback()
+        raise PlaylistGone(pl_id)
+

 def fingerprint(name: str, ids: list[str]) -> str:
    """A stable checksum of a playlist's name + ordered video ids. Stored as the synced
@@ -91,11 +174,18 @@ def parse_unavailable(pl: Playlist) -> set[str]:
    return _load_baseline(pl)[1]


-def _set_baseline(pl: Playlist, ids: list[str], unavailable: list[str] | None = None) -> None:
+def _set_baseline(
+    pl: Playlist,
+    ids: list[str],
+    unavailable: list[str] | None = None,
+    *,
+    name: str | None = None,
+) -> None:
    """Record `ids` as both the hash (drives `dirty`, over the local ids only) and the raw ordered
    set (drives merge). `unavailable` = un-ingestable-but-live YouTube ids to carry forward so the
-    next merge skips them; stored only when non-empty (keeps the common case a plain list)."""
-    pl.synced_fingerprint = fingerprint(pl.name, ids)
+    next merge skips them; stored only when non-empty (keeps the common case a plain list). `name`:
+    the title YouTube now has, when that may differ from the list's own (see the push)."""
+    pl.synced_fingerprint = fingerprint(pl.name if name is None else name, ids)
    if unavailable:
        pl.synced_video_ids = json.dumps({"ids": ids, "unavailable": list(unavailable)})
    else:
@@ -103,6 +193,25 @@ def _set_baseline(pl: Playlist, ids: list[str], unavailable: list[str] | None =
    pl.dirty = False


+def _set_baseline_under_lock(
+    db: Session,
+    pl: Playlist,
+    ids: list[str],
+    unavailable: list[str] | None = None,
+    *,
+    name: str,
+) -> None:
+    """A push's closing baseline: `ids` and `name` are what YouTube now holds. The push spent
+    seconds on YouTube writes since it replaced the local items, so an edit may have landed
+    meanwhile — lock the list and derive `dirty` from what is there, or the edit would read as
+    synced and never reach YouTube. The name too: the lock re-reads a rename made meanwhile, and a
+    baseline taken over THAT name matched it, so the list read clean with YouTube's title still the
+    old one (E28 review round 4)."""
+    _lock_or_gone(db, pl)
+    _set_baseline(pl, ids, unavailable, name=name)
+    recompute_dirty(db, pl)
+
+
 def recompute_dirty(db: Session, pl: Playlist) -> None:
    """Set `dirty` by comparing the current state to the synced baseline. Unlinked lists
    (and Watch later) are never dirty; a missing baseline counts as dirty (unknown YT state)."""
@@ -159,15 +268,13 @@ def _ensure_videos(db: Session, yt: YouTubeClient, video_ids: list[str]) -> None
    db.commit()


-def _replace_items_from_youtube(
-    db: Session, yt: YouTubeClient, pl: Playlist, ids: list[str]
-) -> list[str]:
+def _replace_items_from_youtube(db: Session, pl: Playlist, ids: list[str]) -> list[str]:
    """Mirror a YouTube playlist's ordered video ids into `pl`'s local items (authoritative
-    replace): ensure the videos exist in the catalog, keep only those present in their YT
-    order (de-duplicated), swap the items out, and reset the synced fingerprint + dirty flag.
-    `pl.name` must already be set to the desired name. The caller commits. Returns the final
-    ordered ids."""
-    _ensure_videos(db, yt, ids)
+    replace): keep only those present in the catalog in their YT order (de-duplicated), swap the
+    items out, and reset the synced fingerprint + dirty flag. The caller has ingested `ids`
+    (`_ensure_videos`, which commits) and THEN taken `lock_playlists`, set `pl.name`, and commits
+    after: an ingest in here re-fetched every id YouTube will not return (a private or deleted
+    video) and its commit let go of the lock before the replace. Returns the final ordered ids."""
    present = (
        set(db.execute(select(Video.id).where(Video.id.in_(ids))).scalars().all()) if ids else set()
    )
@@ -196,6 +303,21 @@ def sync_user_playlists(db: Session, user: User) -> dict:
    the user's local playlists and the built-in Watch later untouched."""
    if not has_read_scope(user):
        return {"synced": 0, "reason": "no read scope"}
+    with user_sync_claim(db, user.id) as free:
+        if not free:
+            return {"synced": 0, "reason": "busy"}
+        return pull_user_playlists(db, user)
+
+
+def user_sync_claim(db: Session, user_id: int) -> AbstractContextManager[bool]:
+    """Claim a user's bulk mirror pull for the block; yields whether it was free. Two runs at once
+    (the scheduler beside a manual "sync now", two tabs) both saw a YouTube list unmirrored and
+    each created its mirror — a duplicate row."""
+    return _advisory_claim(db, _USER_SYNC_LOCK_NS, user_id)
+
+
+def pull_user_playlists(db: Session, user: User) -> dict:
+    """The mirror pull itself; the caller holds `user_sync_claim`."""
    synced = 0
    with YouTubeClient(db, user) as yt:
        yt_playlists = list(yt.iter_my_playlists())
@@ -219,11 +341,15 @@ def sync_user_playlists(db: Session, user: User) -> dict:
            .scalars()
            .all()
        )
-        # Drop mirrors whose YouTube playlist no longer exists.
-        for ytid, pl in existing.items():
-            if ytid not in yt_ids:
-                db.delete(pl)
-        db.flush()
+        # Drop mirrors whose YouTube playlist no longer exists — locked first, as every item write.
+        gone = [pl for ytid, pl in existing.items() if ytid not in yt_ids]
+        if gone:
+            lock_playlists(db, *(pl.id for pl in gone))
+        for pl in gone:
+            db.delete(pl)
+        # Committed now: a run where no list below commits (all dirty, or all claimed) would
+        # otherwise drop the deletions with the session.
+        db.commit()

        for idx, p in enumerate(yt_playlists):
            ytid = p.get("id")
@@ -245,12 +371,27 @@ def sync_user_playlists(db: Session, user: User) -> dict:
                )
                db.add(pl)
                db.flush()
-            else:
+            with sync_claim(db, pl.id) as free:
+                if not free:
+                    # The user is pushing or re-pulling this very list: it writes the same rows.
+                    # The next scheduled run refreshes it.
+                    continue
+                ids = list(yt.iter_my_playlist_video_ids(ytid))
+                # Ingest first — it commits — so the row lock below is held from the dirty check
+                # to the commit that replaces the items.
+                _ensure_videos(db, yt, ids)
+                # `dirty` read above is a snapshot from before the YouTube calls (sessions keep
+                # loaded rows past a commit): a remove or reorder made meanwhile must not be
+                # replaced by YouTube's order. Item writes lock the playlist row, so this waits for
+                # one in flight and sees what it committed.
+                lock_playlists(db, pl.id)
+                if pl.dirty:
+                    db.rollback()
+                    continue
                pl.name = p.get("title") or pl.name
-            # Mirror is authoritative: replace the items to match YouTube's order.
-            ids = list(yt.iter_my_playlist_video_ids(ytid))
-            _replace_items_from_youtube(db, yt, pl, ids)
-            db.commit()
+                # Mirror is authoritative: replace the items to match YouTube's order.
+                _replace_items_from_youtube(db, pl, ids)
+                db.commit()
            synced += 1
    return {"synced": synced}

@@ -488,7 +629,8 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
    breaker = _Breaker(playlist_id=pl.id)
    with YouTubeClient(db, user) as yt:
        if not pl.yt_playlist_id:
-            pl.yt_playlist_id = yt.create_playlist(pl.name)
+            pushed_name = pl.name
+            pl.yt_playlist_id = yt.create_playlist(pushed_name)
            db.commit()
            created = 1
            # Brand-new playlist: just append every local video in order.
@@ -501,7 +643,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
                if not isinstance(added, _Failed):
                    inserted += 1
            if not failures:
-                _set_baseline(pl, local)
+                _set_baseline_under_lock(db, pl, local, name=pushed_name)
            db.commit()
            return {
                "created": created,
@@ -542,6 +684,14 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
        # merged order authoritatively. Do this first so local reflects the merge even if a later
        # YouTube write trips the breaker.
        _ensure_videos(db, yt, mp.add_to_local)
+        # `local` was read before the YouTube calls above: an add or remove committed meanwhile
+        # (another tab) would be undone by the replace below. Lock the list — the ingest's commit is
+        # behind us — and plan again from what is there now. Nothing new needs ingesting: a video
+        # the re-read adds is already a local row. A list deleted meanwhile stops here, before a plan
+        # over its now-empty items removes them all from YouTube.
+        _lock_or_gone(db, pl)
+        local = _local_video_ids(db, pl)
+        mp = merge_plan(parse_baseline(pl), local, yt_ids, effective_unavailable)
        # Only the ids that actually exist in the catalog can become local rows (a private/deleted
        # YouTube video won't ingest); keep the merged order, dropping any that didn't materialize.
        present = (
@@ -555,10 +705,12 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
        _set_local_items(db, pl, final_local)
        db.commit()

-        # --- YouTube side (metered, breaker-guarded).
-        if snippet is not None and (snippet.get("title") or "") != pl.name:
+        # --- YouTube side (metered, breaker-guarded). The name as of the lock above: the closing
+        # baseline records THIS one, whatever a rename made during the writes below says.
+        pushed_name = pl.name
+        if snippet is not None and (snippet.get("title") or "") != pushed_name:
            try:
-                yt.update_playlist_title(pl.yt_playlist_id, pl.name)
+                yt.update_playlist_title(pl.yt_playlist_id, pushed_name)
            except YouTubeError as exc:
                # All the caller passes on is the word "title", which says the rename did not
                # happen but not that YouTube refused it, or why.
@@ -626,7 +778,7 @@ def merge_playlist(db: Session, user: User, pl: Playlist, *, live=None) -> dict:
                (effective_unavailable | {v for v in mp.add_to_local if v not in present})
                & yt_id_set
            )
-            _set_baseline(pl, final_local, unavailable)
+            _set_baseline_under_lock(db, pl, final_local, unavailable, name=pushed_name)
        db.commit()
    return {
        "created": created,
@@ -652,9 +804,11 @@ def repull_playlist(db: Session, user: User, pl: Playlist) -> dict:
        snippet = yt.get_playlist_snippet(pl.yt_playlist_id)
        if snippet is None:
            raise YouTubeError("Playlist no longer exists on YouTube")
-        pl.name = snippet.get("title") or pl.name
        ids = list(yt.iter_my_playlist_video_ids(pl.yt_playlist_id))
-        ordered = _replace_items_from_youtube(db, yt, pl, ids)
+        _ensure_videos(db, yt, ids)
+        _lock_or_gone(db, pl)
+        pl.name = snippet.get("title") or pl.name
+        ordered = _replace_items_from_youtube(db, pl, ids)
        db.commit()
    return {"items": len(ordered)}

@@ -1,8 +1,9 @@
 """Import the authenticated user's YouTube subscriptions and channel metadata."""

-from datetime import datetime, timezone
+from collections.abc import Iterable
+from datetime import datetime, timedelta, timezone

-from sqlalchemy import select
+from sqlalchemy import or_, select
 from sqlalchemy.orm import Session

 from app import logs
@@ -47,8 +48,37 @@ def _external_links(branding: dict) -> list | None:
    return out or None


-def apply_channel_details(db: Session, items: list[dict]) -> None:
+# How old a channel's metadata may get before it is fetched again. Banners, avatars, descriptions and
+# counts change on YouTube, and an old banner URL stops resolving at all — without a refresh a channel
+# kept whatever it had the day it was first seen. A week keeps counts roughly current at almost no
+# cost: `channels.list` is 1 quota unit per 50 channels, and only the stale ones are asked for.
+DETAILS_MAX_AGE = timedelta(days=7)
+
+
+def details_stale(channel: Channel, now: datetime) -> bool:
+    """Whether `channel`'s metadata is missing or older than DETAILS_MAX_AGE (see `details_stale_clause`)."""
+    synced = channel.details_synced_at
+    return synced is None or synced < now - DETAILS_MAX_AGE
+
+
+def details_stale_clause(now: datetime):
+    """`details_stale` as a WHERE clause, so the batch import and a single channel agree on "stale"."""
+    return or_(
+        Channel.details_synced_at.is_(None),
+        Channel.details_synced_at < now - DETAILS_MAX_AGE,
+    )
+
+
+def apply_channel_details(db: Session, items: list[dict], asked: Iterable[str]) -> None:
+    """Write `channels.list`'s answer onto the rows. `asked` is every id the call asked for: one
+    YouTube did not return (terminated, deleted) is stamped as synced too — otherwise it stays
+    stale forever and every view / import asks for it again, spending quota on a known miss."""
    now = datetime.now(timezone.utc)
+    returned = {item["id"] for item in items}
+    for cid in set(asked) - returned:
+        missing = db.get(Channel, cid)
+        if missing is not None:
+            missing.details_synced_at = now
    for item in items:
        channel = db.get(Channel, item["id"])
        if channel is None:
@@ -92,7 +122,7 @@ def should_prune(fetched_count: int, existing_count: int) -> bool:
 def import_subscriptions(db: Session, user: User) -> dict:
    """Pull all subscriptions for `user`, upsert channels + subscription links, prune
    channels the user has unsubscribed from on YouTube, and fetch channel details for
-    any channel we don't have details for yet."""
+    any channel whose details are missing or stale (`DETAILS_MAX_AGE`)."""
    fetched: dict[str, dict] = {}
    new_channels = 0

@@ -145,12 +175,12 @@ def import_subscriptions(db: Session, user: User) -> dict:
                    removed += 1
        db.commit()

-        # Fetch details for channels that don't have them yet.
+        # Fetch details for channels that don't have them yet, or had them too long ago.
        need_details = (
            db.execute(
                select(Channel).where(
                    Channel.id.in_(fetched.keys()),
-                    Channel.details_synced_at.is_(None),
+                    details_stale_clause(datetime.now(timezone.utc)),
                )
            )
            .scalars()
@@ -158,8 +188,9 @@ def import_subscriptions(db: Session, user: User) -> dict:
        )
        detailed = 0
        if need_details:
-            items = yt.get_channels([c.id for c in need_details])
-            apply_channel_details(db, items)
+            ids = [c.id for c in need_details]
+            items = yt.get_channels(ids)
+            apply_channel_details(db, items, ids)
            detailed = len(items)
        db.commit()

@@ -137,10 +137,29 @@ SPECS: tuple[ConfigSpec, ...] = (
        min=1,
        max=100_000,
    ),
-    # min=1, NOT 0: the per-file cap is enforced as `if cap and size > cap`, so a stored 0 would read
-    # as falsy and SILENTLY disable the limit (an unbounded streamed write to the volume). Floor it at
-    # 1 so the cap is always active; the overall footprint is separately bounded by the byte quota.
-    ConfigSpec("download_upload_max_bytes", "int", "downloads", "download_upload_max_bytes", min=1),
+    # min=1, NOT 0: a stored 0 used to read as "no per-file cap" (the cap was enforced as
+    # `if cap and size > cap`, so a falsy value disabled it). Since P1 the route passes this number
+    # straight to `capped_stream_to`, where 0 would refuse every upload instead — the opposite
+    # failure, and the reason `config.download_upload_max_bytes` carries its own `ge=1`. Either way
+    # a stored 0 is wrong, so it is floored at 1; the overall footprint is separately bounded by the
+    # byte quota.
+    # `max` is not cosmetic: `bodylimit.ROUTE_MAX_BODY_BYTES` refuses an upload body over exactly
+    # this number at the edge, before the route's own check ever sees it. An admin allowed to raise
+    # the knob past the edge would get 413s from a layer the admin page never mentions, so the two
+    # are pinned together here and `tests/test_body_limit.py` holds them that way. Below the edge is
+    # the useful direction and the one the knob exists for: a lowered knob is what makes the route's
+    # own 422 — the one carrying this figure — the answer the user gets. `_coerce` also
+    # REJECTS a stored value outside these bounds on read (falling back to the env default, with a
+    # warning) — neither bound has always been what it is now, so a legal-when-written override can
+    # be sitting in the database already.
+    ConfigSpec(
+        "download_upload_max_bytes",
+        "int",
+        "downloads",
+        "download_upload_max_bytes",
+        min=1,
+        max=settings.download_upload_max_bytes,
+    ),
    ConfigSpec(
        "download_retention_days", "int", "downloads", "download_retention_days", min=0, max=3_650
    ),
@@ -236,9 +255,29 @@ def _choice(s: ConfigSpec, raw: object) -> str:
    return option


+class OutOfRange(ValueError):
+    """A stored int override that no longer satisfies its spec's bounds."""
+
+
 def _coerce(s: ConfigSpec, raw: str):
    if s.type == "int":
-        return int(raw)
+        # Bounds are checked on READ, not only in `set_value`. Bounds get ADDED to a spec
+        # (download_upload_max_bytes gained a `max` when SEC-20 started enforcing the same number at
+        # the edge; its `min` went 0 → 1 during E7) and env defaults get LOWERED, and either leaves
+        # a stored value that was legal when it was written. Serving it is how one layer ends up
+        # acting on a number another layer refuses, with the admin page showing a value outside the
+        # range it renders.
+        #
+        # It raises rather than CLAMPING, and that distinction cost a round: clamping is a silent
+        # rewrite, and silently rewriting is exactly what this module refuses to do elsewhere. The
+        # case that settles it is a stored 0 for download_upload_max_bytes — legal when `min` was 0,
+        # and meaning "no per-file cap" to the route that reads it. Clamped to `min=1` it becomes a
+        # ONE-BYTE cap and uploads stop working with nothing in the log. Raising drops it into the
+        # same fallback the uncoercible path uses: the env default, and one warning.
+        v = int(raw)
+        if (s.min is not None and v < s.min) or (s.max is not None and v > s.max):
+            raise OutOfRange(f"{v} is outside [{s.min}, {s.max}]")
+        return v
    if s.type == "bool":
        return raw == "true"
    if s.type == "choice":
@@ -291,14 +330,19 @@ def get(db: Session, key: str):
        return _coerce(s, raw)
    except (TypeError, ValueError) as exc:
        # The admin set this in the UI and it is quietly not in force: the app runs on the env
-        # default while the settings page goes on showing the value that was saved.
+        # default while the settings page goes on showing the value that was saved. An OutOfRange is
+        # the same situation arrived at from the other direction — the value was fine when it was
+        # written and the spec moved under it — so it gets the same treatment and its own code.
+        event = (
+            "sysconfig.override_out_of_range"
+            if isinstance(exc, OutOfRange)
+            else "sysconfig.override_uncoercible"
+        )
        if (s.key, raw) not in _coerce_warned:
            _coerce_warned.add((s.key, raw))
            log.warning(
-                "a stored setting could not be coerced; the default is used instead",
-                extra=logs.event(
-                    "sysconfig.override_uncoercible", key=s.key, reason=type(exc).__name__
-                ),
+                "a stored setting is not usable; the default is used instead",
+                extra=logs.event(event, key=s.key, reason=type(exc).__name__),
            )
        return _default(s)

@@ -43,7 +43,7 @@ from app.downloads.jobdb import (
    _staging_dir,
 )
 from app.downloads.status import STOPPED_BY_ROUTE, JobStatus
-from app.models import DownloadJob, MediaAsset
+from app.models import DISPLAY_TEXT_MAX, DownloadJob, MediaAsset

 log = logs.get_logger(__name__)
 _stop = threading.Event()
@@ -562,7 +562,7 @@ def _finish_from_cache(job_id: int, asset_id: int) -> None:
            fields = {"status": JobStatus.DONE, "progress": 100, "phase": None}
            if not job.display_name and asset.title:
                # display_name is VARCHAR(255); a title can be longer (e.g. a recipe in the title).
-                fields["display_name"] = asset.title[:255]
+                fields["display_name"] = asset.title[:DISPLAY_TEXT_MAX]
            asset.last_access_at = datetime.now(timezone.utc)
            # Atomic finalize: only marks the job done while it is still running, so a concurrent
            # cancel/pause is never resurrected (see service.finalize_if_running).
@@ -0,0 +1,31 @@
+// The backend type-check lane (E27 S3) — the gate's ninth lane, and the first thing that has ever
+// type-checked the ~36k lines of `app/`. Read as JSONC: pyright accepts comments here.
+//
+// basedpyright, not mypy: measured on this tree with the dependencies actually installed, both land
+// ~190-200 errors with the same distribution, so the choice was made on the things that differ —
+// basedpyright is ~2x faster, needs no MYPYPATH to resolve our `app.*` imports, and has a FIRST-CLASS
+// baseline (`--writebaseline`), which is the whole ratchet. mypy would have needed a third-party tool
+// for that.
+//
+// It runs in the pytest test image, never on the host: `requirements.lock` cannot be installed on
+// Windows at all (uvloop refuses to build there), so a host run would type-check against absent
+// third-party packages and report nonsense. The version is pinned in requirements-dev.txt, which the
+// image installs — so the lane's version IS the pin, with no host-vs-pin check to drift.
+//
+// `pythonVersion` is not free-standing: `/.python-version` is the single source of truth and
+// `tests/test_python_engine_contract.py` fails this gate if this file, the two Dockerfiles, the CI
+// container or ruff's target-version disagree with it.
+//
+// `include` covers `alembic` for the same reason the ruff lane was widened to it: migrations run on
+// every container start, so one that raises there crash-loops prod, and "it is generated code" is
+// not an argument when the generated code is what boots the system. `tests/` is deliberately OUT —
+// a test's job is to fail loudly when it is wrong, which is the opposite of the silent runtime
+// failure this lane exists to catch, and annotating fixtures to a checker's satisfaction is churn
+// the ratchet exists to avoid.
+{
+  "include": ["app", "alembic"],
+  "extraPaths": ["."],
+  "typeCheckingMode": "basic",
+  "pythonVersion": "3.12",
+  "pythonPlatform": "Linux"
+}
@@ -4,6 +4,10 @@
 # backend lint lane runs on the host (the gate fails when the host's ruff is not this one). httpx2:
 # Starlette 1.x's TestClient is built on it (`import httpx2 as httpx`) and only falls back to the
 # app's own httpx with a deprecation warning on every run.
+# basedpyright: the backend type-check lane (E27 S3). Pinned like everything else here — a type
+# checker whose version floats silently changes what "clean" means, and the ratchet baseline it
+# writes is keyed to the diagnostics THIS version produces.
+basedpyright==1.40.1
 pytest==8.4.2
 ruff==0.15.21
 httpx2==2.13.0
@@ -47,7 +47,6 @@ pydantic-settings==2.15.0
 pydantic==2.13.4
 pydantic_core==2.46.4
 python-dotenv==1.2.3
-python-multipart==0.0.32
 requests==2.34.2
 rich==15.0.0
 starlette==1.6.0
@@ -1,7 +1,4 @@
 fastapi>=0.115,<1.0
-# Multipart form parsing — required by Starlette/FastAPI to accept file uploads (UploadFile/Form).
-# The download center's local-file Upload (E7) is the only multipart endpoint in the app.
-python-multipart>=0.0.9,<1.0
 uvicorn[standard]>=0.30,<1.0
 sqlalchemy>=2.0,<2.1
 psycopg[binary]>=3.2,<4.0
@@ -7,6 +7,10 @@
 # the repo wrap at the same width, and it's the width `ruff format` enforces (gated via
 # `ruff format --check` alongside `ruff check`).
 line-length = 100
+# The interpreter this code actually runs on, so ruff judges syntax and upgrade hints against the
+# right one. Left unset it falls back to a default that has nothing to do with us. `/.python-version`
+# is the single source of truth; tests/test_python_engine_contract.py holds this to it.
+target-version = "py312"

 [lint]
 # Beyond the default set, the rules that hold a LOG LINE to what E22.5 makes of it:
@@ -15,6 +15,7 @@ tests that COMMIT (the whole point of this lane — transaction-ownership behavi

 import os
 import shutil
+from urllib.parse import quote

 import pytest
 from alembic import command
@@ -248,6 +249,27 @@ def as_user(db, override_dep, _configured):
    return _as


+@pytest.fixture
+def upload_headers():
+    """Build the headers `POST /api/downloads/upload` takes since P1.
+
+    Shared, because two test modules drive that route and a second copy of this is exactly the drift
+    that lets the wire shape change in one place only. The body IS the file now; the names ride as
+    percent-encoded headers (`quote` mirrors the client's `encodeURIComponent`, since headers are
+    latin-1 and a Hungarian filename would not survive raw)."""
+
+    def _headers(filename: str, display_name: str | None = None) -> dict[str, str]:
+        headers = {
+            "content-type": "application/octet-stream",
+            "x-upload-filename": quote(filename),
+        }
+        if display_name is not None:
+            headers["x-upload-display-name"] = quote(display_name)
+        return headers
+
+    return _headers
+
+
@pytest.fixture(autouse=True)
 def _reset_rate_limiters():
    """Every RateLimiter is a module-level singleton keyed by client IP, and TestClient always
@@ -100,7 +100,7 @@ def test_the_single_playlist_repull_shares_the_pull_cooldown(db, as_user, make_u
    db.commit()
    monkeypatch.setattr(plroutes, "has_read_scope", lambda u: True)
    monkeypatch.setattr(plroutes, "repull_playlist", lambda d, u, p: {"ok": True})
-    monkeypatch.setattr(plroutes, "sync_user_playlists", lambda d, u: {"ok": True})
+    monkeypatch.setattr(plroutes, "pull_user_playlists", lambda d, u: {"ok": True})

    c = as_user(user)
    codes = [c.post(f"/api/playlists/{pl.id}/revert-youtube").status_code for _ in range(4)]
@@ -0,0 +1,705 @@
+"""SEC-20 — the global request-body cap (`app/bodylimit.py`).
+
+Two halves, deliberately kept apart:
+
+* the MIDDLEWARE tests drive a toy ASGI app, so they pin the mechanism (declared length, counted
+  bytes, the exemption match) with no router, no auth and no database in the way;
+* the APP tests drive the real application, so they pin that the middleware is actually wired in,
+  sits ahead of the auth dependencies, and refuses in the same shape `capped_body` does.
+
+The pair that matters most is "an oversized body is refused" together with "a normal body still
+gets through": the first alone would pass just as well if the cap refused *everything*.
+"""
+
+import ast
+import json
+import pathlib
+
+import pytest
+from fastapi.testclient import TestClient
+from starlette.requests import Request
+
+from app import bodylimit, debugsession, sysconfig
+from app.config import settings
+from app.models import SystemConfig
+from app.bodylimit import DEFAULT_MAX_BODY_BYTES, BodyLimitMiddleware
+from app.routes import diagnostics as diagnostics_routes
+
+SMALL = b"x" * 16
+OVER = b"x" * (DEFAULT_MAX_BODY_BYTES + 1)
+
+
+async def _reading_app(scope, receive, send):
+    """A toy app that reads the whole body the way a route does, then reports its length.
+
+    It uses a real Starlette `Request`, so the faked `http.disconnect` reaches it as the real
+    ClientDisconnect a real handler would see — the middleware's exception path is exercised, not
+    stubbed around.
+    """
+    body = await Request(scope, receive).body()
+    payload = json.dumps({"read": len(body)}).encode()
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 200,
+            "headers": [(b"content-type", b"application/json")],
+        }
+    )
+    await send({"type": "http.response.body", "body": payload})
+
+
+def _client(**kwargs) -> TestClient:
+    return TestClient(BodyLimitMiddleware(_reading_app, **kwargs))
+
+
+def _chunks(total: int, size: int = 64 * 1024):
+    """A body with NO Content-Length: httpx sends an iterator chunked, which is exactly the shape a
+    declared-length check cannot see."""
+    sent = 0
+    while sent < total:
+        n = min(size, total - sent)
+        yield b"x" * n
+        sent += n
+
+
+# --- the mechanism ------------------------------------------------------------------------------
+
+
+def test_a_declared_length_over_the_cap_is_refused_without_reading_the_body():
+    r = _client().post("/anything", content=OVER)
+    assert r.status_code == 413
+    assert r.content == bodylimit.TOO_LARGE_BODY
+
+
+def test_a_body_under_the_cap_is_passed_through_untouched():
+    # The mutation guard for the test above: if the cap refused everything, this would fail.
+    r = _client().post("/anything", content=SMALL)
+    assert r.status_code == 200
+    assert r.json() == {"read": len(SMALL)}
+
+
+def test_a_chunked_body_is_refused_on_the_COUNTED_bytes():
+    # No Content-Length at all, so the only thing that can stop this is counting as it arrives.
+    r = _client().post("/anything", content=_chunks(DEFAULT_MAX_BODY_BYTES + 64 * 1024))
+    assert r.status_code == 413
+    assert r.content == bodylimit.TOO_LARGE_BODY
+
+
+def test_a_chunked_body_under_the_cap_still_arrives_whole():
+    size = DEFAULT_MAX_BODY_BYTES - 1
+    r = _client().post("/anything", content=_chunks(size))
+    assert r.status_code == 200
+    assert r.json() == {"read": size}
+
+
+def test_an_understated_content_length_does_not_buy_a_pass():
+    # The declared-length check is the cheap half; a client that lies must still be counted out.
+    r = _client().post("/anything", content=OVER, headers={"content-length": "10"})
+    assert r.status_code == 413
+
+
+def test_exactly_at_the_cap_is_allowed():
+    size = DEFAULT_MAX_BODY_BYTES
+    r = _client(limit=size).post("/anything", content=b"x" * size)
+    assert r.status_code == 200
+    assert r.json() == {"read": size}
+
+
+# --- the per-route ceilings ---------------------------------------------------------------------
+
+BIG = {("POST", "/api/things/{tid}/blob"): DEFAULT_MAX_BODY_BYTES * 4}
+
+
+def test_a_route_with_a_raised_ceiling_may_send_a_body_over_the_global_cap():
+    r = _client(routes=BIG).post("/api/things/abc/blob", content=OVER)
+    assert r.status_code == 200
+    assert r.json() == {"read": len(OVER)}
+
+
+def test_a_raised_ceiling_is_still_a_ceiling():
+    """The difference between this and an exemption, and the reason the list is a mapping: a route
+    that needs more bytes does not thereby get unlimited bytes. Left uncounted, the upload route
+    would let an ANONYMOUS caller stream without bound — FastAPI parses a declared body before the
+    first dependency, so `require_human` has not run yet when the bytes land."""
+    over = b"x" * (BIG[("POST", "/api/things/{tid}/blob")] + 1)
+    r = _client(routes=BIG).post("/api/things/abc/blob", content=over)
+    assert r.status_code == 413
+    assert r.content == bodylimit.TOO_LARGE_BODY
+
+
+def test_a_raised_ceiling_counts_a_chunked_body_too():
+    cap = BIG[("POST", "/api/things/{tid}/blob")]
+    r = _client(routes=BIG).post("/api/things/abc/blob", content=_chunks(cap + 64 * 1024))
+    assert r.status_code == 413
+
+
+def test_the_raised_ceiling_is_scoped_to_its_method_and_its_path():
+    client = _client(routes=BIG)
+    # Same path, different method.
+    assert client.put("/api/things/abc/blob", content=OVER).status_code == 413
+    # A neighbour that merely starts the same way.
+    assert client.post("/api/things/abc/blob/extra", content=OVER).status_code == 413
+
+
+def test_a_path_parameter_cannot_swallow_a_slash():
+    # `{tid}` matching greedily across `/` would hand the raised ceiling to routes without one.
+    mw = BodyLimitMiddleware(_reading_app, routes={("POST", "/a/{tid}/b"): 99})
+    assert mw.limit_for("POST", "/a/one/b") == 99
+    assert mw.limit_for("POST", "/a/one/two/b") == DEFAULT_MAX_BODY_BYTES
+
+
+def test_every_request_gets_a_finite_ceiling():
+    """There is no pass-through path. A route that is not listed gets the default; one that is
+    listed gets its own; nothing is simply not counted."""
+    mw = BodyLimitMiddleware(_reading_app)
+    assert mw.limit_for("GET", "/api/anything") == DEFAULT_MAX_BODY_BYTES
+    for (method, template), cap in bodylimit.ROUTE_MAX_BODY_BYTES.items():
+        assert cap > DEFAULT_MAX_BODY_BYTES  # the admission rule: raised, never lowered
+        assert mw.limit_for(method, template.replace("{sid}", "abc")) == cap
+
+
+def _declared_routes(root) -> set[tuple[str, str]]:
+    """Every (method, path template) the app serves.
+
+    It has to RECURSE: since FastAPI 0.141 / Starlette 1.6 an `include_router` leaves an opaque
+    `_IncludedRouter` in `app.routes` and keeps the real routes under its `original_router`, instead
+    of flattening them into the parent as older versions did. Reading `app.routes` alone finds 35
+    entries and none of ours; walking the tree finds all 252.
+    """
+    found: set[tuple[str, str]] = set()
+    stack = [root]
+    while stack:
+        node = stack.pop()
+        for route in getattr(node, "routes", ()) or ():
+            inner = getattr(route, "original_router", None)
+            if inner is not None:
+                stack.append(inner)
+                continue
+            for method in getattr(route, "methods", None) or ():
+                found.add((method, route.path))
+    return found
+
+
+@pytest.mark.parametrize(("method", "template"), sorted(bodylimit.ROUTE_MAX_BODY_BYTES))
+def test_every_listed_template_still_resolves_to_a_real_route(method, template):
+    """The drift guard. The list names route templates that live in another file; a renamed route
+    must fail the gate here, not lose its allowance silently in production."""
+    from app.main import app
+
+    assert (method, template) in _declared_routes(app)
+
+
+def test_the_default_ceiling_clears_the_largest_body_a_default_route_takes():
+    """The headroom the module's docblock claims, held as a RATIO rather than as a figure in prose.
+    The client log sink caps itself at 512 KiB — below the default, which is why it is not listed:
+    the global ceiling never fires on it and raising it could only widen what it accepts.
+
+    `<=` alone would not hold the claim. The docblock calls the 2x margin load-bearing precisely
+    because a ceiling that refuses a legitimate request is a worse bug than the one this module
+    fixes, and a margin of 1x is no margin at all.
+    """
+    assert diagnostics_routes.BODY_MAX_BYTES * 2 <= DEFAULT_MAX_BODY_BYTES
+    assert not any(
+        path.startswith("/api/diagnostics") for _, path in bodylimit.ROUTE_MAX_BODY_BYTES
+    )
+
+
+# Every body-reading call site in the routers, as (module, function, limit expression). A route that
+# reads its own body declares the size it MEANS to accept; if that is above the global default and
+# its route is not in ROUTE_MAX_BODY_BYTES, this middleware refuses a request the route would have
+# taken — silently, in production, on a path nobody tested. The point of the list is the third entry.
+#
+# BOTH helpers, not just `capped_body`: P1 added `capped_stream_to` as its sibling and the registry
+# did not follow, so the upload route — the one this whole invariant was written for — was the one
+# site the drift guard could not see (deep-review round 1). The names come from `_common.py` itself
+# below, so a THIRD sibling cannot be added without this list noticing either — and a route that
+# skips the helpers altogether and awaits `request.body()` lands here as `<no ceiling declared>`
+# rather than vanishing (round 3).
+#
+# The module is the path relative to `app/routes/`, so a site under `plex/` is spelled
+# `plex/admin.py` and cannot collide with the top-level `admin.py`.
+CAPPED_BODY_SITES = {
+    ("diagnostics.py", "_parsed_events", "capped_body", "BODY_MAX_BYTES"),
+    ("debug_sessions.py", "_image_body", "capped_body", "debugsession.SCREENSHOT_MAX_BYTES"),
+    ("downloads.py", "spool_upload", "capped_stream_to", "cap"),
+}
+
+
+def _body_readers() -> set[str]:
+    """The names of the body-reading helpers `_common.py` exports — asked of the module rather than
+    listed here, so adding a fourth one cannot quietly leave the registry below behind."""
+    common = pathlib.Path(__file__).resolve().parents[1] / "app" / "routes" / "_common.py"
+    tree = ast.parse(common.read_text("utf-8"), filename=str(common))
+    return {
+        node.name
+        for node in tree.body
+        if isinstance(node, (ast.AsyncFunctionDef, ast.FunctionDef))
+        and node.name.startswith("capped_")
+    }
+
+
+def test_the_registry_covers_every_body_reading_helper():
+    """The mutation guard for the tests below: if a helper were renamed or added, the site list
+    would still match itself while the new one went uncovered."""
+    assert _body_readers() == {"capped_body", "capped_stream_to"}, (
+        "routes/_common.py grew or renamed a body-reading helper — add its call sites to "
+        "CAPPED_BODY_SITES and this expectation."
+    )
+
+
+# The ways a route can read its own body WITHOUT one of `_common.py`'s helpers. Every `Request`
+# parameter under `app/routes/` is named `request`, so the base name is an exact filter and not a
+# guess — the only other `.json()` in the package is `exc.json()` on a ValidationError.
+#
+# Without this set the three guards below know only the `capped_*` naming convention, which means
+# they are blind to the shape `_common.py` itself is written in. A route spelling `await
+# request.body()` inline declares no ceiling, hands no connection back, and would be invisible to
+# all three — reading as "no new sites" rather than as a failure, which is the exact way a drift
+# guard dies quietly (deep-review round 3).
+RAW_BODY_READS = {"body", "stream", "form", "json"}
+
+
+def _call_name(node: ast.Call) -> str | None:
+    if isinstance(node.func, ast.Attribute):
+        return node.func.attr
+    return getattr(node.func, "id", None)
+
+
+def _body_read_calls(fn: ast.AST, readers: set[str]) -> list[tuple[ast.Call, str]]:
+    """Every call inside `fn` that reads the request body, as (node, name) in source order."""
+    out: list[tuple[ast.Call, str]] = []
+    for node in ast.walk(fn):
+        if not isinstance(node, ast.Call):
+            continue
+        if (
+            isinstance(node.func, ast.Attribute)
+            and isinstance(node.func.value, ast.Name)
+            and node.func.value.id == "request"
+            and node.func.attr in RAW_BODY_READS
+        ):
+            out.append((node, f"request.{node.func.attr}"))
+        elif _call_name(node) in readers:
+            out.append((node, _call_name(node) or ""))
+    return sorted(out, key=lambda pair: (pair[0].lineno, pair[0].col_offset))
+
+
+def _body_reading_functions() -> dict[tuple[str, str], dict]:
+    """Every function under `app/routes/` that reads a request body itself, keyed by
+    (module, function).
+
+    Parsed, not grepped. A regex over the call text has to guess how the arguments are spelled, and
+    the shapes it guesses wrong — a bare `4 * 1024 * 1024`, a parameter not named `request` — are
+    the natural ways the NEXT site gets written, so a miss reads as "no new sites" rather than as a
+    failure. `ast` sees every call whatever it looks like.
+
+    Keyed by the ENCLOSING FUNCTION, not just the module: a set keyed by module and limit
+    expression collapses two call sites that spell their limit the same way, which is exactly what
+    a second route copied from the first would do.
+
+    The module half of the key is the path RELATIVE to `app/routes/`, not the basename: the scan
+    recurses, and `admin.py`, `discover.py` and `playlists.py` each exist both at the top level and
+    under `plex/`. Keying by basename would let the second of a colliding pair overwrite the first
+    and take its `releases` flag out of the comparison with it — the same entry-collapse this
+    registry was widened to close.
+
+    `_common.py` is skipped: it is where the helpers live, so its own `request.stream()` loops are
+    the implementation of the rule rather than a violation of it.
+    """
+    readers = _body_readers()
+    routes_dir = pathlib.Path(__file__).resolve().parents[1] / "app" / "routes"
+    found: dict[tuple[str, str], dict] = {}
+    for py in sorted(routes_dir.rglob("*.py")):
+        if py.name == "_common.py":
+            continue
+        module = py.relative_to(routes_dir).as_posix()
+        tree = ast.parse(py.read_text("utf-8"), filename=str(py))
+        for fn in ast.walk(tree):
+            if not isinstance(fn, (ast.AsyncFunctionDef, ast.FunctionDef)):
+                continue
+            calls = _body_read_calls(fn, readers)
+            if not calls:
+                continue
+            names = [name for _, name in calls]
+            limits = []
+            for node, name in zip([n for n, _ in calls], names):
+                if name.startswith("request."):
+                    limits.append("<no ceiling declared>")
+                    continue
+                limit = next((kw.value for kw in node.keywords if kw.arg == "limit"), None)
+                if limit is None:
+                    pos = 2 if name == "capped_stream_to" else 1
+                    limit = node.args[pos] if len(node.args) > pos else None
+                limits.append(ast.unparse(limit) if limit is not None else "<none>")
+            # POSITION, not presence. `any(...)` over the function accepted a release that ran
+            # AFTER the await it exists to precede — the natural spelling for someone reading the
+            # name as "release it when you're done" — while pinning a connection for the whole
+            # transfer. The first body read is what the release has to beat.
+            releases = [
+                node
+                for node in ast.walk(fn)
+                if isinstance(node, ast.Call) and _call_name(node) == "release_read_connection"
+            ]
+            first_read = calls[0][0].lineno
+            found[(module, fn.name)] = {
+                "helpers": names,
+                "limits": limits,
+                "releases": any(node.lineno < first_read for node in releases),
+                "releases_late": bool(releases)
+                and not any(node.lineno < first_read for node in releases),
+            }
+    return found
+
+
+def test_every_body_reading_site_is_known_and_fits_under_its_ceiling():
+    found = {
+        (module, fn, site["helpers"][i], site["limits"][i])
+        for (module, fn), site in _body_reading_functions().items()
+        for i in range(len(site["helpers"]))
+    }
+    assert found == CAPPED_BODY_SITES, (
+        f"a body-reading call site appeared, moved or changed shape: {found ^ CAPPED_BODY_SITES}. "
+        "Each one declares a body size; check it against bodylimit.DEFAULT_MAX_BODY_BYTES and, if "
+        "it is larger, add its route to bodylimit.ROUTE_MAX_BODY_BYTES — then update this list."
+    )
+    # And the known ones really do satisfy the rule.
+    assert diagnostics_routes.BODY_MAX_BYTES <= DEFAULT_MAX_BODY_BYTES
+    assert debugsession.SCREENSHOT_MAX_BYTES > DEFAULT_MAX_BODY_BYTES
+    assert ("POST", "/api/debug-sessions/{sid}/screenshots") in bodylimit.ROUTE_MAX_BODY_BYTES
+    # The upload site's limit is the sysconfig knob, which is bounded BY the edge ceiling rather
+    # than being a constant to compare against — that pairing is its own test below.
+    assert ("POST", "/api/downloads/upload") in bodylimit.ROUTE_MAX_BODY_BYTES
+
+
+def test_release_read_connection_ends_the_transaction_it_was_called_for(db):
+    """The helper itself: a SELECT has autobegun, and afterwards it has not."""
+    from sqlalchemy import select
+
+    from app.db import release_read_connection
+
+    db.execute(select(SystemConfig).limit(1))
+    assert db.in_transaction(), "nothing autobegan, so this test would pass vacuously"
+    release_read_connection(db)
+    assert not db.in_transaction()
+
+
+def test_release_read_connection_refuses_to_discard_pending_work(db):
+    """The precondition, ENFORCED rather than described.
+
+    The session belongs to the whole request, not to the dependency calling this — so if something
+    ahead of it ever stages a write, ending the transaction would throw that write away with
+    nothing in the log. `service.enqueue` already learned that a whole-session rollback takes the
+    caller's pending work with it, which is why it uses a SAVEPOINT. A comment cannot stop the next
+    dependency from being added in the wrong place; this can.
+    """
+    from app.db import release_read_connection
+
+    db.add(SystemConfig(key="probe_pending_write", value="1"))
+    with pytest.raises(RuntimeError, match="pending work"):
+        release_read_connection(db)
+    db.rollback()  # the staged row is this test's own
+
+
+def test_release_read_connection_refuses_to_discard_a_FLUSHED_write(db):
+    """The half the unit-of-work check cannot see.
+
+    `db.new`/`dirty`/`deleted` empty out the moment a helper flushes, and CLAUDE.md's canonical
+    split is "the handler commits; helpers flush" — so the single most likely future violator is
+    the one shape the obvious check is blind to. Measured before the fix: all three sets empty, the
+    guard silent, the row gone after the rollback.
+    """
+    from app.db import release_read_connection
+
+    db.add(SystemConfig(key="probe_flushed_write", value="1"))
+    db.flush()
+    assert not (db.new or db.dirty or db.deleted), (
+        "the flush did not clear the unit-of-work, so this test would pass for the wrong reason"
+    )
+    with pytest.raises(RuntimeError, match="already WRITTEN"):
+        release_read_connection(db)
+    db.rollback()
+
+
+def test_release_read_connection_refuses_to_discard_a_core_dml_write(db):
+    """The other half: `db.execute(update(...))` never enters the unit-of-work at all, and
+    `downloads/service.py` writes that way on purpose (a conditional `UPDATE … WHERE status=…` is
+    the honest-states pattern)."""
+    from sqlalchemy import insert
+
+    from app.db import release_read_connection
+
+    db.execute(insert(SystemConfig).values(key="probe_core_dml", value="1"))
+    assert not (db.new or db.dirty or db.deleted), (
+        "Core DML entered the unit-of-work, so this test would pass for the wrong reason"
+    )
+    with pytest.raises(RuntimeError, match="already WRITTEN"):
+        release_read_connection(db)
+    db.rollback()
+
+
+def test_every_body_reading_site_hands_its_pooled_connection_back_first():
+    """Reading the body yourself is what makes a request SLOW inside its own database session.
+
+    The auth (or ownership) dependency that must resolve first is a SELECT, so SQLAlchemy has
+    autobegun and the session is holding one of the pool's connections; awaiting the body then pins
+    it for as long as the client keeps sending — one connection per in-flight upload, `idle in
+    transaction`, with nothing to time it out. `db.release_read_connection` ends that transaction,
+    and every one of these sites needs it.
+
+    Held generically because the three sites arrived one at a time and only the newest was fixed:
+    a fourth body-reading route gets the same requirement automatically.
+
+    BEFORE the read, not merely somewhere in the function. A release that runs after the await
+    satisfies the letter of the rule and none of its purpose — the connection was held for exactly
+    the span the rule exists to protect — so `releases_late` is reported as its own, louder case.
+    """
+    sites = _body_reading_functions()
+    late = [f"{module}:{fn}" for (module, fn), site in sites.items() if site["releases_late"]]
+    missing = [
+        f"{module}:{fn}"
+        for (module, fn), site in sites.items()
+        if not site["releases"] and not site["releases_late"]
+    ]
+    assert not late, (
+        "a route calls db.release_read_connection AFTER it reads the body, which holds the pooled "
+        f"connection for exactly the transfer it was supposed to free: {late}. Move the call above "
+        "the await."
+    )
+    assert not missing, (
+        "a route reads its own request body while still inside its read transaction, pinning a "
+        f"pooled connection for the whole transfer: {missing}. Call "
+        "db.release_read_connection(db) before the await — see routes/downloads.py:spool_upload."
+    )
+
+
+def test_the_upload_ceiling_and_the_admin_knob_cannot_drift_apart():
+    """The upload route's in-handler cap is a `sysconfig` value an admin can change; the edge is a
+    constant. If the knob could be set above the edge, an admin raising it would silently start
+    getting 413s from a layer the admin page never mentions.
+
+    Since P1 the two count the SAME bytes — the body is the file, with no multipart envelope
+    wrapped round it — so the old allowance is gone and the edge is the knob's own maximum,
+    exactly. A gap reappearing means someone re-wrapped the upload in an envelope without saying so.
+
+    Equality also means the EDGE is what answers on a default install, where no override has lowered
+    the knob: the declared-length check refuses before a byte is read. That is not a gap to close
+    with headroom (measured: headroom only moves the boundary by its own size, and the route's drain
+    pushes the count back over it) — it is a refusal the client has to be able to read, which is why
+    `errors.tooLarge` exists and why the dialog checks the file against `upload_max_bytes` first.
+    """
+    spec = next(s for s in sysconfig.SPECS if s.key == "download_upload_max_bytes")
+    edge = bodylimit.ROUTE_MAX_BODY_BYTES[("POST", "/api/downloads/upload")]
+    assert spec.max == edge
+
+
+def _route_objects(root):
+    """`_declared_routes`' sibling, keeping the route OBJECT so its FastAPI dependant can be read."""
+    found: dict[tuple[str, str], object] = {}
+    stack = [root]
+    while stack:
+        node = stack.pop()
+        for route in getattr(node, "routes", ()) or ():
+            inner = getattr(route, "original_router", None)
+            if inner is not None:
+                stack.append(inner)
+                continue
+            for method in getattr(route, "methods", None) or ():
+                found[(method, route.path)] = route
+    return found
+
+
+@pytest.mark.parametrize(("method", "template"), sorted(bodylimit.ROUTE_MAX_BODY_BYTES))
+def test_no_route_with_a_raised_ceiling_declares_a_body_parameter(method, template):
+    """P1's invariant, and the reason this is a test rather than a comment.
+
+    A raised ceiling is only honest when the route's own cap applies to the bytes AS THEY ARRIVE.
+    FastAPI reads and spools a DECLARED body (`= File(...)`, `= Form(...)`, a Pydantic model)
+    BEFORE the first dependency resolves — so on such a route this middleware's ceiling is the only
+    thing between an anonymous caller and the whole allowance, `require_human` never gets a say, and
+    the route's in-handler cap measures bytes that have already landed. That is exactly what P1
+    closed on the upload route, which sat in `ROUTE_MAX_BODY_BYTES` with a 500 MiB ceiling and a
+    `file: UploadFile = File(...)` body for one release.
+
+    Asked of FastAPI itself rather than parsed or grepped: the router already knows which parameters
+    it will read the body for, and a shape a regex or an AST walk guesses wrong is precisely how the
+    next route slips through.
+
+    `route.body_field`, NOT `route.dependant.body_params`, and the difference is the whole test.
+    `body_params` holds only the parameters of the route's OWN callable; `body_field` is built from
+    `_get_flat_body_params`, which recurses into sub-dependencies — and that is also what FastAPI
+    itself consults when it decides to read the body. Measured on the pinned FastAPI: a body declared
+    inside a sub-dependency leaves `body_params` EMPTY while the body is still read in full before
+    auth, so the first version of this test was green over a reproduction of the very defect it
+    exists to forbid (deep-review round 1). The upload route's own idiom — a body read from a
+    `yield` dependency — is exactly the shape that would have slipped through."""
+    from app.main import app
+
+    route = _route_objects(app).get((method, template))
+    assert route is not None, f"{method} {template} is not a route any more"
+    assert route.body_field is None, (
+        f"{method} {template} declares a body ({route.body_field.name}) on the route or in one of "
+        "its dependencies, so FastAPI reads it before the first dependency runs and the raised "
+        "ceiling is all that stands between an anonymous caller and the whole allowance. Read the "
+        "body yourself, from a dependency declared AFTER the auth one — see "
+        "routes/downloads.py:spool_upload."
+    )
+
+
+def test_a_stored_override_outside_the_bounds_falls_back_on_READ(db):
+    """`set_value` refuses an out-of-range int, but neither bound has always been what it is now —
+    the upload knob had no `max` before SEC-20 and its `min` was 0 before E7 — so a value that was
+    legal when it was written can be sitting in the database. Served as-is it is exactly the drift
+    the test above forbids: the route would accept bytes the edge refuses.
+
+    The fallback is the env default and a warning, NOT a clamp. A clamp is a silent rewrite, and on
+    the min side it would be a wrong one: a stored 0 meant "no per-file cap" to the route, and
+    clamped to 1 it becomes a one-byte cap that kills uploads with nothing in the log.
+    """
+    spec = next(s for s in sysconfig.SPECS if s.key == "download_upload_max_bytes")
+    assert spec.max is not None and spec.min is not None
+    default = settings.download_upload_max_bytes
+
+    row = SystemConfig(key="download_upload_max_bytes", value=str(spec.max * 4))
+    db.add(row)
+    db.commit()
+    assert sysconfig.get_int(db, "download_upload_max_bytes") == default
+
+    row.value = "0"  # the legacy "no per-file cap", now below min
+    db.commit()
+    assert sysconfig.get_int(db, "download_upload_max_bytes") == default
+
+    # An override that IS in range must still be honoured — otherwise a bounds predicate written
+    # backwards would make every override inert and the two assertions above could not tell.
+    # Deliberately not `spec.max`: that equals the env default for this key, so the assertion would
+    # be satisfied by the fallback it is meant to rule out.
+    row.value = str(spec.max - 1)
+    db.commit()
+    assert spec.max - 1 != default
+    assert sysconfig.get_int(db, "download_upload_max_bytes") == spec.max - 1
+
+
+def test_the_cap_sits_inside_the_response_decorators_and_outside_the_setup_gate():
+    """The registration order, held in code rather than in the comment beside it. `add_middleware`
+    inverts the reading order (last registered = OUTERMOST), which is exactly the kind of thing a
+    prose description gets backwards — it already did once.
+
+    The layers are named, not counted by class: all four `@app.middleware("http")` decorators —
+    including the setup gate, which must be INSIDE — register as the same `BaseHTTPMiddleware`, so a
+    class-shaped assertion passes for every arrangement anyone would plausibly get wrong.
+
+    Outside the cap: only response decorators, so the 413 is dressed like any other answer. Inside
+    it: everything that does work on the caller's behalf — the setup gate opens a DB session per
+    request while an instance is unconfigured, which is the anonymous pre-auth work SEC-20 exists to
+    remove.
+    """
+    from app.main import app
+
+    def layer(m) -> str:
+        dispatch = m.kwargs.get("dispatch") if m.kwargs else None
+        return dispatch.__name__ if dispatch is not None else getattr(m.cls, "__name__", str(m.cls))
+
+    names = [layer(m) for m in app.user_middleware]  # outer → inner
+    i = names.index("BodyLimitMiddleware")
+    assert set(names[:i]) <= {
+        "log_requests",
+        "security_headers",
+        "static_cache_headers",
+        "CORSMiddleware",
+    }, f"something that is not a response decorator sits outside the cap: {names[:i]}"
+    assert "log_requests" in names[:i], "the access log must stay outside, so a 413 is logged"
+    assert "setup_gate" in names[i + 1 :], "the setup gate must not run for an oversized body"
+    assert "SessionMiddleware" in names[i + 1 :]
+
+
+def test_the_screenshot_ceiling_matches_the_cap_the_route_itself_enforces():
+    assert debugsession.SCREENSHOT_MAX_BYTES > DEFAULT_MAX_BODY_BYTES
+    assert (
+        bodylimit.ROUTE_MAX_BODY_BYTES[("POST", "/api/debug-sessions/{sid}/screenshots")]
+        == debugsession.SCREENSHOT_MAX_BYTES
+    )
+
+
+# --- the real application -----------------------------------------------------------------------
+
+
+def test_the_global_refusal_carries_the_baseline_security_headers():
+    """The 413 is a response like any other, so it has to be dressed like one. The middleware sits
+    INSIDE the security-header and CORS layers for exactly this reason: a refusal a browser drops
+    for a missing header is indistinguishable from a network failure, and the user would be shown a
+    generic error instead of the translated `too_large`.
+
+    A bare TestClient on purpose, not the `client` fixture: this is the only test that exercises the
+    middleware ORDER, and that fixture is DB-gated — so on a host without Postgres the one assertion
+    holding the move would have skipped while the file still reported green. The refusal never
+    reaches a database; it is answered above the router.
+    """
+    from app.main import app
+
+    r = TestClient(app).post(
+        "/auth/password-login", content=OVER, headers={"content-type": "text/plain"}
+    )
+    assert r.status_code == 413
+    assert r.headers.get("x-content-type-options") == "nosniff"
+    assert "referrer-policy" in r.headers
+
+
+def test_the_login_route_is_refused_before_a_single_dependency_runs(client, monkeypatch):
+    """`/auth/password-login` is the reason SEC-20 exists: it is anonymous, it declares a body, and
+    FastAPI reads that body in full before the first dependency. `_login_limiter.allow` is the very
+    first statement of the handler, so it is the sharpest available proof that nothing ran."""
+    from app.routes import auth as auth_routes
+
+    reached = False
+
+    def _record(*args, **kwargs):
+        nonlocal reached
+        reached = True
+        return True
+
+    monkeypatch.setattr(auth_routes._login_limiter, "allow", _record)
+
+    r = client.post("/auth/password-login", content=OVER, headers={"content-type": "text/plain"})
+    assert r.status_code == 413
+    assert not reached, "the handler ran — the cap is inside the router instead of ahead of it"
+
+
+def test_a_normal_login_body_still_reaches_the_handler(client, monkeypatch):
+    """The mutation check for the test above. If the cap refused every body, the 413 test would
+    pass while the app was broken; this one would not."""
+    from app.routes import auth as auth_routes
+
+    reached = False
+
+    def _record(*args, **kwargs):
+        nonlocal reached
+        reached = True
+        return True
+
+    monkeypatch.setattr(auth_routes._login_limiter, "allow", _record)
+
+    r = client.post("/auth/password-login", json={"email": "nobody@example.com", "password": "x"})
+    assert r.status_code == 401
+    assert reached
+
+
+def test_the_global_refusal_is_byte_identical_to_the_per_route_one(db, as_user, make_user):
+    """Two shapes for one fact is how the `cancelled`/`canceled` bug happened. The log sink caps
+    itself with `capped_body`; its 413 and the middleware's must be the same bytes.
+
+    Signed in on purpose: `current_user` resolves before the body dependency, so an anonymous call
+    would be answered 401 and never reach the per-route cap this compares against. The body is over
+    the SINK's 512 KiB but under the global 1 MiB, so it is `capped_body` that refuses it.
+    """
+    user = make_user()
+    db.commit()
+    over_the_sink = b"x" * (diagnostics_routes.BODY_MAX_BYTES + 1)
+    assert len(over_the_sink) < DEFAULT_MAX_BODY_BYTES
+    r = as_user(user).post(
+        "/api/diagnostics/events",
+        content=over_the_sink,
+        headers={"content-type": "application/json"},
+    )
+    assert r.status_code == 413
+    # RAW BYTES, not parsed JSON: the two used to differ by the two spaces `json.dumps` puts in by
+    # default and `JSONResponse` does not, and a structural comparison could not see it — which is
+    # the only kind of drift the docblock's promise was ever at risk from.
+    assert r.content == bodylimit.TOO_LARGE_BODY
@@ -0,0 +1,143 @@
+"""A channel's metadata is fetched again once it is stale, not only the first time it is seen.
+
+Banners, avatars, descriptions and counts change on YouTube, and an old banner URL stops resolving:
+a channel that kept the metadata of the day it was first imported showed a dead banner forever. The
+subscription import and the channel page both refresh what is older than `DETAILS_MAX_AGE`, and
+leave fresh metadata alone (each refresh spends quota). DB lane.
+"""
+
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from app.models import Channel, Subscription
+from app.routes import channels
+from app.sync import subscriptions
+from app.sync.subscriptions import DETAILS_MAX_AGE, import_subscriptions
+
+NOW = datetime.now(timezone.utc)
+FRESH = NOW - timedelta(days=1)
+STALE = NOW - DETAILS_MAX_AGE - timedelta(hours=1)
+
+
+def _item(cid: str) -> dict:
+    return {
+        "id": cid,
+        "snippet": {"title": f"{cid} renamed", "publishedAt": "2010-01-01T00:00:00Z"},
+        "brandingSettings": {"image": {"bannerExternalUrl": f"https://yt3.example/{cid}-new"}},
+    }
+
+
+def _youtube(asked: list[list[str]], subscribed: list[str], gone: tuple[str, ...] = ()):
+    class _Client:
+        def __init__(self, db, user):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *exc):
+            return False
+
+        def iter_subscriptions(self):
+            for cid in subscribed:
+                yield {"channel_id": cid, "title": cid, "yt_subscription_id": f"sub-{cid}"}
+
+        def get_channels(self, ids):
+            asked.append(sorted(ids))
+            # A terminated / deleted channel is simply absent from `channels.list`'s answer.
+            return [_item(cid) for cid in ids if cid not in gone]
+
+    return _Client
+
+
+def _channel(db, cid: str, synced: datetime | None) -> None:
+    db.add(
+        Channel(
+            id=cid,
+            title=cid,
+            banner_url=f"https://yt3.example/{cid}-old",
+            published_at=datetime(2010, 1, 1, tzinfo=timezone.utc),
+            details_synced_at=synced,
+        )
+    )
+
+
+def test_the_import_refreshes_stale_and_missing_details_and_leaves_fresh_ones(
+    db, make_user, monkeypatch
+):
+    user = make_user()
+    _channel(db, "UCfresh", FRESH)
+    _channel(db, "UCstale", STALE)
+    _channel(db, "UCnever", None)
+    db.flush()
+    for cid in ("UCfresh", "UCstale", "UCnever"):
+        db.add(Subscription(user_id=user.id, channel_id=cid))
+    db.commit()
+    asked: list[list[str]] = []
+    monkeypatch.setattr(
+        subscriptions, "YouTubeClient", _youtube(asked, ["UCfresh", "UCstale", "UCnever"])
+    )
+
+    result = import_subscriptions(db, user)
+
+    assert asked == [["UCnever", "UCstale"]]
+    assert result["channels_detailed"] == 2
+    stale = db.get(Channel, "UCstale")
+    assert stale is not None
+    assert stale.banner_url == "https://yt3.example/UCstale-new"
+    assert stale.details_synced_at is not None and stale.details_synced_at > STALE
+    fresh = db.get(Channel, "UCfresh")
+    assert fresh is not None and fresh.banner_url == "https://yt3.example/UCfresh-old"
+
+
+@pytest.mark.parametrize(("synced", "refreshed"), [(STALE, True), (FRESH, False)])
+def test_the_channel_page_refreshes_a_stale_channel_only(
+    db, make_user, monkeypatch, synced, refreshed
+):
+    user = make_user()
+    _channel(db, "UCpage", synced)
+    db.commit()
+    asked: list[list[str]] = []
+    monkeypatch.setattr(channels, "YouTubeClient", _youtube(asked, []))
+
+    body = channels.channel_detail("UCpage", user=user, db=db)
+
+    assert asked == ([["UCpage"]] if refreshed else [])
+    suffix = "new" if refreshed else "old"
+    assert body["banner_url"] == f"https://yt3.example/UCpage-{suffix}"
+
+
+def test_a_channel_youtube_no_longer_returns_is_not_asked_for_on_every_view(
+    db, make_user, monkeypatch
+):
+    """A terminated channel is missing from `channels.list`'s answer, so nothing was stamped and the
+    channel page asked for it again (1 quota unit) on every single view. The miss is stamped like a
+    fetch, so the next ask waits for `DETAILS_MAX_AGE` like any other channel."""
+    user = make_user()
+    db.add(Channel(id="UCgone", title="UCgone"))
+    db.commit()
+    asked: list[list[str]] = []
+    monkeypatch.setattr(channels, "YouTubeClient", _youtube(asked, [], gone=("UCgone",)))
+
+    channels.channel_detail("UCgone", user=user, db=db)
+    channels.channel_detail("UCgone", user=user, db=db)
+
+    assert asked == [["UCgone"]]
+
+
+def test_the_import_stamps_a_channel_youtube_no_longer_returns(db, make_user, monkeypatch):
+    user = make_user()
+    _channel(db, "UCgone", STALE)
+    db.flush()
+    db.add(Subscription(user_id=user.id, channel_id="UCgone"))
+    db.commit()
+    asked: list[list[str]] = []
+    monkeypatch.setattr(
+        subscriptions, "YouTubeClient", _youtube(asked, ["UCgone"], gone=("UCgone",))
+    )
+
+    import_subscriptions(db, user)
+    import_subscriptions(db, user)
+
+    assert asked == [["UCgone"]]
@@ -786,6 +786,7 @@ class FakeGitea:
        self.redirect = False  # an http:// address behind a proxy that sends it to https
        self.garbage_asset = False  # a 2xx that is not the API's answer (a proxy's page)
        self.patched_body: str | None = None
+        self.markdown_payloads: list[dict] = []  # what the preview asked the tracker to render

    def handler(self, request: httpx.Request) -> httpx.Response:
        path = request.url.path.removeprefix("/api/v1")
@@ -826,6 +827,7 @@ class FakeGitea:
            self.patched_body = json.loads(request.content)["body"]
            return httpx.Response(201, json={"number": 7})
        if request.method == "POST" and path == "/markdown":
+            self.markdown_payloads.append(json.loads(request.content))
            return httpx.Response(200, text="<h3>Steps</h3>")
        return httpx.Response(404, json={"message": "not found"})

@@ -1180,6 +1182,20 @@ def test_the_preview_is_the_trackers_own_rendering(gitea_fake, db, make_user, as
    assert stranger.post(f"/api/debug-sessions/{sid}/issue").status_code == 404


+def test_the_preview_never_asks_the_tracker_for_a_repository_context(
+    gitea_fake, db, make_user, as_user
+):
+    """A `Context` makes Gitea hunt for commit links, and on the API's render path that hunt
+    dereferences a nil checker: the tracker's whole process segfaults. Every report carries a
+    hex-shaped id, so the payload — not the text — is what has to stay safe (measured against
+    1.26.4 / 1.27.1, fixed upstream in 1.27.3; a self-hoster's version is not ours to pick)."""
+    owner = as_user(make_user())
+    sid = _start(owner)["id"]
+    text = "| tab | 5645b1c0ae01 |"
+    assert owner.post(f"/api/debug-sessions/{sid}/preview", json={"text": text}).status_code == 200
+    assert gitea_fake.markdown_payloads == [{"Text": text, "Mode": "gfm"}]
+
+
 def test_the_admin_connection_test_names_what_is_wrong(gitea_fake, db, make_user, as_user):
    admin = as_user(make_user(role="admin"))
    r = admin.post("/api/admin/config/test-issues")
@@ -0,0 +1,105 @@
+"""E28 S3e2 — adding a video 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
+also overwrite any change another tab made in between. Positions can have gaps after removals, so
+the position is an index over the ORDERED rows, and the list is renumbered around it.
+"""
+
+from datetime import datetime, timezone
+
+from app.models import Channel, Playlist, PlaylistItem, Video
+
+
+def _seed(db, user, ids, *, positions=None, **kw):
+    db.add(Channel(id="UCtest", title="Test"))
+    now = datetime.now(timezone.utc)
+    for v in [*ids, "vX"]:
+        db.add(Video(id=v, channel_id="UCtest", published_at=now))
+    pl = Playlist(user_id=user.id, name="L", **kw)
+    db.add(pl)
+    db.flush()
+    for i, vid in enumerate(ids):
+        db.add(PlaylistItem(playlist_id=pl.id, video_id=vid, position=(positions or range(99))[i]))
+    db.commit()
+    return pl
+
+
+def _ids(db, pl_id):
+    db.expire_all()
+    return [
+        r.video_id
+        for r in db.execute(
+            PlaylistItem.__table__.select()
+            .where(PlaylistItem.playlist_id == pl_id)
+            .order_by(PlaylistItem.position)
+        ).all()
+    ]
+
+
+def _add(client, pl_id, body):
+    return client.post(f"/api/playlists/{pl_id}/items", json=body)
+
+
+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})
+    assert r.status_code == 200
+    assert _ids(db, pl.id) == ["a", "vX", "b", "c"]
+
+
+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})
+    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})
+    assert _ids(db, pl.id) == ["a", "b", "vX"]
+
+
+def test_no_position_still_appends(db, make_user, as_user):
+    user = make_user()
+    pl = _seed(db, user, ["a", "b"])
+    _add(as_user(user), pl.id, {"video_id": "vX"})
+    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.
+    user = make_user()
+    pl = _seed(db, user, ["a", "b", "c"])
+    _add(as_user(user), pl.id, {"video_id": "c", "position": 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})
+    assert r.status_code == 422
+    assert _ids(db, pl.id) == ["a"]
+
+
+def test_putting_a_removed_video_back_leaves_a_linked_list_clean(db, make_user, as_user):
+    # Remove + undo is no change at all: a YouTube-linked list must not stay "unsynced" after it.
+    user = make_user()
+    pl = _seed(db, user, ["a", "b", "c"], yt_playlist_id="PLx")
+    client = as_user(user)
+    from app.sync.playlists import current_fingerprint
+
+    pl.synced_fingerprint = current_fingerprint(db, pl)
+    pl.dirty = False
+    db.commit()
+    client.delete(f"/api/playlists/{pl.id}/items/b")
+    db.expire_all()
+    assert db.get(Playlist, pl.id).dirty is True
+    _add(client, pl.id, {"video_id": "b", "position": 1})
+    db.expire_all()
+    assert db.get(Playlist, pl.id).dirty is False
@@ -13,6 +13,9 @@ Two properties are load-bearing and neither is visible from the happy path alone

 from datetime import datetime, timedelta, timezone

+import pytest
+from sqlalchemy.exc import OperationalError
+
 from app.models import Channel, Playlist, PlaylistItem, Video


@@ -269,12 +272,12 @@ def test_a_target_that_already_had_it_is_not_recently_changed(db, make_user, as_
    assert db.get(Playlist, dst.id).updated_at == old


-def test_a_concurrent_add_to_the_target_lands_as_the_already_present_move(
-    db, make_user, as_user, monkeypatch
-):
-    """The already-in-target check is a read, not a lock: another tab's add (or the scheduler's
-    YouTube merge) can commit the same video to the target in between, and the re-parent then
-    hits uq_playlist_video. That is the idempotent outcome arriving late — not a raw 500."""
+def test_no_add_can_land_in_the_target_while_a_move_holds_it(db, make_user):
+    """The already-in-target check is a read; it holds because the move locks both lists first and
+    an insert into the target — another tab's add, a YouTube merge — needs the target row for its
+    foreign key, so it waits for the move's commit instead of hitting uq_playlist_video under it."""
+    from sqlalchemy import text
+
    from app.db import SessionLocal
    from app.routes import playlists as plroutes

@@ -282,16 +285,10 @@ def test_a_concurrent_add_to_the_target_lands_as_the_already_present_move(
    _seed_videos(db, ["v1"])
    src = _playlist(db, user, "Source", ["v1"])
    dst = _playlist(db, user, "Target", [])
-    real = plroutes._next_item_position
-
-    def add_first(session, playlist_id):
-        with SessionLocal() as other:  # the other tab, committing between check and re-parent
-            other.add(PlaylistItem(playlist_id=dst.id, video_id="v1", position=0))
-            other.commit()
-        return real(session, playlist_id)
-
-    monkeypatch.setattr(plroutes, "_next_item_position", add_first)
-    assert _move(as_user(user), src.id, "v1", dst.id).status_code == 200
-    db.expire_all()
-    assert _ids(db, src.id) == []
-    assert _ids(db, dst.id) == ["v1"]
+    plroutes.lock_playlists(db, src.id, dst.id)  # what the move holds until its commit
+    with SessionLocal() as other:
+        other.execute(text("SET LOCAL lock_timeout = '300ms'"))
+        other.add(PlaylistItem(playlist_id=dst.id, video_id="v1", position=0))
+        with pytest.raises(OperationalError, match="lock timeout"):
+            other.flush()
+    db.rollback()
@@ -0,0 +1,262 @@
+"""E28 review — every request that reads a playlist's item positions and writes new ones locks the
+playlist row first.
+
+Without it two adds (two tabs; the rail and the page) both read the same `max(position)` and land
+on one position, and a reorder racing an add collides with it — the list's order between the two
+rows is then whatever the planner returns. A true two-connection race is not reproducible on
+demand, so the test holds the mechanism: the parent row is taken `FOR UPDATE` by each such route.
+A Plex reorder that omits a row (added in another tab meanwhile) must not collide with it either.
+
+Round 2: the lock also comes FIRST — before the request reads or writes a single item row. A remove
+that deleted an item and then touched the playlist beside a reorder that went the other way was a
+deadlock (a 500 for one of them), and an add that checked "already there?" before the lock let two
+adds of one video both insert (a 500 on the unique key).
+"""
+
+import re
+from datetime import datetime, timezone
+
+import pytest
+from sqlalchemy import event
+
+from app.models import (
+    Channel,
+    Playlist,
+    PlaylistItem,
+    PlexItem,
+    PlexLibrary,
+    PlexPlaylist,
+    PlexPlaylistItem,
+    Video,
+)
+
+
+@pytest.fixture
+def locks(db):
+    """The tables each request took a row lock on (`SELECT … FROM <t> … FOR UPDATE`)."""
+    seen: list[str] = []
+
+    def _record(conn, cursor, statement, *_):
+        if "FOR UPDATE" in statement:
+            seen.extend(re.findall(r"FROM\s+(\w+)", statement)[:1])
+
+    engine = db.get_bind()
+    event.listen(engine, "before_cursor_execute", _record)
+    yield seen
+    event.remove(engine, "before_cursor_execute", _record)
+
+
+@pytest.fixture
+def statements(db):
+    """Every statement a request ran, in order."""
+    seen: list[str] = []
+
+    def _record(conn, cursor, statement, *_):
+        seen.append(" ".join(statement.split()))
+
+    engine = db.get_bind()
+    event.listen(engine, "before_cursor_execute", _record)
+    yield seen
+    event.remove(engine, "before_cursor_execute", _record)
+
+
+def _locked_before_items(seen: list[str], parent: str, items: str) -> str | None:
+    """The first statement touching `items` must come after a `FOR UPDATE` of `parent`; returns
+    that lock statement (None when it came too late or never)."""
+    lock = None
+    for st in seen:
+        if lock is None and "FOR UPDATE" in st and re.search(rf"FROM {parent}\b", st):
+            lock = st
+        if re.search(rf"\b{items}\b", st):
+            return lock
+    return lock
+
+
+def _yt(db, user):
+    db.add(Channel(id="UCtest", title="Test"))
+    now = datetime.now(timezone.utc)
+    for v in ("v1", "v2", "v3"):
+        db.add(Video(id=v, channel_id="UCtest", published_at=now))
+    pl = Playlist(user_id=user.id, name="L")
+    other = Playlist(user_id=user.id, name="M")
+    db.add_all([pl, other])
+    db.flush()
+    db.add(PlaylistItem(playlist_id=pl.id, video_id="v1", position=0))
+    db.commit()
+    return pl.id, other.id
+
+
+def _plex(db, user):
+    lib = PlexLibrary(plex_key="p1", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    items = [PlexItem(rating_key=rk, library_id=lib.id, kind="movie", title=rk) for rk in "abcd"]
+    db.add_all(items)
+    pl = PlexPlaylist(user_id=user.id, title="L")
+    db.add(pl)
+    db.flush()
+    for i, it in enumerate(items[:3]):
+        db.add(PlexPlaylistItem(playlist_id=pl.id, item_id=it.id, position=i))
+    db.commit()
+    return pl.id
+
+
+YT = Playlist.__table__.name
+PLEX = PlexPlaylist.__table__.name
+
+
+@pytest.mark.parametrize(
+    "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}
+        ),
+        lambda c, pid, other: c.put(f"/api/playlists/{pid}/order", json={"video_ids": ["v1"]}),
+    ],
+    ids=["add", "add-at", "watch-later", "move", "reorder"],
+)
+def test_a_youtube_playlist_write_locks_the_playlist(db, make_user, as_user, locks, call):
+    user = make_user()
+    pid, other = _yt(db, user)
+    r = call(as_user(user), pid, other)
+    assert r.status_code == 200, r.text
+    assert YT in locks
+
+
+@pytest.mark.parametrize(
+    "call",
+    [
+        lambda c, pid: c.post(f"/api/plex/playlists/{pid}/items", json={"item_rating_key": "d"}),
+        lambda c, pid: c.post(
+            f"/api/plex/playlists/{pid}/items/bulk", json={"item_rating_keys": ["d"]}
+        ),
+        lambda c, pid: c.post(
+            f"/api/plex/playlists/{pid}/items/bulk",
+            json={"item_rating_keys": ["d"], "positions": [0]},
+        ),
+        lambda c, pid: c.put(
+            f"/api/plex/playlists/{pid}/order", json={"item_rating_keys": ["c", "b", "a"]}
+        ),
+    ],
+    ids=["add", "bulk", "bulk-at", "reorder"],
+)
+def test_a_plex_playlist_write_locks_the_playlist(db, make_user, as_user, locks, call):
+    user = make_user()
+    pid = _plex(db, user)
+    r = call(as_user(user), pid)
+    assert r.status_code == 200, r.text
+    assert PLEX in locks
+
+
+def test_a_plex_reorder_that_omits_a_row_does_not_collide_with_it(db, make_user, as_user):
+    """The row "a" was added in another tab after this page loaded its order ["c", "b"]: it keeps
+    its place after the given rows instead of sharing position 0 with "c"."""
+    user = make_user()
+    pid = _plex(db, user)
+    r = as_user(user).put(f"/api/plex/playlists/{pid}/order", json={"item_rating_keys": ["c", "b"]})
+    assert r.status_code == 200
+    db.expire_all()
+    rows = db.query(PlexPlaylistItem).filter_by(playlist_id=pid).all()
+    by_id = {it.id: it.rating_key for it in db.query(PlexItem).all()}
+    got = sorted((r.position, by_id[r.item_id]) for r in rows)
+    assert got == [(0, "c"), (1, "b"), (2, "a")]
+
+
+YT_ITEMS = PlaylistItem.__table__.name
+PLEX_ITEMS = PlexPlaylistItem.__table__.name
+
+
+@pytest.mark.parametrize(
+    "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}
+        ),
+        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}"),
+    ],
+    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
+):
+    user = make_user()
+    pid, other = _yt(db, user)
+    c = as_user(user)
+    statements.clear()
+    r = call(c, pid, other)
+    assert r.status_code == 200, r.text
+    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."""
+    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}
+    )
+    assert r.status_code == 200, r.text
+    lock = _locked_before_items(statements, YT, YT_ITEMS)
+    assert lock and "ORDER BY" in lock, lock
+    # BOTH lists in that one statement: one bound id per list in its IN (…) (a single-id lock
+    # renders the same IN and ORDER BY)
+    listed = re.search(r" IN \((.*?)\) ORDER BY", lock)
+    assert listed and len(re.findall(r"%\(\w+\)s", listed.group(1))) == 2, lock
+
+
+def test_watch_later_add_and_remove_lock_it_before_any_item(db, make_user, as_user, statements):
+    user = make_user()
+    _yt(db, user)
+    c = as_user(user)
+    assert c.post("/api/playlists/watch-later", json={"video_id": "v2"}).status_code == 200
+    statements.clear()
+    assert c.post("/api/playlists/watch-later", json={"video_id": "v2"}).status_code == 200
+    assert _locked_before_items(statements, YT, YT_ITEMS), statements
+    statements.clear()
+    assert c.delete("/api/playlists/watch-later/v2").status_code == 200
+    assert _locked_before_items(statements, YT, YT_ITEMS), statements
+
+
+def test_a_rename_locks_the_playlist(db, make_user, as_user, locks):
+    """A rename moves `dirty`, which the scheduled mirror refresh re-reads under this lock."""
+    user = make_user()
+    pid, _ = _yt(db, user)
+    r = as_user(user).patch(f"/api/playlists/{pid}", json={"name": "New"})
+    assert r.status_code == 200, r.text
+    assert YT in locks
+
+
+@pytest.mark.parametrize(
+    "call",
+    [
+        lambda c, pid: c.delete(f"/api/plex/playlists/{pid}/items/a"),
+        lambda c, pid: c.post(
+            f"/api/plex/playlists/{pid}/items/remove-bulk", json={"item_rating_keys": ["a", "b"]}
+        ),
+        lambda c, pid: c.post(f"/api/plex/playlists/{pid}/items", json={"item_rating_key": "a"}),
+    ],
+    ids=["remove", "remove-bulk", "add-present"],
+)
+def test_a_plex_item_write_locks_the_playlist_before_any_item(
+    db, make_user, as_user, statements, call
+):
+    user = make_user()
+    pid = _plex(db, user)
+    c = as_user(user)
+    statements.clear()
+    r = call(c, pid)
+    assert r.status_code == 200, r.text
+    assert _locked_before_items(statements, PLEX, PLEX_ITEMS), statements
@@ -0,0 +1,210 @@
+"""E28 review C1 — one YouTube sync of a playlist at a time, whoever starts it.
+
+A push reads YouTube and then writes both sides for seconds, committing step by step, so the
+client's in-flight flag (one page's menus) and a row lock (gone at the first commit) both leave two
+tabs, or a push and the scheduled mirror refresh, free to interleave. The claim is an advisory lock
+on a connection of its own; the test holds it from outside, the way a second request would.
+"""
+
+from sqlalchemy import text
+
+from app.auth import require_write_scope
+from app.db import SessionLocal
+from app.models import Playlist
+from app.routes import playlists as plroutes
+from app.sync import playlists as plsync
+
+
+def _linked(db, user, *, source="local"):
+    pl = Playlist(user_id=user.id, name="L", source=source, yt_playlist_id="PL123")
+    db.add(pl)
+    db.commit()
+    return pl
+
+
+class FakeYT:
+    """YouTube as far as these routes read it: two playlists, none with items."""
+
+    def __init__(self, *_):
+        pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        return False
+
+    def iter_my_playlists(self):
+        return [{"id": "PL123", "title": "Renamed"}, {"id": "PL999", "title": "New"}]
+
+    def iter_my_playlist_video_ids(self, _ytid):
+        return []
+
+    def iter_playlist_items_with_ids(self, _ytid):
+        return []
+
+    def get_playlist_snippet(self, _ytid):
+        return {}
+
+
+def test_push_and_revert_refuse_while_the_list_is_claimed(
+    db, as_user, make_user, override_dep, monkeypatch
+):
+    user = make_user()
+    pl = _linked(db, user)
+    override_dep(require_write_scope, lambda: user)
+    monkeypatch.setattr(plroutes, "has_read_scope", lambda u: True)
+    ran: list[str] = []
+    monkeypatch.setattr(plroutes, "YouTubeClient", FakeYT)
+    monkeypatch.setattr(plroutes, "plan_merge", lambda d, u, p, live: {"units_estimate": 0})
+    monkeypatch.setattr(plroutes, "merge_playlist", lambda d, u, p, live: ran.append("push") or {})
+    monkeypatch.setattr(plroutes, "repull_playlist", lambda d, u, p: ran.append("revert") or {})
+    c = as_user(user)
+
+    with plsync.sync_claim(db, pl.id) as free:
+        assert free
+        for path in ("push", "revert-youtube"):
+            r = c.post(f"/api/playlists/{pl.id}/{path}")
+            assert r.status_code == 409
+            assert r.json()["detail"] == {"code": "playlist", "reason": "sync_busy"}
+        # a delete too: a push mid-way would plan the deleted list as emptied (E28 round 4)
+        r = c.delete(f"/api/playlists/{pl.id}")
+        assert r.status_code == 409
+        assert r.json()["detail"] == {"code": "playlist", "reason": "sync_busy"}
+    assert ran == []
+    assert db.get(Playlist, pl.id) is not None
+
+    # Released on the way out: the same list syncs again, and a claim is per list.
+    assert c.post(f"/api/playlists/{pl.id}/push").status_code == 200
+    assert c.post(f"/api/playlists/{pl.id}/revert-youtube").status_code == 200
+    assert ran == ["push", "revert"]
+
+
+def test_a_claim_is_released_when_its_block_raises(db, make_user):
+    pl = _linked(db, make_user())
+    try:
+        with plsync.sync_claim(db, pl.id) as free:
+            assert free
+            raise RuntimeError("boom")
+    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).
+    held = db.scalar(
+        text("SELECT count(*) FROM pg_locks WHERE locktype = 'advisory' AND objid = :id"),
+        {"id": pl.id},
+    )
+    assert held == 0
+
+
+def test_a_claim_draws_no_connection_from_the_app_pool(db, make_user):
+    """A claim is held for a whole push beside the request's pooled session; drawn from the pool
+    too, a burst of pushes ran it dry and stalled every other request for pool_timeout."""
+    from app.db import engine
+
+    pl = _linked(db, make_user())
+    before = engine.pool.checkedout()
+    with plsync.sync_claim(db, pl.id) as free:
+        assert free
+        assert engine.pool.checkedout() == before
+
+
+def test_the_scheduled_refresh_skips_a_mirror_being_synced(db, make_user, monkeypatch):
+    user = make_user()
+    busy = _linked(db, user, source="youtube")
+    replaced: list[int] = []
+
+    monkeypatch.setattr(plsync, "has_read_scope", lambda u: True)
+    monkeypatch.setattr(plsync, "YouTubeClient", FakeYT)
+    monkeypatch.setattr(
+        plsync, "_replace_items_from_youtube", lambda d, p, ids: replaced.append(p.id)
+    )
+
+    with plsync.sync_claim(db, busy.id):
+        out = plsync.sync_user_playlists(db, user)
+
+    assert out == {"synced": 1}
+    assert busy.id not in replaced and len(replaced) == 1
+    db.refresh(busy)
+    assert busy.name == "L"
+
+
+def test_refused_reverts_do_not_spend_the_pull_cooldown(
+    db, as_user, make_user, override_dep, monkeypatch
+):
+    """Round 2: the cooldown (three pulls per ten minutes) is checked after the claim, so clicking
+    Revert while a push runs is refused as busy without using up a pull."""
+    user = make_user()
+    pl = _linked(db, user)
+    monkeypatch.setattr(plroutes, "has_read_scope", lambda u: True)
+    monkeypatch.setattr(plroutes, "repull_playlist", lambda d, u, p: {})
+    c = as_user(user)
+    with plsync.sync_claim(db, pl.id):
+        for _ in range(4):
+            assert c.post(f"/api/playlists/{pl.id}/revert-youtube").status_code == 409
+    assert c.post(f"/api/playlists/{pl.id}/revert-youtube").status_code == 200
+
+
+def test_a_bulk_pull_runs_once_per_user_at_a_time(db, as_user, make_user, monkeypatch):
+    """Two bulk pulls at once both saw a YouTube list unmirrored and each created its mirror."""
+    user = make_user()
+    monkeypatch.setattr(plsync, "has_read_scope", lambda u: True)
+    monkeypatch.setattr(plroutes, "has_read_scope", lambda u: True)
+    monkeypatch.setattr(plsync, "YouTubeClient", FakeYT)
+    monkeypatch.setattr(plsync, "_replace_items_from_youtube", lambda d, p, ids: None)
+    c = as_user(user)
+    with plsync.user_sync_claim(db, user.id):
+        assert plsync.sync_user_playlists(db, user) == {"synced": 0, "reason": "busy"}
+        for _ in range(4):
+            r = c.post("/api/playlists/sync-youtube")
+            assert r.status_code == 409
+            assert r.json()["detail"] == {"code": "playlist", "reason": "sync_all_busy"}
+    assert c.post("/api/playlists/sync-youtube").json() == {"ok": True, "synced": 2}
+
+
+def test_a_gone_mirror_is_deleted_even_when_no_list_refreshes(db, make_user, monkeypatch):
+    """Every remaining mirror has unpushed edits, so nothing below the deletion commits."""
+    user = make_user()
+    gone = Playlist(user_id=user.id, name="Gone", source="youtube", yt_playlist_id="PLgone")
+    kept = Playlist(user_id=user.id, name="K", source="youtube", yt_playlist_id="PL123", dirty=True)
+    other = Playlist(
+        user_id=user.id, name="O", source="youtube", yt_playlist_id="PL999", dirty=True
+    )
+    db.add_all([gone, kept, other])
+    db.commit()
+    gone_id = gone.id
+    monkeypatch.setattr(plsync, "has_read_scope", lambda u: True)
+    monkeypatch.setattr(plsync, "YouTubeClient", FakeYT)
+
+    assert plsync.sync_user_playlists(db, user) == {"synced": 0}
+    db.rollback()  # what the request's session close does to an uncommitted deletion
+    assert db.get(Playlist, gone_id) is None
+
+
+def test_a_mirror_edited_during_the_pull_is_not_replaced(db, make_user, monkeypatch):
+    """The loop's `dirty` is a snapshot from before the YouTube calls; a remove committed by another
+    request meanwhile must win over YouTube's order."""
+    user = make_user()
+    pl = _linked(db, user, source="youtube")
+    replaced: list[int] = []
+
+    class EditedMeanwhile(FakeYT):
+        def iter_my_playlists(self):
+            return [{"id": "PL123", "title": "Renamed"}]
+
+        def iter_my_playlist_video_ids(self, _ytid):
+            with SessionLocal() as other:
+                other.get(Playlist, pl.id).dirty = True
+                other.commit()
+            return []
+
+    monkeypatch.setattr(plsync, "has_read_scope", lambda u: True)
+    monkeypatch.setattr(plsync, "YouTubeClient", EditedMeanwhile)
+    monkeypatch.setattr(
+        plsync, "_replace_items_from_youtube", lambda d, p, ids: replaced.append(p.id)
+    )
+
+    assert plsync.sync_user_playlists(db, user) == {"synced": 0}
+    assert replaced == []
+    db.expire_all()
+    assert db.get(Playlist, pl.id).name == "L"
@@ -0,0 +1,292 @@
+"""E28 review round 3 — the YouTube sync paths take the playlist row BEFORE they touch an item, and
+hold it to the commit that writes them.
+
+Round 2 made every route edit lock the playlist first. The sync paths were left item-first (a push's
+and a re-pull's item replace, a delete's cascade), so a push beside a remove could deadlock (a 500),
+and the scheduled mirror refresh re-ingested inside its lock — its commit let go of the lock before
+the replace, so a remove made then was undone and the list read as synced. A push also replaced the
+items from a snapshot read before its YouTube calls, and marked the list clean over an edit made
+during its YouTube writes. The "other tab" here is a second session that commits while the push is
+talking to YouTube — when the push holds no lock, as a real one does not.
+"""
+
+import json
+import re
+from datetime import datetime, timezone
+
+import pytest
+from sqlalchemy import delete, event, text
+
+from app.db import SessionLocal
+from app.models import Channel, Playlist, PlaylistItem, Video
+from app.sync import playlists as pl_mod
+
+ITEMS = PlaylistItem.__table__.name
+LISTS = Playlist.__table__.name
+
+
+@pytest.fixture
+def trace(db):
+    """Every statement and every COMMIT on the test engine, in order."""
+    seen: list[str] = []
+
+    def _stmt(conn, cursor, statement, *_):
+        seen.append(" ".join(statement.split()))
+
+    def _commit(conn):
+        seen.append("COMMIT")
+
+    engine = db.get_bind()
+    event.listen(engine, "before_cursor_execute", _stmt)
+    event.listen(engine, "commit", _commit)
+    yield seen
+    event.remove(engine, "before_cursor_execute", _stmt)
+    event.remove(engine, "commit", _commit)
+
+
+def _held_to_the_item_write(seen: list[str], verb: str) -> bool:
+    """The first `<verb> … playlist_items` comes after a `FOR UPDATE` of playlists, with no COMMIT
+    in between (a commit ends the lock)."""
+    locked = False
+    for st in seen:
+        if "FOR UPDATE" in st and re.search(rf"FROM {LISTS}\b", st):
+            locked = True
+        elif st == "COMMIT":
+            locked = False
+        elif st.startswith(verb) and re.search(rf"\b{ITEMS}\b", st):
+            return locked
+    return False
+
+
+class FakeYT:
+    """YouTube for the sync paths: one playlist, its items, and ids the Data API will not return."""
+
+    def __init__(self, items, *, unavailable=(), title="Mix", on_get=None, on_add=None):
+        self.items = [(f"it{i}", v) for i, v in enumerate(items)]
+        self.unavailable = set(unavailable)
+        self.title = title
+        self.get_calls = 0
+        self._on_get = on_get
+        self._on_add = on_add
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        return False
+
+    def iter_my_playlists(self):
+        return [{"id": "PLyt", "title": self.title}]
+
+    def iter_my_playlist_video_ids(self, _pid):
+        return [v for _, v in self.items]
+
+    def iter_playlist_items_with_ids(self, _pid):
+        return [{"item_id": i, "video_id": v} for i, v in self.items]
+
+    def get_playlist_snippet(self, _pid):
+        return {"title": self.title}
+
+    def get_videos(self, ids):
+        self.get_calls += 1
+        if self._on_get:
+            self._on_get()
+        return [
+            {"id": v, "snippet": {"channelId": "UCtest", "publishedAt": "2020-01-01T00:00:00Z"}}
+            for v in ids
+            if v not in self.unavailable
+        ]
+
+    def create_playlist(self, title, *_, **__):
+        return "PLyt"
+
+    def update_playlist_title(self, _pid, title):
+        self.title = title
+
+    def add_playlist_item(self, _pid, vid, position=None):
+        if self._on_add:
+            self._on_add()
+        iid = f"it{len(self.items) + 100}"
+        self.items.append((iid, vid))
+        return iid
+
+    def delete_playlist_item(self, item_id):
+        self.items = [r for r in self.items if r[0] != item_id]
+
+    def move_playlist_item(self, item_id, _pid, _vid, position):
+        row = next(r for r in self.items if r[0] == item_id)
+        self.items.remove(row)
+        self.items.insert(position, row)
+
+
+@pytest.fixture
+def fake_yt(monkeypatch):
+    def install(fake):
+        monkeypatch.setattr(pl_mod, "YouTubeClient", lambda *_: fake)
+        return fake
+
+    return install
+
+
+def _seed(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, local, *, source="local", baseline=None):
+    pl = Playlist(
+        user_id=user.id,
+        name="Mix",
+        source=source,
+        yt_playlist_id="PLyt",
+        synced_video_ids=None if baseline is None else pl_mod._dump_ids(baseline),
+    )
+    db.add(pl)
+    db.flush()
+    for pos, v in enumerate(local):
+        db.add(PlaylistItem(playlist_id=pl.id, video_id=v, position=pos))
+    db.commit()
+    return pl
+
+
+def _other_tab(pl_id, *, add=None, remove=None, rename=None, drop=False):
+    """A second session's edit, committed at once — what another tab's request does. It runs on
+    the push's own thread: a lock the push wrongly held here would be waited on forever, so the
+    wait is bounded and a regression fails instead of hanging the gate."""
+    with SessionLocal() as s:
+        s.execute(text("SET LOCAL lock_timeout = '2s'"))
+        if drop:
+            s.execute(delete(Playlist).where(Playlist.id == pl_id))
+        if rename:
+            s.get(Playlist, pl_id).name = rename
+        if add:
+            pos = len(s.query(PlaylistItem).filter_by(playlist_id=pl_id).all())
+            s.add(PlaylistItem(playlist_id=pl_id, video_id=add, position=pos))
+        if remove:
+            s.query(PlaylistItem).filter_by(playlist_id=pl_id, video_id=remove).delete()
+        s.commit()
+
+
+def test_the_mirror_refresh_holds_its_lock_through_a_list_with_a_private_video(
+    db, make_user, fake_yt, trace
+):
+    user = make_user()
+    _seed(db, ["a"])
+    pl = _playlist(db, user, ["a"], source="youtube")
+    fake = fake_yt(FakeYT(["a", "ghost"], unavailable={"ghost"}))
+    trace.clear()
+    pl_mod.pull_user_playlists(db, user)
+    assert _held_to_the_item_write(trace, "DELETE"), trace
+    # the private video is asked for once, not again under the lock
+    assert fake.get_calls == 1
+    assert pl_mod._local_video_ids(db, pl) == ["a"]
+
+
+def test_the_mirror_drop_locks_the_list_before_its_items(db, make_user, fake_yt, trace):
+    user = make_user()
+    _seed(db, ["a"])
+    pl = _playlist(db, user, ["a"], source="youtube")
+    pl.yt_playlist_id = "PLgone"
+    db.commit()
+    fake_yt(FakeYT([]))
+    trace.clear()
+    pl_mod.pull_user_playlists(db, user)
+    assert _held_to_the_item_write(trace, "DELETE"), trace
+
+
+def test_a_repull_ingests_before_its_lock_and_holds_it_to_the_replace(
+    db, make_user, fake_yt, trace
+):
+    user = make_user()
+    _seed(db, ["a"])
+    pl = _playlist(db, user, ["a"])
+    fake = fake_yt(FakeYT(["b", "a", "ghost"], unavailable={"ghost"}, title="Renamed"))
+    trace.clear()
+    pl_mod.repull_playlist(db, user, pl)
+    assert _held_to_the_item_write(trace, "DELETE"), trace
+    assert fake.get_calls == 1
+    db.refresh(pl)
+    assert (pl.name, pl.dirty) == ("Renamed", False)
+    assert pl_mod._local_video_ids(db, pl) == ["b", "a"]
+
+
+def test_a_push_locks_the_list_before_it_replaces_the_items(db, make_user, fake_yt, trace):
+    user = make_user()
+    _seed(db, ["a", "b"])
+    pl = _playlist(db, user, ["a", "b"], baseline=["a"])
+    fake_yt(FakeYT(["a", "y"]))
+    trace.clear()
+    pl_mod.merge_playlist(db, user, pl)
+    assert _held_to_the_item_write(trace, "DELETE"), trace
+
+
+def test_an_add_made_while_a_push_reads_youtube_survives_it(db, make_user, fake_yt):
+    user = make_user()
+    _seed(db, ["a", "x"])
+    pl = _playlist(db, user, ["a"], baseline=["a"])
+    # 'y' is new on YouTube, so the push ingests it — and the other tab adds 'x' meanwhile.
+    fake = fake_yt(FakeYT(["a", "y"], on_get=lambda: _other_tab(pl.id, add="x")))
+    pl_mod.merge_playlist(db, user, pl)
+    local = pl_mod._local_video_ids(db, pl)
+    assert set(local) == {"a", "x", "y"}
+    assert "x" in [v for _, v in fake.items]  # and it reached YouTube as a local add
+
+
+@pytest.mark.parametrize("linked", [True, False], ids=["linked", "first-push"])
+def test_a_rename_made_during_a_push_s_youtube_writes_stays_dirty(db, make_user, fake_yt, linked):
+    """The closing baseline is YouTube's title, not the one the lock re-reads: over the new name it
+    matched the rename, and the list read synced with YouTube still on the old title."""
+    user = make_user()
+    _seed(db, ["a", "b"])
+    pl = _playlist(db, user, ["a", "b"], baseline=["a"] if linked else None)
+    if not linked:
+        pl.yt_playlist_id = None
+        db.commit()
+    fake = fake_yt(
+        FakeYT(["a"] if linked else [], on_add=lambda: _other_tab(pl.id, rename="Mix 2"))
+    )
+    pl_mod.merge_playlist(db, user, pl)
+    db.refresh(pl)
+    assert (pl.name, fake.title) == ("Mix 2", "Mix")
+    assert pl.dirty is True  # the rename has not reached YouTube; the list must say so
+
+
+def test_a_push_stops_at_a_list_deleted_while_it_read_youtube(db, make_user, fake_yt):
+    """A delete landing mid-push left a plan over no items: every item "removed here", so the push
+    emptied the YouTube playlist the delete meant to keep."""
+    user = make_user()
+    _seed(db, ["a", "b"])
+    pl = _playlist(db, user, ["a", "b"])
+    # a video YouTube would not return last time, retried now — the read the delete lands in
+    pl.synced_video_ids = json.dumps({"ids": ["a", "b"], "unavailable": ["ghost"]})
+    db.commit()
+    fake = fake_yt(
+        FakeYT(
+            ["a", "b", "ghost"], unavailable={"ghost"}, on_get=lambda: _other_tab(pl.id, drop=True)
+        )
+    )
+    raised = None
+    try:
+        pl_mod.merge_playlist(db, user, pl)
+    except Exception as exc:  # noqa: BLE001 — the regression raises too, AFTER its YouTube writes
+        raised = exc
+    assert [v for _, v in fake.items] == ["a", "b", "ghost"]  # YouTube untouched
+    assert isinstance(raised, pl_mod.PlaylistGone)  # which the route answers with a 404
+
+
+@pytest.mark.parametrize("linked", [True, False], ids=["linked", "first-push"])
+def test_an_edit_made_during_a_push_s_youtube_writes_stays_dirty(db, make_user, fake_yt, linked):
+    user = make_user()
+    _seed(db, ["a", "b"])
+    pl = _playlist(db, user, ["a", "b"], baseline=["a"] if linked else None)
+    if not linked:
+        pl.yt_playlist_id = None
+        db.commit()
+    fake_yt(FakeYT(["a"] if linked else [], on_add=lambda: _other_tab(pl.id, remove="a")))
+    pl_mod.merge_playlist(db, user, pl)
+    db.refresh(pl)
+    assert pl_mod._local_video_ids(db, pl) == ["b"]
+    assert pl.dirty is True  # the removal has not reached YouTube; the list must say so
@@ -0,0 +1,113 @@
+"""E28 S3e2 — putting removed Plex playlist rows back WHERE THEY WERE: the list page's "Undo".
+
+A removal can take one row, a season or a whole show, and a season's episodes need not sit together
+(a reorder inside the show interleaves them), so each key carries its own index — over the ORDERED
+rows, since positions have gaps after a removal. One request: an append plus a second reorder call
+leaves the rows at the end whenever that call fails, and would overwrite another tab's changes.
+"""
+
+from app.models import PlexItem, PlexLibrary, PlexPlaylist, PlexPlaylistItem
+
+
+def _seed(db, user, rks, *, positions=None, extra=("x", "y")):
+    lib = PlexLibrary(plex_key="p1", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    items = {}
+    for rk in [*rks, *extra]:
+        it = PlexItem(rating_key=rk, library_id=lib.id, kind="movie", title=rk.upper())
+        db.add(it)
+        items[rk] = it
+    pl = PlexPlaylist(user_id=user.id, title="L")
+    db.add(pl)
+    db.flush()
+    for i, rk in enumerate(rks):
+        pos = (positions or range(99))[i]
+        db.add(PlexPlaylistItem(playlist_id=pl.id, item_id=items[rk].id, position=pos))
+    db.commit()
+    return pl
+
+
+def _order(db, pid):
+    db.expire_all()
+    rows = db.execute(
+        PlexPlaylistItem.__table__.select()
+        .where(PlexPlaylistItem.playlist_id == pid)
+        .order_by(PlexPlaylistItem.position, PlexPlaylistItem.id)
+    ).all()
+    by_id = {it.id: it.rating_key for it in db.query(PlexItem).all()}
+    return [by_id[r.item_id] for r in rows], [r.position for r in rows]
+
+
+def _add(client, pid, keys, positions=None):
+    body = {"item_rating_keys": keys}
+    if positions is not None:
+        body["positions"] = positions
+    return client.post(f"/api/plex/playlists/{pid}/items/bulk", json=body)
+
+
+def test_one_row_goes_back_to_its_index(db, make_user, as_user):
+    user = make_user()
+    pl = _seed(db, user, ["a", "b", "c"])
+    r = _add(as_user(user), pl.id, ["x"], [1])
+    assert r.status_code == 200
+    assert r.json()["added"] == 1
+    assert _order(db, pl.id) == (["a", "x", "b", "c"], [0, 1, 2, 3])
+
+
+def test_scattered_rows_go_back_to_each_of_their_indices(db, make_user, as_user):
+    # A season whose episodes were interleaved with another season's: removed rows at 1 and 3 of
+    # a, x, b, y, c. Given in any order, each lands where it stood.
+    user = make_user()
+    pl = _seed(db, user, ["a", "b", "c"])
+    _add(as_user(user), pl.id, ["y", "x"], [3, 1])
+    assert _order(db, pl.id)[0] == ["a", "x", "b", "y", "c"]
+
+
+def test_indices_count_rows_not_stored_numbers(db, make_user, as_user):
+    user = make_user()
+    pl = _seed(db, user, ["a", "b", "c"], positions=[0, 7, 20])
+    _add(as_user(user), pl.id, ["x"], [2])
+    assert _order(db, pl.id) == (["a", "b", "x", "c"], [0, 1, 2, 3])
+
+
+def test_an_index_past_the_end_appends(db, make_user, as_user):
+    user = make_user()
+    pl = _seed(db, user, ["a"])
+    _add(as_user(user), pl.id, ["x"], [50])
+    assert _order(db, pl.id)[0] == ["a", "x"]
+
+
+def test_a_row_already_in_the_list_does_not_move(db, make_user, as_user):
+    user = make_user()
+    pl = _seed(db, user, ["a", "b", "c"])
+    r = _add(as_user(user), pl.id, ["c"], [0])
+    assert r.json()["added"] == 0
+    assert _order(db, pl.id)[0] == ["a", "b", "c"]
+
+
+def test_without_positions_it_still_appends(db, make_user, as_user):
+    user = make_user()
+    pl = _seed(db, user, ["a", "b"])
+    _add(as_user(user), pl.id, ["y", "x"])
+    assert _order(db, pl.id)[0] == ["a", "b", "y", "x"]
+
+
+def test_positions_must_pair_with_the_keys(db, make_user, as_user):
+    user = make_user()
+    pl = _seed(db, user, ["a"])
+    assert _add(as_user(user), pl.id, ["x", "y"], [0]).status_code == 422
+    assert _add(as_user(user), pl.id, ["x"], [-1]).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=())
+    client = as_user(user)
+    client.post(
+        f"/api/plex/playlists/{pl.id}/items/remove-bulk", json={"item_rating_keys": ["b", "d"]}
+    )
+    assert _order(db, pl.id)[0] == ["a", "c"]
+    _add(client, pl.id, ["b", "d"], [1, 3])
+    assert _order(db, pl.id)[0] == ["a", "b", "c", "d"]
@@ -0,0 +1,115 @@
+"""A sidecar subtitle in a legacy code page must render its accents, not U+FFFD.
+
+Found live on Arrow S03E15 (a Hungarian .srt beside the .mp4): the served WebVTT held 1391 U+FFFD and
+not one accented letter, because `_sidecar_vtt` decoded the bytes as UTF-8 with `errors="replace"`
+while the file was Windows-1250 (ő = 0xF5, ű = 0xFB). Legacy-code-page .srt files are the norm for
+Hungarian releases, and SubRip carries no charset of its own, so the stream's language is the only hint.
+No Postgres: Plex and ffmpeg are stubbed.
+"""
+
+from pathlib import Path
+from typing import cast
+
+import pytest
+from sqlalchemy.orm import Session
+
+from app.plex import subtitles
+
+HU = "1\r\n00:00:01,000 --> 00:00:02,000\r\nMiért nem szóltál? Ősz, űr.\r\n"
+FR = "1\r\n00:00:01,000 --> 00:00:02,000\r\nDéjà vu, garçon.\r\n"
+RU = "1\r\n00:00:01,000 --> 00:00:02,000\r\nПривет, мир.\r\n"
+
+
+class _Plex:
+    def __init__(self, raw: bytes):
+        self.raw = raw
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+    def raw_get(self, key: str) -> bytes:
+        return self.raw
+
+
+def _sidecar(monkeypatch, raw: bytes, lang: str | None, codec: str = "srt") -> str:
+    monkeypatch.setattr(subtitles, "PlexClient", lambda db: _Plex(raw))
+    stream = {"key": "/library/streams/1", "codec": codec, "languageCode": lang}
+    return subtitles._sidecar_vtt(cast(Session, None), stream)
+
+
+@pytest.mark.parametrize(
+    ("text", "encoding", "lang"),
+    [
+        (HU, "cp1250", "hun"),  # the file that was found broken
+        (FR, "cp1252", "fre"),  # a Western legacy file
+        (RU, "cp1251", "rus"),  # a Cyrillic one
+        (HU, "utf-8", "hun"),  # already UTF-8: untouched
+        (HU, "utf-8-sig", "hun"),  # UTF-8 with a BOM
+        (HU, "utf-16", "hun"),  # UTF-16 (carries its BOM)
+    ],
+    ids=["cp1250-hu", "cp1252-fr", "cp1251-ru", "utf8", "utf8-bom", "utf16"],
+)
+def test_a_sidecar_srt_is_decoded_in_its_own_encoding(monkeypatch, text, encoding, lang):
+    vtt = _sidecar(monkeypatch, text.encode(encoding), lang)
+    assert "\ufffd" not in vtt
+    assert vtt.startswith("WEBVTT\n\n")
+    assert text.splitlines()[2] in vtt
+
+
+def test_a_non_srt_sidecar_reaches_ffmpeg_as_utf8(monkeypatch):
+    seen: dict[str, bytes] = {}
+
+    def fake_ffmpeg(src: str, sub_ord):
+        seen["bytes"] = Path(src).read_bytes()
+        return "WEBVTT\n"
+
+    monkeypatch.setattr(subtitles, "ffmpeg_to_vtt", fake_ffmpeg)
+    _sidecar(monkeypatch, "[Events]\nDialogue: Ősz\n".encode("cp1250"), "hun", codec="ass")
+    assert seen["bytes"].decode("utf-8") == "[Events]\nDialogue: Ősz\n"
+
+
+def test_a_track_cached_before_the_encoding_fix_is_not_served(tmp_path, monkeypatch):
+    """The cache has no eviction, so a mis-decoded track would have stayed broken for good: the key
+    is versioned, and a track cached under the old one is read again (once) instead of served."""
+    monkeypatch.setattr(subtitles, "CACHE_DIR", tmp_path)
+    (tmp_path / "sub_14881_1.vtt").write_text(
+        "WEBVTT\n\n1\n00:00:01.000 --> 00:00:02.000\nAz�rt\n", "utf-8"
+    )
+    assert subtitles.cached_track("14881", 1)[0] is None
+
+
+def test_one_stray_byte_does_not_send_a_utf8_file_to_a_legacy_code_page(monkeypatch):
+    """A UTF-8 release with ONE bad byte (a cut-and-paste Windows-1252 quote) failed strict UTF-8 as a
+    whole, and the whole file was then read as Windows-1250: every correct ő/é became mojibake. Nearly
+    all of it is valid UTF-8, so it stays UTF-8 and only the one byte is replaced."""
+    raw = (HU * 20).encode("utf-8") + b"\x93quoted\x94\r\n"
+    vtt = _sidecar(monkeypatch, raw, "hun")
+    assert "Miért nem szóltál? Ősz, űr." in vtt
+    assert "MiĂ©rt" not in vtt
+
+
+def test_an_untagged_legacy_sidecar_is_read_as_central_european(monkeypatch):
+    """No language tag: the fallback was Windows-1252, which turns a Hungarian ő/ű into õ/û."""
+    vtt = _sidecar(monkeypatch, HU.encode("cp1250"), None)
+    assert "Ősz, űr." in vtt
+
+
+def test_a_latin_serbian_sidecar_is_read_as_central_european(monkeypatch):
+    """Serbian releases are overwhelmingly Latin script in Windows-1250 (like hrv/bos); read as
+    Windows-1251 every č/ć/š/ž/đ turned into Cyrillic noise."""
+    sr = "1\r\n00:00:01,000 --> 00:00:02,000\r\nŠta ćeš, đače? Čekaj.\r\n"
+    vtt = _sidecar(monkeypatch, sr.encode("cp1250"), "srp")
+    assert "Šta ćeš, đače? Čekaj." in vtt
+
+
+def test_a_track_cached_under_the_previous_decoder_is_not_served(tmp_path, monkeypatch):
+    """The decoder changed again (stray-byte UTF-8, cp1250 fallbacks): the key is versioned once more
+    so a track the old rules mis-decoded is read again instead of served for good."""
+    monkeypatch.setattr(subtitles, "CACHE_DIR", tmp_path)
+    (tmp_path / "sub2_14881_1.vtt").write_text(
+        "WEBVTT\n\n1\n00:00:01.000 --> 00:00:02.000\nAzõrt\n", "utf-8"
+    )
+    assert subtitles.cached_track("14881", 1)[0] is None
@@ -311,8 +311,9 @@ def test_covered_ranges_coalesce_and_answer_membership():
 def test_a_cached_vtt_from_an_older_build_counts_as_complete(tmp_path):
    """Before this change the cache only ever held whole tracks, and none of them has a sidecar.
    Reading one as "covers nothing" would re-extract every already-cached track after the upgrade."""
-    (tmp_path / "sub_98614_0.vtt").write_text(_vtt(_cue("00:01.000", "00:02.000", "x")), "utf-8")
-    assert subtitles.read_meta("sub_98614_0") == ([[0.0, 1_000_000_000.0]], True)
+    key = subtitles.cache_key("98614", 0)
+    (tmp_path / f"{key}.vtt").write_text(_vtt(_cue("00:01.000", "00:02.000", "x")), "utf-8")
+    assert subtitles.read_meta(key) == ([[0.0, 1_000_000_000.0]], True)


 # --- the deep-review round: the seams between the window and the full pass ----------------------
@@ -18,12 +18,12 @@ _PW = "open sesame"


@pytest.fixture
-def unlock_url(as_user, make_user, tmp_path, monkeypatch):
+def unlock_url(as_user, make_user, tmp_path, monkeypatch, upload_headers):
    monkeypatch.setattr(settings, "download_root", str(tmp_path))
    monkeypatch.setattr(probemod, "probe_media", lambda _p: ("h264", "aac", 320, 240, 5))
    owner = as_user(make_user())
    job = owner.post(
-        "/api/downloads/upload", files={"file": ("clip.mp4", b"fake-video", "video/mp4")}
+        "/api/downloads/upload", content=b"fake-video", headers=upload_headers("clip.mp4")
    )
    assert job.status_code == 200, job.text
    link = owner.post(f"/api/downloads/{job.json()['id']}/links", json={"password": _PW})
@@ -0,0 +1,66 @@
+"""The Python major is a contract, not a coincidence — the backend half (E27 S3).
+
+`0.93.2` was released to fix exactly this bug on the JavaScript side: four machines built or checked
+the app and none of them agreed on which Node they ran, the server gate went red for 73 of its last
+90 runs, and nothing told anyone. The Python side had the same shape and nobody had looked: prod
+(`Dockerfile`), the test image (`Dockerfile.test`) and CI (`check.yml`) each spelled **3.12** as an
+independent literal, there was no `.python-version`, no `requires-python`, and ruff had no
+`target-version` — while the dev machine had no 3.12 installed at all, only 3.13 and 3.14.
+
+**The contract is a chain, and it is split across two test files because no single runner can see
+every link.** This suite runs inside the test image, which mounts `backend/` and nothing else, so it
+cannot read the repo-root Dockerfile or the workflow. It therefore holds the link it CAN see, and the
+one that matters most here:
+
+    the interpreter actually running  ==  backend/pyrightconfig.json  ==  backend/ruff.toml
+
+and `frontend/src/lib/pythonEngine.contract.test.ts` — which runs on the host, with the whole tree —
+holds the rest of the chain:
+
+    /.python-version  ==  pyrightconfig.json  ==  ruff.toml  ==  Dockerfile  ==  Dockerfile.test  ==  check.yml
+
+Together they close the loop. To move the version: edit `/.python-version`, then follow the failures
+in both files. Every place they name is a place that would otherwise have been forgotten.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+BACKEND = Path(__file__).resolve().parents[1]
+
+
+def _version_in(path: Path, pattern: str) -> tuple[int, int]:
+    """The (major, minor) the given file declares. A rename or a moved line lands here — re-point
+    the test, the contract did not go away with it."""
+    text = path.read_text(encoding="utf-8")
+    match = re.search(pattern, text, re.MULTILINE)
+    assert match is not None, f"{pattern!r} not found in {path.name}"
+    return int(match.group(1)), int(match.group(2))
+
+
+# pyrightconfig.json is JSONC (it carries comments), so it is read by regex rather than json.loads.
+PINNED = _version_in(BACKEND / "pyrightconfig.json", r'"pythonVersion"\s*:\s*"(\d+)\.(\d+)"')
+
+
+def test_pins_a_plausible_python_version():
+    """Guards against a typo agreeing with nothing at all."""
+    assert PINNED >= (3, 12), PINNED
+
+
+def test_this_interpreter_is_the_pinned_one():
+    """The assertion that pays. A green suite on another minor does not mean the shipped image is
+    green — it means the suite and the image have drifted and nobody noticed yet."""
+    running = sys.version_info[:2]
+    assert running == PINNED, (
+        f"these tests are running on Python {running[0]}.{running[1]}, but the app is pinned to "
+        f"{PINNED[0]}.{PINNED[1]} (backend/pyrightconfig.json, /.python-version). The suite runs in "
+        f"the test image, so this failing means backend/Dockerfile.test has drifted from the pin."
+    )
+
+
+def test_ruff_judges_the_pinned_version():
+    """Unset, ruff falls back to a default that has nothing to do with us, and its syntax and
+    upgrade advice are then aimed at some other interpreter."""
+    major, minor = _version_in(BACKEND / "ruff.toml", r'^target-version\s*=\s*"py(\d)(\d+)"')
+    assert (major, minor) == PINNED
@@ -12,15 +12,23 @@ parsing (image → file, cover-art skip, dims, duration) is covered directly by
 below, which stubs one level down (`run_ffprobe_json`) and exercises the real `probe_media`.
 """

+import ast
+import asyncio
+import io
+import pathlib
 from pathlib import Path

 import pytest
+from fastapi import HTTPException

 from app.config import settings
+from app.routes._common import capped_stream_to
+from sqlalchemy import select
+
 from app.downloads import mediakind, quota, storage
 from app.downloads import probe as probemod
 from app.downloads import upload as uploadmod
-from app.models import DownloadQuota, MediaAsset
+from app.models import DISPLAY_TEXT_MAX, DownloadJob, DownloadQuota, MediaAsset


 # --- pure: the kind invariant ---------------------------------------------------------------
@@ -123,15 +131,143 @@ def test_ingest_rejects_over_footprint_cap_before_writing(db, make_user, _root,
    assert db.query(MediaAsset).count() == 0  # and no orphan asset row


+# --- route: the auth-first body (P1) --------------------------------------------------------
+
+
+def _counting_body(chunks: int = 4, size: int = 1024):
+    """A request body that records how much of itself the server actually pulled.
+
+    httpx's ASGI transport feeds the app lazily, one `http.request` message per yielded chunk, so a
+    chunk that was never yielded is a chunk the app never asked for. That is the whole assertion
+    below: it is not "the upload was refused", it is "the refusal happened before the bytes moved".
+    """
+    pulled: list[int] = []
+
+    def body():
+        for _ in range(chunks):
+            pulled.append(size)
+            yield b"x" * size
+
+    return body(), pulled
+
+
+_BOUNDARY = "p1boundary"
+
+
+def _counting_multipart(chunks: int = 4, size: int = 1024):
+    """The same counter, wrapped in a real multipart envelope.
+
+    The content-type is the load-bearing part. Starlette's `request.form()` returns an EMPTY
+    FormData without touching the stream when the content-type is not multipart/urlencoded — so a
+    raw-body probe cannot tell "the route stopped reading strangers" apart from "there was nothing
+    here to parse". Only a well-formed multipart body makes the old shape actually spool.
+    """
+    pulled: list[int] = []
+    head = (
+        f"--{_BOUNDARY}\r\n"
+        'Content-Disposition: form-data; name="file"; filename="clip.mp4"\r\n'
+        "Content-Type: application/octet-stream\r\n\r\n"
+    ).encode()
+    tail = f"\r\n--{_BOUNDARY}--\r\n".encode()
+
+    def body():
+        pulled.append(len(head))
+        yield head
+        for _ in range(chunks):
+            pulled.append(size)
+            yield b"x" * size
+        pulled.append(len(tail))
+        yield tail
+
+    return body(), pulled
+
+
+def test_an_anonymous_upload_is_refused_before_a_byte_of_it_is_read(client):
+    """P1 — the defect E27 bounded but did not close.
+
+    While the route declared `file: UploadFile = File(...)`, FastAPI parsed and spooled the body
+    BEFORE the first dependency ran, so `require_human` could not gate it: an unauthenticated
+    caller could make the server write the whole per-file allowance (500 MiB by default) to temp,
+    per request. SEC-20's ceiling capped the number; it could not stop the writing.
+
+    The route now reads its own body from a dependency declared AFTER the auth one, the shape
+    `POST /api/debug-sessions/{sid}/screenshots` already uses. The claim under test is the strong
+    one — a stranger's bytes are never read WHATEVER they claim to send, so the probe sends the
+    multipart the old route would have spooled, not the raw body the new one expects."""
+    body, pulled = _counting_multipart()
+    r = client.post(
+        "/api/downloads/upload",
+        content=body,
+        headers={"content-type": f"multipart/form-data; boundary={_BOUNDARY}"},
+    )
+    assert r.status_code == 401
+    assert pulled == [], f"the server read {sum(pulled)} bytes from an anonymous caller"
+
+
+def test_an_authenticated_upload_still_has_its_body_read(as_user, make_user, _root, monkeypatch):
+    """The mutation check for the test above: a route that read NOBODY's body would pass it just as
+    well as the fixed one. The same counting body, signed in, must be pulled in full."""
+    _probe(monkeypatch, (None, None, None, None, None))
+    body, pulled = _counting_body()
+    c = as_user(make_user())
+    r = c.post(
+        "/api/downloads/upload",
+        content=body,
+        headers={"content-type": "application/octet-stream", "x-upload-filename": "clip.bin"},
+    )
+    assert r.status_code == 200, r.text
+    assert sum(pulled) == 4096
+
+
+def test_capped_stream_to_drains_the_rest_before_refusing():
+    """Measured in a real browser, then pinned HERE rather than at the route.
+
+    The cap now fires while the client is still sending, and answering + closing mid-upload is what
+    a browser reports as a NETWORK failure: the dialog said "the server couldn't be reached"
+    instead of naming the limit, because XHR never got to read the 422. `capped_stream_to` reads
+    the remainder to nowhere before raising, so the client finishes sending and reads the real
+    answer.
+
+    It is asserted against the helper and not through TestClient on purpose — httpx's ASGI
+    transport pumps the request body whether or not the app reads it, so a route-level version of
+    this test passes just as happily with the drain deleted. It was written that way first and
+    caught by its own mutation check.
+    """
+    pulled = []
+
+    async def stream():
+        for i in range(8):
+            pulled.append(i)
+            yield b"x" * 1024
+
+    class _Req:
+        def stream(self):
+            return stream()
+
+    out = io.BytesIO()
+    refusal = HTTPException(status_code=422, detail={"code": "upload_too_large", "limit": 2048})
+    # `asyncio.run` rather than an async test: the suite has no async plugin, and adding one to
+    # pin four lines of helper would mean a new dev dependency and a lock regeneration.
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(capped_stream_to(_Req(), out, 2048, refusal))
+    assert exc.value is refusal
+    assert len(pulled) == 8, "the body was abandoned mid-stream, not drained"
+    # Drained means DISCARDED: nothing past the limit is written.
+    assert len(out.getvalue()) <= 2048
+
+
 # --- route ----------------------------------------------------------------------------------


-def test_upload_route_generic_forces_download(as_user, make_user, _root, monkeypatch):
+def test_upload_route_generic_forces_download(
+    as_user, make_user, _root, monkeypatch, upload_headers
+):
    _probe(monkeypatch, (None, None, None, None, None))
    c = as_user(make_user())
    r = c.post(
        "/api/downloads/upload",
-        files={"file": ("report.html", b"<script>alert(1)</script>", "text/html")},
+        content=b"<script>alert(1)</script>",
+        headers=upload_headers("report.html"),
    )
    assert r.status_code == 200, r.text
    job = r.json()
@@ -145,7 +281,7 @@ def test_upload_route_generic_forces_download(as_user, make_user, _root, monkeyp


 def test_upload_route_media_html_extension_not_served_as_html(
-    as_user, make_user, _root, monkeypatch
+    as_user, make_user, _root, monkeypatch, upload_headers
 ):
    """The XSS guard: a MEDIA-classified upload (real codecs) named with an executable extension must
    NOT be served with a guessed text/html type. The served Content-Type comes from the verified
@@ -156,7 +292,8 @@ def test_upload_route_media_html_extension_not_served_as_html(
    c = as_user(make_user())
    r = c.post(
        "/api/downloads/upload",
-        files={"file": ("evil.html", b"<script>alert(1)</script>", "text/html")},
+        content=b"<script>alert(1)</script>",
+        headers=upload_headers("evil.html"),
    )
    assert r.status_code == 200, r.text
    job = r.json()
@@ -177,7 +314,9 @@ def test_upload_route_media_html_extension_not_served_as_html(
    assert "attachment" in pr.headers["content-disposition"].lower()


-def test_public_watch_file_forces_download_for_generic_file(as_user, make_user, _root, monkeypatch):
+def test_public_watch_file_forces_download_for_generic_file(
+    as_user, make_user, _root, monkeypatch, upload_headers
+):
    """The login-free public serve of a generic upload (media_kind='file') must be a neutral
    force-download attachment — the branch that stops uploaded HTML/SVG executing on the public
    origin. This is a SEPARATE code path from the authenticated /file route, so it needs its own
@@ -186,7 +325,8 @@ def test_public_watch_file_forces_download_for_generic_file(as_user, make_user,
    c = as_user(make_user())
    job = c.post(
        "/api/downloads/upload",
-        files={"file": ("notes.html", b"<script>alert(1)</script>", "text/html")},
+        content=b"<script>alert(1)</script>",
+        headers=upload_headers("notes.html"),
    ).json()
    assert job["asset"]["media_kind"] == "file"
    link = c.post(f"/api/downloads/{job['id']}/links", json={"allow_download": True}).json()
@@ -197,7 +337,7 @@ def test_public_watch_file_forces_download_for_generic_file(as_user, make_user,


 def test_public_watch_file_serves_media_inline_with_real_type(
-    as_user, make_user, _root, monkeypatch
+    as_user, make_user, _root, monkeypatch, upload_headers
 ):
    """A recognised media container IS still served inline with its real audio/video type (so it
    plays in the watch page) — the fix must not break legitimate playback. A stream-only link →
@@ -206,7 +346,8 @@ def test_public_watch_file_serves_media_inline_with_real_type(
    c = as_user(make_user())
    job = c.post(
        "/api/downloads/upload",
-        files={"file": ("clip.mp4", b"fake-mp4-bytes", "video/mp4")},
+        content=b"fake-mp4-bytes",
+        headers=upload_headers("clip.mp4"),
    ).json()
    link = c.post(f"/api/downloads/{job['id']}/links", json={"allow_download": False}).json()
    pr = c.get(f"/api/public/watch/{link['token']}/file")
@@ -215,7 +356,9 @@ def test_public_watch_file_serves_media_inline_with_real_type(
    assert "inline" in pr.headers["content-disposition"].lower()


-def test_upload_route_enforces_per_file_cap(as_user, make_user, db, _root, monkeypatch):
+def test_upload_route_enforces_per_file_cap(
+    as_user, make_user, db, _root, monkeypatch, upload_headers
+):
    from app import sysconfig

    sysconfig.set_value(db, "download_upload_max_bytes", 5)
@@ -223,47 +366,391 @@ def test_upload_route_enforces_per_file_cap(as_user, make_user, db, _root, monke
    c = as_user(make_user())
    r = c.post(
        "/api/downloads/upload",
-        files={"file": ("big.bin", b"way over the cap", "application/octet-stream")},
+        content=b"way over the cap",
+        headers=upload_headers("big.bin"),
    )
    assert r.status_code == 422
    assert r.json()["detail"]["code"] == "upload_too_large"


+def test_the_cap_admits_a_body_of_EXACTLY_the_cap_and_refuses_one_byte_more(
+    as_user, make_user, db, _root, monkeypatch, upload_headers
+):
+    """The boundary, which the test above cannot see: it sends 16 bytes against a cap of 5, so a
+    `>` silently loosened to `>=` refuses it just the same and the mutation survives the whole
+    suite. The cap is `size > limit`, so a file of exactly the cap must be ACCEPTED.
+    """
+    from app import sysconfig
+
+    _probe(monkeypatch, (None, None, None, None, None))
+    payload = b"x" * 64
+    sysconfig.set_value(db, "download_upload_max_bytes", len(payload))
+    db.commit()
+    c = as_user(make_user())
+
+    at_the_cap = c.post(
+        "/api/downloads/upload", content=payload, headers=upload_headers("exact.bin")
+    )
+    assert at_the_cap.status_code == 200, at_the_cap.text
+
+    over = c.post(
+        "/api/downloads/upload", content=payload + b"x", headers=upload_headers("over.bin")
+    )
+    assert over.status_code == 422
+    assert over.json()["detail"] == {"code": "upload_too_large", "limit": len(payload)}
+
+
+def test_a_non_ascii_filename_survives_the_header_round_trip(
+    as_user, make_user, db, _root, monkeypatch, upload_headers
+):
+    """The percent-decoding, which every other test in this file leaves vacuous.
+
+    Headers are latin-1 on the wire, so the client `encodeURIComponent`s the name and the route
+    `unquote`s it. Every filename the suite sends is pure ASCII — and `quote()` is the IDENTITY
+    function on ASCII — so deleting the `unquote` call changes nothing anywhere else. A Hungarian
+    name is the only input that can tell the two apart: without the decode the sanitizer would be
+    handed the literal `nyaral%C3%A1s.bin` and would keep the percent-escapes in the stored name.
+    """
+    _probe(monkeypatch, (None, None, None, None, None))
+    c = as_user(make_user())
+    r = c.post(
+        "/api/downloads/upload", content=b"data", headers=upload_headers("nyaralás ősszel.bin")
+    )
+    assert r.status_code == 200, r.text
+    asset = db.execute(select(MediaAsset).order_by(MediaAsset.id.desc())).scalars().first()
+    assert asset is not None
+    stored = Path(asset.rel_path).name
+    assert "%" not in stored and "c3" not in stored.lower(), stored
+    assert stored.startswith("nyaralas_osszel"), stored
+
+
+def test_a_long_display_name_is_truncated_on_EVERY_route_that_takes_one(
+    db, as_user, make_user, _root, monkeypatch, upload_headers
+):
+    """The sweep, held end to end rather than at one site.
+
+    `display_text` was introduced for the upload path and applied to three of the five writers of
+    this varchar(255) column; `POST /api/downloads` and `POST /api/downloads/edit` kept the old
+    `(x or "").strip() or None` and would still have answered a bare 500 (a psycopg DataError,
+    which main.py re-raises for everything but the NUL case) to a name a user simply pasted. Found
+    by four independent readers in deep-review round 2 — a sweep is exactly the kind of thing that
+    gets done four-fifths of the way, so this holds all of it at once.
+    """
+    _probe(monkeypatch, ("h264", "aac", 640, 480, 60))
+    monkeypatch.setattr(uploadmod.editmod, "ensure_poster", lambda _a, _root: None)
+    long_name = "n" * 300
+    bound = "n" * DISPLAY_TEXT_MAX
+    c = as_user(make_user())
+
+    # 1. the upload route — the name arrives in a request header.
+    up = c.post(
+        "/api/downloads/upload", content=b"video", headers=upload_headers("a.mp4", long_name)
+    )
+    assert up.status_code == 200, up.text
+    assert up.json()["display_name"] == bound
+
+    # 2. the enqueue route — a plain JSON field, from the Add-download dialog. An inline `spec`
+    # rather than a profile id, so the test does not have to seed the builtin profile table.
+    enq = c.post(
+        "/api/downloads",
+        json={"source": "dQw4w9WgXcQ", "spec": {"kind": "video"}, "display_name": long_name},
+    )
+    assert enq.status_code == 200, enq.text
+    assert enq.json()["display_name"] == bound
+
+    # 3. the edit route — the same field, from the editor.
+    edit = c.post(
+        "/api/downloads/edit",
+        json={
+            "source_job_id": up.json()["id"],
+            "edit_spec": {"trim": {"start_s": 0, "end_s": 1}},
+            "display_name": long_name,
+        },
+    )
+    assert edit.status_code == 200, edit.text
+    assert edit.json()["display_name"] == bound
+
+    # 4 + 5. the metadata PATCH's two fields.
+    patched = c.patch(
+        f"/api/downloads/{up.json()['id']}",
+        json={"display_name": long_name, "display_uploader": long_name},
+    )
+    assert patched.status_code == 200, patched.text
+    assert patched.json()["display_name"] == bound
+    assert patched.json()["display_uploader"] == bound
+
+
+def _display_write_sites() -> dict[tuple[str, str], set[str]]:
+    """Every place under `backend/app/` that puts a value into a display field, as
+    (module relative to `app/`, enclosing function) -> the set of value expressions written there.
+
+    TWO SHAPES, because the first version of this guard walked only `ast.Assign` and was therefore
+    blind to the shape the upload route itself uses — `SpooledUpload(..., display_name=...)` is an
+    `ast.keyword`, not an assignment, so the one site with an unbounded REQUEST HEADER behind it was
+    the site the guard could not see (deep-review round 3).
+
+    ANNOTATED assignments are excluded on purpose: `display_name: Mapped[str | None] =
+    mapped_column(...)` in `models.py` and `display_name: str | None = None` in a Pydantic model are
+    declarations of the field, not writes into it.
+
+    The whole of `app/`, not just `app/routes/`: a job row is constructed in `downloads/service.py`
+    and `downloads/upload.py`, so a walk stopping at the HTTP boundary misses the writers that
+    actually reach the column.
+    """
+    app_dir = pathlib.Path(__file__).resolve().parents[1] / "app"
+    found: dict[tuple[str, str], set[str]] = {}
+    for py in sorted(app_dir.rglob("*.py")):
+        module = py.relative_to(app_dir).as_posix()
+        tree = ast.parse(py.read_text("utf-8"), filename=str(py))
+        enclosing: dict[int, str] = {}
+        for fn in ast.walk(tree):
+            if isinstance(fn, (ast.AsyncFunctionDef, ast.FunctionDef)):
+                for node in ast.walk(fn):
+                    enclosing.setdefault(id(node), fn.name)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Assign):
+                names = {
+                    t.id if isinstance(t, ast.Name) else t.attr
+                    for t in node.targets
+                    if isinstance(t, (ast.Name, ast.Attribute))
+                }
+                value = node.value
+            elif isinstance(node, ast.keyword):
+                names = {node.arg} if node.arg else set()
+                value = node.value
+            else:
+                continue
+            if not names & {"display_name", "display_uploader"}:
+                continue
+            key = (module, enclosing.get(id(node), "<module>"))
+            found.setdefault(key, set()).add(ast.unparse(value))
+    return found
+
+
+# Every write into a display field, with the expression each one writes. A varchar(255) column with
+# a request header behind it turns a too-long name into a psycopg DataError — a 500 AFTER the whole
+# file has transferred — so each of these has to be bounded, and each one here has been read.
+#
+# Bounded by `display_text` unless noted:
+#   auth.get_or_create_demo_user      a literal.
+#   service.redownload                CLEARS the field so the fresh metadata wins — `None` is the
+#                                     one value that needs no bound, and a clear is still a write.
+#   service.enqueue / enqueue_edit    `display_name` is already bounded by its caller; the fallback
+#                                     slices the YouTube title to the same width.
+#   downloads.upload_download         passes through `spool_upload`'s value, bounded there.
+#
+# Held as EXACT EQUALITY rather than as a list of offenders. The offender form could only fail
+# upward: refactoring the writers into a shape the walker did not recognise left it asserting
+# `not []` and enforcing nothing, which is how a drift guard dies quietly (round 3). This one fails
+# when a site appears, when one disappears, and when one changes what it writes.
+DISPLAY_WRITE_SITES = {
+    ("auth.py", "get_or_create_demo_user"): {"'Demo'"},
+    ("downloads/service.py", "redownload"): {"None"},
+    ("downloads/service.py", "enqueue"): {
+        "display_name or (asset.title[:DISPLAY_TEXT_MAX] "
+        "if asset.status == 'ready' and asset.title else None)"
+    },
+    ("downloads/service.py", "enqueue_edit"): {"display_name or asset.title[:DISPLAY_TEXT_MAX]"},
+    ("downloads/upload.py", "ingest_upload"): {"display_text(display_name)"},
+    ("routes/auth.py", "callback"): {"display_text(userinfo.get('name'))"},
+    ("routes/auth.py", "_complete_link"): {"display_text(userinfo.get('name'))"},
+    ("routes/downloads.py", "enqueue_download"): {"display_text(body.display_name)"},
+    ("routes/downloads.py", "enqueue_edit"): {"display_text(body.display_name)"},
+    ("routes/downloads.py", "update_download_meta"): {
+        "display_text(body.display_name)",
+        "display_text(body.display_uploader)",
+    },
+    ("routes/downloads.py", "upload_download"): {"upload.display_name"},
+    ("routes/downloads.py", "spool_upload"): {
+        "display_text(_header_text(request, UPLOAD_DISPLAY_NAME_HEADER))"
+    },
+}
+
+
+def test_no_code_path_assigns_a_display_field_without_the_shared_helper():
+    """The drift guard for the test above: it holds five routes, this holds the rule.
+
+    Parsed, not grepped. Every value that reaches a display field takes a string a user typed (or
+    YouTube supplied) and puts it on its way to a varchar(255) column, so every one of them must be
+    bounded. A writer added tomorrow fails here instead of 500ing in production.
+    """
+    found = _display_write_sites()
+    moved = set(found) ^ set(DISPLAY_WRITE_SITES)
+    changed = {
+        key: (found[key], DISPLAY_WRITE_SITES[key])
+        for key in set(found) & set(DISPLAY_WRITE_SITES)
+        if found[key] != DISPLAY_WRITE_SITES[key]
+    }
+    assert found == DISPLAY_WRITE_SITES, (
+        "a display-field write appeared, moved or changed shape. Every value reaching "
+        "display_name/display_uploader must be bounded to models.DISPLAY_TEXT_MAX — normally by "
+        "models.display_text — or a name longer than the column is a 500 rather than a truncation. "
+        f"Sites that appeared or vanished: {moved}. Sites that changed: {changed}."
+    )
+
+
+def test_the_display_text_bound_matches_the_columns_it_guards():
+    """A number living in two places is how the `cancelled`/`canceled` bug happened. `display_text`
+    truncates to `DISPLAY_TEXT_MAX`; the columns it feeds are `String(255)`. Held against the model
+    itself, so widening one without the other fails here rather than as a DataError in production."""
+    for name in ("display_name", "display_uploader"):
+        assert DownloadJob.__table__.c[name].type.length == DISPLAY_TEXT_MAX
+
+
+def test_the_display_name_header_reaches_the_job_and_is_bounded(
+    as_user, make_user, _root, monkeypatch, upload_headers
+):
+    """The second header, which had no backend test at all — and the length nothing bounded.
+
+    Since P1 the display name arrives in a REQUEST HEADER rather than as a form field, so the only
+    limit on it was the header size. The column is varchar(255), so a longer one reached Postgres as
+    a DataError: a 500 AFTER the whole file had been transferred. It is truncated now, by the same
+    helper the metadata PATCH uses.
+    """
+    _probe(monkeypatch, (None, None, None, None, None))
+    c = as_user(make_user())
+
+    ok = c.post(
+        "/api/downloads/upload",
+        content=b"data",
+        headers=upload_headers("clip.bin", "Nyári vakáció"),
+    )
+    assert ok.status_code == 200, ok.text
+    assert ok.json()["display_name"] == "Nyári vakáció"
+
+    long_name = "n" * 300
+    bounded = c.post(
+        "/api/downloads/upload", content=b"data2", headers=upload_headers("clip2.bin", long_name)
+    )
+    assert bounded.status_code == 200, bounded.text
+    assert bounded.json()["display_name"] == "n" * DISPLAY_TEXT_MAX
+
+
+def test_the_upload_holds_no_db_transaction_while_the_body_streams(
+    as_user, make_user, db, _root, monkeypatch, upload_headers
+):
+    """P1 moved the body read behind the auth dependency, which put the whole transfer INSIDE the
+    request's database session: resolving the caller and reading the cap are SELECTs, SQLAlchemy 2.0
+    autobegins on the first one, and the session then holds one of the twenty pooled connections —
+    `idle in transaction` to Postgres, with no `idle_in_transaction_session_timeout` to end it — for
+    as long as the client keeps sending. `db.py` sizes the pool on that not happening and
+    `plex/playback.py` records the production incident behind the rule.
+
+    Asserted on the session rather than on `engine.pool.checkedout()`: the transaction is the cause,
+    the checkout is its consequence (measured), and the pool counter is shared with whatever else
+    the test process is holding.
+    """
+    from app.routes import downloads as downloads_routes
+
+    _probe(monkeypatch, (None, None, None, None, None))
+    seen: dict[str, bool] = {}
+    real_stream = downloads_routes.capped_stream_to
+    real_release = downloads_routes.release_read_connection
+
+    def spy_release(session):
+        # The PRECONDITION, so this test cannot pass vacuously. Asserting only "no transaction
+        # while streaming" would stay green if the auth/cap reads stopped opening one at all —
+        # and under `as_user` the auth SELECT is already overridden away, so that is a live risk
+        # rather than a theoretical one.
+        seen["before"] = bool(session.in_transaction())
+        real_release(session)
+        seen["after_release"] = bool(session.in_transaction())
+
+    async def spy_stream(request, out, limit, refusal):
+        seen["while_streaming"] = bool(db.in_transaction())
+        return await real_stream(request, out, limit, refusal)
+
+    monkeypatch.setattr(downloads_routes, "release_read_connection", spy_release)
+    monkeypatch.setattr(downloads_routes, "capped_stream_to", spy_stream)
+    c = as_user(make_user())
+    r = c.post("/api/downloads/upload", content=b"data", headers=upload_headers("held.bin"))
+    assert r.status_code == 200, r.text
+    assert seen["before"] is True, (
+        "nothing had opened a transaction before the release, so this test proves nothing — the "
+        "reads it is meant to follow must have moved or been stubbed away"
+    )
+    assert seen["after_release"] is False
+    assert seen["while_streaming"] is False, (
+        "the request's session was inside a transaction when the transfer began, so a pooled "
+        "connection is pinned for the whole upload"
+    )
+
+
+def test_the_usage_route_reports_the_per_file_upload_cap(as_user, make_user, db):
+    """The dialog refuses an over-cap file off this number, and it is the only layer that produces
+    a refusal carrying the limit on a default install — so the field is load-bearing, not
+    decorative. Nothing held it: the route had no test at all, and the frontend's `DownloadUsage`
+    is an unvalidated cast, so dropping the key would have been green everywhere (round 2).
+    """
+    from app import sysconfig
+
+    c = as_user(make_user())
+    r = c.get("/api/downloads/usage")
+    assert r.status_code == 200, r.text
+    assert r.json()["upload_max_bytes"] == sysconfig.get_int(db, "download_upload_max_bytes")
+
+    # And it is the KNOB, not a constant: a lowered override must show through.
+    sysconfig.set_value(db, "download_upload_max_bytes", 4096)
+    db.commit()
+    assert c.get("/api/downloads/usage").json()["upload_max_bytes"] == 4096
+
+
+def test_a_refused_upload_leaves_nothing_in_the_staging_directory(
+    as_user, make_user, db, _root, monkeypatch, upload_headers
+):
+    """`spool_upload` writes the body to a staging temp file as it arrives, so a refusal happens
+    with a partial file already on disk — its `finally` is what removes it. Nothing asserted that:
+    deleting the unlink left the whole suite green while every refused upload leaked its partial
+    bytes onto the volume, one file per attempt, with no job to ever clean them up.
+    """
+    from app import sysconfig
+
+    sysconfig.set_value(db, "download_upload_max_bytes", 8)
+    db.commit()
+    staging = Path(settings.download_root) / ".staging" / "uploads"
+    c = as_user(make_user())
+
+    r = c.post("/api/downloads/upload", content=b"x" * 4096, headers=upload_headers("leaky.bin"))
+    assert r.status_code == 422
+    assert staging.exists(), "the dependency did not get as far as creating the staging dir"
+    assert list(staging.iterdir()) == [], "a refused upload left its partial file behind"
+
+
 def test_upload_cap_cannot_be_disabled_with_zero(db):
-    """download_upload_max_bytes floors at 1: a stored 0 would read falsy in the route's
-    `if cap and size > cap` guard and SILENTLY disable the per-file cap, so set_value must reject it.
-    Pins the min=1 invariant so a revert to min=0 can't pass the gate."""
+    """download_upload_max_bytes floors at 1, and set_value must enforce it.
+
+    The falsy-0 footgun this originally guarded is gone — the route's old `if cap and size > cap`
+    read a stored 0 as "no cap at all", while `capped_stream_to` compares unconditionally and a 0
+    would refuse everything instead. Refusing everything is the safe direction, but it is still
+    wrong, and the knob is also the number the admin page and the 422 `limit` advertise. Pins the
+    min=1 invariant so a revert to min=0 can't pass the gate."""
    from app import sysconfig

    with pytest.raises(ValueError):
        sysconfig.set_value(db, "download_upload_max_bytes", 0)


-def test_upload_route_rejects_empty_file(as_user, make_user, _root, monkeypatch):
+def test_upload_route_rejects_empty_file(as_user, make_user, _root, monkeypatch, upload_headers):
    c = as_user(make_user())
-    r = c.post(
-        "/api/downloads/upload", files={"file": ("empty.bin", b"", "application/octet-stream")}
-    )
+    r = c.post("/api/downloads/upload", content=b"", headers=upload_headers("empty.bin"))
    assert r.status_code == 400
    assert r.json()["detail"]["code"] == "upload_empty"


-def test_redownload_rejects_an_upload(as_user, make_user, _root, monkeypatch):
+def test_redownload_rejects_an_upload(as_user, make_user, _root, monkeypatch, upload_headers):
    _probe(monkeypatch, (None, None, None, None, None))
    c = as_user(make_user())
-    job = c.post(
-        "/api/downloads/upload", files={"file": ("a.bin", b"data", "application/octet-stream")}
-    ).json()
+    job = c.post("/api/downloads/upload", content=b"data", headers=upload_headers("a.bin")).json()
    r = c.post(f"/api/downloads/{job['id']}/redownload")
    assert r.status_code == 409


-def test_edit_rejects_a_generic_upload_source(as_user, make_user, _root, monkeypatch):
+def test_edit_rejects_a_generic_upload_source(
+    as_user, make_user, _root, monkeypatch, upload_headers
+):
    _probe(monkeypatch, (None, None, None, None, None))
    c = as_user(make_user())
-    job = c.post(
-        "/api/downloads/upload", files={"file": ("a.bin", b"data", "application/octet-stream")}
-    ).json()
+    job = c.post("/api/downloads/upload", content=b"data", headers=upload_headers("a.bin")).json()
    r = c.post(
        "/api/downloads/edit",
        json={"source_job_id": job["id"], "edit_spec": {"trim": {"start_s": 0, "end_s": 1}}},
@@ -37,7 +37,7 @@ def test_a_failure_is_sorted_by_what_the_user_can_do(exc, reason):
    ("route", "target"),
    [
        ("/api/sync/subscriptions", "app.routes.sync.import_subscriptions"),
-        ("/api/playlists/sync-youtube", "app.routes.playlists.sync_user_playlists"),
+        ("/api/playlists/sync-youtube", "app.routes.playlists.pull_user_playlists"),
    ],
 )
 def test_a_manual_sync_youtube_refuses_is_a_422_not_a_500(
@@ -0,0 +1,638 @@
+# DESIGN.md — how Siftlode looks and behaves
+
+This is the one written source of truth for the UI: principles, tokens, the canonical solution per pattern,
+and the interaction rules. Screens are measured against it. A pattern that has more than one look in the
+code is either a decision still open here (marked **Pending**) or a violation to fix.
+
+**Status:** written in E28; every chapter is _Decided_ and in force. The design lab (below) renders each rule's
+chosen form. A new question opens a **Pending** item here, with its variants in the lab, until the product
+owner settles it.
+
+## How this document changes
+
+- A rule changes only through an explicit decision recorded in the [decision log](#decision-log): what was
+  decided, the options it was chosen from, and why. No mid-sprint taste changes. A new idea goes on the
+  list for the next design round.
+- Every rule rests on a named standard: Nielsen's heuristics, WCAG 2.2 AA, WAI-ARIA APG, Apple HIG or
+  Material. The tag is in brackets after the rule.
+- A rule stated here should also be enforced in code (an eslint rule, a primitive's type, a test). A rule
+  that lives only in prose drifts. That is the finding that started this document.
+
+## Conformance — the check before a UI change is done
+
+A screen is measured against this document, not against taste. Every change that renders something new
+runs this check before it is called done (E28 S3g):
+
+1. **Primitives at a named rung.** Each control goes through its primitive (lint refuses the raw element,
+   and a `<div role="button">` with it), at a rung or role this document names: a `Button` size, an
+   `IconButton` size, a `Chip` size, the `SegmentedToggle` rung, a `SURFACE` role. The lint holds the
+   element, not the rung, so the rung is checked by eye and by measure.
+2. **The pattern's chapter, re-read.** The change matches the chapter of every pattern it touches, or it
+   opens a **Pending** item and a log row. It never quietly adds a second look.
+3. **Measured.** On the changed pages, the rendered elements are grouped by kind (button, icon button,
+   chip, field, tab, segment, menu row, surface) and by their computed look (radius, height, type, fill,
+   edge). Each distinct look maps to a rung or role named here; a look that maps to none is a violation
+   or a new decision. The S3g baseline across the 15 pages at 1920 × 1080: every button, icon button,
+   chip, field, tab, segment and menu row is drawn by its primitive. What the measure still counts as
+   hand-drawn is by design: text links (no primitive), surfaces painted by their `SURFACE` role (a class,
+   which the measure cannot trace to a component) and the playlist table's own rows.
+4. **Seen.** A screenshot of every changed state, thin edges at 1:1; the tablet widths (1024 × 768, a
+   narrow split screen) when the layout can reflow. Phones are the E29 epic's, not this check's.
+
+## The design lab
+
+`npm run dev`, then open **`http://localhost:5173/design-lab`**. The lab renders each open decision's variants
+with the app's real CSS, tokens, glass and themes, and has its own switches for theme, scheme, text size and
+backdrop. It is dev-only: `main.tsx` reaches it behind `import.meta.env.DEV`, and the build plugin
+`frontend/devOnlyGuard.ts` fails a production build that would contain it. Once a decision is taken, the
+losing variants are deleted and the chosen one stays as the reference rendering: the lab is the living
+style guide.
+
+## Principles
+
+1. **Glass over a calm background is the look.** Surfaces are translucent layers (`.glass`,
+   `.glass-card`, `.glass-menu`, `.glass-media`) over a per-scheme backdrop. Depth comes from the
+   **header + fade**: a crisp sticky header with a short gradient just below it, so content dissolves as it
+   slides under. The reference is `DataTable`'s sticky header. A flat opaque box where a glass surface
+   belongs is a violation.
+2. **Built for one known, daily user, on a desktop and a tablet.** Density is welcome where a mouse is
+   the pointer; on touch every target grows. Nothing is designed for phones.
+3. **One primitive per pattern.** Where a `components/ui/` primitive exists and is used, the looks don't
+   drift. The drift lives in hand-rolled markup. A new generic control goes into `ui/`, and a screen
+   composes primitives rather than restyling them.
+4. **Measured, not eyeballed.** Contrast, target sizes and layout at the contract sizes are measured in a
+   real browser before a UI change is called done.
+5. **Honest states.** An error never renders as an empty state; loading, empty and error are three
+   different screens (`QueryState` / `StateMessage`).
+
+## Device adaptation — _Decided_
+
+- **Supported:** tablet portrait and landscape and every size above them (from 768px wide). Phones are not a
+  target. Measure a UI change at 1024×768, 820×1180 (portrait) and a desktop size.
+- **Adapt by capability, never by user agent:** `@media (pointer: coarse)` and `(hover: none)` decide touch
+  behaviour; container queries decide how a panel lays itself out. Breakpoints are named tokens, never
+  literal pixel values scattered in call sites. [HIG, WCAG 1.4.10]
+- **Touch never loses a function.** Anything revealed on hover is visible at rest on `hover: none` (the
+  `.reveal` class), or it is removed on touch because the same action is reachable another way
+  (`.reveal-hover`). [WCAG 1.4.13, Nielsen #6]
+- **Targets:** at least 2.75rem (44px) on a coarse pointer, as a real box, not an invisible hit area:
+  overlapping hit areas fire the wrong control. It covers every control primitive, not only `Button`
+  (A3, under Controls). [HIG, WCAG 2.5.8]
+- **Text inputs** use at least 1rem text on a coarse pointer, so a tablet browser doesn't zoom the page
+  when an input gets focus.
+- **Side panels (C2):** on touch, and at any width below 768 (a narrow window, split screen), the rail tab
+  or the band's "Filters · n" button slides the panel **over** the content with a scrim; a tap outside, Esc
+  or Back closes it, and the content never reflows. Pinning is its own button in the panel header, offered
+  only where a pinned panel leaves the content room (≥ 1024 wide). The mouse keeps hover-to-peek and
+  click-to-pin. A filter is never unreachable at any supported width. Built in S3f3: `ui/SidePanel`
+  opens `ui/Modal`'s `drawer-start` placement (the dialog's own Esc, Back, scrim, focus trap and scroll
+  lock); the tab shows at every width and is 44 wide on touch; a pin saved on a desktop is left alone
+  below 1024, not honoured. [Nielsen #7, WCAG 1.4.10]
+- **A row answers to its own width.** A list row that must fit a narrow column (the download row, the
+  playlist table, the Channels tag row) stacks by a container query on its own box, not by the
+  window: the same list sits beside a rail, in a split-screen tablet and in a zoomed-in browser. A
+  line of facts (the download row's "Ready · MP4 · 18.9 MB · 1:11 · 1w ago") is one line cut at its
+  end, never a flex row that breaks its pieces apart.
+- **A table gives its secondary columns back.** By the table's own width, as a row does: below 42rem
+  a column marked `narrowHidden` steps aside, below 64rem (a 1024 window) one marked `tabletHidden`
+  does, so the name keeps its room. The Channels table drops Prio, About and Length there (at 1024 the
+  name had 60 px); the row's "…" still sets the priority.
+- **Players on touch (C3):** see [Players](#players).
+
+## Tokens
+
+- **Colour:** only semantic tokens (`--bg --surface --card --fg --muted --accent --accent-fg --danger
+--warn --success --info --border`, each with a `-fg` partner where text sits on it), and no palette class
+  (`text-amber-500`: lint-refused). A score's gold is `--rating` (theme-scoped, 4.5:1 on the page and on its
+  own chip), never `--warn`: a score is not a warning. What sits on a picture looks the same in both themes,
+  because the picture does: the broadcast red `--live` under `--live-fg` (never `--danger`: "live" is not an
+  error), `--rating-media` on a poster's scrim, and `--media-chrome` for the always-dark player's menus
+  (owner decision F16). Black and white are the media scrims and their text. Five schemes × dark
+  and light (B2): **Midnight** (blue), **Forest** (cyan), **Slate** (fuchsia), **Matrix** (moss) each earn their
+  place with their own hue family; **Fjord** (Midnight's navy with a calm steel-blue accent) is the one kept
+  exception, the calm twin of the vivid Midnight. A new scheme still needs its own hue family. Normal text ≥ 4.5:1 and a control's edge ≥ 3:1 in **every** scheme and mode.
+  [WCAG 1.4.3, 1.4.11] The input edge token is set under Controls (A4). The ≥ 3:1 edge is the field
+  family's (a field, the form's dropdown trigger), whose edge is the only thing that says "type here". A
+  labelled pill (a chip, a toolbar trigger, a tab, a segment) keeps the faint `--border`: its text names it,
+  and 1.4.11 does not ask an edge of a control its label already identifies (owner decision F14).
+- **The accent never looks like a status.** A scheme's accent is at least 30° of OKLCH hue away from
+  `--danger`, `--warn` and `--success`, and passes 4.5:1 both as text on `--bg` and under `--accent-fg` on
+  the fill, in dark and light. A primary button must never read as a destructive one. A new scheme is
+  measured against this before it ships (the lab's B2 tiles do the arithmetic). [WCAG 1.4.1, 1.4.3]
+- **Held in code:** `frontend/src/lib/theme.contract.test.ts` measures every scheme × mode in `index.css`
+  against the two rules above (text 4.5:1, a control edge 3:1, the status and rating colours as text, the accent's
+  hue gap), and the media colours against what they sit on. A scheme or a retuned colour that breaks them does not pass the gate.
+- **No per-user colour tuning.** The schemes are the only colour choice; the old floating glass tuner was
+  retired (E28), because free tuning is exactly the drift these rules exist to stop.
+- **Backdrops:** one per scheme and mode (`public/backdrops/`), soft pools in the accent's family, with a
+  grey `overlay` grain that breaks the gradient banding (measured by pixel-scanning a canvas, never a
+  screenshot, which rescales).
+- **State layers (B3):** hover and pressed are a layer, not a colour swap: the text colour mixed at **10%**
+  (hover) / **16%** (pressed) over whatever the control sits on, so it reads on the page, a card and glass
+  alike. A filled control mixes its own text colour into its fill at 14% / 24%. Opacity dimming and
+  `bg-card` hovers are violations (invisible on a light card). Selected stays the solid accent. The one
+  exception is an edged pill (a chip, a toolbar or form trigger, a segment): its hover is the accent edge
+  (`.pill:hover`, `glass-hover`), which reads on every surface too (owner decision F14).
+  A card that is one row with actions answers as a whole: the layer is the card's, under its badges and
+  buttons, and the row's open button spans the card beneath the actions (a hover that stopped at the first
+  badge read as broken; owner, E28 — `AdminUsers` user rows).
+- **Tokens as utilities:** the decided values live once in `index.css` — `--hover` / `--press`,
+  `--edge-strong`, `--touch-target`, and the utilities `state-layer`, `state-filled`, `state-danger`,
+  `edge-strong`, `fade-below`, `fade-below-panel`, `fade-above-panel`, `fade-edges-x`. A primitive or a lab
+  rendering uses them; restating one as an arbitrary class is a violation.
+- **Type and size:** everything is rem-derived off `--font-scale` (the Settings text-size slider), so a
+  px font size or a px-frozen box is an eslint error.
+- **Radius:** chips and segmented controls `rounded-full`; tabs `rounded-lg`. Buttons, icon buttons and
+  form fields `rounded-lg`; toolbar triggers and search a pill (Controls). Surfaces: see Surfaces.
+- **Layers:** the fixed z-index scale in `index.css` (`base < menu < chrome < paneltab < panel < rail <
+overlay < popover < tooltip`), plus `under`, a surface's own layer under its content inside its `isolate`.
+  No ad-hoc z-index. [maintainability]
+
+## Controls — _Decided_ (batches A and B)
+
+The chosen rendering of each rule is in the lab under "Decided". The primitives are built to it in S3.
+
+- **Buttons (A1):** `rounded-lg` (r8): a control's corner is smaller than the surface it sits on (card r12,
+  dialog r16). The rung follows the context: `md` in forms and dialog footers, `sm` in toolbars and panel
+  headers, `xs` inside a table row. Glass is a `Button` variant, not a hand-built glass button. [HIG, Material]
+- **Density (B1): compact, by explicit height.** `md` 2rem (32), `sm` 1.75rem (28), `xs` 1.5rem (24); icon
+  buttons 1.75rem / 2rem. A toolbar's search pill, dropdown trigger, `sm` button and small icon button are
+  the same 28, so the row lines up. Nothing goes under 24 (WCAG 2.5.8); touch grows it to 44 (A3).
+- **Icon buttons (A2):** two sizes (28 / 32), r8: the smaller in rows and dense toolbars, the larger on its own. On a
+  picture, a round, dark translucent button, readable on any thumbnail. Round means "floats over something":
+  on media, or the one floating button over the page (back to top, a 48 glass circle, the FAB); a button
+  inside a pill field is round too, so the radii nest. A text
+  button on a picture is a pill (the card's Continue in the accent, Restart dark translucent, C5), and
+  the one 48px glyph is the Play in the middle of a not-started card (C5).
+- **Touch (A3):** on a coarse pointer every control primitive (`Button`, `SegmentedToggle`, `FilterSelect`,
+  `Tabs`, `Switch`, chips, the nav rail) grows to 2.75rem (44px) through one token, as a real box. Mouse
+  sizes don't change. [HIG, WCAG 2.5.8]
+- **Input (A4):** one bordered input primitive, `ui/Input` (`Textarea` for several lines; a frame that also
+  holds an icon or chips is painted with `fieldClass` around an `InnerInput`). The edge is
+  `color-mix(in srgb, var(--fg) 55%, var(--bg))`, ≥ 3:1 against the page in every scheme and mode; focus
+  turns it into a 2px accent edge, `invalid` into the danger edge. A form field is r8 at the `md` height
+  (32); a toolbar search, a field in a popover or an inline rename is `sm` (28), the toolbar search a pill;
+  the page's one hero field is `lg` (40): the header search, a glass pill floating over the page (the
+  YouTube/Gmail shape), and the command palette's field;
+  a field in a table row or the pager `xs` (24); an inline rename of a page title keeps the heading's type
+  (`heading`). Text is 1rem and the box 44 on a coarse pointer. [WCAG 1.4.11]
+- **Dropdown trigger (A5):** `ui/SelectTrigger`. A pill in a toolbar (where the pill means "a filter or a
+  choice"), r8 and full width in a form, where it wears the field's frame (see-through, the ≥ 3:1 edge) and
+  lines up with the inputs. Open is the accent edge and the chevron turned over.
+- **Checkbox, switch, slider (A6):** the browser's own controls tinted with `accent-color` (`Checkbox`,
+  `CheckRow`, `Slider`); `ColorInput` is the browser's colour well, which `accent-color` does not reach (it
+  tints only checkboxes, radios, ranges and progress bars). The whole labelled row is the 44px target. Keyboard, screen reader and
+  forced-colours support come from the browser. The switch stays `form`'s `Switch`: no browser has a native
+  one yet. A raw `<input>` or `<textarea>` outside those primitives is a lint error (a hidden file picker
+  passes). A checkable row that cannot hold an `<input>` — a menu row, a whole-row button whose role says
+  checkbox — draws the ONE `ui/MenuCheck` in its leading icon slot: a box filled with the accent for a set
+  (tags, playlists, a filter's values; a minus for a group only partly in), a bare tick for one choice (a
+  language, a sort, a priority step), an unticked choice keeping the slot empty so the labels line up.
+- **In-place editing:** a field that replaces its trigger (a title rename, the priority number) hands the
+  focus back to that trigger when Enter or Escape closes it (`useReturnFocus`), never to `<body>`.
+  [WCAG 2.4.3]
+
+Also in force:
+
+- **One primitive per button family** (E28 S3b): a labelled action is `Button` (a rung from the ladder,
+  plus `lg` 40 for a page's single hero call to action, and nothing else); a glyph is `IconButton` (a
+  required `label`); a card, row, tile or menu row whose content is the control is `Pressable`; a filter or
+  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
+  `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).
+  `filter` is a selectable option, solid accent when `pressed`; the "+N" and "More…" triggers are filter
+  chips too, and while their popover is open they show it as an open trigger does, the accent edge and
+  text (not the solid fill, which would say "selected"); `token` is an applied narrowing, the accent tint, the whole chip removing
+  it; `tag` is a user's tag, the solid accent; `suggest` is a suggestion not yet taken (dashed accent);
+  `ghost` the quiet "add a tag" (dashed neutral). A chip whose label is not the control but carries its
+  own × is `DismissibleChip`: two sibling controls at most, never a button in a button. An overflowing chip
+  lane measures a hidden mirror painted with `chipClass`, so the mirror cannot drift from the chips.
+- **Unavailable with a reason** stays focusable: `aria-disabled` plus the reason in the label or tooltip,
+  never native `disabled`, which drops it from the tab order with its explanation. [WCAG 2.1.1]
+- A choice between a few values is `SegmentedToggle`; a long list or a user's own list is `FilterSelect`.
+  Never a native `<select>` (lint-enforced). Its rung is the toolbar's, 28 with `text-xs`, so it lines up
+  with the triggers and the pager's buttons; the 24 rung with the smallest type is only a side panel's
+  captioned match toggle (S3g: the old small default had put a pager and a toolbar count on 10px type).
+- **A multi-value filter's any/all switch** (tags, topics, languages, genres, collections, actors) is
+  `ui/MatchToggle`, on the panel right above its picker, from two picks on — never in the picker's
+  popover, where a closed picker hid that "all" was on. One wording: Match · Any / All. [Nielsen #1]
+- **The pager** is four glyphs — first, previous, next, last — round the page box (`IconButton`s, their
+  names as the tooltip); no words, at any width.
+- A single-select row of filter chips goes through `FilterChipGroup` (its options are `Chip`s).
+- 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]
+
+## Surfaces and page chrome — _Decided_ (batch B)
+
+- **Surface per role (B5):** a dialog or panel is `.glass` r16; a card or picker `.glass-card` r12; a menu
+  `.glass-menu` r12 with 4px padding and r8 items (12 − 4, so the corners nest); a tooltip `.glass-menu` r8.
+  Translucency comes only from the tiers (the app backdrop, Plex media, light); a per-site alpha override is a
+  violation. A call site names the ROLE (`SURFACE.panel` / `drawer` / `card` / `menu` / `popover` / `tooltip`,
+  `ui/surfaces.ts`), which brings the tier AND the radius; a page section is a panel, and what floats over
+  undimmed content (a menu, a hover card, a status popover, a toast, a tooltip) is `.glass-menu`. A bare glass
+  class is a lint error. A role's depth is its own shadow (the top highlight + the drop); a `shadow-*` size beside
+  a role would replace both and is a lint error too — a field that floats takes `shadow-float`, the same shadow.
+- **Static vs pressable (owner, S3d):** a label that does nothing (a topic, a keyword, a status, a count) is a
+  flat, tonal `Badge` with no edge; everything that does something has an edge (a chip, a trigger, a field).
+  A genre that filters the library is a chip; the same genre where it can't is a badge. A badge's `tone`
+  (neutral / accent / warn) is its own colour at 6%, measured at 4.5:1 in every scheme; a `<span>` drawn with a
+  round edge is a lint error (F29). A toggle button states itself through `pressed` (the solid accent), never a
+  bare `aria-pressed`, which the type refuses (F28).
+- **A link that looks like a button** (a download, a sign-in that leaves the app) is `LinkButton` /
+  `IconLink`: still an `<a>`, wearing the button's own face.
+- **Page chrome (B4):** a page's tabs and filters sit in ONE sticky band of the page colour, with the fade
+  under it (below). Below ~600px of height the filter row folds into one "Filters · n" button. Every page has
+  a visually hidden `h1`; the nav rail and the browser tab title are the visible identity. [WCAG 2.4.6]
+  Built as: the band is `PageShell`'s toolbar slot (`PageToolbar`), above the one scroller; a console
+  whose toolbar lives inside its frame (the server log) makes that toolbar `sticky` with `fade-below`
+  instead. The band holds controls only: an intro paragraph scrolls with the content (in the band it
+  ate three lines of a short window). The fold is `useFilterFold` + `FilterFoldButton`: the same row
+  shown or hidden in place, never copied into a popover. The hidden `h1` is `PageShell`'s `title`; a
+  view with its own visible title (a channel, a Plex show, a playlist) renders it as `PageHeading`
+  and the hidden one steps aside, so a page has exactly one `h1` (a hand `<h1>` inside the shell is
+  refused by a contract test). A section's caption is `SectionLabel`, an `h2` (an `h3` in a dialog),
+  never a styled `div`. The first Tab stop is "Skip to content" (`SkipLink`), which focuses the
+  scroller's `<main>`. [WCAG 2.4.1, 1.3.1]
+- **The header + fade edge (B9):** a crisp band and a 1rem gradient of the colour it sits on, so content
+  dissolves as it slides under; it shows only once something is under it, never over a list at rest. It goes on sticky toolbars and table headers, tabs over a scrolling panel, a
+  long dialog's header and footer, and the clipped ends of an overflowing chip row. Not on thumbnails (they
+  are the content) and not on buttons (it becomes a dated gloss). Built as: a sticky element takes the
+  `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
+  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).
+- **Nav rail (B7):** the `ui/NavRail` primitive, slim: 3.75rem wide. "You are here" is a soft accent tint plus a
+  3px edge bar. Labels under the icons are optional, a per-user switch in Settings (off by default); they add
+  height, never width, so each module has a short rail label that fits, and the full name stays in the
+  tooltip. No wide padding around the icons. The switch is Settings → Appearance → "Labels in the side
+  menu"; with the labels on, a row's accessible name is its visible short label (WCAG 2.5.3), and an
+  unread count is part of the name, not only drawn.
+- **Loading (B8):** a first load of a grid, list or table shows its skeleton (`LoadingState shape="grid" |
+"poster" | "list" | "table"`, built from the `Skeleton` primitive), so
+  nothing jumps when the data lands; a control's own work shows its spinner (`loading`). Neither appears
+  before ~300ms. [Nielsen #1]
+- **The public watch page (B6)** follows these same rules (glass, `Button`, the pressed-pill toggle, the
+  scheme's backdrop); only the video keeps the browser's own controls, because a stranger's device is
+  unknown.
+
+Already in force:
+
+- The glass role is load-bearing: a dropdown or menu is `.glass-menu` (it floats over undimmed content, so a
+  card alpha would bleed through), a dialog is `.glass`, and a grid card is `.glass-card`.
+- Every overlay is a `Modal`/`Overlay` or an anchored popover from the one popover engine. Escape closes the
+  topmost layer only, and focus returns to the control that opened it. [WCAG 2.4.3, 2.1.2]
+
+## Action placement — _Decided_
+
+Which actions are visible and which live in a menu.
+
+- **One menu, several triggers.** An object's actions are ONE list. The visible "…" button, a right-click,
+  a long-press (touch) and Shift+F10 / the Menu key all open the same `ContextMenu` built from that list.
+  A second, hand-made menu for the same object is a violation.
+- **Nothing is reachable only by a gesture.** Every menu action also has a visible path: the "…" button,
+  the page toolbar, or the object's detail view. A right-click is a shortcut, never the only door.
+  [Nielsen #6, #7]
+- **What stays visible:** the object's primary action (play or open) and any state the user needs to see
+  (watched, saved, downloading). **What goes into the menu:** rare, secondary and destructive actions.
+  Destructive ones keep their confirmation. [Nielsen #8, #5]
+- **On touch, a card shows fewer actions and a "…" button.** The rest are in the menu.
+- **The classification (C1)** says, per object, what is visible at rest, on hover and on touch; its full
+  table is the lab's C1 reference, and S3 turns it into each object's one action list in code. In short:
+  - A video or Plex card: play and its state (watched, progress) at rest; the everyday toggles (watched,
+    save, add to playlist) and "…" on hover; on touch the state and a 44px "…" beside the title. Details,
+    download, hide and reset live in the menu.
+  - A row (playlist item, channel, download): its primary action and its values (priority, tags, error)
+    stay visible; destructive and rare row buttons (unsubscribe, delete, cancel, remove) move into the menu.
+    A playlist item's X column goes: Delete key plus an undo toast.
+  - Downloads, Notifications and the Scheduler get a menu (they have none today); a page's destructive
+    header action ("Clear everything", "Purge discovery") goes into the header's "…".
+- **Built as:** one `useContextMenu` per list; the row spreads `triggerProps` (right-click, long-press,
+  Shift+F10) and its "…" is `ui/MoreButton` with `buttonProps` (the same menu, under the button; a second
+  press closes it). An object's list is one builder (`useVideoActions` for a video, `usePlexCardActions`
+  for a Plex title, composed by their lists and by Home's rails); a row that opens a panel ("Add to playlist…", "Details") anchors it to
+  `menu.anchor`, the element the menu came from. "Copy title" / "Copy link" come from `useCopyItems` and
+  run inside the click (`inGesture`, Safari's clipboard rule). The card's hover row sits on its picture
+  (the duration steps aside while it shows); on touch the toggles are gone and a 44px "…" sits beside
+  the title (`.touch-only`). The hover chrome and what steps aside for it are one pair of class strings
+  (`ui/reveal.ts`), shared by the video and the Plex cards. A table or rail ROW shows its "…" at the
+  row's end on hover or focus and always on touch (`.reveal`). A playlist's rows take Remove from the
+  Delete key too (the `listDelete` key scope, registered only by a list that can remove) and answer it
+  with an undo toast whose Undo puts the row back at its index in one request; a playlist itself has
+  one list (`usePlaylistActions.items`) that its rail row and its page header's "…" both open. A
+  subscribed channel's row ends in its "…" (`useChannelActions`: open, pin, Tags, Priority, YouTube,
+  copy, full history, hide with an undo toast, unsubscribe behind its confirm), docked beside the name
+  in the card layout. Its Tags submenu lists the reader's tags A–Z, each a check that toggles in place
+  (the menu stays open for the next); its Priority submenu offers the fixed steps 10 · 5 · 3 · 2 · 1 · 0
+  (an off-scale current value shows ticked in its place), and a pick re-sorts the list at once — only
+  that row moves — with the pager and the focus (its "…") following it. The row's stepper still sets any
+  value and leaves the order until the next load. A Plex playlist's title, show group and season each open the page's one row menu
+  (a title's is its `usePlexCardActions` list plus the removal); removals take the same undo toast,
+  `j`/`k` walk the visible rows and Delete removes the walked one; its rename and delete sit in the
+  header's "…". A toast that carries an action lives at least 8 s, whatever the toast setting. A
+  download row keeps play (pause / resume / retry in the queue) and the save link, a library row also
+  Share (the link copy, ahead of save), and ends in its "…" (`useDownloadActions`: the editors,
+  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
+  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
+  groups are `ui/menuGroups`: a rule between
+  two non-empty groups only.
+- **Background menu:** a right-click on EMPTY content area (not over text, inputs, links or media) may open
+  a page menu. It only mirrors page-scope actions that already exist in the toolbar (sort, view, quick
+  filters, select all); it adds no new function. Shift+right-click falls through to the browser's own menu.
+  Desktop only: on touch a long-press on the background clashes with scrolling and text selection, so the
+  toolbar stays the touch path. Built (`ui/PageMenu`; PageShell listens, `lib/backgroundTarget` decides
+  "empty") on five pages: the **feed** (sort, reshuffle, view, watch state, content types, source, clear
+  filters), the **Plex library grid** (sort, watch state, clear filters), the **channel manager** (layout,
+  the cards' sort, sync status, edit tags, clear the tag filter, read subscriptions from YouTube), a
+  **playlist** (play all, group by channel, reset view, save order, undo / redo, and the list's own "…")
+  and the **notification center** (mark all read). Never a destructive row (delete, revert, clear
+  everything) and never a long quota run (backfill): a stray right-click must not be one click from those.
+  The tab-only pages keep the browser's menu; `pageMenuScope.contract.test.ts` holds the list.
+
+### Text stays selectable — _Decided_
+
+Wherever there is text, the user can select it and copy it, and no click action overrides that.
+
+- A title or a name inside a click surface stays selectable: the card, row, person, channel or log line
+  that opens is `selectable` (`ui/FocusSafeButton`, under `Pressable` and `Button`). Chrome selects no
+  text inside a `<button>` unless it is `user-select: text` (measured), so the flag sets that and the
+  click guard below. A control's own label (a menu row, an option, a tab, a nav item, a switch) is not
+  a title and stays plain; `pressableSelectable.contract.test.ts` makes every new `Pressable` choose.
+- A click that ends a text selection does nothing: if the selection inside the element is non-empty, or
+  the pointer moved past the drag slop, no play or open fires.
+- A right-click on selected words opens the browser's own menu (Copy, Search, Translate), not the
+  object's; a right-click beside the selection still opens the object's menu (`ui/useContextMenu`).
+- On touch the long-press belongs to the context menu, so the object's menu offers **Copy title** and
+  **Copy link**.
+
+## Media card — _Decided_ (S3h)
+
+A film, a show, an episode, a video or a pinned channel is ONE card wherever it appears: the Plex grid,
+the feed, Home's shelves and hero, the Plex rails, the media-info page's collection strip. A place may
+pick a density step; it never changes the anatomy or loses an action. [Nielsen #4]
+
+- **Anatomy (the owner's pick C).** One frame: the picture, the title, the meta line pinned to the
+  frame's bottom edge, so a one-line title leaves no hole above the meta. What is ON the picture: the
+  length (a film's runtime, a show's season count, a video's duration) as a dark badge in the corner,
+  the watched mark, the progress bar along the bottom. Built as `ui/MediaCard` + the classes in
+  `ui/mediaCardStyles` (`MEDIA_PICTURE`, `MEDIA_IMG`, `MEDIA_BADGE`, `MEDIA_HOVER_LAYER`, `MEDIA_BAR`,
+  `mediaTitleClass`, `mediaPictureBox`).
+- **Play only where the click plays.** The hover layer dims the picture and shows `MediaPlayGlyph`, the
+  one round media Play (the button family's `media` variant), only on a card whose click starts
+  playback; a show without a next episode opens instead and shows none. The hover row (watched, save or
+  add, "…") docks at the picture's bottom-right; the length badge steps aside while it shows.
+- **Density.** A grid card: a two-line title and the full meta (Plex: year · ★ score; a video: the
+  channel, then views · age). On a shelf (any horizontal strip) the title is one line, cut with an
+  ellipsis, over ONE meta line (Plex: year · ★; a video: the channel; a tile: its count), so every card on
+  the strip is the same height. A Home shelf slot is 232px: at 200 the Play and the hover row
+  overlapped by 2px, at 232 they stand 6px apart; a landscape shelf picture takes the smaller Play.
+- **A mixed shelf is landscape.** Beside videos a Plex title shows its wide art, not its poster; a
+  rail's slot is a grid cell, so each card fills the height the strip stretches to. A carousel turns
+  the cards' content-visibility off (`mediaRail.contract.test.ts`): an off-screen card's reserved height
+  had become the strip's.
+- **The preview (the owner's pick C).** Resting the mouse on a Plex card for ~0.9 s opens a panel beside
+  it: the whole title, year · length · ★, and the synopsis in short lines (`ui/MediaPreview` +
+  `useMediaPreview`). Mouse only (a keyboard walk or a tap never opens it; "…" → Media info has the same),
+  passive (it never takes a click), and any press on the card closes it. Long text never goes in a
+  native `title` tooltip.
+- **Home's hero is a card** (the owner's pick A): the same hover row and Play on its picture, the same
+  whole menu on right-click, long-press and a touch "…" in its button row. In a wide window it stands
+  three quarters wide and centred, with even padding; its text is one centred stack — kicker, title,
+  subtitle (dropped when it is only the year), one fact line, a summary only when there is one.
+- **Home's shelf tiles act like their object.** A pinned channel or playlist: Play when it has a next
+  video, ↗ to open it, "…" with an Open row. A show carries its next episode: the Play, the watched
+  toggle and add act on that episode ("Next: S6·E16" is its meta line), and an ⓘ opens the show. A
+  channel's Home menu is play, open and the shelf's own rows; its tags, priority, hide and unsubscribe
+  stay on the Channels page.
+- **The compact list row (the owner's pick B).** The title leads; a faint "…" is always at the row's end;
+  on hover or focus the quick toggles float in beside it over the date, which steps aside (the Gmail
+  row). On touch only the "…".
+- **The media-info page (layout B).** Under the hero a main column — the collection strips (the same
+  card), then the crew, then the cast — beside a 20rem sidebar of facts (details, keywords). Every
+  section is the reader's to hide; a column with nothing in it is not drawn and the other takes the
+  width. A show's page uses the same meta row: a value that filters is a chip, a plain fact is flat
+  text, spaced by the gap, no "·".
+- **Browse tiles** (genres, playlists, collections) answer the pointer as a card does: the edge takes
+  the accent, the shadow lifts and the art zooms.
+- **A missing picture says what the item is.** No picture at all (a link that failed before its
+  details, a poster that never came) shows a quiet glyph — a film, a note, a file — never an empty box,
+  which reads as "still loading". A download with no name yet is titled by its short link, once: no
+  channel line, no second link line.
+- **Reading measure.** Prose (a synopsis, a biography, a channel's description) is capped at ~65
+  characters a line (the `measure` utility) wherever its container can be wider. [WCAG 1.4.8]
+
+## 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]
+- **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
+  clipping card rings inside itself, following its corners, since outside the ring ran under the table
+  head or was clipped away. [WCAG 2.4.7, 2.4.11]
+- **Menus and tabs follow WAI-ARIA APG:** arrow keys move, Home/End jump, Escape closes and returns focus;
+  tabs carry `tablist`/`tab`/`tabpanel` roles.
+- **Feedback:** a finished action is confirmed briefly (a toast that leaves by itself); anything that must
+  be read or acted on is not only in a toast. Status changes are announced through a live region.
+  [Nielsen #1, WCAG 2.2.1, 4.1.3]
+- **Errors:** a failed write goes through `meta.failTitle` / `notifyActionError`, never a silent `catch`.
+  An error sits next to what failed and says how to recover; a field error is under its field and linked
+  with `aria-describedby`. Colour is never the only signal. [Nielsen #9, WCAG 3.3.1, 1.4.1]
+- **Loading:** anything slower than ~300ms shows a loading state; a near-instant load doesn't flash one.
+  Space is reserved for late content so the layout doesn't jump; the form is under Surfaces (B8).
+- **Reordering:** anything you can drag also has a button or menu way to move it (Top / Up / Down / Bottom),
+  and a drag handle carries `touch-action: none` so a finger drags instead of scrolling. [WCAG 2.5.7]
+  A list whose rows have a "…" (a YouTube playlist, a Plex playlist: a block among the blocks, an
+  episode within its show) puts the four moves there (`ui/useOrderItems`); the saved views' editor
+  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).
+- **Motion:** 150–300ms micro-interactions, transform/opacity only; `prefers-reduced-motion` is respected.
+  [WCAG 2.3.3]
+
+## Players — _Decided_ (C3, C5, built in S3f)
+
+- **A tap on the Plex video only shows or hides the controls** (C3); play/pause is the button. The mouse keeps
+  click-to-pause. Measured live: before this, a tap with the bar hidden both revealed it and paused. [Nielsen #3]
+- **The hide timer starts with playback,** not with the first touch (before, on touch, the bar stayed up until
+  the first tap however long the video played).
+- **The bars stay up while the pointer rests on them** (F22, owner); leaving starts a fresh 3 s. YouTube and
+  Plex Web do the same: before, the row faded out from under a mouse parked on Next.
+- **Volume is the native `Slider`** (A6); the hand-drawn bar had no hover, focus, keyboard or screen-reader
+  state. A pointer drag gives the focus back, so Space and the arrows keep driving the player.
+- **The seek bar:** the track stays thin inside a 2.75rem (44px) hit area with `touch-action: none`, so a finger
+  drag scrubs instead of panning; the scrub head is always visible on touch. Controls are 44 on touch. [WCAG 2.5.8]
+- **The Plex control set (C5, the owner's model):** one row that fits a portrait tablet.
+  - No Stop (closing the player is stopping), no Restart, no ±10 s buttons.
+  - **Back:** more than 3 s in → back to the start; within the first 3 s → the previous item, at its resume
+    point if it has one, else its start. The first item has only the restart.
+  - **Next** shows only when there is a next item (an episode, a playlist queue). It starts that item at its
+    resume point and leaves one behind on the current item, which does not count as watched unless it is
+    already inside the finish margin (the credits).
+  - **±10 s:** the keyboard keeps ← / →; on touch a double-tap on the left or right third of the picture skips
+    ∓10 s, while a single tap still only shows the controls. Touch never loses a function. [WCAG 2.5.1]
+  - The row: play/pause, Back, Next, mute, the time, audio & subtitles, a fixed **⋯** (player settings, media
+    info, stats, keyboard shortcuts, download the original file), fullscreen. The volume slider is
+    mouse only: a tablet's volume is its buttons.
+- **Restarting lives on the media card** (C5): not started → Play; started → **Continue** (primary) +
+  **Restart**, the video card's own pair and words (`MediaResumeButtons`, one component for every card and
+  Home's hero). A poster stacks the pair; a landscape picture sets it side by side, icon-only on a small one.
+  On touch a tap continues and the card's "…" has "Play from the beginning" under its Play row. The restart
+  applies to the item the player opened on (`fromStart`); every item it moves on to resumes.
+- **The YouTube modal:** its chrome uses the `Button` rungs (44 on touch), the side arrows stay inside the
+  screen, and the description opens from an ⓘ button, because a hover popover never opens on a tap (measured
+  live). [WCAG 1.4.13]
+
+## Dialogs — _Decided_ (C4, built in S3f)
+
+- **Initial focus by purpose** (`Modal`'s required `initialFocus`, so no dialog inherits "the first
+  focusable", which is always the ✕): `field` — a form opens on the body's first control, and one that
+  loads after opening moves the focus there when it arrives, as long as the focus still rests on the ✕;
+  `action` — a confirm, where the least destructive button takes `autoFocus`; `close` — anything to read,
+  browse or manage. [WAI-ARIA APG]
+- **The header and the footer are fixed; only the body scrolls,** with the B9 fade at each edge, so the
+  primary action stays on screen when the on-screen keyboard takes half of it (the viewport's
+  `interactive-widget=resizes-content` makes the keyboard shrink the layout, where Chrome would otherwise
+  slide it over a fixed dialog). A fade shows only while content is under it (the body's scroll timeline):
+  a dialog that fits draws none. [Nielsen #3, WCAG 2.4.11]
+- **The footer is the dialog's commit row** — Cancel / Save, Start, Retry / Close, a confirm's choices —
+  placed with `ModalFooter` from any depth of the body. A section's own buttons (a sub-form inside a
+  manager, a list row's Delete) stay in the body; a manager with no commit row has no footer.
+
+## Copy — _Decided_ (S3g)
+
+- Every user-facing string is in both Hungarian and English with zero key drift, and a user-facing error is
+  a structured `{code, reason}` translated on the client. Hungarian speaks to the user as "te".
+- **One name per feature.** The nav rail's label is the feature's name; page titles, menus, shortcuts,
+  settings tabs and onboarding use the same words. The rail may shorten them ("Config" for
+  "Configuration", "Listák" for "Lejátszási listák"), never swap in another word. [Nielsen #4]
+- **One verb per meaning.** Delete / Törlés: gone for good. Remove / Eltávolítás: out of a list, the
+  thing itself survives. Dismiss / Elrejtés: a notice leaves the view. Discard / Elvetés: unsaved edits
+  are thrown away. A confirm uses its action's verb. [Nielsen #4]
+- **Sentence case.** Capitals only for brand names (YouTube, Plex, Google) and the app's places used as
+  places ("Hide from Feed", "Megnézés a Könyvtárban"). [Material, HIG]
+- **"…" when the command asks first.** A label ends in "…" when it opens a dialog, form or picker before
+  anything happens ("Edit tags…"); not on a submenu (its chevron says it) or an immediate action. Progress
+  text ("Loading…") keeps its own. [HIG, Windows]
+- **Messages.** A toast or error of one sentence has no full stop and no "✓": "Couldn't sync
+  subscriptions" / "Nem sikerült szinkronizálni". Two sentences keep their stops. Help text is prose.
+- **Quotes** around a name are curly: “abc” in English, „abc” in Hungarian.
+- **Dates**, in the UI language, only from `lib/format.ts` (lint: `local/date-format`): recency in a list
+  is relative ("3d ago" / "3 napja") through `ui/RelativeTime`, which carries the exact minute on hover;
+  a date is "Sep 27, 2026" / "2026. szept. 27."; a moment "Sep 27, 2026, 08:30 AM" /
+  "2026. szept. 27. 08:30"; seconds only in the server log, the audit and the recorder.
+- **Units.** A figure with a unit (a length, a countdown, a range of days) is the browser's short form
+  (`Intl`), through `formatUnit` / `formatRuntime`: "90 min", "2 hr 13 min" / "90 p", "2 ó 13 p"; a fixed
+  label holding one is written in that same form ("Under 90 min"). Never a bare letter ("90m", "24h",
+  "7d"; test-held). In a sentence, and in a list of time spans named in words ("24 hours", "1 week"), the
+  unit is a word. A clock-style length on a picture stays "2:34:11".
+- A label says what happens ("Delete playlist"), not "OK"; a destructive confirm names the object.
+
+## Anti-patterns
+
+- A flat `bg-card` / `bg-surface` box where a glass surface belongs.
+- A hand-rolled control that restyles what a primitive already does.
+- Information or actions that exist only on hover, or only behind a right-click.
+- A click handler on text that swallows the user's text selection.
+- A colour literal, a px font size, a px-frozen box.
+- An empty state shown for an error.
+
+## 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-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                                                                                                         |
@@ -3,6 +3,17 @@
 How to run Siftlode locally and pass the gate. Conventions for the backend code itself live in
 [`backend/app/README.md`](../backend/app/README.md).

+## Node
+
+One major, everywhere. `.nvmrc` pins it; the CI container, the `Dockerfile`'s frontend build stage,
+`frontend/package.json`'s `engines` and `@types/node` must all match it — and so must the machine you
+run the gate on. `frontend/src/lib/nodeEngine.contract.test.ts` fails the gate the moment any of them
+drift apart, including when yours is the odd one out. `nvm use` in the repo root picks it up.
+
+This is a contract, not a preference: tsc and vitest read the engine's own `Intl` and web APIs, and
+those change between majors — the same currency format renders `$160M` on one and `$160.0M` on the
+next. A gate that is green on a major you do not ship is green about nothing.
+
 ## Run it locally

 The whole stack (Postgres + API + worker) comes up from the localdev compose file:
@@ -21,6 +32,10 @@ For a fast frontend edit loop, run the Vite dev server with HMR against that API
 cd frontend && npm install && npm run dev   # http://localhost:5173, proxying the API on :8080
 ```

+The dev server also serves the **design lab** at `http://localhost:5173/design-lab`: the open design
+decisions and the chosen patterns, rendered with the app's real CSS. It never reaches a production build
+(see [`DESIGN.md`](DESIGN.md)).
+
 ## The gate

 A change is done when all of this is green. CI runs the same checks server-side
@@ -0,0 +1,29 @@
+import type { Plugin } from "vite";
+
+// The design lab (`src/design-lab/`) is a dev-only page: main.tsx reaches it behind
+// `import.meta.env.DEV`, which Vite folds to `false` in a production build, so the dynamic import
+// is dead code and the chunk is never emitted. That rule used to be a sentence; this makes it a
+// build failure. If a future edit imports the lab unguarded (a static import, a shared helper, a
+// re-export), the production build refuses instead of shipping the lab to every visitor.
+const DEV_ONLY_DIR = "/src/design-lab/";
+
+export function devOnlyGuard(): Plugin {
+  return {
+    name: "siftlode-dev-only-guard",
+    apply: "build",
+    generateBundle(_options, bundle) {
+      for (const [fileName, output] of Object.entries(bundle)) {
+        if (output.type !== "chunk") continue;
+        const leaked = Object.keys(output.modules).find((id) =>
+          id.replaceAll("\\", "/").includes(DEV_ONLY_DIR),
+        );
+        if (leaked) {
+          this.error(
+            `dev-only module ${leaked} reached the production bundle (${fileName}). ` +
+              "Import src/design-lab only behind `import.meta.env.DEV`.",
+          );
+        }
+      }
+    },
+  };
+}
@@ -46,7 +46,8 @@ user), reset to a deterministic baseline every run by
 [`scripts/e2e_seed.py`](../../scripts/e2e_seed.py) (run
 in-container so it reuses the app's models + argon2 hasher): the top-3 organic channels subscribed,
 one in-progress + one watched + one saved video, prefs pinned to `language: en`. Credentials come
-from `E2E_EMAIL` / `E2E_PASSWORD` (local-only defaults). Override the container name with
+from `E2E_EMAIL` (default `e2e@siftlode.local`) and `E2E_PASSWORD` — **required, no default**: run
+the suite through the ops wrapper, which exports it from the secret store. Override the container name with
 `E2E_API_CONTAINER`; skip the in-container seed with `E2E_SKIP_SEED=1`.

 ## Selectors
@@ -14,7 +14,9 @@ import { fileURLToPath } from "node:url";

 const STORAGE = "e2e/.auth/state.json";
 const EMAIL = process.env.E2E_EMAIL || "e2e@siftlode.local";
-const PASSWORD = process.env.E2E_PASSWORD || "e2e-golden-master";
+// No default: a password committed to a public repo is not a credential. The ops wrapper
+// (`siftlode e2e` / `check-full`) exports it from the secret store.
+const PASSWORD = process.env.E2E_PASSWORD ?? "";
 const CONTAINER = process.env.E2E_API_CONTAINER || "siftlode-api-1";
 const BASE_URL = process.env.PW_BASE_URL || "http://127.0.0.1:8080";

@@ -25,6 +27,11 @@ const SEED_SCRIPT = resolve(HERE, "../../scripts/e2e_seed.py");
 const isLocalTarget = /\/\/(127\.0\.0\.1|localhost)[:/]/.test(BASE_URL);

 setup("seed + authenticate", async ({ page }) => {
+  expect(
+    PASSWORD,
+    "E2E_PASSWORD is not set — run the suite through `siftlode e2e` (it reads the secret store)",
+  ).not.toBe("");
+
  // 1. Preflight: fail fast (with a useful message) if the stack isn't running.
  const health = await page.request.get("/healthz");
  expect(
@@ -69,7 +69,7 @@ const focusSafeDisabled = {
  meta: {
    type: "problem",
    messages: {
-      raw: "A raw <button disabled> throws a focused user to <body> when it turns disabled. Use ui/FocusSafeButton (or ui/Button).",
+      raw: "A raw <button disabled> throws a focused user to <body> when it turns disabled. Build the primitive on ui/FocusSafeButton; anywhere else use ui/Button, IconButton or Pressable.",
    },
  },
  create(context) {
@@ -82,6 +82,199 @@ const focusSafeDisabled = {
    };
  },
 };
+// E28 S3g (docs/DESIGN.md "Copy"): the app shows a date in three forms plus the relative one, all
+// built in lib/format.ts in the UI language. A bare `toLocaleString()` formats in the BROWSER's locale
+// and as numbers with seconds; seven call sites had drifted into five shapes. Outside lib/format.ts
+// a `toLocale*String` call or an `Intl.DateTimeFormat` / `Intl.RelativeTimeFormat` is refused (a
+// number goes through formatNumber, which the same rule covers).
+const dateFormat = {
+  meta: {
+    type: "problem",
+    messages: {
+      date: "Format dates and numbers through lib/format.ts (formatDate, formatDateTime, formatDateTimeSec, relativeTime, formatNumber), in the UI language.",
+    },
+  },
+  create(context) {
+    const path = context.filename.split("\\").join("/");
+    // lib/format.ts is where the forms live; a test computes its expectations; the Plex player's
+    // on-screen clock (lib/plexPlayerPrefs.ts) is a clock face with its own 12/24h switch, not a date.
+    if (/\/src\/lib\/(format|plexPlayerPrefs)\.ts$|\.test\.tsx?$/.test(path)) return {};
+    return {
+      "CallExpression > MemberExpression.callee[property.name=/^toLocale(Date|Time)?String$/]"(
+        node,
+      ) {
+        context.report({ node, messageId: "date" });
+      },
+      "MemberExpression[object.name='Intl'][property.name=/^(DateTimeFormat|RelativeTimeFormat)$/]"(
+        node,
+      ) {
+        context.report({ node, messageId: "date" });
+      },
+    };
+  },
+};
+// E28 S3b: one primitive per button family (docs/DESIGN.md). 268 hand-rolled buttons in 79 files had
+// drifted into as many looks, heights and hover styles; they were swept onto ui/Button, IconButton,
+// Pressable, Chip and DragHandle, and this keeps the next one out. The raw element lives only in the
+// files that ARE a control primitive — not in the rest of components/ui/, whose composites (a pager, a
+// side panel, a toast) are built from the primitives like any feature component.
+const BUTTON_PRIMITIVES = new Set([
+  "FocusSafeButton.tsx", // the focus-keeping <button> everything stands on
+  "Button.tsx",
+  "IconButton.tsx",
+  "Pressable.tsx",
+  "Chip.tsx",
+  "DragHandle.tsx",
+  "AnchoredPopover.tsx", // the menu row: floating-ui's roving focus reads its native `disabled`
+  "SegmentedToggle.tsx",
+  "Tabs.tsx",
+  "form.tsx", // Switch
+  "PriorityStepper.tsx",
+  "SortControl.tsx",
+  "SelectTrigger.tsx", // the dropdown trigger (A5)
+  "FilterSelect.tsx", // its option rows
+  "Combobox.tsx", // the field's chevron (A4)
+]);
+const buttonPrimitive = {
+  meta: {
+    type: "problem",
+    messages: {
+      raw: "A raw <{{name}}> outside the control primitives: use ui/Button (a labelled action), IconButton (a glyph), Pressable (a card or row that is the control), Chip or DragHandle.",
+      role: 'A <{{name}} role="button"> is a hand-built button (its own Enter/Space, no focus-safe disabled, no touch target): use ui/Pressable for a surface that is the control.',
+    },
+  },
+  create(context) {
+    const path = context.filename.split("\\").join("/");
+    const file = path.slice(path.lastIndexOf("/") + 1);
+    if (path.includes("/src/components/ui/") && BUTTON_PRIMITIVES.has(file)) return {};
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== "JSXIdentifier") return;
+        const name = node.name.name;
+        if (name === "button" || name === "FocusSafeButton")
+          context.report({ node, messageId: "raw", data: { name } });
+        // S3g: the same button spelled as a div with a role slipped past the rule above (my own
+        // S3h Plex picture). A component (capitalised) may take a role for its own reasons.
+        else if (
+          /^[a-z]/.test(name) &&
+          node.attributes.some(
+            (a) =>
+              a.type === "JSXAttribute" &&
+              a.name.name === "role" &&
+              a.value?.type === "Literal" &&
+              a.value.value === "button",
+          )
+        )
+          context.report({ node, messageId: "role", data: { name } });
+      },
+    };
+  },
+};
+// The same for a text field and the native checkbox / slider / colour well (docs/DESIGN.md A4, A6;
+// E28 S3c): ~100 hand-styled boxes carried six edges, four radii and two focus looks between them. A
+// file picker has no look (it is hidden behind a Button), so it passes.
+const INPUT_PRIMITIVES = new Set([
+  "Input.tsx",
+  "NativeControls.tsx",
+  "PriorityStepper.tsx", // the number box laid over the stepper's own face
+]);
+const inputPrimitive = {
+  meta: {
+    type: "problem",
+    messages: {
+      raw: "A raw <{{name}}> outside the field primitives: use ui/Input, Textarea or InnerInput (inside a fieldClass frame), or Checkbox / CheckRow / Slider / ColorInput.",
+    },
+  },
+  create(context) {
+    const path = context.filename.split("\\").join("/");
+    const file = path.slice(path.lastIndexOf("/") + 1);
+    if (path.includes("/src/components/ui/") && INPUT_PRIMITIVES.has(file)) return {};
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== "JSXIdentifier") return;
+        const name = node.name.name;
+        if (name !== "input" && name !== "textarea") return;
+        const type = node.attributes.find(
+          (a) => a.type === "JSXAttribute" && a.name.name === "type",
+        );
+        const v = type?.value?.type === "Literal" ? type.value.value : null;
+        if (name === "input" && (v === "file" || v === "hidden")) return;
+        context.report({ node, messageId: "raw", data: { name } });
+      },
+    };
+  },
+};
+// B5 (docs/DESIGN.md; E28 S3d): a glass surface is a ROLE from ui/surfaces.ts, which brings its radius.
+// ~140 sites had paired the three glass tiers with five radii and three menu paddings. A class string
+// (two or more tokens, so `variant="glass"` passes) holding a bare glass tier is refused outside the
+// role table and the control primitives that paint a glass BUTTON face.
+const SURFACE_OWNERS = new Set([
+  "surfaces.ts",
+  "buttonStyles.ts", // the `glass` button face
+  "SelectTrigger.tsx",
+  "fieldStyles.ts", // the header search floats over the page
+]);
+const GLASS_TIER = /^glass(-card|-menu)?$/;
+// A glass surface's depth is its own box-shadow, whose inset top highlight a `shadow-*` utility would
+// replace wholesale (the header search and the debug pill lost theirs). A shadow COLOUR only sets a
+// variable, and `shadow-float` IS the surface's shadow, so both pass.
+const SHADOW_SIZE = /^shadow-(xs|sm|md|lg|xl|2xl|\[.+\]|\(.+\))$/;
+const isShadowSize = (w) => SHADOW_SIZE.test(w.slice(w.lastIndexOf(":") + 1));
+const isSurfaceRole = (n) =>
+  n?.type === "MemberExpression" && n.object.type === "Identifier" && n.object.name === "SURFACE";
+const surfaceRole = {
+  meta: {
+    type: "problem",
+    messages: {
+      raw: "A bare `{{tier}}` class: use a role from ui/surfaces.ts (SURFACE.panel / drawer / card / menu / popover / tooltip), which brings the radius too.",
+      shadow:
+        "`{{shadow}}` on a glass surface replaces its own shadow and drops the top highlight; the role's depth is the intended one.",
+    },
+  },
+  create(context) {
+    const path = context.filename.split("\\").join("/");
+    const file = path.slice(path.lastIndexOf("/") + 1);
+    if (path.includes("/src/components/ui/") && SURFACE_OWNERS.has(file)) return {};
+    if (path.includes("/src/lib/")) return {}; // no classes live there, only prose ("a glass tuner")
+    const check = (node, text) => {
+      if (typeof text !== "string") return;
+      const words = text.split(/\s+/).filter(Boolean);
+      // A lone word is a value (`variant="glass"`); a class string has company, or is a template
+      // fragment that a space joins to its neighbour.
+      if (words.length < 2 && text === text.trim()) return;
+      const tier = words.find((w) => GLASS_TIER.test(w));
+      if (tier) context.report({ node, messageId: "raw", data: { tier } });
+    };
+    // A role plus a shadow size in one class list: `${SURFACE.x} shadow-lg` or clsx(SURFACE.x, "shadow-lg").
+    const shadowBeside = (node, parts) => {
+      if (!parts.some(isSurfaceRole)) return;
+      for (const part of parts) {
+        const text =
+          part.type === "TemplateElement"
+            ? part.value.cooked
+            : part.type === "Literal" && typeof part.value === "string"
+              ? part.value
+              : "";
+        const shadow = text.split(/\s+/).find(isShadowSize);
+        if (shadow) context.report({ node, messageId: "shadow", data: { shadow } });
+      }
+    };
+    return {
+      Literal(node) {
+        check(node, node.value);
+      },
+      TemplateElement(node) {
+        check(node, node.value.cooked);
+      },
+      TemplateLiteral(node) {
+        shadowBeside(node, [...node.quasis, ...node.expressions]);
+      },
+      CallExpression(node) {
+        shadowBeside(node, node.arguments);
+      },
+    };
+  },
+};
 // The words a screen reader or a tooltip says are user-facing text like any other, and the HU/EN
 // parity rule covers them too. Five `aria-label="remove"`-style literals survived every lane (the
 // Plex playlist rows, a filter chip, the player's reset) and a whole opt-in panel was English only —
@@ -152,11 +345,46 @@ const sortableA11y = {
    };
  },
 };
+// An <a> whose content is only a glyph is a link that looks like a button (DESIGN.md): `IconLink`, with
+// a name, a 24+ box and the icon button's layer. The E28 audit found five bare 14px ones. Text or an
+// expression anywhere in its CHILDREN (not its attributes: every link has an `href={…}`) is a text
+// link or a card, and passes; a self-closing <a> is a `Trans` slot that i18n fills with text.
+const glyphLink = {
+  meta: {
+    type: "problem",
+    messages: {
+      glyph:
+        "a glyph-only <a> is a link that looks like a button: use ui/LinkButton's IconLink (a name, a 24+ box, the state layer).",
+    },
+  },
+  create(context) {
+    const hasText = (children) =>
+      children.some(
+        (c) =>
+          (c.type === "JSXText" && /\S/.test(c.value)) ||
+          (c.type === "JSXExpressionContainer" && c.expression.type !== "JSXEmptyExpression") ||
+          ((c.type === "JSXElement" || c.type === "JSXFragment") && hasText(c.children)),
+      );
+    return {
+      JSXElement(node) {
+        const open = node.openingElement;
+        if (open.name.type !== "JSXIdentifier" || open.name.name !== "a" || open.selfClosing)
+          return;
+        if (!hasText(node.children)) context.report({ node: open, messageId: "glyph" });
+      },
+    };
+  },
+};
 const localRules = {
  rules: {
+    "glyph-link": glyphLink,
    "sortable-a11y": sortableA11y,
    "jsx-comment-text": jsxCommentText,
    "focus-safe-disabled": focusSafeDisabled,
+    "button-primitive": buttonPrimitive,
+    "date-format": dateFormat,
+    "input-primitive": inputPrimitive,
+    "surface-role": surfaceRole,
    "literal-a11y-text": literalA11yText,
  },
 };
@@ -167,6 +395,43 @@ const BOX_PX =
  "/(^|[\\s:])(min-|max-)?(w|h|size|left|right|top|bottom|inset|gap|p[xytrbl]?|m[xytrbl]?)-\\[[\\d.]+px\\]/";
 const BOX_PX_MESSAGE =
  "px-frozen box size doesn't scale with --font-scale: use the spacing scale (w-37.5, max-w-60), not w-[Npx].";
+// A stacking order outside the layer scale (DESIGN.md Tokens: `base < menu < chrome < … < tooltip` in
+// index.css). A numeric `z-10` equals a level today but doesn't follow it when the scale moves; name it.
+const Z_RAW = "/(^|[\\s:])-?z-([1-9]\\d*|\\[[^\\]]+\\])(?![\\w-])/";
+const Z_RAW_MESSAGE =
+  "z-index off the layer scale: use a named level (z-under, z-base, z-menu, z-chrome, z-panel, z-rail, z-overlay, z-popover, z-tooltip), not z-N or z-[…].";
+
+// A hover that swaps a colour instead of laying the B3 state layer (DESIGN.md Tokens): `bg-card`,
+// `bg-border` and `bg-surface` vanish on a light card, an opacity dim reads as "disabled", and
+// `bg-(--hover)` restates the `state-layer` utility by hand. `group-hover:` (a reveal on a parent's
+// hover, C1) and an edged pill's accent hover (F14) are not matched.
+const HOVER_SWAP =
+  "/(^|[\\s:])hover:(bg-(card|border|surface|muted)(?![\\w-])|bg-\\(--(hover|press)\\)|opacity-)/";
+const HOVER_SWAP_MESSAGE =
+  "hover by a colour swap: use the B3 layer (`state-layer`, Pressable `layer`, `state-filled` on a fill), not hover:bg-card / bg-border / opacity-N.";
+
+// A palette colour (DESIGN.md Tokens "only semantic tokens", audit F16): nothing measures `text-amber-500`,
+// so a gold that reads on dark ships at 2:1 on light. Black and white are not matched: they are the
+// media scrims and the text on them, the same in every theme.
+const PALETTE =
+  "/(^|[\\s:])(text|bg|border|fill|stroke|from|via|to|ring|outline|decoration|divide|caret|shadow)-(red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone)-\\d/";
+const PALETTE_MESSAGE =
+  "a palette colour: use a semantic token (text-rating, bg-live, bg-media-chrome, text-danger, …; DESIGN.md Tokens), not text-amber-500.";
+
+// A static label with an edge (DESIGN.md "Static vs pressable", audit F29): a <span> drawn round with a
+// border reads as a chip, is clicked and does nothing. A label that does nothing is ui/Badge (flat).
+// A small `rounded` box (a check mark drawn inside a menu row) is a glyph, not a label: only the label
+// radii match.
+const EDGED_LABEL = "/^(?=.*(^|\\s)rounded-(full|md|lg|xl|2xl)(\\s|$))(?=.*(^|\\s)border(\\s|$))/";
+const EDGED_LABEL_MESSAGE =
+  "a static label with an edge reads as a pressable chip: use ui/Badge (flat, tonal) for a label that does nothing.";
+
+// A class name split by an interpolation: the text right after `${…}` starts with a variant (`hover:`),
+// or the interpolation IS the variant and the text goes on with its class (`${NARROW}:w-24`, E28 S3f3).
+// A clock (`${m}:00`) and a URL (`${u}://`) are not classes.
+const SPLIT_CLASS = "/^([a-z][\\w-]*:[\\w\\[!-]|:[a-z\\[!])/";
+const SPLIT_CLASS_MESSAGE =
+  "a class split by an interpolation (`${x}hover:…`): Tailwind never sees it whole and emits no CSS; write the class literally (a shared guard is the `act:` variant).";

 export default tseslint.config(
  { ignores: ["dist", "node_modules", "playwright-report", "test-results", "e2e/.auth"] },
@@ -187,9 +452,36 @@ export default tseslint.config(
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
+      // eslint-plugin-react-hooks 7's `recommended` is no longer two rules — it carries the whole
+      // React Compiler rule set (E27 S1). On this codebase that landed 283 findings, and they were
+      // triaged rather than bulk-suppressed, because the two answers are different:
+      //
+      //   react-hooks/refs  217 — OFF, see below.
+      //   the other 66      — real. They went into eslint-suppressions.json as a ratchet for one
+      //                       sprint and E27 S2 burned the file down to nothing: what survives is
+      //                       an inline directive at the site, each naming the invariant it
+      //                       protects. There is DELIBERATELY no suppressions file any more — a
+      //                       bulk `--suppress-all` would hide the next violation instead of
+      //                       answering it, and it cannot hold a warning-level rule anyway.
+      //
+      // `refs` is off because it fires on this app's popover architecture, not on its history, so
+      // suppressing it would not help the next popover anyone writes. Measured over the 217:
+      // 79 are `pop.refs.setReference` / `getReferenceProps` — @floating-ui/react's callback-ref
+      // setters, which are the documented way to use it — and 74 more are passing the popover handle
+      // down as a prop (`popover={pop}`, `ref={fade.ref}`), which is what `components/ui`'s popover
+      // engine is FOR. That is 153 of 217 flagged for having the word `refs` in an object that is not
+      // a React ref. The remaining ~64 are genuine render-phase `someRef.current = x` writes and are
+      // real (E27 S2 answered the ones the other rules could see, at their sites).
+      // Re-evaluate when the rule can: it shipped in 1.0.0 and this looks like over-approximation.
+      "react-hooks/refs": "off",
      "local/jsx-comment-text": "error",
      "local/focus-safe-disabled": "error",
+      "local/button-primitive": "error",
+      "local/date-format": "error",
+      "local/input-primitive": "error",
+      "local/surface-role": "error",
      "local/literal-a11y-text": "error",
+      "local/glyph-link": "error",
      "local/sortable-a11y": "error",
      "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
      // tsc already enforces these under strict + noUnusedLocals/Parameters — let it own them so a
@@ -221,12 +513,19 @@ export default tseslint.config(
        {
          selector: "Literal[value=/(^|\\s)enabled:hover:/]",
          message:
-            "`enabled:hover:` misses a focused FocusSafeButton (aria-disabled): use `enabled:not-aria-disabled:hover:`.",
+            "`enabled:hover:` misses a focused FocusSafeButton (aria-disabled): use `act:hover:` (index.css).",
        },
        {
          selector: "TemplateElement[value.raw=/(^|\\s)enabled:hover:/]",
          message:
-            "`enabled:hover:` misses a focused FocusSafeButton (aria-disabled): use `enabled:not-aria-disabled:hover:`.",
+            "`enabled:hover:` misses a focused FocusSafeButton (aria-disabled): use `act:hover:` (index.css).",
+        },
+        // Tailwind emits CSS only for a class it finds WHOLE in the source. A variant glued onto an
+        // interpolated prefix (`${ACT}hover:text-fg`) is never found, so it ships with no rule: every
+        // hover colour of the button and chip primitives was dead that way (E28 audit).
+        {
+          selector: `TemplateLiteral > TemplateElement:not(:first-child)[value.raw=${SPLIT_CLASS}]`,
+          message: SPLIT_CLASS_MESSAGE,
        },
        // The canonical "FE control" row (CLAUDE.md): a short fixed set is a SegmentedToggle, a
        // longer one or a user's own list a FilterSelect. Six native selects had drifted in; the
@@ -255,6 +554,20 @@ export default tseslint.config(
        // 150px at the default size) — 32 of these were swept in the 2026-09 debt burn.
        { selector: `Literal[value=${BOX_PX}]`, message: BOX_PX_MESSAGE },
        { selector: `TemplateElement[value.raw=${BOX_PX}]`, message: BOX_PX_MESSAGE },
+        { selector: `Literal[value=${Z_RAW}]`, message: Z_RAW_MESSAGE },
+        { selector: `TemplateElement[value.raw=${Z_RAW}]`, message: Z_RAW_MESSAGE },
+        { selector: `Literal[value=${HOVER_SWAP}]`, message: HOVER_SWAP_MESSAGE },
+        { selector: `TemplateElement[value.raw=${HOVER_SWAP}]`, message: HOVER_SWAP_MESSAGE },
+        { selector: `Literal[value=${PALETTE}]`, message: PALETTE_MESSAGE },
+        { selector: `TemplateElement[value.raw=${PALETTE}]`, message: PALETTE_MESSAGE },
+        {
+          selector: `JSXOpeningElement[name.name='span'] JSXAttribute[name.name='className'] Literal[value=${EDGED_LABEL}]`,
+          message: EDGED_LABEL_MESSAGE,
+        },
+        {
+          selector: `JSXOpeningElement[name.name='span'] JSXAttribute[name.name='className'] TemplateElement[value.raw=${EDGED_LABEL}]`,
+          message: EDGED_LABEL_MESSAGE,
+        },
      ],
    },
  },
@@ -335,6 +648,13 @@ export default tseslint.config(
    files: ["src/components/ui/FocusSafeButton.tsx", "src/components/ui/AnchoredPopover.tsx"],
    rules: { "local/focus-safe-disabled": "off" },
  },
+  {
+    // The design lab (src/design-lab, E28) is a dev-only page that never reaches the production
+    // bundle (devOnlyGuard fails the build if it does). Its copy is the developer's and the product
+    // owner's working text, not the product's, so the translate-every-label rule does not apply.
+    files: ["src/design-lab/**/*.{ts,tsx}"],
+    rules: { "local/literal-a11y-text": "off" },
+  },
  {
    // Tests stand doubles in for the network (`vi.stubGlobal("fetch", …)`) and may reach it directly.
    // …and render throwaway markup whose labels no user ever hears.
@@ -343,6 +663,11 @@ export default tseslint.config(
      "no-restricted-globals": "off",
      "no-restricted-properties": "off",
      "local/literal-a11y-text": "off",
+      // A test renders a raw button as a stand-in trigger or a focus target, not as product UI.
+      "local/button-primitive": "off",
+      "local/input-primitive": "off",
+      "local/surface-role": "off",
+      "local/glyph-link": "off",
    },
  },
  prettier,
@@ -2,7 +2,13 @@
 <html lang="en" data-theme="dark" data-scheme="midnight">
  <head>
    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <!-- resizes-content: the on-screen keyboard shrinks the layout viewport, not only the visual one,
+         so a dialog's pinned footer (DESIGN C4) sits above the keyboard instead of under it. Chrome's
+         default since 108 only shrinks the visual viewport; Safari ignores the key. -->
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1, interactive-widget=resizes-content"
+    />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <!-- OG:START — the server replaces this block for /watch/{token} so shared links unfurl with
         the video's title/channel/thumbnail; every other route keeps these generic defaults. -->
@@ -5,6 +5,7 @@
  "packages": {
    "": {
      "name": "siftlode-frontend",
+      "license": "AGPL-3.0-only",
      "dependencies": {
        "@dnd-kit/core": "^6.3.1",
        "@dnd-kit/sortable": "^10.0.0",
@@ -17,22 +18,23 @@
        "hls.js": "^1.6.16",
        "i18next": "^23.11.5",
        "lucide-react": "^0.408.0",
-        "react": "^18.3.1",
-        "react-dom": "^18.3.1",
-        "react-i18next": "^14.1.2"
+        "react": "19.3.0",
+        "react-dom": "19.3.0",
+        "react-i18next": "^15.7.4"
      },
      "devDependencies": {
        "@eslint/js": "9.39.1",
        "@playwright/test": "^1.61.1",
        "@tailwindcss/postcss": "^4.3.3",
        "@testing-library/react": "^16.3.2",
-        "@types/node": "^26.1.1",
-        "@types/react": "^18.3.3",
-        "@types/react-dom": "^18.3.0",
+        "@types/node": "^24.13.6",
+        "@types/react": "19.3.0",
+        "@types/react-dom": "19.3.0",
        "@vitejs/plugin-react": "^4.3.1",
+        "babel-plugin-react-compiler": "1.0.0",
        "eslint": "9.39.1",
        "eslint-config-prettier": "10.1.8",
-        "eslint-plugin-react-hooks": "5.2.0",
+        "eslint-plugin-react-hooks": "7.1.1",
        "eslint-plugin-react-refresh": "0.4.24",
        "globals": "16.5.0",
        "jsdom": "^25.0.1",
@@ -44,6 +46,9 @@
        "typescript-eslint": "8.46.0",
        "vite": "^5.3.4",
        "vitest": "^3.2.7"
+      },
+      "engines": {
+        "node": "24.x"
      }
    },
    "node_modules/@alloc/quick-lru": {
@@ -2909,41 +2914,33 @@
      "license": "MIT"
    },
    "node_modules/@types/node": {
-      "version": "26.1.1",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.1.1.tgz",
-      "integrity": "sha512-nxAkRSVkN1Y0JC1W8ky/fTfkGsMmcrRsbx+3XoZE+rMOX71kLYTV7fLXpqud1GpbpP5TuffXFqfX7fH2GgZREw==",
+      "version": "24.13.6",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.13.6.tgz",
+      "integrity": "sha512-SGrw/h3KPFshy3OE6ZL53LMBG5vGQQ8/gIpiqz/kRZhPJ7HgwCEs8LBuNtWLa8dvGZVpSF7+Bf+c11HUrCb/yg==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "undici-types": "~8.3.0"
+        "undici-types": "~7.18.0"
      }
    },
-    "node_modules/@types/prop-types": {
-      "version": "15.7.15",
-      "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz",
-      "integrity": "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==",
-      "dev": true,
-      "license": "MIT"
-    },
    "node_modules/@types/react": {
-      "version": "18.3.31",
-      "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.31.tgz",
-      "integrity": "sha512-vfEqpXTvwT91yhmwdfouStN2hSKwTvyRs8qpLfADyrq/kxDw0hZM7Wk9Ug1FELj8hIby+S/+kQCSRFF32nv2Qw==",
+      "version": "19.3.0",
+      "resolved": "https://registry.npmjs.org/@types/react/-/react-19.3.0.tgz",
+      "integrity": "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@types/prop-types": "*",
        "csstype": "^3.2.2"
      }
    },
    "node_modules/@types/react-dom": {
-      "version": "18.3.7",
-      "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-18.3.7.tgz",
-      "integrity": "sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ==",
+      "version": "19.3.0",
+      "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.3.0.tgz",
+      "integrity": "sha512-ZI7bU42mZXXKHn/qNLEw2IrbiINU7X5+vfgdixBHkCNpYWXjKgfQ/P+uyGb5CjOLB9UcnTeg3rylQtV2hym44Q==",
      "dev": true,
      "license": "MIT",
      "peerDependencies": {
-        "@types/react": "^18.0.0"
+        "@types/react": "^19.3.0"
      }
    },
    "node_modules/@typescript-eslint/eslint-plugin": {
@@ -3465,6 +3462,16 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/babel-plugin-react-compiler": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/babel-plugin-react-compiler/-/babel-plugin-react-compiler-1.0.0.tgz",
+      "integrity": "sha512-Ixm8tFfoKKIPYdCCKYTsqv+Fd4IJ0DQqMyEimo+pxUOMUR9cVPlwTrFt9Avu+3cb6Zp3mAzl+t1MrG2fxxKsxw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.26.0"
+      }
+    },
    "node_modules/balanced-match": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
@@ -4080,16 +4087,23 @@
      }
    },
    "node_modules/eslint-plugin-react-hooks": {
-      "version": "5.2.0",
-      "resolved": "https://registry.npmjs.org/eslint-plugin-react-hooks/-/eslint-plugin-react-hooks-5.2.0.tgz",
-      "integrity": "sha512-+f15FfK64YQwZdJNELETdn5ibXEUQmW1DZL6KXhNnc2heoy/sg9VJJeT7n8TlMWouzWqSWavFkIhHyIbIAEapg==",
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-react-hooks/-/eslint-plugin-react-hooks-7.1.1.tgz",
+      "integrity": "sha512-f2I7Gw6JbvCexzIInuSbZpfdQ44D7iqdWX01FKLvrPgqxoE7oMj8clOfto8U6vYiz4yd5oKu39rRSVOe1zRu0g==",
      "dev": true,
      "license": "MIT",
+      "dependencies": {
+        "@babel/core": "^7.24.4",
+        "@babel/parser": "^7.24.4",
+        "hermes-parser": "^0.25.1",
+        "zod": "^3.25.0 || ^4.0.0",
+        "zod-validation-error": "^3.5.0 || ^4.0.0"
+      },
      "engines": {
-        "node": ">=10"
+        "node": ">=18"
      },
      "peerDependencies": {
-        "eslint": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0 || ^9.0.0"
+        "eslint": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0 || ^9.0.0 || ^10.0.0"
      }
    },
    "node_modules/eslint-plugin-react-refresh": {
@@ -4582,6 +4596,23 @@
        "node": ">= 0.4"
      }
    },
+    "node_modules/hermes-estree": {
+      "version": "0.25.1",
+      "resolved": "https://registry.npmjs.org/hermes-estree/-/hermes-estree-0.25.1.tgz",
+      "integrity": "sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/hermes-parser": {
+      "version": "0.25.1",
+      "resolved": "https://registry.npmjs.org/hermes-parser/-/hermes-parser-0.25.1.tgz",
+      "integrity": "sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "hermes-estree": "0.25.1"
+      }
+    },
    "node_modules/hls.js": {
      "version": "1.6.16",
      "resolved": "https://registry.npmjs.org/hls.js/-/hls.js-1.6.16.tgz",
@@ -4772,6 +4803,7 @@
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
      "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
+      "dev": true,
      "license": "MIT"
    },
    "node_modules/js-yaml": {
@@ -5275,18 +5307,6 @@
      "dev": true,
      "license": "MIT"
    },
-    "node_modules/loose-envify": {
-      "version": "1.4.0",
-      "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
-      "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
-      "license": "MIT",
-      "dependencies": {
-        "js-tokens": "^3.0.0 || ^4.0.0"
-      },
-      "bin": {
-        "loose-envify": "cli.js"
-      }
-    },
    "node_modules/loupe": {
      "version": "3.2.1",
      "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz",
@@ -5820,42 +5840,39 @@
      "license": "MIT"
    },
    "node_modules/react": {
-      "version": "18.3.1",
-      "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
-      "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
+      "version": "19.3.0",
+      "resolved": "https://registry.npmjs.org/react/-/react-19.3.0.tgz",
+      "integrity": "sha512-E8LUcbtBWt20bbl2YoHfx4ZDBdxVTfOKtCZn9cDSJ4l6/nuoApcpIBcj47t2wZoVX8g2ZHuMHbiShgCR1T5Sog==",
      "license": "MIT",
-      "dependencies": {
-        "loose-envify": "^1.1.0"
-      },
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/react-dom": {
-      "version": "18.3.1",
-      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
-      "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
+      "version": "19.3.0",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.3.0.tgz",
+      "integrity": "sha512-JDk8dgif51OjFoDE70+OT9ICyYr+69HlmihNwp1+Nsfbna3t5sIiCa9ZJktDmQ4/1b/rn26hIAR2uYXDMr5r0Q==",
      "license": "MIT",
      "dependencies": {
-        "loose-envify": "^1.1.0",
-        "scheduler": "^0.23.2"
+        "scheduler": "^0.28.0"
      },
      "peerDependencies": {
-        "react": "^18.3.1"
+        "react": "^19.3.0"
      }
    },
    "node_modules/react-i18next": {
-      "version": "14.1.3",
-      "resolved": "https://registry.npmjs.org/react-i18next/-/react-i18next-14.1.3.tgz",
-      "integrity": "sha512-wZnpfunU6UIAiJ+bxwOiTmBOAaB14ha97MjOEnLGac2RJ+h/maIYXZuTHlmyqQVX1UVHmU1YDTQ5vxLmwfXTjw==",
+      "version": "15.7.4",
+      "resolved": "https://registry.npmjs.org/react-i18next/-/react-i18next-15.7.4.tgz",
+      "integrity": "sha512-nyU8iKNrI5uDJch0z9+Y5XEr34b0wkyYj3Rp+tfbahxtlswxSCjcUL9H0nqXo9IR3/t5Y5PKIA3fx3MfUyR9Xw==",
      "license": "MIT",
      "dependencies": {
-        "@babel/runtime": "^7.23.9",
+        "@babel/runtime": "^7.27.6",
        "html-parse-stringify": "^3.0.1"
      },
      "peerDependencies": {
-        "i18next": ">= 23.2.3",
-        "react": ">= 16.8.0"
+        "i18next": ">= 23.4.0",
+        "react": ">= 16.8.0",
+        "typescript": "^5"
      },
      "peerDependenciesMeta": {
        "react-dom": {
@@ -5863,6 +5880,9 @@
        },
        "react-native": {
          "optional": true
+        },
+        "typescript": {
+          "optional": true
        }
      }
    },
@@ -6012,13 +6032,10 @@
      }
    },
    "node_modules/scheduler": {
-      "version": "0.23.2",
-      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
-      "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==",
-      "license": "MIT",
-      "dependencies": {
-        "loose-envify": "^1.1.0"
-      }
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.28.0.tgz",
+      "integrity": "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw==",
+      "license": "MIT"
    },
    "node_modules/semver": {
      "version": "6.3.1",
@@ -6364,7 +6381,7 @@
      "version": "5.9.3",
      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
-      "dev": true,
+      "devOptional": true,
      "license": "Apache-2.0",
      "bin": {
        "tsc": "bin/tsc",
@@ -6409,9 +6426,9 @@
      }
    },
    "node_modules/undici-types": {
-      "version": "8.3.0",
-      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.3.0.tgz",
-      "integrity": "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==",
+      "version": "7.18.2",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
+      "integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==",
      "dev": true,
      "license": "MIT"
    },
@@ -6832,6 +6849,19 @@
      "funding": {
        "url": "https://github.com/sponsors/colinhacks"
      }
+    },
+    "node_modules/zod-validation-error": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/zod-validation-error/-/zod-validation-error-4.0.2.tgz",
+      "integrity": "sha512-Q6/nZLe6jxuU80qb/4uJ4t5v2VEZ44lzQjPDhYJNztRQ4wyWc6VF3D3Kb/fAuPetZQnhS3hnajCf9CsWesghLQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+      }
    }
  }
 }
@@ -3,6 +3,9 @@
  "private": true,
  "license": "AGPL-3.0-only",
  "type": "module",
+  "engines": {
+    "node": "24.x"
+  },
  "scripts": {
    "dev": "vite",
    "typecheck": "npm run typecheck:app && npm run typecheck:node && npm run typecheck:e2e",
@@ -31,22 +34,23 @@
    "hls.js": "^1.6.16",
    "i18next": "^23.11.5",
    "lucide-react": "^0.408.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "react-i18next": "^14.1.2"
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "react-i18next": "^15.7.4"
  },
  "devDependencies": {
    "@eslint/js": "9.39.1",
    "@playwright/test": "^1.61.1",
    "@tailwindcss/postcss": "^4.3.3",
    "@testing-library/react": "^16.3.2",
-    "@types/node": "^26.1.1",
-    "@types/react": "^18.3.3",
-    "@types/react-dom": "^18.3.0",
+    "@types/node": "^24.13.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
    "@vitejs/plugin-react": "^4.3.1",
+    "babel-plugin-react-compiler": "1.0.0",
    "eslint": "9.39.1",
    "eslint-config-prettier": "10.1.8",
-    "eslint-plugin-react-hooks": "5.2.0",
+    "eslint-plugin-react-hooks": "7.1.1",
    "eslint-plugin-react-refresh": "0.4.24",
    "globals": "16.5.0",
    "jsdom": "^25.0.1",
@@ -1,18 +1,18 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 1000" preserveAspectRatio="xMidYMid slice">
  <defs>
-    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#7a1620" stop-opacity=".9"/><stop offset="100%" stop-color="#7a1620" stop-opacity="0"/></radialGradient>
-    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#ff3b46" stop-opacity=".4"/><stop offset="100%" stop-color="#ff3b46" stop-opacity="0"/></radialGradient>
-    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#3a0d24" stop-opacity=".9"/><stop offset="100%" stop-color="#3a0d24" stop-opacity="0"/></radialGradient>
-    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#2a1010" stop-opacity=".85"/><stop offset="100%" stop-color="#2a1010" stop-opacity="0"/></radialGradient>
+    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#1d4a66" stop-opacity=".95"/><stop offset="100%" stop-color="#1d4a66" stop-opacity="0"/></radialGradient>
+    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#337599" stop-opacity=".5"/><stop offset="100%" stop-color="#337599" stop-opacity="0"/></radialGradient>
+    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#1f2d57" stop-opacity=".9"/><stop offset="100%" stop-color="#1f2d57" stop-opacity="0"/></radialGradient>
+    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#173c52" stop-opacity=".85"/><stop offset="100%" stop-color="#173c52" stop-opacity="0"/></radialGradient>
    <filter id="s"><feGaussianBlur stdDeviation="60"/></filter>
-    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .5 0"/></filter>
+    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/></filter>
  </defs>
-  <rect width="1600" height="1000" fill="#0d0708"/>
+  <rect width="1600" height="1000" fill="#080d1a"/>
  <g filter="url(#s)">
    <rect width="1600" height="1000" fill="url(#a)"/>
    <rect width="1600" height="1000" fill="url(#c)"/>
    <rect width="1600" height="1000" fill="url(#d)"/>
    <rect width="1600" height="1000" fill="url(#b)"/>
  </g>
-  <rect width="1600" height="1000" filter="url(#g)" opacity="0.05"/>
+  <rect width="1600" height="1000" filter="url(#g)" opacity="0.35" style="mix-blend-mode:overlay"/>
 </svg>
@@ -1,11 +1,11 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 1000" preserveAspectRatio="xMidYMid slice">
  <defs>
-    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#0f5245" stop-opacity=".95"/><stop offset="100%" stop-color="#0f5245" stop-opacity="0"/></radialGradient>
-    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#2dd4bf" stop-opacity=".5"/><stop offset="100%" stop-color="#2dd4bf" stop-opacity="0"/></radialGradient>
+    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#0e4a5a" stop-opacity=".95"/><stop offset="100%" stop-color="#0e4a5a" stop-opacity="0"/></radialGradient>
+    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#22d3ee" stop-opacity=".5"/><stop offset="100%" stop-color="#22d3ee" stop-opacity="0"/></radialGradient>
    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#134a2c" stop-opacity=".9"/><stop offset="100%" stop-color="#134a2c" stop-opacity="0"/></radialGradient>
    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#0d3a52" stop-opacity=".85"/><stop offset="100%" stop-color="#0d3a52" stop-opacity="0"/></radialGradient>
    <filter id="s"><feGaussianBlur stdDeviation="60"/></filter>
-    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .5 0"/></filter>
+    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/></filter>
  </defs>
  <rect width="1600" height="1000" fill="#06120e"/>
  <g filter="url(#s)">
@@ -14,5 +14,5 @@
    <rect width="1600" height="1000" fill="url(#d)"/>
    <rect width="1600" height="1000" fill="url(#b)"/>
  </g>
-  <rect width="1600" height="1000" filter="url(#g)" opacity="0.05"/>
+  <rect width="1600" height="1000" filter="url(#g)" opacity="0.35" style="mix-blend-mode:overlay"/>
 </svg>
@@ -1,18 +1,18 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 1000" preserveAspectRatio="xMidYMid slice">
  <defs>
-    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#f0a3aa" stop-opacity=".85"/><stop offset="100%" stop-color="#f0a3aa" stop-opacity="0"/></radialGradient>
-    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#ff5b64" stop-opacity=".4"/><stop offset="100%" stop-color="#ff5b64" stop-opacity="0"/></radialGradient>
-    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#e096a8" stop-opacity=".8"/><stop offset="100%" stop-color="#e096a8" stop-opacity="0"/></radialGradient>
-    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#eec2c2" stop-opacity=".8"/><stop offset="100%" stop-color="#eec2c2" stop-opacity="0"/></radialGradient>
+    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#a8c6dc" stop-opacity=".9"/><stop offset="100%" stop-color="#a8c6dc" stop-opacity="0"/></radialGradient>
+    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#5aa1cb" stop-opacity=".5"/><stop offset="100%" stop-color="#5aa1cb" stop-opacity="0"/></radialGradient>
+    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#b9c6e0" stop-opacity=".85"/><stop offset="100%" stop-color="#b9c6e0" stop-opacity="0"/></radialGradient>
+    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#a9d0dc" stop-opacity=".8"/><stop offset="100%" stop-color="#a9d0dc" stop-opacity="0"/></radialGradient>
    <filter id="s"><feGaussianBlur stdDeviation="60"/></filter>
-    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .35 0"/></filter>
+    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/></filter>
  </defs>
-  <rect width="1600" height="1000" fill="#faeef0"/>
+  <rect width="1600" height="1000" fill="#eaf0f6"/>
  <g filter="url(#s)">
    <rect width="1600" height="1000" fill="url(#a)"/>
    <rect width="1600" height="1000" fill="url(#c)"/>
    <rect width="1600" height="1000" fill="url(#d)"/>
    <rect width="1600" height="1000" fill="url(#b)"/>
  </g>
-  <rect width="1600" height="1000" filter="url(#g)" opacity="0.04"/>
+  <rect width="1600" height="1000" filter="url(#g)" opacity="0.35" style="mix-blend-mode:overlay"/>
 </svg>
@@ -1,11 +1,11 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 1000" preserveAspectRatio="xMidYMid slice">
  <defs>
-    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#7fd0bf" stop-opacity=".9"/><stop offset="100%" stop-color="#7fd0bf" stop-opacity="0"/></radialGradient>
-    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#2dd4bf" stop-opacity=".5"/><stop offset="100%" stop-color="#2dd4bf" stop-opacity="0"/></radialGradient>
+    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#8fd3e0" stop-opacity=".9"/><stop offset="100%" stop-color="#8fd3e0" stop-opacity="0"/></radialGradient>
+    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#22d3ee" stop-opacity=".5"/><stop offset="100%" stop-color="#22d3ee" stop-opacity="0"/></radialGradient>
    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#8fc9a5" stop-opacity=".85"/><stop offset="100%" stop-color="#8fc9a5" stop-opacity="0"/></radialGradient>
    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#88c2d6" stop-opacity=".8"/><stop offset="100%" stop-color="#88c2d6" stop-opacity="0"/></radialGradient>
    <filter id="s"><feGaussianBlur stdDeviation="60"/></filter>
-    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .35 0"/></filter>
+    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/></filter>
  </defs>
  <rect width="1600" height="1000" fill="#e9f5f0"/>
  <g filter="url(#s)">
@@ -14,5 +14,5 @@
    <rect width="1600" height="1000" fill="url(#d)"/>
    <rect width="1600" height="1000" fill="url(#b)"/>
  </g>
-  <rect width="1600" height="1000" filter="url(#g)" opacity="0.04"/>
+  <rect width="1600" height="1000" filter="url(#g)" opacity="0.35" style="mix-blend-mode:overlay"/>
 </svg>
@@ -1,18 +1,18 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 1000" preserveAspectRatio="xMidYMid slice">
  <defs>
-    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#8fd8ae" stop-opacity=".9"/><stop offset="100%" stop-color="#8fd8ae" stop-opacity="0"/></radialGradient>
-    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#46b87c" stop-opacity=".45"/><stop offset="100%" stop-color="#46b87c" stop-opacity="0"/></radialGradient>
-    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#7fc9c9" stop-opacity=".85"/><stop offset="100%" stop-color="#7fc9c9" stop-opacity="0"/></radialGradient>
-    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#96d69c" stop-opacity=".8"/><stop offset="100%" stop-color="#96d69c" stop-opacity="0"/></radialGradient>
+    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#d9e2c4" stop-opacity=".9"/><stop offset="100%" stop-color="#d9e2c4" stop-opacity="0"/></radialGradient>
+    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#86a05a" stop-opacity=".35"/><stop offset="100%" stop-color="#86a05a" stop-opacity="0"/></radialGradient>
+    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#cdd6bf" stop-opacity=".85"/><stop offset="100%" stop-color="#cdd6bf" stop-opacity="0"/></radialGradient>
+    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#c3cfb3" stop-opacity=".8"/><stop offset="100%" stop-color="#c3cfb3" stop-opacity="0"/></radialGradient>
    <filter id="s"><feGaussianBlur stdDeviation="60"/></filter>
-    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .35 0"/></filter>
+    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/></filter>
  </defs>
-  <rect width="1600" height="1000" fill="#eaf5ec"/>
+  <rect width="1600" height="1000" fill="#eef0e8"/>
  <g filter="url(#s)">
    <rect width="1600" height="1000" fill="url(#a)"/>
    <rect width="1600" height="1000" fill="url(#c)"/>
    <rect width="1600" height="1000" fill="url(#d)"/>
    <rect width="1600" height="1000" fill="url(#b)"/>
  </g>
-  <rect width="1600" height="1000" filter="url(#g)" opacity="0.04"/>
+  <rect width="1600" height="1000" filter="url(#g)" opacity="0.35" style="mix-blend-mode:overlay"/>
 </svg>
@@ -5,7 +5,7 @@
    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#b3a8ec" stop-opacity=".85"/><stop offset="100%" stop-color="#b3a8ec" stop-opacity="0"/></radialGradient>
    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#9fd6e0" stop-opacity=".8"/><stop offset="100%" stop-color="#9fd6e0" stop-opacity="0"/></radialGradient>
    <filter id="s"><feGaussianBlur stdDeviation="60"/></filter>
-    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .35 0"/></filter>
+    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/></filter>
  </defs>
  <rect width="1600" height="1000" fill="#edf1fc"/>
  <g filter="url(#s)">
@@ -14,5 +14,5 @@
    <rect width="1600" height="1000" fill="url(#d)"/>
    <rect width="1600" height="1000" fill="url(#b)"/>
  </g>
-  <rect width="1600" height="1000" filter="url(#g)" opacity="0.04"/>
+  <rect width="1600" height="1000" filter="url(#g)" opacity="0.35" style="mix-blend-mode:overlay"/>
 </svg>
@@ -1,18 +1,18 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 1000" preserveAspectRatio="xMidYMid slice">
  <defs>
-    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#e6c393" stop-opacity=".9"/><stop offset="100%" stop-color="#e6c393" stop-opacity="0"/></radialGradient>
-    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#e8913c" stop-opacity=".45"/><stop offset="100%" stop-color="#e8913c" stop-opacity="0"/></radialGradient>
-    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#dba98c" stop-opacity=".85"/><stop offset="100%" stop-color="#dba98c" stop-opacity="0"/></radialGradient>
-    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#cabf9e" stop-opacity=".8"/><stop offset="100%" stop-color="#cabf9e" stop-opacity="0"/></radialGradient>
+    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#e0c2ea" stop-opacity=".9"/><stop offset="100%" stop-color="#e0c2ea" stop-opacity="0"/></radialGradient>
+    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#e879f9" stop-opacity=".45"/><stop offset="100%" stop-color="#e879f9" stop-opacity="0"/></radialGradient>
+    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#d6c0dc" stop-opacity=".85"/><stop offset="100%" stop-color="#d6c0dc" stop-opacity="0"/></radialGradient>
+    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#c9ccd6" stop-opacity=".8"/><stop offset="100%" stop-color="#c9ccd6" stop-opacity="0"/></radialGradient>
    <filter id="s"><feGaussianBlur stdDeviation="60"/></filter>
-    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .35 0"/></filter>
+    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/></filter>
  </defs>
-  <rect width="1600" height="1000" fill="#f4efe6"/>
+  <rect width="1600" height="1000" fill="#f3f1f5"/>
  <g filter="url(#s)">
    <rect width="1600" height="1000" fill="url(#a)"/>
    <rect width="1600" height="1000" fill="url(#c)"/>
    <rect width="1600" height="1000" fill="url(#d)"/>
    <rect width="1600" height="1000" fill="url(#b)"/>
  </g>
-  <rect width="1600" height="1000" filter="url(#g)" opacity="0.04"/>
+  <rect width="1600" height="1000" filter="url(#g)" opacity="0.35" style="mix-blend-mode:overlay"/>
 </svg>
@@ -1,18 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 1000" preserveAspectRatio="xMidYMid slice">
-  <defs>
-    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#8fb6e8" stop-opacity=".9"/><stop offset="100%" stop-color="#8fb6e8" stop-opacity="0"/></radialGradient>
-    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#38b6ff" stop-opacity=".45"/><stop offset="100%" stop-color="#38b6ff" stop-opacity="0"/></radialGradient>
-    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#94a0e0" stop-opacity=".85"/><stop offset="100%" stop-color="#94a0e0" stop-opacity="0"/></radialGradient>
-    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#8fc3d2" stop-opacity=".8"/><stop offset="100%" stop-color="#8fc3d2" stop-opacity="0"/></radialGradient>
-    <filter id="s"><feGaussianBlur stdDeviation="60"/></filter>
-    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .35 0"/></filter>
-  </defs>
-  <rect width="1600" height="1000" fill="#e9f1fc"/>
-  <g filter="url(#s)">
-    <rect width="1600" height="1000" fill="url(#a)"/>
-    <rect width="1600" height="1000" fill="url(#c)"/>
-    <rect width="1600" height="1000" fill="url(#d)"/>
-    <rect width="1600" height="1000" fill="url(#b)"/>
-  </g>
-  <rect width="1600" height="1000" filter="url(#g)" opacity="0.04"/>
-</svg>
@@ -1,18 +1,18 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 1000" preserveAspectRatio="xMidYMid slice">
  <defs>
-    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#0f4a30" stop-opacity=".95"/><stop offset="100%" stop-color="#0f4a30" stop-opacity="0"/></radialGradient>
-    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#46b87c" stop-opacity=".45"/><stop offset="100%" stop-color="#46b87c" stop-opacity="0"/></radialGradient>
-    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#0c3a3a" stop-opacity=".9"/><stop offset="100%" stop-color="#0c3a3a" stop-opacity="0"/></radialGradient>
-    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#164a26" stop-opacity=".85"/><stop offset="100%" stop-color="#164a26" stop-opacity="0"/></radialGradient>
+    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#34431f" stop-opacity=".95"/><stop offset="100%" stop-color="#34431f" stop-opacity="0"/></radialGradient>
+    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#86a05a" stop-opacity=".35"/><stop offset="100%" stop-color="#86a05a" stop-opacity="0"/></radialGradient>
+    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#1d2a18" stop-opacity=".9"/><stop offset="100%" stop-color="#1d2a18" stop-opacity="0"/></radialGradient>
+    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#22301c" stop-opacity=".85"/><stop offset="100%" stop-color="#22301c" stop-opacity="0"/></radialGradient>
    <filter id="s"><feGaussianBlur stdDeviation="60"/></filter>
-    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .5 0"/></filter>
+    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/></filter>
  </defs>
-  <rect width="1600" height="1000" fill="#020805"/>
+  <rect width="1600" height="1000" fill="#0a0c09"/>
  <g filter="url(#s)">
    <rect width="1600" height="1000" fill="url(#a)"/>
    <rect width="1600" height="1000" fill="url(#c)"/>
    <rect width="1600" height="1000" fill="url(#d)"/>
    <rect width="1600" height="1000" fill="url(#b)"/>
  </g>
-  <rect width="1600" height="1000" filter="url(#g)" opacity="0.05"/>
+  <rect width="1600" height="1000" filter="url(#g)" opacity="0.35" style="mix-blend-mode:overlay"/>
 </svg>
@@ -5,7 +5,7 @@
    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#3b2f80" stop-opacity=".9"/><stop offset="100%" stop-color="#3b2f80" stop-opacity="0"/></radialGradient>
    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#145e6b" stop-opacity=".85"/><stop offset="100%" stop-color="#145e6b" stop-opacity="0"/></radialGradient>
    <filter id="s"><feGaussianBlur stdDeviation="60"/></filter>
-    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .5 0"/></filter>
+    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/></filter>
  </defs>
  <rect width="1600" height="1000" fill="#070b16"/>
  <g filter="url(#s)">
@@ -14,5 +14,5 @@
    <rect width="1600" height="1000" fill="url(#d)"/>
    <rect width="1600" height="1000" fill="url(#b)"/>
  </g>
-  <rect width="1600" height="1000" filter="url(#g)" opacity="0.05"/>
+  <rect width="1600" height="1000" filter="url(#g)" opacity="0.35" style="mix-blend-mode:overlay"/>
 </svg>
@@ -1,18 +1,18 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 1000" preserveAspectRatio="xMidYMid slice">
  <defs>
-    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#7a4d18" stop-opacity=".95"/><stop offset="100%" stop-color="#7a4d18" stop-opacity="0"/></radialGradient>
-    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#e8913c" stop-opacity=".45"/><stop offset="100%" stop-color="#e8913c" stop-opacity="0"/></radialGradient>
-    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#5a2f14" stop-opacity=".9"/><stop offset="100%" stop-color="#5a2f14" stop-opacity="0"/></radialGradient>
-    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#403820" stop-opacity=".85"/><stop offset="100%" stop-color="#403820" stop-opacity="0"/></radialGradient>
+    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#5a2a6a" stop-opacity=".95"/><stop offset="100%" stop-color="#5a2a6a" stop-opacity="0"/></radialGradient>
+    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#e879f9" stop-opacity=".45"/><stop offset="100%" stop-color="#e879f9" stop-opacity="0"/></radialGradient>
+    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#3a2050" stop-opacity=".9"/><stop offset="100%" stop-color="#3a2050" stop-opacity="0"/></radialGradient>
+    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#2c3040" stop-opacity=".85"/><stop offset="100%" stop-color="#2c3040" stop-opacity="0"/></radialGradient>
    <filter id="s"><feGaussianBlur stdDeviation="60"/></filter>
-    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .5 0"/></filter>
+    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="saturate" values="0"/></filter>
  </defs>
-  <rect width="1600" height="1000" fill="#141009"/>
+  <rect width="1600" height="1000" fill="#111217"/>
  <g filter="url(#s)">
    <rect width="1600" height="1000" fill="url(#a)"/>
    <rect width="1600" height="1000" fill="url(#c)"/>
    <rect width="1600" height="1000" fill="url(#d)"/>
    <rect width="1600" height="1000" fill="url(#b)"/>
  </g>
-  <rect width="1600" height="1000" filter="url(#g)" opacity="0.05"/>
+  <rect width="1600" height="1000" filter="url(#g)" opacity="0.35" style="mix-blend-mode:overlay"/>
 </svg>
@@ -1,18 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 1000" preserveAspectRatio="xMidYMid slice">
-  <defs>
-    <radialGradient id="a" cx="20%" cy="18%" r="55%"><stop offset="0%" stop-color="#123b6b" stop-opacity=".95"/><stop offset="100%" stop-color="#123b6b" stop-opacity="0"/></radialGradient>
-    <radialGradient id="b" cx="86%" cy="26%" r="52%"><stop offset="0%" stop-color="#38b6ff" stop-opacity=".45"/><stop offset="100%" stop-color="#38b6ff" stop-opacity="0"/></radialGradient>
-    <radialGradient id="c" cx="68%" cy="92%" r="60%"><stop offset="0%" stop-color="#1f2a72" stop-opacity=".9"/><stop offset="100%" stop-color="#1f2a72" stop-opacity="0"/></radialGradient>
-    <radialGradient id="d" cx="8%" cy="88%" r="55%"><stop offset="0%" stop-color="#0f5566" stop-opacity=".85"/><stop offset="100%" stop-color="#0f5566" stop-opacity="0"/></radialGradient>
-    <filter id="s"><feGaussianBlur stdDeviation="60"/></filter>
-    <filter id="g"><feTurbulence type="fractalNoise" baseFrequency="0.85" numOctaves="2" stitchTiles="stitch"/><feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .5 0"/></filter>
-  </defs>
-  <rect width="1600" height="1000" fill="#040914"/>
-  <g filter="url(#s)">
-    <rect width="1600" height="1000" fill="url(#a)"/>
-    <rect width="1600" height="1000" fill="url(#c)"/>
-    <rect width="1600" height="1000" fill="url(#d)"/>
-    <rect width="1600" height="1000" fill="url(#b)"/>
-  </g>
-  <rect width="1600" height="1000" filter="url(#g)" opacity="0.05"/>
-</svg>
@@ -0,0 +1,34 @@
+import react from "@vitejs/plugin-react";
+import reactCompiler from "babel-plugin-react-compiler";
+
+// ONE React transform, shared by vite.config.ts and vitest.config.ts (E27 S1).
+//
+// It is a shared factory rather than two `react()` calls because the two configs must not drift:
+// if the compiler ran only in the production build, every vitest run would be exercising code the
+// user never receives, and a compiler-induced behaviour change would ship green. That is precisely
+// the defect `0.93.2` was released to fix — a gate and a build image that had quietly stopped being
+// the same thing — so the rule here is that the gate compiles the code the same way the build does.
+//
+// The React Compiler auto-memoises: it infers what `useCallback`/`useMemo` were being hand-written
+// for and applies the equivalent itself. It is enabled repo-wide with no opt-out list because it
+// bails out on its own for anything it cannot prove safe (its rules are also linted, via
+// eslint-plugin-react-hooks). `target` follows the installed React major and must move with it.
+//
+// The plugin is IMPORTED rather than named by the usual `"babel-plugin-react-compiler"` string. Two
+// reasons, both about the gate: a string is invisible to knip, which then reports the dependency as
+// unused, and — worse — a typo in that string is a silent no-op that ships an uncompiled bundle,
+// while a bad import is a resolve error on the tsc lane.
+//
+// The price of the import: plugin-react finds the compiler only by that string, so it doesn't know the
+// compiler is there. Its one compiler-specific switch is Babel's `retainLines`, which it turns on for
+// dev (and so for vitest) unless the compiler is present. With the compiler's re-printed JSX that eats
+// the space at the end of a text line ("for example <code>" rendered "for example/api/feed"). The
+// production build never had it on. `generatorOpts` wins over the top-level option, so it is switched
+// off here, for every mode. Pinned by src/jsxWhitespace.dom.test.tsx.
+export const reactWithCompiler = () =>
+  react({
+    babel: {
+      plugins: [[reactCompiler, { target: "19" }]],
+      generatorOpts: { retainLines: false },
+    },
+  });
@@ -1,4 +1,4 @@
-import { lazy, Suspense, useEffect, useState } from "react";
+import { lazy, Suspense, useEffect, useRef, useState } from "react";
 import { qk } from "./lib/queryKeys";
 import { useTranslation } from "react-i18next";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
@@ -32,7 +32,8 @@ import Header from "./components/Header";
 import NavSidebar from "./components/NavSidebar";
 import BackToTop from "./components/ui/BackToTop";
 import PageShell from "./components/ui/PageShell";
-import GlassTuner from "./components/GlassTuner";
+import { SkipLink } from "./components/ui/SkipLink";
+import { pageTitleKey } from "./lib/pageMeta";
 import ChatDock from "./components/ChatDock";
 import DebugRecorder from "./components/DebugRecorder";
 import Toaster from "./components/ui/Toaster";
@@ -45,8 +46,8 @@ import DemoBanner from "./components/DemoBanner";
 import VerifyBanner from "./components/VerifyBanner";
 import { focusAccessRequestsTab } from "./lib/adminUsersTab";
 // The built app version, NOT imported from releaseNotes — importing anything from that module
-// pulls its whole ~900-line changelog into the eager App chunk and defeats the lazy ReleaseNotes
-// split. FRONTEND_VERSION equals RELEASE_NOTES[0].version by release convention (both bump together).
+// pulls the release-notes loader into the eager App chunk and defeats the lazy ReleaseNotes
+// split. FRONTEND_VERSION equals the newest release note's version by release convention (both bump together).
 import { FRONTEND_VERSION } from "./lib/version";
 import { applyDiagnostics } from "./lib/diagnostics";

@@ -131,6 +132,9 @@ export default function App() {
  });
  const needsSetup = setupQuery.data?.configured === false;
  const meQuery = useQuery({ queryKey: qk.me(), queryFn: api.me, enabled: false });
+  // The signed-in account, or null/undefined while signed out. Hoisted here because half a dozen
+  // effects below depend on it, and a dep list is only honest if it names the value the body reads.
+  const me = meQuery.data;

  // The `global` key scope: `h` opens the cheat sheet, Mod+K the jump-to palette, Shift+W jumps to
  // Home ("mit nézzek?"). Bound only once signed in, because that is where the overlays are mounted
@@ -141,32 +145,40 @@ export default function App() {
  // page underneath (owner decision 2026-09-09: the key always ends with the answer on screen).
  // The `page` scope rides the same binding: the `g` chords jump to a module, but only to one this
  // account can reach (the nav rail's own list, plus Settings, which is not in the rail's order).
-  useGlobalKeymap(
-    !!meQuery.data,
-    setPage,
-    meQuery.data ? [...moduleOrder(meQuery.data), "settings"] : [],
-  );
+  useGlobalKeymap(!!me, setPage, me ? [...moduleOrder(me), "settings"] : []);

  // The account's consented diagnostics level (E22 S5), applied to this tab's log: raised, the log is
  // kept in more detail and streamed to the server until the level lapses. A debug session that is
  // recording (E16) raises it for its own run and tags what it keeps. A lapse (its own timer, or the
  // server saying it is off) refetches `me`, so Settings and the recorder show what is in force.
-  const diagnostics = meQuery.data?.diagnostics;
-  const debugSession = meQuery.data?.debug_session;
+  // Re-running this on every `me` refetch is FREE and therefore the deps are the honest ones:
+  // applyDiagnostics computes an effective-level key and returns early when it has not moved
+  // (lib/diagnostics.ts), so an unchanged level is a no-op. It does refresh the `lapsed` callback
+  // before that early return, which is the half we WANT re-run. The old dep list picked out four
+  // primitive fields to dodge the fresh object identity a refetch produces; that is the checker's
+  // job to verify, not a comment's to assert, and it silently missed any other field the module
+  // may come to read.
+  const diagnostics = me?.diagnostics;
+  const debugSession = me?.debug_session;
  useEffect(() => {
    applyDiagnostics(
      diagnostics,
      debugSession,
      () => void queryClient.invalidateQueries({ queryKey: qk.me() }),
    );
-  }, [diagnostics?.level, diagnostics?.until, debugSession?.id, debugSession?.ended_at]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [diagnostics, debugSession, queryClient]);

  // Fetch the code of every module this account can open — and the channel page — once the first page
  // is on screen, so a module's first visit renders at once instead of flashing the chunk fallback.
  // Idle-scheduled so it never competes with the first page's own requests (Safari has no
  // requestIdleCallback, hence the timer).
+  // Depending on the whole `me` rather than its id is both honest and MORE correct: the module set
+  // is derived from `me` through each module's own gate (lib/modules moduleOrder), so a permission
+  // change — an admin grant, a Plex server appearing — alters it without the id moving, and the old
+  // `[me.id]` dep never re-preloaded for those. Re-running costs nothing: `preload()` is idempotent
+  // (lazyWithPreload memoises the pending promise), so a refetch that changes nothing fetches
+  // nothing; only the idle callback is re-scheduled.
  useEffect(() => {
-    const me = meQuery.data;
    if (!me) return;
    const run = () => {
      preloadPages([...moduleOrder(me), "settings"]);
@@ -179,7 +191,7 @@ export default function App() {
    }
    const id = window.setTimeout(run, 1000);
    return () => window.clearTimeout(id);
-  }, [meQuery.data?.id]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [me]);

  // Measure the scrollbar's gutter width once and publish it as --sbw, so the floating header and the
  // toolbar band can pad their right edge to line up with the scrolled cards (the app scroller reserves
@@ -197,9 +209,13 @@ export default function App() {
  // Once signed in, drop any leftover ONE-TIME query params from the pre-login flow (?access, ?verify,
  // ?reset) — but NOT the nav/filter params, which the logged-in app now reads from and keeps in the
  // URL. Gated on auth so the logged-out Welcome page still reads its params first.
+  // Keyed on "is there a session at all", which is the whole condition the body tests. Re-running
+  // on an account switch was never the point — by then the params are already gone and a second
+  // clearParams is a no-op.
+  const signedIn = !!me;
  useEffect(() => {
-    if (meQuery.data) clearParams("access", "verify", "reset");
-  }, [meQuery.data?.id]); // eslint-disable-line react-hooks/exhaustive-deps
+    if (signedIn) clearParams("access", "verify", "reset");
+  }, [signedIn]);

  // Any request that 401s means the session ended server-side. If we were signed in (cached
  // `me` is a user object), reload to the login page at once (also covers any click that hits
@@ -218,12 +234,20 @@ export default function App() {
  // Returning from an in-app Google link/upgrade round-trip (auth.py redirects to ?link=…).
  // Surface the outcome, refresh `me` (can_read/can_write/has_google may have flipped), land on
  // Settings → Account so the new state is visible, then strip the param for a clean URL.
+  // "Exactly once per mount" is now ENFORCED by the ref rather than asserted by an empty dep list:
+  // `t` changes identity on a language switch, so the honest dep list would otherwise re-fire the
+  // toast when the user changes language. (The old `[]` got away with it only because clearParams
+  // had already removed the param — an invariant held by a side effect two lines further down.)
+  const linkAnswered = useRef(false);
+  const { refetch: refetchMe } = meQuery;
  useEffect(() => {
+    if (linkAnswered.current) return;
    const result = new URLSearchParams(window.location.search).get("link");
    if (!result) return;
+    linkAnswered.current = true;
    if (result === "ok") {
      notify({ level: "success", message: t("settings.account.googleLink.linked") });
-      void meQuery.refetch();
+      void refetchMe();
      setAccountRaw(LS.settingsTab, "account");
      setPage("settings");
    } else {
@@ -231,42 +255,59 @@ export default function App() {
      notify({ level: "error", message: t(`settings.account.googleLink.${key}`) });
    }
    clearParams("link");
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [t, setPage, refetchMe]);

  // A Google OAuth flow started while already signed in (add-another-account, link, or upgrade) was
  // cancelled at Google's consent screen. The backend only emits this for a live session, so a
  // neutral toast is the right feedback — the pre-auth login banner would never render here.
+  // Same one-shot shape as the `?link=` handler above, same reason for the ref.
+  const oauthAnswered = useRef(false);
  useEffect(() => {
+    if (oauthAnswered.current) return;
    if (new URLSearchParams(window.location.search).get("oauth") !== "cancelled") return;
+    oauthAnswered.current = true;
    notify({ level: "info", message: t("settings.account.googleCancelled") });
    clearParams("oauth");
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [t]);

  // Deep-link from the "new access request" admin email (?admin=access-requests) → jump straight to
  // the admin Users → Access requests view. Snapshot the param up front (read once at mount); act once
  // `me` is known, and only for an admin (others just land on their default page).
  const [adminDeepLink] = useState(() => new URLSearchParams(window.location.search).get("admin"));
+  // Ref-guarded like the two above, and here it closes a real hole rather than only satisfying the
+  // checker: the snapshot lives for the whole session, so with honest deps a later role change —
+  // or any `me` refetch, under the old id-only key — would yank the user to Users long after the
+  // deep link was answered.
+  const adminDeepLinkAnswered = useRef(false);
  useEffect(() => {
-    if (adminDeepLink !== "access-requests" || !meQuery.data) return;
-    if (meQuery.data.role === "admin") {
+    if (adminDeepLinkAnswered.current) return;
+    if (adminDeepLink !== "access-requests" || !me) return;
+    adminDeepLinkAnswered.current = true;
+    if (me.role === "admin") {
      focusAccessRequestsTab();
      setPage("users");
    }
    clearParams("admin");
-  }, [adminDeepLink, meQuery.data?.id]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [adminDeepLink, me, setPage]);

  // Nudge admins when access requests are waiting (in lieu of a server-push bell). Keyed on the
  // pending COUNT so it re-resolves the moment an approval/denial changes it — not only on a
  // fresh load (which is why the notice used to linger until F5 after an approval).
+  // Honest deps, and `t` among them is a fix rather than a concession: the nudge is a persisted
+  // toast whose text is translated at issue time, so a language switch must re-issue it. It did not
+  // before — the notice stayed in the old language until the count changed.
+  const role = me?.role;
+  const pendingInvites = me?.pending_invites ?? 0;
+  const pendingActivations = me?.pending_activations ?? 0;
  useEffect(() => {
-    if (meQuery.data?.role !== "admin") return;
+    if (role !== "admin") return;
    // Keep a single, current nudge: drop any prior one (persisted copies reload as dismissed
    // history, so they'd otherwise pile up one-per-reload) before re-issuing the live notice.
    removeByMetaKind("access-requests");
    // Both kinds of "someone is waiting on you": a request needing a decision, and a sign-up whose
    // address was approved before they registered. The second used to produce NO signal at all —
    // nothing lands in the queue for it — which is how the 2026-09-03 registrant went unnoticed.
-    const pending = (meQuery.data.pending_invites ?? 0) + (meQuery.data.pending_activations ?? 0);
+    const pending = pendingInvites + pendingActivations;
    if (pending > 0) {
      notify({
        level: "warning",
@@ -285,8 +326,7 @@ export default function App() {
        },
      });
    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [meQuery.data?.role, meQuery.data?.pending_invites, meQuery.data?.pending_activations]);
+  }, [role, pendingInvites, pendingActivations, t, setPage]);

  // Language is edited outside the Settings page (sidebar/login), so it stays instant.
  function changeLanguage(code: LangCode) {
@@ -302,7 +342,7 @@ export default function App() {
  if (needsSetup) return <SetupWizard />;
  // /api/me answers 200 always (null body = logged out), and BootGate has already handled a failed
  // probe — so no data here means "not signed in" → the public landing.
-  if (!meQuery.data) return <Welcome verify={verifyEntry} />;
+  if (!me) return <Welcome verify={verifyEntry} />;

  // Shown while a page's chunk is still on its way: only if its visit beats the preload above (or the
  // preload failed), and like every loading state it stays invisible for a load that is quick anyway.
@@ -323,16 +363,16 @@ export default function App() {
  // page the account can't reach (a gated module via stale nav / a deep link) falls back to the feed,
  // exactly as the old ternary's fallthrough did. A channel page overlays the content column, so no
  // side rail shows behind it.
-  const me = meQuery.data!;
  const pageGate = moduleDef(page).gate;
-  const activePage: Page = !pageGate || pageGate(me) ? page : "feed";
+  const activePage: Page = !pageGate || pageGate(me!) ? page : "feed";
  const { Component: PageContent, maxWidth } = PAGE_CONTENT[activePage];
  const railDef = channelView ? undefined : PAGE_RAIL[activePage];

  return (
-    <div className="h-screen flex text-fg">
+    <div className="h-dvh flex text-fg">
+      <SkipLink label={t("nav.skipToContent")} />
      <NavSidebar
-        me={meQuery.data!}
+        me={me!}
        onOpenAbout={() => setAboutOpen(true)}
        onChangeLanguage={changeLanguage}
        language={i18n.language as LangCode}
@@ -368,7 +408,7 @@ export default function App() {
                key={channelView.id}
                channelId={channelView.id}
                initialName={channelView.name}
-                me={meQuery.data!}
+                me={me!}
                view={view}
                setView={setView}
                onShowInFeed={() => {
@@ -391,13 +431,14 @@ export default function App() {
          </PageShell>
        ) : (
          <PageShell
+            title={t(pageTitleKey(activePage))}
            scrollKey={normalScrollKey}
            maxWidth={maxWidth}
-            header={<Header me={meQuery.data!} onYtSearch={enterYtSearch} />}
+            header={<Header me={me!} onYtSearch={enterYtSearch} />}
            banners={
              <>
                <VerifyBanner entry={verifyEntry} />
-                {meQuery.data!.is_demo && <DemoBanner />}
+                {me!.is_demo && <DemoBanner />}
                <VersionBanner onOpen={() => openReleaseNotes(FRONTEND_VERSION)} />
              </>
            }
@@ -417,9 +458,9 @@ export default function App() {
          "take me to X" the same way. Their keys are bound by useGlobalKeymap above. */}
      <KeyboardHelp />
      <AppCommandPalette />
-      {meQuery.data && !meQuery.data.is_demo && <ChatDock meId={meQuery.data.id} />}
+      {me && !me.is_demo && <ChatDock meId={me.id} />}
      {/* The debug recorder (E16): its start dialog, and its pill docked under the toasts. */}
-      {meQuery.data && !meQuery.data.is_demo && <DebugRecorder />}
+      {me && !me.is_demo && <DebugRecorder />}
      <Suspense fallback={null}>
        {aboutOpen && (
          <About
@@ -437,8 +478,6 @@ export default function App() {
      <ErrorDialog />
      {/* Re-binds to the active page's scroll container on navigation (page or channel change). */}
      <BackToTop dep={channelView ? `chan:${channelView.id}` : page} />
-      {/* Opt-in live appearance tuner (Settings → Appearance; off by default). */}
-      <GlassTuner />
    </div>
  );
 }
@@ -45,6 +45,7 @@ export default function About({

  return (
    <Modal
+      initialFocus="close"
      title={
        <span className="flex items-center gap-2">
          <Info className="w-5 h-5 text-accent" /> {t("about.title")}
@@ -5,6 +5,7 @@ import { api } from "../lib/api";
 import ChannelAboutContent from "./ChannelAbout";
 import { PopoverSurface } from "./ui/AnchoredPopover";
 import { useAnchoredPopover } from "./ui/anchoredPopoverHooks";
+import { SURFACE } from "./ui/surfaces";

 /**
 * A channel-description cell: one truncated line in the table, revealing the FULL channel "About"
@@ -56,7 +57,7 @@ export default function AboutCell({ text, channelId }: { text: string | null; ch
      </span>
      <PopoverSurface
        popover={pop}
-        className="glass w-120 overflow-y-auto px-3.5 py-3 rounded-lg animate-[fadeIn_0.12s_ease]"
+        className={`${SURFACE.popover} w-120 overflow-y-auto px-3.5 py-3 animate-[fadeIn_0.12s_ease]`}
        // min(design cap, available space): keeps the 28rem cap on a tall viewport, shrinks to fit on a
        // short one (high zoom). --fit-max-h is set by the fitHeight `size` middleware once positioned.
        style={{ maxHeight: "min(28rem, var(--fit-max-h, 28rem))" }}
@@ -13,7 +13,9 @@ import { copyText } from "../lib/clipboard";
 import { formatDateTime } from "../lib/format";
 import { invalidateUserAccess } from "../lib/adminUsers";
 import type { AdminUserAccess, AdminUserRow } from "../lib/api/admin";
-import { FocusSafeButton } from "./ui/FocusSafeButton";
+import { Button } from "./ui/Button";
+import { SURFACE } from "./ui/surfaces";
+import { SectionLabel } from "./ui/Headings";

 // The admin's answer to "why can this person not get in?", and the place every recovery action for
 // one account lives (E12 · S5, design option C).
@@ -103,8 +105,14 @@ export default function AccountPanel({
  const a: AdminUserAccess | undefined = q.data;

  return (
-    <Modal title={displayName(user)} onClose={onClose} placement="drawer" maxWidth="max-w-md">
-      <div className="text-2xs text-muted truncate -mt-2 mb-4">{user.email}</div>
+    <Modal
+      initialFocus="close"
+      title={displayName(user)}
+      onClose={onClose}
+      placement="drawer"
+      maxWidth="max-w-md"
+    >
+      <div className="text-2xs text-muted truncate mb-4">{user.email}</div>

      {q.isError && !a ? (
        <StateMessage tone="error" onRetry={() => q.refetch()}>
@@ -114,10 +122,10 @@ export default function AccountPanel({
        <LoadingState />
      ) : (
        <>
-          <div className="text-2xs uppercase tracking-wider text-muted mb-2">
+          <SectionLabel level={3} className="mb-2">
            {t("users.account.access")}
-          </div>
-          <div className="glass-card rounded-xl p-3 space-y-2 mb-5">
+          </SectionLabel>
+          <div className={`${SURFACE.card} p-3 space-y-2 mb-5`}>
            <AccessRow
              icon={Mail}
              label={t("users.account.email")}
@@ -191,29 +199,33 @@ export default function AccountPanel({
            )}
          </div>

-          <div className="text-2xs uppercase tracking-wider text-muted mb-2">
+          <SectionLabel level={3} className="mb-2">
            {t("users.account.recovery")}
-          </div>
+          </SectionLabel>
          <div className="space-y-2">
            {a.can_activate && (
-              <FocusSafeButton
+              <Button
+                variant="glass"
+                fullWidth
+                icon={<Check />}
+                loading={activate.isPending}
                onClick={() => activate.mutate()}
-                disabled={activate.isPending}
-                className="w-full glass-card glass-hover flex items-center gap-2 px-3 py-2.5 rounded-lg text-xs border border-accent/40 text-accent disabled:opacity-50 transition"
+                className="border border-accent/40 text-accent"
              >
-                <Check className="w-4 h-4 shrink-0" />
                <span className="flex-1 text-left">{t("users.account.activate")}</span>
-              </FocusSafeButton>
+              </Button>
            )}

-            <FocusSafeButton
+            <Button
+              variant="glass"
+              fullWidth
+              icon={<Send />}
+              loading={resend.isPending}
              onClick={() => resend.mutate()}
              // The demo account's address is never confirmed, and the server refuses to mail it — as
              // it refuses it a set-password link below (deep-review E11 round 3).
-              disabled={user.is_demo || !a.email_configured || a.email_verified || resend.isPending}
-              className="w-full glass-card glass-hover flex items-center gap-2 px-3 py-2.5 rounded-lg text-xs disabled:opacity-45 transition"
+              disabled={user.is_demo || !a.email_configured || a.email_verified}
            >
-              <Send className="w-4 h-4 shrink-0" />
              <span className="flex-1 text-left">{t("users.account.resend")}</span>
              {/* Says WHY it is unavailable instead of just greying out — the no-mail case is the
                    whole reason the link below exists, so naming it here is the explanation. */}
@@ -223,18 +235,21 @@ export default function AccountPanel({
              {a.email_configured && a.email_verified && (
                <span className="text-muted">{t("users.account.alreadyConfirmed")}</span>
              )}
-            </FocusSafeButton>
+            </Button>

-            <FocusSafeButton
+            <Button
+              variant="glass"
+              fullWidth
+              icon={<KeyRound />}
+              loading={issue.isPending}
+              disabled={user.is_demo}
              onClick={() => issue.mutate()}
-              disabled={issue.isPending || user.is_demo}
-              className="w-full glass-card glass-hover flex items-center gap-2 px-3 py-2.5 rounded-lg text-xs border border-accent/40 text-accent disabled:opacity-50 transition"
+              className="border border-accent/40 text-accent"
            >
-              <KeyRound className="w-4 h-4 shrink-0" />
              <span className="flex-1 text-left">
                {link ? t("users.account.setPasswordAgain") : t("users.account.setPassword")}
              </span>
-            </FocusSafeButton>
+            </Button>
          </div>

          {link && (
@@ -243,13 +258,14 @@ export default function AccountPanel({
                <div className="flex-1 min-w-0 bg-surface border border-border rounded-lg px-3 py-2 text-2xs font-mono truncate">
                  {link.url}
                </div>
-                <button
+                <Button
+                  variant="glass"
+                  icon={copied ? <Check /> : <Copy />}
                  onClick={copy}
-                  className="shrink-0 glass-card glass-hover inline-flex items-center gap-1.5 px-3 py-2 rounded-lg text-xs border border-accent/40 text-accent transition"
+                  className="border border-accent/40 text-accent"
                >
-                  {copied ? <Check className="w-3.5 h-3.5" /> : <Copy className="w-3.5 h-3.5" />}
                  {copied ? t("users.account.copied") : t("users.account.copy")}
-                </button>
+                </Button>
              </div>
              <p className="text-2xs text-muted leading-relaxed">{t("users.account.linkNote")}</p>
            </div>
@@ -6,6 +6,10 @@ import { decideChipLayout } from "../lib/chipOverflow";
 import { chipLaneClass, useChipOverflowFit } from "../lib/useChipOverflowFit";
 import { PopoverItem, PopoverSurface } from "./ui/AnchoredPopover";
 import { useAnchoredPopover } from "./ui/anchoredPopoverHooks";
+import { Button } from "./ui/Button";
+import { Chip } from "./ui/Chip";
+import { chipClass } from "./ui/chipStyles";
+import { SURFACE } from "./ui/surfaces";

 // The applied-filter row above the feed: every narrowing currently in force, each removable on its
 // own. It exists because the filter panel now sits collapsed as a tab — without this you'd have to
@@ -22,23 +26,19 @@ import { useAnchoredPopover } from "./ui/anchoredPopoverHooks";
 // the "fit some + N more" treatment used on wider lanes.
 const NARROW_PX = 420;

-const chipCls =
-  "chip group inline-flex items-center gap-1 pl-2.5 pr-1.5 py-1 text-sm whitespace-nowrap hover:border-accent hover:bg-accent/20 transition";
-
 function ChipButton({ f, testId }: { f: ActiveFilter; testId?: string }) {
  const { t } = useTranslation();
  return (
-    <button
+    <Chip
+      variant="token"
+      size="md"
      data-testid={testId}
      data-filter-key={f.key}
      onClick={f.remove}
-      title={t("feed.chips.remove", { name: f.label })}
-      aria-label={t("feed.chips.remove", { name: f.label })}
-      className={chipCls}
+      removeLabel={t("feed.chips.remove", { name: f.label })}
    >
      <span className="max-w-56 truncate">{f.label}</span>
-      <X className="w-3 h-3 shrink-0 opacity-60 group-hover:opacity-100" />
-    </button>
+    </Chip>
  );
 }

@@ -69,22 +69,20 @@ function OverflowPopover({
  const name = ariaLabel ?? label;
  return (
    <>
-      <button
-        type="button"
+      <Chip
+        variant="token"
+        size="md"
        ref={pop.refs.setReference}
        {...pop.getReferenceProps()}
        aria-label={name}
-        className={`chip inline-flex shrink-0 items-center gap-1 px-2.5 py-1 text-sm whitespace-nowrap transition ${
-          open ? "border-accent text-accent" : "hover:border-accent"
-        }`}
+        icon={icon ? <Filter className="size-3.5" aria-hidden="true" /> : undefined}
      >
-        {icon && <Filter className="w-3.5 h-3.5 shrink-0" aria-hidden="true" />}
        {label}
-      </button>
+      </Chip>
      <PopoverSurface
        popover={pop}
        ariaLabel={name}
-        className="glass-menu min-w-48 max-w-72 rounded-xl p-1.5 shadow-lg animate-[popIn_0.16s_ease]"
+        className={`${SURFACE.menu} min-w-48 max-w-72 animate-[popIn_0.16s_ease]`}
      >
        <div role="group" aria-label={name} className="max-h-72 overflow-y-auto no-scrollbar">
          {chips.map((f) => (
@@ -93,7 +91,7 @@ function OverflowPopover({
              role="menuitem"
              onSelect={f.remove}
              label={f.label}
-              className="group flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm text-fg transition"
+              className="group flex w-full items-center gap-2 rounded-lg px-2 py-1.5 text-left text-sm text-fg transition"
            >
              <span className="flex-1 truncate">{f.label}</span>
              <X className="w-3.5 h-3.5 shrink-0 opacity-60 group-hover:opacity-100" />
@@ -101,17 +99,17 @@ function OverflowPopover({
          ))}
        </div>
        <div className="mt-1 border-t border-border px-1 pt-1.5">
-          <button
-            type="button"
+          <Button
+            variant="link-muted"
            data-testid="active-filter-clear-all"
            onClick={() => {
              onClearAll();
              setOpen(false);
            }}
-            className="text-xs text-muted hover:text-fg underline underline-offset-2 transition"
+            className="text-xs underline underline-offset-2"
          >
            {t("sidebar.clearAll")}
-          </button>
+          </Button>
        </div>
      </PopoverSurface>
    </>
@@ -191,13 +189,13 @@ export default function ActiveFilterChips({
            ref={(el) => {
              chipRefs.current[i] = el;
            }}
-            className={chipCls}
+            className={chipClass("token", "md") + " pr-1.5"}
          >
            <span className="max-w-56 truncate">{f.label}</span>
-            <X className="w-3 h-3 shrink-0" />
+            <X className="size-3" />
          </span>
        ))}
-        <span ref={plusRef} className="chip inline-flex items-center gap-1 px-2.5 py-1 text-sm">
+        <span ref={plusRef} className={chipClass("token", "md")}>
          +{n}
        </span>
        <span ref={clearRef} className="ml-0.5 text-sm underline underline-offset-2">
@@ -230,13 +228,14 @@ export default function ActiveFilterChips({
            />
          )}
          {layout.mode === "all" && n > 1 && (
-            <button
+            <Button
+              variant="link-muted"
              data-testid="active-filter-clear-all"
              onClick={onClearAll}
-              className="ml-0.5 shrink-0 text-sm text-muted hover:text-fg underline underline-offset-2 transition"
+              className="ml-0.5 text-sm underline underline-offset-2"
            >
              {t("sidebar.clearAll")}
-            </button>
+            </Button>
          )}
        </>
      )}
@@ -1,14 +1,18 @@
-import { useState } from "react";
+import { useLayoutEffect, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { qk } from "../lib/queryKeys";
-import { Check, ListPlus, Plus, Youtube } from "lucide-react";
+import { ListPlus, Plus, Youtube } from "lucide-react";
+import { MenuCheck } from "./ui/MenuCheck";
 import { api, type Playlist } from "../lib/api";
 import { notifyActionError } from "../lib/actionErrors";
 import { useScrollFade } from "../lib/useScrollFade";
 import { playlistName } from "../lib/playlistName";
 import { PopoverItem, PopoverSurface } from "./ui/AnchoredPopover";
 import { useAnchoredPopover } from "./ui/anchoredPopoverHooks";
+import { IconButton } from "./ui/IconButton";
+import { Input } from "./ui/Input";
+import { SURFACE } from "./ui/surfaces";

 // A small anchored menu for toggling a video's membership in the user's playlists, with inline
 // "new playlist" creation. Same shape as the channel tag editor (R8 S1's pilot): radio-style
@@ -16,26 +20,82 @@ import { useAnchoredPopover } from "./ui/anchoredPopoverHooks";
 // the input swallowing non-Escape keys, since character and arrow keys belong to the text field.
 export default function AddToPlaylist({
  videoId,
-  className,
+  variant = "ghost",
+  size = "sm",
 }: {
  videoId: string;
-  className?: string;
+  variant?: "ghost" | "outline" | "overlay" | "media";
+  size?: "sm" | "md";
 }) {
  const { t } = useTranslation();
-  const qc = useQueryClient();
-  const fade = useScrollFade();
  const [open, setOpen] = useState(false);
-  const [newName, setNewName] = useState("");
-  const [busy, setBusy] = useState(false);
+  const pop = useMembershipPopover(open, setOpen);
+  return (
+    <>
+      <IconButton
+        ref={pop.refs.setReference}
+        variant={variant}
+        size={size}
+        {...pop.getReferenceProps({
+          // The trigger sits on a feed card that opens the player on click, so the toggle must not
+          // reach it.
+          onClick: (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+          },
+        })}
+        label={t("playlists.addToPlaylist")}
+      >
+        <ListPlus />
+      </IconButton>
+      <MembershipPanel videoId={videoId} pop={pop} />
+    </>
+  );
+}

-  const pop = useAnchoredPopover({
+/** The same panel, opened from an object's menu ("Add to playlist…", E28 C1) rather than its own
+ *  button: anchored to the element the menu came from, and gone when it closes. */
+export function AddToPlaylistAt({
+  videoId,
+  anchor,
+  onClose,
+}: {
+  videoId: string;
+  anchor: Element;
+  onClose: () => void;
+}) {
+  const pop = useMembershipPopover(true, (next) => {
+    if (!next) onClose();
+  });
+  const { setPositionReference } = pop.refs;
+  useLayoutEffect(() => setPositionReference(anchor), [anchor, setPositionReference]);
+  return <MembershipPanel videoId={videoId} pop={pop} />;
+}
+
+function useMembershipPopover(open: boolean, onOpenChange: (open: boolean) => void) {
+  return useAnchoredPopover({
    open,
-    onOpenChange: setOpen,
+    onOpenChange,
    offset: 6,
    // The menu holds a "new playlist" text field — keep typed chars and pointer-hover out of the
    // roving list so they don't steal the caret.
    hostsInput: true,
  });
+}
+
+function MembershipPanel({
+  videoId,
+  pop,
+}: {
+  videoId: string;
+  pop: ReturnType<typeof useAnchoredPopover>;
+}) {
+  const { t } = useTranslation();
+  const qc = useQueryClient();
+  const fade = useScrollFade();
+  const open = pop.open;
+  const [newName, setNewName] = useState("");
+  const [busy, setBusy] = useState(false);

  const membership = useQuery({
    queryKey: qk.playlistMembership(videoId),
@@ -90,28 +150,13 @@ export default function AddToPlaylist({

  return (
    <>
-      <button
-        ref={pop.refs.setReference}
-        {...pop.getReferenceProps({
-          // The trigger sits on a feed card that opens the player on click, so the toggle must not
-          // reach it.
-          onClick: (e) => {
-            e.preventDefault();
-            e.stopPropagation();
-          },
-        })}
-        title={t("playlists.addToPlaylist")}
-        aria-label={t("playlists.addToPlaylist")}
-        className={className ?? "p-1.5 rounded-md hover:bg-surface text-muted hover:text-fg"}
-      >
-        <ListPlus className="w-4 h-4" />
-      </button>
-
-      <PopoverSurface popover={pop} className="glass-menu w-60 rounded-xl p-2">
+      <PopoverSurface popover={pop} className={`${SURFACE.popover} w-60 p-2`}>
        {/* A React portal still propagates events up the REACT tree, so a click inside this panel
            would otherwise reach the feed card that hosts the trigger and start playback. */}
        <div onClick={(e) => e.stopPropagation()}>
-          <div className="text-xs text-muted px-1.5 pb-1.5">{t("playlists.addToPlaylist")}</div>
+          <div className="text-xs text-muted px-1.5 pb-1.5">
+            {t("playlists.addToPlaylistTitle")}
+          </div>
          <div
            ref={fade.ref}
            style={fade.style}
@@ -135,13 +180,7 @@ export default function AddToPlaylist({
                label={playlistName(pl, t)}
                className="w-full flex items-center gap-2 text-sm px-1.5 py-1.5 rounded-lg text-fg outline-hidden transition"
              >
-                <span
-                  className={`grid place-items-center w-4 h-4 rounded border ${
-                    pl.has_video ? "bg-accent border-accent text-accent-fg" : "border-border"
-                  }`}
-                >
-                  {pl.has_video && <Check className="w-3 h-3" />}
-                </span>
+                <MenuCheck kind="many" on={!!pl.has_video} />
                <span className="truncate flex-1 text-left">{playlistName(pl, t)}</span>
                {(pl.source === "youtube" || pl.yt_playlist_id) && (
                  <Youtube className="w-3 h-3 shrink-0 text-muted" />
@@ -151,7 +190,9 @@ export default function AddToPlaylist({
          </div>
          <div className="flex items-center gap-1.5 border-t border-border mt-1.5 pt-1.5">
            <Plus className="w-3.5 h-3.5 text-muted shrink-0" />
-            <input
+            <Input
+              className="flex-1"
+              size="sm"
              value={newName}
              onChange={(e) => setNewName(e.target.value)}
              onKeyDown={(e) => {
@@ -165,7 +206,6 @@ export default function AddToPlaylist({
                }
              }}
              placeholder={t("playlists.newPlaylist")}
-              className="flex-1 min-w-0 bg-surface border border-border rounded-md px-2 py-1 text-xs focus:outline-hidden focus:ring-2 focus:ring-accent/40"
            />
          </div>
        </div>
@@ -1,3 +1,4 @@
+import clsx from "clsx";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import {
@@ -6,11 +7,11 @@ import {
  useQuery,
  useQueryClient,
 } from "@tanstack/react-query";
-import { Copy, Radio, Search, X } from "lucide-react";
+import { Copy, Radio, Search } from "lucide-react";

 import { api, type LogFacet, type LogQuery, type ServerLogRow } from "../lib/api";
 import { copyText } from "../lib/clipboard";
-import { formatDateTime } from "../lib/format";
+import { formatDateTimeSec } from "../lib/format";
 import { nextNavId, notifyNav, rememberNavPosition } from "../lib/history";
 import { LEVEL_GROUPS, type LevelGroup } from "../lib/log";
 import {
@@ -31,8 +32,14 @@ import NavGrid from "./ui/NavGrid";
 import { Button } from "./ui/Button";
 import FilterChipGroup from "./ui/FilterChipGroup";
 import FilterSelect from "./ui/FilterSelect";
+import { FilterFoldButton } from "./ui/FilterFold";
+import { useFilterFold } from "../lib/useFilterFold";
+import { useStickyTop } from "./ui/stickyTop";
 import { Section } from "./ui/form";
 import { LoadingState, StateMessage } from "./ui/QueryState";
+import { DismissibleChip } from "./ui/Chip";
+import { InnerInput } from "./ui/Input";
+import { fieldClass } from "./ui/fieldStyles";

 // Admin → Szervernapló: the server's stored log (`log_events`, E22.6). One list, newest first; a line
 // opens in place to its full record, and its request id / job id narrow the list to that request or
@@ -73,6 +80,14 @@ export default function AdminLogs() {
    logsParamsToState(new URLSearchParams(window.location.search)),
  );
  const [live, setLiveState] = useState(false);
+  // The toolbar sticks at the scroller's top (./ui/stickyTop), and folds its facet row when short.
+  useStickyTop();
+  const fold = useFilterFold();
+  const facetFilters =
+    state.sources.length +
+    (state.user ? 1 : 0) +
+    (state.event ? 1 : 0) +
+    (state.window !== DEFAULT_LOGS_STATE.window ? 1 : 0);
  // Read by `getNextPageParam` when a page is fetched, not when it renders: while live, a refetch
  // stops after the newest page, however many pages the cache holds — a "Load older" that lands
  // after Live was switched on, or a filter set revisited with older pages still cached.
@@ -241,104 +256,119 @@ export default function AdminLogs() {

        <div
          data-testid="admin-logs"
-          className="overflow-hidden rounded-xl border border-border bg-bg"
+          // overflow-clip, not -hidden: a hidden box is a scroll container, and the toolbar would stick
+          // to it instead of to the page.
+          className="overflow-clip rounded-xl border border-border bg-bg"
        >
-          <div className="flex flex-wrap items-center gap-2 border-b border-border p-2">
-            <label className="flex min-w-[12rem] flex-1 items-center gap-1.5 rounded-lg border border-border bg-card px-2 py-1 text-sm focus-within:border-accent">
-              <Search className="h-3.5 w-3.5 shrink-0 text-muted" aria-hidden />
-              <input
-                type="search"
-                value={state.q}
-                onChange={(e) => update({ q: e.target.value.slice(0, 200) })}
-                placeholder={t("adminLogs.search")}
-                aria-label={t("adminLogs.search")}
-                className="min-w-0 flex-1 bg-transparent outline-none"
+          {/* The console's toolbar is the page's band (B4, B9): it sticks at the top with the fade
+              under it while the lines scroll, so a filter is in reach at line 500. */}
+          <div className="sticky top-0 z-base bg-bg fade-below">
+            <div className="flex flex-wrap items-center gap-2 border-b border-border p-2">
+              <label
+                className={clsx(
+                  fieldClass({ size: "sm", pill: true }),
+                  "flex min-w-[12rem] flex-1 items-center gap-1.5",
+                )}
+              >
+                <Search className="h-3.5 w-3.5 shrink-0 text-muted" aria-hidden />
+                <InnerInput
+                  type="search"
+                  value={state.q}
+                  onChange={(e) => update({ q: e.target.value.slice(0, 200) })}
+                  placeholder={t("adminLogs.search")}
+                  aria-label={t("adminLogs.search")}
+                />
+              </label>
+              <FilterChipGroup
+                ariaLabel={t("adminLogs.levelLabel")}
+                value={state.group}
+                onChange={(group) => update({ group })}
+                options={GROUPS.map((g) => ({
+                  value: g,
+                  label: t(`settings.myLog.filters.${g}`),
+                  count: groupCount(g),
+                }))}
              />
-            </label>
-            <FilterChipGroup
-              ariaLabel={t("adminLogs.levelLabel")}
-              value={state.group}
-              onChange={(group) => update({ group })}
-              options={GROUPS.map((g) => ({
-                value: g,
-                label: t(`settings.myLog.filters.${g}`),
-                count: groupCount(g),
-              }))}
-            />
-          </div>
-
-          <div className="flex flex-wrap items-center gap-2 border-b border-border p-2">
-            <FilterSelect
-              label={t("adminLogs.source")}
-              options={facetOptions(facets.data?.sources, state.sources[0] ?? null, (v) => v)}
-              selected={[state.sources[0] ?? ""]}
-              onChange={([source]) => update({ sources: source ? [source] : [] })}
-              testId="logs-source"
-            />
-            <FilterSelect
-              label={t("adminLogs.account")}
-              options={facetOptions(facets.data?.users, state.user, accountLabel)}
-              selected={[state.user ?? ""]}
-              onChange={([user]) => update({ user: user || null })}
-              testId="logs-user"
-            />
-            <FilterSelect
-              label={t("adminLogs.event")}
-              options={facetOptions(facets.data?.events, state.event, (v) =>
-                v === "none" ? t("adminLogs.noEvent") : v,
-              )}
-              selected={[state.event ?? ""]}
-              onChange={([event]) => update({ event: event || null })}
-              testId="logs-event"
-            />
-            <FilterSelect
-              label={t("adminLogs.window")}
-              options={WINDOWS.map((w) => ({ value: w, label: t(`adminLogs.windows.${w}`) }))}
-              selected={[state.window]}
-              onChange={([window]) => update({ window: window as LogWindow })}
-              testId="logs-window"
-            />
-            <span className="ml-auto flex gap-1.5">
-              <Button
-                variant={polling ? "outline-accent" : "outline"}
-                size="xs"
-                icon={<Radio className="h-3.5 w-3.5" />}
-                aria-pressed={polling}
-                onClick={toggleLive}
-              >
-                {t("adminLogs.live")}
-              </Button>
-              <Button
-                variant="outline"
-                size="xs"
-                icon={<Copy className="h-3.5 w-3.5" />}
-                // While a filter change loads, the rows on screen are the previous filter's.
-                disabled={rows.length === 0 || logs.isPlaceholderData}
-                onClick={() => void copy()}
-              >
-                {t("adminLogs.copy")}
-              </Button>
-            </span>
-          </div>
-
-          {(state.requestId || state.jobId !== null) && (
-            <div className="flex flex-wrap items-center gap-2 border-b border-border px-2 py-1.5 text-xs">
-              {state.requestId && (
-                <PivotChip
-                  label={t("adminLogs.pivotRequest", { id: state.requestId })}
-                  clearLabel={t("adminLogs.clearPivot")}
-                  onClear={() => update({ requestId: null })}
-                />
-              )}
-              {state.jobId !== null && (
-                <PivotChip
-                  label={t("adminLogs.pivotJob", { id: state.jobId })}
-                  clearLabel={t("adminLogs.clearPivot")}
-                  onClear={() => update({ jobId: null })}
-                />
-              )}
            </div>
-          )}
+
+            <div className="flex flex-wrap items-center gap-2 border-b border-border p-2">
+              <FilterFoldButton fold={fold} label={t("sidebar.filters")} count={facetFilters} />
+              {!fold.folded && (
+                <>
+                  <FilterSelect
+                    label={t("adminLogs.source")}
+                    options={facetOptions(facets.data?.sources, state.sources[0] ?? null, (v) => v)}
+                    selected={[state.sources[0] ?? ""]}
+                    onChange={([source]) => update({ sources: source ? [source] : [] })}
+                    testId="logs-source"
+                  />
+                  <FilterSelect
+                    label={t("adminLogs.account")}
+                    options={facetOptions(facets.data?.users, state.user, accountLabel)}
+                    selected={[state.user ?? ""]}
+                    onChange={([user]) => update({ user: user || null })}
+                    testId="logs-user"
+                  />
+                  <FilterSelect
+                    label={t("adminLogs.event")}
+                    options={facetOptions(facets.data?.events, state.event, (v) =>
+                      v === "none" ? t("adminLogs.noEvent") : v,
+                    )}
+                    selected={[state.event ?? ""]}
+                    onChange={([event]) => update({ event: event || null })}
+                    testId="logs-event"
+                  />
+                  <FilterSelect
+                    label={t("adminLogs.window")}
+                    options={WINDOWS.map((w) => ({ value: w, label: t(`adminLogs.windows.${w}`) }))}
+                    selected={[state.window]}
+                    onChange={([window]) => update({ window: window as LogWindow })}
+                    testId="logs-window"
+                  />
+                </>
+              )}
+              <span className="ml-auto flex gap-1.5">
+                <Button
+                  variant="outline"
+                  size="xs"
+                  icon={<Radio className="h-3.5 w-3.5" />}
+                  pressed={polling}
+                  onClick={toggleLive}
+                >
+                  {t("adminLogs.live")}
+                </Button>
+                <Button
+                  variant="outline"
+                  size="xs"
+                  icon={<Copy className="h-3.5 w-3.5" />}
+                  // While a filter change loads, the rows on screen are the previous filter's.
+                  disabled={rows.length === 0 || logs.isPlaceholderData}
+                  onClick={() => void copy()}
+                >
+                  {t("adminLogs.copy")}
+                </Button>
+              </span>
+            </div>
+
+            {(state.requestId || state.jobId !== null) && (
+              <div className="flex flex-wrap items-center gap-2 border-b border-border px-2 py-1.5 text-xs">
+                {state.requestId && (
+                  <PivotChip
+                    label={t("adminLogs.pivotRequest", { id: state.requestId })}
+                    clearLabel={t("adminLogs.clearPivot")}
+                    onClear={() => update({ requestId: null })}
+                  />
+                )}
+                {state.jobId !== null && (
+                  <PivotChip
+                    label={t("adminLogs.pivotJob", { id: state.jobId })}
+                    clearLabel={t("adminLogs.clearPivot")}
+                    onClear={() => update({ jobId: null })}
+                  />
+                )}
+              </div>
+            )}
+          </div>

          {failure && (
            <StateMessage
@@ -361,7 +391,7 @@ export default function AdminLogs() {
                {t("common.loadError")}
              </StateMessage>
            ) : logs.isLoading ? (
-              <LoadingState />
+              <LoadingState shape="table" />
            ) : rows.length === 0 ? (
              <p className="px-3 py-6 text-center font-sans text-sm text-muted">
                {t("adminLogs.empty")}
@@ -376,7 +406,7 @@ export default function AdminLogs() {
                    level={row.level}
                    event={row.event ?? "—"}
                    msg={row.msg}
-                    title={formatDateTime(row.ts)}
+                    title={formatDateTimeSec(row.ts)}
                    open={open === row.id}
                    onToggle={() => setOpen(open === row.id ? null : row.id)}
                  >
@@ -421,18 +451,9 @@ function PivotChip({
  onClear: () => void;
 }) {
  return (
-    <span className="chip py-0.5 pl-2.5 pr-1">
-      <span className="font-mono">{label}</span>
-      <button
-        type="button"
-        onClick={onClear}
-        aria-label={clearLabel}
-        title={clearLabel}
-        className="rounded-full p-0.5 hover:bg-accent/20"
-      >
-        <X className="h-3 w-3" aria-hidden />
-      </button>
-    </span>
+    <DismissibleChip onDismiss={onClear} dismissLabel={clearLabel} className="font-mono">
+      {label}
+    </DismissibleChip>
  );
 }

@@ -449,12 +470,12 @@ function RowDetail({
 }) {
  const { t } = useTranslation();
  const pivotCls =
-    "font-mono text-accent underline decoration-dotted underline-offset-2 hover:decoration-solid";
+    "font-mono underline decoration-dotted underline-offset-2 hover:decoration-solid";
  return (
    <div className="flex flex-col gap-2">
      <dl className="grid grid-cols-[max-content_minmax(0,1fr)] gap-x-3 gap-y-0.5 font-sans text-xs">
        <dt>{t("adminLogs.fields.when")}</dt>
-        <dd className="tabular-nums">{formatDateTime(row.ts)}</dd>
+        <dd className="tabular-nums">{formatDateTimeSec(row.ts)}</dd>
        <dt>{t("adminLogs.fields.source")}</dt>
        <dd className="font-mono">
          {row.source} · {row.logger}
@@ -465,14 +486,14 @@ function RowDetail({
          <>
            <dt>{t("adminLogs.fields.request")}</dt>
            <dd>
-              <button
-                type="button"
+              <Button
+                variant="link"
                className={pivotCls}
                title={t("adminLogs.showRequest")}
                onClick={() => onRequest(row.request_id!)}
              >
                {row.request_id}
-              </button>
+              </Button>
            </dd>
          </>
        )}
@@ -480,14 +501,14 @@ function RowDetail({
          <>
            <dt>{t("adminLogs.fields.job")}</dt>
            <dd>
-              <button
-                type="button"
+              <Button
+                variant="link"
                className={pivotCls}
                title={t("adminLogs.showJob")}
                onClick={() => onJob(row.job_id!)}
              >
                {row.job_id}
-              </button>
+              </Button>
            </dd>
          </>
        )}
@@ -98,6 +98,24 @@ describe("the last sign-in column (E22 S1)", () => {
  });
 });

+// E28 (owner): the hover ended wherever the row's first badge or button began, because the layer was
+// the name button's own. The card is the row: it paints the layer under its content, and the name
+// button's hit layer spans the card, under the actions that sit above it.
+describe("a user row", () => {
+  it("answers as a whole card, with its actions above the card's hit layer", async () => {
+    mount();
+    const open = await screen.findByTitle("users.account.open");
+    const card = open.parentElement!;
+    expect(card.className).toMatch(/(^|\s)isolate(\s|$)/);
+    expect(card.className).toMatch(/(^|\s)hover:before:bg-\(--hover\)(\s|$)/);
+    expect(open.className).toMatch(/(^|\s)after:inset-0(\s|$)/);
+    expect(open.className).not.toMatch(/selectable|hover:/);
+    const actions = [...card.querySelectorAll("button")].filter((b) => b !== open);
+    expect(actions.length).toBeGreaterThan(0);
+    for (const b of actions) expect(b.className).toMatch(/(^|\s)relative(\s|$)/);
+  });
+});
+
 describe("a user action that fails", () => {
  it("says a user who is gone, and refetches the list", async () => {
    const users = mount();
@@ -28,7 +28,9 @@ import { notify } from "../lib/notifications";
 import { formatDateTime, relativeTime } from "../lib/format";
 import { invalidateUserAccess } from "../lib/adminUsers";
 import { ADMIN_USERS_TAB_KEY } from "../lib/adminUsersTab";
+import { Badge } from "./ui/Badge";
 import { Button } from "./ui/Button";
+import { IconButton } from "./ui/IconButton";
 import Tooltip from "./ui/Tooltip";
 import InlineNotice from "./ui/InlineNotice";
 import { Section } from "./ui/form";
@@ -38,11 +40,14 @@ import { LoadingState, StateMessage } from "./ui/QueryState";
 import AccountPanel from "./AccountPanel";
 import { useConfirm } from "./confirmContext";
 import Tabs from "./ui/Tabs";
+import { useTabPanel } from "./ui/tabPanel";
 import { useAccountPersistedState } from "../lib/storage";
 import { PageToolbar } from "./ui/PageShell";
 import { useMe } from "../lib/useMe";
 import { notifyActionError, notifyKnownFailure } from "../lib/actionErrors";
-import { FocusSafeButton } from "./ui/FocusSafeButton";
+import { Pressable } from "./ui/Pressable";
+import { Input } from "./ui/Input";
+import { SURFACE } from "./ui/surfaces";

 // Admin-only user & access management: roles, access requests (the Invite whitelist), and the
 // demo whitelist + reset. Each section is its own tab (persisted across reloads); the Access tab
@@ -50,10 +55,18 @@ import { FocusSafeButton } from "./ui/FocusSafeButton";
 // (The tab key + a "focus the Access tab" helper live in lib/adminUsersTab so callers can
 // pre-select the tab without importing this lazy-loaded page — see that file.)

+// A user row's B3 layer (DESIGN.md "State layers"), painted by the card under its content, and the name
+// button's stretched hit layer over the whole card. Why the row is built so: at the row below.
+const ROW_LAYER =
+  "relative isolate before:absolute before:inset-0 before:z-under before:rounded-[inherit] before:transition-colors before:content-[''] hover:before:bg-(--hover) has-[[data-row-open]:active]:before:bg-(--press)";
+const ROW_OPEN =
+  "focus-visible:outline-none after:absolute after:inset-0 after:rounded-xl after:content-[''] focus-visible:after:outline-2 focus-visible:after:-outline-offset-2 focus-visible:after:outline-accent";
+
 export default function AdminUsers() {
  const me = useMe();
  const { t } = useTranslation();
  const [tab, setTab] = useAccountPersistedState(ADMIN_USERS_TAB_KEY, "roles");
+  const panel = useTabPanel();
  const tabs = [
    { id: "roles", label: t("users.tabs.roles") },
    // Both kinds of "waiting on the admin": a request needing a decision, and a sign-up whose
@@ -72,10 +85,10 @@ export default function AdminUsers() {
      {/* The tab bar is fixed chrome; the tab content scrolls under it. */}
      <PageToolbar>
        <div className="px-4 pt-2 max-w-3xl w-full mx-auto">
-          <Tabs tabs={tabs} active={active} onChange={setTab} />
+          <Tabs idBase={panel.idBase} tabs={tabs} active={active} onChange={setTab} />
        </div>
      </PageToolbar>
-      <div className="px-4 pb-4 pt-3 max-w-3xl w-full mx-auto">
+      <div {...panel.panelProps(active)} className="px-4 pb-4 pt-3 max-w-3xl w-full mx-auto">
        {active === "roles" && <UsersRoles me={me} />}
        {active === "access" && (
          <>
@@ -89,24 +102,6 @@ export default function AdminUsers() {
  );
 }

-function Badge({
-  tone,
-  children,
-}: {
-  tone: "accent" | "muted" | "warning";
-  children: React.ReactNode;
-}) {
-  const cls =
-    tone === "accent"
-      ? "border-accent/40 text-accent"
-      : tone === "warning"
-        ? "border-warn/40 text-warn"
-        : "border-border text-muted";
-  return (
-    <span className={`shrink-0 text-2xs px-2 py-0.5 rounded-full border ${cls}`}>{children}</span>
-  );
-}
-
 function UsersRoles({ me }: { me: Me }) {
  const { t } = useTranslation();
  const qc = useQueryClient();
@@ -221,7 +216,7 @@ function UsersRoles({ me }: { me: Me }) {
          {t("common.loadError")}
        </StateMessage>
      ) : q.isLoading && !q.data ? (
-        <LoadingState />
+        <LoadingState shape="list" />
      ) : rows.length === 0 ? (
        <p className="text-sm text-muted">{t("users.roles.empty")}</p>
      ) : (
@@ -229,28 +224,39 @@ function UsersRoles({ me }: { me: Me }) {
          {rows.map((u) => {
            const self = u.id === me.id;
            return (
-              <div key={u.id} className="glass-card flex items-center gap-2.5 p-2.5 rounded-xl">
-                <button
+              // The whole card is the row, so the whole card answers (owner, E28): the name's button
+              // stretches an invisible layer over the card (`after:inset-0`), so a click on a badge or
+              // a gap opens the account too, and the B3 hover layer is the card's own `::before`, under
+              // the badges and buttons (`isolate` + `z-under`). The actions are `relative`, above the
+              // stretched layer. The hover used to be the name button's own and ended at the first badge.
+              <div
+                key={u.id}
+                className={`${SURFACE.card} ${ROW_LAYER} flex items-center gap-2.5 p-2.5`}
+              >
+                <Pressable
+                  selectable
+                  data-row-open=""
                  onClick={() => setPanelFor(u)}
                  title={t("users.account.open")}
-                  className="selectable cursor-pointer min-w-0 flex-1 text-left rounded-lg -m-1 p-1"
+                  className={`min-w-0 flex-1 cursor-pointer ${ROW_OPEN}`}
                >
                  <div className="text-sm truncate">
                    {displayName(u)}
                    {self && <span className="text-muted"> · {t("users.roles.you")}</span>}
                  </div>
                  <div className="text-2xs text-muted truncate">{u.email}</div>
-                </button>
+                </Pressable>
                {u.role === "admin" && <Badge tone="accent">{t("users.roles.admin")}</Badge>}
-                {u.is_demo && <Badge tone="muted">{t("users.roles.demo")}</Badge>}
-                {u.is_suspended && <Badge tone="warning">{t("users.roles.suspended")}</Badge>}
-                {!u.is_active && <Badge tone="warning">{t("users.roles.pending")}</Badge>}
+                {u.is_demo && <Badge>{t("users.roles.demo")}</Badge>}
+                {u.is_suspended && <Badge tone="warn">{t("users.roles.suspended")}</Badge>}
+                {!u.is_active && <Badge tone="warn">{t("users.roles.pending")}</Badge>}
                {/* A Google sign-in proves the email, so "unverified" only applies to a
                    password-only account that hasn't clicked its verification link. */}
                {u.is_active && !u.email_verified && !u.has_google && (
-                  <Badge tone="warning">{t("users.roles.unverified")}</Badge>
+                  <Badge tone="warn">{t("users.roles.unverified")}</Badge>
                )}
                <Tooltip
+                  always={u.is_demo || self}
                  hint={
                    u.is_demo
                      ? t("users.roles.demoLocked")
@@ -264,15 +270,19 @@ function UsersRoles({ me }: { me: Me }) {
                  <Button
                    variant="glass"
                    size="xs"
-                    className="shrink-0"
+                    className="relative shrink-0"
                    onClick={() => onToggle(u)}
-                    disabled={u.is_demo || self || pendingIds.has(u.id)}
+                    // Locked (demo / self) is unavailable WITH a reason, the tooltip's: aria-disabled keeps it
+                    // focusable so a keyboard user reaches the reason. A pending write is transient.
+                    aria-disabled={u.is_demo || self}
+                    disabled={pendingIds.has(u.id)}
                    icon={<Shield className="w-3.5 h-3.5" />}
                  >
                    {u.role === "admin" ? t("users.roles.makeUser") : t("users.roles.makeAdmin")}
                  </Button>
                </Tooltip>
                <Tooltip
+                  always={u.is_demo || self}
                  hint={
                    u.is_demo
                      ? t("users.suspend.demoLocked")
@@ -283,36 +293,41 @@ function UsersRoles({ me }: { me: Me }) {
                          : t("users.suspend.action")
                  }
                >
-                  <Button
-                    variant={u.is_suspended ? "outline-warn" : "outline"}
-                    size="icon-sm"
-                    className="shrink-0"
-                    onClick={() => onSuspend(u)}
-                    disabled={u.is_demo || self || pendingIds.has(u.id)}
-                    aria-label={
+                  <IconButton
+                    noTitle
+                    label={
                      u.is_suspended ? t("users.suspend.undoAction") : t("users.suspend.action")
                    }
-                    icon={
-                      u.is_suspended ? (
-                        <RotateCcw className="w-4 h-4" />
-                      ) : (
-                        <Ban className="w-4 h-4" />
-                      )
-                    }
-                  />
+                    size="sm"
+                    variant={u.is_suspended ? "outline-warn" : "outline"}
+                    className="relative"
+                    onClick={() => onSuspend(u)}
+                    aria-disabled={u.is_demo || self}
+                    disabled={pendingIds.has(u.id)}
+                  >
+                    {u.is_suspended ? (
+                      <RotateCcw className="w-4 h-4" />
+                    ) : (
+                      <Ban className="w-4 h-4" />
+                    )}
+                  </IconButton>
                </Tooltip>
                <Tooltip
+                  always={u.is_demo || self}
                  hint={u.is_demo || self ? t("users.delete.locked") : t("users.delete.action")}
                >
-                  <Button
+                  <IconButton
+                    noTitle
+                    label={t("users.delete.action")}
+                    size="sm"
                    variant="outline-danger"
-                    size="icon-sm"
-                    className="shrink-0"
+                    className="relative"
                    onClick={() => onDelete(u)}
-                    disabled={u.is_demo || self || pendingIds.has(u.id)}
-                    aria-label={t("users.delete.action")}
-                    icon={<Trash2 className="w-4 h-4" />}
-                  />
+                    aria-disabled={u.is_demo || self}
+                    disabled={pendingIds.has(u.id)}
+                  >
+                    <Trash2 className="w-4 h-4" />
+                  </IconButton>
                </Tooltip>
                {/* How long ago this account last signed in. LAST in the row on purpose: the badges and
                    the role button before it vary in width row to row, so only the row's own right
@@ -327,7 +342,7 @@ function UsersRoles({ me }: { me: Me }) {
                        : t("users.roles.lastLoginNone")
                  }
                >
-                  <span className="hidden sm:inline-block w-20 shrink-0 text-right text-2xs text-muted tabular-nums">
+                  <span className="relative hidden sm:inline-block w-20 shrink-0 text-right text-2xs text-muted tabular-nums">
                    {u.last_login_at ? relativeTime(u.last_login_at) : "—"}
                  </span>
                </Tooltip>
@@ -392,7 +407,7 @@ function PendingAccess() {
          {t("common.loadError")}
        </StateMessage>
      ) : rows.isLoading && !rows.data ? (
-        <LoadingState />
+        <LoadingState shape="list" />
      ) : (
        <div className="space-y-1.5">
          {list.map((u) => (
@@ -427,7 +442,7 @@ function PendingAccessRowView({
 }) {
  const { t } = useTranslation();
  return (
-    <div className="glass-card flex items-center gap-2 p-2.5 rounded-xl">
+    <div className={`${SURFACE.card} flex items-center gap-2 p-2.5`}>
      <div className="min-w-0 flex-1">
        <div className="text-sm truncate">{row.email}</div>
        <div className="text-2xs text-muted flex items-center gap-2 mt-0.5 flex-wrap">
@@ -459,15 +474,16 @@ function PendingAccessRowView({
      </div>
      {!row.email_verified && (
        <Tooltip hint={t("users.pendingAccess.resendHint")}>
-          <Button
+          <IconButton
+            noTitle
+            label={t("users.pendingAccess.resend")}
+            size="sm"
            variant="outline"
-            size="icon-sm"
-            className="shrink-0"
            onClick={onResend}
            disabled={busy}
-            aria-label={t("users.pendingAccess.resend")}
-            icon={<Send className="w-4 h-4" />}
-          />
+          >
+            <Send className="w-4 h-4" />
+          </IconButton>
        </Tooltip>
      )}
      {row.can_activate && (
@@ -660,7 +676,7 @@ function AdminInvites() {
          {t("common.loadError")}
        </StateMessage>
      ) : invites.isLoading && !invites.data ? (
-        <LoadingState />
+        <LoadingState shape="list" />
      ) : pending.length === 0 ? (
        <p className="text-sm text-muted">{t("settings.invites.noPending")}</p>
      ) : (
@@ -685,12 +701,12 @@ function AdminInvites() {
        }}
        className="flex items-center gap-2 mt-3"
      >
-        <input
+        <Input
+          className="flex-1"
          type="email"
          value={newEmail}
          onChange={(e) => setNewEmail(e.target.value)}
          placeholder={t("settings.invites.addPlaceholder")}
-          className="flex-1 min-w-0 bg-surface border border-border rounded-xl px-3 py-2 text-sm focus:outline-hidden focus:ring-2 focus:ring-accent/40"
        />
        <Button
          type="submit"
@@ -729,18 +745,15 @@ function AdminInvites() {
                        : t("settings.invites.inviteHint")
                    }
                  >
-                    <FocusSafeButton
+                    <IconButton
+                      noTitle
                      onClick={() => onInvite(i)}
                      disabled={invite.isPending}
-                      className={`shrink-0 p-1 rounded-md disabled:opacity-50 transition ${
-                        i.invited_at
-                          ? "text-muted/50 hover:text-fg"
-                          : "text-muted hover:text-accent"
-                      }`}
-                      aria-label={t("settings.invites.inviteLabel", { email: i.email })}
+                      label={t("settings.invites.inviteLabel", { email: i.email })}
                    >
-                      <Mails className="w-3.5 h-3.5" />
-                    </FocusSafeButton>
+                      {/* Already invited: the glyph fades, the action stays (a resend). */}
+                      <Mails className={i.invited_at ? "opacity-50" : ""} />
+                    </IconButton>
                  </Tooltip>
                )}
                {/* An entry with an account behind it stays read-only: deleting it would revoke that
@@ -748,26 +761,24 @@ function AdminInvites() {
                {i.has_account ? (
                  // `disabled` would drop it from the tab order AND suppress the title, so the
                  // reason reached nobody — same call as the Playlists drag handle.
-                  <button
-                    type="button"
+                  <IconButton
                    aria-disabled
                    onClick={(e) => e.preventDefault()}
-                    title={t("settings.invites.deleteHasAccount")}
-                    aria-label={t("settings.invites.deleteHasAccount")}
-                    className="shrink-0 p-1 text-muted/50 cursor-not-allowed"
+                    label={t("settings.invites.deleteHasAccount")}
                  >
-                    <Trash2 className="w-3.5 h-3.5" />
-                  </button>
+                    <Trash2 />
+                  </IconButton>
                ) : (
                  <Tooltip hint={t("settings.invites.deleteHint")}>
-                    <FocusSafeButton
+                    <IconButton
+                      noTitle
+                      variant="danger"
                      onClick={() => onDelete(i)}
                      disabled={remove.isPending}
-                      className="shrink-0 p-1 rounded-md text-muted hover:text-danger disabled:opacity-50 transition"
-                      aria-label={t("settings.invites.deleteLabel", { email: i.email })}
+                      label={t("settings.invites.deleteLabel", { email: i.email })}
                    >
-                      <Trash2 className="w-3.5 h-3.5" />
-                    </FocusSafeButton>
+                      <Trash2 />
+                    </IconButton>
                  </Tooltip>
                )}
              </div>
@@ -831,7 +842,7 @@ function AdminDemo() {
      {rows.length > 0 && (
        <div className="space-y-1.5 mb-3">
          {rows.map((r) => (
-            <div key={r.id} className="glass-card flex items-center gap-2 p-2.5 rounded-xl">
+            <div key={r.id} className={`${SURFACE.card} flex items-center gap-2 p-2.5`}>
              <div className="min-w-0 flex-1">
                <div className="text-sm truncate">{r.email}</div>
                {r.added_by && (
@@ -841,15 +852,16 @@ function AdminDemo() {
                )}
              </div>
              <Tooltip hint={t("settings.demo.removeHint")}>
-                <Button
+                <IconButton
+                  noTitle
+                  label={t("settings.demo.remove")}
+                  size="sm"
                  variant="outline-danger"
-                  size="icon-sm"
-                  className="shrink-0"
                  onClick={() => onRemove(r)}
                  disabled={remove.isPending}
-                  aria-label={t("settings.demo.remove")}
-                  icon={<Trash2 className="w-4 h-4" />}
-                />
+                >
+                  <Trash2 className="w-4 h-4" />
+                </IconButton>
              </Tooltip>
            </div>
          ))}
@@ -863,12 +875,12 @@ function AdminDemo() {
        }}
        className="flex items-center gap-2"
      >
-        <input
+        <Input
+          className="flex-1"
          type="email"
          value={newEmail}
          onChange={(e) => setNewEmail(e.target.value)}
          placeholder={t("settings.demo.addPlaceholder")}
-          className="flex-1 min-w-0 bg-surface border border-border rounded-xl px-3 py-2 text-sm focus:outline-hidden focus:ring-2 focus:ring-accent/40"
        />
        <Button variant="glass" size="md" className="shrink-0" type="submit">
          <UserPlus className="w-4 h-4" /> {t("settings.demo.add")}
@@ -877,7 +889,11 @@ function AdminDemo() {

      <div className="mt-4 pt-3 border-t border-border">
        <Tooltip hint={t("settings.demo.resetHint")}>
-          <FocusSafeButton
+          <Button
+            variant="glass"
+            size="sm"
+            icon={<RotateCcw />}
+            loading={reset.isPending}
            onClick={async () => {
              if (
                await confirm({
@@ -889,12 +905,9 @@ function AdminDemo() {
              )
                reset.mutate();
            }}
-            disabled={reset.isPending}
-            className="glass-card glass-hover flex items-center gap-2 px-3 py-2 rounded-xl text-sm disabled:opacity-50 transition"
          >
-            <RotateCcw className={`w-4 h-4 ${reset.isPending ? "animate-spin" : ""}`} />
            {t("settings.demo.reset")}
-          </FocusSafeButton>
+          </Button>
        </Tooltip>
      </div>
    </Section>
@@ -916,7 +929,7 @@ function InviteRow({
 }) {
  const { t } = useTranslation();
  return (
-    <div className="glass-card flex items-center gap-2 p-2.5 rounded-xl">
+    <div className={`${SURFACE.card} flex items-center gap-2 p-2.5`}>
      <div className="min-w-0 flex-1">
        <div className="text-sm truncate">{inv.email}</div>
        {inv.requested_at && (
@@ -928,26 +941,28 @@ function InviteRow({
        )}
      </div>
      <Tooltip hint={t("settings.invites.approveHint")}>
-        <Button
+        <IconButton
+          noTitle
+          label={t("settings.invites.approve")}
+          size="sm"
          variant="outline-accent"
-          size="icon-sm"
-          className="shrink-0"
          onClick={onApprove}
          disabled={busy}
-          aria-label={t("settings.invites.approve")}
-          icon={<Check className="w-4 h-4" />}
-        />
+        >
+          <Check className="w-4 h-4" />
+        </IconButton>
      </Tooltip>
      <Tooltip hint={t("settings.invites.denyHint")}>
-        <Button
+        <IconButton
+          noTitle
+          label={t("settings.invites.deny")}
+          size="sm"
          variant="outline-danger"
-          size="icon-sm"
-          className="shrink-0"
          onClick={onDeny}
          disabled={busy}
-          aria-label={t("settings.invites.deny")}
-          icon={<X className="w-4 h-4" />}
-        />
+        >
+          <X className="w-4 h-4" />
+        </IconButton>
      </Tooltip>
      {/* Deny records a decision and keeps the row; delete forgets the address. Once an account
          exists for it the row is that account's approval gate, so it is managed from Users & roles
@@ -955,27 +970,26 @@ function InviteRow({
          silently missing a button their other rows have. */}
      {inv.has_account ? (
        // aria-disabled, not `disabled`: the reason has to stay reachable by keyboard.
-        <button
-          type="button"
+        <IconButton
+          variant="outline"
          aria-disabled
          onClick={(e) => e.preventDefault()}
-          title={t("settings.invites.deleteHasAccount")}
-          aria-label={t("settings.invites.deleteHasAccount")}
-          className="shrink-0 p-1.5 rounded-lg border border-border/50 text-muted/50 cursor-not-allowed"
+          label={t("settings.invites.deleteHasAccount")}
        >
-          <Trash2 className="w-4 h-4" />
-        </button>
+          <Trash2 />
+        </IconButton>
      ) : (
        <Tooltip hint={t("settings.invites.deleteHint")}>
-          <Button
+          <IconButton
+            noTitle
+            label={t("settings.invites.deleteLabel", { email: inv.email })}
+            size="sm"
            variant="outline-danger"
-            size="icon-sm"
-            className="shrink-0"
            onClick={onDelete}
            disabled={busy}
-            aria-label={t("settings.invites.deleteLabel", { email: inv.email })}
-            icon={<Trash2 className="w-4 h-4" />}
-          />
+          >
+            <Trash2 className="w-4 h-4" />
+          </IconButton>
        </Tooltip>
      )}
    </div>
@@ -62,7 +62,7 @@ export default function AuditLog() {
            {t("common.loadError")}
          </StateMessage>
        ) : q.isLoading ? (
-          <LoadingState />
+          <LoadingState shape="table" />
        ) : rows.length === 0 ? (
          <p className="text-sm text-muted">{t("audit.empty")}</p>
        ) : (
@@ -73,6 +73,8 @@ export default function AuditLog() {
              rowKey={(r) => String(r.id)}
              persistKey={LS.auditTable}
              controlsPosition="top"
+              controlsInBand
+              controlsBandClassName="px-4 max-w-5xl mx-auto"
              controlsLeading={
                <Button
                  variant="outline-danger"
@@ -191,6 +191,26 @@ describe("BootGate", () => {
    expect(sessionStorage.getItem(ACTIVE_ACCOUNT_KEY)).toBe("5");
  });

+  // The adoption effect is idempotent for the identity it already adopted, and that is load-bearing
+  // rather than tidy: a re-run reloads the page, so an effect that cannot tell "already adopted this
+  // account" from "adopted a different one" turns an ordinary boot into a reload loop. The spy is
+  // installed BEFORE mounting on purpose — the other reload tests stub it after the app is up, which
+  // is exactly late enough to miss the re-run that setting `readyFor` triggers.
+  it("a plain boot never reloads, however many times the adoption effect re-runs", async () => {
+    const reload = vi.fn();
+    vi.stubGlobal("location", { ...window.location, reload });
+    vi.spyOn(api, "me").mockResolvedValue(account());
+
+    const qc = mount();
+    await screen.findByTestId("app");
+    // Anything that re-renders the gate must leave it alone: a pref save, a background refetch.
+    act(() => qc.setQueryData(qk.me(), account({ preferences: { startup: "last" } })));
+    await act(() => new Promise((r) => setTimeout(r, 20)));
+
+    expect(reload).not.toHaveBeenCalled();
+    expect(mounts).toBe(1);
+  });
+
  it("a change to the account's data, not its identity, leaves the app as it is", async () => {
    vi.spyOn(api, "me").mockResolvedValue(account());
    const qc = mount();
@@ -1,4 +1,4 @@
-import { useLayoutEffect, useState, type ReactNode } from "react";
+import { useLayoutEffect, useRef, useState, type ReactNode } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { useTranslation } from "react-i18next";
 import { api, getActiveAccount, setActiveAccount } from "../lib/api";
@@ -30,7 +30,7 @@ import { LoadingState, StateMessage } from "./ui/QueryState";
 * Suspense fallback after it and the first page's own loading state keep one clock (see LoadingState). */
 export function BootScreen() {
  return (
-    <div className="min-h-screen grid place-items-center">
+    <div className="min-h-dvh grid place-items-center">
      <LoadingState since={0} delayMs={400} />
    </div>
  );
@@ -83,23 +83,31 @@ export default function BootGate({ children }: { children: ReactNode }) {
  //   • Adopt the account's language, which follows the account across devices — the local copy only
  //     knows what this browser last showed.
  const [readyFor, setReadyFor] = useState<number | null | undefined>(undefined);
+  // `me` is read for the identity it produced, so it rides a ref: a background refetch of the same
+  // account must not re-run the adoption over a language the user has just changed. That rule used
+  // to live in a dep list that excluded `me`, which made the dep list load-bearing for correctness —
+  // and the failure mode of getting it wrong was a page-reload loop, not a stale value.
+  const meRef = useRef(me);
+  meRef.current = me;
  useLayoutEffect(() => {
    if (identity === undefined) return;
    if (readyFor !== undefined) {
-      // The tree was built for another identity — see the header. The pin stays as it is: the tree
-      // being torn down still runs its unmount saves before the page goes, and with the pin moved they
-      // would land under the new account's local keys. The reloaded page's first probe corrects it.
-      location.reload();
+      // Already adopted. Only a DIFFERENT identity reloads: the tree was built for another account —
+      // see the header. The pin stays as it is: the tree being torn down still runs its unmount saves
+      // before the page goes, and with the pin moved they would land under the new account's local
+      // keys. The reloaded page's first probe corrects it. Comparing rather than merely testing for
+      // "set" is what makes this effect idempotent, so a re-run for any other reason is a no-op
+      // instead of a reload.
+      if (readyFor !== identity) location.reload();
      return;
    }
-    if (me && getActiveAccount() !== me.id) setActiveAccount(me.id);
-    const lang = me?.preferences?.language;
+    const account = meRef.current;
+    if (account && getActiveAccount() !== account.id) setActiveAccount(account.id);
+    const lang = account?.preferences?.language;
    if (typeof lang === "string" && isSupported(lang) && lang !== i18n.language) setLanguage(lang);
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- the adoption latch. It cannot be derived: the whole point is that the tree mounts only AFTER the pin and the language have been applied, and both are writes to things outside React (sessionStorage, i18n). A layout effect so the frame that first shows the app already has them.
    setReadyFor(identity);
-    // `me` is read for the identity it produced; a background refetch of the same account must not
-    // re-run the adoption over a language the user has just changed.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [identity]);
+  }, [identity, readyFor]);

  // No answer at all (a network or 5xx failure on the very first setup or account probe — past the
  // one retry `req` already makes): say so, with a retry. An unanswered setup probe is NOT "signed
@@ -113,7 +121,7 @@ export default function BootGate({ children }: { children: ReactNode }) {
        : null;
  if (failed)
    return (
-      <div className="min-h-screen grid place-items-center">
+      <div className="min-h-dvh grid place-items-center">
        <StateMessage tone="error" onRetry={() => failed.refetch()}>
          {t("common.somethingWrong")}
        </StateMessage>
@@ -2,6 +2,7 @@ import { useTranslation } from "react-i18next";
 import { ExternalLink } from "lucide-react";
 import type { ChannelDetail } from "../lib/api";
 import { linkify } from "../lib/linkify";
+import { Badge } from "./ui/Badge";

 // --- About-tab metadata helpers (shared by the channel page and the manager's About overlay) ---
 function displayName(code: string, lang: string, type: "region" | "language"): string {
@@ -50,7 +51,7 @@ export default function ChannelAboutContent({ ch }: { ch: ChannelDetail }) {
  return (
    <>
      {ch.description ? (
-        <p className="text-sm whitespace-pre-wrap wrap-break-word leading-relaxed">
+        <p className="measure text-sm whitespace-pre-wrap wrap-break-word leading-relaxed">
          {linkify(ch.description)}
        </p>
      ) : (
@@ -101,9 +102,7 @@ export default function ChannelAboutContent({ ch }: { ch: ChannelDetail }) {
              <div className="flex flex-wrap gap-1.5">
                {/* Future search epic: these topic chips become clickable filters. */}
                {topics.map((tp) => (
-                  <span key={tp} className="glass-card px-2 py-0.5 rounded-full text-xs">
-                    {tp}
-                  </span>
+                  <Badge key={tp}>{tp}</Badge>
                ))}
              </div>
            </div>
@@ -113,9 +112,7 @@ export default function ChannelAboutContent({ ch }: { ch: ChannelDetail }) {
              <span className="text-muted w-24 shrink-0 pt-0.5">{t("channel.keywords")}</span>
              <div className="flex flex-wrap gap-1.5">
                {keywords.map((kw, i) => (
-                  <span key={i} className="glass-card px-2 py-0.5 rounded-full text-xs">
-                    {kw}
-                  </span>
+                  <Badge key={i}>{kw}</Badge>
                ))}
              </div>
            </div>
@@ -2,6 +2,7 @@ import { useEffect } from "react";
 import { useTranslation } from "react-i18next";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { qk } from "../lib/queryKeys";
+import { invalidateSubscription } from "../lib/subscriptionCache";
 import { UserPlus } from "lucide-react";
 import { api, type DiscoveredChannel } from "../lib/api";
 import { accountKey, LS } from "../lib/storage";
@@ -23,7 +24,7 @@ import Pager from "./ui/Pager";
 import { PageToolbar } from "./ui/PageShell";
 import { useConfirm } from "./confirmContext";
 import { useChannelLayout } from "./channelsContext";
-import { FocusSafeButton } from "./ui/FocusSafeButton";
+import { Button } from "./ui/Button";

 // The Channel manager's "Discovery" tab: channels that turn up in the user's playlists but
 // that they don't subscribe to. Subscribing here only creates the subscription + enriches
@@ -58,9 +59,7 @@ export default function ChannelDiscovery({
    onSuccess: (_data, c) => {
      // The channel moves from "discovery" to "subscribed", and its videos will start
      // arriving — refresh both lists plus the per-user status.
-      qc.invalidateQueries({ queryKey: qk.discoveredChannels() });
-      qc.invalidateQueries({ queryKey: qk.channels() });
-      qc.invalidateQueries({ queryKey: qk.myStatus() });
+      invalidateSubscription(qc, c.id);
      const name = c.title ?? c.id;
      // Name the channel and ship a typed payload so the inbox can offer "open in the
      // Channel manager" / "open on YouTube" links — kept after reload, when live
@@ -93,8 +92,8 @@ export default function ChannelDiscovery({
  );

  const columns: Column<DiscoveredChannel>[] = [
-    // Actions first, mirroring the Subscriptions table (where it sits right after Prio) so the two
-    // tabs' action clusters line up in the same place.
+    // Subscribe first: it is this table's primary action, the one thing a discovery row is for (the
+    // Subscriptions table has no such button — its row ends in the channel's "…", E28 C1).
    {
      key: "actions",
      header: t("channels.cols.actions"),
@@ -104,20 +103,21 @@ export default function ChannelDiscovery({
      cardLabel: false,
      render: (c) => (
        <Tooltip
+          always={!canWrite}
          hint={
            canWrite ? t("channels.discovery.subscribeHint") : t("channels.discovery.needWriteHint")
          }
        >
-          <FocusSafeButton
-            // Busy blocks the click, not the focus (FocusSafeButton).
+          <Button
+            variant="glass"
+            size="xs"
+            icon={<UserPlus />}
            onClick={() => onSubscribe(c)}
-            disabled={!canWrite}
-            busy={subscribe.isPending}
-            className="glass-card glass-hover inline-flex items-center gap-1.5 px-2.5 py-1.5 rounded-lg text-xs disabled:opacity-50 aria-disabled:opacity-50 transition"
+            aria-disabled={!canWrite}
+            loading={subscribe.isPending}
          >
-            <UserPlus className="w-3.5 h-3.5" />
            {t("channels.discovery.subscribe")}
-          </FocusSafeButton>
+          </Button>
        </Tooltip>
      ),
    },
@@ -201,34 +201,33 @@ export default function ChannelDiscovery({

  return (
    <>
-      {/* Intro + the table controls are fixed chrome; only the table rows scroll (sticky header). */}
+      {/* The table controls are the page's band (B4); only the rows scroll (sticky header). The intro
+          scrolls with them: in the band it held two lines of a short window for text read once. */}
      <PageToolbar>
-        <div className="px-4 pt-2 max-w-384 mx-auto flex items-start justify-between gap-4">
-          <p className="text-xs text-muted leading-relaxed">{t("channels.discovery.intro")}</p>
-          {/* Cards has no column headers, so a dropdown drives the sort + a pager (table uses its own). */}
-          {layout === "cards" && (
-            <div className="flex items-center gap-3 shrink-0">
-              <Pager {...pagerProps} />
-              <ColumnSortControl
-                columns={columns}
-                sort={sort}
-                onChange={setSort}
-                label={t("channels.sort.label")}
-                defaultLabel={t("channels.sort.default")}
-                ascLabel={t("channels.sort.asc")}
-                descLabel={t("channels.sort.desc")}
-              />
-            </div>
-          )}
-        </div>
+        {/* Cards has no column headers, so a dropdown drives the sort + a pager (table uses its own). */}
+        {layout === "cards" && (
+          <div className="px-4 pt-2 max-w-384 mx-auto flex items-center justify-end gap-3">
+            <Pager {...pagerProps} />
+            <ColumnSortControl
+              columns={columns}
+              sort={sort}
+              onChange={setSort}
+              label={t("channels.sort.label")}
+              defaultLabel={t("channels.sort.default")}
+              ascLabel={t("channels.sort.asc")}
+              descLabel={t("channels.sort.desc")}
+            />
+          </div>
+        )}
      </PageToolbar>
      <div className="px-4 pb-4 max-w-384 mx-auto">
+        <p className="text-xs text-muted leading-relaxed pt-2">{t("channels.discovery.intro")}</p>
        {query.isError && !query.data ? (
          <StateMessage tone="error" onRetry={() => query.refetch()}>
            {t("common.loadError")}
          </StateMessage>
        ) : query.isLoading ? (
-          <LoadingState label={t("channels.discovery.loading")} />
+          <LoadingState shape="list" label={t("channels.discovery.loading")} />
        ) : layout === "table" ? (
          <DataTable
            rows={rows}
@@ -85,3 +85,20 @@ describe("ChannelLayoutGrid · keyboard", () => {
    expect(opened).toEqual(["UCb"]);
  });
 });
+
+describe('ChannelLayoutGrid · the card\'s "…"', () => {
+  it("docks it in the heading row beside the name, not in the meta line", () => {
+    const columns: Column<Ch>[] = [
+      { key: "channel", header: "Channel", cardPrimary: true, render: (c) => <b>{c.title}</b> },
+      { key: "stored", header: "Stored", render: () => <i>12</i> },
+      { key: "actions", header: "", render: (c) => <u data-testid={`more-${c.id}`}>…</u> },
+    ];
+    const { getByTestId, getByText } = render(
+      <ChannelLayoutGrid rows={rows} columns={columns} rowKey={(c) => c.id} moreKey="actions" />,
+    );
+    const heading = getByText("Alpha").closest("div")!.parentElement!;
+    expect(heading.contains(getByTestId("more-UCa"))).toBe(true);
+    // Exactly once: a slotted column is not also painted in the meta line.
+    expect(document.querySelectorAll('[data-testid="more-UCa"]')).toHaveLength(1);
+  });
+});
@@ -4,6 +4,7 @@ import { type Column } from "./ui/DataTable";
 import VirtualGrid from "./ui/VirtualGrid";
 import { CHANNEL_LAYOUT_SPEC } from "../lib/channelLayout";
 import { navItemAttrs } from "../lib/listNav";
+import { SURFACE } from "./ui/surfaces";

 // The channel manager's `cards` layout (E4 S3), built by reusing the SAME `Column<T>` render closures
 // the DataTable draws — so the subscribed and discovery tables (which have different columns) both get
@@ -27,6 +28,9 @@ interface ChannelLayoutGridProps<T> {
  aboutKey?: string;
  /** Column key rendered as the action cluster, pinned to the card's bottom edge. */
  actionsKey?: string;
+  /** Column key docked at the top-right corner after the lead: the card's "…" (E28 C1), which
+   *  belongs beside the name it acts on, not under the card's last line. */
+  moreKey?: string;
  rowClassName?: (row: T) => string;
  /** Extra DOM props per card — same escape hatch, same single consumer, as `DataTable.rowProps`, so
   *  a channel answers the right-click in the card layout exactly as it does in the table. */
@@ -41,6 +45,7 @@ export default function ChannelLayoutGrid<T>({
  leadKey,
  aboutKey,
  actionsKey,
+  moreKey,
  rowClassName,
  rowProps,
  emptyText,
@@ -48,11 +53,12 @@ export default function ChannelLayoutGrid<T>({
  const { t } = useTranslation();
  const spec = CHANNEL_LAYOUT_SPEC.cards;

-  const slotted = new Set([leadKey, aboutKey, actionsKey].filter(Boolean) as string[]);
+  const slotted = new Set([leadKey, aboutKey, actionsKey, moreKey].filter(Boolean) as string[]);
  const primary = columns.filter((c) => c.cardPrimary);
  const lead = leadKey ? columns.find((c) => c.key === leadKey) : undefined;
  const about = aboutKey ? columns.find((c) => c.key === aboutKey) : undefined;
  const actions = actionsKey ? columns.find((c) => c.key === actionsKey) : undefined;
+  const more = moreKey ? columns.find((c) => c.key === moreKey) : undefined;
  // Everything else flows in the meta line: not the heading, not a slotted column.
  const meta = columns.filter((c) => !c.cardPrimary && !slotted.has(c.key));

@@ -60,7 +66,7 @@ export default function ChannelLayoutGrid<T>({
    <div
      {...rowProps?.(row)}
      {...navItemAttrs(index)}
-      className={`glass-card rounded-xl p-3 h-full flex flex-col gap-2 ${rowClassName?.(row) ?? ""}`}
+      className={`${SURFACE.card} p-3 h-full flex flex-col gap-2 ${rowClassName?.(row) ?? ""}`}
    >
      <div className="flex items-start justify-between gap-2">
        <div className="min-w-0 flex-1 font-medium">
@@ -69,6 +75,7 @@ export default function ChannelLayoutGrid<T>({
          ))}
        </div>
        {lead && <div className="shrink-0">{lead.render(row)}</div>}
+        {more && <div className="shrink-0 -my-1">{more.render(row)}</div>}
      </div>
      {about && <div className="min-w-0 text-sm">{about.render(row)}</div>}
      <div className="flex flex-wrap items-center gap-x-3 gap-y-1.5 text-sm min-w-0">
@@ -1,8 +1,9 @@
 import { useTranslation } from "react-i18next";
 import { ExternalLink } from "lucide-react";
 import Avatar from "./ui/Avatar";
-import Tooltip from "./ui/Tooltip";
 import { channelYouTubeUrl } from "../lib/format";
+import { Pressable } from "./ui/Pressable";
+import { IconLink } from "./ui/LinkButton";

 // Avatar + channel name + "open on YouTube" link, shared by the Channel manager and the
 // discovery list (and anywhere else that lists a channel). When `onView` is given the name
@@ -28,7 +29,8 @@ export default function ChannelLink({
    <div className="flex items-center gap-2 min-w-0">
      <Avatar src={thumbnailUrl} fallback={title ?? ""} className="w-8 h-8 rounded-full shrink-0" />
      {onView ? (
-        <button
+        <Pressable
+          selectable
          onClick={onView}
          // The channel's "open" element: in a keyboard-walkable list (lib/listNav) Enter on the row or
          // card clicks this.
@@ -46,26 +48,24 @@ export default function ChannelLink({
          }}
          // title = the full name, so a truncated fluid-column name is still readable on hover.
          title={name}
-          className="text-sm font-medium truncate hover:text-accent text-left min-w-0"
+          className="min-h-6 min-w-0 truncate text-sm font-medium hover:text-accent pointer-coarse:min-h-(--touch-target)"
        >
          {name}
-        </button>
+        </Pressable>
      ) : (
        <span title={name} className="text-sm font-medium truncate min-w-0">
          {name}
        </span>
      )}
-      <Tooltip hint={t("channels.row.openOnYouTube")}>
-        <a
-          href={ytUrl}
-          target="_blank"
-          rel="noopener noreferrer"
-          className="text-muted hover:text-accent shrink-0"
-          aria-label={t("channels.row.openOnYouTube")}
-        >
-          <ExternalLink className="w-3.5 h-3.5" />
-        </a>
-      </Tooltip>
+      <IconLink
+        href={ytUrl}
+        target="_blank"
+        rel="noopener noreferrer"
+        label={t("channels.row.openOnYouTube")}
+        className="shrink-0"
+      >
+        <ExternalLink />
+      </IconLink>
    </div>
  );
 }
@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+//
+// The channel banner is served from Google's image CDN (yt3.googleusercontent.com), which refuses a
+// request that carries a Referer from our origin — every time, not only under load (measured
+// 2026-09-26: 6/6 refused with the page's referrer or its bare origin, 8/8 served without one). So the
+// banner <img> must send none, as ui/Avatar does for the same CDN; with a referrer the banner never
+// showed and the page fell back to the blank bar.
+import type { ReactNode } from "react";
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, cleanup, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+}));
+vi.mock("./navigationContext", () => ({
+  useNavigationActions: () => ({ closeChannel: vi.fn(), openChannel: vi.fn() }),
+}));
+vi.mock("./confirmContext", () => ({ useConfirm: () => async () => true }));
+vi.mock("./feedFiltersContext", () => ({
+  useFeedFilters: () => ({ includeNormal: true, includeShorts: false, includeLive: false }),
+}));
+vi.mock("./Feed", () => ({ default: () => null }));
+vi.mock("./ChannelAbout", () => ({ default: () => null }));
+// The page's chrome portals into the shell's fixed toolbar band, which this test has no shell for.
+vi.mock("./ui/PageShell", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./ui/PageShell")>()),
+  PageToolbar: ({ children }: { children?: ReactNode }) => <>{children}</>,
+}));
+
+import ChannelPage from "./ChannelPage";
+import { api, type ChannelDetail, type Me } from "../lib/api";
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+});
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+const CH = "UCqoAEDirJPjEUFcF2FklnBA";
+
+describe("ChannelPage — the banner", () => {
+  it("is requested without a referrer, which Google's image CDN refuses", async () => {
+    vi.spyOn(api, "channelDetail").mockResolvedValue({
+      id: CH,
+      title: "StarTalk",
+      banner_url: "https://yt3.googleusercontent.com/banner",
+      subscribed: true,
+      blocked: false,
+      hidden: false,
+      deep_requested: false,
+      backfill_done: true,
+      stored_videos: 10,
+    } as unknown as ChannelDetail);
+    vi.spyOn(api, "tags").mockResolvedValue([] as never);
+    const { container } = render(
+      <QueryClientProvider
+        client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}
+      >
+        <ChannelPage
+          channelId={CH}
+          initialName="StarTalk"
+          me={{ id: 1, can_write: true } as unknown as Me}
+          view="cards"
+          setView={() => {}}
+          onShowInFeed={() => {}}
+        />
+      </QueryClientProvider>,
+    );
+    const banner = await waitFor(() => {
+      const img = container.querySelector<HTMLImageElement>('img[src^="https://yt3."]');
+      expect(img).not.toBeNull();
+      return img!;
+    });
+    expect(banner.getAttribute("referrerpolicy")).toBe("no-referrer");
+  });
+});
@@ -6,7 +6,7 @@
 // ui/Button in E11 S2), so a busy toggle blocks the click with aria-disabled instead — focusable, and
 // still pressed only once.
 import type { ReactNode } from "react";
-import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeAll, afterEach, onTestFinished } from "vitest";
 import { render, screen, fireEvent, waitFor, cleanup, act } from "@testing-library/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

@@ -97,3 +97,53 @@ describe("ChannelPage — a busy toggle keeps the keyboard", () => {
    },
  );
 });
+
+// The banner is retried on error (googleusercontent drops a burst); while an attempt fails and the
+// next waits, a visible <img> shows the browser's broken-image glyph (seen live, E28). It stays
+// invisible until a source has actually loaded.
+describe("ChannelPage — the banner", () => {
+  it("is invisible until it loads, and again while a failed attempt is retried", async () => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+    onTestFinished(() => {
+      vi.useRealTimers();
+    });
+    vi.spyOn(api, "channelDetail").mockResolvedValue({
+      id: CH,
+      title: "LEMMiNO",
+      subscribed: true,
+      blocked: false,
+      hidden: false,
+      deep_requested: false,
+      backfill_done: true,
+      stored_videos: 10,
+      banner_url: "https://yt3.example/banner",
+    } as unknown as ChannelDetail);
+    vi.spyOn(api, "tags").mockResolvedValue([] as never);
+    const { container } = render(
+      <QueryClientProvider
+        client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}
+      >
+        <ChannelPage
+          channelId={CH}
+          initialName="LEMMiNO"
+          me={{ id: 1, can_write: true } as unknown as Me}
+          view="cards"
+          setView={() => {}}
+          onShowInFeed={() => {}}
+        />
+      </QueryClientProvider>,
+    );
+    const banner = () =>
+      container.querySelector<HTMLImageElement>('img[src^="https://yt3.example/banner"]')!;
+    await waitFor(() => expect(banner()).toBeTruthy());
+    expect(banner().classList.contains("opacity-0")).toBe(true);
+    fireEvent.error(banner());
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(600);
+    });
+    expect(banner().getAttribute("src")).toContain("?r=1");
+    expect(banner().classList.contains("opacity-0")).toBe(true);
+    fireEvent.load(banner());
+    expect(banner().classList.contains("opacity-0")).toBe(false);
+  });
+});
@@ -4,6 +4,7 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useLiveQuery } from "../lib/useLiveQuery";
 import { channelDetailPollMs, useBackfillFeedRefresh } from "../lib/channelDetailPoll";
 import { qk } from "../lib/queryKeys";
+import { invalidateSubscription } from "../lib/subscriptionCache";
 import { useNavigationActions } from "./navigationContext";
 import { PriorityStepper } from "./ui/PriorityStepper";
 import { useChannelPriority } from "../lib/useChannelPriority";
@@ -22,6 +23,7 @@ import {
 } from "lucide-react";
 import Avatar from "./ui/Avatar";
 import Tabs from "./ui/Tabs";
+import { useTabPanel } from "./ui/tabPanel";
 import Feed from "./Feed";
 import ChannelAboutContent from "./ChannelAbout";
 import { PageToolbar } from "./ui/PageShell";
@@ -33,11 +35,13 @@ import { notifyYouTubeActionError } from "../lib/youtubeErrors";
 import { notifyActionError } from "../lib/actionErrors";
 import { api, DEFAULT_TAG_MODES, type FeedFilters, type Me, type ChannelDetail } from "../lib/api";
 import type { FeedView } from "../lib/feedView";
-import { channelYouTubeUrl, formatViews } from "../lib/format";
+import { channelYouTubeUrl, formatDate, formatViews } from "../lib/format";
 import { ChannelTagsControl } from "./ChannelTags";
 import { useChannelTagActions } from "../lib/useChannelTagActions";
 import { Button } from "./ui/Button";
-import { FocusSafeButton } from "./ui/FocusSafeButton";
+import { IconButton } from "./ui/IconButton";
+import { IconLink } from "./ui/LinkButton";
+import { PageHeading } from "./ui/Headings";

 // A dedicated channel page: an "About"-style header (banner, avatar, stats, subscribe) over the
 // channel's videos (the catalog filtered to this channel). For an un-subscribed channel it
@@ -74,18 +78,22 @@ export default function ChannelPage({
  // inherit it instead of forcing Live/Upcoming on. The channel toolbar can still toggle these.
  const globalFilters = useFeedFilters();
  const [tab, setTab] = useState<"videos" | "about">("videos");
+  const panel = useTabPanel();
  // The whole channel chrome (banner, identity, tabs, toolbar) is fixed: it portals into the shell's
  // fixed band so only the video grid scrolls. This node sits at the bottom of that chrome and is
  // where the channelScoped Feed portals ITS toolbar (via the overridden PageToolbarSlot below), so
  // the toolbar lands under the tabs inside the fixed band rather than in the scroller.
  const [chromeSlot, setChromeSlot] = useState<HTMLDivElement | null>(null);
-  // The banner URL is valid, but googleusercontent intermittently throttles it when the channel
-  // page fires the banner + avatar + ~16 thumbnails in one burst — the request is dropped and the
-  // browser then NEGATIVE-CACHES the miss, so the banner stays broken even though a retry would
-  // succeed. So on error we retry a few times with a cache-buster (forcing a fresh request), and
-  // only fall back to the blank bar if it keeps failing (a genuinely dead URL — rare).
+  // The banner comes from Google's image CDN, which refuses any request carrying a Referer from our
+  // origin — every time, not only in a burst (measured 2026-09-26) — so the <img> sends none
+  // (`referrerPolicy`, as ui/Avatar). A load can still drop, and the browser NEGATIVE-CACHES the miss,
+  // so on error we retry a few times with a cache-buster (forcing a fresh request), and only fall
+  // back to the blank bar if it keeps failing (a genuinely dead URL — rare).
  const MAX_BANNER_RETRIES = 3;
  const [bannerAttempt, setBannerAttempt] = useState(0);
+  // The banner source that has actually loaded. Until then the <img> is invisible: an attempt that
+  // fails shows the browser's broken-image glyph for as long as the retry waits (seen live, E28).
+  const [bannerLoaded, setBannerLoaded] = useState<string | null>(null);

  // A LIVE query: while THIS user's full-history backfill is running, poll so the stored count (and
  // the N/S/L breakdown) climb on their own — the immediate backfill fills it in seconds, and the
@@ -95,7 +103,13 @@ export default function ChannelPage({
    intervalMs: channelDetailPollMs,
  });
  const ch = detail.data;
-  useEffect(() => setBannerAttempt(0), [ch?.banner_url]); // fresh channel/banner → try again
+  // A fresh channel/banner gets the retries back, in the render that changes it: as an effect the
+  // new banner was committed with the previous one's exhausted attempt count still in place.
+  const [bannerFor, setBannerFor] = useState(ch?.banner_url);
+  if (bannerFor !== ch?.banner_url) {
+    setBannerFor(ch?.banner_url);
+    setBannerAttempt(0);
+  }
  // The poll above is also the ONLY signal that the running backfill has written videos, so it
  // drives the video grid's refresh too (the "Get full history" mutation below can't: it fires on
  // the PATCH response, before the background job has stored anything).
@@ -137,6 +151,7 @@ export default function ChannelPage({
    if (ch.subscribed || ch.blocked) return;
    if (ch.explored && ch.stored_videos > 0) return;
    autoTried.current = channelId;
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- a one-off INGEST of an unsubscribed channel's uploads on first visit — a network side effect, not state. The autoTried ref keyed on the channel id is what makes it once per channel.
    void runExplore();
  }, [ch, channelId, me.is_demo, runExplore]);

@@ -167,12 +182,7 @@ export default function ChannelPage({
  const subscribe = useMutation({
    mutationFn: () => api.subscribeChannel(channelId),
    onSuccess: () => {
-      qc.invalidateQueries({ queryKey: qk.channel(channelId) });
-      qc.invalidateQueries({ queryKey: qk.feed() });
-      qc.invalidateQueries({ queryKey: qk.channels() });
-      // Match ChannelDiscovery: the channel leaves discovery and the manager's stats move.
-      qc.invalidateQueries({ queryKey: qk.myStatus() });
-      qc.invalidateQueries({ queryKey: qk.discoveredChannels() });
+      invalidateSubscription(qc, channelId);
      notify({ level: "info", message: t("channel.subscribed", { name: ch?.title ?? "" }) });
    },
    // A 403 (missing write scope) otherwise fails silently on the channel page (no wizard handle
@@ -181,11 +191,7 @@ export default function ChannelPage({
  });
  const unsubscribe = useMutation({
    mutationFn: () => api.unsubscribeChannel(channelId),
-    onSuccess: () => {
-      qc.invalidateQueries({ queryKey: qk.channel(channelId) });
-      qc.invalidateQueries({ queryKey: qk.feed() });
-      qc.invalidateQueries({ queryKey: qk.channels() });
-    },
+    onSuccess: () => invalidateSubscription(qc, channelId),
    onError: (err) => notifyYouTubeActionError(err, t("channels.notify.unsubscribeFailed")),
  });
  // "Get full history": the catalog only holds the recent-backfill/RSS subset of a channel's
@@ -273,12 +279,7 @@ export default function ChannelPage({

  const name = ch?.title ?? initialName ?? channelId;
  const ytUrl = channelYouTubeUrl(channelId, ch?.handle);
-  const joined = ch?.published_at
-    ? new Date(ch.published_at).toLocaleDateString(i18n.language, {
-        year: "numeric",
-        month: "short",
-      })
-    : null;
+  const joined = ch?.published_at ? formatDate(ch.published_at, i18n.language) : null;
  // Handle + stats on one compact meta line under the name (saves the separate stats row).
  const metaParts = [
    ch?.handle ? `@${ch.handle.replace(/^@/, "")}` : null,
@@ -310,12 +311,15 @@ export default function ChannelPage({
  // The channel page owns no scroller of its own (PageShell provides the one app scroller). Its
  // whole chrome is fixed — wrapped in <PageToolbar> it portals into the shell's fixed band, so the
  // banner/identity/tabs/toolbar stay put and only the video grid scrolls.
+  const bannerSrc = ch?.banner_url
+    ? `${ch.banner_url}=w1707${bannerAttempt ? `?r=${bannerAttempt}` : ""}`
+    : null;
  return (
    <>
      <PageToolbar>
        {/* Banner + back — OPTION C: inset, rounded card (not full-bleed) */}
        <div className="relative px-4 sm:px-6 pt-3">
-          {ch?.banner_url && bannerAttempt <= MAX_BANNER_RETRIES ? (
+          {bannerSrc && bannerAttempt <= MAX_BANNER_RETRIES ? (
            // Match YouTube's banner: the stored bannerExternalUrl is the full 16:9 template at a
            // low default size, so request a crisp wide version (=w1707) and object-cover the
            // desktop "safe area" — the centre 2560×423 (~6:1) band.
@@ -327,9 +331,13 @@ export default function ChannelPage({
                // key forces a fresh <img> per attempt; the ?r= cache-buster on a retry bypasses the
                // browser's negative cache (googleusercontent accepts an extra query param).
                key={bannerAttempt}
-                src={`${ch.banner_url}=w1707${bannerAttempt ? `?r=${bannerAttempt}` : ""}`}
+                src={bannerSrc}
+                referrerPolicy="no-referrer"
                alt=""
-                className="w-full h-full object-cover object-center"
+                className={`w-full h-full object-cover object-center ${
+                  bannerLoaded === bannerSrc ? "" : "opacity-0"
+                }`}
+                onLoad={() => setBannerLoaded(bannerSrc)}
                onError={() => {
                  if (bannerAttempt <= MAX_BANNER_RETRIES) {
                    window.setTimeout(
@@ -349,14 +357,15 @@ export default function ChannelPage({
              style={{ aspectRatio: "2560 / 423", maxHeight: "150px" }}
            />
          )}
-          <button
+          <Button
+            variant="media"
            data-testid="channel-back"
+            icon={<ArrowLeft />}
            onClick={closeChannel}
-            className="absolute top-5 left-7 sm:left-9 z-base inline-flex items-center gap-1.5 px-3 py-1.5 rounded-lg text-sm bg-black/45 text-white hover:bg-black/65 backdrop-blur-xs"
+            className="absolute top-5 left-7 sm:left-9 z-base backdrop-blur-xs"
          >
-            <ArrowLeft className="w-4 h-4" />
            {t("channel.back")}
-          </button>
+          </Button>
        </div>

        <div className="px-4 sm:px-6">
@@ -370,9 +379,9 @@ export default function ChannelPage({
            />
            <div className="flex-1 min-w-0 pb-1">
              <div className="flex items-center gap-2 flex-wrap">
-                <h1 data-testid="channel-title" className="text-xl font-semibold truncate">
+                <PageHeading data-testid="channel-title" className="text-xl font-semibold truncate">
                  {name}
-                </h1>
+                </PageHeading>
                {ch?.blocked ? (
                  <span className="text-xs px-2 py-0.5 rounded-full bg-danger/15 text-danger">
                    {t("channel.blockedBadge")}
@@ -409,6 +418,7 @@ export default function ChannelPage({
            within a few pixels of each other instead of across the page. */}
          <div className="flex items-center gap-2 mt-3 border-b border-border pb-2">
            <Tabs
+              idBase={panel.idBase}
              className="flex gap-1"
              active={tab}
              onChange={(id) => setTab(id as "videos" | "about")}
@@ -418,25 +428,25 @@ export default function ChannelPage({
              ]}
            />
            <div className="ml-2 flex items-center gap-2">
-              <a
+              <IconLink
                href={ytUrl}
                target="_blank"
                rel="noreferrer"
-                title={t("channels.row.openOnYouTube")}
-                aria-label={t("channels.row.openOnYouTube")}
-                className="inline-flex items-center justify-center w-9 h-9 rounded-lg text-muted hover:text-fg border border-border"
+                label={t("channels.row.openOnYouTube")}
+                size="md"
+                variant="outline"
              >
-                <ExternalLink className="w-4 h-4" />
-              </a>
+                <ExternalLink />
+              </IconLink>
              {ch?.subscribed && (
-                <Button
+                <IconButton
+                  label={t("channel.showInFeed")}
+                  size="md"
                  variant="outline"
-                  size="icon"
                  onClick={onShowInFeed}
-                  title={t("channel.showInFeed")}
-                  aria-label={t("channel.showInFeed")}
-                  icon={<SlidersHorizontal className="w-4 h-4" />}
-                />
+                >
+                  <SlidersHorizontal className="w-4 h-4" />
+                </IconButton>
              )}
              {ch?.subscribed && !me.is_demo && (
                <div className="inline-flex items-center gap-1.5 h-9 px-2.5 rounded-lg border border-border">
@@ -481,39 +491,32 @@ export default function ChannelPage({
                </Button>
              )}
              {!me.is_demo && (
-                <FocusSafeButton
+                <IconButton
                  // Busy blocks the click, not the focus (FocusSafeButton). Nor does a busy toggle
                  // light up on hover, as if a click would do something.
+                  size="md"
+                  variant={ch?.blocked ? "danger-soft" : "outline-danger"}
                  onClick={() => block.mutate()}
-                  busy={block.isPending}
-                  title={ch?.blocked ? t("channel.unblock") : t("channel.block")}
-                  aria-label={ch?.blocked ? t("channel.unblock") : t("channel.block")}
-                  className={`inline-flex items-center justify-center w-9 h-9 rounded-lg border aria-disabled:opacity-50 transition ${
-                    ch?.blocked
-                      ? "border-danger text-danger"
-                      : "border-border text-muted not-aria-disabled:hover:text-danger not-aria-disabled:hover:border-danger"
-                  }`}
+                  loading={block.isPending}
+                  label={ch?.blocked ? t("channel.unblock") : t("channel.block")}
                >
-                  <Ban className="w-4 h-4" />
-                </FocusSafeButton>
+                  <Ban />
+                </IconButton>
              )}
              {/* Hide-from-feed toggle — subscription-scoped, so offered only on a followed channel
                  (mirrors the manager's Eye/EyeOff). Keeps the subscription; only drops its videos
                  from the feed. EyeOff = currently hidden (click to unhide). */}
              {ch?.subscribed && !me.is_demo && (
-                <FocusSafeButton
+                <IconButton
+                  size="md"
+                  variant={ch.hidden ? "outline-accent" : "outline"}
                  onClick={() => toggleHidden.mutate()}
-                  busy={toggleHidden.isPending}
+                  loading={toggleHidden.isPending}
+                  label={ch.hidden ? t("channel.unhide") : t("channel.hide")}
                  title={ch.hidden ? t("channel.hiddenHint") : t("channel.hideHint")}
-                  aria-label={ch.hidden ? t("channel.unhide") : t("channel.hide")}
-                  className={`inline-flex items-center justify-center w-9 h-9 rounded-lg border aria-disabled:opacity-50 transition ${
-                    ch.hidden
-                      ? "border-accent text-accent"
-                      : "border-border text-muted not-aria-disabled:hover:text-fg not-aria-disabled:hover:border-fg/40"
-                  }`}
                >
-                  {ch.hidden ? <EyeOff className="w-4 h-4" /> : <Eye className="w-4 h-4" />}
-                </FocusSafeButton>
+                  {ch.hidden ? <EyeOff /> : <Eye />}
+                </IconButton>
              )}
              {!me.is_demo &&
                !ch?.blocked &&
@@ -561,48 +564,45 @@ export default function ChannelPage({
      {/* Tab content — the feed's toolbar portals up into the fixed chrome via this slot override;
          only the grid (and About) render here, in the scroller. */}
      <PageToolbarSlot.Provider value={chromeSlot}>
-        {tab === "videos" ? (
-          <>
-            <Feed
-              filters={filters}
-              setFilters={setFilters}
-              view={view}
-              setView={setView}
-              canRead={me.can_read}
-              isDemo={me.is_demo}
-              ytSearch={null}
-              onYtSearch={() => {}}
-              onExitYtSearch={() => {}}
-              channelScoped
-            />
-            {!ch?.subscribed && nextToken && (
-              <div className="flex justify-center pb-6">
-                <button
-                  // Busy blocks the click, not the focus (see Block above).
-                  onClick={() => !exploring && runExplore(nextToken)}
-                  aria-disabled={exploring || undefined}
-                  aria-busy={exploring || undefined}
-                  className="inline-flex items-center gap-2 px-4 py-2 rounded-lg text-sm border border-border not-aria-disabled:hover:bg-surface aria-disabled:opacity-50"
-                >
-                  {exploring ? (
-                    <Loader2 className="w-4 h-4 animate-spin" />
-                  ) : (
-                    <RefreshCw className="w-4 h-4" />
-                  )}
-                  {t("channel.loadMore")}
-                </button>
-              </div>
-            )}
-          </>
-        ) : (
-          <div className="px-4 sm:px-6 py-4 max-w-3xl">
-            {ch ? (
-              <ChannelAboutContent ch={ch} />
-            ) : (
-              <p className="text-sm text-muted">{t("channel.noDescription")}</p>
-            )}
-          </div>
-        )}
+        <div {...panel.panelProps(tab)}>
+          {tab === "videos" ? (
+            <>
+              <Feed
+                filters={filters}
+                setFilters={setFilters}
+                view={view}
+                setView={setView}
+                canRead={me.can_read}
+                isDemo={me.is_demo}
+                ytSearch={null}
+                onYtSearch={() => {}}
+                onExitYtSearch={() => {}}
+                channelScoped
+              />
+              {!ch?.subscribed && nextToken && (
+                <div className="flex justify-center pb-6">
+                  <Button
+                    // Busy blocks the click, not the focus (see Block above).
+                    variant="outline"
+                    icon={<RefreshCw />}
+                    loading={exploring}
+                    onClick={() => runExplore(nextToken)}
+                  >
+                    {t("channel.loadMore")}
+                  </Button>
+                </div>
+              )}
+            </>
+          ) : (
+            <div className="px-4 sm:px-6 py-4 max-w-3xl">
+              {ch ? (
+                <ChannelAboutContent ch={ch} />
+              ) : (
+                <p className="text-sm text-muted">{t("channel.noDescription")}</p>
+              )}
+            </div>
+          )}
+        </div>
      </PageToolbarSlot.Provider>
    </>
  );
@@ -40,6 +40,8 @@ export default function ChannelPicker({
      selected={filters.channelIds}
      onChange={(channelIds) => setFilters({ ...filters, channelIds })}
      loading={channelsQuery.isLoading}
+      error={channelsQuery.isError && !channelsQuery.data ? t("common.loadError") : undefined}
+      onRetry={() => void channelsQuery.refetch()}
      emptyText={t("sidebar.noChannelMatch")}
      selectedLabels={selectedLabels}
    />
@@ -14,6 +14,8 @@ import { type MyStatus } from "../lib/api";
 import { formatEta, formatNumber } from "../lib/format";
 import { PopoverSurface } from "./ui/AnchoredPopover";
 import { useAnchoredPopover } from "./ui/anchoredPopoverHooks";
+import { Button } from "./ui/Button";
+import { SURFACE } from "./ui/surfaces";

 // The channel-manager catalog stats, collapsed from a crowded inline row into a compact "Stats" chip
 // that reveals the numbers on hover (reuses the AnchoredPopover hover mode). One row per stat, each
@@ -77,19 +79,19 @@ export default function ChannelStatsPopover({ status }: { status: MyStatus }) {

  return (
    <>
-      <button
-        type="button"
+      <Button
+        variant="glass"
+        size="sm"
+        icon={<BarChart3 aria-hidden="true" />}
        ref={pop.refs.setReference}
        {...pop.getReferenceProps()}
-        className="glass-card glass-hover inline-flex items-center gap-1.5 rounded-lg px-2.5 py-1.5 text-sm text-muted transition"
      >
-        <BarChart3 className="h-4 w-4" aria-hidden="true" />
        {t("channels.stats.label")}
-      </button>
+      </Button>
      <PopoverSurface
        popover={pop}
        ariaLabel={t("channels.stats.label")}
-        className="glass-menu w-60 rounded-xl p-2 text-xs animate-[popIn_0.16s_ease]"
+        className={`${SURFACE.popover} w-60 p-2 text-xs animate-[popIn_0.16s_ease]`}
      >
        {rows.map((r) => (
          <div
@@ -1,5 +1,6 @@
-import { useEffect, useRef, useState } from "react";
-import { Check, Plus, Sparkles, X } from "lucide-react";
+import { useRef, useState } from "react";
+import { Plus, Sparkles } from "lucide-react";
+import { MenuCheck } from "./ui/MenuCheck";
 import { useTranslation } from "react-i18next";
 import { type Tag } from "../lib/api";
 import { PopoverSurface, PopoverItem } from "./ui/AnchoredPopover";
@@ -7,7 +8,11 @@ import { useAnchoredPopover } from "./ui/anchoredPopoverHooks";
 import { useScrollFade } from "../lib/useScrollFade";
 import { fitChipsWithPill } from "../lib/chipOverflow";
 import { chipLaneClass, useChipOverflowFit } from "../lib/useChipOverflowFit";
-import { FocusSafeButton } from "./ui/FocusSafeButton";
+import { IconButton } from "./ui/IconButton";
+import { Chip, DismissibleChip } from "./ui/Chip";
+import { chipClass } from "./ui/chipStyles";
+import { Input } from "./ui/Input";
+import { SURFACE } from "./ui/surfaces";

 // The channel tag surface, shared by the channel manager (table + cards) and the channel detail
 // page. Built on the R8 popover platform. Two design goals it fixes over the old inline TagsCell:
@@ -25,20 +30,15 @@ interface TagChipProps {
  title?: string;
 }

+// `block truncate` on the name, not the chip: the chip is inline-flex, where text-overflow cannot bite.
 function TagChip({ tag, onClick, title }: TagChipProps) {
-  const cls =
-    "chip-solid shrink-0 text-2xs font-medium px-1.5 py-0.5 rounded-full max-w-36 truncate";
+  const name = <span className="block max-w-32 truncate">{tag.name}</span>;
  return onClick ? (
-    <button
-      type="button"
-      onClick={onClick}
-      title={title}
-      className={`${cls} hover:opacity-80 transition`}
-    >
-      {tag.name}
-    </button>
+    <Chip variant="tag" size="xs" onClick={onClick} title={title}>
+      {name}
+    </Chip>
  ) : (
-    <span className={cls}>{tag.name}</span>
+    <span className={chipClass("tag", "xs")}>{name}</span>
  );
 }

@@ -63,33 +63,22 @@ function SuggestedChip({
  const { t } = useTranslation();
  const pct = Math.round(suggestion.confidence * 100);
  return (
-    <span className="shrink-0 inline-flex items-center rounded-full border border-dashed border-accent/50 text-accent/90 text-2xs font-medium pl-1 pr-0.5 py-0.5 max-w-36">
-      <button
-        type="button"
-        onClick={onAccept}
-        title={t("channels.tags.suggestedHint", { pct })}
-        aria-label={t("channels.tags.acceptSuggestion", { name: suggestion.tag.name })}
-        className="inline-flex items-center gap-1 min-w-0 hover:text-accent transition"
-      >
-        <Sparkles className="w-2.5 h-2.5 shrink-0" />
-        <span className="truncate">{suggestion.tag.name}</span>
-      </button>
-      <button
-        type="button"
-        onClick={onDismiss}
-        title={t("channels.tags.dismissSuggestion")}
-        aria-label={t("channels.tags.dismissSuggestion")}
-        className="shrink-0 ml-0.5 rounded-full text-accent/60 hover:text-danger transition"
-      >
-        <X className="w-2.5 h-2.5" />
-      </button>
-    </span>
+    <DismissibleChip
+      variant="suggest"
+      size="xs"
+      className="max-w-36 font-medium"
+      icon={<Sparkles />}
+      onClick={onAccept}
+      bodyTitle={t("channels.tags.suggestedHint", { pct })}
+      bodyLabel={t("channels.tags.acceptSuggestion", { name: suggestion.tag.name })}
+      onDismiss={onDismiss}
+      dismissLabel={t("channels.tags.dismissSuggestion")}
+    >
+      {suggestion.tag.name}
+    </DismissibleChip>
  );
 }

-const GHOST_PILL =
-  "shrink-0 text-3xs px-1.5 py-0.5 rounded-full border border-dashed border-accent/50 text-accent/90";
-
 /** A single-line lane of suggested ghost chips that collapses its overflow into a "+N" pill (hover
 *  reveals the rest, still accept/dismiss-able), reusing the SAME fit machinery as the attached-chip
 *  lane. Rendered in the untagged-channel case only, so it owns the full tags-cell width — this is what
@@ -117,18 +106,28 @@ function SuggestedChipsLane({
    decide: (g) =>
      fitChipsWithPill({ chipRights: g.chipRights, pillW: g.pillW, avail: g.avail, gap: g.gap }),
  });
-  const hidden = suggestions.length - visible;
+  // Clamped, and not defensively: `useChipOverflowFit` keeps `visible` in state and re-decides in a
+  // layout effect, so the render in which the chip set SHRINKS still holds the previous measurement
+  // and a raw subtraction goes negative. An unclamped `hidden` slips past the `=== 0` reset below —
+  // the flag survives exactly the window it exists to close, and the popover springs back on the
+  // next re-fit.
+  const hidden = Math.max(0, suggestions.length - visible);

-  const [overflowOpen, setOverflowOpen] = useState(false);
+  // Open only while there is a "+N" trigger to anchor it — derived, not closed by an effect, so the
+  // frame in which the last collapsed chip fits again cannot also hold a menu pointing at a
+  // reference that has gone. Same shape as TagFilterChips and the second row below, INCLUDING the
+  // render-phase reset: deriving hides the card but never clears the flag (a hover card whose pill
+  // unmounts under the cursor gets no mouseleave), so without this it springs back the next time
+  // the lane overflows. Convergent — the write falsifies its own condition.
+  const [overflowOpenRaw, setOverflowOpen] = useState(false);
+  if (overflowOpenRaw && hidden === 0) setOverflowOpen(false);
+  const overflowOpen = overflowOpenRaw && hidden > 0;
  const overflowPop = useAnchoredPopover({
    open: overflowOpen,
    onOpenChange: setOverflowOpen,
    mode: "hover",
    placement: "bottom",
  });
-  useEffect(() => {
-    if (hidden === 0 && overflowOpen) setOverflowOpen(false);
-  }, [hidden, overflowOpen]);

  return (
    <div className={`${chipLaneClass} flex items-center gap-1 min-w-0 flex-1`}>
@@ -148,7 +147,7 @@ function SuggestedChipsLane({
            <SuggestedChip suggestion={s} onAccept={() => {}} onDismiss={() => {}} />
          </span>
        ))}
-        <span ref={pillRef} className={GHOST_PILL}>
+        <span ref={pillRef} className={chipClass("suggest", "xs")}>
          +{suggestions.length}
        </span>
      </div>
@@ -163,22 +162,22 @@ function SuggestedChipsLane({
          />
        ))}
        {hidden > 0 && (
-          <button
+          <Chip
+            variant="suggest"
+            size="xs"
            ref={overflowPop.refs.setReference}
-            type="button"
            aria-label={t("channels.tags.moreCount", { count: hidden })}
-            className={`${GHOST_PILL} hover:text-accent transition`}
            {...overflowPop.getReferenceProps()}
          >
            +{hidden}
-          </button>
+          </Chip>
        )}
      </div>

      {/* Hover: the overflowed suggestions, each still one-tap accept / × dismiss. */}
      <PopoverSurface
        popover={overflowPop}
-        className="glass-menu max-w-[18rem] rounded-xl p-1.5 flex flex-wrap items-center gap-1 animate-[popIn_0.16s_ease]"
+        className={`${SURFACE.popover} max-w-[18rem] p-1.5 flex flex-wrap items-center gap-1 animate-[popIn_0.16s_ease]`}
      >
        {suggestions.slice(visible).map((s) => (
          <SuggestedChip
@@ -230,17 +229,11 @@ function TagEditorMenu({
              checked={on}
              onSelect={() => onToggle(tg.id)}
              label={tg.name}
-              className={`w-full flex items-center gap-2 text-left text-xs px-2 py-1.5 rounded-md outline-hidden transition ${
+              className={`w-full flex items-center gap-2 text-left text-xs px-2 py-1.5 rounded-lg outline-hidden transition ${
                on ? "text-fg" : "text-muted"
              }`}
            >
-              <span
-                className={`w-3.5 h-3.5 rounded border flex items-center justify-center shrink-0 ${
-                  on ? "bg-accent border-accent text-accent-fg" : "border-border"
-                }`}
-              >
-                {on && <Check className="w-2.5 h-2.5" />}
-              </span>
+              <MenuCheck kind="many" on={on} />
              <span className="truncate">{tg.name}</span>
            </PopoverItem>
          );
@@ -250,7 +243,9 @@ function TagEditorMenu({
        )}
      </div>
      <div className="mt-1 pt-1.5 border-t border-border flex items-center gap-1">
-        <input
+        <Input
+          className="flex-1"
+          size="sm"
          value={draft}
          onChange={(e) => setDraft(e.target.value)}
          onKeyDown={(e) => {
@@ -266,18 +261,15 @@ function TagEditorMenu({
          }}
          maxLength={64}
          placeholder={t("channels.tags.createPlaceholder")}
-          className="flex-1 min-w-0 bg-transparent text-xs px-2 py-1 rounded-md border border-border focus:outline-hidden focus:ring-2 focus:ring-accent/40"
        />
-        <FocusSafeButton
-          type="button"
+        <IconButton
+          variant="outline"
          onClick={submit}
          disabled={!draft.trim()}
-          title={t("channels.tags.create")}
-          aria-label={t("channels.tags.create")}
-          className="shrink-0 w-6 h-6 inline-flex items-center justify-center rounded-md border border-border text-muted hover:text-accent hover:border-accent disabled:opacity-40 transition"
+          label={t("channels.tags.create")}
        >
-          <Plus className="w-3.5 h-3.5" />
-        </FocusSafeButton>
+          <Plus />
+        </IconButton>
      </div>
    </div>
  );
@@ -340,7 +332,12 @@ export function ChannelTagsControl({
      fitChipsWithPill({ chipRights: g.chipRights, pillW: g.pillW, avail: g.avail, gap: g.gap }),
  });

-  const hidden = attached.length - visible;
+  // Clamped, and not defensively: `useChipOverflowFit` keeps `visible` in state and re-decides in a
+  // layout effect, so the render in which the chip set SHRINKS still holds the previous measurement
+  // and a raw subtraction goes negative. An unclamped `hidden` slips past the `=== 0` reset below —
+  // the flag survives exactly the window it exists to close, and the popover springs back on the
+  // next re-fit.
+  const hidden = Math.max(0, attached.length - visible);

  const [editorOpen, setEditorOpen] = useState(false);
  const editPop = useAnchoredPopover({
@@ -353,21 +350,21 @@ export function ChannelTagsControl({
    hostsInput: true,
  });

-  const [overflowOpen, setOverflowOpen] = useState(false);
+  // Derived for the same reason as the suggestion row above: if tags change so nothing is collapsed
+  // anymore, the "+N" trigger unmounts, and the popover must already be shut in that same render —
+  // and the flag reset with it, or the card returns unasked on the next overflow.
+  const [overflowOpenRaw, setOverflowOpen] = useState(false);
+  if (overflowOpenRaw && hidden === 0) setOverflowOpen(false);
+  const overflowOpen = overflowOpenRaw && hidden > 0;
  const overflowPop = useAnchoredPopover({
    open: overflowOpen,
    onOpenChange: setOverflowOpen,
    mode: "hover",
    placement: "bottom",
  });
-  // If tags change so nothing is collapsed anymore, the "+N" trigger unmounts — force the reveal-all
-  // popover's state closed so it can't linger open against a gone reference.
-  useEffect(() => {
-    if (hidden === 0 && overflowOpen) setOverflowOpen(false);
-  }, [hidden, overflowOpen]);

-  const pillClass =
-    "shrink-0 text-3xs px-1.5 py-0.5 rounded-full bg-card text-muted border border-border";
+  // The "+N" is a filter-look chip (neutral): the tags themselves are the accent.
+  const pillClass = chipClass("filter", "xs");

  return (
    // When `bounded`, a FIXED width keeps the cell's footprint constant under `table-layout:auto`: a
@@ -381,21 +378,18 @@ export function ChannelTagsControl({
      {/* The add trigger LEADS the row — a stable left anchor that never moves as chips are added
          (they grow to its right), so its editor popover can't drift. Compact icon in the width-
          bounded manager cell; a labelled "＋ Tag" pill where there's free width (the detail header). */}
-      <button
+      <Chip
+        variant="ghost"
+        size="xs"
        ref={editPop.refs.setReference}
-        type="button"
        title={t("channels.row.editTags")}
        aria-label={t("channels.row.editTags")}
-        className={
-          bounded
-            ? "shrink-0 w-5 h-5 inline-flex items-center justify-center rounded-full border border-dashed border-border text-muted hover:text-accent hover:border-accent transition"
-            : "shrink-0 inline-flex items-center gap-1 h-6 pl-1.5 pr-2 rounded-full border border-dashed border-border text-2xs font-medium text-muted hover:text-accent hover:border-accent transition"
-        }
+        icon={<Plus className="size-3" />}
+        className={`font-medium ${bounded ? "w-6 justify-center px-0" : ""}`}
        {...editPop.getReferenceProps()}
      >
-        <Plus className="w-3 h-3 shrink-0" />
-        {!bounded && <span className="whitespace-nowrap">{t("channels.tags.add")}</span>}
-      </button>
+        {!bounded && t("channels.tags.add")}
+      </Chip>

      {/* Untagged + has suggestions → the ghost-chip lane (its own overflow "+N"); otherwise the
          attached-chip lane. The two are mutually exclusive: suggestions are computed for untagged
@@ -444,15 +438,14 @@ export function ChannelTagsControl({
              />
            ))}
            {hidden > 0 && (
-              <button
+              <Chip
+                size="xs"
                ref={overflowPop.refs.setReference}
-                type="button"
                aria-label={t("channels.tags.moreCount", { count: hidden })}
-                className={`${pillClass} hover:text-fg transition`}
                {...overflowPop.getReferenceProps()}
              >
                +{hidden}
-              </button>
+              </Chip>
            )}
          </div>
        </>
@@ -461,7 +454,7 @@ export function ChannelTagsControl({
      {/* Hover: reveal every attached tag when some are collapsed into "+N". */}
      <PopoverSurface
        popover={overflowPop}
-        className="glass-menu max-w-[18rem] rounded-xl p-1.5 flex flex-wrap items-center gap-1 animate-[popIn_0.16s_ease]"
+        className={`${SURFACE.popover} max-w-[18rem] p-1.5 flex flex-wrap items-center gap-1 animate-[popIn_0.16s_ease]`}
      >
        {attached.map((tg) => (
          <TagChip
@@ -476,7 +469,7 @@ export function ChannelTagsControl({
      {/* Click: the shared editor (toggle existing + create inline). */}
      <PopoverSurface
        popover={editPop}
-        className="glass-menu w-56 rounded-xl p-1.5 animate-[popIn_0.16s_ease]"
+        className={`${SURFACE.menu} w-56 animate-[popIn_0.16s_ease]`}
      >
        <TagEditorMenu
          userTags={userTags}
--- a/Show More
+++ b/Show More
@@ -1 +1 @@
 .93.0
 .96.0