release: 0.98.0 (feature/e31-design-review-2)

It printed the tag's whole-library count as the current filter's while the
facets loaded, and for good when they failed: live, "Music 238" beside a
search that matched 3 of its channels. Ordering still falls back to it.

CLAUDE.md

@@ -46,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.
 
@@ -58,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`, `bodylimit`, `progress`,
+`sysconfig`, `state`, `audit`, `notifications`, `userscope`, `realtime`, `ratelimit`, `bodylimit`, `progress`, `collation`,
 `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
@@ -79,7 +81,7 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory
 | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
 | 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                          |
+| 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)                                             |
@@ -90,10 +92,13 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory
 | 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 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                               |

VERSION

@@ -1 +1 @@
-0.95.0
+0.98.0

backend/.basedpyright/baseline.json

@@ -639,14 +639,6 @@
                     "lineCount": 1
                 }
             },
-            {
-                "code": "reportArgumentType",
-                "range": {
-                    "startColumn": 27,
-                    "endColumn": 33,
-                    "lineCount": 1
-                }
-            },
             {
                 "code": "reportArgumentType",
                 "range": {

backend/alembic/versions/0091_plex_tagline_hu.py

@@ -0,0 +1,27 @@
+"""add tagline_hu to plex_items + plex_shows — the HU overlay's tagline (E30 S1)
+
+Revision ID: 0091_plex_tagline_hu
+Revises: 0090_debug_session_draft
+Create Date: 2026-09-29
+
+The Hungarian overlay section lists a tagline beside the title and summary; the info page showed the
+English one to a Hungarian reader. NULL until the next overlay sync fills it (serving falls back to EN).
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0091_plex_tagline_hu"
+down_revision: str | None = "0090_debug_session_draft"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.add_column("plex_items", sa.Column("tagline_hu", sa.Text(), nullable=True))
+    op.add_column("plex_shows", sa.Column("tagline_hu", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("plex_shows", "tagline_hu")
+    op.drop_column("plex_items", "tagline_hu")

backend/alembic/versions/0092_plex_person_biography_hu.py

@@ -0,0 +1,31 @@
+"""add biography_hu to plex_people — TMDB's Hungarian biography (E30 S4)
+
+Revision ID: 0092_plex_person_biography_hu
+Revises: 0091_plex_tagline_hu
+Create Date: 2026-09-29
+
+The person page showed a Hungarian reader the English biography although TMDB has a Hungarian one for
+most people. The person fetch now appends `translations` and keeps the Hungarian biography beside the
+English one. Already-enriched people are un-stamped, so their next page open refetches them once (the
+same lazy path as a first open) and fills it; until then the English biography stands in.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0092_plex_person_biography_hu"
+down_revision: str | None = "0091_plex_tagline_hu"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.add_column("plex_people", sa.Column("biography_hu", sa.Text(), nullable=True))
+    op.execute(
+        "UPDATE plex_people SET tmdb_enriched_at = NULL "
+        "WHERE tmdb_person_id IS NOT NULL AND tmdb_enriched_at IS NOT NULL"
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("plex_people", "biography_hu")

backend/alembic/versions/0093_plex_person_known_for_votes.py

@@ -0,0 +1,29 @@
+"""re-fetch linked people — "Known for" ranked by votes, without guest visits (E30 S6)
+
+Revision ID: 0093_plex_person_known_for_votes
+Revises: 0092_plex_person_biography_hu
+Create Date: 2026-09-30
+
+A person's "Known for" pool was their credits ranked by TMDB popularity, so talk-show visits as
+themselves crowded out the films (Tom Cruise: 14 of 15 were talk shows, none in the library). The pool is
+now ranked by vote count, without guest visits, with directed works, and deeper. Already-enriched people
+are un-stamped so the people_enrich job fetches them again; their biography stays on the row meanwhile.
+"""
+
+from alembic import op
+
+revision: str = "0093_plex_person_known_for_votes"
+down_revision: str | None = "0092_plex_person_biography_hu"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.execute(
+        "UPDATE plex_people SET tmdb_enriched_at = NULL "
+        "WHERE tmdb_person_id IS NOT NULL AND tmdb_enriched_at IS NOT NULL"
+    )
+
+
+def downgrade() -> None:
+    pass  # the watermark only says "fetched"; a refetch under the old ranking is not worth undoing to

backend/alembic/versions/0094_plex_genres_hu_everywhere.py

@@ -0,0 +1,45 @@
+"""Hungarian genres on every Plex row, not only on overlaid ones (E30 review)
+
+Revision ID: 0094_plex_genres_hu_everywhere
+Revises: 0093_plex_person_known_for_votes
+Create Date: 2026-09-30
+
+The HU genre facets and filter read `genres_hu`, which only the overlay pass wrote — so a library with
+no HU twin, or a guid-less row, offered English genres a Hungarian filter could never match. The sync
+now writes `genres_hu` for every row (plex/sync.py `_apply_facet_fields`); this fills the rows it has
+not reached yet, from their own English list through the same map.
+"""
+
+import json
+
+import sqlalchemy as sa
+from alembic import op
+
+from app.plex.genres import hu_genres
+
+revision: str = "0094_plex_genres_hu_everywhere"
+down_revision: str | None = "0093_plex_person_known_for_votes"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    for table in ("plex_items", "plex_shows"):
+        rows = conn.execute(
+            sa.text(
+                f"SELECT id, genres FROM {table} "
+                "WHERE genres_hu IS NULL AND jsonb_typeof(genres) = 'array'"
+            )
+        ).fetchall()
+        updates = [
+            {"id": rid, "g": json.dumps(hu)} for rid, genres in rows if (hu := hu_genres(genres))
+        ]
+        if updates:
+            conn.execute(
+                sa.text(f"UPDATE {table} SET genres_hu = CAST(:g AS jsonb) WHERE id = :id"), updates
+            )
+
+
+def downgrade() -> None:
+    pass  # derived from `genres`; the sync writes the same values again

backend/alembic/versions/0095_videos_channel_cover_index.py

@@ -0,0 +1,83 @@
+"""videos: the per-channel index covers what the channel manager and the feed sidebar read (E31 S4d)
+
+The channel manager (`GET /api/channels`) sums each subscribed channel's videos: count, last upload, total
+duration. The feed sidebar (`/feed/summary`, `/feed/years`) counts the reader's videos per channel and per
+year under the default filters: available, not via explore, not a short, not live. Every one of them found
+its rows through `ix_videos_channel_pub_desc` (channel_id, published_at DESC NULLS LAST, id) and then read
+each video's heap page for the rest: ~270k rows at ~2.5 KB each, 681 MB on prod. That stays in cache only
+while nothing else needs the memory. Measured on prod (2026-10-02): `/api/channels` 51–61 ms warm, but
+2.25 s and 1.96 s on a first open in the browser and 6.4 s under EXPLAIN with 30k blocks read from disk;
+`/feed/summary` and `/feed/years` ~140 ms warm, ~800 ms cold.
+
+The same key with those columns INCLUDEd makes them Index Only Scans. On a prod-copy localdev, after a
+VACUUM, the manager's sums read 0 heap pages and the summary reads the 25 MB index instead of the heap.
+The visibility map is what lets them skip the heap; prod's autovacuum kept it complete (relallvisible ==
+relpages). The key columns are unchanged, so every reader of the old index (the per-channel feed, the FK
+cascade, the sync upsert, channel detail) rides this one. The old index is dropped.
+tests/test_channel_list_index_only.py holds the queries and this column list together.
+
+CONCURRENTLY (autocommit_block) builds it without blocking a live prod. IF (NOT) EXISTS keeps the drift
+test's downgrade → re-upgrade round trip idempotent. A re-run after a build that failed part-way rebuilds
+the INVALID leftover, and the old index is dropped only once the new one is valid: a re-run that kept the
+leftover and dropped the old one left `videos` with no usable channel_id index (E31 S5 review).
+"""
+
+from alembic import op
+from sqlalchemy import text
+
+revision: str = "0095_videos_channel_cover_index"
+down_revision: str | None = "0094_plex_genres_hu_everywhere"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def _valid(name: str) -> bool | None:
+    """The index's `indisvalid`, or None when there is no index of that name."""
+    row = (
+        op.get_bind()
+        .execute(
+            text(
+                "SELECT i.indisvalid FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid "
+                "WHERE c.relname = :name"
+            ),
+            {"name": name},
+        )
+        .first()
+    )
+    return None if row is None else bool(row[0])
+
+
+def _build(name: str, ddl: str) -> None:
+    """CREATE INDEX CONCURRENTLY `name` (`ddl` is what follows the name), re-runnable. A build that
+    failed part-way leaves an INVALID index under the name, and `IF NOT EXISTS` would keep it: the
+    planner never uses it, and nothing says so (E31 S5 review). Such a leftover is dropped and built
+    again."""
+    if _valid(name) is False:
+        op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {name}")
+    op.execute(f"CREATE INDEX CONCURRENTLY IF NOT EXISTS {name} {ddl}")
+
+
+def _swap(build: str, ddl: str, drop: str) -> None:
+    _build(build, ddl)
+    if not _valid(build):
+        raise RuntimeError(f"{build} did not build valid; {drop} is kept")
+    op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {drop}")
+
+
+def upgrade() -> None:
+    with op.get_context().autocommit_block():
+        _swap(
+            "ix_videos_channel_pub_cover",
+            "ON videos (channel_id, published_at DESC NULLS LAST, id) "
+            "INCLUDE (duration_seconds, unavailable_since, via_explore, is_short, live_status)",
+            "ix_videos_channel_pub_desc",
+        )
+
+
+def downgrade() -> None:
+    with op.get_context().autocommit_block():
+        _swap(
+            "ix_videos_channel_pub_desc",
+            "ON videos (channel_id, published_at DESC NULLS LAST, id ASC)",
+            "ix_videos_channel_pub_cover",
+        )

backend/alembic/versions/0096_videos_sort_indexes.py

@@ -0,0 +1,86 @@
+"""videos: an index per feed sort, so a sorted page stops after its rows (E31 S4e)
+
+The feed's views, duration and title sorts had no index. Every page (the first and each next cursor)
+read the whole videos heap, filtered it and kept a top-N: on prod ~350 ms a page for views/duration,
+550–780 ms for title (the ICU comparison on every row), 2.3 s for page 2 when the copies of one request
+queued. With an index in the exact ORDER BY (`feedquery.order_by`: the key, NULLS LAST, then id) the
+planner walks it and stops after the page. On a prod-copy localdev every plain sort fell from 180–310 ms
+to ~1 ms, deep pages (20) to 3–5 ms, and narrow filters (a tag, a channel, a year, nothing found) stayed
+at 0.3–25 ms.
+
+One index per direction: a backward scan of `DESC NULLS LAST` gives `ASC NULLS FIRST`, not the
+`ASC NULLS LAST` the asc sorts ask for. The title pair is per reader language (`app.collation.ICU`):
+an index only serves an ORDER BY in its own collation.
+
+Cost: ~130 MB (localdev: 10 + 10 + 8 + 8 + 4 × 23). Writes stay cheap: view_count and duration are
+written by the enrich, which rewrites indexed columns already (the revalidation job only touches
+last_checked_at), so no HOT update is lost. A search combined with one of these sorts can now walk the
+index too: a term matching ~2 % of the videos took 130–200 ms instead of 7 (still under the plain sort it
+replaces); rarer and broader terms stay fast. Fencing the index off under a search made broad terms
+(`m`, `the`) take 2 s, so it is left to the planner.
+
+The title indexes are the schema's first ones on an ICU collation: an ICU upgrade in the Postgres image
+reorders them, and `app.collation.heal_drift` rebuilds them at startup when it sees one.
+tests/test_feed_sort_indexes.py holds each sort and its index together.
+
+CONCURRENTLY (autocommit_block) builds them without blocking a live prod; IF (NOT) EXISTS keeps the drift
+test's downgrade → re-upgrade round trip idempotent.
+"""
+
+from alembic import op
+from sqlalchemy import text
+
+revision: str = "0096_videos_sort_indexes"
+down_revision: str | None = "0095_videos_channel_cover_index"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+# name → the indexed ORDER BY (feedquery.sort_keys + order_by: key NULLS LAST, then id).
+INDEXES = {
+    "ix_videos_views_desc": "view_count DESC NULLS LAST, id",
+    "ix_videos_views_asc": "view_count ASC NULLS LAST, id",
+    "ix_videos_duration_desc": "duration_seconds DESC NULLS LAST, id",
+    "ix_videos_duration_asc": "duration_seconds ASC NULLS LAST, id",
+    "ix_videos_title_en": '(lower(title) COLLATE "en-x-icu") ASC NULLS LAST, id',
+    "ix_videos_title_en_desc": '(lower(title) COLLATE "en-x-icu") DESC NULLS LAST, id',
+    "ix_videos_title_hu": '(lower(title) COLLATE "hu-x-icu") ASC NULLS LAST, id',
+    "ix_videos_title_hu_desc": '(lower(title) COLLATE "hu-x-icu") DESC NULLS LAST, id',
+}
+
+
+def _valid(name: str) -> bool | None:
+    """The index's `indisvalid`, or None when there is no index of that name."""
+    row = (
+        op.get_bind()
+        .execute(
+            text(
+                "SELECT i.indisvalid FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid "
+                "WHERE c.relname = :name"
+            ),
+            {"name": name},
+        )
+        .first()
+    )
+    return None if row is None else bool(row[0])
+
+
+def _build(name: str, ddl: str) -> None:
+    """CREATE INDEX CONCURRENTLY `name` (`ddl` is what follows the name), re-runnable. A build that
+    failed part-way leaves an INVALID index under the name, and `IF NOT EXISTS` would keep it: the
+    planner never uses it, and nothing says so (E31 S5 review). Such a leftover is dropped and built
+    again."""
+    if _valid(name) is False:
+        op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {name}")
+    op.execute(f"CREATE INDEX CONCURRENTLY IF NOT EXISTS {name} {ddl}")
+
+
+def upgrade() -> None:
+    with op.get_context().autocommit_block():
+        for name, columns in INDEXES.items():
+            _build(name, f"ON videos ({columns})")
+
+
+def downgrade() -> None:
+    with op.get_context().autocommit_block():
+        for name in INDEXES:
+            op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {name}")

backend/app/README.md

@@ -23,7 +23,8 @@ Three layers, by *who* runs the code — not by feature:
 3. **Flat `app/*.py` core modules — cross-cutting primitives.** `auth`, `sysconfig`, `quota`, `audit`,
    `notifications`, `userscope`, `realtime`, `ratelimit`, `progress`, `logs` (the one logging
    configuration), `logsink` (its `log_events` table), `diagnostics` (a user's consented log
-   level) and `debugsession` (a recording that tags its user's lines, E16), … are single-file primitives many layers import. They depend on nothing above them (a core
+   level), `debugsession` (a recording that tags its user's lines, E16) and `collation` (A→Z in the
+   reader's alphabet, E30), … are single-file primitives many layers import. They depend on nothing above them (a core
    module must never import a `routes/…` module).
 
 **Extraction trigger: the SECOND consumer.** Keep new logic inline in its first caller. The moment a

backend/app/collation.py

@@ -0,0 +1,83 @@
+"""Alphabetical order in the reader's language (E30 S3).
+
+Why not the database default: the Postgres image is Alpine, and musl's `en_US.utf8` collation is BYTE
+order — every accented initial sorted after "Z" ("Zorró < Életrajzi < Ötödik"), in every A→Z list the
+server orders. Postgres ships the ICU collations on the same image (dev, test, prod alike), so a text
+sort names one: Hungarian puts "Ö" after "O" and "Cs" after "Cu", English folds the accents in.
+
+`collated` wraps an ORDER BY expression — and because a keyset cursor compares with the SAME expression
+(`feedquery.sort_keys`), the cursor pages in the same order it sorted in. `sorted_words` orders a Python
+list the same way through the database, so a list built in Python matches one built in SQL exactly.
+
+The feed's title sorts ride indexes built in these collations (migration 0096), and an index keeps the
+order of the ICU that built it. `postgres:16-alpine` is a floating tag: an image update can bring a newer
+ICU, after which those indexes disagree with the comparisons a query makes (a keyset page skips or
+repeats a title). `heal_drift` rebuilds them at startup once Postgres reports the version moved."""
+
+from typing import Any
+
+from sqlalchemy import Engine, SQLColumnExpression, column, func, select, text, values
+from sqlalchemy.orm import Session
+from sqlalchemy.sql.elements import ColumnElement
+from sqlalchemy.types import String
+
+from app import logs
+from app.mailtext import normalize
+
+log = logs.get_logger(__name__)
+
+ICU: dict[str, str] = {"en": "en-x-icu", "hu": "hu-x-icu"}
+
+
+def collation(lang: str | None) -> str:
+    """The ICU collation for a UI language; anything unknown sorts as English."""
+    return ICU[normalize(lang)]
+
+
+def collated(expr: SQLColumnExpression[Any], lang: str | None) -> ColumnElement[Any]:
+    """`expr` compared in the reader's alphabet. Case-folded, so "apple" and "Apple" sit together."""
+    return func.lower(expr).collate(collation(lang))
+
+
+def sorted_words(db: Session, words: list[str], lang: str | None) -> list[str]:
+    """`words` in the reader's alphabetical order, by the same ICU collation as `collated`."""
+    if not words:
+        return []
+    w = values(column("w", String), name="words").data([(x,) for x in words])
+    return list(db.scalars(select(w.c.w).order_by(collated(w.c.w, lang), w.c.w)))
+
+
+def heal_drift(engine: Engine) -> list[str]:
+    """Rebuild every index on an ICU collation whose library version moved, then record the new version.
+    Returns the rebuilt indexes. CONCURRENTLY: the feed keeps reading while it runs."""
+    with engine.connect().execution_options(isolation_level="AUTOCOMMIT") as conn:
+        drifted = conn.execute(
+            text(
+                "SELECT oid, collname FROM pg_collation WHERE collname = ANY(:names) "
+                "AND collversion IS DISTINCT FROM pg_collation_actual_version(oid)"
+            ),
+            {"names": list(ICU.values())},
+        ).all()
+        if not drifted:
+            return []
+        indexes = list(
+            conn.execute(
+                text(
+                    "SELECT DISTINCT d.objid::regclass::text FROM pg_depend d "
+                    "JOIN pg_class c ON c.oid = d.objid AND c.relkind = 'i' "
+                    "WHERE d.classid = 'pg_class'::regclass "
+                    "AND d.refclassid = 'pg_collation'::regclass AND d.refobjid = ANY(:oids)"
+                ),
+                {"oids": [row.oid for row in drifted]},
+            ).scalars()
+        )
+        log.warning(
+            "ICU collation version changed (%s): rebuilding %d indexes",
+            ", ".join(row.collname for row in drifted),
+            len(indexes),
+        )
+        for name in indexes:
+            conn.execute(text(f"REINDEX INDEX CONCURRENTLY {name}"))
+        for row in drifted:
+            conn.execute(text(f'ALTER COLLATION "{row.collname}" REFRESH VERSION'))
+        return indexes

backend/app/config.py

@@ -366,6 +366,11 @@ class Settings(BaseSettings):
     tmdb_enrich_interval_min: int = 120
     # Titles fetched per TMDB enrichment run (TMDB is fast + generously rate-limited).
     tmdb_enrich_batch: int = 100
+    # How often the people job (E30 S6) fetches a batch of person bios from TMDB and portraits through Plex,
+    # in minutes, and how many of each per run: ~18k linked people at 300 per 10 min is about ten hours
+    # once, then only the newcomers.
+    people_enrich_interval_min: int = 10
+    people_enrich_batch: int = 300
 
     @property
     def allowed_email_set(self) -> set[str]:

backend/app/db.py

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

backend/app/discover/hero.py

@@ -48,6 +48,7 @@ def pick(
     shelf: list[dict] | None = None,
     exclude: set[str] | None = None,
     start: int = 0,
+    lang: str,
 ) -> dict | None:
     """`{"tier": ..., "card": ...}`, or None when nothing at all fits.
 
@@ -70,8 +71,8 @@ def pick(
     skip = exclude or set()
 
     def _resume() -> dict | None:
-        for card in rails.continue_watching(db, user) if resume is None else resume:
-            playable = rails.playable(db, user.id, card)
+        for card in rails.continue_watching(db, user, lang=lang) if resume is None else resume:
+            playable = rails.playable(db, user.id, card, lang=lang)
             # Excluded on the card the USER saw (the show), not only on what it resolves to, so a
             # rerolled-past show does not come straight back as its own next episode.
             if cards.key(card) in skip or (playable is not None and cards.key(playable) in skip):
@@ -82,7 +83,7 @@ def pick(
 
     def _comfort() -> dict | None:
         if shelf is None:
-            own = pins.shelf(db, user, include_plex=rails.plex_available(db))
+            own = pins.shelf(db, user, include_plex=rails.plex_available(db), lang=lang)
         else:
             own = shelf
         for card in pins.playables(own):
@@ -93,7 +94,7 @@ def pick(
     def _surprise() -> dict | None:
         # A wider draw than the one card we need: the shuffle is seeded, so without the headroom an
         # excluded pick would leave the tier empty rather than move past it.
-        for card in rails.surprise(db, user, budget, seed, limit=SURPRISE_DRAW):
+        for card in rails.surprise(db, user, budget, seed, limit=SURPRISE_DRAW, lang=lang):
             if cards.key(card) not in skip:
                 return card
         return None

backend/app/discover/pins.py

@@ -170,7 +170,7 @@ class _Batch:
         return b
 
 
-def _shelf_card(db: Session, user: User, pin: ComfortPin, batch: _Batch) -> dict | None:
+def _shelf_card(db: Session, user: User, pin: ComfortPin, batch: _Batch, lang: str) -> dict | None:
     """One pin as a unified card with its resolved `next`. None when the pinned row has gone (the FK
     cascade removes the pin itself, so this is only the window between a delete and a refetch)."""
     card: dict | None = None
@@ -196,7 +196,7 @@ def _shelf_card(db: Session, user: User, pin: ComfortPin, batch: _Batch) -> dict
         if it is None:
             return None
         st = rollup.item_state_map(db, user.id, [it.id]).get(it.id)
-        card = cards.from_plex(leaf_card(it, st))
+        card = cards.from_plex(leaf_card(it, st, lang=lang))
         nxt = dict(card)  # a movie or a single episode plays itself
 
     elif pin.plex_show_id is not None:
@@ -204,8 +204,8 @@ def _shelf_card(db: Session, user: User, pin: ComfortPin, batch: _Batch) -> dict
         if sh is None:
             return None
         status = rollup.state_map(db, user.id, [sh.id]).get(sh.id, "new")
-        card = cards.from_plex(show_card(sh, status))
-        ep = queries.next_episode(db, user.id, sh.id)
+        card = cards.from_plex(show_card(sh, status, lang=lang))
+        ep = queries.next_episode(db, user.id, sh.id, lang=lang)
         nxt = cards.from_plex(ep) if ep else None
 
     elif pin.playlist_id is not None:
@@ -229,7 +229,7 @@ def _shelf_card(db: Session, user: User, pin: ComfortPin, batch: _Batch) -> dict
 _PLEX_COLUMNS = ("plex_item_id", "plex_show_id")
 
 
-def shelf(db: Session, user: User, *, include_plex: bool = True) -> list[dict]:
+def shelf(db: Session, user: User, *, include_plex: bool = True, lang: str) -> list[dict]:
     """The whole shelf, in the user's own order.
 
     `include_plex=False` is the Home surface with the deployment's Plex toggle off (the owner's call,
@@ -243,7 +243,7 @@ def shelf(db: Session, user: User, *, include_plex: bool = True) -> list[dict]:
         pins = [p for p in pins if all(getattr(p, c) is None for c in _PLEX_COLUMNS)]
     batch = _Batch.load(db, user, pins)
     for pin in pins:
-        card = _shelf_card(db, user, pin, batch)
+        card = _shelf_card(db, user, pin, batch, lang)
         if card is not None:
             out.append(card)
     return out

backend/app/discover/queries.py

@@ -40,7 +40,7 @@ from app.models import (
     VideoState,
 )
 from app.plex import rollup
-from app.plex.cards import leaf_card, movie_card, show_card
+from app.plex.cards import display_title, leaf_card, movie_card, show_card
 from app.plex.query import apply_show_state_filter, content_libs
 
 # How many rows a single rail may carry — Home's rails and the Plex module's Discover rails alike
@@ -221,7 +221,9 @@ def _unseen_movie_conds(uid: int):
     return ~seen
 
 
-def plex_in_progress(db: Session, uid: int, limit: int = RAIL_LIMIT) -> list[tuple[object, dict]]:
+def plex_in_progress(
+    db: Session, uid: int, limit: int = RAIL_LIMIT, *, lang: str
+) -> list[tuple[object, dict]]:
     """In-progress movies + partially-watched shows as (progressed_at, card).
 
     Mirrors `routes/plex/discover.py::_continue_watching` — same `PlexState` predicate for movies (a
@@ -249,7 +251,7 @@ def plex_in_progress(db: Session, uid: int, limit: int = RAIL_LIMIT) -> list[tup
             .limit(limit)
         )
         for it, st in db.execute(mq).all():
-            out.append((st.progress_updated_at, movie_card(it, st)))
+            out.append((st.progress_updated_at, movie_card(it, st, lang=lang)))
 
     if show_libs:
         prog = rollup.agg_subquery(db, uid, include_resumed=True).subquery()
@@ -263,12 +265,14 @@ def plex_in_progress(db: Session, uid: int, limit: int = RAIL_LIMIT) -> list[tup
         for sh, resumed_at in db.execute(
             sq.order_by(prog.c.resumed_at.desc().nullslast()).limit(limit)
         ).all():
-            out.append((resumed_at, show_card(sh, "in_progress")))
+            out.append((resumed_at, show_card(sh, "in_progress", lang=lang)))
 
     return out
 
 
-def plex_surprise(db: Session, uid: int, budget: str, seed: int, limit: int) -> list[dict]:
+def plex_surprise(
+    db: Session, uid: int, budget: str, seed: int, limit: int, *, lang: str
+) -> list[dict]:
     """Unseen playable movies inside the budget, in seeded-shuffle order.
 
     Movies only. A show is not a thing you can start playing, and resolving every candidate show to
@@ -300,14 +304,14 @@ def plex_surprise(db: Session, uid: int, budget: str, seed: int, limit: int) ->
         q = q.where(PlexItem.duration_s <= hi)
     items = db.execute(q).scalars().all()
     states = rollup.item_state_map(db, uid, [it.id for it in items])
-    return [movie_card(it, states.get(it.id)) for it in items]
+    return [movie_card(it, states.get(it.id), lang=lang) for it in items]
 
 
 # Watch states that take an episode out of the running for "what would play next".
 _DONE = ("watched", "hidden")
 
 
-def next_episode(db: Session, uid: int, show_id: int) -> dict | None:
+def next_episode(db: Session, uid: int, show_id: int, *, lang: str) -> dict | None:
     """What "put that show on" means: the episode in progress, else the first unwatched one, else the
     first — over the same `(season, episode)` broadcast ordering `detail.py::_episode_nav` uses.
 
@@ -357,5 +361,9 @@ def next_episode(db: Session, uid: int, show_id: int) -> dict | None:
     ep, st = pick
     show = db.get(PlexShow, show_id)
     return leaf_card(
-        ep, st, show_title=show.title if show else None, show_rk=show.rating_key if show else None
+        ep,
+        st,
+        show_title=display_title(show, lang) if show else None,
+        show_rk=show.rating_key if show else None,
+        lang=lang,
     )

backend/app/discover/rails.py

@@ -22,7 +22,7 @@ def plex_available(db: Session) -> bool:
     return sysconfig.get_bool(db, "plex_enabled")
 
 
-def playable(db: Session, uid: int, card: dict) -> dict | None:
+def playable(db: Session, uid: int, card: dict, *, lang: str) -> dict | None:
     """The thing that would actually START from this card — itself for anything with a runtime, and
     for a Plex SHOW the episode that is next (in progress, else the first unwatched, else the first).
 
@@ -40,11 +40,11 @@ def playable(db: Session, uid: int, card: dict) -> dict | None:
     sh = by_rating_key(db, PlexShow, card["id"])
     if sh is None:
         return None
-    ep = queries.next_episode(db, uid, sh.id)
+    ep = queries.next_episode(db, uid, sh.id, lang=lang)
     return cards.from_plex(ep) if ep else None
 
 
-def continue_watching(db: Session, user: User, limit: int = RAIL_LIMIT) -> list[dict]:
+def continue_watching(db: Session, user: User, limit: int = RAIL_LIMIT, *, lang: str) -> list[dict]:
     """One resume rail across both sources, most recently progressed first.
 
     A Plex SHOW enters as a show CARD — that is what the Plex rail shows, and it is the artwork the
@@ -57,17 +57,22 @@ def continue_watching(db: Session, user: User, limit: int = RAIL_LIMIT) -> list[
         (ts, cards.from_video(r)) for ts, r in queries.yt_in_progress(db, user, limit)
     ]
     if plex_available(db):
-        rows += [(ts, cards.from_plex(c)) for ts, c in queries.plex_in_progress(db, user.id, limit)]
+        rows += [
+            (ts, cards.from_plex(c))
+            for ts, c in queries.plex_in_progress(db, user.id, limit, lang=lang)
+        ]
     rows.sort(key=lambda r: r[0] or NO_TS, reverse=True)
     out = [card for _, card in rows[:limit]]
     # Resolve AFTER the slice: only the rows that survive it are worth a query.
     for card in out:
         if card["kind"] == "show":
-            card["next"] = playable(db, user.id, card)
+            card["next"] = playable(db, user.id, card, lang=lang)
     return out
 
 
-def surprise(db: Session, user: User, budget: str, seed: int, limit: int = 3) -> list[dict]:
+def surprise(
+    db: Session, user: User, budget: str, seed: int, limit: int = 3, *, lang: str
+) -> list[dict]:
     """The hero's draw pool: unseen things that fit the budget, from both sources under ONE seed.
 
     Interleaved rather than concatenated — the same alternation `routes/plex/discover.py` uses for its
@@ -83,7 +88,9 @@ def surprise(db: Session, user: User, budget: str, seed: int, limit: int = 3) ->
         (cards.from_video, queries.yt_surprise(db, user, budget, seed, limit)),
         (
             cards.from_plex,
-            queries.plex_surprise(db, user.id, budget, seed, limit) if plex_available(db) else [],
+            queries.plex_surprise(db, user.id, budget, seed, limit, lang=lang)
+            if plex_available(db)
+            else [],
         ),
     ]
     if seed % 2:

backend/app/feedquery.py

@@ -12,9 +12,10 @@ import binascii
 import json
 from datetime import date, datetime, timedelta, timezone
 
-from sqlalchemy import BigInteger, Select, and_, cast, false, func, or_, select
+from sqlalchemy import BigInteger, Select, and_, case, cast, false, func, or_, select
 from sqlalchemy.orm import Session, aliased
 
+from app.collation import collated
 from app.models import (
     LIVE_OR_UPCOMING,
     BlockedChannel,
@@ -264,7 +265,8 @@ def filtered_query(
     # the queries that surfaced the video > description; see Video.search_vector). YouTube-like
     # "fuzzy" matching: word-order-independent, multi-word AND, prefix on the word being typed,
     # accent-insensitive (unaccent_simple). The channel name still matches as a substring so
-    # channel searches work. `rank_expr` (weight-aware ts_rank) drives the "relevance" sort.
+    # channel searches work. `rank_expr` (weight-aware ts_rank) drives the "relevance" sort, over the
+    # newest RANK_WINDOW matches only (see there).
     rank_expr = None
     if q:
         # Resolve the channels whose NAME matches up front (there are only a few hundred channels, so
@@ -478,8 +480,10 @@ def feed_years(db: Session, user: User, **params) -> list[dict]:
 # replaces OFFSET/LIMIT: deep scrolling no longer scans-and-discards skipped rows,
 # and the page boundary is stable even as the scheduler ingests new videos mid-scroll
 # (OFFSET would shift and duplicate/skip rows).
-def sort_keys(sort: str, seed: int, rank_expr=None) -> list[dict]:
+def sort_keys(sort: str, seed: int, rank_expr=None, lang: str | None = None) -> list[dict]:
+    """`lang` orders the title sorts in the reader's alphabet (`collation`); the other keys ignore it."""
     pub = {"expr": Video.published_at, "asc": False, "nullable": False, "kind": "dt"}
+    title = collated(Video.title, lang)
     table: dict[str, list[dict]] = {
         "newest": [pub],
         "oldest": [{**pub, "asc": True}],
@@ -491,10 +495,8 @@ def sort_keys(sort: str, seed: int, rank_expr=None) -> list[dict]:
         "duration_asc": [
             {"expr": Video.duration_seconds, "asc": True, "nullable": True, "kind": "num"}
         ],
-        "title": [{"expr": func.lower(Video.title), "asc": True, "nullable": True, "kind": "str"}],
-        "title_desc": [
-            {"expr": func.lower(Video.title), "asc": False, "nullable": True, "kind": "str"}
-        ],
+        "title": [{"expr": title, "asc": True, "nullable": True, "kind": "str"}],
+        "title_desc": [{"expr": title, "asc": False, "nullable": True, "kind": "str"}],
         "subscribers": [
             {"expr": Channel.subscriber_count, "asc": False, "nullable": True, "kind": "num"}
         ],
@@ -542,6 +544,54 @@ def sort_keys(sort: str, seed: int, rank_expr=None) -> list[dict]:
     return table.get(sort) or table["newest"]
 
 
+# Relevance ranks only the newest RANK_WINDOW matches (E31): ts_rank reads every match's tsvector, and
+# a broad word matches most of the library ("a" ranked 193k rows in 6.8 s on prod, against 1.1 s to just
+# find them). The rows past the window keep rank 0, so they follow the ranked ones newest first; a word
+# that broad has no meaningful relevance order anyway, and a specific one fits the window whole.
+RANK_WINDOW = 2000
+
+
+def rank_window_start(db: Session, query: Select) -> datetime | None:
+    """The published_at the ranked window starts at: the RANK_WINDOW-th newest match, None when fewer
+    match (rank them all). The newest-first walk stops after RANK_WINDOW matches (40 ms for "a")."""
+    return db.scalar(
+        query.with_only_columns(Video.published_at)
+        .order_by(Video.published_at.desc())
+        .offset(RANK_WINDOW - 1)
+        .limit(1)
+    )
+
+
+def windowed_rank(rank_expr, since: datetime | None):
+    """`rank_expr` inside the window, 0 past it. CASE evaluates ts_rank only for the rows inside."""
+    if since is None:
+        return rank_expr
+    return case((Video.published_at >= since, rank_expr), else_=0)
+
+
+def windowed_relevance_rows(
+    db: Session, query: Select, keys: list[dict], window: datetime, cursor_id: str | None, n: int
+) -> list:
+    """Up to `n` rows of the windowed relevance order, read as its two halves: the window ranked, then
+    the rest newest first (every window row sorts before every row past it). As one ORDER BY the
+    planner computes the CASE for every match and sorts them all (2.7 s for "a" on prod); split, each
+    half rides an index (80 ms + 5 ms). With a cursor, `keys` carry its values (keyset_predicate)."""
+    pub_key = keys[1]  # relevance: [rank, published_at]
+    rows: list = []
+    if cursor_id is None or pub_key["value"] >= window:
+        inside = query.where(Video.published_at >= window).order_by(*order_by(keys))
+        if cursor_id is not None:
+            inside = inside.where(keyset_predicate(keys, cursor_id))
+        rows = list(db.execute(inside.limit(n)).all())
+    if len(rows) < n:
+        newest = [pub_key]  # past the window every rank is 0: the order is newest first
+        rest = query.where(Video.published_at < window).order_by(*order_by(newest))
+        if cursor_id is not None:
+            rest = rest.where(keyset_predicate(newest, cursor_id))
+        rows += db.execute(rest.limit(n - len(rows))).all()
+    return rows
+
+
 def order_by(keys: list[dict]):
     cols = []
     for k in keys:
@@ -588,26 +638,45 @@ def keyset_predicate(keys: list[dict], cursor_id: str):
     return rec(0)
 
 
-def encode_cursor(keys: list[dict], row) -> str:
+def encode_cursor(keys: list[dict], row, window: datetime | None = None) -> str:
+    """`window` is the relevance window's start: the cursor carries it, so every page ranks against the
+    window page one did. Recomputed per page, a video ingested mid-scroll would push the window's oldest
+    row to rank 0, behind the cursor, and the reader would see it twice."""
     vals = []
     for i, k in enumerate(keys):
         v = getattr(row, f"_k{i}")
         vals.append(v.isoformat() if (v is not None and k["kind"] == "dt") else v)
-    payload = json.dumps({"k": vals, "id": row.id})
+    body: dict = {"k": vals, "id": row.id}
+    if window is not None:
+        body["w"] = window.isoformat()
+    payload = json.dumps(body)
     return base64.urlsafe_b64encode(payload.encode()).decode()
 
 
-def decode_cursor(keys: list[dict], cursor: str) -> tuple[list, str]:
+def _cursor_dt(v):
+    """A cursor's timestamp: aware or refused. The server writes only aware ones (timestamptz), and
+    windowed_relevance_rows compares them in Python, where a naive one beside an aware one raises — a
+    500 for a hand-made cursor instead of the 400 (E31 review 2)."""
+    if v is None:
+        return None
+    dt = datetime.fromisoformat(v)
+    if dt.tzinfo is None:
+        raise ValueError("naive cursor timestamp")
+    return dt
+
+
+def decode_cursor(keys: list[dict], cursor: str) -> tuple[list, str, datetime | None]:
     try:
         payload = json.loads(base64.urlsafe_b64decode(cursor.encode()))
         raw = payload["k"]
         if len(raw) != len(keys):
             raise ValueError("key arity mismatch")
-        vals = [
-            datetime.fromisoformat(v) if (v is not None and k["kind"] == "dt") else v
-            for k, v in zip(keys, raw)
-        ]
-        return vals, payload["id"]
+        vals = [_cursor_dt(v) if k["kind"] == "dt" else v for k, v in zip(keys, raw)]
+        for k, v in zip(keys, vals):
+            if v is None and not k["nullable"]:
+                raise ValueError("null value for a non-nullable key")
+        window = payload.get("w")
+        return vals, payload["id"], _cursor_dt(window) if window else None
     except (binascii.Error, json.JSONDecodeError, KeyError, ValueError, TypeError) as exc:
         # Framework-free: the route handler translates this into an HTTP 400 so the
         # read-model stays web-layer-agnostic (see routes/feed.get_feed).

backend/app/main.py

@@ -24,11 +24,12 @@ from sqlalchemy.exc import DataError
 from starlette.middleware.sessions import SessionMiddleware
 
 from app import bodylimit
+from app import collation
 from app import logsink
 from app import state
 from app import sysconfig
 from app.config import settings
-from app.db import SessionLocal
+from app.db import SessionLocal, engine
 from app.plex import stream as plex_stream
 from app.plex import subtitles as plex_subtitles
 from app.routes import (
@@ -97,6 +98,9 @@ async def lifespan(app: FastAPI):
     # owns, so racing it against early playback is safe.
     sweep = asyncio.create_task(_sweep_hls_orphans())
     reaper = asyncio.create_task(_reap_hls_sessions())
+    # Fire and forget as well: a rebuild after an ICU upgrade takes seconds, and the title sorts serve
+    # meanwhile (CONCURRENTLY) in the old index's order, as they did before the restart.
+    heal = asyncio.create_task(_heal_collation_drift())
     start_scheduler()
     try:
         yield
@@ -106,7 +110,7 @@ async def lifespan(app: FastAPI):
         # pending ("Task was destroyed but it is pending!" — noise that reads like a bug during
         # triage). Cancelling does NOT interrupt the rmtree thread itself; this only makes our own
         # bookkeeping honest.
-        for task in (sweep, reaper):
+        for task in (sweep, reaper, heal):
             task.cancel()
             with suppress(asyncio.CancelledError):
                 await task
@@ -139,6 +143,18 @@ async def _reap_hls_sessions() -> None:
             log.exception("HLS session reap failed")
 
 
+async def _heal_collation_drift() -> None:
+    """Background startup check of the ICU collation the title-sort indexes are built in (see
+    `collation.heal_drift`). A failure is logged, never fatal: the sorts still answer, only possibly in
+    the old order."""
+    try:
+        await asyncio.to_thread(collation.heal_drift, engine)
+    except asyncio.CancelledError:
+        raise
+    except Exception:
+        log.exception("ICU collation drift check failed")
+
+
 async def _sweep_hls_orphans() -> None:
     """Background half of the startup HLS sweep (see lifespan). Owns its own errors: a failure here
     must never take the app down, and a cancelled shutdown is not one."""

backend/app/models.py

@@ -330,10 +330,12 @@ class Video(Base, TimestampMixin):
     __tablename__ = "videos"
 
     id: Mapped[str] = mapped_column(String(16), primary_key=True)  # video id
-    # No standalone channel_id index: the composite `ix_videos_channel_pub_desc`
-    # (channel_id, published_at DESC NULLS LAST, id) from migration 0067 leads with channel_id, so it
-    # serves every channel_id lookup (FK cascade, sync upsert, channel-detail) AND the per-channel feed
-    # sort. Like the search_vector GIN, this composite is migration-defined, not an inline `index=True`.
+    # No standalone channel_id index: the composite `ix_videos_channel_pub_cover`
+    # (channel_id, published_at DESC NULLS LAST, id) from migration 0095 leads with channel_id, so it
+    # serves every channel_id lookup (FK cascade, sync upsert, channel-detail) and the per-channel feed
+    # sort. Its INCLUDEd columns make the channel manager's sums and the feed sidebar's counts Index Only
+    # Scans (no heap): a column those queries start reading belongs in it (test_channel_list_index_only).
+    # Like the search_vector GIN, this composite is migration-defined, not an inline `index=True`.
     channel_id: Mapped[str] = mapped_column(ForeignKey("channels.id", ondelete="CASCADE"))
     title: Mapped[str | None] = mapped_column(Text)  # normalized for display (see app.titles)
     original_title: Mapped[str | None] = mapped_column(Text)  # raw YouTube title, preserved
@@ -347,6 +349,9 @@ class Video(Base, TimestampMixin):
         DateTime(timezone=True), index=True, nullable=False, server_default=func.now()
     )
     thumbnail_url: Mapped[str | None] = mapped_column(String(1024))
+    # The feed's views / duration / title sorts each ride a migration-defined index in their exact
+    # ORDER BY, one per direction (and per ICU collation for title): migration 0096, held to
+    # `feedquery.order_by` by test_feed_sort_indexes.
     duration_seconds: Mapped[int | None] = mapped_column(Integer)
     view_count: Mapped[int | None] = mapped_column(BigInteger)
     like_count: Mapped[int | None] = mapped_column(BigInteger)
@@ -1224,6 +1229,7 @@ class PlexShow(Base, TimestampMixin, UpdatedAtMixin):
     # Hungarian-metadata twin fields, written by the overlay sync (E5 S5). NULL = no HU twin matched,
     # so serving falls back to the EN columns. `people_text` is language-neutral, reused for both vectors.
     title_hu: Mapped[str | None] = mapped_column(String(512))
+    tagline_hu: Mapped[str | None] = mapped_column(Text)  # the HU overlay's tagline (E30)
     summary_hu: Mapped[str | None] = mapped_column(Text)
     genres_hu: Mapped[list | None] = mapped_column(JSONB(none_as_null=True))
     search_vector: Mapped[object | None] = mapped_column(
@@ -1385,6 +1391,7 @@ class PlexItem(Base, TimestampMixin, UpdatedAtMixin):
     # Hungarian-metadata twin fields, written by the overlay sync (E5 S5). NULL = no HU twin matched
     # (serving falls back to the EN columns). `people_text` is language-neutral, reused for both vectors.
     title_hu: Mapped[str | None] = mapped_column(String(512))
+    tagline_hu: Mapped[str | None] = mapped_column(Text)  # the HU overlay's tagline (E30)
     summary_hu: Mapped[str | None] = mapped_column(Text)
     genres_hu: Mapped[list | None] = mapped_column(JSONB(none_as_null=True))
     search_vector: Mapped[object | None] = mapped_column(
@@ -1415,7 +1422,8 @@ class PlexPerson(Base, TimestampMixin, UpdatedAtMixin):
     top few cast. Rows whose name no longer appears in ANY item's cast_names/directors (a library
     removal orphaned them) are pruned by the maintenance sweep, mirroring how Plex drops orphaned
     metadata. The filterable cast lives in plex_items/plex_shows.cast_names (self-cleaning with the
-    row); this table is ONLY the headshot cache."""
+    row); this table is the people's own facts: the headshot link, the TMDB link and the TMDB bio
+    (the headshot FILE lives in the image cache, filled by the people_enrich job)."""
 
     __tablename__ = "plex_people"
 
@@ -1425,11 +1433,15 @@ class PlexPerson(Base, TimestampMixin, UpdatedAtMixin):
     # TMDB person id, linked by name from a title's TMDB credits (E5 S2 lays the foundation; the /person
     # biography fetch + person-page render land in S6). NULL until a TMDB-enriched title names this person.
     tmdb_person_id: Mapped[int | None] = mapped_column(Integer)
-    # --- TMDB person enrichment (E5 S6): fetched from /person/{tmdb_person_id} the first time the person
-    #     page is opened, then SERVED FROM THE ROW. `tmdb_enriched_at` is the watermark (set even on a
+    # --- TMDB person enrichment (E5 S6): fetched from /person/{tmdb_person_id} by the people_enrich job
+    #     (E30 S6), or by the first person-page open the job hasn't reached, then SERVED FROM THE ROW. `tmdb_enriched_at` is the watermark (set even on a
     #     no-op fetch so it isn't retried every open). `known_for` = top combined-credits [{tmdb_id,
     #     media_type, title}], resolved to library rows by guid at serve time (like recommendations). ---
     biography: Mapped[str | None] = mapped_column(Text)
+    # TMDB's Hungarian biography (E30 S4), from the same request's `translations`; a Hungarian reader is
+    # served it, and the instance-language `biography` when TMDB has none. Birthplace, aliases and
+    # keywords have no Hungarian on TMDB, so they stay in the instance language.
+    biography_hu: Mapped[str | None] = mapped_column(Text)
     birthday: Mapped[str | None] = mapped_column(String(10))  # "YYYY-MM-DD", served as-is
     deathday: Mapped[str | None] = mapped_column(String(10))
     place_of_birth: Mapped[str | None] = mapped_column(Text)

backend/app/plex/cards.py

@@ -15,20 +15,35 @@ def _art_url(rating_key: str, art_key: str | None) -> str | None:
 
 
 # Card hover-overview: a short synopsis for the reveal panel, trimmed so a strip/related row of cards
-# stays a few hundred bytes each rather than carrying full synopses. (These non-grid card paths serve
-# the EN summary/rating; the main grid coalesces the HU twin in browse.unified_library.)
+# stays a few hundred bytes each rather than carrying full synopses.
 def _card_summary(summary: str | None) -> str | None:
     return (summary or "")[:300] or None
 
 
-def movie_card(it: PlexItem, st: PlexState | None) -> dict:
+def norm_lang(lang: str | None) -> str:
+    """The overlay has an EN base + an optional HU twin; anything other than `hu` serves EN."""
+    return "hu" if lang == "hu" else "en"
+
+
+# Every card speaks the reader's language (E30): `lang="hu"` serves the HU overlay twin's title and
+# summary, falling back to EN where a row has none — the same rule as browse.unified_library's
+# `title_col`/`summary_col`. These rails once served English to a Hungarian reader.
+def display_title(row: PlexItem | PlexShow, lang: str) -> str:
+    return (row.title_hu or row.title) if lang == "hu" else row.title
+
+
+def display_summary(row: PlexItem | PlexShow, lang: str) -> str | None:
+    return (row.summary_hu or row.summary) if lang == "hu" else row.summary
+
+
+def movie_card(it: PlexItem, st: PlexState | None, *, lang: str) -> dict:
     return {
         "id": it.rating_key,
         "type": "movie",
-        "title": it.title,
+        "title": display_title(it, lang),
         "year": it.year,
         "rating": it.rating,
-        "summary": _card_summary(it.summary),
+        "summary": _card_summary(display_summary(it, lang)),
         "duration_seconds": it.duration_s,
         "thumb": f"/api/plex/image/{it.rating_key}",
         "art": _art_url(it.rating_key, it.art_key),
@@ -39,14 +54,14 @@ def movie_card(it: PlexItem, st: PlexState | None) -> dict:
     }
 
 
-def show_card(sh: PlexShow, status: str = "new") -> dict:
+def show_card(sh: PlexShow, status: str = "new", *, lang: str) -> dict:
     return {
         "id": sh.rating_key,
         "type": "show",
-        "title": sh.title,
+        "title": display_title(sh, lang),
         "year": sh.year,
         "rating": sh.rating,
-        "summary": _card_summary(sh.summary),
+        "summary": _card_summary(display_summary(sh, lang)),
         "thumb": f"/api/plex/image/{sh.rating_key}",
         "art": _art_url(sh.rating_key, sh.art_key),
         "season_count": sh.child_count,
@@ -55,12 +70,12 @@ def show_card(sh: PlexShow, status: str = "new") -> dict:
     }
 
 
-def episode_card(e: PlexItem, st: PlexState | None) -> dict:
+def episode_card(e: PlexItem, st: PlexState | None, *, lang: str) -> dict:
     return {
         "id": e.rating_key,
         "type": "episode",
-        "title": e.title,
-        "summary": e.summary,
+        "title": display_title(e, lang),
+        "summary": display_summary(e, lang),
         "season_number": e.season_number,
         "episode_number": e.episode_number,
         "duration_seconds": e.duration_s,
@@ -77,12 +92,15 @@ def leaf_card(
     st: PlexState | None,
     show_title: str | None = None,
     show_rk: str | None = None,
+    *,
+    lang: str,
 ) -> dict:
     """A playable-leaf card (movie or episode). Used by playlists, which can mix both kinds.
-    `show_rk` (the show's rating_key) lets the client group a playlist's episodes by show/season."""
+    `show_rk` (the show's rating_key) lets the client group a playlist's episodes by show/season.
+    `show_title` is the caller's, already in `lang` (see `display_title`)."""
     if it.kind == "episode":
-        card = episode_card(it, st)
+        card = episode_card(it, st, lang=lang)
         card["show_title"] = show_title
         card["show_id"] = show_rk
         return card
-    return movie_card(it, st)
+    return movie_card(it, st, lang=lang)

backend/app/plex/genres.py

@@ -0,0 +1,100 @@
+"""One Hungarian word per Plex genre (E30).
+
+Plex's Hungarian agent returns a MIXED vocabulary: some genres come back translated ("Dráma",
+"Vígjáték"), others stay English ("Action", "Adventure", "Biography"), and a title with no HU twin has
+only its English genres. The HU genre list therefore offered "Drama" beside "Dráma" and a dozen English
+words. This map sends every genre word we have met — English (Plex EN agent, TMDB, IMDb) or Plex's
+Hungarian — to the ONE word a Hungarian reader sees. The overlay sync writes it into `genres_hu`, and a
+genre filter is read through it too, so a saved filter still holding "Action" keeps matching "Akció".
+
+A word not in the map passes through unchanged: an unknown genre stays visible (in whatever language
+Plex gave it) rather than disappearing.
+"""
+
+from collections.abc import Iterable
+
+# Keys are matched case-insensitively (see `_BY_KEY`). The Hungarian values double as keys mapping to
+# themselves, so running a list through twice changes nothing.
+_HU: dict[str, str] = {
+    "Action": "Akció",
+    "Action & Adventure": "Akció és kaland",
+    "Adventure": "Kaland",
+    "Animation": "Animációs",
+    "Anime": "Anime",
+    "Biography": "Életrajzi",
+    "Children": "Gyerek",
+    "Comedy": "Vígjáték",
+    "Crime": "Bűnügyi",
+    "Documentary": "Dokumentum",
+    "Drama": "Dráma",
+    "Family": "Családi",
+    "Fantasy": "Fantasy",
+    "Film-Noir": "Film noir",
+    "Food": "Gasztronómia",
+    "Game Show": "Vetélkedő",
+    "Game-Show": "Vetélkedő",
+    "History": "Történelmi",
+    "Home and Garden": "Otthon és kert",
+    "Horror": "Horror",
+    "Indie": "Független",
+    "Kids": "Gyerek",
+    "Martial Arts": "Harcművészet",
+    "Mini-Series": "Minisorozat",
+    "Music": "Zenei",
+    "Musical": "Musical",
+    "Mystery": "Rejtély",
+    "News": "Hírek",
+    "Reality": "Valóságshow",
+    "Reality-TV": "Valóságshow",
+    "Romance": "Romantikus",
+    "Sci-Fi": "Sci-Fi",
+    "Sci-Fi & Fantasy": "Sci-Fi és fantasy",
+    "Science Fiction": "Sci-Fi",
+    "Short": "Rövidfilm",
+    "Soap": "Szappanopera",
+    "Sport": "Sport",
+    "Suspense": "Feszültség",
+    "Talk": "Talkshow",
+    "Talk Show": "Talkshow",
+    "Thriller": "Thriller",
+    "Travel": "Utazás",
+    "TV Movie": "TV film",
+    "War": "Háborús",
+    "War & Politics": "Háború és politika",
+    "Western": "Western",
+    # Plex's own Hungarian words, pinned to themselves (and to the spelling above where they differ).
+    "Akció": "Akció",
+    "Animációs": "Animációs",
+    "Bűnügyi": "Bűnügyi",
+    "Családi": "Családi",
+    "Dokumentum": "Dokumentum",
+    "Dokumentumfilm": "Dokumentum",
+    "Dráma": "Dráma",
+    "Életrajzi": "Életrajzi",
+    "Háborús": "Háborús",
+    "Kaland": "Kaland",
+    "Rejtély": "Rejtély",
+    "Romantikus": "Romantikus",
+    "Történelmi": "Történelmi",
+    "TV film": "TV film",
+    "Vígjáték": "Vígjáték",
+    "Zene": "Zenei",
+    "Zenei": "Zenei",
+}
+_BY_KEY = {k.casefold(): v for k, v in _HU.items()}
+
+
+def hu_genre(word: str) -> str:
+    """The Hungarian word for one genre; an unknown word comes back unchanged."""
+    return _BY_KEY.get(word.strip().casefold(), word)
+
+
+def hu_genres(words: Iterable[str] | None) -> list[str] | None:
+    """A genre list in Hungarian, in its first-seen order, each word once ("Drama" + "Dráma" → one
+    "Dráma"). None or empty stays None, like the listing's own `_tags`."""
+    out: list[str] = []
+    for w in words or ():
+        hu = hu_genre(w)
+        if hu not in out:
+            out.append(hu)
+    return out or None

backend/app/plex/imgcache.py

@@ -8,6 +8,9 @@ few hundred MB at most for a big library — acceptable, matching the download d
 The cache directory (``cache.CACHE_DIR``) is shared with the subtitle cache (see ``subtitles.py``).
 """
 
+import time
+from datetime import timedelta
+
 from fastapi import Response
 from sqlalchemy.orm import Session
 
@@ -20,9 +23,23 @@ log = logs.get_logger(__name__)
 
 _EXT_CT = [("jpg", "image/jpeg"), ("png", "image/png"), ("webp", "image/webp")]
 _CT_EXT = {ct: ext for ext, ct in _EXT_CT}
-# Target box per variant — Plex resizes to these server-side. Posters fill ≤176px cells (grid/info/
-# strips), so 400px covers 2× DPR; the faint backdrop art only needs ~1280px. Keeps images ~tens of KB.
-SIZES = {"thumb": (400, 600), "art": (1280, 720)}
+# Target box per variant — Plex resizes to these server-side. The full poster (400px) covers a detail
+# page's ≤224px poster at 2× DPR, the full art (1280px) a hero backdrop. A card is much smaller: a grid
+# poster is ~144px and a shelf's landscape art ~212px, so the `_sm` pair serves those at 1.33× DPR
+# (E31 S4e: cards fetched the 400 poster, 42 KB, and the 1280 art for a 212px picture). The browser
+# picks between a pair itself (`srcset`, built by the frontend's `lib/plexImage` cardImage, whose
+# widths plexImage.contract.test holds to these).
+SIZES = {
+    "thumb": (400, 600),
+    "thumb_sm": (240, 360),
+    "art": (1280, 720),
+    "art_sm": (480, 270),
+}
+
+
+def picture(variant: str) -> str:
+    """Which stored picture a size variant is cut from: the poster (`thumb`) or the backdrop (`art`)."""
+    return "art" if variant.startswith("art") else "thumb"
 
 
 def key_for(db: Session, rating_key: str, variant: str) -> str | None:
@@ -56,6 +73,49 @@ def read(key: str) -> tuple[bytes, str] | None:
     return None
 
 
+def has(key: str) -> bool:
+    """A cached, non-empty file exists for `key` (a prefetch's cheap check — no read)."""
+    for ext, _ in _EXT_CT:
+        try:
+            if (CACHE_DIR / f"{key}.{ext}").stat().st_size > 0:
+                return True
+        # silent-ok: a miss, as in read().
+        except OSError:
+            pass
+    return False
+
+
+def drop(key: str) -> None:
+    """Remove `key`'s file, whatever its extension (a superseded variant). Best-effort."""
+    for ext, _ in _EXT_CT:
+        try:
+            (CACHE_DIR / f"{key}.{ext}").unlink(missing_ok=True)
+        # silent-ok: a leftover original only costs disk; the small twin is already written.
+        except OSError:
+            pass
+
+
+def mark_miss(key: str) -> None:
+    """Remember that `key`'s source could not be fetched (an empty `.miss` file; its mtime is when), so
+    a prefetch can leave a dead source alone for a while. Best-effort."""
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        (CACHE_DIR / f"{key}.miss").touch()
+    # silent-ok: without the mark the dead source is only asked for again on the next run.
+    except OSError:
+        pass
+
+
+def missed_within(key: str, age: timedelta) -> bool:
+    """`key` was marked as a miss less than `age` ago."""
+    try:
+        mtime = (CACHE_DIR / f"{key}.miss").stat().st_mtime
+    # silent-ok: no mark (the usual case).
+    except OSError:
+        return False
+    return time.time() - mtime < age.total_seconds()
+
+
 def write(key: str, data: bytes, ct: str) -> None:
     ext = _CT_EXT.get((ct or "").split(";")[0].strip(), "jpg")
     try:

backend/app/plex/people.py

@@ -3,13 +3,23 @@ or show (cast_names + the people_text search blob + the plex_people headshot cac
 orphaned people. Used by BOTH the info-page lazy enrichment (routes.plex) and the background rich
 re-sync (plex.sync), so the two paths never diverge."""
 
-from urllib.parse import quote
+import hashlib
+import re
+from datetime import timedelta
+from typing import Literal
+from urllib.parse import quote, unquote
 
+import httpx
 from sqlalchemy import select, text
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
 
+from app import logs, sysconfig
 from app.models import PlexPerson
+from app.plex import imgcache
+from app.plex.client import PlexClient, PlexError, PlexNotConfigured
+
+log = logs.get_logger(__name__)
 
 # Cast/crew photos come from Plex's PUBLIC metadata CDN (no token). We proxy them (host-whitelisted)
 # so the user's browser makes no third-party request (privacy + self-host CSP friendliness).
@@ -19,9 +29,7 @@ PERSON_IMG_HOST = "https://metadata-static.plex.tv/"
 def person_thumb_url(thumb: str | None) -> str | None:
     """Proxied /person-image URL for a Plex CDN headshot, or None when it's missing / off-CDN."""
     t = str(thumb or "")
-    return (
-        f"/api/plex/person-image?u={quote(t, safe='')}" if t.startswith(PERSON_IMG_HOST) else None
-    )
+    return f"/api/plex/person-image?u={quote(t, safe='')}" if is_portrait_url(t) else None
 
 
 def cast_from_meta(meta: dict, limit: int = 24) -> list[dict]:
@@ -89,14 +97,23 @@ def enrich_row_people(db: Session, row, cast: list[dict]) -> bool:
     return dirty
 
 
+# Every credit reference: one person name per (movie/show, credit column). The ONE list of credit
+# columns, so the orphan prune and the enrichment order never disagree about who is credited.
+_CREDIT_COLUMNS = [
+    (table, col) for table in ("plex_items", "plex_shows") for col in ("cast_names", "directors")
+]
+
+
+def _credit_refs_sql(union: Literal["UNION", "UNION ALL"]) -> str:
+    return f" {union} ".join(
+        f"SELECT jsonb_array_elements_text({col}) FROM {table} WHERE jsonb_typeof({col}) = 'array'"
+        for table, col in _CREDIT_COLUMNS
+    )
+
+
 # The person names still referenced by ANY movie/show (cast OR directors). plex_people rows outside
 # this set are orphans left by a library removal.
-_REFERENCED_PEOPLE_SQL = """
-    SELECT jsonb_array_elements_text(cast_names) FROM plex_items WHERE jsonb_typeof(cast_names) = 'array'
-    UNION SELECT jsonb_array_elements_text(directors) FROM plex_items WHERE jsonb_typeof(directors) = 'array'
-    UNION SELECT jsonb_array_elements_text(cast_names) FROM plex_shows WHERE jsonb_typeof(cast_names) = 'array'
-    UNION SELECT jsonb_array_elements_text(directors) FROM plex_shows WHERE jsonb_typeof(directors) = 'array'
-"""
+_REFERENCED_PEOPLE_SQL = _credit_refs_sql("UNION")
 
 
 def prune_orphan_people(db: Session) -> int:
@@ -113,3 +130,152 @@ def prune_orphan_people(db: Session) -> int:
     )
     db.commit()
     return res.rowcount or 0
+
+
+# How often each person is credited across movies, shows and episodes (cast OR director) — the order the
+# people_enrich job works in, so the faces met most often are local first.
+_CREDIT_COUNTS_SQL = (
+    f"SELECT ref, count(*) AS n FROM ({_credit_refs_sql('UNION ALL')}) AS refs(ref) GROUP BY ref"
+)
+_NEEDS = {
+    # linked to TMDB, bio never fetched
+    "bio": "p.tmdb_person_id IS NOT NULL AND p.tmdb_enriched_at IS NULL",
+    # has a Plex headshot (whether it is cached is the disk's answer, not the row's)
+    "portrait": "p.photo_thumb IS NOT NULL",
+}
+
+
+def people_by_credits(
+    db: Session, need: Literal["bio", "portrait"], limit: int | None
+) -> list[int]:
+    """plex_people ids that `need` something, the most-credited first (ties by id)."""
+    rows = db.execute(
+        text(
+            f"SELECT p.id FROM plex_people p LEFT JOIN ({_CREDIT_COUNTS_SQL}) c ON c.ref = p.name "
+            f"WHERE {_NEEDS[need]} ORDER BY coalesce(c.n, 0) DESC, p.id"
+            + (" LIMIT :limit" if limit is not None else "")
+        ),
+        {"limit": limit} if limit is not None else {},
+    )
+    return [r[0] for r in rows]
+
+
+# --- Portraits (E30 S6) ---------------------------------------------------------------------------
+# A Plex CDN headshot is a full-size original (~170 KB on average, measured). Plex's photo transcoder
+# fits it into this box (~13 KB), which covers the largest place a portrait is drawn (the person page's
+# 6rem avatar) at 2x density and a raised text size. The box is part of the cache key, like a poster's:
+# a new box re-caches instead of serving a stale size. Only a resized image is ever written under it —
+# an original fetched without Plex keeps its own key, and goes once its small twin lands.
+PORTRAIT_BOX = 320
+# A headshot Plex answered "not found" for (a dead CDN file) is not asked for again this long, so a
+# few dead faces never hold up the rest of the prefetch.
+PORTRAIT_RETRY = timedelta(days=7)
+# The one shape a Plex CDN headshot has (…/7/people/<hash>.jpg): plain path segments, no query, no
+# fragment, no dot segment or empty segment (an HTTP client folds `a/../b` and the CDN `a//b` onto one
+# file). The person-image proxy takes nothing else, so it cannot be made to cache endless spellings of
+# one file (the image cache has no eviction). Used where a stored headshot is made, served and warmed.
+_SEGMENT = r"[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*"  # a name, dots only between its parts
+_PORTRAIT_URL = re.compile(re.escape(PERSON_IMG_HOST) + _SEGMENT + rf"(?:/{_SEGMENT})*")
+
+
+def is_portrait_url(url: str) -> bool:
+    return _PORTRAIT_URL.fullmatch(url) is not None
+
+
+def _portrait_keys(url: str) -> tuple[str, str]:
+    """(the resized portrait's key, the full-size original's key)."""
+    base = "person_" + hashlib.sha1(url.encode()).hexdigest()
+    return f"{base}_{PORTRAIT_BOX}", base
+
+
+def portrait_cached(url: str) -> tuple[bytes, str] | None:
+    """The cached portrait: the resized one, else an original kept from a time without Plex."""
+    small, original = _portrait_keys(url)
+    return imgcache.read(small) or imgcache.read(original)
+
+
+def cache_portrait(plex: PlexClient | None, url: str) -> tuple[bytes, str]:
+    """Fetch one CDN headshot and cache it. With a Plex client it is resized (the box key; the original
+    is removed); without one the original comes straight from the public CDN and is cached under its own
+    key, so the job still resizes it once Plex is there. Raises PlexError / httpx.HTTPError."""
+    small, original = _portrait_keys(url)
+    if plex is None:
+        with httpx.Client(timeout=10.0, follow_redirects=True) as c:
+            r = c.get(url)
+            r.raise_for_status()
+        data, ct = r.content, r.headers.get("content-type", "image/jpeg")
+        imgcache.write(original, data, ct)
+        return data, ct
+    data, ct = plex.image_bytes(url, PORTRAIT_BOX, PORTRAIT_BOX)
+    imgcache.write(small, data, ct)
+    imgcache.drop(original)
+    return data, ct
+
+
+def cdn_url(photo_thumb: str) -> str | None:
+    """The CDN url inside a stored proxied `/person-image?u=` value (see person_thumb_url)."""
+    _, _, q = photo_thumb.partition("?u=")
+    url = unquote(q)
+    return url if is_portrait_url(url) else None
+
+
+# Plex failing this many headshots in a row ends a run: it is Plex that is failing, not the files.
+_PLEX_DOWN_AFTER = 3
+# The statuses that mean the one file is gone.
+_DEAD = frozenset({404, 410})
+
+
+def warm_portraits(db: Session, limit: int) -> dict:
+    """Cache up to `limit` not-yet-cached headshots, the most-credited people first (E30 S6), so a
+    person's face comes from local disk. Needs Plex (the resize) and the Plex module on; without them
+    nothing is prefetched — full-size originals for every person would cost gigabytes. A headshot Plex
+    answers "not found" for is marked and left for PORTRAIT_RETRY; Plex failing in a row ends the run."""
+    if not sysconfig.get_bool(db, "plex_enabled"):
+        return {"cached": 0, "skipped": "disabled"}
+    try:
+        plex = PlexClient(db)
+    # silent-ok: no Plex server set up is a setting, not a failure; the run's result says "disabled".
+    except PlexNotConfigured:
+        return {"cached": 0, "skipped": "disabled"}
+    photos: dict[int, str] = {
+        pid: thumb
+        for pid, thumb in db.execute(
+            select(PlexPerson.id, PlexPerson.photo_thumb).where(PlexPerson.photo_thumb.is_not(None))
+        ).tuples()
+        if thumb
+    }
+    # `down` counts Plex failing in a row (any answer from Plex breaks it), `plex_failed` in all
+    done = dead = plex_failed = down = 0
+    with plex:
+        for pid in people_by_credits(db, "portrait", None):
+            if done + dead >= limit or down >= _PLEX_DOWN_AFTER:
+                break
+            url = cdn_url(photos.get(pid) or "")
+            if url is None:
+                continue
+            key = _portrait_keys(url)[0]
+            if imgcache.has(key) or imgcache.missed_within(key, PORTRAIT_RETRY):
+                continue
+            try:
+                cache_portrait(plex, url)
+                done, down = done + 1, 0
+            except PlexError as exc:
+                # "Not found" is Plex's answer about this one file (a dead CDN headshot: measured 404,
+                # the CDN itself says 403). Anything else — no answer, a refused token, a 5xx — is
+                # Plex failing, which must neither mark the file nor keep the run going.
+                cause = exc.__cause__
+                if isinstance(cause, httpx.HTTPStatusError) and cause.response.status_code in _DEAD:
+                    dead, down = dead + 1, 0  # Plex answered: it is up, the streak is broken
+                    imgcache.mark_miss(key)
+                else:
+                    plex_failed, down = plex_failed + 1, down + 1
+                log.warning(
+                    "a portrait could not be cached",
+                    extra=logs.event(
+                        "plex.people.portrait_failed",
+                        person_id=pid,
+                        reason=type(exc.__cause__).__name__,
+                    ),
+                )
+    failed = dead + plex_failed
+    return {"cached": done, **({"failed": failed} if failed else {})}

backend/app/plex/query.py

@@ -11,6 +11,7 @@ from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Session
 
 from app.models import PlexItem, PlexLibrary
+from app.plex.genres import hu_genre
 
 TS_CONFIG = "public.unaccent_simple"
 
@@ -183,7 +184,13 @@ def meta_filter_conds(model, p: dict, lang: str = "en") -> list:
     gsel = split_csv(p.get("genres"))
     if gsel:
         gcol = genres_col(model, lang)
-        gc = [gcol.contains([g]) for g in gsel]
+        if lang == "hu":
+            # The HU column holds one Hungarian word per genre (plex/genres.py), so a filter saved while
+            # it offered "Action" is read as "Akció" too. The word as picked still matches as well: a row
+            # the sync has not reached since keeps its English (or Plex's mixed) list until it does.
+            gc = [or_(*(gcol.contains([w]) for w in dict.fromkeys((hu_genre(g), g)))) for g in gsel]
+        else:
+            gc = [gcol.contains([g]) for g in gsel]
         conds.append(and_(*gc) if p.get("genre_mode") == "all" else or_(*gc))
     crs = split_csv(p.get("content_ratings"))
     if crs:

backend/app/plex/subtitles.py

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

backend/app/plex/sync.py

@@ -15,6 +15,7 @@ dead `enabled` column) is a separate follow-up. Cast + intro/credit markers are
 item-detail/player path (P2), not here.
 """
 
+from collections.abc import Iterable
 from datetime import datetime, timezone
 
 from sqlalchemy import func, select
@@ -24,6 +25,7 @@ from app import logs, sysconfig
 from app.models import PlexCollection, PlexItem, PlexLibrary, PlexSeason, PlexShow
 from app.plex import detail, people
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
+from app.plex.genres import hu_genres
 from app.plex.lookups import by_rating_key
 
 log = logs.get_logger(__name__)
@@ -448,6 +450,10 @@ def _apply_facet_fields(row, meta: dict) -> None:
     row.studio = (meta.get("studio") or None) and str(meta.get("studio"))[:255]
     row.originally_available_at = _date(meta.get("originallyAvailableAt"))
     row.genres = _tags(meta, "Genre")
+    # Every row has Hungarian genres, not only one with an HU overlay twin (the overlay pass, which runs
+    # after this, puts the twin's own list over it): the HU genre facets and filter read this column,
+    # and an English word there could never match a filter read in Hungarian.
+    row.genres_hu = hu_genres(row.genres)
     row.directors = _tags(meta, "Director")
     # The listing carries only the top ~20 cast, so re-applying it would DOWNGRADE an already-enriched
     # full cast (up to 24, grown by the rich backfill/info-page enrich), silently breaking the
@@ -659,35 +665,72 @@ def _sync_overlay(
     db: Session, plex: PlexClient, lib: PlexLibrary, en_lib_id: int, stats: dict
 ) -> None:
     """Write an overlay section's Hungarian metadata onto its EN twin's rows, matched by guid. Creates
-    NO browsable rows — an overlay library is never listed on its own. Only title/summary/genres differ
-    by language; the language-neutral people_text feeds both search vectors.
+    NO browsable rows — an overlay library is never listed on its own. Only title/summary/tagline/genres
+    differ by language; the language-neutral people_text feeds both search vectors. A show section's
+    episodes are overlaid too (E30): the HU section lists every episode with its Hungarian title and
+    summary, and the episode rows live in the EN show library.
 
     This is a full RECONCILE: every guid-bearing EN row's HU fields are cleared first, then the HU
     section repopulates the matches — so an EN row whose HU twin vanished (or was re-guid'd) falls back
     to EN instead of keeping stale Hungarian metadata. HU items with no EN match are skipped."""
     if lib.kind == "movie":
-        rows = db.execute(
-            select(PlexItem).where(
-                PlexItem.library_id == en_lib_id,
-                PlexItem.kind == "movie",
-                PlexItem.guid.is_not(None),
+        passes = [
+            (
+                _TYPE_MOVIE,
+                select(PlexItem).where(
+                    PlexItem.library_id == en_lib_id,
+                    PlexItem.kind == "movie",
+                    PlexItem.guid.is_not(None),
+                ),
             )
-        ).scalars()
-        item_type = _TYPE_MOVIE
+        ]
     else:
-        rows = db.execute(
-            select(PlexShow).where(PlexShow.library_id == en_lib_id, PlexShow.guid.is_not(None))
-        ).scalars()
-        item_type = _TYPE_SHOW
+        passes = [
+            (
+                _TYPE_SHOW,
+                select(PlexShow).where(
+                    PlexShow.library_id == en_lib_id, PlexShow.guid.is_not(None)
+                ),
+            ),
+            (
+                _TYPE_EPISODE,
+                select(PlexItem).where(
+                    PlexItem.library_id == en_lib_id,
+                    PlexItem.kind == "episode",
+                    PlexItem.guid.is_not(None),
+                ),
+            ),
+        ]
+    for item_type, rows_q in passes:
+        _overlay_pass(db, plex, lib, item_type, db.execute(rows_q).scalars(), stats)
+    db.flush()
+
+
+def _overlay_pass(
+    db: Session,
+    plex: PlexClient,
+    lib: PlexLibrary,
+    item_type: int,
+    rows: Iterable[PlexItem] | Iterable[PlexShow],
+    stats: dict,
+) -> None:
+    """One kind of the overlay (movies, shows or episodes) — see `_sync_overlay`."""
     # guid -> the EN rows carrying it (a list: two editions of one film can share a guid; both overlay).
-    by_guid: dict[str, list] = {}
+    by_guid: dict[str, list[PlexItem | PlexShow]] = {}
     for r in rows:
-        by_guid.setdefault(r.guid, []).append(r)
+        if r.guid:  # the passes select guid-bearing rows only
+            by_guid.setdefault(r.guid, []).append(r)
     # Reconcile step: clear HU fields on all guid-bearing rows. Only rows that actually held HU data
     # become dirty (SQLAlchemy skips a no-net-change UPDATE), so this is cheap; matches are re-set below.
+    # The genres are the exception: every row gets Hungarian ones, from its HU twin or, lacking one, from
+    # its own English list — otherwise the HU genre list mixed "Drama" (no twin) with "Dráma".
+    episodes = item_type == _TYPE_EPISODE
     for group in by_guid.values():
         for row in group:
-            row.title_hu = row.summary_hu = row.genres_hu = None
+            row.title_hu = row.summary_hu = None
+            if not episodes:
+                row.tagline_hu = None
+                row.genres_hu = hu_genres(row.genres)
     seen: set[str] = (
         set()
     )  # first HU entry for a guid wins; a dup HU item can't overwrite or double-count
@@ -699,13 +742,15 @@ def _sync_overlay(
         seen.add(g)
         title_hu = (meta.get("title") or "").strip() or None
         summary_hu = meta.get("summary")
-        genres_hu = _tags(meta, "Genre")
+        tagline_hu = (meta.get("tagline") or "").strip() or None
+        genres_hu = hu_genres(_tags(meta, "Genre"))
         for row in targets:
             row.title_hu = title_hu
             row.summary_hu = summary_hu
-            row.genres_hu = genres_hu
+            if not episodes:
+                row.tagline_hu = tagline_hu
+                row.genres_hu = genres_hu or row.genres_hu
         stats["overlaid"] = stats.get("overlaid", 0) + 1
-    db.flush()
 
 
 def _upsert_collection(

backend/app/plex/tmdb.py

@@ -10,8 +10,10 @@ One-parser rule (mirrors app/plex/detail.py): `parse_tmdb` is the pure parser, `
 the row. The enrich batch + scheduler entry live here too so the whole TMDB integration is one module.
 """
 
+import re
 import time
 from datetime import datetime, timezone
+from typing import cast
 
 import httpx
 from sqlalchemy import func, select
@@ -21,6 +23,8 @@ from sqlalchemy.orm import Session
 from app import logs, sysconfig
 from app.config import settings
 from app.models import PlexItem, PlexPerson, PlexShow
+from app.plex.cards import display_title
+from app.plex.people import people_by_credits, warm_portraits
 
 log = logs.get_logger(__name__)
 # Politeness throttle: TMDB tolerates ~50 req/s; ~33/s leaves comfortable headroom for a shared host.
@@ -124,9 +128,17 @@ class TmdbClient:
         """Resolve an external id (imdb_id / tvdb_id) to TMDB items via /find."""
         return self._get(f"/find/{external_id}", {"external_source": source})
 
+    def countries(self) -> list[dict] | None:
+        """TMDB's country list: `[{iso_3166_1, english_name, native_name}]` (a JSON array, which
+        `_get`'s dict annotation does not describe)."""
+        return cast("list[dict] | None", self._get("/configuration/countries"))
+
     def fetch_person(self, person_id: int) -> dict | None:
-        """One person's bio + combined credits (E5 S6), in a single append_to_response request."""
-        return self._get(f"/person/{person_id}", {"append_to_response": "combined_credits"})
+        """One person's bio + combined credits (E5 S6) + the bio's translations (E30 S4), in a single
+        append_to_response request."""
+        return self._get(
+            f"/person/{person_id}", {"append_to_response": "combined_credits,translations"}
+        )
 
 
 def guid_to_tmdb_id(guid: str | None, media_type: str, tmdb: TmdbClient) -> int | None:
@@ -254,8 +266,12 @@ def parse_tmdb(payload: dict, media_type: str) -> dict:
             c.get("name") for c in (payload.get("production_companies") or []) if c.get("name")
         ][:8]
         or None,
+        # The ISO code beside TMDB's English name (E30): the client names the country in the reader's
+        # language from the code; the name is the fallback for a code it cannot name.
         "production_countries": [
-            c.get("name") for c in (payload.get("production_countries") or []) if c.get("name")
+            {"code": c.get("iso_3166_1") or None, "name": c["name"]}
+            for c in (payload.get("production_countries") or [])
+            if c.get("name")
         ]
         or None,
         "recommendations": recs or None,
@@ -301,8 +317,8 @@ def _link_people(db: Session, links: dict[str, int]) -> None:
 
 
 def enrich_batch(db: Session, tmdb: TmdbClient, limit: int) -> int:
-    """Enrich up to `limit` not-yet-TMDB-enriched titles (movies first, shows fill the remainder —
-    mirrors _enrich_people_batch). A transient TmdbError leaves the watermark NULL for retry; a
+    """Enrich up to `limit` not-yet-TMDB-enriched titles (movies first, shows fill the
+    remainder). A transient TmdbError leaves the watermark NULL for retry; a
     definitive no-match (unresolvable guid / TMDB 404) still stamps the watermark so it isn't re-fetched
     every run. One commit at the end. Returns the number processed (matched OR definitively unmatched)."""
     movies = (
@@ -356,13 +372,62 @@ def enrich_batch(db: Session, tmdb: TmdbClient, limit: int) -> int:
     return processed
 
 
+def _country(c: dict | str) -> dict:
+    """One stored production country as served: `{code, name}`. A row enriched before E30 stored the
+    bare English name; until `backfill_country_codes` reaches it, it serves with no code (the client
+    shows the name)."""
+    return c if isinstance(c, dict) else {"code": None, "name": c}
+
+
+def backfill_country_codes(db: Session, tmdb: TmdbClient) -> int:
+    """Give the countries stored before E30 (bare English names) their ISO codes, from TMDB's own
+    country list — the names came from that list, so they match it exactly. One request, and only
+    while such a row is left: re-fetching each title instead would take the enrichment batch days.
+    A name the list does not hold keeps no code. Returns the number of rows rewritten."""
+    stale = [
+        row
+        for model in (PlexItem, PlexShow)
+        for row in db.execute(
+            select(model).where(func.jsonb_typeof(model.production_countries[0]) == "string")
+        ).scalars()
+    ]
+    if not stale:
+        return 0
+    codes = {
+        c["english_name"]: c["iso_3166_1"]
+        for c in tmdb.countries() or []
+        if c.get("english_name") and c.get("iso_3166_1")
+    }
+    for row in stale:
+        row.production_countries = [
+            {"code": codes.get(c), "name": c} if isinstance(c, str) else c
+            for c in row.production_countries or []
+        ]
+    db.commit()
+    return len(stale)
+
+
 def run_enrich(db: Session) -> dict:
     """Scheduler entry point. No-op (never an error) when the TMDB key isn't configured."""
     if not sysconfig.get_str(db, "tmdb_api_key"):
         return {"enriched": 0, "skipped": "tmdb_api_key not set"}
     with TmdbClient(db) as tmdb:
+        coded = backfill_country_codes(db, tmdb)
         n = enrich_batch(db, tmdb, settings.tmdb_enrich_batch)
-    return {"enriched": n}
+    return {"enriched": n, **({"countries_coded": coded} if coded else {})}
+
+
+def run_people_enrich(db: Session) -> dict:
+    """Scheduler entry point of people_enrich (E30 S6): a batch of person bios (the most-credited
+    first) and a batch of portraits. Each half is a no-op — never an error — without its TMDB key /
+    without Plex."""
+    batch = settings.people_enrich_batch
+    if sysconfig.get_str(db, "tmdb_api_key"):
+        with TmdbClient(db) as tmdb:
+            bios = enrich_people_batch(db, tmdb, batch)
+    else:
+        bios = {"skipped": "tmdb_api_key not set"}
+    return {"bios": bios, "portraits": warm_portraits(db, batch)}
 
 
 def resolve_library_guids(
@@ -406,10 +471,11 @@ def resolve_library_guids(
     return movies, shows
 
 
-def resolve_recs(db: Session, recs: list[dict] | None) -> list[dict]:
+def resolve_recs(db: Session, recs: list[dict] | None, *, lang: str) -> list[dict]:
     """Tag each recommendation with whether it's in OUR library (matched by guid `tmdb:<id>`, bucketed
     by media_type — see resolve_library_guids) and, if so, its rating_key — so the client can deep-link
-    the ones we have and merely display the rest."""
+    the ones we have and merely display the rest. One we have is named as the library names it, in
+    `lang` (E30); one we lack keeps the title TMDB gave."""
     if not recs:
         return []
     movies, shows = resolve_library_guids(db, recs)
@@ -417,13 +483,19 @@ def resolve_recs(db: Session, recs: list[dict] | None) -> list[dict]:
     for r in recs:
         g = f"tmdb:{r.get('tmdb_id')}"
         row = shows.get(g) if r.get("media_type") == "tv" else movies.get(g)
+        named = {"title": display_title(row, lang)} if row is not None else {}
         out.append(
-            {**r, "in_library": row is not None, "rating_key": row.rating_key if row else None}
+            {
+                **r,
+                **named,
+                "in_library": row is not None,
+                "rating_key": row.rating_key if row else None,
+            }
         )
     return out
 
 
-def serve_block(db: Session, row) -> dict | None:
+def serve_block(db: Session, row, *, lang: str) -> dict | None:
     """The TMDB extras for a movie/show detail response, served from the row (no live TMDB call).
     None until the row has been TMDB-enriched (the client then shows nothing extra)."""
     if row.tmdb_enriched_at is None:
@@ -437,30 +509,58 @@ def serve_block(db: Session, row) -> dict | None:
         "keywords": row.keywords or [],
         "crew": row.crew or [],
         "studios": row.studios or [],
-        "production_countries": row.production_countries or [],
-        "recommendations": resolve_recs(db, row.recommendations),
+        "production_countries": [_country(c) for c in row.production_countries or []],
+        "recommendations": resolve_recs(db, row.recommendations, lang=lang),
         "backdrops": row.backdrops or [],
     }
 
 
 # --- Person enrichment (E5 S6) -------------------------------------------------------------------
-# A person's bio + birth facts + a "Known for" credit pool, fetched once (the first person-page open)
-# and served from the plex_people row. `known_for` stores the top combined-credits ids; the person
+# A person's bio + birth facts + a "Known for" credit pool, fetched once — by the people_enrich job, or
+# by the first person-page open if the job has not reached them yet — and served from the plex_people row. `known_for` stores the top combined-credits ids; the person
 # endpoint resolves them to library rows by guid at serve time (like recommendations).
 
-_KNOWN_FOR_MAX = 15
+# The candidate pool kept per person. Only the titles that are in the library are shown (at most
+# routes.plex.people._KNOWN_FOR_SHOWN), so the pool is deeper than the rail: a star's 15 most-voted
+# credits are often not the 15 a given library holds.
+_KNOWN_FOR_MAX = 40
+# TMDB genre ids of the shows a person visits as a guest (News, Reality, Talk). Ranked by popularity,
+# talk-show visits crowded out the films (Tom Cruise: 14 of 15 were talk shows; E30 S6).
+_GUEST_GENRES = {10763, 10764, 10767}
+# A credit in which the person plays themselves ("Self", "Himself - Guest", "Herself (archive footage)").
+_SELF_CREDIT = re.compile(r"^\s*(self|himself|herself|themselves)\b", re.IGNORECASE)
+# The crew jobs that make a title the person's own work (a director is known for what they directed).
+_KNOWN_FOR_CREW_JOBS = {"Director", "Creator"}
+
+
+def _known_for_credit(c: dict, crew: bool) -> bool:
+    if crew:
+        return c.get("job") in _KNOWN_FOR_CREW_JOBS
+    if _SELF_CREDIT.match(c.get("character") or ""):
+        return False
+    return not _GUEST_GENRES.intersection(c.get("genre_ids") or [])
 
 
 def parse_person(payload: dict) -> dict:
     """TMDB /person/{id} (+combined_credits) → the persisted bio fields. `known_for` = the person's
-    most-popular movie/tv credits (deduped by id), top `_KNOWN_FOR_MAX`, resolved to library later."""
-    credits = (payload.get("combined_credits") or {}).get("cast") or []
+    most-voted movie/tv credits — roles and directed works, not guest visits as themselves — deduped,
+    the top `_KNOWN_FOR_MAX`, resolved to library rows at serve time. Ranked by vote count, as TMDB's
+    own "Known for" is: popularity is this week's attention, which a talk-show visit wins."""
+    combined = payload.get("combined_credits") or {}
+    credits = [c for c in combined.get("cast") or [] if _known_for_credit(c, crew=False)] + [
+        c for c in combined.get("crew") or [] if _known_for_credit(c, crew=True)
+    ]
     # Dedup on (id, media_type), not the bare id: TMDB movie ids and tv ids are independent sequences
     # (id 603 can be both a movie and a show — see resolve_library_guids), so a same-id movie+show pair
     # is two distinct credits and both must survive.
     seen: set[tuple[int, str]] = set()
     known: list[dict] = []
-    for c in sorted(credits, key=lambda c: c.get("popularity") or 0, reverse=True):
+    ranked = sorted(
+        credits,
+        key=lambda c: (c.get("vote_count") or 0, c.get("popularity") or 0),
+        reverse=True,
+    )
+    for c in ranked:
         tid, mt = c.get("id"), c.get("media_type")
         if not tid or mt not in ("movie", "tv") or (tid, mt) in seen:
             continue
@@ -470,6 +570,7 @@ def parse_person(payload: dict) -> dict:
             break
     return {
         "biography": (payload.get("biography") or "").strip() or None,
+        "biography_hu": _translated_bio(payload, "hu"),
         "birthday": payload.get("birthday") or None,
         "deathday": payload.get("deathday") or None,
         "place_of_birth": payload.get("place_of_birth") or None,
@@ -479,8 +580,17 @@ def parse_person(payload: dict) -> dict:
     }
 
 
+def _translated_bio(payload: dict, lang: str) -> str | None:
+    """The `lang` biography from the appended `translations` (TMDB leaves an untranslated one blank)."""
+    for tr in (payload.get("translations") or {}).get("translations") or []:
+        if tr.get("iso_639_1") == lang:
+            return ((tr.get("data") or {}).get("biography") or "").strip() or None
+    return None
+
+
 def apply_person(row: PlexPerson, parsed: dict) -> None:
     row.biography = parsed["biography"]
+    row.biography_hu = parsed["biography_hu"]
     row.birthday = parsed["birthday"]
     row.deathday = parsed["deathday"]
     row.place_of_birth = parsed["place_of_birth"]
@@ -490,11 +600,22 @@ def apply_person(row: PlexPerson, parsed: dict) -> None:
     row.tmdb_enriched_at = datetime.now(timezone.utc)
 
 
+def _fetch_person_into(tmdb: TmdbClient, person: PlexPerson) -> None:
+    """Fetch one person from TMDB and write the row (not committed). A 404 (deleted person) stamps the
+    watermark with empty fields so it isn't fetched again. Raises TmdbError on a transient failure,
+    leaving the row untouched and `tmdb_enriched_at` NULL for a retry."""
+    payload = tmdb.fetch_person(cast(int, person.tmdb_person_id))
+    if payload is None:
+        person.tmdb_enriched_at = datetime.now(timezone.utc)
+    else:
+        apply_person(person, parse_person(payload))
+
+
 def enrich_person(db: Session, person: PlexPerson) -> bool:
-    """Lazily fetch + persist one person's TMDB bio (first person-page open), committing the write so it
-    survives regardless of the read path. No-op (False) without a key or a `tmdb_person_id`; a transient
-    error leaves `tmdb_enriched_at` NULL so the next open retries. A 404 (deleted person) stamps the
-    watermark with empty fields so we don't refetch it every open."""
+    """Lazily fetch + persist one person's TMDB bio (a person page opened before the background job
+    reached them), committing the write so it survives regardless of the read path. No-op (False)
+    without a key or a `tmdb_person_id`; a transient error leaves `tmdb_enriched_at` NULL so the next
+    open retries."""
     if not person.tmdb_person_id or not sysconfig.get_str(db, "tmdb_api_key"):
         return False
     try:
@@ -502,7 +623,7 @@ def enrich_person(db: Session, person: PlexPerson) -> bool:
         # longer blocks a serve; still cap the outbound TMDB call with a short timeout so a hanging TMDB
         # doesn't tie up a threadpool worker for the default 30s.
         with TmdbClient(db, timeout=8.0) as tmdb:
-            payload = tmdb.fetch_person(person.tmdb_person_id)
+            _fetch_person_into(tmdb, person)
     except TmdbError as exc:
         # False leaves the person un-enriched and unstamped, so it is retried — but the page in
         # front of the user right now shows an empty biography with nothing to say why.
@@ -515,9 +636,41 @@ def enrich_person(db: Session, person: PlexPerson) -> bool:
             ),
         )
         return False
-    if payload is None:
-        person.tmdb_enriched_at = datetime.now(timezone.utc)
-    else:
-        apply_person(person, parse_person(payload))
     db.commit()
     return True
+
+
+# Lookups failing this many people in a row end a people batch: TMDB itself is degraded, and hammering
+# it helps nobody. One person failing alone is skipped, so an id TMDB keeps refusing never stalls the rest.
+_PEOPLE_FAILS_IN_A_ROW = 3
+
+
+def enrich_people_batch(db: Session, tmdb: TmdbClient, limit: int) -> dict:
+    """Fetch up to `limit` linked, not-yet-enriched people (E30 S6), the most-credited first, so a
+    person page reads its bio from the row instead of waiting on TMDB. Each person is committed as it
+    lands: a page open during the run already sees it. A failed lookup is skipped (left unstamped for the
+    next run); _PEOPLE_FAILS_IN_A_ROW of them in a row end the batch."""
+    ids = people_by_credits(db, "bio", limit)
+    done = failed = in_a_row = 0
+    for pid in ids:
+        if in_a_row >= _PEOPLE_FAILS_IN_A_ROW:
+            break
+        person = db.get(PlexPerson, pid)
+        # A page open may have enriched this person since the select: skip, don't fetch twice.
+        if person is None or person.tmdb_enriched_at is not None:
+            continue
+        try:
+            _fetch_person_into(tmdb, person)
+        except TmdbError as exc:
+            db.rollback()
+            failed, in_a_row = failed + 1, in_a_row + 1
+            log.warning(
+                "a TMDB person lookup in the batch failed",
+                extra=logs.event(
+                    "plex.tmdb.people_batch_failed", person_id=pid, reason=type(exc).__name__
+                ),
+            )
+            continue
+        db.commit()
+        done, in_a_row = done + 1, 0
+    return {"enriched": done, **({"failed": failed} if failed else {})}

backend/app/progress.py

@@ -24,6 +24,19 @@ def report(current: int, total: int | None = None, phase: str | None = None) ->
         sink(current, total, phase)
 
 
+class JobFailed(RuntimeError):
+    """A job's own failure, said so the reader's language can name it (E31): the client reads
+    `scheduler.failure.<reason>` and interpolates `params` (keep them to values the reader may see —
+    numbers, ids, short codes). The message is the English line the log and `last_error` keep. An
+    upstream's own error (a timeout, a refused connection) is not one of these: it stays as raised,
+    being diagnostic."""
+
+    def __init__(self, reason: str, message: str, **params: object):
+        super().__init__(message)
+        self.reason = reason
+        self.params = params
+
+
 class bind:
     """Context manager that binds a progress sink for the duration of a job run."""
 

backend/app/routes/_common.py

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

backend/app/routes/admin.py

@@ -834,7 +834,11 @@ def reset_demo(admin: User = Depends(admin_user), db: Session = Depends(get_db))
     demo = get_or_create_demo_user(db)
     seeded = reset_demo_state(db, demo)
     audit.record(
-        db, admin.id, AuditAction.DEMO_RESET, summary=f"{seeded} sample playlists re-seeded"
+        db,
+        admin.id,
+        AuditAction.DEMO_RESET,
+        summary=f"{seeded} sample playlists re-seeded",
+        after={"playlists_seeded": seeded},  # the count as data: named in the reader's language
     )
     db.commit()
     return {"ok": True, "reset": True, "playlists_seeded": seeded}

backend/app/routes/audit.py

@@ -66,6 +66,12 @@ def list_audit(
 def clear_audit(admin: User = Depends(admin_user), db: Session = Depends(get_db)) -> dict:
     """Clear the audit log. Leaves ONE row recording who cleared it + how many (tamper-evidence)."""
     n = db.execute(delete(AuditLog)).rowcount or 0
-    audit.record(db, admin.id, AuditAction.AUDIT_CLEAR, summary=f"Cleared {n} audit entries")
+    audit.record(
+        db,
+        admin.id,
+        AuditAction.AUDIT_CLEAR,
+        summary=f"Cleared {n} audit entries",
+        after={"cleared": n},  # the count as data: the log names it in the reader's language
+    )
     db.commit()
     return {"ok": True, "cleared": n}

backend/app/routes/channels.py

@@ -6,9 +6,11 @@ from datetime import datetime, timezone
 
 from fastapi import APIRouter, BackgroundTasks, Depends
 from pydantic import BaseModel
-from sqlalchemy import func, select, update
+from sqlalchemy import Select, func, select, update
 from sqlalchemy.orm import Session
 
+from app.collation import collated, sorted_words
+from app.mailtext import lang_for_user
 from app import logs, quota
 from app.auth import admin_user, current_user, require_human, require_write_scope
 from app.db import get_db
@@ -28,7 +30,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
@@ -38,33 +40,40 @@ router = APIRouter(prefix="/api/channels", tags=["channels"])
 log = logs.get_logger(__name__)
 
 
+def channel_aggregates(channel_ids: list[str]) -> Select:
+    """Per-channel stored count, last upload and total duration, in one grouped pass. Every column it
+    reads is in `ix_videos_channel_pub_cover` (migration 0095), so Postgres answers it from the index
+    alone; a test holds that (test_channel_list_index_only)."""
+    return (
+        select(
+            Video.channel_id,
+            func.count(Video.id),
+            func.max(Video.published_at),
+            func.coalesce(func.sum(Video.duration_seconds), 0),
+        )
+        .where(Video.channel_id.in_(channel_ids))
+        .group_by(Video.channel_id)
+    )
+
+
 @router.get("")
 def list_channels(user: User = Depends(current_user), db: Session = Depends(get_db)) -> list[dict]:
     rows = db.execute(
         select(Subscription, Channel)
         .join(Channel, Channel.id == Subscription.channel_id)
         .where(Subscription.user_id == user.id)
-        .order_by(Subscription.priority.desc(), func.lower(Channel.title))
+        .order_by(Subscription.priority.desc(), collated(Channel.title, lang_for_user(user)))
     ).all()
 
-    # Per-channel aggregates over the shared catalog in ONE grouped pass: stored count, last
-    # upload, total duration. Cheap — a single grouped scan, so computed on read rather than
-    # denormalised (measure-first: reads aren't frequent/hot enough to warrant cached columns).
+    # Per-channel aggregates over the shared catalog (channel_aggregates), computed on read rather than
+    # denormalised: an Index Only Scan over a ~20 MB index, where it used to read every video's heap page
+    # (681 MB on prod, a 2–6 s first open once something else had pushed it out of memory, E31 S4d).
     # (The Normal/Shorts/Live breakdown moved to the channel-detail page in R14, so it is no longer
     # computed here — the manager table dropped its N/S/L column.)
     channel_ids = [c.id for _, c in rows]
     agg: dict[str, dict] = {}
     if channel_ids:
-        for cid, n, last_up, total_dur in db.execute(
-            select(
-                Video.channel_id,
-                func.count(Video.id),
-                func.max(Video.published_at),
-                func.coalesce(func.sum(Video.duration_seconds), 0),
-            )
-            .where(Video.channel_id.in_(channel_ids))
-            .group_by(Video.channel_id)
-        ).all():
+        for cid, n, last_up, total_dur in db.execute(channel_aggregates(channel_ids)).all():
             agg[cid] = {
                 "stored": n,
                 "last_video_at": iso(last_up),
@@ -139,7 +148,7 @@ def _discovery_rows(db: Session, user: User) -> list:
     return db.execute(
         q.group_by(Channel.id).order_by(
             func.count(func.distinct(PlaylistItem.video_id)).desc(),
-            func.lower(Channel.title),
+            collated(Channel.title, lang_for_user(user)),
         )
     ).all()
 
@@ -190,12 +199,16 @@ 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).
+            # Match _discovery_rows' ORDER BY exactly: video-count DESC, then title in the reader's
+            # alphabet (NULLs LAST, as Postgres orders them — coercing NULL→"" would wrongly float
+            # untitled channels up).
+            titles = [r[0].title for r in rows if r[0].title is not None]
+            alpha = {w: i for i, w in enumerate(sorted_words(db, titles, lang_for_user(user)))}
             rows = sorted(
-                rows, key=lambda r: (-int(r[1]), r[0].title is None, (r[0].title or "").lower())
+                rows,
+                key=lambda r: (-int(r[1]), r[0].title is None, alpha.get(r[0].title or "", 0)),
             )
         except YouTubeError as exc:
             log.warning(
@@ -296,17 +309,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 +428,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 +604,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",
@@ -658,7 +672,7 @@ def list_blocked(user: User = Depends(current_user), db: Session = Depends(get_d
             select(Channel)
             .join(BlockedChannel, BlockedChannel.channel_id == Channel.id)
             .where(BlockedChannel.user_id == user.id)
-            .order_by(func.lower(Channel.title))
+            .order_by(collated(Channel.title, lang_for_user(user)))
         )
         .scalars()
         .all()

backend/app/routes/discover.py

@@ -23,6 +23,7 @@ from app.discover import hero as hero_mod
 from app.discover import pins, rails
 from app.discover.budget import Budget, DEFAULT_BUDGET
 from app.models import ComfortPin, User
+from app.plex.cards import norm_lang
 from app.routes._common import owned_or_404, not_found
 
 router = APIRouter(prefix="/api/discover", tags=["discover"])
@@ -45,6 +46,7 @@ class ReorderIn(BaseModel):
 def get_discover(
     budget: Budget = DEFAULT_BUDGET,
     seed: int = 0,
+    lang: str = "en",
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
@@ -52,13 +54,14 @@ def get_discover(
 
     `resume` and `shelf` are built once and handed to the hero, so the two rails the hero draws from
     are not queried twice for a single page load."""
-    resume = rails.continue_watching(db, user)
+    lang = norm_lang(lang)
+    resume = rails.continue_watching(db, user, lang=lang)
     # Plex off → the shelf rail (and so the hero's comfort tier) goes YouTube-only like the rails
     # beside it; the pins are kept and `GET /pins` still lists them (`pins.shelf`).
-    shelf = pins.shelf(db, user, include_plex=rails.plex_available(db))
+    shelf = pins.shelf(db, user, include_plex=rails.plex_available(db), lang=lang)
     return {
         "budget": budget,
-        "hero": hero_mod.pick(db, user, budget, seed, resume=resume, shelf=shelf),
+        "hero": hero_mod.pick(db, user, budget, seed, resume=resume, shelf=shelf, lang=lang),
         "continue_watching": resume,
         "comfort": shelf,
     }
@@ -80,6 +83,7 @@ def get_pick(
     seed: int = 0,
     exclude: str = "",
     start: int = 0,
+    lang: str = "en",
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
@@ -99,18 +103,25 @@ def get_pick(
     return {
         "budget": budget,
         "hero": hero_mod.pick(
-            db, user, budget, seed, exclude=set(list(skip)[:MAX_EXCLUDE]), start=start
+            db,
+            user,
+            budget,
+            seed,
+            exclude=set(list(skip)[:MAX_EXCLUDE]),
+            start=start,
+            lang=norm_lang(lang),
         ),
     }
 
 
 @router.get("/pins")
 def list_pins(
+    lang: str = "en",
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
     """The shelf on its own — for the shelf editor, which needs it without the rest of the page."""
-    return {"items": pins.shelf(db, user)}
+    return {"items": pins.shelf(db, user, lang=norm_lang(lang))}
 
 
 @router.post("/pins")

backend/app/routes/downloads.py

@@ -21,6 +21,8 @@ from pydantic import BaseModel
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
+from app.mailtext import lang_for_user
+from app.collation import collated
 from app import audit, sysconfig
 from app.auth import admin_user, require_human
 from app.config import settings
@@ -917,7 +919,14 @@ def share_download(
             user_id=recipient.id,
             type="download_shared",
             title=(job.display_name or "A download") + " was shared with you",
-            data={"kind": "download_shared", "from": user.email, "job_id": job_id},
+            # The client names the notice in the reader's language from `data` (E30); the title is the
+            # English fallback only.
+            data={
+                "kind": "download_shared",
+                "from": user.email,
+                "job_id": job_id,
+                "title": job.display_name,
+            },
             commit=False,
         )
         db.commit()
@@ -981,7 +990,7 @@ def share_recipients(
         db.execute(
             select(User)
             .where(User.id != user.id, *messageable_clauses())
-            .order_by(func.lower(User.email))
+            .order_by(collated(User.email, lang_for_user(user)))
         )
         .scalars()
         .all()

backend/app/routes/feed.py

@@ -10,6 +10,7 @@ from sqlalchemy.orm.exc import StaleDataError
 from app import quota
 from app.auth import current_user
 from app.db import get_db
+from app.mailtext import lang_for_user
 from app.feedquery import (
     decode_cursor,
     encode_cursor,
@@ -18,8 +19,11 @@ from app.feedquery import (
     filtered_query,
     keyset_predicate,
     order_by,
+    rank_window_start,
     serialize,
     sort_keys,
+    windowed_rank,
+    windowed_relevance_rows,
 )
 from app.models import (
     POSITION_MAX_S,
@@ -108,30 +112,45 @@ def get_feed(
     db: Session = Depends(get_db),
 ) -> dict:
     query, rank_expr = filtered_query(db, user, **params)
-    keys = sort_keys(sort, seed, rank_expr)
-
-    # Expose each key column on the row so we can build the next cursor from the last item.
-    query = query.add_columns(*[k["expr"].label(f"_k{i}") for i, k in enumerate(keys)])
-    query = query.order_by(*order_by(keys))
+    lang = lang_for_user(user)
+    keys = sort_keys(sort, seed, rank_expr, lang)
 
+    vals, cursor_id, window = None, None, None
     if cursor:
         # The read-model raises a plain ValueError on a malformed cursor; translate it to the
         # HTTP 400 here so feedquery stays web-framework-free.
         try:
-            vals, cursor_id = decode_cursor(keys, cursor)
+            vals, cursor_id, window = decode_cursor(keys, cursor)
         except ValueError:
             # `from None`: the ValueError is an expected bad-input signal, not an error to chain.
             raise refused(400, "invalid_cursor") from None
+    ranked = sort == "relevance" and rank_expr is not None
+    if ranked and not cursor:
+        window = rank_window_start(db, query)
+    if ranked and window is not None:
+        keys = sort_keys(sort, seed, windowed_rank(rank_expr, window), lang)
+
+    # Expose each key column on the row so we can build the next cursor from the last item.
+    query = query.add_columns(*[k["expr"].label(f"_k{i}") for i, k in enumerate(keys)])
+    if vals is not None:
         for k, v in zip(keys, vals):
             k["value"] = v
-        query = query.where(keyset_predicate(keys, cursor_id))
-
-    rows = db.execute(query.limit(limit + 1)).all()
+    if ranked and window is not None:
+        rows = windowed_relevance_rows(db, query, keys, window, cursor_id, limit + 1)
+    else:
+        query = query.order_by(*order_by(keys))
+        if cursor_id is not None:
+            query = query.where(keyset_predicate(keys, cursor_id))
+        rows = db.execute(query.limit(limit + 1)).all()
     has_more = len(rows) > limit
     page = rows[:limit]
     return {
         "items": [serialize(r) for r in page],
-        "next_cursor": encode_cursor(keys, page[-1]) if (has_more and page) else None,
+        "next_cursor": (
+            encode_cursor(keys, page[-1], window if ranked else None)
+            if (has_more and page)
+            else None
+        ),
         "has_more": has_more,
         "limit": limit,
     }

backend/app/routes/messages.py

@@ -21,6 +21,8 @@ from pydantic import BaseModel
 from sqlalchemy import and_, case, delete, func, or_, select
 from sqlalchemy.orm import Session
 
+from app.mailtext import lang_for_user
+from app.collation import collated
 from app.auth import require_human, resolved_user_id
 from app.db import SessionLocal, get_db
 from app.models import Message, MessageKey, User
@@ -92,13 +94,31 @@ def _system_partner() -> dict:
     return {"id": SYSTEM_PARTNER_ID, "name": SYSTEM_NAME, "avatar_url": None}
 
 
-def _serialize_msg(m: Message) -> dict:
+# The welcome's opening line in every language — how a stored copy is recognised. It was rendered
+# once, in the language of the day it was created, so an account that later switched language kept
+# reading it in the old one (E31 S1: the owner's, in English). Recognised here, it is served in the
+# reader's language instead. Derived from WELCOME itself, so a change to an OPENING line, or a
+# language taken out of WELCOME, orphans the copies already stored: they are served as stored. The
+# one retired language (German, 2026-07) left none on prod (checked 2026-10-02).
+_WELCOME_OPENINGS = {text.partition("\n")[0] for text in WELCOME.values()}
+
+
+def _system_body(body: str | None, lang: str | None) -> str | None:
+    """A system message's text for a reader of `lang`: the welcome in their language, any other as
+    stored."""
+    if body is None or lang is None or body.partition("\n")[0] not in _WELCOME_OPENINGS:
+        return body
+    return WELCOME.get(lang, WELCOME["en"])
+
+
+def _serialize_msg(m: Message, lang: str | None = None) -> dict:
+    """`lang`: the reader's language, for a system message's text (a user message is ciphertext)."""
     return {
         "id": m.id,
         "kind": m.kind,
         "sender_id": m.sender_id,
         "recipient_id": m.recipient_id,
-        "body": m.body,  # only set for system messages
+        "body": _system_body(m.body, lang) if m.kind == "system" else m.body,
         "ciphertext": m.ciphertext,
         "iv": m.iv,
         "read_at": iso(m.read_at),
@@ -122,7 +142,7 @@ def ensure_welcome(db: Session, user: User) -> None:
     db.add(m)
     db.commit()
     db.refresh(m)
-    manager.push(user.id, {"type": "message", "message": _serialize_msg(m)})
+    manager.push(user.id, {"type": "message", "message": _serialize_msg(m, lang_for_user(user))})
 
 
 # --- E2EE key directory / blob store -----------------------------------------
@@ -246,7 +266,7 @@ def list_recipients(
             select(User)
             .join(MessageKey, MessageKey.user_id == User.id)
             .where(User.id != user.id, *messageable_clauses())
-            .order_by(func.lower(func.coalesce(User.display_name, User.email)))
+            .order_by(collated(func.coalesce(User.display_name, User.email), lang_for_user(user)))
         )
         .scalars()
         .all()
@@ -311,7 +331,7 @@ def list_conversations(user: User = Depends(require_human), db: Session = Depend
         items.append(
             {
                 "partner": partner,
-                "last_message": _serialize_msg(m),
+                "last_message": _serialize_msg(m, lang_for_user(user)),
                 "unread": int(unread.get(pid, 0)),
             }
         )
@@ -364,7 +384,7 @@ def get_thread(
             # refreshes live instead of waiting for the next 20s poll. The client re-fetches the
             # count on this signal, so no number is carried here.
             manager.push(user.id, {"type": "unread"})
-    return {"partner": partner, "items": [_serialize_msg(m) for m in msgs]}
+    return {"partner": partner, "items": [_serialize_msg(m, lang_for_user(user)) for m in msgs]}
 
 
 @router.post("")

backend/app/routes/playlists.py

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

backend/app/routes/plex/_shared.py

@@ -4,6 +4,7 @@ from sqlalchemy.orm import Session
 
 from app import logs
 from app.models import PlexItem
+from app.plex.cards import norm_lang as _norm_lang  # noqa: F401 — the package's historic name
 from app.plex.lookups import by_rating_key
 from app.routes._common import not_found
 
@@ -15,8 +16,3 @@ def item_or_404(db: Session, rating_key: str) -> PlexItem:
     if it is None:
         raise not_found("plex_item")
     return it
-
-
-def _norm_lang(lang: str | None) -> str:
-    """The overlay has an EN base + an optional HU twin; anything other than `hu` serves EN."""
-    return "hu" if lang == "hu" else "en"

backend/app/routes/plex/browse.py

@@ -10,10 +10,13 @@ from sqlalchemy import (
     func,
     literal,
     null,
+    or_,
     select,
 )
 from sqlalchemy.orm import Session, aliased
 
+from app.mailtext import lang_for_user
+from app.collation import collated, sorted_words
 from app import sysconfig
 from app.auth import current_user
 from app.db import get_db
@@ -25,7 +28,7 @@ from app.models import (
     User,
 )
 from app.plex import rollup
-from app.plex.cards import episode_card
+from app.plex.cards import display_title, episode_card
 from app.plex.query import (
     FIELD_COLUMNS,
     PLAYBACK_CLASSES,
@@ -54,14 +57,15 @@ from app.utils import to_tsquery_str
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
 
-def sort_column(u, sort: str):
+def sort_column(u, sort: str, lang: str = "en"):
     """The browse grid's sort key -> orderable column on the union subquery. Module-level (not inline
     in the handler) so a test can pin its vocabulary to `PLEX_SORT_KEYS` — a key the Sort control
     offers but this cannot order would quietly fall back to `added_at` and look like a broken control.
-    An unknown key (a stale bookmark, a hand-edited URL) deliberately keeps that fallback."""
+    An unknown key (a stale bookmark, a hand-edited URL) deliberately keeps that fallback. The title sorts
+    in the reader's alphabet (`collation`)."""
     return {
         "added": u.c.added_at,
-        "title": func.lower(u.c.title),
+        "title": collated(u.c.title, lang),
         "year": u.c.year,
         "rating": u.c.rating,
         "duration": u.c.duration_s,
@@ -78,7 +82,7 @@ def list_libraries(user: User = Depends(current_user), db: Session = Depends(get
         db.execute(
             select(PlexLibrary)
             .where(PlexLibrary.overlay_of.is_(None))
-            .order_by(PlexLibrary.kind.desc(), PlexLibrary.title)
+            .order_by(PlexLibrary.kind.desc(), collated(PlexLibrary.title, lang_for_user(user)))
         )
         .scalars()
         .all()
@@ -237,7 +241,7 @@ def unified_library(
         if tsq is not None:
             order = [u.c.rank.desc()]
         else:
-            col = sort_column(u, sort)
+            col = sort_column(u, sort, lang)
             order = [(col.asc() if sort_dir == "asc" else col.desc()).nullslast()]
         order.append(u.c.rk.desc())
         rows = db.execute(select(u).order_by(*order).offset(offset).limit(limit)).all()
@@ -281,26 +285,32 @@ def unified_library(
     episodes = []
     if tsq is not None and want_shows and field in ("all", "episode"):
         ep_st = aliased(PlexState)
-        ep_vec = (
-            func.to_tsvector(TS_CONFIG, func.coalesce(PlexItem.title, ""))
-            if field == "episode"
-            else PlexItem.search_vector
-        )
+        # In HU an episode is found by its Hungarian title too (E30: the overlay now fills it) — and
+        # still by its English one, like `vector_match` does for the grid.
+        if field == "episode":
+            ep_vec = func.to_tsvector(TS_CONFIG, func.coalesce(PlexItem.title, ""))
+            ep_vec_hu = func.to_tsvector(TS_CONFIG, func.coalesce(PlexItem.title_hu, ""))
+        else:
+            ep_vec, ep_vec_hu = PlexItem.search_vector, PlexItem.search_vector_hu
+        hit = ep_vec.op("@@")(tsq)
+        if lang == "hu":
+            hit = or_(ep_vec_hu.op("@@")(tsq), hit)
+            ep_vec = ep_vec_hu
         eps = db.execute(
-            select(PlexItem, ep_st, PlexShow.title.label("show_title"))
+            select(PlexItem, ep_st, PlexShow)
             .outerjoin(ep_st, and_(ep_st.item_id == PlexItem.id, ep_st.user_id == user.id))
             .outerjoin(PlexShow, PlexShow.id == PlexItem.show_id)
             .where(
                 PlexItem.kind == "episode",
                 PlexItem.library_id.in_(show_lib_ids),
-                ep_vec.op("@@")(tsq),
+                hit,
             )
             .order_by(func.ts_rank(ep_vec, tsq).desc())
             .limit(24)
         ).all()
-        for e, s, show_title in eps:
-            card = episode_card(e, s)
-            card["show_title"] = show_title
+        for e, s, sh in eps:
+            card = episode_card(e, s, lang=lang)
+            card["show_title"] = display_title(sh, lang) if sh is not None else None
             episodes.append(card)
 
     return {
@@ -348,6 +358,24 @@ def facets(
 
     uid = user.id
 
+    # The shows that pass the watch-state scope, asked ONCE. The per-user episode rollup behind it is a
+    # full pass over the user's episodes (~10 ms on a prod-sized library), and each of the show groups
+    # (genres, ratings, studios, years, rating max) asked it again: half of a filtered facets call
+    # (E31 S4e). The same filter on the same rows, so the counts do not change
+    # (test_plex_facets_grid_parity).
+    shows_in_scope: list[int] | None = None
+    if show_ids and show in ("watched", "in_progress", "unwatched"):
+        agg = rollup.agg_subquery(db, uid).subquery()
+        in_scope = select(PlexShow.id).outerjoin(agg, agg.c.show_id == PlexShow.id)
+        in_scope = apply_show_state_filter(
+            in_scope,
+            func.coalesce(agg.c.total, 0),
+            func.coalesce(agg.c.watched, 0),
+            func.coalesce(agg.c.inprog, 0),
+            show,
+        )
+        shows_in_scope = list(db.scalars(in_scope.where(PlexShow.library_id.in_(show_ids))))
+
     def wsq(query, model, ids, pp, kind_movie, with_dur):
         """Apply the (self-excluded) metadata filters + library scope + the per-user watch-state to a
         facet aggregation query, so the facets reflect exactly the visible result set."""
@@ -366,14 +394,8 @@ def facets(
             st = aliased(PlexState)
             query = query.outerjoin(st, and_(st.item_id == model.id, st.user_id == uid))
             query = apply_movie_state_filter(query, st, show)
-        else:
-            if show in ("watched", "in_progress", "unwatched"):
-                agg = rollup.agg_subquery(db, uid).subquery()
-                query = query.outerjoin(agg, agg.c.show_id == model.id)
-                tot = func.coalesce(agg.c.total, 0)
-                wat = func.coalesce(agg.c.watched, 0)
-                inp = func.coalesce(agg.c.inprog, 0)
-                query = apply_show_state_filter(query, tot, wat, inp, show)
+        elif shows_in_scope is not None:
+            query = query.where(model.id.in_(shows_in_scope))
         return query
 
     genre_counts: dict[str, int] = {}
@@ -523,16 +545,19 @@ def facets(
     for c in split_csv(f.playable):
         if c in PLAYBACK_CLASSES:
             playable_counts.setdefault(c, 0)
+    # Names in the reader's alphabet: the genres are Hungarian words for a Hungarian reader (E30 S1).
+    alpha = {w: i for i, w in enumerate(sorted_words(db, [*genre_counts, *studio_counts], lang))}
     return {
         "genres": [
-            {"value": g, "count": c} for g, c in sorted(genre_counts.items(), key=lambda kv: kv[0])
+            {"value": g, "count": c}
+            for g, c in sorted(genre_counts.items(), key=lambda kv: alpha[kv[0]])
         ],
         "content_ratings": [
             {"value": cr, "count": c} for cr, c in sorted(cr_counts.items(), key=lambda kv: -kv[1])
         ],
         "studios": [
             {"value": s, "count": c}
-            for s, c in sorted(studio_counts.items(), key=lambda kv: (-kv[1], kv[0]))
+            for s, c in sorted(studio_counts.items(), key=lambda kv: (-kv[1], alpha[kv[0]]))
         ],
         # Fixed good→heavy order (not by count), so the class list reads as a severity scale.
         "playable": [

backend/app/routes/plex/collections.py

@@ -9,6 +9,8 @@ from pydantic import BaseModel
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
+from app.mailtext import lang_for_user
+from app.collation import collated, sorted_words
 from app import logs
 from app.auth import admin_user, current_user
 from app.db import get_db
@@ -22,10 +24,10 @@ from app.models import (
 )
 from app.plex import rollup
 from app.plex import sync as plex_sync
-from app.plex.cards import movie_card, show_card
+from app.plex.cards import display_title, movie_card, norm_lang, show_card
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.plex.lookups import by_rating_key
-from app.plex.query import content_libs, runtime_by_key, top_art_keys
+from app.plex.query import content_libs, runtime_by_key, title_col, top_art_keys
 from app.utils import like_escape
 from app.refusal import refused
 from app.routes._common import not_found
@@ -142,7 +144,7 @@ def collections(
         db.execute(
             query.order_by(
                 PlexCollection.child_count.desc().nullslast(),
-                func.lower(PlexCollection.title),
+                collated(PlexCollection.title, lang_for_user(user)),
             )
         )
         .scalars()
@@ -208,16 +210,24 @@ MEMBER_SORT_KEYS: dict[str, Callable[[Member], Any]] = {
 DEFAULT_MEMBER_SORT = "year"
 
 
-def sort_members(members: list[Member], sort: str, sort_dir: str) -> list[Member]:
+def sort_members(
+    members: list[Member], sort: str, sort_dir: str, alpha: dict[str, int] | None = None
+) -> list[Member]:
     """Order a collection's members by one of `PLEX_SORT_KEYS`.
 
     Two properties worth stating because they are easy to get wrong with a plain `reverse=True`:
     members with no value for the key sink to the END in BOTH directions (matching the browse grid's
     `nullslast()` — a movie with no rating is not "the worst rated"), and ties always resolve
     title-ascending, so flipping the direction reverses the ranking rather than the alphabet inside
-    it. An unknown key falls back to the page's default instead of returning an arbitrary order."""
+    it. An unknown key falls back to the page's default instead of returning an arbitrary order.
+
+    `alpha` ranks each title in the reader's alphabet (`collation.sorted_words`); without it, titles
+    compare as Python strings, which puts every accented initial after "z"."""
+    by_title = (lambda m: alpha[m.title]) if alpha is not None else (lambda m: m.title)
     key = MEMBER_SORT_KEYS.get(sort, MEMBER_SORT_KEYS[DEFAULT_MEMBER_SORT])
-    ordered = sorted(members, key=lambda m: m.title)  # stable secondary, applied first
+    if key is MEMBER_SORT_KEYS["title"]:
+        key = by_title
+    ordered = sorted(members, key=by_title)  # stable secondary, applied first
     have = [m for m in ordered if key(m) is not None]
     missing = [m for m in ordered if key(m) is None]
     have.sort(key=key, reverse=sort_dir != "asc")
@@ -229,6 +239,7 @@ def collection_detail(
     rating_key: str,
     sort: str = DEFAULT_MEMBER_SORT,
     sort_dir: str = "asc",
+    lang: str = "en",
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
@@ -237,6 +248,7 @@ def collection_detail(
     control means the same thing on both surfaces; the default is release year ascending, which is
     what this page did before it had a control. Read-only here; edits go through the admin mutation
     endpoints below."""
+    lang = norm_lang(lang)
     col = by_rating_key(db, PlexCollection, rating_key)
     if col is None:
         raise not_found("collection")
@@ -244,7 +256,7 @@ def collection_detail(
         db.execute(
             select(PlexItem)
             .where(PlexItem.kind == "movie", PlexItem.collection_keys.contains([rating_key]))
-            .order_by(PlexItem.year.asc().nullslast(), func.lower(PlexItem.title))
+            .order_by(PlexItem.year.asc().nullslast(), collated(title_col(PlexItem, lang), lang))
         )
         .scalars()
         .all()
@@ -253,7 +265,7 @@ def collection_detail(
         db.execute(
             select(PlexShow)
             .where(PlexShow.collection_keys.contains([rating_key]))
-            .order_by(PlexShow.year.asc().nullslast(), func.lower(PlexShow.title))
+            .order_by(PlexShow.year.asc().nullslast(), collated(title_col(PlexShow, lang), lang))
         )
         .scalars()
         .all()
@@ -285,7 +297,7 @@ def collection_detail(
         Member(
             kind="movie",
             obj=m,
-            title=(m.title or "").lower(),
+            title=display_title(m, lang).lower(),
             year=m.year,
             rating=m.rating,
             added=m.added_at,
@@ -298,7 +310,7 @@ def collection_detail(
         Member(
             kind="show",
             obj=sh,
-            title=(sh.title or "").lower(),
+            title=display_title(sh, lang).lower(),
             year=sh.year,
             rating=sh.rating,
             added=sh.added_at,
@@ -308,11 +320,12 @@ def collection_detail(
         )
         for sh in shows
     ]
-    members = sort_members(members, sort, sort_dir)
+    alpha = {w: i for i, w in enumerate(sorted_words(db, [m.title for m in members], lang))}
+    members = sort_members(members, sort, sort_dir, alpha)
     items = [
-        movie_card(m.obj, mstate.get(m.obj.id))
+        movie_card(m.obj, mstate.get(m.obj.id), lang=lang)
         if m.kind == "movie"
-        else show_card(m.obj, sstate.get(m.obj.id, "new"))
+        else show_card(m.obj, sstate.get(m.obj.id, "new"), lang=lang)
         for m in members
     ]
     years = [m.year for m in members if m.year is not None]

backend/app/routes/plex/detail.py

@@ -1,14 +1,16 @@
 """Plex show/item detail: the show drill-down + the per-item player payload (markers, cast, nav)."""
 
+import re
 import threading
 import time
 from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timezone
 
 from fastapi import APIRouter, Depends
-from sqlalchemy import func, select
+from sqlalchemy import select
 from sqlalchemy.orm import Session
 
+from app.collation import collated, sorted_words
 from app import logs
 from app.auth import current_user
 from app.db import get_db
@@ -24,6 +26,7 @@ from app.models import (
 from app.plex import detail as plex_detail
 from app.plex import people as plex_people
 from app.plex import rollup, subtitles
+from app.plex.query import title_col
 from app.plex import tmdb as plex_tmdb
 from app.plex.cards import episode_card, movie_card, show_card
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
@@ -107,7 +110,8 @@ def show_detail(
     db: Session = Depends(get_db),
 ) -> dict:
     """A show's seasons + episodes (the drill-down view) with per-user watch state."""
-    hu = _norm_lang(lang) == "hu"
+    lang = _norm_lang(lang)
+    hu = lang == "hu"
     sh = by_rating_key(db, PlexShow, rating_key)
     if sh is None:
         raise not_found("show")
@@ -144,7 +148,7 @@ def show_detail(
     by_season: dict[int | None, list] = {}
     all_cards: list[dict] = []  # every episode, in season/episode order → show-level rollup
     for e in eps:
-        card = episode_card(e, states.get(e.id))
+        card = episode_card(e, states.get(e.id), lang=lang)
         by_season.setdefault(e.season_id, []).append(card)
         all_cards.append(card)
     show_roll = rollup.rollup(all_cards)
@@ -156,7 +160,7 @@ def show_detail(
     related: list[dict] = []
     try:
         meta, related_raw = _show_enrichment(db, sh.rating_key)
-        related = _relatedshow_cards(db, user.id, related_raw, exclude=sh.id)
+        related = _relatedshow_cards(db, user.id, related_raw, exclude=sh.id, lang=lang)
         if sh.people_enriched_at is None and meta:
             plex_people.enrich_row_people(db, sh, plex_people.cast_from_meta(meta))
             plex_detail.apply_rich_detail(sh, meta)  # imdb/tagline/full_cast for future views
@@ -210,7 +214,7 @@ def show_detail(
             "episode_count": show_roll["episode_count"],
             "collection_keys": sh.collection_keys or [],
             # TMDB enrichment (E5 S2), served from the row.
-            "tmdb": plex_tmdb.serve_block(db, sh),
+            "tmdb": plex_tmdb.serve_block(db, sh, lang=lang),
         },
         "seasons": [_season_block(se, by_season.get(se.id, [])) for se in seasons],
         "related": related,
@@ -234,7 +238,9 @@ def _season_block(se: PlexSeason, cards: list[dict]) -> dict:
     }
 
 
-def _relatedshow_cards(db: Session, user_id: int, related: list[dict], exclude: int) -> list[dict]:
+def _relatedshow_cards(
+    db: Session, user_id: int, related: list[dict], exclude: int, lang: str
+) -> list[dict]:
     """Map Plex 'related' metadata to show cards for the shows we actually mirror (so they're openable),
     excluding the current show. Order preserved; capped."""
     rks = [str(m.get("ratingKey")) for m in related if m.get("ratingKey")]
@@ -254,13 +260,13 @@ def _relatedshow_cards(db: Session, user_id: int, related: list[dict], exclude:
         if sh is None or rk in seen:
             continue
         seen.add(rk)
-        out.append(show_card(sh, statuses.get(sh.id, "new")))
+        out.append(show_card(sh, statuses.get(sh.id, "new"), lang=lang))
         if len(out) >= 20:
             break
     return out
 
 
-def _collection_strips(db: Session, it: PlexItem, user_id: int) -> list[dict]:
+def _collection_strips(db: Session, it: PlexItem, user_id: int, lang: str) -> list[dict]:
     """The collections this movie belongs to, each with its member titles (playable cards) — the
     'Avatar Collection' strip on the info page. Pure local lookup (no Plex call)."""
     keys = it.collection_keys or []
@@ -273,7 +279,8 @@ def _collection_strips(db: Session, it: PlexItem, user_id: int) -> list[dict]:
         ).scalars()
     }
     # Smallest (most specific — e.g. a franchise) first; the big auto-lists (IMDb/TMDb Popular) last.
-    ordered = sorted((c for c in cols.values()), key=lambda c: (c.child_count or 0, c.title))
+    alpha = {w: i for i, w in enumerate(sorted_words(db, [c.title for c in cols.values()], lang))}
+    ordered = sorted(cols.values(), key=lambda c: (c.child_count or 0, alpha[c.title]))
     out = []
     for col in ordered:
         rk = col.rating_key
@@ -285,7 +292,9 @@ def _collection_strips(db: Session, it: PlexItem, user_id: int) -> list[dict]:
                     PlexItem.kind == "movie",
                     PlexItem.collection_keys.contains([rk]),
                 )
-                .order_by(PlexItem.year.asc().nullslast(), func.lower(PlexItem.title))
+                .order_by(
+                    PlexItem.year.asc().nullslast(), collated(title_col(PlexItem, lang), lang)
+                )
                 .limit(60)
             )
             .scalars()
@@ -305,7 +314,7 @@ def _collection_strips(db: Session, it: PlexItem, user_id: int) -> list[dict]:
                 "id": rk,
                 "title": col.title,
                 "source": _collection_source(col),
-                "items": [movie_card(m, states.get(m.id)) for m in members],
+                "items": [movie_card(m, states.get(m.id), lang=lang) for m in members],
             }
         )
     return out
@@ -339,6 +348,26 @@ def _episode_nav(db: Session, it: PlexItem) -> tuple[str | None, str | None]:
     return (keys[i - 1] if i > 0 else None), (keys[i + 1] if i < len(keys) - 1 else None)
 
 
+# The technical tail of Plex's track title — "English (AC3 5.1)" → "AC3 5.1".
+_TRACK_TAIL = re.compile(r"\(([^()]+)\)\s*$")
+
+
+def _track_naming(s: dict) -> dict:
+    """What the player names a track from (E30). Plex's `displayTitle` is in the SERVER's language
+    ("English (AC3 5.1)", "magyar Forced", "中文 (EAC3 Stereo)"), so it is sent only as the fallback
+    `label`; the client builds the name in the reader's language from the language tag, the
+    forced / SDH flags and the codec tail. No title and no language → no label (the client numbers it)."""
+    title = s.get("displayTitle") or s.get("language") or None
+    tail = _TRACK_TAIL.search(title) if title else None
+    return {
+        "label": title,
+        "lang_tag": s.get("languageTag") or None,
+        "forced": bool(s.get("forced")),
+        "hearing_impaired": bool(s.get("hearingImpaired")),
+        "detail": tail.group(1).strip() if tail else None,
+    }
+
+
 @router.get("/item/{rating_key}")
 def item_detail(
     rating_key: str,
@@ -384,9 +413,7 @@ def item_detail(
                 audio_streams.append(
                     {
                         "ord": len(audio_streams),
-                        "label": s.get("displayTitle")
-                        or s.get("language")
-                        or f"Audio {len(audio_streams) + 1}",
+                        **_track_naming(s),
                         "language": s.get("languageTag") or s.get("language"),
                         "default": bool(s.get("selected") or s.get("default")),
                     }
@@ -396,9 +423,7 @@ def item_detail(
                 subtitle_streams.append(
                     {
                         "ord": len(subtitle_streams),
-                        "label": s.get("displayTitle")
-                        or s.get("language")
-                        or f"Subtitle {len(subtitle_streams) + 1}",
+                        **_track_naming(s),
                         "language": s.get("languageTag") or s.get("language"),
                         "codec": codec,
                         # Text subs (srt/ass/…) can be served as WebVTT tracks; image subs (PGS/VobSub)
@@ -468,7 +493,7 @@ def item_detail(
             "genres": (it.genres_hu or it.genres if hu else it.genres) or [],
             "directors": it.directors or [],
             "studio": it.studio,
-            "tagline": it.tagline,
+            "tagline": (it.tagline_hu or it.tagline) if hu else it.tagline,
         }
     else:
         rich = plex_detail.rich_detail(meta)
@@ -512,7 +537,7 @@ def item_detail(
         "episode_number": it.episode_number,
         "prev_id": prev_id,
         "next_id": next_id,
-        "collections": _collection_strips(db, it, user.id),
+        "collections": _collection_strips(db, it, user.id, lang),
         # TMDB enrichment (E5 S2), served from the row — movies only (episodes aren't enriched).
-        "tmdb": plex_tmdb.serve_block(db, it) if it.kind == "movie" else None,
+        "tmdb": plex_tmdb.serve_block(db, it, lang=lang) if it.kind == "movie" else None,
     }

backend/app/routes/plex/discover.py

@@ -18,11 +18,12 @@ from fastapi import APIRouter, Depends, Query
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.orm import Session
 
+from app.collation import sorted_words
 from app.auth import current_user
 from app.db import get_db
 from app.models import PlexItem, PlexShow, PlexState, User
 from app.plex import rollup
-from app.plex.cards import leaf_card, movie_card, show_card
+from app.plex.cards import display_title, leaf_card, movie_card, show_card
 from app.plex.query import (
     LibraryFilters,
     apply_meta_filters,
@@ -61,14 +62,14 @@ def _movie_meta(q, p: dict, lang: str, f: LibraryFilters):
     return q
 
 
-def _movie_cards(db: Session, uid: int, items: list[PlexItem]) -> list[dict]:
+def _movie_cards(db: Session, uid: int, items: list[PlexItem], lang: str) -> list[dict]:
     sts = rollup.item_state_map(db, uid, [it.id for it in items])
-    return [movie_card(it, sts.get(it.id)) for it in items]
+    return [movie_card(it, sts.get(it.id), lang=lang) for it in items]
 
 
-def _show_cards(db: Session, uid: int, shows: list[PlexShow]) -> list[dict]:
+def _show_cards(db: Session, uid: int, shows: list[PlexShow], lang: str) -> list[dict]:
     statuses = rollup.state_map(db, uid, [s.id for s in shows])
-    return [show_card(s, statuses.get(s.id, "new")) for s in shows]
+    return [show_card(s, statuses.get(s.id, "new"), lang=lang) for s in shows]
 
 
 def _recently_added(
@@ -123,8 +124,8 @@ def _recently_added(
     # share one), so the merge doesn't depend on object identity staying alive.
     top_movies = [o for _, kind, o in top if kind == "movie"]
     top_shows = [o for _, kind, o in top if kind == "show"]
-    mcards = {m.rating_key: c for m, c in zip(top_movies, _movie_cards(db, uid, top_movies))}
-    scards = {s.rating_key: c for s, c in zip(top_shows, _show_cards(db, uid, top_shows))}
+    mcards = {m.rating_key: c for m, c in zip(top_movies, _movie_cards(db, uid, top_movies, lang))}
+    scards = {s.rating_key: c for s, c in zip(top_shows, _show_cards(db, uid, top_shows, lang))}
     return [mcards[o.rating_key] if kind == "movie" else scards[o.rating_key] for _, kind, o in top]
 
 
@@ -156,10 +157,10 @@ def _recently_watched(
             .order_by(PlexState.watched_at.desc().nullslast())
             .limit(RAIL_LIMIT)
         ).all():
-            rows.append((st.watched_at, leaf_card(it, st)))
+            rows.append((st.watched_at, leaf_card(it, st, lang=lang)))
     if show_ids:
         eq = (
-            select(PlexItem, PlexState, PlexShow.title, PlexShow.rating_key)
+            select(PlexItem, PlexState, PlexShow)
             .join(PlexState, and_(PlexState.item_id == PlexItem.id, PlexState.user_id == uid))
             .join(PlexShow, PlexShow.id == PlexItem.show_id)
             .where(
@@ -170,8 +171,11 @@ def _recently_watched(
             .order_by(PlexState.watched_at.desc().nullslast())
             .limit(RAIL_LIMIT)
         )
-        for ep, st, sh_title, sh_rk in db.execute(eq).all():
-            rows.append((st.watched_at, leaf_card(ep, st, show_title=sh_title, show_rk=sh_rk)))
+        for ep, st, sh in db.execute(eq).all():
+            card = leaf_card(
+                ep, st, show_title=display_title(sh, lang), show_rk=sh.rating_key, lang=lang
+            )
+            rows.append((st.watched_at, card))
     rows.sort(key=lambda r: r[0] or rollup.NO_TS, reverse=True)
     return [card for _, card in rows[:RAIL_LIMIT]]
 
@@ -214,7 +218,7 @@ def _continue_watching(
             .limit(RAIL_LIMIT)
         ).all()
         for it, st in mrows:
-            rows.append((st.progress_updated_at, movie_card(it, st)))
+            rows.append((st.progress_updated_at, movie_card(it, st, lang=lang)))
 
     if show_ids:
         # Reuse the shared per-show episode rollup (total/watched/inprog) rather than re-inlining it, plus
@@ -234,7 +238,7 @@ def _continue_watching(
             .limit(RAIL_LIMIT)
         ).all()
         for sh, resumed_at in srows:
-            rows.append((resumed_at, show_card(sh, "in_progress")))
+            rows.append((resumed_at, show_card(sh, "in_progress", lang=lang)))
 
     rows.sort(key=lambda r: r[0] or rollup.NO_TS, reverse=True)
     return [card for _, card in rows[:RAIL_LIMIT]]
@@ -261,7 +265,8 @@ def _genre_tiles(
         expanded = base.subquery()
         for g, c in db.execute(select(expanded.c.g, func.count()).group_by(expanded.c.g)).all():
             counts[g] = counts.get(g, 0) + c
-    top = sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))[:GENRE_TILES]
+    alpha = {w: i for i, w in enumerate(sorted_words(db, list(counts), lang))}
+    top = sorted(counts.items(), key=lambda kv: (-kv[1], alpha[kv[0]]))[:GENRE_TILES]
     # A 2×2 poster collage per tile: the top movies in that genre (color hash is the client fallback).
     art = top_art_keys(
         db,
@@ -310,7 +315,7 @@ def _because_you_watched(
     )
     if anchor is None:
         return None
-    resolved = resolve_recs(db, anchor.recommendations)
+    resolved = resolve_recs(db, anchor.recommendations, lang=lang)
     # Preserve TMDB's recommendation order, keep only in-library hits, and drop the anchor itself.
     rks = [
         r["rating_key"]
@@ -346,9 +351,11 @@ def _because_you_watched(
     ordered_shows = [shows[rk] for rk in rks if rk in shows]
     # rating_key is globally unique in Plex, so it keys the serialized cards back safely (no id()).
     mcards = {
-        m.rating_key: c for m, c in zip(ordered_movies, _movie_cards(db, uid, ordered_movies))
+        m.rating_key: c for m, c in zip(ordered_movies, _movie_cards(db, uid, ordered_movies, lang))
+    }
+    scards = {
+        s.rating_key: c for s, c in zip(ordered_shows, _show_cards(db, uid, ordered_shows, lang))
     }
-    scards = {s.rating_key: c for s, c in zip(ordered_shows, _show_cards(db, uid, ordered_shows))}
     items: list[dict] = []
     for rk in rks:
         if rk in mcards:
@@ -357,7 +364,10 @@ def _because_you_watched(
             items.append(scards[rk])
     if not items:
         return None
-    return {"anchor": {"id": anchor.rating_key, "title": anchor.title}, "items": items}
+    return {
+        "anchor": {"id": anchor.rating_key, "title": display_title(anchor, lang)},
+        "items": items,
+    }
 
 
 @router.get("/discover")
@@ -456,8 +466,8 @@ def surprise(
             .scalars()
             .all()
         )
-    mcards = _movie_cards(db, user.id, movies)
-    scards = _show_cards(db, user.id, shows)
+    mcards = _movie_cards(db, user.id, movies, lang)
+    scards = _show_cards(db, user.id, shows, lang)
     # Interleave movie/show cards, then trim to `limit`.
     items: list[dict] = []
     for i in range(max(len(mcards), len(scards))):

backend/app/routes/plex/people.py

@@ -7,7 +7,8 @@ from fastapi import APIRouter, BackgroundTasks, Depends
 from sqlalchemy import func, or_, select
 from sqlalchemy.orm import Session
 
-from app import logs
+from app.collation import collated
+from app import logs, sysconfig
 from app.auth import current_user
 from app.db import SessionLocal, get_db
 from app.models import (
@@ -18,22 +19,28 @@ from app.models import (
 )
 from app.plex import rollup
 from app.plex import tmdb as plex_tmdb
-from app.plex.cards import movie_card, show_card
-from app.plex.query import content_libs, split_csv
+from app.plex.cards import movie_card, norm_lang, show_card
+from app.plex.query import content_libs, split_csv, title_col
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 log = logs.get_logger(__name__)
 
 
+# How many "Known for" titles the person page shows (the stored pool is deeper; see plex.tmdb).
+_KNOWN_FOR_SHOWN = 15
+
+
 def _resolve_known_for(
     db: Session,
     known_for: list | None,
     uid: int,
     movie_lib_ids: list[int],
     show_lib_ids: list[int],
+    lang: str,
 ) -> list[dict]:
-    """The person's TMDB "Known for" credits (top by popularity) that are IN our library, as cards, in
-    popularity order. Matched by the canonical guid `tmdb:<id>`; out-of-library credits are dropped."""
+    """The person's TMDB "Known for" credits (most-voted first) that are IN our library, as cards, in
+    that order, at most _KNOWN_FOR_SHOWN. Matched by the canonical guid `tmdb:<id>`; out-of-library
+    credits are dropped."""
     if not known_for:
         return []
     # Match each credit to a library row by guid, bucketed by media_type (movie ids and tv ids collide
@@ -50,10 +57,10 @@ def _resolve_known_for(
         # A credit resolves against its OWN media_type's bucket only.
         if k.get("media_type") == "tv":
             if g in shows:
-                out.append(show_card(shows[g], show_statuses.get(shows[g].id, "new")))
+                out.append(show_card(shows[g], show_statuses.get(shows[g].id, "new"), lang=lang))
         elif g in movies:
-            out.append(movie_card(movies[g], m_states.get(movies[g].id)))
-    return out
+            out.append(movie_card(movies[g], m_states.get(movies[g].id), lang=lang))
+    return out[:_KNOWN_FOR_SHOWN]
 
 
 @router.get("/people/cards")
@@ -159,6 +166,7 @@ def _enrich_person_bg(person_id: int) -> None:
 def person_detail(
     name: str,
     background_tasks: BackgroundTasks,
+    lang: str = "en",
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
@@ -171,18 +179,24 @@ def person_detail(
     E5 S6: the first time a page is opened, the person's TMDB bio + "Known for" credits are lazily
     fetched (from the S2-linked `tmdb_person_id`) and persisted, then served from the row on every open.
     The fetch runs OFF the request path (a background task); the first open serves whatever's in the row
-    (bio possibly still null) and the bio lands from the row by the next open.
+    with `enriching` set, and the page asks again until the bio lands. E30 S6: the people_enrich job
+    fetches everyone ahead of time, so this lazy path is only for a person the job hasn't reached yet.
     """
+    lang = norm_lang(lang)
     person = db.execute(select(PlexPerson).where(PlexPerson.name == name)).scalars().first()
     # Lazy one-time bio enrich, scheduled AFTER the response so the TMDB call is never on the serve path.
     # Gated by a per-person cooldown so concurrent/rapid opens (or repeated opens while TMDB is degraded)
     # can't pile background tasks onto the shared threadpool.
-    if (
+    # `enriching` tells the page the bio is on its way (E30 S6): it asks again shortly instead of showing
+    # an empty page until the next open. True while a fetch is pending, including one an earlier open
+    # already reserved.
+    enriching = (
         person is not None
-        and person.tmdb_person_id
+        and bool(person.tmdb_person_id)
         and person.tmdb_enriched_at is None
-        and _should_schedule_enrich(person.id)
-    ):
+        and bool(sysconfig.get_str(db, "tmdb_api_key"))
+    )
+    if enriching and person is not None and _should_schedule_enrich(person.id):
         background_tasks.add_task(_enrich_person_bg, person.id)
     movie_lib_ids, show_lib_ids = content_libs(db)
 
@@ -199,14 +213,16 @@ def person_detail(
                         PlexItem.directors.contains([name]),
                     ),
                 )
-                .order_by(PlexItem.year.desc().nullslast(), func.lower(PlexItem.title))
+                .order_by(
+                    PlexItem.year.desc().nullslast(), collated(title_col(PlexItem, lang), lang)
+                )
                 .limit(_PERSON_SECTION_MAX)
             )
             .scalars()
             .all()
         )
         states = rollup.item_state_map(db, user.id, [it.id for it in items])
-        movies = [movie_card(it, states.get(it.id)) for it in items]
+        movies = [movie_card(it, states.get(it.id), lang=lang) for it in items]
 
     shows: list[dict] = []
     if show_lib_ids:
@@ -220,28 +236,34 @@ def person_detail(
                         PlexShow.directors.contains([name]),
                     ),
                 )
-                .order_by(PlexShow.year.desc().nullslast(), func.lower(PlexShow.title))
+                .order_by(
+                    PlexShow.year.desc().nullslast(), collated(title_col(PlexShow, lang), lang)
+                )
                 .limit(_PERSON_SECTION_MAX)
             )
             .scalars()
             .all()
         )
         statuses = rollup.state_map(db, user.id, [s.id for s in show_rows])
-        shows = [show_card(sh, statuses.get(sh.id, "new")) for sh in show_rows]
+        shows = [show_card(sh, statuses.get(sh.id, "new"), lang=lang) for sh in show_rows]
 
     known_for = _resolve_known_for(
-        db, person.known_for if person else None, user.id, movie_lib_ids, show_lib_ids
+        db, person.known_for if person else None, user.id, movie_lib_ids, show_lib_ids, lang
     )
     return {
         "name": name,
         "photo": person.photo_thumb if person else None,
-        "biography": person.biography if person else None,
+        # The Hungarian biography for a Hungarian reader, the instance-language one when TMDB has none.
+        "biography": ((person.biography_hu if lang == "hu" else None) or person.biography)
+        if person
+        else None,
         "birthday": person.birthday if person else None,
         "deathday": person.deathday if person else None,
         "place_of_birth": person.place_of_birth if person else None,
         "known_for_department": person.known_for_department if person else None,
         "also_known_as": (person.also_known_as if person else None) or [],
         "known_for": known_for,
+        "enriching": enriching,
         "movies": movies,
         "shows": shows,
     }

backend/app/routes/plex/playback.py

@@ -1,6 +1,5 @@
 """Plex playback: image/subtitle proxies, HLS streaming, and watch-state writes."""
 
-import hashlib
 import threading
 from datetime import datetime, timedelta, timezone
 
@@ -66,7 +65,7 @@ def image(rating_key: str, request: Request, variant: str = "thumb") -> Response
     brief session only to resolve the image key + read the Plex config, then RELEASES it before the
     fetch. Auth is the signed-session check (no DB user-load)."""
     _require_session(request)
-    v = "art" if variant == "art" else "thumb"
+    v = variant if variant in imgcache.SIZES else "thumb"
     w, h = imgcache.SIZES[v]
     # Size is part of the cache key: Plex resizes server-side (see PlexClient.image_bytes), so we cache
     # the small variant. The width tag also means changing a target size just re-caches, never serves a
@@ -78,7 +77,7 @@ def image(rating_key: str, request: Request, variant: str = "thumb") -> Response
     # Cold miss: short-lived session for the key + Plex client config, released before the slow fetch.
     try:
         with SessionLocal() as db:
-            key = imgcache.key_for(db, str(rating_key), v)
+            key = imgcache.key_for(db, str(rating_key), imgcache.picture(v))
             if not key:
                 raise not_found("image")
             plex = PlexClient(db)  # reads base URL + token now; the fetch below needs no DB
@@ -214,24 +213,31 @@ def _resume_push_superseded(user_id: int, item_id: int, intent: datetime) -> boo
 
 @router.get("/person-image")
 def person_image(u: str, request: Request) -> Response:
-    """Proxy a cast/crew photo from Plex's public metadata CDN (host-whitelisted; no token needed).
-    Signed-session auth (no DB) so it, like /image, never holds a pool connection during the fetch."""
+    """Proxy a cast/crew photo from Plex's public metadata CDN (only a headshot-shaped URL on its host;
+    no token needed), resized through Plex and cached (plex.people.cache_portrait; the people_enrich job
+    fills the same cache ahead of time). Signed-session auth; like /image, the DB session is released
+    before the fetch."""
     _require_session(request)
-    if not u.startswith(plex_people.PERSON_IMG_HOST):
+    if not plex_people.is_portrait_url(u):
         raise refused(400, "image_host")
-    cache_key = "person_" + hashlib.sha1(u.encode()).hexdigest()
-    hit = imgcache.read(cache_key)
+    hit = plex_people.portrait_cached(u)
     if hit:
         return imgcache.response(*hit)
     try:
-        with httpx.Client(timeout=10.0, follow_redirects=True) as c:
-            r = c.get(u)
-            r.raise_for_status()
-    except httpx.HTTPError:
-        raise refused(502, "image_fetch_failed")
-    ct = r.headers.get("content-type", "image/jpeg")
-    imgcache.write(cache_key, r.content, ct)
-    return imgcache.response(r.content, ct)
+        with SessionLocal() as db:
+            plex: PlexClient | None = PlexClient(db)
+    # silent-ok: Plex off is a setting; without its resize the original comes straight from the CDN.
+    except PlexNotConfigured:
+        plex = None
+    try:
+        if plex is None:
+            data, ct = plex_people.cache_portrait(None, u)
+        else:
+            with plex:
+                data, ct = plex_people.cache_portrait(plex, u)
+    except (PlexError, httpx.HTTPError):
+        raise refused(502, "image_fetch_failed") from None
+    return imgcache.response(data, ct)
 
 
 def _push_resume_guarded(

backend/app/routes/plex/playlists.py

@@ -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
@@ -17,7 +19,7 @@ from app.models import (
     PlexState,
     User,
 )
-from app.plex.cards import leaf_card
+from app.plex.cards import display_title, leaf_card, norm_lang
 from app.plex.lookups import by_rating_key
 from app.routes._common import owned_or_404, not_found
 from app.refusal import refused
@@ -135,8 +137,12 @@ def create_playlist(
 
 @router.get("/playlists/{pid}")
 def playlist_detail(
-    pid: int, user: User = Depends(current_user), db: Session = Depends(get_db)
+    pid: int,
+    lang: str = "en",
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
 ) -> dict:
+    lang = norm_lang(lang)
     pl = owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
     rows = db.execute(_playlist_item_query(pid)).all()
     items = [it for (_pi, it) in rows]
@@ -161,8 +167,9 @@ def playlist_detail(
         leaf_card(
             it,
             states.get(it.id),
-            shows[it.show_id].title if it.show_id in shows else None,
+            display_title(shows[it.show_id], lang) if it.show_id in shows else None,
             shows[it.show_id].rating_key if it.show_id in shows else None,
+            lang=lang,
         )
         for it in items
     ]
@@ -217,7 +224,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 +257,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 +295,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 +406,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 +436,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 +444,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}

backend/app/routes/search.py

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

backend/app/routes/sync.py

@@ -71,7 +71,7 @@ def sync_status(user: User = Depends(current_user), db: Session = Depends(get_db
 def my_status(user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
     """Per-user sync progress: how far the channels *this* user subscribes to have synced."""
     sub_join = and_(Subscription.channel_id == Channel.id, Subscription.user_id == user.id)
-    total, details_synced, recent_synced, deep_done = db.execute(
+    total, details_synced, recent_synced, all_deep_done = db.execute(
         select(
             func.count(Channel.id),
             func.count(Channel.details_synced_at),
@@ -82,7 +82,7 @@ def my_status(user: User = Depends(current_user), db: Session = Depends(get_db))
         .join(Subscription, sub_join)
     ).one()
     total = total or 0
-    deep_done = int(deep_done or 0)
+    all_deep_done = int(all_deep_done or 0)
 
     # Per-user full-history (deep) backfill: channels this user has opted in, and an ETA
     # for the still-pending ones (quota-bound estimate).
@@ -97,6 +97,10 @@ def my_status(user: User = Depends(current_user), db: Session = Depends(get_db))
         .all()
     )
     deep_eta = estimate_deep_backfill(db, deep_requested_channels)
+    # "done / requested" is shown as one ratio, so both halves count the SAME channels: the ones this
+    # user asked full history for. Counting every subscribed channel whose back-catalog happens to be
+    # complete (another user asked, or it was short) gave "342/329".
+    deep_done = sum(1 for c in deep_requested_channels if c.backfill_done)
 
     my_videos = db.scalar(
         select(func.count(Video.id)).join(
@@ -117,7 +121,7 @@ def my_status(user: User = Depends(current_user), db: Session = Depends(get_db))
         "channels_recent_synced": recent_synced,
         "channels_deep_done": deep_done,
         "channels_recent_pending": total - recent_synced,
-        "channels_deep_pending": total - deep_done,
+        "channels_deep_pending": total - all_deep_done,
         "channels_deep_requested": len(deep_requested_channels),
         "deep_pending_count": deep_eta["channels_pending"],
         "deep_eta_seconds": deep_eta["eta_seconds"],

backend/app/scheduler.py

@@ -18,6 +18,7 @@ from app.downloads.gc import run_download_gc
 from app.models import SchedulerSetting, User
 from app.plex.sync import sync as run_plex_sync
 from app.plex.tmdb import run_enrich as run_tmdb_enrich
+from app.plex.tmdb import run_people_enrich
 from app.plex.watch_sync import run_plex_watch_reconcile, run_plex_watch_sync
 from app.notifications import create_notification
 from app.state import is_sync_paused
@@ -69,6 +70,7 @@ JOB_INTERVALS: dict[str, int] = {
     "plex_watch_sync": settings.plex_watch_sync_interval_min,
     "plex_watch_reconcile": settings.plex_watch_reconcile_interval_min,
     "tmdb_enrich": settings.tmdb_enrich_interval_min,
+    "people_enrich": settings.people_enrich_interval_min,
     "audit_gc": settings.audit_gc_minutes,
     "log_gc": settings.log_gc_minutes,
 }
@@ -115,7 +117,9 @@ def _record(name: str, **fields) -> None:
         _activity.setdefault(name, {}).update(fields)
 
 
-def _notify_done(db, actor_id: int, job_id: str, status: str, summary: str | None) -> None:
+def _notify_done(
+    db, actor_id: int, job_id: str, status: str, summary: str | None, result: dict | None = None
+) -> None:
     """Post a completion notice to the triggering admin's inbox (manual runs only). Best
     effort — a notification failure must never mask the job's own outcome."""
     try:
@@ -125,7 +129,7 @@ def _notify_done(db, actor_id: int, job_id: str, status: str, summary: str | Non
             type="scheduler",
             title=f"{job_id}: {status}",  # English fallback; UI renders translated from data
             body=summary,
-            data={"job_id": job_id, "status": status, "summary": summary},
+            data={"job_id": job_id, "status": status, "summary": summary, "result": result},
         )
     except Exception:
         db.rollback()
@@ -140,7 +144,12 @@ def _run_changed(result) -> bool:
     if result is None:
         return False
     if isinstance(result, dict):
-        return any(isinstance(v, (int, float)) and v for v in result.values())
+        # A phased job (backfill's recent/deep, people_enrich's bios/portraits) nests a result per
+        # phase: a count inside a phase is a change too.
+        return any(
+            _run_changed(v) if isinstance(v, dict) else isinstance(v, (int, float)) and bool(v)
+            for v in result.values()
+        )
     if isinstance(result, (int, float)):
         return result != 0
     return bool(result)
@@ -152,6 +161,9 @@ def _audit_run(db, actor_id, job_id, status, summary, result) -> None:
     they changed something, so routine no-op polls don't spam the trail. Best-effort."""
     if actor_id is None and status == "ok" and not _run_changed(result):
         return
+    # The result as data too (E30): the audit log names it in the reader's language, as the inbox
+    # does; `summary` stays the English line of the row's own summary column.
+    data = _result_data(result)
     try:
         audit.record(
             db,
@@ -160,7 +172,7 @@ def _audit_run(db, actor_id, job_id, status, summary, result) -> None:
             target_type="job",
             target_id=job_id,
             summary=f"{job_id}: {status}" + (f" — {summary}" if summary else ""),
-            after={"status": status, "summary": summary},
+            after={"status": status, "summary": summary, **({"result": data} if data else {})},
         )
         db.commit()
     except Exception:
@@ -192,28 +204,49 @@ def _job(name: str, fn) -> None:
                 status="skipped",
                 last_finished=_now_iso(),
                 last_result="paused",
+                result=_PAUSED,
                 progress=None,
             )
             if actor_id is not None:
-                _notify_done(db, actor_id, name, "skipped", "sync paused")
-                _audit_run(db, actor_id, name, "skipped", "sync paused", None)
+                _notify_done(db, actor_id, name, "skipped", "sync paused", _PAUSED)
+                _audit_run(db, actor_id, name, "skipped", "sync paused", _PAUSED)
             return
         with progress.bind(sink):
             result = fn(db)
         summary = _summarize(result)
+        data = _result_data(result)
         log.info("job %s -> %s", name, result)
-        _record(name, status="ok", last_finished=_now_iso(), last_result=summary, progress=None)
+        _record(
+            name,
+            status="ok",
+            last_finished=_now_iso(),
+            last_result=summary,
+            result=data,
+            progress=None,
+        )
         if actor_id is not None:
-            _notify_done(db, actor_id, name, "ok", summary)
+            _notify_done(db, actor_id, name, "ok", summary, data)
         _audit_run(db, actor_id, name, "ok", summary, result)
     except Exception as exc:
         db.rollback()
         log.exception("job %s failed", name, extra=logs.event("scheduler.job.failed", job=name))
         err = str(exc) or exc.__class__.__name__
-        _record(name, status="error", last_finished=_now_iso(), last_error=err, progress=None)
+        # A failure the job named (progress.JobFailed) rides along as data, as a result does, so the
+        # client says it in the reader's language; `err` stays the English line.
+        failure = (
+            {"failure": exc.reason, **exc.params} if isinstance(exc, progress.JobFailed) else None
+        )
+        _record(
+            name,
+            status="error",
+            last_finished=_now_iso(),
+            last_error=err,
+            result=failure,
+            progress=None,
+        )
         if actor_id is not None:
-            _notify_done(db, actor_id, name, "error", err)
-        _audit_run(db, actor_id, name, "error", err, None)
+            _notify_done(db, actor_id, name, "error", err, failure)
+        _audit_run(db, actor_id, name, "error", err, failure)
     finally:
         # ALWAYS release the claim, even if the body raised before its own status update — so a
         # failure can never wedge the job as permanently "running".
@@ -221,6 +254,21 @@ def _job(name: str, fn) -> None:
         db.close()
 
 
+# A skipped run's result, in the same shape as a job's own `{"skipped": …}`.
+_PAUSED = {"skipped": "sync paused"}
+
+
+def _result_data(result) -> dict | None:
+    """A job's result as the client names it in the reader's language (E30): the dict itself (counts,
+    a `skipped` / `reason` word, a nested dict per phase), `enrich`'s bare count as one. The one-line
+    `_summarize` is the English fallback."""
+    if isinstance(result, dict):
+        return result or None
+    if isinstance(result, int) and not isinstance(result, bool):
+        return {"enriched": result}
+    return None
+
+
 def _summarize(result) -> str | None:
     """Compact one-line rendering of a job's return value for the dashboard."""
     if result is None:
@@ -259,6 +307,7 @@ def scheduler_snapshot() -> dict:
                 "last_started": a.get("last_started"),
                 "last_finished": a.get("last_finished"),
                 "last_result": a.get("last_result"),
+                "result": a.get("result"),
                 "last_error": a.get("last_error"),
                 "progress": a.get("progress"),
             }
@@ -369,6 +418,12 @@ def _tmdb_enrich_job() -> None:
     _job("tmdb_enrich", run_tmdb_enrich)
 
 
+def _people_enrich_job() -> None:
+    # Make the people local (E30 S6): a batch of person bios from TMDB and a batch of portraits resized
+    # through Plex, so a person page and a cast strip never wait on an outside service.
+    _job("people_enrich", run_people_enrich)
+
+
 def _audit_gc_job() -> None:
     # Prune audit-log rows older than the admin-set retention (audit_retention_days; 0 = keep
     # forever). Pure DB, no quota.
@@ -415,6 +470,7 @@ JOB_FUNCS: dict[str, Callable[[], None]] = {
     "plex_watch_sync": _plex_watch_sync_job,
     "plex_watch_reconcile": _plex_watch_reconcile_job,
     "tmdb_enrich": _tmdb_enrich_job,
+    "people_enrich": _people_enrich_job,
     "audit_gc": _audit_gc_job,
     "log_gc": _log_gc_job,
 }

backend/app/sync/autotag.py

@@ -115,7 +115,9 @@ _TOPIC_SLUGS = {
     "Tourism": "Travel",
     "Fashion": "Fashion & Beauty",
     "Physical_attractiveness": "Fashion & Beauty",
-    "Humor": "Comedy",
+    # YouTube links the British page (…/wiki/Humour); the key was "Humor", so no channel ever got Comedy
+    # from its topic (E30).
+    "Humour": "Comedy",
     "Entertainment": "Entertainment",
     "Film": "Film",
     "Television_program": "TV",

backend/app/sync/playlists.py

@@ -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)}
 

backend/app/sync/runner.py

@@ -83,6 +83,8 @@ def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str
     # outage from one permanently dead feed id — which is the whole difference on an instance with
     # a single subscription, where BOTH render as 100% failed.
     first_error: str | None = None
+    # The same first failure as data, for the reader's language: whose feed, and why (`reasons`' key).
+    first_failure: tuple[str, str] | None = None
     # What failed, as counts per reason (`http_404`, `transport`, `apply`, …) plus a few examples —
     # the ONE warning a poll writes. One line per failed channel was what turned YouTube's RSS outage
     # of 2026-09-16 into 11k warnings in four hours; each channel's own line is DEBUG now.
@@ -92,18 +94,19 @@ def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str
     # hand the same rows to the same broken write) — the feed fallback's candidates.
     unread: list[str] = []
 
-    def fail(reason: str, detail: str, *, unexpected: str | None = None) -> None:
+    def fail(reason: str, channel_id: str, detail: str, *, unexpected: str | None = None) -> None:
         """Count a channel that did not get polled. `unexpected` is the message for a failure that
         is a bug on our side: its FIRST occurrence per reason gets a traceback at ERROR, the rest
         DEBUG — a read-only database fails every channel the same way, and 979 identical tracebacks
         tell nobody anything the first one didn't. Call it from inside the `except` block."""
-        nonlocal failed, first_error
+        nonlocal failed, first_error, first_failure
         if unexpected is not None:
             level = logging.ERROR if reasons[reason] == 0 else logging.DEBUG
             log.log(level, unexpected, exc_info=True)
         failed += 1
         reasons[reason] += 1
         first_error = first_error or detail
+        first_failure = first_failure or (channel_id, reason)
         if len(examples) < RSS_FAILURE_EXAMPLES:
             examples.append(detail)
 
@@ -125,13 +128,16 @@ def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str
             # bug on our side and earns a traceback (the first of its kind per poll).
             except RssError as exc:
                 log.debug("RSS poll skipped for channel %s: %s", channel.id, exc)
-                fail(exc.reason, f"{channel.id}: {exc}")
+                fail(exc.reason, channel.id, f"{channel.id}: {exc}")
                 unread.append(channel.id)
             # silent-ok: `fail(unexpected=…)` is the report — it logs at ERROR with the
             # traceback, once per reason per poll, which is the flood control this loop needs.
             except Exception as exc:  # noqa: BLE001 — one channel must not stop the poll
                 fail(
-                    "error", f"{channel.id}: {exc}", unexpected=f"RSS fetch failed for {channel.id}"
+                    "error",
+                    channel.id,
+                    f"{channel.id}: {exc}",
+                    unexpected=f"RSS fetch failed for {channel.id}",
                 )
             else:
                 try:
@@ -144,6 +150,7 @@ def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str
                     db.rollback()
                     fail(
                         "apply",
+                        channel.id,
                         f"{channel.id} (apply): {exc}",
                         unexpected=f"RSS apply failed for {channel.id}",
                     )
@@ -180,9 +187,17 @@ def run_rss_poll(db: Session, channels: list[Channel] | None = None) -> dict[str
         # "fix this subscription"; `Connection refused` says "the egress is down".
         # The fallback's count rides along: a red card during an RSS outage should still say
         # whether the uploads are arriving another way.
-        raise RuntimeError(
+        # As data too (E31): the audit log and the inbox say it in the reader's language, the first
+        # failure as its channel and its reason code (`http_404` vs `transport` is that difference).
+        first_channel, first_reason = first_failure or ("", "error")
+        raise progress.JobFailed(
+            "rss_all_failed",
             f"RSS poll failed for all {total} channels — first: {first_error}"
-            f" (read through the API instead: {fallback['read']})"
+            f" (read through the API instead: {fallback['read']})",
+            total=total,
+            channel=first_channel,
+            cause=first_reason,
+            read=fallback["read"],
         )
     return {"new": new + fallback["new"], "failed": failed, "fallback": fallback["read"]}
 

backend/app/sync/subscriptions.py

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

backend/app/sysconfig.py

@@ -10,6 +10,7 @@ stored in the DB and stay env-only).
 
 from dataclasses import dataclass
 
+from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app import logs, security
@@ -45,8 +46,8 @@ class ConfigSpec:
 
 
 # Registry of DB-overridable keys. Add a key here + wire its read through get_*() to move it
-# off env into the admin UI; the admin page renders it automatically from this list. The ORDER is the
-# admin page's tab order (first appearance of each group), so keep a group's keys together.
+# off env into the admin UI; the admin page renders it automatically from this list. A group's keys
+# stay together, in the order its section lists them; a NEW group also needs its place in SECTIONS.
 SPECS: tuple[ConfigSpec, ...] = (
     # --- Access / registration ---
     ConfigSpec("allow_registration", "bool", "access", "allow_registration"),
@@ -219,6 +220,16 @@ SPECS: tuple[ConfigSpec, ...] = (
     # is a config.py default — both stay out of SPECS, like plex_sync_interval_min.)
 )
 
+# The admin page's sections (E31, the owner's pick): sixteen groups as tabs wrapped to three rows at 133%
+# zoom, so they are a vertical list under four headings, in this order. Every group of SPECS sits in
+# exactly one section (test-held), so a new group cannot fall off the page.
+SECTIONS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("access", ("access", "google", "email")),
+    ("youtube", ("youtube", "quota", "backfill", "shorts", "batch", "explore")),
+    ("media", ("downloads", "plex", "tmdb")),
+    ("system", ("maintenance", "audit", "diagnostics", "issues")),
+)
+
 _BY_KEY: dict[str, ConfigSpec] = {s.key: s for s in SPECS}
 
 
@@ -297,7 +308,11 @@ def _raw_override(db: Session, key: str) -> str | None:
     per key so the operator gets a real signal without a per-request traceback. Recovery is documented in
     docs/self-hosting.md: the key must never change once secrets are stored. (B-core-2)
     """
-    row = db.get(SystemConfig, key)
+    return _raw_of(db.get(SystemConfig, key), key)
+
+
+def _raw_of(row: SystemConfig | None, key: str) -> str | None:
+    """`_raw_override` over a row already read (describe() reads them all in one query)."""
     if row is None or row.value is None:
         return None
     if not row.encrypted:
@@ -317,8 +332,11 @@ def _raw_override(db: Session, key: str) -> str | None:
 
 def get(db: Session, key: str):
     """Effective value: the DB override (typed) if set, else the env/config default."""
-    s = _BY_KEY[key]
-    raw = _raw_override(db, key)
+    return _effective(_BY_KEY[key], _raw_override(db, key))
+
+
+def _effective(s: ConfigSpec, raw: str | None):
+    """`get` over an override already read."""
     if raw is None:
         return _default(s)
     if raw == "" and not s.allow_empty:
@@ -410,8 +428,12 @@ def describe(db: Session) -> dict:
     """Admin-UI metadata + current values, grouped. Secret values are never echoed —
     only whether an override is set and whether an env default exists."""
     groups: dict[str, list[dict]] = {}
+    # Every override in one query: a db.get per key was one round trip each (two for a key with no
+    # row, which the session cannot cache), ~40 ms of the page's ~55 on prod (E31 S4d).
+    rows = {r.key: r for r in db.scalars(select(SystemConfig))}
     for s in SPECS:
-        is_set = db.get(SystemConfig, s.key) is not None
+        row = rows.get(s.key)
+        is_set = row is not None
         item: dict = {
             "key": s.key,
             "type": s.type,
@@ -426,7 +448,10 @@ def describe(db: Session) -> dict:
         if s.secret:
             item["default_is_set"] = bool(_default(s))
         else:
-            item["value"] = get(db, s.key)
+            item["value"] = _effective(s, _raw_of(row, s.key))
             item["default"] = _default(s)
         groups.setdefault(s.group, []).append(item)
-    return {"groups": groups, "secrets_manageable": secrets_manageable()}
+    sections = [
+        {"id": sid, "groups": [g for g in members if g in groups]} for sid, members in SECTIONS
+    ]
+    return {"groups": groups, "sections": sections, "secrets_manageable": secrets_manageable()}

backend/app/utils.py

@@ -60,16 +60,24 @@ def now_utc() -> datetime:
     return datetime.now(timezone.utc)
 
 
+# The shortest last word that is prefix-matched. A 1–2 letter prefix matches a large share of the
+# library and ts_rank then scores every match: "m" took ~5–8 s on prod against ~100 ms for a whole
+# word (E31 S4e). A shorter last word is matched whole instead ("tv", "4k" still find themselves).
+MIN_PREFIX_LEN = 3
+
+
 def to_tsquery_str(q: str) -> str | None:
     """Turn free-text into a to_tsquery() string: word runs ANDed together, the LAST word
-    prefix-matched (`:*`) for as-you-type search — e.g. "ti amo magyar" → "ti & amo & magyar:*".
+    prefix-matched (`:*`) for as-you-type search — e.g. "ti amo magyar" → "ti & amo & magyar:*" —
+    once it has MIN_PREFIX_LEN characters ("ti amo m" → "ti & amo & m").
     Only `\\w` runs containing an alphanumeric are kept, so no tsquery operators can leak in
     (the string is built from sanitised tokens, never the raw query). Shared by the YouTube feed
     search and the Plex library search, hence this neutral home rather than either domain module."""
     tokens = [t for t in re.findall(r"\w+", q, flags=re.UNICODE) if any(c.isalnum() for c in t)]
     if not tokens:
         return None
-    tokens[-1] = tokens[-1] + ":*"
+    if len(tokens[-1]) >= MIN_PREFIX_LEN:
+        tokens[-1] = tokens[-1] + ":*"
     return " & ".join(tokens)
 
 

backend/tests/test_abuse_limits.py

@@ -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)]

backend/tests/test_audit_count_rows.py

@@ -0,0 +1,36 @@
+"""E30: an admin action that counts something keeps the count as data in its audit row's `after`, under
+the key the audit log names in the reader's language (`scheduler.result.<key>`, frontend
+auditColumns.tsx) — not only in the English `summary`. A renamed key would fall back to the raw word.
+DB lane (Postgres).
+"""
+
+from sqlalchemy import select
+
+from app.models import AuditLog
+
+
+def _after(db, action: str) -> dict:
+    db.expire_all()
+    return db.execute(select(AuditLog.after).where(AuditLog.action == action)).scalar_one()
+
+
+def test_clearing_the_audit_log_keeps_the_count_as_data(as_user, db, make_user):
+    admin = make_user(email="boss@example.com", role="admin")
+    db.add_all([AuditLog(action="sync_pause"), AuditLog(action="sync_resume")])
+    db.commit()
+    assert as_user(admin).delete("/api/admin/audit").json()["cleared"] == 2
+    assert _after(db, "audit_clear") == {"cleared": 2}
+
+
+def test_a_demo_reset_keeps_the_count_as_data(as_user, db, make_user):
+    admin = make_user(email="boss@example.com", role="admin")
+    seeded = as_user(admin).post("/api/admin/demo/reset").json()["playlists_seeded"]
+    assert _after(db, "demo_reset") == {"playlists_seeded": seeded}
+
+
+def test_a_discovery_purge_keeps_its_counts_as_data(as_user, db, make_user):
+    admin = make_user(email="boss@example.com", role="admin")
+    body = as_user(admin).post("/api/admin/purge-discovery").json()
+    body.pop("ok")
+    assert _after(db, "discovery_purge") == body
+    assert {"videos_deleted", "channels_deleted", "search_videos_deleted"} <= set(body)

backend/tests/test_autotag_topics.py

@@ -0,0 +1,24 @@
+"""A YouTube topic URL's slug → the auto-tag it gives (pure). The slugs are the ones YouTube actually
+links (measured on the owner's channels, 2026-09-29): a key spelled differently from YouTube's page
+never matches, silently — "Humor" sat in the map for months while YouTube links …/wiki/Humour."""
+
+import pytest
+
+from app.sync.autotag import map_topic_slug
+
+
+@pytest.mark.parametrize(
+    ("slug", "tag"),
+    [
+        ("Humour", "Comedy"),
+        ("Video_game_culture", "Gaming"),
+        ("Electronic_music", "Music"),
+        ("Association_football", "Sports"),
+        ("Knowledge", "Education"),
+        ("Physical_fitness", "Health & Fitness"),
+        ("Television_program", "TV"),
+        ("Lifestyle_(sociology)", None),  # YouTube's catch-all: deliberately no tag
+    ],
+)
+def test_a_youtube_topic_slug_gives_its_tag(slug, tag):
+    assert map_topic_slug(slug) == tag

backend/tests/test_channel_details_refresh.py

@@ -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"]]

backend/tests/test_channel_list_index_only.py

@@ -0,0 +1,83 @@
+"""The channel manager's sums and the feed sidebar's counts read the index alone (E31 S4d).
+
+`GET /api/channels` counts each subscribed channel's videos and sums their durations; `/feed/summary`
+and `/feed/years` count the reader's videos per channel and per year under the default filters. They
+used to read every video's heap page for that (681 MB on prod), a 2–6 s first open once something else
+had pushed the table out of memory. Migration 0095 makes `ix_videos_channel_pub_cover` carry every
+column those queries read, so Postgres answers them with Index Only Scans. This test holds the queries
+and the index together: a column added to one and not the other fails it. DB lane.
+"""
+
+import re
+
+from sqlalchemy import text
+from sqlalchemy.dialects import postgresql
+
+from app.feedquery import filtered_query
+from app.models import Video
+from app.routes.channels import channel_aggregates
+
+INDEX = "ix_videos_channel_pub_cover"
+
+# The feed's own defaults (routes/feed.py _feed_params): what the sidebar asks on a plain open.
+FEED_DEFAULTS = {
+    "tags": [],
+    "tag_modes": {"language": "or", "topic": "or", "other": "or"},
+    "untagged": False,
+    "channel_ids": [],
+    "q": None,
+    "min_duration": None,
+    "max_duration": None,
+    "max_age_days": None,
+    "published_after": None,
+    "published_before": None,
+    "show_normal": True,
+    "include_shorts": False,
+    "include_live": False,
+    "show": "unwatched",
+    "scope": "my",
+    "library_source": "organic",
+}
+
+
+def _index_columns(db) -> list[str]:
+    # Key columns first, then the INCLUDE ones, in the index's own order.
+    return list(
+        db.execute(
+            text(
+                "SELECT a.attname FROM pg_index i "
+                "JOIN pg_class c ON c.oid = i.indexrelid "
+                "CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, n) "
+                "JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum "
+                "WHERE c.relname = :name ORDER BY k.n"
+            ),
+            {"name": INDEX},
+        ).scalars()
+    )
+
+
+def _video_columns(stmt) -> set[str]:
+    # The columns of `videos` the statement as SENT reads: the compiled SQL, not the expression tree,
+    # which still carries the projection a with_only_columns replaced.
+    sql = str(stmt.compile(dialect=postgresql.dialect()))
+    return set(re.findall(r"\bvideos\.(\w+)", sql))
+
+
+def _assert_covered(db, read: set[str]) -> None:
+    held = _index_columns(db)
+    assert held, f"{INDEX} is missing"
+    # It leads with channel_id, so it also serves every per-channel lookup the old index did.
+    assert held[0] == "channel_id"
+    assert read <= set(held), f"read but not in {INDEX}: {sorted(read - set(held))}"
+
+
+def test_the_channel_sums_read_only_columns_the_index_holds(db):
+    _assert_covered(db, _video_columns(channel_aggregates(["UC_x"])))
+
+
+def test_the_feed_sidebar_counts_read_only_columns_the_index_holds(db, make_user):
+    # feed_summary groups the default filter by channel, feed_years by publish date.
+    base, _rank = filtered_query(db, make_user(), **FEED_DEFAULTS)
+    _assert_covered(
+        db, _video_columns(base.with_only_columns(Video.channel_id, Video.published_at))
+    )

backend/tests/test_collation.py

@@ -0,0 +1,302 @@
+"""E30 S3: every A→Z list the server orders is in the reader's alphabet. The database image is Alpine,
+whose `en_US.utf8` is BYTE order: "Életrajzi" and "Ötödik" sorted after "Zorró" in the feed, the channel
+list, the Plex grid, the genre list. Hungarian puts "Ö" after "O" and "Cs" after "Cu". Needs the DB."""
+
+from fastapi.testclient import TestClient
+
+import app.state as state
+from app.auth import current_user
+from app.collation import sorted_words
+from app.db import get_db
+from app.main import app
+from app.models import (
+    Channel,
+    Playlist,
+    PlaylistItem,
+    PlexCollection,
+    PlexItem,
+    PlexLibrary,
+    Subscription,
+    User,
+    Video,
+)
+from datetime import datetime, timezone
+
+WORDS = ["Zorró", "Életrajzi", "Ötödik", "oroszlán", "Csillag", "Cukor"]
+HU = ["Cukor", "Csillag", "Életrajzi", "oroszlán", "Ötödik", "Zorró"]
+EN = ["Csillag", "Cukor", "Életrajzi", "oroszlán", "Ötödik", "Zorró"]
+
+
+def _user(db, lang: str) -> User:
+    user = User(email=f"collate-{lang}@example.com", preferences={"language": lang})
+    db.add(user)
+    db.flush()
+    return user
+
+
+def _client(db, user, monkeypatch, override_dep) -> TestClient:
+    monkeypatch.setattr(state, "_configured_cache", True)
+    override_dep(get_db, db.info["request"])
+    override_dep(current_user, lambda: user)
+    return TestClient(app)
+
+
+def test_words_sort_in_the_readers_alphabet(db):
+    assert sorted_words(db, WORDS, "hu") == HU
+    assert sorted_words(db, WORDS, "en") == EN
+    assert sorted_words(db, WORDS, "xx") == EN  # an unknown language sorts as English
+    assert sorted_words(db, [], "hu") == []
+
+
+def _seed_feed(db, user):
+    db.add(Channel(id="UCc", title="Channel"))
+    db.flush()
+    db.add(Subscription(user_id=user.id, channel_id="UCc", priority=0, hidden=False))
+    db.add_all(
+        Video(
+            id=f"v{i}",
+            channel_id="UCc",
+            published_at=datetime(2024, 1, i + 1, tzinfo=timezone.utc),
+            title=w,
+            is_short=False,
+            live_status="none",
+            via_search=False,
+            via_explore=False,
+        )
+        for i, w in enumerate(WORDS)
+    )
+    db.commit()
+
+
+def test_the_feed_title_sort_pages_in_the_readers_alphabet(db, monkeypatch, override_dep):
+    user = _user(db, "hu")
+    _seed_feed(db, user)
+    client = _client(db, user, monkeypatch, override_dep)
+
+    full = [it["title"] for it in client.get("/api/feed?sort=title&limit=50").json()["items"]]
+    assert full == HU
+    # The cursor compares with the same collated expression, so paging walks the same order.
+    walked: list[str] = []
+    cursor = None
+    for _ in range(len(WORDS)):
+        url = "/api/feed?sort=title&limit=2" + (f"&cursor={cursor}" if cursor else "")
+        body = client.get(url).json()
+        walked += [it["title"] for it in body["items"]]
+        cursor = body["next_cursor"]
+        if not body["has_more"]:
+            break
+    assert walked == HU
+    desc = client.get("/api/feed?sort=title_desc&limit=50").json()["items"]
+    assert [it["title"] for it in desc] == HU[::-1]
+
+
+def test_the_channel_list_is_in_the_readers_alphabet(db, monkeypatch, override_dep):
+    user = _user(db, "hu")
+    db.add_all(Channel(id=f"UC{i}", title=w) for i, w in enumerate(WORDS))
+    db.flush()
+    db.add_all(
+        Subscription(user_id=user.id, channel_id=f"UC{i}", priority=0, hidden=False)
+        for i in range(len(WORDS))
+    )
+    db.commit()
+    r = _client(db, user, monkeypatch, override_dep).get("/api/channels")
+    assert [c["title"] for c in r.json()] == HU
+
+
+def _seed_plex(db):
+    lib = PlexLibrary(plex_key="1", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    col = PlexCollection(rating_key="col1", library_id=lib.id, title="Set", child_count=len(WORDS))
+    db.add(col)
+    db.add_all(
+        PlexItem(
+            rating_key=f"m{i}",
+            library_id=lib.id,
+            kind="movie",
+            title=f"EN {i}",
+            title_hu=w,
+            year=2000,
+            genres_hu=[w],
+            collection_keys=["col1"],
+        )
+        for i, w in enumerate(WORDS)
+    )
+    db.commit()
+
+
+def _plex(db, monkeypatch, override_dep) -> TestClient:
+    user = _user(db, "hu")
+    _seed_plex(db)
+    return _client(db, user, monkeypatch, override_dep)
+
+
+def test_the_plex_grid_sorts_by_the_hungarian_title(db, monkeypatch, override_dep):
+    client = _plex(db, monkeypatch, override_dep)
+    grid = client.get("/api/plex/library?scope=movie&sort=title&sort_dir=asc&lang=hu").json()
+    assert [it["title"] for it in grid["items"]] == HU
+
+
+def test_the_plex_genre_list_is_in_the_readers_alphabet(db, monkeypatch, override_dep):
+    client = _plex(db, monkeypatch, override_dep)
+    facets = client.get("/api/plex/facets?scope=movie&lang=hu").json()
+    assert [g["value"] for g in facets["genres"]] == HU
+
+
+def test_a_collection_sorts_by_the_hungarian_title(db, monkeypatch, override_dep):
+    client = _plex(db, monkeypatch, override_dep)
+    members = client.get("/api/plex/collections/col1?sort=title&sort_dir=asc&lang=hu").json()
+    assert [it["title"] for it in members["items"]] == HU
+    # year ties everywhere, so the default (year) order falls through to the title tiebreak
+    default = client.get("/api/plex/collections/col1?lang=hu").json()
+    assert [it["title"] for it in default["items"]] == HU
+
+
+def _seed_discovery(db, user, synced: bool):
+    """Channels the user's playlist holds one video from each, not subscribed: discovery lists them,
+    count-tied, so the title decides. `synced=False` leaves them stubs, which sends the endpoint down
+    its enrich path — the one that re-sorts in Python and has to agree with the ORDER BY."""
+    pl = Playlist(user_id=user.id, name="Mix")
+    db.add(pl)
+    db.flush()
+    stamp = datetime(2024, 1, 1, tzinfo=timezone.utc) if synced else None
+    for i, w in enumerate(WORDS):
+        db.add(Channel(id=f"UCd{i}", title=w, details_synced_at=stamp))
+        db.flush()
+        db.add(
+            Video(
+                id=f"d{i}",
+                channel_id=f"UCd{i}",
+                published_at=datetime(2024, 1, 1, tzinfo=timezone.utc),
+                title="x",
+                is_short=False,
+                live_status="none",
+                via_search=False,
+                via_explore=False,
+            )
+        )
+        db.flush()
+        db.add(PlaylistItem(playlist_id=pl.id, video_id=f"d{i}", position=i))
+    db.commit()
+
+
+def test_channel_discovery_is_in_the_readers_alphabet(db, monkeypatch, override_dep):
+    user = _user(db, "hu")
+    _seed_discovery(db, user, synced=True)
+    r = _client(db, user, monkeypatch, override_dep).get("/api/channels/discovery")
+    assert [c["title"] for c in r.json()] == HU
+
+
+def test_channel_discovery_keeps_that_order_after_enriching(db, monkeypatch, override_dep):
+    import app.routes.channels as channels
+
+    class FakeYouTube:
+        def __init__(self, *a, **k): ...
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+        def get_channels(self, ids):
+            return []
+
+    monkeypatch.setattr(channels, "YouTubeClient", FakeYouTube)
+    monkeypatch.setattr(channels, "apply_channel_details", lambda *a, **k: None)
+    user = _user(db, "hu")
+    _seed_discovery(db, user, synced=False)
+    r = _client(db, user, monkeypatch, override_dep).get("/api/channels/discovery")
+    assert [c["title"] for c in r.json()] == HU
+
+
+# --- The other lists the server puts in the reader's alphabet (E30 review): each call site, once. ---
+
+
+def _others(db, n_offset: int = 0) -> list[User]:
+    users = [
+        User(email=f"{w.lower()}@example.com", display_name=w) for w in WORDS
+    ]  # emails and names in WORDS' order
+    db.add_all(users)
+    db.flush()
+    return users
+
+
+def test_the_share_and_message_recipients_are_in_the_readers_alphabet(
+    db, monkeypatch, override_dep
+):
+    from app.models import MessageKey
+
+    user = _user(db, "hu")
+    others = _others(db)
+    db.add_all(
+        MessageKey(
+            user_id=u.id,
+            public_key="k",
+            wrapped_private_key="w",
+            salt="s",
+            wrap_iv="i",
+            key_check="c",
+        )
+        for u in others
+    )
+    db.commit()
+    client = _client(db, user, monkeypatch, override_dep)
+    emails = [r["email"] for r in client.get("/api/downloads/recipients").json()]
+    assert emails == [f"{w.lower()}@example.com" for w in HU]
+    names = [r["name"] for r in client.get("/api/messages/users").json()]
+    assert names == HU
+
+
+def test_the_blocked_channels_are_in_the_readers_alphabet(db, monkeypatch, override_dep):
+    from app.models import BlockedChannel
+
+    user = _user(db, "hu")
+    db.add_all(Channel(id=f"UC{i}", title=w) for i, w in enumerate(WORDS))
+    db.flush()
+    db.add_all(BlockedChannel(user_id=user.id, channel_id=f"UC{i}") for i in range(len(WORDS)))
+    db.commit()
+    r = _client(db, user, monkeypatch, override_dep).get("/api/channels/blocked/list")
+    assert [c["title"] for c in r.json()] == HU
+
+
+def test_the_plex_libraries_and_collections_are_in_the_readers_alphabet(
+    db, monkeypatch, override_dep
+):
+    user = _user(db, "hu")
+    libs = [
+        PlexLibrary(plex_key=str(i), title=w, kind="movie", enabled=True)
+        for i, w in enumerate(WORDS)
+    ]
+    db.add_all(libs)
+    db.flush()
+    db.add_all(
+        PlexCollection(rating_key=f"c{i}", library_id=libs[0].id, title=w, child_count=1)
+        for i, w in enumerate(WORDS)
+    )
+    db.commit()
+    client = _client(db, user, monkeypatch, override_dep)
+    assert [lib["title"] for lib in client.get("/api/plex/libraries").json()["libraries"]] == HU
+    cols = client.get("/api/plex/collections").json()["collections"]
+    assert [c["title"] for c in cols] == HU
+
+
+def test_a_persons_titles_of_one_year_are_in_the_readers_alphabet(db, monkeypatch, override_dep):
+    user = _user(db, "hu")
+    lib = PlexLibrary(plex_key="1", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    db.add_all(
+        PlexItem(
+            rating_key=f"m{i}",
+            library_id=lib.id,
+            kind="movie",
+            title=f"EN {i}",
+            title_hu=w,
+            year=2000,
+            cast_names=["Anna"],
+        )
+        for i, w in enumerate(WORDS)
+    )
+    db.commit()
+    body = _client(db, user, monkeypatch, override_dep).get("/api/plex/person/Anna?lang=hu").json()
+    assert [m["title"] for m in body["movies"]] == HU

backend/tests/test_discover.py

@@ -180,7 +180,7 @@ def test_continue_watching_merges_both_sources_by_recency(db):
     )
     db.commit()
 
-    got = rails.continue_watching(db, user)
+    got = rails.continue_watching(db, user, lang="en")
     assert [(c["source"], c["id"]) for c in got] == [("plex", "pm1"), ("youtube", "vmed")]
     assert got[0]["remaining_seconds"] == 100 * 60 - 600
 
@@ -208,7 +208,7 @@ def test_continue_watching_is_youtube_only_when_plex_is_off(db):
         ]
     )
     db.commit()
-    assert {c["source"] for c in rails.continue_watching(db, user)} == {"youtube"}
+    assert {c["source"] for c in rails.continue_watching(db, user, lang="en")} == {"youtube"}
 
 
 def test_the_resume_rail_obeys_the_channel_blocklist(db):
@@ -227,13 +227,13 @@ def test_the_resume_rail_obeys_the_channel_blocklist(db):
         )
     )
     db.commit()
-    assert [c["id"] for c in rails.continue_watching(db, user)] == ["vmed"]
+    assert [c["id"] for c in rails.continue_watching(db, user, lang="en")] == ["vmed"]
 
     db.add(BlockedChannel(user_id=user.id, channel_id=ch.id))
     db.commit()
-    assert rails.continue_watching(db, user) == []
+    assert rails.continue_watching(db, user, lang="en") == []
     # And so the hero, whose resume tier draws from that rail, has nothing to offer either.
-    assert hero.pick(db, user, "any", 0) is None
+    assert hero.pick(db, user, "any", 0, lang="en") is None
 
 
 def test_a_null_timestamp_sorts_last(db):
@@ -263,7 +263,7 @@ def test_a_null_timestamp_sorts_last(db):
         ]
     )
     db.commit()
-    got = rails.continue_watching(db, user)
+    got = rails.continue_watching(db, user, lang="en")
     assert got[0]["id"] == "vshort"
     assert len(got) == 3
 
@@ -283,7 +283,7 @@ def test_hero_prefers_resume_and_labels_the_tier(db):
         )
     )
     db.commit()
-    got = hero.pick(db, user, "any", seed=1)
+    got = hero.pick(db, user, "any", seed=1, lang="en")
     assert got["tier"] == "resume"
     assert got["card"]["id"] == "vmed"
 
@@ -302,7 +302,7 @@ def test_hero_skips_a_resume_that_does_not_fit_the_budget(db):
         )
     )
     db.commit()
-    got = hero.pick(db, user, "short", seed=1)
+    got = hero.pick(db, user, "short", seed=1, lang="en")
     assert got["tier"] == "surprise"
     assert got["card"]["duration_seconds"] <= BANDS["short"][1]
 
@@ -312,7 +312,7 @@ def test_hero_falls_back_to_the_shelf_before_guessing(db):
     user, ch = _seed_yt(db)
     db.add(ComfortPin(user_id=user.id, video_id="vmed", position=0))
     db.commit()
-    got = hero.pick(db, user, "medium", seed=1)
+    got = hero.pick(db, user, "medium", seed=1, lang="en")
     assert got["tier"] == "comfort"
     assert got["card"]["id"] == "vmed"
 
@@ -332,7 +332,7 @@ def test_hero_resolves_a_show_to_the_episode_that_would_play(db):
         )
     )
     db.commit()
-    got = hero.pick(db, user, "any", seed=1)
+    got = hero.pick(db, user, "any", seed=1, lang="en")
     assert got["tier"] == "resume"
     assert got["card"]["kind"] == "episode"
     assert got["card"]["id"] == "ps1e2"  # ep1 is finished → ep2 is what plays
@@ -345,17 +345,19 @@ def test_hero_is_none_when_nothing_fits(db):
     user, ch = _seed_yt(db)
     db.execute(text("DELETE FROM videos WHERE id = 'vlong'"))
     db.commit()
-    assert hero.pick(db, user, "long", seed=1) is None
+    assert hero.pick(db, user, "long", seed=1, lang="en") is None
 
 
 def test_surprise_is_reproducible_for_a_seed(db):
     """The reroll button depends on this: one seed drives both sources, so the same seed must give
     the same answer and a different seed must be free to give another."""
     user, _ = _seed_yt(db)
-    a = rails.surprise(db, user, "any", seed=7, limit=3)
-    b = rails.surprise(db, user, "any", seed=7, limit=3)
+    a = rails.surprise(db, user, "any", seed=7, limit=3, lang="en")
+    b = rails.surprise(db, user, "any", seed=7, limit=3, lang="en")
     assert [c["id"] for c in a] == [c["id"] for c in b]
-    seeds = {tuple(c["id"] for c in rails.surprise(db, user, "any", s, 3)) for s in range(12)}
+    seeds = {
+        tuple(c["id"] for c in rails.surprise(db, user, "any", s, 3, lang="en")) for s in range(12)
+    }
     assert len(seeds) > 1  # the seed actually reaches the ordering
 
 
@@ -374,7 +376,9 @@ def test_surprise_never_offers_something_already_started(db):
         )
     )
     db.commit()
-    assert "vlong" not in {c["id"] for c in rails.surprise(db, user, "long", seed=3, limit=5)}
+    assert "vlong" not in {
+        c["id"] for c in rails.surprise(db, user, "long", seed=3, limit=5, lang="en")
+    }
 
 
 def test_the_seed_decides_which_source_leads(db):
@@ -384,7 +388,9 @@ def test_the_seed_decides_which_source_leads(db):
     user, _ = _seed_yt(db)
     _seed_plex(db, user)
     _enable_plex(db)
-    leaders = {rails.surprise(db, user, "any", s, limit=1)[0]["source"] for s in range(6)}
+    leaders = {
+        rails.surprise(db, user, "any", s, limit=1, lang="en")[0]["source"] for s in range(6)
+    }
     assert leaders == {"youtube", "plex"}
 
 
@@ -413,10 +419,10 @@ def test_the_reroll_must_be_able_to_move_past_the_resume_tier(db):
     )
     db.commit()
 
-    first = hero.pick(db, user, "any", seed=1)
+    first = hero.pick(db, user, "any", seed=1, lang="en")
     assert first["card"]["id"] == "vmed"
     # Same seed, same everything — only the exclusion differs.
-    second = hero.pick(db, user, "any", seed=1, exclude={"youtube:vmed"})
+    second = hero.pick(db, user, "any", seed=1, exclude={"youtube:vmed"}, lang="en")
     assert second["card"]["id"] == "vshort"
 
 
@@ -438,7 +444,7 @@ def test_the_reroll_rotates_which_tier_answers(db):
     )
     db.add(ComfortPin(user_id=user.id, video_id="vlong", position=0))
     db.commit()
-    tiers = [hero.pick(db, user, "any", seed=1, start=n)["tier"] for n in range(4)]
+    tiers = [hero.pick(db, user, "any", seed=1, start=n, lang="en")["tier"] for n in range(4)]
     assert tiers == ["resume", "comfort", "surprise", "resume"]
 
 
@@ -447,7 +453,7 @@ def test_the_rotation_still_falls_through_an_empty_tier(db):
     Here there is no shelf at all, so the comfort-led press has to answer from somewhere else."""
     user, _ = _seed_yt(db)
     assert db.execute(select(func.count()).select_from(ComfortPin)).scalar_one() == 0
-    got = hero.pick(db, user, "any", seed=1, start=1)
+    got = hero.pick(db, user, "any", seed=1, start=1, lang="en")
     assert got is not None and got["tier"] != "comfort"
 
 
@@ -468,10 +474,10 @@ def test_excluding_a_show_also_excludes_the_episode_it_resolves_to(db):
     )
     db.commit()
 
-    shown = hero.pick(db, user, "any", seed=1)
+    shown = hero.pick(db, user, "any", seed=1, lang="en")
     assert shown["card"]["id"] == "ps1e1"  # the show resolved to its in-progress episode
     # Excluding what the USER saw — the show — must move the tier on, not return the episode again.
-    after = hero.pick(db, user, "any", seed=1, exclude={"plex:ps1"})
+    after = hero.pick(db, user, "any", seed=1, exclude={"plex:ps1"}, lang="en")
     assert after is None or after["card"]["id"] != "ps1e1"
 
 
@@ -518,7 +524,7 @@ def test_shelf_resolves_a_channel_to_its_newest_unwatched_video(db):
     user, ch = _seed_yt(db)
     db.add(ComfortPin(user_id=user.id, channel_id=ch.id, position=0))
     db.commit()
-    (card,) = pins.shelf(db, user)
+    (card,) = pins.shelf(db, user, lang="en")
     assert card["kind"] == "channel"
     assert card["unwatched_count"] == 3
     assert card["next"]["id"] == "vshort"  # newest
@@ -538,7 +544,7 @@ def test_shelf_resolves_a_playlist_to_its_first_unwatched_item(db):
     db.add(VideoState(user_id=user.id, video_id="vshort", status="watched", watched_at=NOW))
     db.add(ComfortPin(user_id=user.id, playlist_id=pl.id, position=0))
     db.commit()
-    (card,) = pins.shelf(db, user)
+    (card,) = pins.shelf(db, user, lang="en")
     assert card["kind"] == "playlist"
     assert card["item_count"] == 2
     assert card["next"]["id"] == "vmed"
@@ -585,7 +591,7 @@ def test_the_shelf_resolves_each_channel_and_playlist_on_its_own_terms(db):
 
     got = [
         (c.get("unwatched_count", c.get("item_count")), (c["next"] or {}).get("id"))
-        for c in pins.shelf(db, user)
+        for c in pins.shelf(db, user, lang="en")
     ]
     assert got == [(3, "vshort"), (1, "vother"), (1, "vlong"), (0, None)]
 
@@ -601,14 +607,14 @@ def test_the_shelf_costs_the_same_queries_for_one_pin_or_many(db):
     db.add(ComfortPin(user_id=user.id, channel_id=ch.id, position=0))
     db.add(ComfortPin(user_id=user.id, playlist_id=lists[0].id, position=1))
     db.commit()
-    few = _count_statements(db, lambda: pins.shelf(db, user))
+    few = _count_statements(db, lambda: pins.shelf(db, user, lang="en"))
 
     for i, c in enumerate(extra):
         db.add(ComfortPin(user_id=user.id, channel_id=c.id, position=10 + i))
     for i, p in enumerate(lists[1:]):
         db.add(ComfortPin(user_id=user.id, playlist_id=p.id, position=20 + i))
     db.commit()
-    assert _count_statements(db, lambda: pins.shelf(db, user)) == few
+    assert _count_statements(db, lambda: pins.shelf(db, user, lang="en")) == few
 
 
 def test_a_pinned_video_survives_leaving_the_feed_scope(db):
@@ -619,7 +625,7 @@ def test_a_pinned_video_survives_leaving_the_feed_scope(db):
     db.commit()
     db.execute(delete(Subscription))
     db.commit()
-    (card,) = pins.shelf(db, user)
+    (card,) = pins.shelf(db, user, lang="en")
     assert card["id"] == "vmed"
     assert card["next"]["id"] == "vmed"
 
@@ -633,7 +639,9 @@ def test_the_plex_surprise_obeys_the_time_budget(db):
     _seed_plex(db, user)
     _enable_plex(db)
     drawn = lambda budget: {  # noqa: E731
-        (c["source"], c["id"]) for s in range(6) for c in rails.surprise(db, user, budget, s, 5)
+        (c["source"], c["id"])
+        for s in range(6)
+        for c in rails.surprise(db, user, budget, s, 5, lang="en")
     }
     assert ("plex", "pm1") not in drawn("short")
     # …and it IS offered where it fits, so this cannot pass by the rail being empty.
@@ -658,7 +666,9 @@ def test_the_plex_surprise_never_offers_something_already_started(db):
     )
     db.commit()
     drawn = {
-        (c["source"], c["id"]) for s in range(6) for c in rails.surprise(db, user, "long", s, 5)
+        (c["source"], c["id"])
+        for s in range(6)
+        for c in rails.surprise(db, user, "long", s, 5, lang="en")
     }
     assert ("plex", "pm1") not in drawn
 
@@ -682,7 +692,7 @@ def test_a_new_pin_lands_at_the_end_even_after_a_hole(db):
 
     db.add(ComfortPin(user_id=user.id, channel_id=ch.id, position=pins.next_position(db, user)))
     db.commit()
-    assert [c["kind"] for c in pins.shelf(db, user)] == ["video", "channel"]
+    assert [c["kind"] for c in pins.shelf(db, user, lang="en")] == ["video", "channel"]
     positions = (
         db.execute(select(ComfortPin.position).order_by(ComfortPin.position)).scalars().all()
     )
@@ -695,7 +705,7 @@ def test_a_self_playing_pin_does_not_reference_itself(db):
     user, _ = _seed_yt(db)
     db.add(ComfortPin(user_id=user.id, video_id="vmed", position=0))
     db.commit()
-    (card,) = pins.shelf(db, user)
+    (card,) = pins.shelf(db, user, lang="en")
     assert card["next"] is not card
     assert "next" not in card["next"]
 
@@ -718,7 +728,7 @@ def test_the_resume_rail_says_what_would_actually_play(db):
         )
     )
     db.commit()
-    rail = rails.continue_watching(db, user)
+    rail = rails.continue_watching(db, user, lang="en")
     tile = next(c for c in rail if c["kind"] == "show")
     assert tile["id"] == "ps1"  # still the show
     assert tile["next"]["kind"] == "episode"
@@ -762,7 +772,7 @@ def test_only_a_show_row_pays_for_a_resolution(db):
     )
     db.commit()
 
-    rail = rails.continue_watching(db, user)
+    rail = rails.continue_watching(db, user, lang="en")
     # A video, a movie and a show — one row of each kind that can appear here, so the assertion below
     # actually exercises both sides of the equality.
     assert {c["kind"] for c in rail} == {"video", "movie", "show"}
@@ -778,7 +788,7 @@ def test_next_episode_takes_an_episode_with_no_state_row_at_all(db):
     _, show, ep1 = _seed_plex(db, user)
     db.add(PlexState(user_id=user.id, item_id=ep1.id, status="watched", watched_at=NOW))
     db.commit()  # ep2 has NO PlexState row
-    assert queries.next_episode(db, user.id, show.id)["id"] == "ps1e2"
+    assert queries.next_episode(db, user.id, show.id, lang="en")["id"] == "ps1e2"
 
 
 def test_a_finished_show_starts_again_from_the_top(db):
@@ -793,7 +803,7 @@ def test_a_finished_show_starts_again_from_the_top(db):
         ]
     )
     db.commit()
-    assert queries.next_episode(db, user.id, show.id)["id"] == "ps1e1"
+    assert queries.next_episode(db, user.id, show.id, lang="en")["id"] == "ps1e1"
 
 
 def test_next_episode_agrees_with_the_show_page_when_two_are_in_progress(db):
@@ -825,12 +835,16 @@ def test_next_episode_agrees_with_the_show_page_when_two_are_in_progress(db):
     )
     db.commit()
 
-    got = queries.next_episode(db, user.id, show.id)
+    got = queries.next_episode(db, user.id, show.id, lang="en")
     assert got["id"] == "ps1e2"
     # Asserted against the other implementation rather than against a literal, so the two cannot
     # drift apart again without this failing.
     ordered = [
-        leaf_card(ep, db.execute(select(PlexState).where(PlexState.item_id == ep.id)).scalar_one())
+        leaf_card(
+            ep,
+            db.execute(select(PlexState).where(PlexState.item_id == ep.id)).scalar_one(),
+            lang="en",
+        )
         for ep in (ep1, ep2)
     ]
     assert rollup.rollup(ordered)["resume"]["id"] == got["id"]
@@ -848,7 +862,7 @@ def test_next_episode_prefers_the_one_in_progress(db):
         ]
     )
     db.commit()
-    assert queries.next_episode(db, user.id, show.id)["id"] == "ps1e2"
+    assert queries.next_episode(db, user.id, show.id, lang="en")["id"] == "ps1e2"
 
 
 # ── HTTP surface ──────────────────────────────────────────────────────────────────────────────────

backend/tests/test_download_share_notice.py

@@ -0,0 +1,41 @@
+"""E30: the "shared with you" notice carries the download's title in its data, so the client can name
+the notice in the reader's language. Its stored title is an English sentence ("Cats was shared with
+you") — the only place the title lived, so a Hungarian reader got the English. Needs the DB."""
+
+from sqlalchemy import select
+
+from app.models import DownloadJob, MediaAsset, Notification
+
+
+def test_a_share_notice_carries_the_title_and_the_sharer(db, make_user, as_user):
+    owner = make_user("owner@example.com")
+    friend = make_user("friend@example.com")
+    asset = MediaAsset(
+        source_kind="url", source_ref="share-e30", format_sig="sig", status="ready", ref_count=1
+    )
+    db.add(asset)
+    db.flush()
+    job = DownloadJob(
+        user_id=owner.id,
+        asset_id=asset.id,
+        source_kind="url",
+        source_ref="share-e30",
+        status="done",
+        queue_pos=1,
+        profile_snapshot={},
+        display_name="Cats",
+    )
+    db.add(job)
+    db.commit()
+
+    r = as_user(owner).post(f"/api/downloads/{job.id}/share", json={"email": "friend@example.com"})
+    assert r.status_code == 200, r.text
+
+    notice = db.execute(select(Notification).where(Notification.user_id == friend.id)).scalar_one()
+    assert notice.type == "download_shared"
+    assert notice.data == {
+        "kind": "download_shared",
+        "from": "owner@example.com",
+        "job_id": job.id,
+        "title": "Cats",
+    }

backend/tests/test_feed_relevance_window.py

@@ -0,0 +1,133 @@
+"""Relevance ranks only the newest RANK_WINDOW matches (E31), DB-lane.
+
+A broad word ("a") matched most of the prod library and ts_rank read every match's tsvector: 6.8 s a page.
+The ranking now covers the newest RANK_WINDOW matches and the rest follow newest first. The window's start
+rides the cursor, so a video ingested mid-scroll cannot push a row behind the cursor and repeat it.
+"""
+
+import base64
+import json
+from datetime import datetime, timezone
+
+import pytest
+
+from app import feedquery
+from app.models import Channel, Subscription, User, Video
+
+
+def _video(vid: str, day: int, title: str) -> Video:
+    return Video(
+        id=vid,
+        channel_id="UCw",
+        published_at=datetime(2024, 1, day, tzinfo=timezone.utc),
+        title=title,
+        is_short=False,
+        live_status="none",
+        via_search=False,
+        via_explore=False,
+    )
+
+
+def _seed(db) -> User:
+    db.add(Channel(id="UCw", title="Window"))
+    user = User(email="window@example.com", email_verified=True)
+    db.add(user)
+    db.flush()
+    db.add(Subscription(user_id=user.id, channel_id="UCw", priority=0, hidden=False))
+    # m1 is the oldest and the strongest match, m4 the strongest of the newest three; the rest tie on one
+    # title "foo" each (ts_rank counts occurrences, it does not normalise by length).
+    db.add_all(
+        [
+            _video("m1", 1, "foo foo foo foo foo"),
+            _video("m2", 2, "foo and some other words here"),
+            _video("m3", 3, "foo plus some filler words"),
+            _video("m4", 4, "foo foo foo"),
+            _video("m5", 5, "foo with a longer title"),
+            _video("m6", 6, "foo with yet another title"),
+        ]
+    )
+    db.commit()
+    return user
+
+
+def _ids(client, cursor=None, limit=50):
+    url = f"/api/feed?q=foo&sort=relevance&limit={limit}"
+    if cursor:
+        url += f"&cursor={cursor}"
+    resp = client.get(url)
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    return [it["id"] for it in body["items"]], body["next_cursor"]
+
+
+def test_a_specific_word_ranks_every_match(db, as_user):
+    client = as_user(_seed(db))
+    ids, _ = _ids(client)
+    assert ids[:2] == ["m1", "m4"], ids
+
+
+def test_a_broad_word_ranks_the_newest_window_and_the_rest_follow_newest_first(
+    db, as_user, monkeypatch
+):
+    monkeypatch.setattr(feedquery, "RANK_WINDOW", 3)
+    client = as_user(_seed(db))
+    ids, _ = _ids(client)
+    assert ids[0] == "m4", ids  # the strongest of the newest three
+    assert sorted(ids[:3]) == ["m4", "m5", "m6"], ids
+    assert ids[3:] == ["m3", "m2", "m1"], ids  # past the window: newest first, m1 not ranked
+
+
+def test_paging_keeps_the_window_page_one_ranked_against(db, as_user, monkeypatch):
+    monkeypatch.setattr(feedquery, "RANK_WINDOW", 3)
+    client = as_user(_seed(db))
+    full, _ = _ids(client)
+
+    first, cursor = _ids(client, limit=2)
+    assert first == full[:2]
+    # A newer match lands mid-scroll. Ranked against a recomputed window, m4 (shown on page one) would
+    # fall out of it to rank 0, sort behind the cursor and come back on page two.
+    db.add(_video("m7", 7, "foo arriving while the reader scrolls"))
+    db.commit()
+
+    walked = list(first)
+    while cursor:
+        page, cursor = _ids(client, cursor, limit=2)
+        walked.extend(page)
+    assert len(walked) == len(set(walked)), walked
+    assert set(full) <= set(walked), walked
+
+
+@pytest.mark.parametrize(
+    ("window", "limit"),
+    # 3: the page is read as its two halves (the window ranked, the rest newest first), and pages of 2
+    # and 3 cross the window's edge mid-page and exactly at it. 2000: one ranked query.
+    [(3, 2), (3, 3), (2000, 2)],
+)
+def test_cursor_walk_matches_the_unpaged_order(db, as_user, monkeypatch, window, limit):
+    monkeypatch.setattr(feedquery, "RANK_WINDOW", window)
+    client = as_user(_seed(db))
+    full, _ = _ids(client)
+    if window == 3:
+        assert full == ["m4", "m6", "m5", "m3", "m2", "m1"]
+    walked, cursor = _ids(client, limit=limit)
+    while cursor:
+        page, cursor = _ids(client, cursor, limit=limit)
+        walked.extend(page)
+    assert walked == full
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        {"k": [5, None], "id": "m1", "w": "2024-01-01T00:00:00+00:00"},  # null published_at
+        {"k": [5, "2024-01-03T00:00:00+00:00"], "id": "m1", "w": "2024-01-01T00:00:00"},  # naive w
+        {"k": [5, "2024-01-03T00:00:00"], "id": "m1", "w": "2024-01-01T00:00:00+00:00"},  # naive k
+    ],
+)
+def test_a_hand_made_relevance_cursor_is_refused_not_a_crash(db, as_user, payload):
+    # The page halves compare the cursor's timestamp with the window's in Python: a null or a naive
+    # one raised there, past the route's 400 — a 500 (E31 review 2).
+    client = as_user(_seed(db))
+    cursor = base64.urlsafe_b64encode(json.dumps(payload).encode()).decode()
+    resp = client.get(f"/api/feed?q=foo&sort=relevance&limit=2&cursor={cursor}")
+    assert resp.status_code == 400, resp.text

backend/tests/test_feed_sort_indexes.py

@@ -0,0 +1,100 @@
+"""Every feed sort on a videos column rides an index, and an ICU upgrade rebuilds the title ones (E31 S4e).
+
+Without an index in the exact ORDER BY, each feed page read the whole videos heap and kept a top-N
+(prod: 350 ms a page for views/duration, 550–780 ms for title). Migration 0096 adds one per direction
+and per reader language. The planner is told it may not sort or scan the table, so a plan that still
+sorts it whole means no index matches the ORDER BY `feedquery.order_by` builds: a key, direction, NULLS
+rule or collation changed on one side only. An Incremental Sort is fine: the index gives the key's order
+and only its ties are sorted by id (`newest`/`oldest` ride the published_at indexes that way). DB lane.
+"""
+
+import re
+
+import pytest
+from sqlalchemy import select, text
+from sqlalchemy.dialects import postgresql
+
+from app import collation
+from app.db import engine
+from app.feedquery import order_by, sort_keys
+from app.models import Video
+
+VIDEO_SORTS = [
+    "newest",
+    "oldest",
+    "views",
+    "views_asc",
+    "duration_desc",
+    "duration_asc",
+    "title",
+    "title_desc",
+]
+
+
+def _plan(db, sort: str, lang: str) -> str:
+    stmt = select(Video.id).order_by(*order_by(sort_keys(sort, 0, None, lang))).limit(60)
+    sql = str(stmt.compile(dialect=postgresql.dialect(), compile_kwargs={"literal_binds": True}))
+    db.execute(text("SET LOCAL enable_seqscan = off"))
+    db.execute(text("SET LOCAL enable_sort = off"))
+    db.execute(text("SET LOCAL enable_bitmapscan = off"))
+    return "\n".join(db.execute(text(f"EXPLAIN {sql}")).scalars())
+
+
+@pytest.mark.parametrize("lang", sorted(collation.ICU))
+@pytest.mark.parametrize("sort", VIDEO_SORTS)
+def test_the_sort_walks_an_index(db, sort, lang):
+    plan = _plan(db, sort, lang)
+    db.rollback()
+    full_sort = re.search(r"(?<!Incremental )Sort  \(", plan)
+    assert not full_sort, f"{sort} ({lang}) sorts the table:\n{plan}"
+    assert "Index Scan" in plan or "Index Only Scan" in plan, plan
+
+
+def _drifted(db) -> list[str]:
+    return list(
+        db.execute(
+            text(
+                "SELECT collname FROM pg_collation WHERE collname = ANY(:names) "
+                "AND collversion IS DISTINCT FROM pg_collation_actual_version(oid)"
+            ),
+            {"names": list(collation.ICU.values())},
+        ).scalars()
+    )
+
+
+def _files(db) -> dict[str, int]:
+    return dict(
+        db.execute(
+            text("SELECT relname, relfilenode FROM pg_class WHERE relname LIKE 'ix_videos_title_%'")
+        ).all()
+    )
+
+
+def test_an_icu_upgrade_rebuilds_the_title_indexes(db):
+    # What an image update with a newer ICU looks like from inside: the recorded version no longer
+    # matches the library's (the test database runs as the bootstrap superuser, as the app's does).
+    db.execute(text("UPDATE pg_collation SET collversion = '0.0' WHERE collname = 'hu-x-icu'"))
+    db.commit()
+    try:
+        assert _drifted(db) == ["hu-x-icu"]
+        before = _files(db)
+        # A concurrent rebuild waits for every open transaction, this session's too.
+        db.rollback()
+        rebuilt = collation.heal_drift(engine)
+        assert sorted(rebuilt) == ["ix_videos_title_hu", "ix_videos_title_hu_desc"]
+        after = _files(db)
+        # Rebuilt = written to new files; the English pair, on an unchanged ICU, is left alone.
+        assert {n for n in before if before[n] != after[n]} == set(rebuilt)
+        assert _drifted(db) == []
+    finally:
+        db.execute(
+            text(
+                "UPDATE pg_collation SET collversion = pg_collation_actual_version(oid) "
+                "WHERE collname = 'hu-x-icu'"
+            )
+        )
+        db.commit()
+
+
+def test_no_drift_rebuilds_nothing(db):
+    assert collation.heal_drift(engine) == []

backend/tests/test_messages_welcome.py

@@ -0,0 +1,53 @@
+"""E31 S1: the welcome message is rendered once, when the account is created, in the language of that day.
+An account that switched language afterwards kept reading it in the old one (the owner's: English under a
+Hungarian UI). It is served in the reader's language now; any other system message stays as stored.
+Needs the DB."""
+
+from fastapi.testclient import TestClient
+
+import app.state as state
+from app.auth import current_user
+from app.db import get_db
+from app.main import app
+from app.models import Message, User
+from app.routes.messages import WELCOME
+
+
+def _client(db, user, monkeypatch, override_dep) -> TestClient:
+    monkeypatch.setattr(state, "_configured_cache", True)
+    override_dep(get_db, db.info["request"])
+    override_dep(current_user, lambda: user)
+    return TestClient(app)
+
+
+def _user_with_english_welcome(db) -> User:
+    """An account whose welcome was written in English, then switched to Hungarian."""
+    user = User(email="welcome-hu@example.com", preferences={"language": "hu"})
+    db.add(user)
+    db.flush()
+    db.add(Message(kind="system", sender_id=None, recipient_id=user.id, body=WELCOME["en"]))
+    db.commit()
+    return user
+
+
+def test_the_welcome_is_read_in_the_readers_language(db, monkeypatch, override_dep):
+    user = _user_with_english_welcome(db)
+    client = _client(db, user, monkeypatch, override_dep)
+
+    thread = client.get("/api/messages/conversations/0").json()["items"]
+    assert [m["body"] for m in thread] == [WELCOME["hu"]]
+
+    convs = client.get("/api/messages/conversations").json()["items"]
+    assert [c["last_message"]["body"] for c in convs if c["partner"]["id"] == 0] == [WELCOME["hu"]]
+
+
+def test_another_system_message_is_served_as_stored(db, monkeypatch, override_dep):
+    user = _user_with_english_welcome(db)
+    db.add(
+        Message(kind="system", sender_id=None, recipient_id=user.id, body="Maintenance tonight.")
+    )
+    db.commit()
+    client = _client(db, user, monkeypatch, override_dep)
+
+    bodies = [m["body"] for m in client.get("/api/messages/conversations/0").json()["items"]]
+    assert bodies == [WELCOME["hu"], "Maintenance tonight."]

backend/tests/test_migration_rerun_invalid_index.py

@@ -0,0 +1,53 @@
+"""A concurrent index build that failed part-way, then re-run (E31 S5 review), DB-lane.
+
+CREATE INDEX CONCURRENTLY that fails leaves an INVALID index under its name, and alembic_version is not
+stamped, so the next start runs the migration again. `IF NOT EXISTS` matched the name and kept the
+leftover, which the planner never uses; 0095 then dropped the old channel_id index, leaving `videos`
+with no usable one. A re-run now rebuilds the leftover and drops the old index only once the new one is
+valid.
+"""
+
+from alembic import command
+from alembic.config import Config
+from sqlalchemy import text
+
+from app.db import engine
+
+
+def _index(name: str) -> tuple[bool, str] | None:
+    with engine.connect() as conn:
+        row = conn.execute(
+            text(
+                "SELECT i.indisvalid, pg_get_indexdef(i.indexrelid) FROM pg_index i "
+                "JOIN pg_class c ON c.oid = i.indexrelid WHERE c.relname = :name"
+            ),
+            {"name": name},
+        ).first()
+    return None if row is None else (bool(row[0]), row[1])
+
+
+def _leave_invalid(name: str) -> None:
+    """What a build that failed part-way leaves behind: the name taken, the index INVALID."""
+    with engine.connect().execution_options(isolation_level="AUTOCOMMIT") as conn:
+        conn.execute(text(f"CREATE INDEX {name} ON videos (id)"))
+        conn.execute(
+            text(f"UPDATE pg_index SET indisvalid = false WHERE indexrelid = '{name}'::regclass")
+        )
+
+
+def test_a_rerun_rebuilds_an_invalid_leftover_before_dropping_the_old_index(db):
+    db.rollback()  # CONCURRENTLY waits for every open transaction, this session's too
+    cfg = Config("alembic.ini")
+    command.downgrade(cfg, "0094_plex_genres_hu_everywhere")
+    try:
+        _leave_invalid("ix_videos_channel_pub_cover")
+        _leave_invalid("ix_videos_views_desc")
+    finally:
+        command.upgrade(cfg, "head")
+
+    cover = _index("ix_videos_channel_pub_cover")
+    assert cover is not None and cover[0], cover
+    assert "INCLUDE (duration_seconds" in cover[1]
+    assert _index("ix_videos_channel_pub_desc") is None
+    views = _index("ix_videos_views_desc")
+    assert views is not None and views[0] and "view_count DESC NULLS LAST" in views[1], views

backend/tests/test_my_status_deep.py

@@ -0,0 +1,33 @@
+"""The Stats page's "Full history: done / requested" ratio counts the SAME channels on both sides — the
+ones this user asked full history for. The numerator used to count every subscribed channel whose
+back-catalog was complete (another user had asked, or the channel was short), so the page read
+"342/329". "Channels without full history yet" still counts every subscribed channel. Needs the DB."""
+
+from app.models import Channel, Subscription
+
+
+def test_full_history_ratio_counts_only_the_requested_channels(db, make_user, as_user):
+    user = make_user("deep@example.com")
+    db.add_all(
+        [
+            Channel(id="UCreqdone", title="Requested, done", backfill_done=True),
+            Channel(id="UCreqopen", title="Requested, pending", backfill_done=False),
+            Channel(id="UCdone", title="Not requested, done anyway", backfill_done=True),
+            Channel(id="UCopen", title="Not requested, pending", backfill_done=False),
+        ]
+    )
+    db.flush()
+    db.add_all(
+        [
+            Subscription(user_id=user.id, channel_id="UCreqdone", deep_requested=True),
+            Subscription(user_id=user.id, channel_id="UCreqopen", deep_requested=True),
+            Subscription(user_id=user.id, channel_id="UCdone"),
+            Subscription(user_id=user.id, channel_id="UCopen"),
+        ]
+    )
+    db.commit()
+
+    body = as_user(user).get("/api/sync/my-status").json()
+    assert body["channels_deep_requested"] == 2
+    assert body["channels_deep_done"] == 1  # never more than it is out of
+    assert body["channels_deep_pending"] == 2  # subscribed channels without full history yet

backend/tests/test_playlist_add_position.py

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

backend/tests/test_playlist_move.py

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

backend/tests/test_playlist_position_lock.py

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

backend/tests/test_playlist_sync_claim.py

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

backend/tests/test_playlist_sync_lock_order.py

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

backend/tests/test_plex_cards.py

@@ -11,21 +11,21 @@ from app.plex.cards import movie_card, show_card
 
 def test_movie_card_emits_art_when_art_key_present():
     it = PlexItem(rating_key="m1", kind="movie", title="M", year=2020, art_key="/library/art/1")
-    card = movie_card(it, None)
+    card = movie_card(it, None, lang="en")
     assert card["thumb"] == "/api/plex/image/m1"
     assert card["art"] == "/api/plex/image/m1?variant=art"
 
 
 def test_movie_card_art_is_none_without_art_key():
     it = PlexItem(rating_key="m2", kind="movie", title="M2")
-    assert movie_card(it, None)["art"] is None
+    assert movie_card(it, None, lang="en")["art"] is None
 
 
 def test_show_card_emits_art_when_art_key_present():
     sh = PlexShow(rating_key="s1", title="S", art_key="/library/art/2")
-    assert show_card(sh)["art"] == "/api/plex/image/s1?variant=art"
+    assert show_card(sh, lang="en")["art"] == "/api/plex/image/s1?variant=art"
 
 
 def test_show_card_art_is_none_without_art_key():
     sh = PlexShow(rating_key="s2", title="S2")
-    assert show_card(sh)["art"] is None
+    assert show_card(sh, lang="en")["art"] is None

backend/tests/test_plex_detail.py

@@ -352,3 +352,52 @@ def test_show_detail_lazy_fills_when_unenriched(db, monkeypatch, override_dep):
     assert show.imdb_id == "tt0068646"  # persisted for next time
     assert show.people_enriched_at is not None
     assert [c["name"] for c in show.full_cast] == ["Marlon Brando", "Al Pacino"]
+
+
+def test_item_detail_names_tracks_from_their_language_not_plexs_title(
+    db, monkeypatch, override_dep
+):
+    """E30: Plex titles a track in the Plex SERVER's language ("English (AC3 5.1)", "magyar Forced",
+    "中文 (EAC3 Stereo)"), so a Hungarian reader got a mix. The route sends what the client names it
+    from instead — the language tag, the forced / SDH flags, the codec tail — keeping Plex's title
+    only as the fallback, and no invented English "Audio 2" for a track with neither."""
+    lib = PlexLibrary(plex_key="1", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    db.add(PlexItem(rating_key="m1", library_id=lib.id, kind="movie", title="T"))
+    db.commit()
+    user = _user(db, "tracks@example.com")
+    db.commit()
+    streams = [
+        {"streamType": 2, "displayTitle": "English (AC3 5.1)", "languageTag": "en-US"},
+        {"streamType": 2, "displayTitle": "中文 (EAC3 Stereo)", "languageTag": "zh"},
+        {"streamType": 2},
+        {
+            "streamType": 3,
+            "displayTitle": "magyar Forced",
+            "languageTag": "hu",
+            "forced": True,
+            "codec": "srt",
+        },
+        {
+            "streamType": 3,
+            "displayTitle": "English SDH",
+            "languageTag": "en",
+            "hearingImpaired": True,
+            "codec": "srt",
+        },
+    ]
+    meta = {**RICH_META, "Media": [{"Part": [{"Stream": streams}]}]}
+    monkeypatch.setattr(detail_routes, "PlexClient", lambda db: _StubClient(meta))
+    body = _get(db, user, monkeypatch, override_dep, "/api/plex/item/m1").json()
+
+    naming = ("label", "lang_tag", "forced", "hearing_impaired", "detail")
+    assert [tuple(a[k] for k in naming) for a in body["audio_streams"]] == [
+        ("English (AC3 5.1)", "en-US", False, False, "AC3 5.1"),
+        ("中文 (EAC3 Stereo)", "zh", False, False, "EAC3 Stereo"),
+        (None, None, False, False, None),
+    ]
+    assert [tuple(s[k] for k in naming) for s in body["subtitle_streams"]] == [
+        ("magyar Forced", "hu", True, False, None),
+        ("English SDH", "en", False, True, None),
+    ]

backend/tests/test_plex_facets_grid_parity.py

@@ -214,3 +214,28 @@ def test_hidden_movie_absent_from_grid_and_facets(db, as_user):
     facets = client.get("/api/plex/facets?scope=movie&show=all")
     crs = {c["value"]: c["count"] for c in facets.json()["content_ratings"]}
     assert crs.get("R") == 1, crs
+
+
+def test_a_watch_state_scope_rolls_the_episodes_up_once(db, as_user):
+    """The per-user episode rollup behind a show's watch state is a pass over every episode; each show
+    facet group asked it again (E31 S4e: half of a filtered facets call). It is asked once now."""
+    from sqlalchemy import event
+
+    from app.db import engine
+
+    seed = _seed(db)
+    client = as_user(seed["user"])
+    rollups: list[str] = []
+
+    def count(conn, cursor, statement, *_):
+        if "GROUP BY plex_items.show_id" in statement:
+            rollups.append(statement)
+
+    event.listen(engine, "before_cursor_execute", count)
+    try:
+        for show in ("watched", "in_progress", "unwatched"):
+            rollups.clear()
+            assert client.get(f"/api/plex/facets?scope=both&show={show}").status_code == 200
+            assert len(rollups) == 1, show
+    finally:
+        event.remove(engine, "before_cursor_execute", count)

backend/tests/test_plex_image_sizes.py

@@ -0,0 +1,77 @@
+"""A card asks the Plex image proxy for a small cut; a detail page keeps the full one (E31 S4e).
+
+Cards fetched the 400×600 poster for a ~144px picture and the 1280×720 backdrop for a ~212px shelf
+picture. The `_sm` variants are cut by Plex at a card's size and cached apart from the full ones; an
+unknown variant still gets the full poster. DB lane (the proxy opens its own short session).
+"""
+
+from fastapi.testclient import TestClient
+
+import app.state as app_state
+from app.main import app
+from app.models import PlexItem, PlexLibrary
+from app.plex import imgcache
+from app.routes.plex import playback
+
+
+class _FakePlex:
+    calls: list[tuple[str, int | None, int | None]] = []
+
+    def __init__(self, db) -> None:
+        pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc) -> None:
+        return None
+
+    def image_bytes(self, key, width=None, height=None):
+        _FakePlex.calls.append((key, width, height))
+        return b"\xff\xd8jpeg", "image/jpeg"
+
+
+def _setup(db, make_user, monkeypatch, tmp_path) -> TestClient:
+    user = make_user()
+    lib = PlexLibrary(plex_key="90", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    db.add(
+        PlexItem(
+            rating_key="pm1",
+            library_id=lib.id,
+            kind="movie",
+            title="A Movie",
+            thumb_key="/library/metadata/pm1/thumb/1",
+            art_key="/library/metadata/pm1/art/1",
+        )
+    )
+    db.commit()
+    monkeypatch.setattr(app_state, "_configured_cache", True)
+    monkeypatch.setattr(playback, "resolved_user_id", lambda request: (user.id, True))
+    monkeypatch.setattr(playback, "PlexClient", _FakePlex)
+    monkeypatch.setattr(imgcache, "CACHE_DIR", tmp_path)
+    _FakePlex.calls = []
+    return TestClient(app)
+
+
+def test_each_variant_is_cut_at_its_own_size(db, make_user, monkeypatch, tmp_path):
+    client = _setup(db, make_user, monkeypatch, tmp_path)
+    for variant in ("thumb", "thumb_sm", "art", "art_sm"):
+        assert client.get(f"/api/plex/image/pm1?variant={variant}").status_code == 200
+    assert _FakePlex.calls == [
+        ("/library/metadata/pm1/thumb/1", 400, 600),
+        ("/library/metadata/pm1/thumb/1", 240, 360),
+        ("/library/metadata/pm1/art/1", 1280, 720),
+        ("/library/metadata/pm1/art/1", 480, 270),
+    ]
+    # Each cut is cached under its own name: asking again reaches Plex no more.
+    for variant in ("thumb", "thumb_sm", "art", "art_sm"):
+        client.get(f"/api/plex/image/pm1?variant={variant}")
+    assert len(_FakePlex.calls) == 4
+
+
+def test_an_unknown_variant_gets_the_full_poster(db, make_user, monkeypatch, tmp_path):
+    client = _setup(db, make_user, monkeypatch, tmp_path)
+    assert client.get("/api/plex/image/pm1?variant=huge").status_code == 200
+    assert _FakePlex.calls == [("/library/metadata/pm1/thumb/1", 400, 600)]

backend/tests/test_plex_lang.py

@@ -12,7 +12,19 @@ import app.state as state
 from app.auth import current_user
 from app.db import get_db
 from app.main import app
-from app.models import PlexItem, PlexLibrary, User
+from app import sysconfig
+from app.plex.cards import display_summary, display_title
+from app.models import (
+    PlexCollection,
+    PlexItem,
+    PlexLibrary,
+    PlexPlaylist,
+    PlexPlaylistItem,
+    PlexSeason,
+    PlexShow,
+    PlexState,
+    User,
+)
 
 
 def _seed(db):
@@ -30,7 +42,9 @@ def _seed(db):
         summary="English summary.",
         summary_hu="Magyar összefoglaló.",
         genres=["Drama"],
-        genres_hu=["Dráma"],
+        genres_hu=["Dráma", "Akció"],
+        tagline="English tagline.",
+        tagline_hu="Magyar mottó.",
         rating=6.5,
         imdb_rating=None,
         year=2001,
@@ -44,7 +58,9 @@ def _seed(db):
         library_id=lib.id,
         kind="movie",
         title="EN Only",
-        genres=["Comedy"],  # no HU twin
+        summary="English only.",
+        tagline="English only tagline.",
+        genres=["Comedy"],  # no HU twin, never reached by a sync since: no genres_hu
         year=2002,
         added_at=datetime(2024, 1, 2, tzinfo=timezone.utc),
         people_enriched_at=datetime(2024, 1, 2, tzinfo=timezone.utc),
@@ -102,12 +118,52 @@ def test_genre_filter_matches_active_language_vocabulary(db, monkeypatch, overri
     assert miss.json()["items"] == []
 
 
+def test_a_genre_filter_saved_in_english_still_matches_in_hungarian(db, monkeypatch, override_dep):
+    """E30: the HU column holds one Hungarian word per genre. A filter saved while the HU list still
+    offered "Action" is read through the same map, so it finds the "Akció" title instead of nothing."""
+    user = _seed(db)
+    resp = _get(
+        db, user, monkeypatch, override_dep, "/api/plex/library?scope=movie&lang=hu&genres=Action"
+    )
+    assert _titles(resp) == {"Magyar Cím"}
+
+
+def test_a_genre_the_hungarian_list_offers_in_english_still_matches(db, monkeypatch, override_dep):
+    """E30 review: a row the sync has not given Hungarian genres yet is listed under its English word
+    (the facets read coalesce(genres_hu, genres)); filtering by that word must find it."""
+    user = _seed(db)
+    facets = _get(db, user, monkeypatch, override_dep, "/api/plex/facets?scope=movie&lang=hu")
+    assert "Comedy" in {g["value"] for g in facets.json()["genres"]}
+    resp = _get(
+        db, user, monkeypatch, override_dep, "/api/plex/library?scope=movie&lang=hu&genres=Comedy"
+    )
+    assert _titles(resp) == {"EN Only"}
+
+
+def test_a_title_without_a_hungarian_twin_reads_in_english(db, monkeypatch, override_dep):
+    user = _seed(db)
+    body = _get(db, user, monkeypatch, override_dep, "/api/plex/item/m2?lang=hu").json()
+    assert (body["title"], body["summary"], body["tagline"]) == (
+        "EN Only",
+        "English only.",
+        "English only tagline.",
+    )
+    row = PlexItem(title="T", summary="S")
+    assert (display_title(row, "hu"), display_summary(row, "hu")) == ("T", "S")
+    row.title_hu, row.summary_hu = "HT", "HS"
+    assert (display_title(row, "hu"), display_summary(row, "hu")) == ("HT", "HS")
+    assert (display_title(row, "en"), display_summary(row, "en")) == ("T", "S")
+
+
 def test_item_detail_language_and_rating_split(db, monkeypatch, override_dep):
     user = _seed(db)
     resp = _get(db, user, monkeypatch, override_dep, "/api/plex/item/m1?lang=hu")
     body = resp.json()
     assert body["title"] == "Magyar Cím"
     assert body["summary"] == "Magyar összefoglaló."
+    assert body["tagline"] == "Magyar mottó."  # E30: the HU overlay's tagline
+    en = _get(db, user, monkeypatch, override_dep, "/api/plex/item/m1").json()
+    assert en["tagline"] == "English tagline."
     # imdb_rating is IMDb-only (None here); the audience score is served separately as `rating`.
     assert body["imdb_rating"] is None
     assert body["rating"] == 6.5
@@ -147,3 +203,126 @@ def test_rating_filter_prefers_imdb_over_audience(db, monkeypatch, override_dep)
     assert "High IMDb" in _titles(hit)
     miss = _get(db, user, monkeypatch, override_dep, "/api/plex/library?scope=movie&rating_min=9")
     assert "High IMDb" not in _titles(miss)
+
+
+def _seed_rails(db):
+    """`_seed` plus what every card rail reads: a HU-overlaid show with a HU-overlaid episode in
+    progress, a cast name, a collection, and a playlist holding the movie and the episode."""
+    user = _seed(db)
+    m1 = db.query(PlexItem).filter_by(rating_key="m1").one()
+    m1.cast_names = ["Anna"]
+    m1.collection_keys = ["c1"]
+    db.add(PlexCollection(rating_key="c1", library_id=m1.library_id, title="Coll"))
+    tv = PlexLibrary(plex_key="2", title="TV Shows", kind="show", enabled=True)
+    db.add(tv)
+    db.flush()
+    show = PlexShow(
+        rating_key="s1",
+        library_id=tv.id,
+        title="English Show",
+        title_hu="Magyar Sorozat",
+        added_at=datetime(2024, 1, 3, tzinfo=timezone.utc),
+    )
+    db.add(show)
+    db.flush()
+    season = PlexSeason(rating_key="s1s1", show_id=show.id, title="Season 1", season_number=1)
+    db.add(season)
+    db.flush()
+    ep = PlexItem(
+        rating_key="e1",
+        library_id=tv.id,
+        kind="episode",
+        show_id=show.id,
+        season_id=season.id,
+        title="Pilot",
+        title_hu="Kezdet",
+        season_number=1,
+        episode_number=1,
+        duration_s=3000,
+    )
+    db.add(ep)
+    db.flush()
+    db.add(
+        PlexState(
+            user_id=user.id,
+            item_id=ep.id,
+            status="in_progress",
+            position_seconds=600,
+            progress_updated_at=datetime(2024, 2, 1, tzinfo=timezone.utc),
+        )
+    )
+    pl = PlexPlaylist(user_id=user.id, title="Mix")
+    db.add(pl)
+    db.flush()
+    db.add_all(
+        [
+            PlexPlaylistItem(playlist_id=pl.id, item_id=m1.id, position=0),
+            PlexPlaylistItem(playlist_id=pl.id, item_id=ep.id, position=1),
+        ]
+    )
+    # TMDB extras: m2 recommends m1 (held) and a title we lack; m1, watched, anchors the recs rail.
+    m1.guid = "tmdb:1"
+    m1.tmdb_enriched_at = datetime(2024, 1, 1, tzinfo=timezone.utc)
+    m1.recommendations = [{"tmdb_id": 2, "title": "EN Only", "media_type": "movie"}]
+    m2 = db.query(PlexItem).filter_by(rating_key="m2").one()
+    m2.guid = "tmdb:2"
+    m2.tmdb_enriched_at = datetime(2024, 1, 1, tzinfo=timezone.utc)
+    m2.recommendations = [
+        {"tmdb_id": 1, "title": "English Title", "media_type": "movie"},
+        {"tmdb_id": 77, "title": "Elsewhere", "media_type": "movie"},
+    ]
+    db.add(
+        PlexState(
+            user_id=user.id,
+            item_id=m1.id,
+            status="watched",
+            watched_at=datetime(2024, 3, 1, tzinfo=timezone.utc),
+        )
+    )
+    sysconfig.set_value(db, "plex_enabled", True)
+    db.commit()
+    return user, pl.id
+
+
+def test_every_card_rail_serves_the_readers_language(db, monkeypatch, override_dep):
+    """E30: the grid spoke Hungarian, but every other card surface (Discover rails, show page,
+    search, collection, person page, playlist, Home) served the English title to a HU reader."""
+    user, pid = _seed_rails(db)
+
+    def get(path):
+        return _get(db, user, monkeypatch, override_dep, path).json()
+
+    def titles(cards):
+        return {c["title"] for c in cards}
+
+    rails = get("/api/plex/discover?scope=both&lang=hu")
+    assert {"Magyar Cím", "Magyar Sorozat"} <= titles(rails["recently_added"])
+    assert "Magyar Sorozat" in titles(rails["continue_watching"])
+    assert titles(get("/api/plex/show/s1?lang=hu")["seasons"][0]["episodes"]) == {"Kezdet"}
+    found = get("/api/plex/library?scope=both&lang=hu&q=Kezdet")["episodes"]
+    assert [(e["title"], e["show_title"]) for e in found] == [("Kezdet", "Magyar Sorozat")]
+    assert titles(get("/api/plex/collections/c1?lang=hu")["items"]) == {"Magyar Cím"}
+    assert titles(get("/api/plex/person/Anna?lang=hu")["movies"]) == {"Magyar Cím"}
+    items = get(f"/api/plex/playlists/{pid}?lang=hu")["items"]
+    assert [(c["title"], c.get("show_title")) for c in items] == [
+        ("Magyar Cím", None),
+        ("Kezdet", "Magyar Sorozat"),
+    ]
+    # A recommendation we hold is named as the library names it; the rail's anchor too.
+    recs = get("/api/plex/item/m2?lang=hu")["tmdb"]["recommendations"]
+    assert [(r["title"], r["in_library"]) for r in recs] == [
+        ("Magyar Cím", True),
+        ("Elsewhere", False),
+    ]
+    byw = get("/api/plex/discover?scope=both&lang=hu")["because_you_watched"]
+    assert byw["anchor"]["title"] == "Magyar Cím"
+    home = get("/api/discover?lang=hu")["continue_watching"]
+    plex = [c for c in home if c["source"] == "plex"]
+    assert [c["title"] for c in plex] == ["Magyar Sorozat"]
+    assert plex[0]["next"]["title"] == "Kezdet"
+    # EN (the default) still serves English on the same rails.
+    items = get(f"/api/plex/playlists/{pid}")["items"]
+    assert [(c["title"], c.get("show_title")) for c in items] == [
+        ("English Title", None),
+        ("Pilot", "English Show"),
+    ]

backend/tests/test_plex_overlay.py

@@ -6,11 +6,16 @@ Uses the DB lane (`db` fixture) — skipped when no Postgres is reachable. Runs
 (migrations 0063/0064) so the JSONB + STORED generated columns are exercised.
 """
 
+from alembic import command
+from alembic.config import Config
 from sqlalchemy import func, select
+from sqlalchemy.orm import Session
 
 import app.plex.sync as syncmod
 from app import sysconfig
-from app.models import PlexItem, PlexLibrary
+from app.db import engine
+from app.models import PlexItem, PlexLibrary, PlexShow
+from app.plex.genres import hu_genre, hu_genres
 from app.plex.sync import _apply_item, _canonical_guid, _sync_overlay
 from app.plex.query import content_libs
 
@@ -244,3 +249,171 @@ def test_content_libs_excludes_overlay_libraries(db):
     assert en_lib.id in movie_ids
     assert overlay.id not in movie_ids  # the HU overlay is never browsable
     assert show_ids == [en_shows.id]
+
+
+class _KindStub:
+    """An overlay section listing per Plex type (2 = show, 4 = episode), like a HU TV section."""
+
+    def __init__(self, by_type: dict[int, list[dict]]):
+        self._by = by_type
+
+    def section_items(self, key, item_type, start, size):
+        items = self._by.get(item_type, [])
+        return items[start : start + size], len(items)
+
+
+def test_a_show_overlay_writes_hungarian_episode_titles_and_summaries(db):
+    """E30: the HU TV section lists every episode in Hungarian; they were never read, so a Hungarian
+    reader saw every episode title and summary in English."""
+    en_lib = PlexLibrary(plex_key="1", title="TV Shows", kind="show")
+    hu_lib = PlexLibrary(plex_key="9", title="Sorozatok", kind="show", metadata_lang="hu")
+    db.add_all([en_lib, hu_lib])
+    db.flush()
+    show = PlexShow(rating_key="s1", library_id=en_lib.id, title="3 Body Problem", guid="tmdb:10")
+    db.add(show)
+    db.flush()
+    ep = PlexItem(
+        rating_key="e1",
+        library_id=en_lib.id,
+        kind="episode",
+        show_id=show.id,
+        title="Countdown",
+        summary="EN.",
+        guid="tmdb:501",
+    )
+    db.add(ep)
+    db.commit()
+    stub = _KindStub(
+        {
+            syncmod._TYPE_SHOW: [_hu_movie("hs", "A 3-test-probléma", "HU.", [], "tmdb://10")],
+            syncmod._TYPE_EPISODE: [
+                _hu_movie("he", "Visszaszámlálás", "Magyar epizód.", [], "tmdb://501")
+            ],
+        }
+    )
+    _sync_overlay(db, stub, hu_lib, en_lib.id, {})
+    db.commit()
+    db.refresh(ep)
+    db.refresh(show)
+    assert (ep.title_hu, ep.summary_hu) == ("Visszaszámlálás", "Magyar epizód.")
+    assert show.title_hu == "A 3-test-probléma"
+
+
+def test_the_overlay_gives_every_row_one_hungarian_word_per_genre(db):
+    """E30: Plex's HU agent mixes "Action" with "Dráma", and a title with no HU twin kept only its
+    English list — so the HU genre list offered "Drama" beside "Dráma"."""
+    en_lib = PlexLibrary(plex_key="4", title="Movies", kind="movie")
+    hu_lib = PlexLibrary(plex_key="9", title="Filmek", kind="movie", metadata_lang="hu")
+    db.add_all([en_lib, hu_lib])
+    db.flush()
+    twin = PlexItem(
+        rating_key="m1",
+        library_id=en_lib.id,
+        kind="movie",
+        title="Heat",
+        guid="tmdb:1",
+        genres=["Action", "Crime"],
+    )
+    lone = PlexItem(
+        rating_key="m2",
+        library_id=en_lib.id,
+        kind="movie",
+        title="Solo",
+        guid="tmdb:2",
+        genres=["Drama", "Science Fiction"],
+    )
+    db.add_all([twin, lone])
+    db.commit()
+    meta = _hu_movie(
+        "h1", "Szemtől szemben", "HU.", ["Action", "Bűnügyi", "Drama", "Dráma"], "tmdb://1"
+    )
+    meta["tagline"] = "Magyar mottó."
+    _sync_overlay(db, _StubPlex([meta]), hu_lib, en_lib.id, {})
+    db.commit()
+    db.refresh(twin)
+    db.refresh(lone)
+    assert twin.genres_hu == ["Akció", "Bűnügyi", "Dráma"]
+    assert twin.tagline_hu == "Magyar mottó."
+    assert lone.genres_hu == ["Dráma", "Sci-Fi"]  # no twin: its own English list, in Hungarian
+    assert lone.tagline_hu is None
+
+
+def test_a_twin_without_genres_keeps_the_rows_own_hungarian_list(db):
+    en_lib = PlexLibrary(plex_key="4", title="Movies", kind="movie")
+    hu_lib = PlexLibrary(plex_key="9", title="Filmek", kind="movie", metadata_lang="hu")
+    db.add_all([en_lib, hu_lib])
+    db.flush()
+    row = PlexItem(
+        rating_key="m1",
+        library_id=en_lib.id,
+        kind="movie",
+        title="Heat",
+        guid="tmdb:1",
+        genres=["Crime"],
+    )
+    db.add(row)
+    db.commit()
+    _sync_overlay(
+        db,
+        _StubPlex([_hu_movie("h1", "Szemtől szemben", "HU.", [], "tmdb://1")]),
+        hu_lib,
+        en_lib.id,
+        {},
+    )
+    db.commit()
+    db.refresh(row)
+    assert (row.title_hu, row.genres_hu) == ("Szemtől szemben", ["Bűnügyi"])
+
+
+def test_every_synced_row_gets_hungarian_genres():
+    """E30 review: not only an overlaid row — the HU facets and filter read genres_hu for all."""
+    from app.plex.sync import _apply_facet_fields
+
+    row = PlexItem(title="Solo")
+    _apply_facet_fields(row, {"Genre": [{"tag": "Drama"}, {"tag": "Action"}]})
+    assert (row.genres, row.genres_hu) == (["Drama", "Action"], ["Dráma", "Akció"])
+
+
+def test_the_genre_map_is_idempotent_and_keeps_an_unknown_word():
+    assert hu_genre("science fiction") == "Sci-Fi"  # case-insensitive
+    assert hu_genre("Dráma") == "Dráma"
+    assert hu_genre("Space Opera") == "Space Opera"  # unknown: shown as Plex gave it, never dropped
+    once = hu_genres(["Drama", "Action", "Dráma"])
+    assert once == ["Dráma", "Akció"]
+    assert hu_genres(once) == once
+    assert hu_genres(None) is None and hu_genres([]) is None
+
+
+def test_0094_gives_every_row_without_a_hungarian_list_one(db):
+    cfg = Config("alembic.ini")
+    command.downgrade(cfg, "0093_plex_person_known_for_votes")
+    upgraded = False
+    try:
+        with Session(engine) as s:
+            lib = PlexLibrary(plex_key="1", title="Movies", kind="movie", enabled=True)
+            s.add(lib)
+            s.flush()
+            rows = {
+                "bare": PlexItem(genres=["Action", "Biography"]),
+                "overlaid": PlexItem(
+                    genres=["Action"], genres_hu=["Kaland"]
+                ),  # its twin's own list
+                "genreless": PlexItem(genres=[]),
+            }
+            for key, row in rows.items():
+                row.rating_key, row.library_id, row.kind, row.title = key, lib.id, "movie", key
+            show = PlexShow(rating_key="s", library_id=lib.id, title="s", genres=["Comedy"])
+            s.add_all([*rows.values(), show])
+            s.commit()
+            ids = {k: r.id for k, r in rows.items()}
+            show_id = show.id
+        command.upgrade(cfg, "head")
+        upgraded = True
+        with Session(engine) as s:
+            got = {k: s.get(PlexItem, i).genres_hu for k, i in ids.items()}  # type: ignore[union-attr]
+            show_hu = s.get(PlexShow, show_id).genres_hu  # type: ignore[union-attr]
+        assert got == {"bare": ["Akció", "Életrajzi"], "overlaid": ["Kaland"], "genreless": None}
+        assert show_hu == ["Vígjáték"]
+    finally:
+        if not upgraded:
+            command.upgrade(cfg, "head")

backend/tests/test_plex_people_enrich.py

@@ -0,0 +1,463 @@
+"""E30 S6: the people are made local ahead of time. The people_enrich job fetches linked people's TMDB
+bios (the most-credited first) and caches their portraits resized through Plex; the person page says
+when a bio is still on its way (`enriching`), so it can ask again instead of staying empty.
+DB lane (Postgres); the portrait cache runs in a temp directory.
+"""
+
+from datetime import datetime, timezone
+
+import httpx
+import pytest
+
+from app import scheduler
+from app.models import PlexItem, PlexLibrary, PlexPerson, User
+from app.plex import imgcache
+from app.plex import people as plex_people
+from app.plex import tmdb as plex_tmdb
+
+CDN = plex_people.PERSON_IMG_HOST + "people/"
+DONE = datetime(2024, 1, 1, tzinfo=timezone.utc)
+
+
+def _movie(db, lib, key, cast):
+    db.add(PlexItem(rating_key=key, library_id=lib.id, kind="movie", title=key, cast_names=cast))
+
+
+def _library(db):
+    lib = PlexLibrary(plex_key="1", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    return lib
+
+
+class _Tmdb:
+    """A TmdbClient stand-in: records the ids asked for, fails on `fail_on`."""
+
+    def __init__(self, fail_on=()):
+        self.asked: list[int] = []
+        self.fail_on = set(fail_on)
+
+    def fetch_person(self, pid):
+        self.asked.append(pid)
+        if pid in self.fail_on:
+            raise plex_tmdb.TmdbError("429")
+        return {"biography": f"Bio {pid}."}
+
+
+def test_the_batch_takes_the_most_credited_linked_people_first(db):
+    lib = _library(db)
+    _movie(db, lib, "a", ["Often", "Sometimes"])
+    _movie(db, lib, "b", ["Often", "Sometimes"])
+    _movie(db, lib, "c", ["Often", "Unlinked"])
+    db.add_all(
+        [
+            PlexPerson(name="Sometimes", tmdb_person_id=2),
+            PlexPerson(name="Often", tmdb_person_id=1),
+            PlexPerson(name="Unlinked"),  # no TMDB id: nothing to fetch
+            PlexPerson(name="Done", tmdb_person_id=3, tmdb_enriched_at=DONE),
+            PlexPerson(name="Rare", tmdb_person_id=4),  # credited nowhere: last
+        ]
+    )
+    db.commit()
+    tmdb = _Tmdb()
+    assert plex_tmdb.enrich_people_batch(db, tmdb, 2) == {"enriched": 2}  # type: ignore[arg-type]
+    assert tmdb.asked == [1, 2]
+    db.expire_all()
+    often = db.query(PlexPerson).filter_by(name="Often").one()
+    assert often.biography == "Bio 1." and often.tmdb_enriched_at is not None
+    assert db.query(PlexPerson).filter_by(name="Rare").one().tmdb_enriched_at is None  # next run
+
+
+def test_a_failed_lookup_is_skipped_and_the_rest_still_land(db):
+    db.add_all([PlexPerson(name="A", tmdb_person_id=1), PlexPerson(name="B", tmdb_person_id=2)])
+    db.add(PlexPerson(name="C", tmdb_person_id=3))
+    db.commit()
+    tmdb = _Tmdb(fail_on={2})
+    assert plex_tmdb.enrich_people_batch(db, tmdb, 10) == {"enriched": 2, "failed": 1}  # type: ignore[arg-type]
+    assert tmdb.asked == [1, 2, 3]  # B refused: skipped, not the end of the batch
+    db.expire_all()
+    stamped = {p.name: p.tmdb_enriched_at is not None for p in db.query(PlexPerson)}
+    assert stamped == {"A": True, "B": False, "C": True}  # B is tried again next run
+
+
+def test_failures_in_a_row_end_the_batch(db):
+    db.add_all([PlexPerson(name=f"P{i}", tmdb_person_id=i) for i in range(1, 7)])
+    db.commit()
+    tmdb = _Tmdb(fail_on={1, 2, 3, 4, 5, 6})  # TMDB is down
+    assert plex_tmdb.enrich_people_batch(db, tmdb, 10) == {"enriched": 0, "failed": 3}  # type: ignore[arg-type]
+    assert tmdb.asked == [1, 2, 3]
+
+
+def test_failures_between_successes_do_not_end_the_batch(db):
+    db.add_all([PlexPerson(name=f"P{i}", tmdb_person_id=i) for i in range(1, 9)])
+    db.commit()
+    tmdb = _Tmdb(fail_on={1, 3, 5, 7})  # fail, ok, fail, ok, …: never three in a row
+    assert plex_tmdb.enrich_people_batch(db, tmdb, 10) == {"enriched": 4, "failed": 4}  # type: ignore[arg-type]
+    assert tmdb.asked == list(range(1, 9))
+
+
+def test_the_batch_stores_the_hungarian_biography(db):
+    db.add(PlexPerson(name="A", tmdb_person_id=1))
+    db.commit()
+
+    class _WithHu(_Tmdb):
+        def fetch_person(self, pid):
+            return {
+                "biography": "English.",
+                "translations": {
+                    "translations": [{"iso_639_1": "hu", "data": {"biography": "Magyar."}}]
+                },
+            }
+
+    assert plex_tmdb.enrich_people_batch(db, _WithHu(), 10) == {"enriched": 1}  # type: ignore[arg-type]
+    db.expire_all()
+    person = db.query(PlexPerson).one()
+    assert (person.biography, person.biography_hu) == ("English.", "Magyar.")
+
+
+class _Plex:
+    """A PlexClient stand-in. `down`: urls Plex does not answer for (True: none); `dead`: urls Plex
+    answers `gone` for (a dead CDN file: "not found"); `status`: an error status Plex answers every
+    other url with."""
+
+    def __init__(self, down=False, dead=(), status=None, gone=404):
+        self.asked: list[tuple[str, int | None]] = []
+        self.down = down
+        self.dead = set(dead)
+        self.status = status
+        self.gone = gone
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+    def image_bytes(self, url, width=None, height=None):
+        self.asked.append((url, width))
+        if self.down is True or (self.down and url in self.down):
+            raise plex_people.PlexError("down") from httpx.ConnectError("refused")
+        code = self.gone if url in self.dead else self.status
+        if code:
+            req = httpx.Request("GET", url)
+            status = httpx.HTTPStatusError(
+                str(code), request=req, response=httpx.Response(code, request=req)
+            )
+            raise plex_people.PlexError(str(code)) from status
+        return b"small", "image/jpeg"
+
+
+@pytest.fixture
+def cache_dir(tmp_path, monkeypatch):
+    monkeypatch.setattr(imgcache, "CACHE_DIR", tmp_path)
+    return tmp_path
+
+
+@pytest.fixture
+def plex_on(monkeypatch):
+    """The Plex module switched on (the job's gate), with `plex` as its client."""
+    state = {"enabled": True, "plex": _Plex()}
+    monkeypatch.setattr(plex_people.sysconfig, "get_bool", lambda d, k: state["enabled"])
+    monkeypatch.setattr(plex_people, "PlexClient", lambda d: state["plex"])
+    return state
+
+
+def _faces(db, n):
+    db.add_all(
+        [
+            PlexPerson(name=f"P{i}", photo_thumb=plex_people.person_thumb_url(CDN + f"{i}.jpg"))
+            for i in range(n)
+        ]
+    )
+    db.commit()
+
+
+def test_portraits_are_cached_small_and_replace_the_full_size_original(db, cache_dir, plex_on):
+    lib = _library(db)
+    _movie(db, lib, "a", ["Often"])
+    _movie(db, lib, "b", ["Often", "Cached"])
+    db.add_all(
+        [
+            PlexPerson(name="Often", photo_thumb=plex_people.person_thumb_url(CDN + "often.jpg")),
+            PlexPerson(name="Cached", photo_thumb=plex_people.person_thumb_url(CDN + "cached.jpg")),
+            PlexPerson(name="Faceless"),
+        ]
+    )
+    db.commit()
+    small, original = plex_people._portrait_keys(CDN + "often.jpg")
+    imgcache.write(original, b"a big original", "image/jpeg")  # cached without Plex
+    imgcache.write(plex_people._portrait_keys(CDN + "cached.jpg")[0], b"x", "image/jpeg")
+    plex = plex_on["plex"]
+
+    assert plex_people.warm_portraits(db, 10) == {"cached": 1}
+    assert plex.asked == [
+        (CDN + "often.jpg", plex_people.PORTRAIT_BOX)
+    ]  # resized, the cached one skipped
+    assert imgcache.read(small) == (b"small", "image/jpeg")
+    assert not imgcache.has(original)
+
+
+def test_portraits_wait_for_plex(db, cache_dir, plex_on, monkeypatch):
+    _faces(db, 1)
+
+    def not_configured(d):
+        raise plex_people.PlexNotConfigured()
+
+    monkeypatch.setattr(plex_people, "PlexClient", not_configured)
+    assert plex_people.warm_portraits(db, 10) == {"cached": 0, "skipped": "disabled"}
+    assert list(cache_dir.iterdir()) == []  # no full-size originals behind Plex's back
+
+
+def test_portraits_wait_for_the_plex_module_to_be_on(db, cache_dir, plex_on):
+    _faces(db, 1)
+    plex_on["enabled"] = False  # switched off, its server still set up
+    assert plex_people.warm_portraits(db, 10) == {"cached": 0, "skipped": "disabled"}
+    assert plex_on["plex"].asked == []
+
+
+def test_plex_not_answering_ends_the_portrait_run(db, cache_dir, plex_on):
+    _faces(db, 8)
+    plex_on["plex"] = _Plex(down=True)
+    assert plex_people.warm_portraits(db, 100) == {"cached": 0, "failed": 3}
+    assert len(plex_on["plex"].asked) == 3
+    assert not list(cache_dir.glob("*.miss"))  # Plex was down, the files are not to blame
+
+
+@pytest.mark.parametrize("code", [401, 403, 429, 500, 503])
+def test_plex_refusing_is_plex_failing_not_a_dead_file(db, cache_dir, plex_on, code):
+    _faces(db, 8)
+    plex_on["plex"] = _Plex(status=code)  # a rotated token, a busy or broken transcoder
+    assert plex_people.warm_portraits(db, 100) == {"cached": 0, "failed": 3}
+    assert len(plex_on["plex"].asked) == 3
+    assert not list(cache_dir.glob("*.miss"))  # the files are not to blame: asked again next run
+
+
+def test_plex_failing_between_successes_does_not_end_the_run(db, cache_dir, plex_on):
+    _faces(db, 8)
+    plex_on["plex"] = _Plex(down={CDN + f"{i}.jpg" for i in (0, 2, 4, 6)})  # down, ok, down, ok, …
+    assert plex_people.warm_portraits(db, 100) == {"cached": 4, "failed": 4}
+
+
+def test_plex_failing_between_dead_files_does_not_end_the_run(db, cache_dir, plex_on):
+    _faces(db, 8)
+    plex_on["plex"] = _Plex(  # down, dead, down, dead, …: Plex answers in between
+        down={CDN + f"{i}.jpg" for i in (0, 2, 4, 6)}, dead={CDN + f"{i}.jpg" for i in (1, 3, 5, 7)}
+    )
+    assert plex_people.warm_portraits(db, 100) == {"cached": 0, "failed": 8}
+    assert len(plex_on["plex"].asked) == 8
+
+
+@pytest.mark.parametrize("gone", [404, 410])
+def test_dead_headshots_are_left_alone_and_the_rest_still_land(db, cache_dir, plex_on, gone):
+    _faces(db, 8)
+    dead = {CDN + f"{i}.jpg" for i in range(6)}  # more dead files than any failure limit
+    plex_on["plex"] = _Plex(dead=dead, gone=gone)
+    assert plex_people.warm_portraits(db, 100) == {"cached": 2, "failed": 6}
+
+    plex_on["plex"] = again = _Plex(dead=dead, gone=gone)
+    assert plex_people.warm_portraits(db, 100) == {"cached": 0}
+    assert again.asked == []  # dead ones marked, live ones cached: nothing to ask for
+
+
+def test_the_person_image_route(db, cache_dir, monkeypatch):
+    from fastapi.testclient import TestClient
+
+    import app.state as state
+    from app.main import app
+    from app.routes.plex import playback
+
+    monkeypatch.setattr(state, "_configured_cache", True)
+    monkeypatch.setattr(playback, "_require_session", lambda request: 1)
+    client = TestClient(app)
+    url = CDN + "face.jpg"
+    small, original = plex_people._portrait_keys(url)
+
+    def get(u):
+        return client.get("/api/plex/person-image", params={"u": u})
+
+    # Only a headshot-shaped url on the CDN host: no query variants of one file, no spellings an HTTP
+    # client folds onto it, no other host.
+    for bad in (
+        url + "?n=1",
+        url + "#x",
+        CDN + "x/../face.jpg",
+        CDN + "./face.jpg",
+        plex_people.PERSON_IMG_HOST + "people//face.jpg",
+        CDN + ".face.jpg",
+        "https://example.com/people/a.jpg",
+    ):
+        assert get(bad).status_code == 400, bad
+        assert plex_people.person_thumb_url(bad) is None, bad  # never stored either
+
+    # No Plex: the original from the CDN, kept under its own key (the job resizes it later).
+    def not_configured(d):
+        raise plex_people.PlexNotConfigured()
+
+    class _Cdn:
+        def __init__(self, *a, **k):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *a):
+            return False
+
+        def get(self, u):
+            return httpx.Response(
+                200,
+                content=b"original",
+                headers={"content-type": "image/jpeg"},
+                request=httpx.Request("GET", u),
+            )
+
+    monkeypatch.setattr(playback, "PlexClient", not_configured)
+    monkeypatch.setattr(plex_people.httpx, "Client", _Cdn)
+    resp = get(url)
+    assert (resp.status_code, resp.content) == (200, b"original")
+    assert imgcache.has(original) and not imgcache.has(small)
+    monkeypatch.setattr(plex_people.httpx, "Client", None)  # the CDN is not asked again
+    assert get(url).content == b"original"  # the kept original answers
+
+    # With Plex: resized, and it replaces the original.
+    monkeypatch.setattr(playback, "PlexClient", lambda d: _Plex())
+    imgcache.drop(original)
+    resp = get(url)
+    assert (resp.status_code, resp.content) == (200, b"small")
+    assert imgcache.has(small)
+    assert get(url).content == b"small"  # the cache answers now
+
+    monkeypatch.setattr(playback, "PlexClient", lambda d: _Plex(down=True))
+    assert get(CDN + "other.jpg").status_code == 502
+
+
+def test_the_people_job_runs_its_halves_without_a_tmdb_key(db, cache_dir, plex_on, monkeypatch):
+    _faces(db, 1)
+    monkeypatch.setattr(plex_tmdb.sysconfig, "get_str", lambda d, k: "")
+    assert plex_tmdb.run_people_enrich(db) == {
+        "bios": {"skipped": "tmdb_api_key not set"},
+        "portraits": {"cached": 1},
+    }
+
+
+def test_a_phase_count_is_a_change_worth_an_audit_row():
+    assert scheduler._run_changed({"bios": {"enriched": 3}, "portraits": {"cached": 0}})
+    assert scheduler._run_changed({"recent": {"videos_added": 2}, "deep": {}})
+    assert not scheduler._run_changed({"bios": {"skipped": "x"}, "portraits": {"cached": 0}})
+
+
+def test_the_person_page_says_a_bio_is_on_its_way(db, monkeypatch, override_dep):
+    from fastapi.testclient import TestClient
+
+    import app.state as state
+    from app.auth import current_user
+    from app.db import get_db
+    from app.main import app
+    from app.routes.plex import people
+
+    db.add_all(
+        [
+            PlexPerson(name="Pending", tmdb_person_id=1),
+            PlexPerson(name="Known", tmdb_person_id=2, tmdb_enriched_at=DONE, biography="Bio."),
+            PlexPerson(name="Nobody"),
+        ]
+    )
+    user = User(email="enriching@example.com")
+    db.add(user)
+    db.commit()
+    monkeypatch.setattr(state, "_configured_cache", True)
+    override_dep(get_db, db.info["request"])
+    override_dep(current_user, lambda: user)
+    monkeypatch.setattr(people, "_enrich_person_bg", lambda pid: None)
+    key = {"value": "key"}
+    monkeypatch.setattr(people.sysconfig, "get_str", lambda d, k: key["value"])
+
+    def enriching(name):
+        resp = TestClient(app).get(f"/api/plex/person/{name}")
+        assert resp.status_code == 200, resp.text
+        return resp.json()["enriching"]
+
+    assert enriching("Pending") is True
+    assert enriching("Known") is False
+    assert enriching("Nobody") is False
+    key["value"] = ""  # no TMDB key: nothing will ever arrive, so the page must not wait
+    assert enriching("Pending") is False
+
+
+def test_known_for_is_the_most_voted_roles_not_guest_visits():
+    payload = {
+        "combined_credits": {
+            "cast": [
+                # Popular this week, but a visit as himself: not what he is known for.
+                {
+                    "id": 1,
+                    "media_type": "tv",
+                    "name": "Late Show",
+                    "character": "Himself - Guest",
+                    "popularity": 900,
+                    "vote_count": 50,
+                },
+                {
+                    "id": 2,
+                    "media_type": "tv",
+                    "name": "Talk Hour",
+                    "character": "",
+                    "genre_ids": [10767],
+                    "popularity": 800,
+                    "vote_count": 400,
+                },
+                {
+                    "id": 3,
+                    "media_type": "movie",
+                    "title": "Small Film",
+                    "character": "Bob",
+                    "popularity": 90,
+                    "vote_count": 300,
+                },
+                {
+                    "id": 4,
+                    "media_type": "movie",
+                    "title": "Big Film",
+                    "character": "Hero",
+                    "popularity": 10,
+                    "vote_count": 9000,
+                },
+            ],
+            "crew": [
+                {
+                    "id": 5,
+                    "media_type": "movie",
+                    "title": "His Own Film",
+                    "job": "Director",
+                    "vote_count": 1000,
+                },
+                {
+                    "id": 6,
+                    "media_type": "movie",
+                    "title": "Thanked In",
+                    "job": "Thanks",
+                    "vote_count": 99999,
+                },
+            ],
+        }
+    }
+    kf = plex_tmdb.parse_person(payload)["known_for"]
+    assert [k["title"] for k in kf] == ["Big Film", "His Own Film", "Small Film"]
+
+
+def test_the_page_shows_at_most_fifteen_known_for_titles(db):
+    from app.routes.plex import people
+
+    lib = PlexLibrary(plex_key="1", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    for i in range(1, 21):  # TMDB ids start at 1
+        db.add(
+            PlexItem(
+                rating_key=f"k{i}", library_id=lib.id, kind="movie", title=f"T{i}", guid=f"tmdb:{i}"
+            )
+        )
+    db.commit()
+    pool = [{"tmdb_id": i, "media_type": "movie", "title": f"T{i}"} for i in range(1, 21)]
+    cards = people._resolve_known_for(db, pool, 0, [lib.id], [], "en")
+    assert [c["title"] for c in cards] == [f"T{i}" for i in range(1, 16)]

backend/tests/test_plex_person.py

@@ -133,6 +133,7 @@ def test_person_detail_unknown_name_is_empty(db, monkeypatch, override_dep):
         "place_of_birth": None,
         "known_for_department": None,
         "also_known_as": [],
+        "enriching": False,
         "known_for": [],
         "movies": [],
         "shows": [],

backend/tests/test_plex_person_bio.py

@@ -191,11 +191,12 @@ def test_person_detail_schedules_enrich_off_request_path(db, monkeypatch, overri
 
     scheduled: list[int] = []
     monkeypatch.setattr(people, "_enrich_person_bg", lambda pid: scheduled.append(pid))
+    monkeypatch.setattr(people.sysconfig, "get_str", lambda d, k: "key")
     people._enrich_inflight.clear()  # ensure the per-person cooldown guard doesn't suppress this open
 
     resp = _get(db, user, monkeypatch, override_dep, "/api/plex/person/Lazy P")
     assert resp.status_code == 200, resp.text
-    assert resp.json()["biography"] is None  # not enriched yet — the bio lands by the next open
+    assert resp.json()["biography"] is None  # not enriched yet — the page asks again (`enriching`)
     assert len(scheduled) == 1  # the enrich was scheduled off the request path
 
 
@@ -332,3 +333,74 @@ def test_person_detail_serves_bio_and_resolves_known_for(db, monkeypatch, overri
     assert j["also_known_as"] == ["Alt Name"]
     # Only the in-library known_for credit resolves to a card; the out-of-library one is dropped.
     assert [c["title"] for c in j["known_for"]] == ["Known Movie"]
+
+
+# --- E30 S4: the biography in the reader's language --------------------------------------------------
+# The same /person request appends `translations`; the Hungarian one is kept beside the instance-language
+# biography, and a Hungarian reader is served it, falling back to the English one when TMDB has none.
+
+
+def _translation(lang: str, bio: str) -> dict:
+    return {"iso_639_1": lang, "iso_3166_1": lang.upper(), "data": {"biography": bio}}
+
+
+def test_parse_person_keeps_the_hungarian_biography():
+    payload = {
+        **PAYLOAD,
+        "translations": {
+            "translations": [
+                _translation("de", "Ein Schauspieler."),
+                _translation("hu", "  Ünnepelt színész.  "),
+            ]
+        },
+    }
+    assert plex_tmdb.parse_person(payload)["biography_hu"] == "Ünnepelt színész."
+
+
+def test_parse_person_without_a_hungarian_biography():
+    assert plex_tmdb.parse_person(PAYLOAD)["biography_hu"] is None
+    blank = {**PAYLOAD, "translations": {"translations": [_translation("hu", "   ")]}}
+    assert plex_tmdb.parse_person(blank)["biography_hu"] is None
+
+
+def test_fetch_person_asks_for_the_translations():
+    client = plex_tmdb.TmdbClient.__new__(plex_tmdb.TmdbClient)
+    seen: list[dict] = []
+    client._get = lambda path, params=None: seen.append(params or {}) or {}  # type: ignore[method-assign]
+    client.fetch_person(500)
+    assert "translations" in seen[0]["append_to_response"].split(",")
+
+
+def test_person_detail_serves_the_biography_in_the_readers_language(db, monkeypatch, override_dep):
+    from datetime import datetime, timezone
+
+    done = datetime(2024, 1, 1, tzinfo=timezone.utc)
+    db.add(PlexLibrary(plex_key="7", title="Movies", kind="movie", enabled=True))
+    db.add_all(
+        [
+            PlexPerson(
+                name="Both P",
+                tmdb_person_id=1,
+                tmdb_enriched_at=done,
+                biography="English bio.",
+                biography_hu="Magyar életrajz.",
+            ),
+            PlexPerson(
+                name="Only EN P", tmdb_person_id=2, tmdb_enriched_at=done, biography="Only English."
+            ),
+        ]
+    )
+    user = User(email="biolang@example.com")
+    db.add(user)
+    db.commit()
+
+    def bio(name: str, lang: str) -> str | None:
+        resp = _get(db, user, monkeypatch, override_dep, f"/api/plex/person/{name}?lang={lang}")
+        assert resp.status_code == 200, resp.text
+        return resp.json()["biography"]
+
+    assert bio("Both P", "hu") == "Magyar életrajz."
+    assert bio("Both P", "en") == "English bio."
+    assert (
+        bio("Only EN P", "hu") == "Only English."
+    )  # TMDB has no Hungarian one: the English stands in

backend/tests/test_plex_playlist_add_positions.py

@@ -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"]

backend/tests/test_plex_subtitle_encoding.py

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

backend/tests/test_plex_subtitle_prepare.py

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

backend/tests/test_plex_tmdb.py

@@ -49,7 +49,7 @@ MOVIE_PAYLOAD = {
         ],
     },
     "production_companies": [{"name": "Paramount"}, {"name": "Alfran"}],
-    "production_countries": [{"name": "United States of America"}],
+    "production_countries": [{"iso_3166_1": "US", "name": "United States of America"}],
     "recommendations": {
         "results": [
             {
@@ -126,7 +126,8 @@ def test_parse_movie_pulls_all_fields():
         },
     ]  # the Gaffer is filtered; the two Coppola jobs survive (dedup is by name+job)
     assert d["studios"] == ["Paramount", "Alfran"]
-    assert d["production_countries"] == ["United States of America"]
+    # E30: the code beside the English name, so the client can name the country in the reader's language.
+    assert d["production_countries"] == [{"code": "US", "name": "United States of America"}]
     assert [r["tmdb_id"] for r in d["recommendations"]] == [240, 999]
     assert d["backdrops"] == ["/bd1.jpg", "/bd2.jpg"]
     # cast + crew names → tmdb person ids for the plex_people foundation
@@ -255,13 +256,13 @@ def test_serve_block_none_until_enriched_and_resolves_recs(db):
     db.add_all([sequel, fresh])
     db.commit()
 
-    assert tmdb.serve_block(db, fresh) is None  # not enriched yet
+    assert tmdb.serve_block(db, fresh, lang="en") is None  # not enriched yet
 
     tmdb.apply_tmdb_detail(fresh, tmdb.parse_tmdb(MOVIE_PAYLOAD, "movie"))
     fresh.tmdb_enriched_at = datetime.now(timezone.utc)
     db.commit()
 
-    block = tmdb.serve_block(db, fresh)
+    block = tmdb.serve_block(db, fresh, lang="en")
     assert block is not None
     assert block["budget"] == 6000000
     assert block["keywords"] == ["mafia", "crime family"]
@@ -409,6 +410,7 @@ def test_resolve_recs_matches_by_media_type_not_bare_id(db):
                 {"tmdb_id": 500, "title": "Movie 500", "media_type": "movie"},
                 {"tmdb_id": 900, "title": "Show 900", "media_type": "tv"},
             ],
+            lang="en",
         )
     }
     assert miss[500]["in_library"] is False and miss[500]["rating_key"] is None
@@ -423,7 +425,74 @@ def test_resolve_recs_matches_by_media_type_not_bare_id(db):
                 {"tmdb_id": 900, "media_type": "movie"},
                 {"tmdb_id": 500, "media_type": "tv"},
             ],
+            lang="en",
         )
     }
     assert hit[900]["in_library"] is True and hit[900]["rating_key"] == "m900"
     assert hit[500]["in_library"] is True and hit[500]["rating_key"] == "s500"
+
+
+# ---- E30: countries by ISO code -----------------------------------------------------------------
+
+
+class FakeCountries(FakeTmdb):
+    """TMDB's /configuration/countries, counting the requests."""
+
+    def __init__(self):
+        super().__init__()
+        self.calls = 0
+
+    def countries(self):
+        self.calls += 1
+        return [
+            {"iso_3166_1": "US", "english_name": "United States of America"},
+            {"iso_3166_1": "YU", "english_name": "Yugoslavia"},
+        ]
+
+
+def test_countries_stored_before_codes_get_them_from_tmdbs_list(db):
+    lib = _lib(db)
+    old = PlexItem(
+        rating_key="m1",
+        library_id=lib.id,
+        kind="movie",
+        title="Old",
+        production_countries=["Yugoslavia", "Atlantis"],
+        tmdb_enriched_at=datetime.now(timezone.utc),
+    )
+    show_lib = _lib(db, key="2", kind="show")
+    show = PlexShow(
+        rating_key="s1",
+        library_id=show_lib.id,
+        title="Show",
+        production_countries=["United States of America"],
+    )
+    new = PlexItem(
+        rating_key="m2",
+        library_id=lib.id,
+        kind="movie",
+        title="New",
+        production_countries=[{"code": "US", "name": "United States of America"}],
+    )
+    db.add_all([old, show, new])
+    db.commit()
+
+    # Served before the backfill: the bare name, with no code — never a crash on the old shape.
+    assert tmdb.serve_block(db, old, lang="hu")["production_countries"] == [
+        {"code": None, "name": "Yugoslavia"},
+        {"code": None, "name": "Atlantis"},
+    ]
+
+    fake = FakeCountries()
+    assert tmdb.backfill_country_codes(db, fake) == 2
+    db.refresh(old)
+    db.refresh(show)
+    assert old.production_countries == [
+        {"code": "YU", "name": "Yugoslavia"},
+        {"code": None, "name": "Atlantis"},  # not in TMDB's list → no code, the name kept
+    ]
+    assert show.production_countries == [{"code": "US", "name": "United States of America"}]
+
+    # Nothing left to code: no request at all.
+    assert tmdb.backfill_country_codes(db, fake) == 0
+    assert fake.calls == 1

backend/tests/test_scheduler.py

@@ -2,7 +2,10 @@
 through (at the top of _job): holding _activity_lock across the check-and-set means exactly one
 caller can hold a job's "running" claim at a time, and it's claimable again once released."""
 
+from sqlalchemy import select
+
 from app import scheduler
+from app.models import Notification
 
 _JOB = "unit_test_claim"  # not a real job id — exercises the primitive without touching live jobs
 
@@ -23,3 +26,91 @@ def test_claim_is_exclusive_until_released():
     # ...and now it can be claimed again.
     assert scheduler._claim_running(_JOB) is True
     _release()
+
+
+# ---- E30: the result as data -------------------------------------------------------------------
+
+
+def _snapshot_job(job_id):
+    return next(j for j in scheduler.scheduler_snapshot()["jobs"] if j["id"] == job_id)
+
+
+def test_a_run_keeps_its_result_as_data_for_the_readers_language(db, make_user):
+    """The dashboard and the manual-run notice showed `_summarize`'s English one-liner ("new=3,
+    failed=0", a Python repr for a nested phase). The result rides along as data, so the client names
+    it; the one-liner stays as the fallback and the audit text."""
+    admin = make_user("sched@example.com", role="admin")
+    token = scheduler._manual_actor.set(admin.id)
+    try:
+        scheduler._job("rss_poll", lambda _db: {"new": 3, "failed": 0, "fallback": 1})
+        scheduler._job("enrich", lambda _db: 5)  # enrich returns a bare count
+    finally:
+        scheduler._manual_actor.reset(token)
+
+    rss = _snapshot_job("rss_poll")
+    assert rss["result"] == {"new": 3, "failed": 0, "fallback": 1}
+    assert rss["last_result"] == "new=3, failed=0, fallback=1"
+    assert _snapshot_job("enrich")["result"] == {"enriched": 5}
+
+    notices = db.execute(
+        select(Notification).where(Notification.user_id == admin.id).order_by(Notification.id)
+    ).scalars()
+    assert [n.data["result"] for n in notices] == [
+        {"new": 3, "failed": 0, "fallback": 1},
+        {"enriched": 5},
+    ]
+
+
+def test_a_failed_run_drops_the_previous_result(db):
+    scheduler._job("rss_poll", lambda _db: {"new": 1})
+    scheduler._job("rss_poll", lambda _db: (_ for _ in ()).throw(RuntimeError("boom")))
+    rss = _snapshot_job("rss_poll")
+    assert rss["last_error"] == "boom"
+    assert rss["result"] is None
+
+
+def test_a_job_runs_audit_row_carries_its_result_as_data(db):
+    """E30 review: the audit log names a run's result in the reader's language, as the inbox does —
+    from data, not from the English one-liner (a nested phase there was a Python dict repr)."""
+    from app.models import AuditLog, User
+
+    admin = User(email="auditrun@example.com")
+    db.add(admin)
+    db.commit()
+    scheduler._audit_run(db, None, "people_enrich", "ok", "x", {"bios": {"enriched": 2}})
+    scheduler._audit_run(db, admin.id, "rss_poll", "skipped", "sync paused", scheduler._PAUSED)
+    scheduler._audit_run(db, admin.id, "rss_poll", "error", "boom", None)
+    rows = db.execute(select(AuditLog).order_by(AuditLog.id)).scalars().all()
+    assert [r.after for r in rows] == [
+        {"status": "ok", "summary": "x", "result": {"bios": {"enriched": 2}}},
+        {"status": "skipped", "summary": "sync paused", "result": {"skipped": "sync paused"}},
+        {"status": "error", "summary": "boom"},
+    ]
+
+
+def test_a_failure_the_job_names_rides_along_as_data(db, make_user):
+    """E31: a failed RSS poll reached the Hungarian audit log as the server's English sentence. A
+    failure the job names (`progress.JobFailed`) is stored as data beside that sentence — on the
+    dashboard, the manual-run notice and the audit row — so the client says it in the reader's
+    language. Any other failure keeps only its own text (the test above)."""
+    from app import progress
+    from app.models import AuditLog
+
+    def outage(_db):
+        raise progress.JobFailed("rss_all_failed", "RSS poll failed", total=2, cause="transport")
+
+    admin = make_user("failure@example.com", role="admin")
+    token = scheduler._manual_actor.set(admin.id)
+    try:
+        scheduler._job("rss_poll", outage)
+    finally:
+        scheduler._manual_actor.reset(token)
+
+    named = {"failure": "rss_all_failed", "total": 2, "cause": "transport"}
+    rss = _snapshot_job("rss_poll")
+    assert rss["last_error"] == "RSS poll failed"
+    assert rss["result"] == named
+    notice = db.execute(select(Notification).where(Notification.user_id == admin.id)).scalar_one()
+    assert notice.data["result"] == named
+    row = db.execute(select(AuditLog).order_by(AuditLog.id.desc())).scalars().first()
+    assert row is not None and row.after["result"] == named

backend/tests/test_sync_guards.py

@@ -6,6 +6,7 @@ import logging
 import httpx
 import pytest
 
+from app import progress
 from app.sync import runner
 from app.sync.playlists import FAILED, _Breaker
 from app.sync.subscriptions import should_prune
@@ -224,8 +225,15 @@ class TestRssPollResult:
         def dead(cid):
             raise rss.RssError(f"RSS fetch for {cid} returned HTTP 404", "http_404")
 
-        with pytest.raises(RuntimeError, match="HTTP 404"):
+        with pytest.raises(RuntimeError, match="HTTP 404") as err:
             self._run(monkeypatch, fetch=dead, apply_=lambda db, ch, e: 1, channels=("UC_dead",))
+        # E31: and as data, for the reader's language — whose feed, and the reason code that tells a
+        # dead feed (`http_404`) from a dead egress (`transport`).
+        assert isinstance(err.value, progress.JobFailed)
+        assert (err.value.reason, err.value.params) == (
+            "rss_all_failed",
+            {"total": 1, "channel": "UC_dead", "cause": "http_404", "read": 0},
+        )
 
     def test_a_read_only_database_is_a_total_outage_too(self, monkeypatch):
         # Every feed reads fine, nothing can be stored: just as un-polled, just as red.

backend/tests/test_sysconfig_describe_queries.py

@@ -0,0 +1,39 @@
+"""The admin Configuration page reads every override in one query (E31 S4d).
+
+`sysconfig.describe()` did a `db.get` per key to tell whether an override was set, and `get()` did one
+more for its value: ~55 keys, and two round trips for a key with no row, since the session cannot cache
+an absence. That was ~40 ms of the page's ~55 on prod. It now reads the table once. DB lane.
+"""
+
+from sqlalchemy import event
+
+from app import sysconfig
+
+
+def _statements(db, fn) -> int:
+    seen: list[str] = []
+    engine = db.get_bind()
+    listener = lambda *a, **k: seen.append(a[2])  # noqa: E731 — (conn, cursor, statement, …)
+    event.listen(engine, "before_cursor_execute", listener)
+    try:
+        fn()
+    finally:
+        event.remove(engine, "before_cursor_execute", listener)
+    return len(seen)
+
+
+def test_describe_reads_the_overrides_once(db):
+    sysconfig.set_value(db, "quota_daily_budget", 5000)
+    db.commit()
+    assert _statements(db, lambda: sysconfig.describe(db)) == 1
+
+
+def test_describe_shows_the_stored_value_and_the_default(db):
+    sysconfig.set_value(db, "quota_daily_budget", 5000)
+    db.commit()
+    items = {i["key"]: i for g in sysconfig.describe(db)["groups"].values() for i in g}
+    assert items["quota_daily_budget"]["is_set"] is True
+    assert items["quota_daily_budget"]["value"] == 5000
+    other = next(i for k, i in items.items() if k != "quota_daily_budget" and not i["secret"])
+    assert other["is_set"] is False
+    assert other["value"] == other["default"]

backend/tests/test_sysconfig_registry.py

@@ -1,8 +1,10 @@
-"""The sysconfig registry: its order is the admin page's tab order, and a closed-set knob is a CHOICE.
+"""The sysconfig registry: a group's keys stay together, every group has its section, and a closed-set
+knob is a CHOICE.
 
 The admin Configuration page used to keep its own hand-written group order, which had already drifted
-(`explore` was missing, so its tab sorted last). The page now follows SPECS, so SPECS has to read in
-tab order: one run of keys per group.
+(`explore` was missing, so its tab sorted last). The page now follows the registry: SECTIONS orders the
+groups under their headings (E31), and a group missing there would fall off the page — so each group
+of SPECS sits in exactly one section.
 
 A closed-set admin knob is a CHOICE, not free text (E22 S2 follow-up).
 
@@ -22,7 +24,7 @@ from app.config import Settings, choices_of
 CHOICE_KEYS = {s.key for s in sysconfig.SPECS if s.type == "choice"}
 
 
-def test_each_group_is_one_run_of_keys_so_the_registry_reads_in_tab_order():
+def test_each_group_is_one_run_of_keys():
     runs = [
         s.group
         for i, s in enumerate(sysconfig.SPECS)
@@ -32,6 +34,13 @@ def test_each_group_is_one_run_of_keys_so_the_registry_reads_in_tab_order():
     assert runs[:2] == ["access", "email"]
 
 
+def test_every_group_sits_in_exactly_one_section():
+    listed = [g for _, members in sysconfig.SECTIONS for g in members]
+    assert len(listed) == len(set(listed)), listed
+    assert set(listed) == {s.group for s in sysconfig.SPECS}
+    assert [sid for sid, _ in sysconfig.SECTIONS] == ["access", "youtube", "media", "system"]
+
+
 def test_every_closed_set_knob_is_a_choice_whose_options_come_from_config():
     assert CHOICE_KEYS == {
         "search_source",
@@ -58,19 +67,23 @@ def test_the_env_accepts_any_letter_case_and_rejects_an_unknown_value():
 
 
 class _Row:
-    def __init__(self, value):
-        self.value, self.encrypted = value, False
+    def __init__(self, key, value):
+        self.key, self.value, self.encrypted = key, value, False
 
 
 class _FakeDb:
     """Just enough of a Session for sysconfig's reads: one stored override row per key."""
 
     def __init__(self, **rows):
-        self.rows = {k: _Row(v) for k, v in rows.items()}
+        self.rows = {k: _Row(k, v) for k, v in rows.items()}
 
     def get(self, _model, key):
         return self.rows.get(key)
 
+    def scalars(self, _stmt):
+        # describe() reads every override at once (E31 S4d).
+        return list(self.rows.values())
+
 
 def test_a_stored_value_reads_back_canonical_and_a_stale_one_falls_back_to_the_default():
     assert sysconfig.get_str(_FakeDb(plex_transcode_hw="OFF"), "plex_transcode_hw") == "off"
@@ -85,6 +98,14 @@ def test_describe_hands_the_picker_its_options():
     assert items["quota_daily_budget"]["choices"] == []
 
 
+def test_describe_lists_every_group_under_its_section_in_order():
+    d = sysconfig.describe(_FakeDb())
+    assert [s["id"] for s in d["sections"]] == ["access", "youtube", "media", "system"]
+    assert d["sections"][0]["groups"] == ["access", "google", "email"]
+    listed = [g for s in d["sections"] for g in s["groups"]]
+    assert sorted(listed) == sorted(d["groups"])
+
+
 def test_set_value_stores_the_canonical_spelling_and_refuses_anything_else(db):
     sysconfig.set_value(db, "search_source", "API")
     assert sysconfig.get_str(db, "search_source") == "api"

backend/tests/test_utils.py

@@ -1,8 +1,8 @@
-"""iso(): the single date/datetime→JSON serializer the routes share (R6 S1a)."""
+"""iso(): the single date/datetime→JSON serializer the routes share (R6 S1a); to_tsquery_str()."""
 
 from datetime import date, datetime, timezone
 
-from app.utils import iso, normalize_description
+from app.utils import iso, normalize_description, to_tsquery_str
 
 
 def test_none_maps_to_none():
@@ -56,3 +56,19 @@ def test_normalize_description_single_line_unchanged():
 def test_normalize_description_folds_crlf_line_endings():
     # splitlines() folds CR/CRLF to \n — a documented, benign line-ending normalization.
     assert normalize_description("a\r\nb\r\n\r\nc") == "a\nb\nc"
+
+
+def test_tsquery_prefix_matches_a_last_word_of_three_or_more():
+    assert to_tsquery_str("ti amo magyar") == "ti & amo & magyar:*"
+    assert to_tsquery_str("min") == "min:*"
+
+
+def test_tsquery_matches_a_short_last_word_whole():
+    # A 1-2 letter prefix made ts_rank score most of the library (5-8 s on prod, E31 S4e).
+    assert to_tsquery_str("m") == "m"
+    assert to_tsquery_str("minecraft 4k") == "minecraft & 4k"
+    assert to_tsquery_str("ti amo m") == "ti & amo & m"
+
+
+def test_tsquery_without_a_word_is_none():
+    assert to_tsquery_str("?! --") is None

backend/tests/test_youtube_refusals.py

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

docs/DESIGN.md

@@ -0,0 +1,704 @@
+# 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.
+5. **Judged as a whole** (E30 S6). For each screenshot, one written line on its composition: where the empty
+   space is, what hugs one side, what the eye lands on first. Then the screen at 125% and 133% browser
+   zoom and at the largest text size. All are held to [Composition and the reader](#composition-and-the-reader--decided-e30-s6).
+   A rule that holds is not the same as a screen that works: the person page passed every rule above with
+   half its panel empty.
+
+## 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]
+
+## Composition and the reader — _Decided_ (E30 S6)
+
+The rules above say how each piece looks; these say whether the screen works as a whole, for the one
+reader it is built for. Found when the person page passed every rule with its biography in the left half
+of a full-width panel and nothing on the right.
+
+- **The space is used.** A narrow element in a wide container (prose at `measure`, a form, a short list)
+  comes with a decision about the rest of the width: a second column with related content (the person
+  page: facts and bio left, "Known for" right), a container sized to its content, or a layout that stacks.
+  A band of nothing wider than about a third of a panel, beside content that stops short, is a finding.
+  [Material layout, Gestalt proximity]
+- **One focal point, then an order.** A screen has one thing the eye lands on first (the page heading, the
+  hero, the player), then the sections, then the metadata. A heading level keeps one look across screens;
+  a second focal point competing with the first is a finding. [Nielsen #8, HIG hierarchy]
+- **Worst real data, not the demo row.** A screen is judged with the longest title, the Hungarian label,
+  zero items, the largest list, a missing picture and a missing field. None of them clips, overlaps or
+  leaves a hole where a value was. [Nielsen #9, WCAG 1.4.10]
+- **Where am I.** The browser tab names the place and the object in it ("Nicolas Cage · Plex · Siftlode"),
+  the rail marks the place, and Back returns to the same view at the same scroll position with focus
+  where it was. [Nielsen #1, WCAG 2.4.2]
+- **A click answers at once.** A control shows its pressed or changed state within ~100ms (an optimistic
+  update, a spinner in the control); what a screen opens with is the app's own data — an outside service
+  (TMDB, YouTube) is fetched ahead of time by a job, not on the click, so a page never waits on it.
+  Late content keeps its place (B8). [Nielsen #1, RAIL]
+- **Zoom and text size are first-class.** The owner reads with the browser zoomed and a large text size.
+  Every screen holds at 125% and 133% browser zoom on a 1080p desktop window (what the owner uses: the
+  layout of a 1536 × 729 and a 1444 × 685 viewport) and at the largest Settings text size at 1024 wide:
+  nothing clipped or overlapping, no sideways page scroll, every control reachable and at
+  least its rung, text wrapping rather than cut. Measured, not assumed, on every UI change. [WCAG 1.4.4,
+  1.4.10, 1.4.12]
+
+## 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/locale-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".
+- **Numbers** in the UI language, from `lib/format.ts` (same lint): the decimal mark and grouping are the
+  language's ("8.3" / "8,3", "1,234" / "1 234"); a big count is compact ("1.2K" / "1,2 E"); a size keeps
+  its symbol ("5.0 GB" / "5,0 GB"), as do a stream's (Mbps) and "%" / "px". Never `toFixed` on screen.
+- **Order.** An A→Z list is in the UI language's alphabet ("Ö" after "O", "Cs" after "Cu" in Hungarian),
+  by the name the reader SEES: `compareText` (`lib/collate.ts`) on the client, the ICU collation of
+  `app/collation.py` on the server, so both sort alike.
+- **Hungarian words, not English ones** (E30 D3). Kept as Hungarian users say them: Feed, Shorts, Admin,
+  Token, Port, and technical tokens (log levels, ffmpeg presets, remux). Everything else is Hungarian:
+  közvetítés (stream), Prioritás, Feladat (job), Eseménynapló (audit), Demó, Automatikus, Infó,
+  Felület / Szerver (frontend / backend), videók behúzása (backfill), átkódolás (transcode), e-mail.
+  A longer Hungarian word gets its room — a column is sized to it, a pill truncates — never clipped.
+- 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.
+- Half a panel left empty beside content that stops short.
+- A page that waits on an outside service when the user opens it.
+- A screen checked only at 100% zoom and the default text size.
+
+## Decision log
+
+| Date       | Decision                                         | Chosen                                                                                                                                                                                                                                                                                                                 | Over                                                                                                                                                                                                   | Why                                                                                                                                                                                           |
+| ---------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 2026-09-24 | Floating button                                  | Back to top: a round 48 glass FAB; "round" = floats over something (media or the page)                                                                                                                                                                                                                                 | A Material 3 rounded square; a labelled pill; the old 64 circle                                                                                                                                        | The common web convention for back to top; round tells it apart from every toolbar button; 64 was oversized                                                                                   |
+| 2026-09-24 | Device contract                                  | Tablet portrait + landscape and up; phones out                                                                                                                                                                                                                                                                         | A 1024px floor with a "too small" message                                                                                                                                                              | Portrait tablet use is real, and the app already renders at 820 portrait                                                                                                                      |
+| 2026-09-24 | Card actions on touch                            | Fewer visible, the rest in a "…" menu                                                                                                                                                                                                                                                                                  | 44px buttons that no longer fit the card                                                                                                                                                               | Six 44px targets need more width than a card has                                                                                                                                              |
+| 2026-09-24 | Action placement                                 | One menu with several triggers, never gesture-only, a desktop background menu that mirrors the toolbar                                                                                                                                                                                                                 | Visible buttons for everything                                                                                                                                                                         | Fewer non-critical buttons on screen, without hiding any function                                                                                                                             |
+| 2026-09-24 | Text selection                                   | Text stays selectable; a click that ends a selection does nothing                                                                                                                                                                                                                                                      | Click-to-play on titles                                                                                                                                                                                | The user must be able to copy any text the app shows                                                                                                                                          |
+| 2026-09-24 | A1 Button shape                                  | r8 + a rung per context; glass is a Button variant                                                                                                                                                                                                                                                                     | r12; a pill                                                                                                                                                                                            | Nested corners (r8 in r12 in r16); the pill already means "a filter or a choice"                                                                                                              |
+| 2026-09-24 | A2 Icon buttons                                  | Two sizes, r8; a round button only on media                                                                                                                                                                                                                                                                            | One size; all round                                                                                                                                                                                    | A lone toolbar icon at the row size looks lost; round rows read as tags                                                                                                                       |
+| 2026-09-24 | A3 Touch size                                    | 44 for every control primitive                                                                                                                                                                                                                                                                                         | 36 + gaps; Button only                                                                                                                                                                                 | One rule (HIG 44) instead of two sizes nobody remembers                                                                                                                                       |
+| 2026-09-24 | A4 Input                                         | Bordered, a 55% fg-into-bg edge (≥ 3:1)                                                                                                                                                                                                                                                                                | Filled; today's look as a primitive                                                                                                                                                                    | The only option that clears WCAG 1.4.11 without a heavy fill on glass                                                                                                                         |
+| 2026-09-24 | A5 Dropdown trigger                              | Pill in a toolbar, r8 in a form                                                                                                                                                                                                                                                                                        | Pill everywhere; r8 everywhere                                                                                                                                                                         | Matches the neighbours in each context                                                                                                                                                        |
+| 2026-09-24 | A6 Checkbox, switch, slider                      | Native, accent-tinted, the row is the target                                                                                                                                                                                                                                                                           | Drawn primitives                                                                                                                                                                                       | Free keyboard / screen-reader / forced-colours support; only 3 sites                                                                                                                          |
+| 2026-09-24 | B1 Density                                       | Compact 32 / 28 / 24 by explicit height                                                                                                                                                                                                                                                                                | Standard 38 / 32 / 26                                                                                                                                                                                  | The owner's read of the lab; touch is covered separately (A3), and one toolbar row lines up at 28                                                                                             |
+| 2026-09-24 | B2 Scheme set                                    | Midnight, Forest→cyan, Slate→fuchsia, Matrix→lime                                                                                                                                                                                                                                                                      | Today's six                                                                                                                                                                                            | The accent collided with danger (YouTube), warn (Slate) and success (Forest, Matrix); Midnight and Starship were one scheme twice; 4 of 6 light accents failed 4.5:1                          |
+| 2026-09-24 | B3 State layers                                  | Text colour at 10% / 16% over anything                                                                                                                                                                                                                                                                                 | Material's 8 / 12%; today's opacity + bg-card                                                                                                                                                          | Visible in every scheme and mode (≥ 1.2:1); today's row hover was 1.00:1 on a card                                                                                                            |
+| 2026-09-24 | B4 Page chrome                                   | One sticky band + fade; filters fold when short                                                                                                                                                                                                                                                                        | A floating glass bar; everything scrolls                                                                                                                                                               | Tabs and filters always in reach, in one place; a keyboard-up tablet keeps its content                                                                                                        |
+| 2026-09-24 | B5 Surfaces                                      | One class + radius per role                                                                                                                                                                                                                                                                                            | Today's per-site mix                                                                                                                                                                                   | Nested corners and no per-site alpha drift                                                                                                                                                    |
+| 2026-09-24 | B6 /watch                                        | The app's surfaces, native video controls                                                                                                                                                                                                                                                                              | Flat and minimal                                                                                                                                                                                       | The page strangers see should look like the product; native controls work on any device                                                                                                       |
+| 2026-09-24 | B7 Nav rail                                      | Soft tint + edge bar, optional labels (a user setting), slim                                                                                                                                                                                                                                                           | Solid accent (recommended); a Material rail                                                                                                                                                            | The owner's combination: calmer than a solid fill, labels for who wants them, no width cost                                                                                                   |
+| 2026-09-24 | B8 Loading                                       | Skeleton by shape, spinner in a control                                                                                                                                                                                                                                                                                | A spinner everywhere                                                                                                                                                                                   | Nothing jumps when data lands; a long wait doesn't look stuck                                                                                                                                 |
+| 2026-09-24 | B9 Fade                                          | Toolbars / headers, panel tabs, dialog edges, chip rows                                                                                                                                                                                                                                                                | Thumbnails; buttons                                                                                                                                                                                    | The north-star depth where content scrolls under chrome; not on content or small controls                                                                                                     |
+| 2026-09-24 | C1 Action classification                         | The table (lab C1): state + primary at rest, everyday toggles on hover, "…" on touch, destructive into the menu                                                                                                                                                                                                        | Visible buttons per site, as today                                                                                                                                                                     | One action list per object, nothing gesture-only, fewer buttons without losing a function                                                                                                     |
+| 2026-09-24 | C2 Side panels                                   | A tap opens an overlay drawer; pin is a separate button ≥ 1024                                                                                                                                                                                                                                                         | A tap pins and the content reflows                                                                                                                                                                     | Below 768 the filters were unreachable; on touch a tap pinned and pushed the grid                                                                                                             |
+| 2026-09-24 | C3 Players on touch                              | Tap = show the controls; 44px seek hit area; 44 buttons; the YT description behind ⓘ                                                                                                                                                                                                                                   | Today (tap also pauses; 7.5px seek bar)                                                                                                                                                                | Measured live: you couldn't reach the seek bar without pausing, and the hover-only description never opened on a tap                                                                          |
+| 2026-09-24 | C4 Dialogs                                       | Focus by purpose; a pinned footer                                                                                                                                                                                                                                                                                      | Focus on Close; the footer scrolls                                                                                                                                                                     | A form starts in its first field, and Save stays on screen with the keyboard up                                                                                                               |
+| 2026-09-24 | C5 Plex player controls                          | The owner's lean set: no Stop / Restart / ±10 s buttons, Back by position, Next only with a next item, Resume + From the start on the card, touch double-tap ±10 s                                                                                                                                                     | Every control in one row (it ran off-screen below 1024); Back by a press counter; ±10 s keyboard-only                                                                                                  | The row fits a portrait tablet; the decision to restart is made on the card; a tablet keeps the 10 s skip                                                                                     |
+| 2026-09-24 | Glass tuner                                      | Retired; the schemes are the only colour choice                                                                                                                                                                                                                                                                        | Keep it with ranges clamped to the rules                                                                                                                                                               | Free tuning is the drift the constitution exists to stop (owner)                                                                                                                              |
+| 2026-09-24 | Matrix toned down                                | Moss #86a05a at Midnight's lightness, near-neutral greys; every white-on-accent part → `--accent-fg`                                                                                                                                                                                                                   | The B2 lime #a3e635                                                                                                                                                                                    | The owner found the lime neon and tiring; it was the loudest accent (L 0.85, C 0.21), and fixed white parts sat on it at 1.5:1                                                                |
+| 2026-09-24 | Field primitives                                 | `Input` / `Textarea` / `InnerInput` + `fieldClass`, `SelectTrigger`, the native controls; the lint rule "no raw `<input>`"                                                                                                                                                                                             | `inputCls` and ~40 hand-styled boxes                                                                                                                                                                   | Six edges, four radii and two focus looks for one control; the ≥ 3:1 edge held nowhere                                                                                                        |
+| 2026-09-25 | Surface roles                                    | `SURFACE` roles in `ui/surfaces.ts`; the lint rule "no bare glass class"; menus p-1 with r8 rows                                                                                                                                                                                                                       | Three tiers paired ad hoc with five radii and three menu paddings                                                                                                                                      | ~140 sites drifted; nested corners only hold if the radius comes with the role                                                                                                                |
+| 2026-09-25 | Static labels                                    | Flat tonal `Badge`, no edge; a filtering tag is an edged chip                                                                                                                                                                                                                                                          | A glass pill with an edge, like the chips                                                                                                                                                              | Edged = pressable at a glance; a static tag that looks like a chip gets clicked and does nothing                                                                                              |
+| 2026-09-25 | Header search                                    | A 40 glass pill with the field edge (`lg`); what sits inside it is round                                                                                                                                                                                                                                               | 44, r16, a glass box with a faint edge                                                                                                                                                                 | The one rounded box among pills, and its edge under 3:1; the hero search is the YouTube/Gmail pill                                                                                            |
+| 2026-09-25 | Switch row (F12)                                 | The whole settings row toggles (`SwitchRow`; a hand-laid row points a label at the switch)                                                                                                                                                                                                                             | Only the 36×24 switch toggles                                                                                                                                                                          | The iOS / Material settings row; the text was a dead click beside the control it names                                                                                                        |
+| 2026-09-25 | Edges and hovers (F14)                           | The ≥ 3:1 edge on the field family (fields, the form trigger); labelled pills keep the faint edge and the accent-edge hover                                                                                                                                                                                            | The ≥ 3:1 edge and a state-layer hover on every control                                                                                                                                                | 1.4.11 asks an edge only where nothing else identifies the control; a heavy edge on every chip and tab weighs the whole UI down                                                               |
+| 2026-09-25 | Rating and live (F16)                            | Own tokens: `--rating` (theme-scoped gold), `--live`/`--live-fg`, `--rating-media`, `--media-chrome`; palette classes lint-refused                                                                                                                                                                                     | Map them to `--warn` / `--danger`                                                                                                                                                                      | A gold star and a red LIVE are what the eye expects; as warn/danger they would read as a status. The old amber score was 2:1 on light                                                         |
+| 2026-09-25 | Fjord trial (B2 exception)                       | A fifth scheme, temporary: Midnight's neutrals, Playnite's steel accent (#337599 lifted to #5aa1cb) and steel rules; exit = fold into Midnight or remove                                                                                                                                                               | Retune Midnight straight away; borrow only the qualities                                                                                                                                               | The owner wants to live with the calmer palette app-wide before it replaces the default; it breaks "own hue family" on purpose, and only until that call                                      |
+| 2026-09-25 | Whole-card row (owner)                           | A card row's B3 layer is the card's `::before` under its content; the open button's hit layer spans the card, the actions sit above it                                                                                                                                                                                 | The name button's own hover, ending at the first badge or button                                                                                                                                       | A row that half-answers the pointer reads as broken; a badge click did nothing                                                                                                                |
+| 2026-09-25 | Badge tones (F29)                                | `Badge tone` neutral / accent / warn at 6%; light `--warn` #b45309 → #a14a07; edged label spans lint-refused                                                                                                                                                                                                           | Keep edged status pills (a private Badge in Users, Settings "Granted", the suggestions count)                                                                                                          | Edged = pressable at a glance; amber-700 was 4.58:1 as text and fell under 4.5 on its own tint                                                                                                |
+| 2026-09-26 | Page band built (B4)                             | Controls only in the band (intros scroll); the fold shows the same row in place; one `h1` per page (`PageHeading` steps the hidden one aside); `SectionLabel` headings; Skip to content                                                                                                                                | A popover of the folded filters; the page title kept visible                                                                                                                                           | A folded row is still the same controls, nothing duplicated; the rail and the tab title already name the page                                                                                 |
+| 2026-09-26 | Fade built (B9)                                  | `fade-below` on sticky toolbars and table headers; the scroller mask where the band sits on the backdrop                                                                                                                                                                                                               | A painted band over the backdrop                                                                                                                                                                       | The backdrop is the colour under the band, so fading the content into it is the same edge                                                                                                     |
+| 2026-09-26 | Viewport units                                   | `dvh` everywhere (the Plex player stage with S3f)                                                                                                                                                                                                                                                                      | `vh` / `h-screen`                                                                                                                                                                                      | `100vh` hides the last rows under a tablet browser's toolbar                                                                                                                                  |
+| 2026-09-26 | Video actions built (C1)                         | One list per video (menu, right-click, long-press, "…"); the card keeps watched / save / add to playlist on its picture on hover; download, details, copy, hide, reset in the menu                                                                                                                                     | The six-button row under the card and the hover ⓘ                                                                                                                                                      | The menu is the one door every device has; the card loses a line of height and the touch card its row of 28px buttons                                                                         |
+| 2026-09-26 | Plex actions built (C1)                          | One list per Plex title (play/open, watched, add to playlist, media info, copy title, pin); the poster keeps watched / add / "…" on its picture on hover; seasons get open / watched / add / copy                                                                                                                      | The hover ⓘ, the pin-only menu, an episode's add button at rest, a collection's "Remove" X on the card                                                                                                 | The same door as a video's; the collection grid goes to two columns on a phone so the touch "…" leaves the title its line                                                                     |
+| 2026-09-26 | Playlist actions built (C1)                      | A playlist row's "…" (play, pin, copy title / link, move, order, remove), Delete + an undo toast; one list per playlist (rename, pin, YouTube open / push / revert, delete) from its rail row and its header's "…"                                                                                                     | The row's X column and its confirm; the header's pencil, YouTube link, push, revert and trash buttons                                                                                                  | Remove is reversible, so it needs no confirm; the header keeps Play all; a narrow table drops "#" and Channel so the title keeps a width                                                      |
+| 2026-09-26 | Channel + Plex list actions (C1)                 | A channel row's "…" (open, pin, YouTube, copy, full history, hide + undo, unsubscribe); a Plex playlist's title / show / season "…", Delete + undo; its header's "…" (rename, delete); an action toast lasts ≥ 8 s                                                                                                     | The channel row's full-history, hide and unsubscribe buttons; the Plex list's red X on every row, show and season; the header's pencil and trash                                                       | Hiding and removing are reversible, so they need no confirm and the undo needs time; unsubscribe and deleting a playlist keep theirs                                                          |
+| 2026-09-26 | Download / notification / Scheduler actions (C1) | A download row's "…" (play, share, save, edit, details, re-download, manage sharing, copies, cancel / delete / remove); a library row's Share stays in sight, ahead of save; a notification row's "…" and hover dismiss; the inbox band's and the Scheduler strip's "…"                                                | The download row's five rare buttons and its cancel / delete / remove; the source link's copy button; an activity notice's Find / Undo links; the band's Clear everything; the strip's Purge discovery | The destructive rows keep their confirm, and Clear everything gains one; a row link keeps the browser's own menu; Find in feed drops the tag / search / age filters that could hide its video |
+| 2026-09-26 | Channel menu: Tags + Priority (C1)               | Tags A–Z as in-place checks; Priority as fixed steps 10 · 5 · 3 · 2 · 1 · 0, the current one ticked; a pick re-sorts at once and the page + focus follow the row; one drawn `MenuCheck` for every checkable row that cannot be an `<input>`                                                                            | Relative steps (+1 / +5); straight to the top; the stepper only; seven hand-drawn check marks (three box sizes, a tinted box, a × for "on", a trailing tick)                                           | Bubbling a channel up is one pick; fixed levels keep the scale the reader already uses; the list moving where the reader can see it is the feedback                                           |
+| 2026-09-26 | Reorder without a drag (WCAG 2.5.7)              | Row menus: Top / Up / Down / Bottom (YouTube + Plex playlists); saved views: four buttons with the place beside the selected view (owner: A); side panels in edit mode: an Up / Down pair per group (owner: A), the name wrapping there                                                                                | A "…" on every saved-view row; a "…" on every panel group; drag only                                                                                                                                   | A visible, one-click path where the list is edited; the edge moves shown off so the buttons never shift                                                                                       |
+| 2026-09-26 | Titles in click surfaces                         | The surface stays a button, flagged `selectable`: its text selects, and the click that ends a selection does nothing; every plain `Pressable` pinned with its reason                                                                                                                                                   | Rebuilding each card and row so the title sits outside the button; exceptions for master-detail lists                                                                                                  | Chrome selects inside a button once it is `user-select: text` (measured), so one flag on the primitive keeps the keyboard, focus and list walking every surface already has                   |
+| 2026-09-26 | Right-click on a selection                       | The browser's own menu opens on selected words; beside them the object's menu                                                                                                                                                                                                                                          | A "Copy selection" row in the app menu                                                                                                                                                                 | The reader selected the words to do something with them; the native menu copies, searches and translates, and changes nothing else                                                            |
+| 2026-09-26 | Keyboard ring on a flush row                     | Inside the row (a table row by its tag, a log line, a show header in its clipping card, with the card's corners)                                                                                                                                                                                                       | The ring outside, as on a card                                                                                                                                                                         | Outside it ran under the table head and past the table, and a clipping card cut it away entirely (invisible focus)                                                                            |
+| 2026-09-26 | Fade at rest                                     | The sticky header's fade appears with the first 1rem of scroll (a scroll-driven animation; no fade where unsupported)                                                                                                                                                                                                  | A fade that is always drawn                                                                                                                                                                            | At rest it dimmed the first row and hid its ring's top edge; nothing is under the header yet                                                                                                  |
+| 2026-09-26 | Narrow playlist table                            | "#" and Channel hide by the table's own width (under 42rem), not the window's                                                                                                                                                                                                                                          | Hiding below the `sm` window width                                                                                                                                                                     | Beside the playlist rail a desktop window left the table 432 px and the title 0 px                                                                                                            |
+| 2026-09-26 | Background menu built                            | Five list pages (feed, Plex grid, channels, playlist, notifications); the toolbar's sort / view / filters and the band's actions; no destructive row                                                                                                                                                                   | Every page with a toolbar; the "…" menus copied whole, delete included                                                                                                                                 | The tab-only pages have nothing a menu would add; a blank-area right-click must not be one click from delete                                                                                  |
+| 2026-09-26 | Media card anatomy (C)                           | One frame; the meta line pinned to its bottom; the length a badge on the picture; the Plex card on the same primitive as the video card                                                                                                                                                                                | A: the year as an overline over the title; B: the year inline after it; a fixed two-line title slot                                                                                                    | A one-line title left a hole the eye reads as a missing line; C puts nothing under a variable-height title                                                                                    |
+| 2026-09-26 | One Play                                         | `MediaPlayGlyph` (the media button variant) and only where the click plays                                                                                                                                                                                                                                             | The Plex card's hand-painted accent circle; a playable dot on every card                                                                                                                               | One Play for every card; a dot that only a colour and a tooltip explain says nothing                                                                                                          |
+| 2026-09-26 | Filtering values on the info page                | A value that filters (year, certificate, studio, director) is an edged chip; a fact is flat text                                                                                                                                                                                                                       | Everything flat, the clickable ones only hover-tinted                                                                                                                                                  | The S3d rule: edged = pressable, so the reader sees which values do something                                                                                                                 |
+| 2026-09-26 | Shelf density                                    | On any strip: one title line over one meta line                                                                                                                                                                                                                                                                        | The grid's two lines and full meta on a strip                                                                                                                                                          | The tallest card set the strip's height and left holes in the cards with less to say                                                                                                          |
+| 2026-09-26 | Compact list row (B)                             | The title leads; a faint "…" at the end; the toggles float over the date on hover                                                                                                                                                                                                                                      | A leading 128px action column                                                                                                                                                                          | That column sat empty at rest, a hole at the start of every row                                                                                                                               |
+| 2026-09-26 | Media-info layout (B)                            | A main column (collections first, crew, cast) beside a facts sidebar; an empty column is not drawn                                                                                                                                                                                                                     | Every section full width, stacked                                                                                                                                                                      | The collection is the most used; the keywords' column left a void beside a short details box                                                                                                  |
+| 2026-09-26 | Mixed Home shelf (A)                             | Plex titles as wide art beside videos                                                                                                                                                                                                                                                                                  | Posters, with the videos not stretched                                                                                                                                                                 | Stretching a video card to a poster's height left an ~80px gap                                                                                                                                |
+| 2026-09-27 | Home hero                                        | A card (hover row + Play on the picture, the whole menu, a touch "…"; owner: A); three quarters wide and centred on a wide window; one fact line; the summary at the measure                                                                                                                                           | The hero's pin row alone; full width; an 18rem picture column                                                                                                                                          | The one answer stands in focus, and it offers what the same card offers anywhere                                                                                                              |
+| 2026-09-27 | Home shelf tiles                                 | A channel / playlist tile: Play, ↗ open, "…" with Open; a show acts on its next episode, ⓘ opens it; the shelf slot 232px                                                                                                                                                                                             | The tile's pin row alone; 200px                                                                                                                                                                        | A tile without its object's actions read as broken; at 200 the Play touched the hover row                                                                                                     |
+| 2026-09-27 | Synopsis preview (C)                             | A ~0.9 s mouse rest opens a passive panel beside the card                                                                                                                                                                                                                                                              | The synopsis as the picture's `title` tooltip; an ⓘ to hover; none                                                                                                                                     | One long tooltip line fired anywhere on the art and clashed with the cut title's own tooltip                                                                                                  |
+| 2026-09-27 | Reading measure                                  | Prose capped at ~65 characters a line (`measure`)                                                                                                                                                                                                                                                                      | The container's full width                                                                                                                                                                             | At 110–130 characters a line the eye loses the next line's start                                                                                                                              |
+| 2026-09-24 | Chip family                                      | One `Chip` (filter / token / tag / suggest / ghost) + `DismissibleChip`; nothing under 24; the lint rule "no raw `<button>` outside ui/"                                                                                                                                                                               | Five chip geometries in five files                                                                                                                                                                     | The applied-filter row, the tag cells, the year picker and the saved-view editor each drew their own chip; a one-letter tag was 21px wide                                                     |
+| 2026-09-24 | Button families                                  | `Button` / `IconButton` / `Pressable` / chips / `DragHandle`; `lg` 40 for a hero CTA; pills and a 48 Play on media (from C5)                                                                                                                                                                                           | Every button hand-painted                                                                                                                                                                              | 268 hand-rolled buttons in 79 files drifted into as many looks; the ladder only holds if every button stands on it                                                                            |
+| 2026-09-27 | C4 as built                                      | `initialFocus` required on every `Modal`; the commit row in `ModalFooter`, portalled under the body from any depth; the fades driven by the body's scroll timeline; `interactive-widget=resizes-content`                                                                                                               | An optional prop defaulting to the ✕; a `footer` prop (the issue composer's buttons live three components down); always-on fades                                                                       | A default is how 21 dialogs came to open on the ✕; lifting the composer's state to reach a prop is the larger change; a resting fade dimmed the first line                                    |
+| 2026-09-27 | C3 + C5 as built                                 | A tap toggles the bar through `pointerType` from `pointerdown`; a double-tap takes back its first tap's toggle; the card's pair is the video card's `MediaResumeButtons` (Continue / Restart), a sibling over the picture; the YT description is an ⓘ click popover                                                    | A delayed single tap (wait out the double-tap window); new "Resume / From the start" words for Plex; the pair inside the picture's button                                                              | A delayed tap feels dead; one media card says one pair of words; a button inside a button is invalid and the hover row already sits beside the picture                                        |
+| 2026-09-27 | C2 as built                                      | The side panel's drawer is `ui/Modal` `drawer-start`; drawer = a coarse pointer or below 768; the pin offered in its header ≥ 1024                                                                                                                                                                                     | A drawer of its own inside `SidePanel`                                                                                                                                                                 | Esc, Back, the scrim, the trap and the scroll lock are the dialog's; a second implementation is how two shells drift                                                                          |
+| 2026-09-30 | Composition and the reader (E30 S6)              | A chapter and a Conformance step: the space is used, one focal point, worst real data, where am I, a click answers at once, zoom and text size first-class; the person page as two columns (facts and bio left, "Known for" right)                                                                                     | Rules for pieces only; the bio in a full-width panel; a narrower panel                                                                                                                                 | The person page passed every piece rule with half its panel empty; the owner reads zoomed in, so zoom is a requirement, not a nicety                                                          |
+| 2026-09-30 | Hungarian words (E30 S5)                         | The D3 list: Feed, Shorts, Admin, Token, Port stay; stream, Prio, Job, Audit, Demo, Auto, Info, Frontend/Backend, Backfill, transcode get the Hungarian word; one name per thing (kérelem, behúzás, one "Test connection")                                                                                             | Keep every loanword; translate Feed/Shorts too                                                                                                                                                         | The owner chose the list (D3); the final sweep found the same feature under two names in three places                                                                                         |
+| 2026-09-29 | Numbers and order in the UI language (E30 S3)    | Every number through `lib/format.ts` in the UI language (decimal mark, grouping, compact, units); A→Z by the shown name in the UI language's alphabet, client and server alike; the language comes off `useTranslation`, never the singleton                                                                           | `toFixed`, hand-built "1.2K", `localeCompare` in the browser's locale, byte-order server sorts                                                                                                         | A Hungarian reader saw "8.3", "1.2K", "Életrajzi" after "Z"; the singleton read also left values in the old language after a switch (React Compiler)                                          |
+| 2026-09-27 | Narrow rows by container                         | The download row, the playlist table and the Channels tag row stack by a container query; a fact line never wraps                                                                                                                                                                                                      | Breakpoints on the window                                                                                                                                                                              | The iPad zoomed in, split screen and a column beside a rail are narrow while the window is not; the zoomed download row broke "18.9 / MB" apart                                               |
+| 2026-09-27 | Phones deferred                                  | A phone-only layout (the hamburger nav, a folded feed band) waits for its own epic; E28 stays desktop + tablet                                                                                                                                                                                                         | Fix the phone views inside E28                                                                                                                                                                         | Principle 2; the first phone attempts made the feed worse, and the epic's review grows with every sprint                                                                                      |
+| 2026-09-27 | Conformance check (S3g)                          | A four-step check before a UI change is done: primitive at a named rung, the chapter re-read, the rendered page measured by kind and look, every state seen                                                                                                                                                            | A reviewer's eye per sprint                                                                                                                                                                            | The S1 probe found 69 button looks; after S3 every control kind is drawn by its primitive, and the check keeps a new look from arriving unnoticed                                             |
+| 2026-09-27 | Segmented rung                                   | `SegmentedToggle` defaults to the toolbar rung (28, `text-xs`); 24 only for a panel's captioned match toggle                                                                                                                                                                                                           | The small default                                                                                                                                                                                      | Two toolbars had inherited 10px type from the default beside 28px buttons                                                                                                                     |
+| 2026-09-27 | Copy rule (S3g)                                  | One name per feature (the rail may shorten it); four verbs for four meanings; sentence case with the app's places capitalised; "…" when a command asks first; one-sentence messages without a stop; curly quotes; dates relative in lists with the exact minute on hover, three absolute forms; units from Intl, short | Word-for-word names everywhere; the verbs as they were; all lower case; no "…"; always a stop; always absolute dates; long or compact units                                                            | The copy survey found 7 EN and 6 HU double names, 22 Delete against 27 Remove, five date shapes and three spellings of a minute; the owner picked every recommended option                    |
+| 2026-09-27 | One glyph, one meaning (S4)                      | Play only for playback or resuming a paused transfer; Retry = `RefreshCw`; reset / revert = `RotateCcw`                                                                                                                                                                                                                | Retry drawn with Play                                                                                                                                                                                  | The first UI-review run (Downloads) found a failed row whose Retry showed ▷ in the row and its menu                                                                                           |
+| 2026-09-27 | Fjord kept                                       | Fjord stays a fifth scheme beside Midnight; the trial wording goes                                                                                                                                                                                                                                                     | Fold it into Midnight; remove it                                                                                                                                                                       | The owner lived with it and likes it; the vivid Midnight stays for those who want it. B2's own-hue rule still binds any new scheme                                                            |
+| 2026-09-27 | Tablet columns                                   | A table hides `tabletHidden` columns below 64rem of its own width; Channels drops Prio, About, Length                                                                                                                                                                                                                  | Hide About only; give the name a bigger share                                                                                                                                                          | At 1024 the channel name had 60 px; the owner chose to drop all three there                                                                                                                   |
+| 2026-09-27 | Glyph pager                                      | First / previous / next / last as glyph buttons round the page box, names as tooltips                                                                                                                                                                                                                                  | Words beside the arrows (hidden only on a phone)                                                                                                                                                       | The owner's call: the words widened the row; four arrows are the shared convention                                                                                                            |
+| 2026-09-27 | Match switch on the panel                        | `ui/MatchToggle` above the picker from two picks, everywhere; one wording (Any / All)                                                                                                                                                                                                                                  | The picker's popover footer (Feed, Plex collection)                                                                                                                                                    | A closed picker hid an active "all"; six pickers had drawn it two ways                                                                                                                        |
+| 2026-09-27 | Missing picture, bare link                       | A glyph of the kind for no picture; a download with no name is titled by its short link, once                                                                                                                                                                                                                          | An empty box; the URL as title, channel and link                                                                                                                                                       | The owner's picks 4A and 3A: an empty box read as loading, the URL showed three times                                                                                                         |
+| 2026-09-27 | Copy on a selection                              | Right-click on selected words keeps the browser's menu; no app Copy row                                                                                                                                                                                                                                                | An app menu with Copy first                                                                                                                                                                            | A real browser's menu has copy, search and translate; only the desktop pane's is thin                                                                                                         |
+| 2026-10-01 | Zoom target 125–133%                             | Screens are held at 125% and 133% browser zoom (1536 × 729, 1444 × 685 on a 1080p window) and the largest text size                                                                                                                                                                                                    | 200% browser zoom                                                                                                                                                                                      | The owner: 200% was a guess; 125–133% is what they read Siftlode and most sites at, so 200% would be an upper bound nobody uses                                                               |
+| 2026-10-01 | E31 Nav rail at short heights                    | One "Admin" rail item opening a panel of the admin pages                                                                                                                                                                                                                                                               | A denser rail when short; a visible "+4" hint                                                                                                                                                          | The rail fits at 133–150% without a hidden scroll; the admin pages are rare and admin-only                                                                                                    |
+| 2026-10-01 | E31 Configuration sections                       | A vertical, grouped section list, as Settings has                                                                                                                                                                                                                                                                      | Group tabs + sub-tabs; one long page with a contents list                                                                                                                                              | Sixteen tabs wrapped to three rows at 133%; one pattern for both settings pages                                                                                                               |
+| 2026-10-01 | E31 Statistics overview                          | Number tiles, and the per-operation counts as horizontal bars                                                                                                                                                                                                                                                          | Three narrow cards; a 30-day chart                                                                                                                                                                     | The label sits by its value; what spends the quota is seen at a glance                                                                                                                        |
+| 2026-10-01 | E31 Channel page header                          | The full banner, folding to one row once the grid scrolls                                                                                                                                                                                                                                                              | Always compact; no banner                                                                                                                                                                              | The header is fixed and took 40% of a 685px window; the channel keeps its face at first sight                                                                                                 |
+| 2026-10-01 | E31 Channel page watch state                     | A fresh channel page shows the unwatched videos; a picked state is remembered                                                                                                                                                                                                                                          | Show all, forgotten on reload                                                                                                                                                                          | The owner: open a channel to see what is new; a choice made there should stick                                                                                                                |
+| 2026-10-01 | E31 Audit log runs                               | A job's successful runs fold into one row that opens, whatever ran between; only that job's failure (never folded, danger colour) breaks it                                                                                                                                                                            | A filter defaulting to admin actions; both                                                                                                                                                             | Nothing hidden, the noise collapsed, the failure seen                                                                                                                                         |
+| 2026-10-01 | E31 Users row                                    | Role and state as badges, the actions in the row's one menu                                                                                                                                                                                                                                                            | An inline role toggle; icon-only buttons                                                                                                                                                               | Action placement: the row shows state, rare and destructive actions live in the menu                                                                                                          |
+| 2026-10-01 | E31 YouTube player                               | Video beside an info panel at 1280px and wider (the video as large as the height allows); stacked below                                                                                                                                                                                                                | Today's stack with a one-line bar; full-window like Plex                                                                                                                                               | The owner's eyesight: about 1460px of video on 1080p instead of 1008, the actions still visible                                                                                               |
+| 2026-10-01 | E31 Plex info and show pages                     | A second column for the facts, keywords and crew, as the person page; a collection's hero sized to its content                                                                                                                                                                                                         | Full-width text; a larger poster and fanart                                                                                                                                                            | The right ~40% was empty; one composition for every media page                                                                                                                                |
+| 2026-10-01 | E31 Nav rail rows are links                      | Each page row is a real link: a middle-click or Ctrl-click opens the page in a new tab                                                                                                                                                                                                                                 | A button                                                                                                                                                                                               | The owner: open a page in a tab of its own, as on any site                                                                                                                                    |
+| 2026-10-02 | E31 Plex detail second column (refined)          | The facts over the key crew beside the text; the keywords, chips that filter like the genres, under the text; the show page gets all three too                                                                                                                                                                         | All three in the column, as the mockup drew it                                                                                                                                                         | At 20 keywords and 12 crew the column ran to twice the text's height (849 vs ~400 px at 133%): a hole under the text instead of beside it                                                     |
+| 2026-10-02 | E31 Plex detail poster and crew                  | The movie and show poster keeps its 2:3 and grows a rung in a wide hero (w-56 at a 64rem panel); the crew shows its first 6 names and "Show N more" (a list of 8 or fewer shows whole)                                                                                                                                 | Poster stretched to the row; a "More" on the keywords                                                                                                                                                  | The row is as tall as the crew column, so the poster drew ~175×590 and cropped; the crew, not the keywords, set the hero's height                                                             |

docs/development.md

@@ -32,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

frontend/devOnlyGuard.ts

@@ -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`.",
+          );
+        }
+      }
+    },
+  };
+}

frontend/e2e/README.md

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

frontend/e2e/channel.spec.ts

@@ -106,28 +106,34 @@ test.describe("channel view", () => {
     await expectContentType(page, "includeLive", false);
   });
 
-  // Platform S4b: the whole channel chrome (banner, identity, tabs, toolbar) is fixed — it stays
-  // put while only the video grid scrolls.
-  test("the channel chrome stays fixed while the video grid scrolls", async ({ page }) => {
+  // Platform S4b + E31 S4c: the channel chrome sits outside the scroller. Scrolling into the videos
+  // folds the banner and identity once (the name moves into the tab row); from then on the folded
+  // chrome stays put while only the video grid scrolls.
+  test("the channel chrome folds once, then stays fixed while the grid scrolls", async ({
+    page,
+  }) => {
     await openApp(page);
     await page.getByTestId("video-card-channel").first().click();
     const count = page.getByTestId("item-count");
-    const title = page.getByTestId("channel-title");
     await expect(count).toBeVisible();
     await expect(page.getByTestId("video-card").first()).toBeVisible();
-    const titleTop = await title.evaluate((el) => el.getBoundingClientRect().top);
-    const countTop = await count.evaluate((el) => el.getBoundingClientRect().top);
+    await expect(page.getByTestId("channel-folded")).toHaveCount(0);
 
     // Keep nudging until the grid is tall enough to actually scroll (it may still be filling in).
     await expect
       .poll(async () => {
-        await page.getByRole("main").evaluate((el) => el.scrollBy(0, 1500));
+        await page.getByRole("main").evaluate((el) => el.scrollBy(0, 600));
         return page.getByRole("main").evaluate((el) => el.scrollTop);
       })
       .toBeGreaterThan(400);
+    const folded = page.getByTestId("channel-folded");
+    await expect(folded).toBeVisible();
+    await expect(folded.getByTestId("channel-title")).toBeVisible();
+    const titleTop = await folded.evaluate((el) => el.getBoundingClientRect().top);
+    const countTop = await count.evaluate((el) => el.getBoundingClientRect().top);
 
-    // The chrome didn't move — banner title and toolbar are in exactly the same place.
-    expect(await title.evaluate((el) => el.getBoundingClientRect().top)).toBe(titleTop);
+    await page.getByRole("main").evaluate((el) => el.scrollBy(0, 400));
+    expect(await folded.evaluate((el) => el.getBoundingClientRect().top)).toBe(titleTop);
     expect(await count.evaluate((el) => el.getBoundingClientRect().top)).toBe(countTop);
   });
 });

frontend/e2e/global.setup.ts

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

frontend/eslint.config.js

@@ -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,232 @@ const focusSafeDisabled = {
     };
   },
 };
+// E28 S3g + E30 S3 (docs/DESIGN.md "Copy"): a date, a number and an alphabetical order are all in the
+// UI language — dates and numbers built in lib/format.ts, text compared in lib/collate.ts. A bare
+// `toLocaleString()` formats in the BROWSER's locale (seven date sites had drifted into five shapes), a
+// bare `toFixed` writes the English decimal point, a bare `localeCompare` sorts in the browser's
+// alphabet. So outside those files a `toLocale*String` call or an Intl date/number formatter is refused,
+// an `Intl.Collator` outside collate.ts, and a `localeCompare` anywhere.
+//
+// And in a component, the language itself must come off `useTranslation()`, never the i18n singleton
+// (`import i18n from "../i18n"`): the React Compiler memoizes on what it can see, and a singleton read
+// is invisible to it — a card kept "2 hr 4 min" and a Plex query its English after a switch to
+// Hungarian. The singleton is resolved by SCOPE, so `const { i18n } = useTranslation()` passes.
+const localeFormat = {
+  meta: {
+    type: "problem",
+    messages: {
+      date: "Format dates and numbers through lib/format.ts (formatDate, formatDateTime, formatNumber, formatDecimal, …), in the UI language.",
+      order:
+        "Compare text with compareText (lib/collate.ts), in the UI language — a bare localeCompare sorts in the browser's.",
+      singleton:
+        "Take the language from useTranslation() (`const { i18n } = useTranslation()`), not the i18n singleton — the React Compiler cannot see a singleton read, so the value stays in the old language after a switch.",
+    },
+  },
+  create(context) {
+    const path = context.filename.split("\\").join("/");
+    if (/\.test\.tsx?$/.test(path)) return {};
+    // lib/format.ts is where the forms live; the Plex player's on-screen clock (lib/plexPlayerPrefs.ts)
+    // is a clock face with its own 12/24h switch, not a date.
+    const formats = /\/src\/lib\/(format|plexPlayerPrefs)\.ts$/.test(path);
+    const collates = /\/src\/lib\/collate\.ts$/.test(path);
+    const component = /\/src\/components\//.test(path);
+    const importedFromI18n = (node) => {
+      for (let scope = context.sourceCode.getScope(node); scope; scope = scope.upper) {
+        const v = scope.set.get(node.name);
+        if (v)
+          return v.defs.some(
+            (d) => d.type === "ImportBinding" && /\/i18n$|^i18next$/.test(d.parent.source.value),
+          );
+      }
+      return false;
+    };
+    return {
+      "CallExpression > MemberExpression.callee[property.name=/^toLocale(Date|Time)?String$/]"(
+        node,
+      ) {
+        if (!formats) context.report({ node, messageId: "date" });
+      },
+      "MemberExpression[object.name='Intl'][property.name=/^(DateTimeFormat|RelativeTimeFormat|NumberFormat)$/]"(
+        node,
+      ) {
+        if (!formats) context.report({ node, messageId: "date" });
+      },
+      "MemberExpression[object.name='Intl'][property.name='Collator']"(node) {
+        if (!collates) context.report({ node, messageId: "order" });
+      },
+      "CallExpression > MemberExpression.callee[property.name='localeCompare']"(node) {
+        context.report({ node, messageId: "order" });
+      },
+      "MemberExpression[property.name='language'][object.type='Identifier']"(node) {
+        if (component && importedFromI18n(node.object))
+          context.report({ node, messageId: "singleton" });
+      },
+    };
+  },
+};
+// 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 +378,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,
+    "locale-format": localeFormat,
+    "input-primitive": inputPrimitive,
+    "surface-role": surfaceRole,
     "literal-a11y-text": literalA11yText,
   },
 };
@@ -167,6 +428,49 @@ 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].";
+// …and a grid's auto-fill column MINIMUM in px (`minmax(150px,1fr)`): the cards' text grows with the
+// slider while the column floor stays, so the cards get cramped at a large text size (E30 review). A
+// fixed track (`grid-cols-[1fr_240px]`) is left alone, as is VirtualGrid's measured `minCol` (a number).
+const GRID_MIN_PX = "/minmax\\([\\d.]+px,/";
+const GRID_MIN_PX_MESSAGE =
+  "px-frozen box size doesn't scale with --font-scale: give a grid column's minimum in rem (minmax(9.375rem,1fr)), not minmax(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"] },
@@ -211,7 +515,12 @@ export default tseslint.config(
       "react-hooks/refs": "off",
       "local/jsx-comment-text": "error",
       "local/focus-safe-disabled": "error",
+      "local/button-primitive": "error",
+      "local/locale-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
@@ -238,17 +547,33 @@ export default tseslint.config(
       // lib/*.contract.test.ts).
       "no-restricted-syntax": [
         "error",
+        // A next-page fetch called bare CANCELS the one in flight and sends the same cursor again;
+        // our requests ignore the abort, so the server ran both (E31 S4e: every feed page 2–3×).
+        // lib/nextPage.ts NEXT_PAGE makes the second call join the first.
+        {
+          selector:
+            "CallExpression[arguments.length=0]:matches([callee.name='fetchNextPage'], [callee.property.name='fetchNextPage'])",
+          message:
+            "fetchNextPage() cancels and re-sends a page already loading: call fetchNextPage(NEXT_PAGE) (lib/nextPage.ts).",
+        },
         // `enabled:` sees only the native attribute; a FocusSafeButton that holds the focus is
         // disabled by aria-disabled, so a bare `enabled:hover:` lit it up on hover as if it worked.
         {
           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
@@ -277,6 +602,22 @@ 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=${GRID_MIN_PX}]`, message: GRID_MIN_PX_MESSAGE },
+        { selector: `TemplateElement[value.raw=${GRID_MIN_PX}]`, message: GRID_MIN_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,
+        },
       ],
     },
   },
@@ -357,6 +698,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.
@@ -365,6 +713,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,