release: 0.109.1 (improvement/e44-fe-shell)

Gates the folder move had narrowed or left open: the MenuCheck contract scans the whole app again (it
saw only components/); local/layers refuses an import of an entry (main.tsx, the /watch page) from
any layer, and reads a backtick import() as the path it is; the /watch contract forbids the shell,
the modules and the features by folder (its one path to App had gone stale); chunkGuard's own test
gets the vitest focus/skip rules. The root tests' exemption from local/layers is in the gate
register, with its three imports.

Placement: Plex's chip builder moves into lib beside the feed's, the folder names into
features/folders, and three files only one page uses into that page. ui/FilterRail takes its reset
from useRail instead of a page id. The channel page reads the feed's view and builds "Show in feed"
itself, and the feed's scroll key is the feed's hook, so the shell holds no feed logic.

The floating header re-measures when one page's pills replace another's in the same commit (the
claim count stayed equal, so only the observer caught it). A Plex view applied and edited now stays
across a visit to another page, as the feed's does: pinned by a test. docs/development.md says what a
page with a rail adds in lib.

CHANGELOG.md

@@ -7,6 +7,42 @@ edit the release notes and re-run the generator.
 
 Upgrading, pinning a version and rolling back: [docs/self-hosting.md](docs/self-hosting.md#upgrading).
 
+## 0.109.1 — 2026-10-23
+
+### New
+
+- Development: the frontend is one folder per page (its page, rail, store and definition), with the layers held by lint and the shared /watch page held apart by a contract test; the header knows no page, and the feed and Plex each keep their own saved views.
+
+### Fixed
+
+- Saved views: a view you applied and then changed is still active after a visit to another page, in the feed and in Plex.
+
+## 0.109.0 — 2026-10-21
+
+### New
+
+- Accounts: a browser is signed in to one account at a time. The account menu's "Sign in as someone else" replaces it; the account list and switcher are gone. After this update everyone signs in once more.
+- Settings follow you: the Home start page, the channel manager and Plex playlist layouts, the discovery sorts and a dismissed onboarding or release banner are saved to your account, on every device. Performance mode stays per device.
+- Development: every key the browser stores declares its kind, held by a contract test; one Google connect route serves the sign-in and the YouTube access grants.
+
+### Fixed
+
+- Accounts: a tab still showing another account than the one signed in now reloads as that one and says why; a failed "Sign in as someone else" says what happened.
+- A link whose path starts with // no longer opens the error screen.
+- A member following a link to an admin page lands on the feed, with the rail and the address bar in step.
+- Google: an unknown access request is refused instead of quietly asking for read access, and a YouTube grant on an instance without Google says so.
+
+## 0.108.1 — 2026-10-20
+
+### New
+
+- Development: the backend is split into four units (downloads, reader, catalog, Plex), each owning its tables. A contract test holds what each one reads and writes, and that every query names whose rows it asks for.
+
+### Fixed
+
+- Watch later: saving the first two videos at once no longer makes two lists. An existing second list is merged into the first, its videos and its comfort-shelf pin with it.
+- Playback: the first resume point of a video or a Plex item no longer fails when it is saved together with the watched mark, a whole season marked at once, or a Plex sync.
+
 ## 0.108.0 — 2026-10-18
 
 ### New

CLAUDE.md

@@ -66,52 +66,70 @@ how it gets built. Concretely:
 `downloads/`, `reader/`, `discover/`, `catalog/`, `youtube/`, `issues/` (shared by routes + scheduler + worker) → flat core (`auth`, `apitokens`, `quota`, `jobruns`,
 `sysconfig`, `state`, `audit`, `notifications`, `userscope`, `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 (a shared `/watch` link boots from its own
-entry, `watch.html` → `watchMain.tsx`, held app-free by a contract test) → `moduleRegistry` route-chunks → module
-components → the **platform layer `components/ui/`** (domain-free primitives: the popover engine and
-its menus, `Modal`/`Overlay`, `Button`/`form`, `DataTable`/`VirtualGrid`, `QueryState`, …). That
-boundary is one-way and **lint-enforced**, not just described: a platform component may not import a
-feature component or a domain API slice, and one layer down `lib/` may not import from `components/` at
-all, not even a type (`no-restricted-imports` in `eslint.config.js`, with its own test). A new generic
-component goes in `ui/`; see [`frontend/src/components/ui/README.md`](frontend/src/components/ui/README.md).
-Data via react-query (`qk` factory), per-account `localStorage`, and server prefs; API through
-`lib/api/*` slices over `core.req<T>`.
+The domain is four **units**, each owning its tables: Capture (`downloads/`), Reader (`reader/`, `discover/`, the playlist
+sync), Catalog (`catalog/`, the `sync/` ingests) and Plex (`plex/`). A unit's route does no database work: it reads through
+the unit's `queries`, writes through its `service` (which flushes) and commits. A unit's code reads another unit's tables
+only along a declared edge and writes them only through that unit's service; core reaches a unit's tables through its
+`queries`. **Fence-held, with no exemptions** (`backend/tests/test_unit_fences.py`) — as far as an AST sees: what it
+cannot (an ORM write on another unit's loaded row, SQL in `text()`, a commit by `begin()`) is review's to catch, listed in
+[`backend/app/README.md`](backend/app/README.md) with the conventions.
+Frontend, by folder under `src/`: `main.tsx` provider tree → `shell/` (`App`, header, nav rail, palette,
+boot; a shared `/watch` link boots from its own entry, `watch.html` → `watchMain.tsx` → `watch/`, held
+app-free by a contract test) → **`modules/<page>/`** (one folder per page: the page, its rail, its store, its tests,
+and its `module.ts` definition — label, icon, gate, the lazy page and rail, its store — collected in nav order by
+`features/navigation/moduleRegistry`, which also mounts every store at the root; a new page is its folder, its id in
+`lib/urlState` and its entry there, plus its panel in `lib/panelLayout` if it has a rail) →
+**`features/<name>/`** (what several pages share: video cards, filters, downloads, the player, navigation) → the
+**platform layer `components/ui/`** (domain-free primitives: the popover engine and its menus, `Modal`/`Overlay`,
+`Button`/`form`, `DataTable`/`VirtualGrid`, `QueryState`,
+…) → `lib/`. The direction is one-way and **lint-enforced**, not just described (`local/layers`, with
+its own test): an import only goes down; another module is reached only through its **`index.ts`** (its
+public face — the stores, mounted at the root and read app-wide, which `features/` may read too) or
+lazily by `import()`; a platform component may not import a domain API slice, and `lib/` nothing above
+it, not even a type. A lazily imported page, rail or dialog that a static import drags onto the boot
+path fails the build (`chunkGuard.ts`). A new generic component goes in `ui/`; see
+[`frontend/src/components/ui/README.md`](frontend/src/components/ui/README.md).
+Data via react-query (`qk` factory), the signed-in account's `localStorage` (`storage.ts`), and server
+prefs; API through `lib/api/*` slices over `core.req<T>`.
 
 **Not wanted** (reviewed and rejected as over-engineering for this size): microservices, event bus,
 CQRS, a repository/DI framework, a router library, a generic CRUD-router factory or base serializer.
 
 ## Canonical patterns — when you have a choice, pick THIS
 
-| Area                                 | Use                                                                                                                                                                                               | Not                                                                                                                                                     |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ORM                                  | SQLAlchemy 2.0 `select()`                                                                                                                                                                         | `db.query(...)`                                                                                                                                         |
-| Request body                         | a Pydantic model                                                                                                                                                                                  | `payload: dict`                                                                                                                                         |
-| Request SIZE                         | nothing — `bodylimit` caps every route (SEC-20); need more? add a ceiling to `ROUTE_MAX_BODY_BYTES`                                                                                               | `capped_body` on a route that does not read raw bytes itself                                                                                            |
-| Ownership check                      | `owned_or_404` / `get_or_404`                                                                                                                                                                     | ad-hoc `_own_playlist`/`_owned`/`_own_job`                                                                                                              |
-| Admin gate import                    | `app.auth`                                                                                                                                                                                        | the `app.routes.admin` re-export                                                                                                                        |
-| Upstream failure status              | `422` with JSON detail                                                                                                                                                                            | `502` (reserve 502 for raw byte-proxies)                                                                                                                |
-| User-facing error                    | structured `detail` (`{code, reason}`)                                                                                                                                                            | a bare English string under a bilingual UI                                                                                                              |
-| Mutation response                    | `{"ok": true, …}` (`{"deleted": id}`), test-held                                                                                                                                                  | a bare `{"unsubscribed"}`/`{"cleared": n}`, no `ok`                                                                                                     |
-| Transaction commit                   | the handler commits; helpers `flush` (test-held list)                                                                                                                                             | helpers that commit (only `quota` and `jobruns` own their session)                                                                                      |
-| Admin knob storage                   | `sysconfig` (values)                                                                                                                                                                              | env / `app_state` / a table of its own (the job intervals had one)                                                                                      |
-| 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 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 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 loading/empty/error               | `QueryState` / `StateMessage`                                                                                                                                                                     | ad-hoc conditionals                                                                                                                                     |
-| FE failed write                      | `meta.failTitle`, else `notifyActionError(err, title)`; a YouTube write action (subscribe, sync, …): `notifyYouTubeActionError` — a 403 offers Connect                                            | a bare `catch {}` or `notify()` with no error attached                                                                                                  |
-| FE floating or full-screen layer     | `ui/Overlay` (portals to `<body>`) or the popover engine (`AnchoredPopover` portals itself); stacking by the z-index scale (`z-menu` … `z-popover`, docs/DESIGN.md "Layers")                      | one rendered in place inside a virtualized row or a masked/transformed scroller — clipped or painted over; a magic `z-[n]`                              |
-| FE player on a native media element  | `lib/mediaSession` (`useMediaSession`) + `lib/mediaKeys` + `lib/resume` (`useResume`), the element held as STATE                                                                                  | a private `navigator.mediaSession` / `keydown` / position-saving effect per player                                                                      |
-| FE diagnostics                       | `lib/log.ts` (`log.info("event.code", msg, attrs)`); a filter change → `lib/filterLog.ts`, a player → `lib/mediaLog.ts`                                                                           | `console.*` (lint-enforced); a value only a higher level may carry, logged unguarded                                                                    |
-| FE state that MIRRORS a prop/query   | derive it, or hold a draft (`draft ?? server`)                                                                                                                                                    | a copy an effect re-syncs — that paints the stale value first                                                                                           |
-| FE state reset on a key change       | adjust it DURING render against a remembered key                                                                                                                                                  | `useEffect(() => setX(init), [key])`                                                                                                                    |
-| FE effect that must not re-subscribe | `useEffectEvent` (React 19.2+); a handler or timer: `useLatest` / `useStableCallback`                                                                                                             | a render-phase `ref.current = x` — the React Compiler skips the component                                                                               |
-| FE hook suppression                  | an inline `eslint-disable-next-line` NAMING the invariant                                                                                                                                         | `eslint-suppressions.json` (deliberately absent — E27 S2)                                                                                               |
-| FE popover / scroll-fade ref         | destructure it: `const { setReference } = pop.refs`, then `ref={setReference}`                                                                                                                    | `ref={pop.refs.setReference}` / `ref={fade.ref}` — the compiler then treats the whole object as a ref and skips                                         |
-| FE async handler with cleanup        | `try { … } catch { … }`, then the cleanup after it (steps that `return` early go in their own function); a conditional, loop or `?.` the `try` needs goes before it or into a module-level helper | `try/finally`, or a `?:` / `??` / loop / `?.` inside `try` — the React Compiler skips the whole component (and `react-hooks/todo` misses most of these) |
+| Area                                 | Use                                                                                                                                                                                                                                           | Not                                                                                                                                                                                         |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ORM                                  | SQLAlchemy 2.0 `select()`                                                                                                                                                                                                                     | `db.query(...)`                                                                                                                                                                             |
+| Request body                         | a Pydantic model                                                                                                                                                                                                                              | `payload: dict`                                                                                                                                                                             |
+| Request SIZE                         | nothing — `bodylimit` caps every route (SEC-20); need more? add a ceiling to `ROUTE_MAX_BODY_BYTES`                                                                                                                                           | `capped_body` on a route that does not read raw bytes itself                                                                                                                                |
+| Ownership check                      | `userscope.owned_by` (a filter) / `owned_row` (a row by id): a unit's `queries.own_x` returns None and its route answers `not_found`; a core route `owned_or_404`. A composite rule (own or shared, built-in or own) says so in its `queries` | an inline owner filter — `Model.user_id == …`, an alias's, `.in_()`, `filter_by(user_id=…)` (fence-held, every module) — or a `db.get` and a compare where `owned_row` fits                 |
+| Admin gate import                    | `app.auth`                                                                                                                                                                                                                                    | the `app.routes.admin` re-export                                                                                                                                                            |
+| Upstream failure status              | `422` with JSON detail                                                                                                                                                                                                                        | `502` (reserve 502 for raw byte-proxies)                                                                                                                                                    |
+| User-facing error                    | structured `detail` (`{code, reason}`)                                                                                                                                                                                                        | a bare English string under a bilingual UI                                                                                                                                                  |
+| Mutation response                    | `{"ok": true, …}` (`{"deleted": id}`), test-held                                                                                                                                                                                              | a bare `{"unsubscribed"}`/`{"cleared": n}`, no `ok`                                                                                                                                         |
+| Transaction commit                   | the handler commits; a unit's `service` and every helper `flush` (fence-held, every module)                                                                                                                                                   | a helper that commits — only a listed one (what owns its session, or a core step that must land whatever its caller does next), each with its reason: the fence's `UNIT_COMMITS` / `CORE_COMMITS`, a route's `COMMITTING_HELPERS` (`test_route_conventions`) |
+| Admin knob storage                   | `sysconfig` (values)                                                                                                                                                                                                                          | env / `app_state` / a table of its own (the job intervals had one)                                                                                                                          |
+| 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 browser storage                   | a key in `storage.ts` with its kind (contract-held): a `pref` through `usePref` (the server's, follows the account); `device` / `view` / `cache` this browser's; `public` kept for the /watch page                                            | a `"siftlode.x"` literal; a preference kept only in `localStorage` (it stays on one device)                                                                                                 |
+| 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 a page's header content           | the page renders it into the floating header itself (`PageHeader`, `ui/PageShell`)                                                                                                                                                            | a `page === …` branch in the shell's header, or a bridge carrying a page's state up to it                                                                                                   |
+| FE module store                      | its definition's `Store` (`module.ts`), mounted at the root by `ModuleStores`; it reads no other module's store (contract-held)                                                                                                               | a provider hand-nested in `main.tsx`                                                                                                                                                        |
+| FE saved views                       | the module's own store from `features/filters` (`createSavedViewsStore` + `useSavedViewsStore`)                                                                                                                                               | one store switched by the active page — every visit elsewhere reset it                                                                                                                      |
+| 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 loading/empty/error               | `QueryState` / `StateMessage`                                                                                                                                                                                                                 | ad-hoc conditionals                                                                                                                                                                         |
+| FE failed write                      | `meta.failTitle`, else `notifyActionError(err, title)`; a YouTube write action (subscribe, sync, …): `notifyYouTubeActionError` — a 403 offers Connect                                                                                        | a bare `catch {}` or `notify()` with no error attached                                                                                                                                      |
+| FE floating or full-screen layer     | `ui/Overlay` (portals to `<body>`) or the popover engine (`AnchoredPopover` portals itself); stacking by the z-index scale (`z-menu` … `z-popover`, docs/DESIGN.md "Layers")                                                                  | one rendered in place inside a virtualized row or a masked/transformed scroller — clipped or painted over; a magic `z-[n]`                                                                  |
+| FE player on a native media element  | `lib/mediaSession` (`useMediaSession`) + `lib/mediaKeys` + `lib/resume` (`useResume`), the element held as STATE                                                                                                                              | a private `navigator.mediaSession` / `keydown` / position-saving effect per player                                                                                                          |
+| FE diagnostics                       | `lib/log.ts` (`log.info("event.code", msg, attrs)`); a filter change → `lib/filterLog.ts`, a player → `lib/mediaLog.ts`                                                                                                                       | `console.*` (lint-enforced); a value only a higher level may carry, logged unguarded                                                                                                        |
+| FE state that MIRRORS a prop/query   | derive it, or hold a draft (`draft ?? server`)                                                                                                                                                                                                | a copy an effect re-syncs — that paints the stale value first                                                                                                                               |
+| FE state reset on a key change       | adjust it DURING render against a remembered key                                                                                                                                                                                              | `useEffect(() => setX(init), [key])`                                                                                                                                                        |
+| FE effect that must not re-subscribe | `useEffectEvent` (React 19.2+); a handler or timer: `useLatest` / `useStableCallback`                                                                                                                                                         | a render-phase `ref.current = x` — the React Compiler skips the component                                                                                                                   |
+| FE hook suppression                  | an inline `eslint-disable-next-line` NAMING the invariant                                                                                                                                                                                     | `eslint-suppressions.json` (deliberately absent — E27 S2)                                                                                                                                   |
+| FE popover / scroll-fade ref         | destructure it: `const { setReference } = pop.refs`, then `ref={setReference}`                                                                                                                                                                | `ref={pop.refs.setReference}` / `ref={fade.ref}` — the compiler then treats the whole object as a ref and skips                                                                             |
+| FE async handler with cleanup        | `try { … } catch { … }`, then the cleanup after it (steps that `return` early go in their own function); a conditional, loop or `?.` the `try` needs goes before it or into a module-level helper                                             | `try/finally`, or a `?:` / `??` / loop / `?.` inside `try` — the React Compiler skips the whole component (and `react-hooks/todo` misses most of these)                                     |
 
 Not repeated here, because a lint rule refuses the wrong one and its message names the right one:
 buttons (`ui/Button`, `IconButton`, `Pressable`, `Chip`, `DragHandle`), text fields and native

VERSION

@@ -1 +1 @@
-0.108.0
+0.109.1

backend/alembic/versions/0112_one_watch_later.py

@@ -0,0 +1,70 @@
+"""One Watch later list per user, held by the database
+
+Revision ID: 0112_one_watch_later
+Revises: 0111_audit_request_id
+Create Date: 2026-10-20
+
+Watch later was made on a user's first save by a read then an insert, so two first saves at once
+each made a list, and the reader then picked between them at random. A partial unique index holds
+"one per user" now. An instance that already has a second list keeps the oldest: the others' videos
+move into it (after its own, in their order; one it already holds is not added twice), a Home pin
+of one of them moves to it (unless it is pinned itself; of several, the first on the shelf), then
+they go — a pin left on them goes with them, as the kept list already holds one.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0112_one_watch_later"
+down_revision: str | None = "0111_audit_request_id"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+_EXTRA = """
+    SELECT p.id, k.keep_id
+    FROM playlists p
+    JOIN (
+        SELECT user_id, min(id) AS keep_id FROM playlists WHERE kind = 'watch_later' GROUP BY user_id
+    ) k ON k.user_id = p.user_id
+    WHERE p.kind = 'watch_later' AND p.id <> k.keep_id
+"""
+
+
+def upgrade() -> None:
+    op.execute(
+        f"""
+        INSERT INTO playlist_items (playlist_id, video_id, position, added_at)
+        SELECT e.keep_id, i.video_id,
+               (SELECT coalesce(max(position), -1) FROM playlist_items WHERE playlist_id = e.keep_id)
+               + row_number() OVER (PARTITION BY e.keep_id ORDER BY i.playlist_id, i.position, i.id),
+               i.added_at
+        FROM playlist_items i
+        JOIN ({_EXTRA}) e ON e.id = i.playlist_id
+        ON CONFLICT ON CONSTRAINT uq_playlist_video DO NOTHING
+        """
+    )
+    op.execute(
+        f"""
+        UPDATE comfort_pins c SET playlist_id = m.keep_id
+        FROM (
+            SELECT DISTINCT ON (e.keep_id) p.id AS pin_id, e.keep_id
+            FROM comfort_pins p
+            JOIN ({_EXTRA}) e ON e.id = p.playlist_id
+            WHERE NOT EXISTS (SELECT 1 FROM comfort_pins k WHERE k.playlist_id = e.keep_id)
+            ORDER BY e.keep_id, p.position, p.id
+        ) m
+        WHERE c.id = m.pin_id
+        """
+    )
+    op.execute(f"DELETE FROM playlists WHERE id IN (SELECT id FROM ({_EXTRA}) e)")
+    op.create_index(
+        "uq_playlist_watch_later",
+        "playlists",
+        ["user_id"],
+        unique=True,
+        postgresql_where=sa.text("kind = 'watch_later'"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("uq_playlist_watch_later", table_name="playlists")

backend/app/README.md

@@ -1,9 +1,8 @@
 # Backend conventions
 
 The rules below are already followed across `backend/app` — they lived only in a few module
-docstrings (`userscope.py`, `routes/_common.py`) until this file collected them (E3 S3,
-B-core-20). When you add code, match these so the next reader doesn't have to guess "which pattern do
-I copy".
+docstrings (`userscope.py`, `routes/_common.py`) until this file collected them. When you add code,
+match these so the next reader doesn't have to guess "which pattern do I copy".
 
 ## Module layering
 
@@ -13,12 +12,13 @@ Three layers, by *who* runs the code — not by feature:
    response models, status-code mapping, serialization. It owns logic that runs *only* on a request.
    Business logic that a request happens to trigger does **not** live here if anything else runs it too.
 
-2. **`plex/`, `downloads/`, `sync/`, `issues/` — domain logic shared by more than one caller.** Anything the
-   **scheduler or the worker** runs (not just a request) lives in one of these domain packages, so the
-   route, the worker, and the scheduler share one definition. Examples from this codebase:
-   `downloads/service.py` owns enqueue + the job state transitions (routes call it); `plex/sync.py` is
-   run by both the admin route and the scheduler; `downloads/pipeline.py` is the worker's child pipeline;
-   `issues/bundle.py` is the one definition of a bug report's files, for the zip export and the tracker.
+2. **The units and the other domain packages — logic shared by more than one caller.** A unit's
+   database work (below), and anything the **scheduler or the worker** runs (not just a request), lives
+   in a domain package, so the route, the worker, and the scheduler share one definition. Examples from
+   this codebase: `downloads/service.py` owns enqueue + the job state transitions (routes call it);
+   `plex/sync.py` is run by both the admin route and the scheduler; `downloads/pipeline.py` is the
+   worker's child pipeline; `issues/bundle.py` is the one definition of a bug report's files, for the
+   zip export and the tracker.
 
 3. **Flat `app/*.py` core modules — cross-cutting primitives.** `auth` (with `apitokens`, a machine's
    folder-scoped way into the Files library), `sysconfig`, `quota`, `audit`, `jobruns` (every
@@ -34,19 +34,59 @@ Three layers, by *who* runs the code — not by feature:
 a layer — into the relevant domain package, or a flat core module if it's cross-cutting. Don't
 pre-abstract for a single caller; don't leave shared logic duplicated once there are two.
 
+## Units
+
+The domain is four units, each owning its tables (`models.py` in its package):
+
+| Unit | Package | Its routes |
+| --- | --- | --- |
+| Capture | `downloads/`, the worker | `downloads.py`, `files.py`, `public.py` |
+| Reader | `reader/`, `discover/`, `feedquery.py`, the playlist sync and tag suggestions in `sync/` | `feed.py`, `playlists.py`, `saved_views.py`, `discover.py`, `tags.py` |
+| Catalog | `catalog/`, the ingests in `sync/` | `channels.py`, `search.py`, `sync.py` |
+| Plex | `plex/` | `plex/` |
+
+- **A unit's route does no database work.** It validates, reads through the unit's `queries.py`,
+  writes through its `service.py`, serializes, and commits. It may name a unit's model as a type
+  (under `TYPE_CHECKING`), never use one as a value, and it passes a kind (`"movie"`), not a model, to
+  a query.
+- **A unit's code keeps to its edges.** It reads another unit's tables only along a declared edge
+  (Capture and Reader read Catalog's and Plex's: the feed joins `Video` with `VideoState` in one
+  query) and writes them only through the owner's service. Core code reaches a unit's tables through
+  that unit's `queries`.
+- **Whose a row is, `userscope` says** — in every module, core included: `owned_by(Model.user_id,
+  user)` for a filter, `owned_row(db, Model, id, user)` for a row by id (someone else's row is the
+  same answer as a missing one). A unit's `queries.own_x` returns None and its route answers
+  `not_found`; a core route calls `owned_or_404`. A rule `owned_row` cannot say — a job its owner
+  shared, a built-in profile nobody owns, a folder read under `FOR SHARE` — is written out in the
+  unit's own code, beside the reason.
+
+All of it is held by `tests/test_unit_fences.py`, with no exemptions: the unit map, each unit's
+packages and edges (`UNIT_PACKAGES`, `READS`) and what may commit (`UNIT_COMMITS`, `CORE_COMMITS`)
+are listed there. It reads the code's AST, so it holds the forms written here: an owner column
+compared inline (a model's, an import alias's or an `aliased()` one's, by `==`, `!=`, `.in_()`, or a
+`filter_by(user_id=…)`), a model built or an `insert`/`update`/`delete` (under any import name, of a
+model or its `__table__`) across units, and a `.commit()` call off the lists all fail it. What an AST
+cannot tell is review's to catch: an ORM write on another unit's loaded row (an attribute, a
+`db.delete`), SQL in `text()`, a column or model reached another way (bound to a variable, through
+`__table__.c` or a module path), and a commit made by a `begin()` block or a `commit` handed in.
+
 ## Transaction ownership
 
-This follows CLAUDE.md's canonical rule verbatim — **"the handler/job-wrapper commits; helpers flush
-(only `quota` and `jobruns` own their session)"** — so read it that way, not as an exception to it. The commit belongs
-to the **operation owner**; anything called *inside* another transaction only stages its change
+This follows CLAUDE.md's canonical rule — **the handler commits; a unit's `service` and every helper
+flush** — so read it that way, not as an exception to it. The commit belongs to the **operation
+owner**; anything called *inside* another transaction only stages its change
 (`db.add` / `flush`) and lets the owner commit, so the whole operation is one transaction.
 `audit.record()` is the reference: it adds the audit row and the caller commits it together with the
 mutation it records, so an audit entry can never exist without its change (or vice-versa).
 
-- The **operation owner** is usually the route handler. A `service.*` operation the handler delegates a
-  whole transition to (e.g. `service.cancel`) *is* that owner and commits its one transition — it isn't
-  a mid-operation helper. A helper that owns its OWN short-lived session (the worker's `jobdb` writes,
-  `jobruns`' run rows — the same carve-out CLAUDE.md grants `quota`) commits that session. Everything else flushes.
+- The **operation owner** is the route handler, or a job. A unit's `service` flushes even when it
+  makes a whole transition (`service.cancel`): the handler commits it, together with whatever else the
+  request changed. What owns its OWN session commits it: `quota` and `jobruns`' run rows, the
+  scheduler's jobs, a unit's jobs (the worker's `jobdb` writes, the syncs and ingests that commit per
+  page or batch so a later failure loses nothing already stored), and a few core steps that must land
+  whatever their caller does next (a token's last-used stamp, a refreshed YouTube grant) — the fence's
+  `UNIT_COMMITS` and `CORE_COMMITS` name each with its reason, `test_route_conventions` a route's own
+  committing helpers. Everything else flushes.
 - `SessionLocal` is `expire_on_commit=False`: after a raw `UPDATE` + commit, an ORM object you already
   loaded is **stale**. Read the fresh value from the row (RETURNING, or a re-`SELECT`), not the ORM
   attribute — see `service.decr_ref_count`.

backend/app/apitokens.py

@@ -26,6 +26,7 @@ from fastapi import Depends, Request
 from sqlalchemy import delete, or_, select, update
 from sqlalchemy.orm import Session
 
+from app.userscope import owned_by
 from app import audit, debugsession, logs
 from app.audit import AuditAction
 from app.auth import current_user
@@ -223,7 +224,9 @@ def revoke_all(db: Session, user_id: int) -> int:
     change, "log out everywhere", a revoked untrusted password — ends its tokens too: one minted
     from a stolen session must not outlive the owner's answer to that theft. Returns how many."""
     gone = (
-        db.execute(delete(ApiToken).where(ApiToken.user_id == user_id).returning(ApiToken.id))
+        db.execute(
+            delete(ApiToken).where(owned_by(ApiToken.user_id, user_id)).returning(ApiToken.id)
+        )
         .scalars()
         .all()
     )

backend/app/audit.py

@@ -110,10 +110,9 @@ def record(
 
 def gc(db: Session, retention_days: int) -> int:
     """Delete audit rows older than `retention_days`. Returns the number removed. A
-    retention_days <= 0 disables pruning (keep forever)."""
+    retention_days <= 0 disables pruning (keep forever). Flushes; the job commits."""
     if retention_days <= 0:
         return 0
     cutoff = datetime.now(timezone.utc) - timedelta(days=retention_days)
     result = db.execute(delete(AuditLog).where(AuditLog.created_at < cutoff))
-    db.commit()
     return result.rowcount or 0

backend/app/auth.py

@@ -4,6 +4,7 @@ from sqlalchemy import delete, func, select
 from sqlalchemy.orm import Session
 from starlette.requests import HTTPConnection
 
+from app.userscope import owned_by
 from app import debugsession
 from app import email as email_mod
 from app import logs
@@ -24,8 +25,6 @@ def operator_contact() -> str | None:
     return next(iter(sorted(settings.admin_email_set)), None)
 
 
-MAX_SESSION_ACCOUNTS = 6
-
 # OAuth scope vocabulary — the atoms + the request bundles, kept together as core. has_*_scope check
 # the atoms against a user's stored grant; the *_SCOPES bundles are what the login/callback endpoints
 # request (imported by app/routes/auth.py).
@@ -230,7 +229,7 @@ def purge_user(db: Session, user: User, background: BackgroundTasks) -> None:
     # request's access line, a queued row, a later background task would otherwise put rows back
     # under the id after this DELETE (logs.forget_user).
     logs.forget_user(user_id)
-    db.execute(delete(LogEvent).where(LogEvent.user_id == user_id))
+    db.execute(delete(LogEvent).where(owned_by(LogEvent.user_id, user_id)))
     # Every canonically-equal invite goes, not just the literal spelling: is_allowed matches on the
     # canonical form, so leaving a sibling row behind would keep granting access to a mailbox whose
     # account was just erased — and prod really does carry approved pairs for one mailbox.
@@ -252,94 +251,63 @@ def purge_user(db: Session, user: User, background: BackgroundTasks) -> None:
     background.add_task(email_mod.send_account_deleted, email, lang, operator_contact())
 
 
-ACTIVE_ACCOUNT_HEADER = "x-siftlode-account"
+def session_user_id(conn: HTTPConnection) -> int | None:
+    """The account this browser session signed in as, read from the signed cookie alone (no DB).
+    One account per session: signing in as another replaces it (`routes.auth._establish_session`)."""
+    return conn.session.get("user_id")
 
 
-def resolved_user_id(conn: HTTPConnection, *, strict: bool = True) -> tuple[int | None, bool]:
-    """Which account this connection acts as, and whether that's the session's default account.
-    Takes an HTTPConnection rather than a Request: it reads only the session and the headers.
-
-    The signed cookie holds the *wallet* (`account_ids`, every account signed into this browser)
-    plus a default `user_id`. A caller may name its account with the X-Siftlode-Account header (or
-    `?account=`), but ONLY an account in the wallet — so a tab can't impersonate an account that
-    never authenticated here. A connection that names no account acts as the cookie default.
-
-    A connection naming an account NOT in the wallet acts as nobody (`None`) — typically a tab still
-    pinned to an account that was signed out in another tab. It must not fall back to the default:
-    that tab would go on acting as an account it never showed, its player checkpoints and pref saves
-    landing there and its Sign out signing THAT account out. Only the bootstrap /api/me probe passes
-    `strict=False` and gets the default, which is how such a tab learns who it now is (the frontend
-    re-pins it and reloads). An account whose session ended while it stayed in the wallet (deleted,
-    suspended, revoked) leaves the wallet when it is refused (`_session_user`), so a tab pinned to it
-    takes the same way back.
-    """
-    default_id = conn.session.get("user_id")
-    wallet = conn.session.get("account_ids") or []
-    # Header for normal XHR; ?account= for a context that can't set headers (a plain <a> file
-    # download). Both are wallet-gated below.
-    hdr = conn.headers.get(ACTIVE_ACCOUNT_HEADER) or conn.query_params.get("account")
-    if hdr:
-        try:
-            hid = int(hdr)
-        except ValueError:
-            # Under `strict` this becomes a 401 and the tab authenticates as nobody, which reads
-            # in the browser exactly like a session that expired. The value itself stays out —
-            # it came from a request, and `wallet` says which accounts were actually on offer.
-            log.debug(
-                "the active-account header could not be read as an id",
-                extra=logs.event("auth.account_header.invalid", accounts=len(wallet)),
-            )
-            hid = None
-        if hid is not None and hid in wallet:
-            return hid, hid == default_id
-        if strict:
-            return None, False
-    return default_id, True
+def stamp_session(request: Request, user: User) -> None:
+    """Record the account's current `session_epoch` in the signed cookie, so `current_user` can later
+    reject the cookie once the epoch moves (password reset/change, or "log out everywhere")."""
+    request.session["epoch"] = user.session_epoch or 0
 
 
-def drop_from_wallet(session: dict, user_id: int) -> None:
-    """Take one account out of this browser's wallet (`account_ids`); the session default is untouched."""
-    session["account_ids"] = [a for a in (session.get("account_ids") or []) if a != user_id]
+# The account a tab was built for, sent with every request it makes (`identityHeaders`, the
+# frontend). The cookie alone says who is asking, and one browser holds one account: a sign-in as
+# someone else in another tab replaces it under every open tab. A tab still showing the previous
+# account would otherwise act as the new one — its player checkpoints, pref saves, Sign out and
+# Delete account landing there — until it noticed. It never selects an account; a mismatch is
+# refused, and the tab reloads as whoever is signed in now.
+EXPECTED_ACCOUNT_HEADER = "x-siftlode-expect-account"
 
 
-def _end_account_session(request: Request, user_id: int, is_default: bool) -> None:
-    """An account whose session here is no longer valid. Only nuke the whole session when it is the
-    SESSION DEFAULT; a per-tab account just leaves the wallet (other tabs' default may still be valid).
-    Leaving is what lets a tab pinned to it recover: its next /api/me names an account no longer signed
-    in here and gets the default. Left in, it answered "signed out" — the landing page, with the default
-    still signed in, and no way off it but closing the tab."""
-    if is_default:
-        request.session.clear()
-    else:
-        drop_from_wallet(request.session, user_id)
+def built_for_another_account(user_id: int, expected: str | None) -> bool:
+    """Whether a tab naming `expected` is showing another account than the one signed in. No name is
+    no claim (a caller from before this check, a script): only a mismatch is refused, and the
+    session stays — it is the other tab's sign-in, and it holds. The one comparison for every way a
+    tab names its account: this header on a request, `expect` on a navigation."""
+    if expected is None or expected == str(user_id):
+        return False
+    log.info(
+        "a request from a tab built for another account was refused",
+        extra=logs.event("auth.session.account_changed", user_id=user_id),
+    )
+    return True
 
 
 def current_user(request: Request, db: Session = Depends(get_db)) -> User:
-    return _session_user(request, db, *resolved_user_id(request))
+    user = _session_user(request, db, session_user_id(request))
+    if built_for_another_account(user.id, request.headers.get(EXPECTED_ACCOUNT_HEADER)):
+        raise refused(401, "account_changed")
+    return user
 
 
-def _session_user(request: Request, db: Session, user_id: int | None, is_default: bool) -> User:
+def _session_user(request: Request, db: Session, user_id: int | None) -> User:
     if not user_id:
         raise refused(401, "not_authenticated")
     user = db.get(User, user_id)
     if user is None or not user.is_active or user.is_suspended:
         # Suspended/deactivated mid-session → end it so the block takes effect at once.
-        _end_account_session(request, user_id, is_default)
+        request.session.clear()
         raise refused(401, "not_authenticated")
-    # SA4: reject a cookie whose recorded epoch is behind the account's current one (revoked by a
-    # password reset/change or "log out everywhere"). A cookie with no recorded epoch (pre-SA4, or an
-    # account signed in before this shipped) is treated as epoch 0 — so the FIRST bump revokes it too.
-    epochs = request.session.get("epochs") or {}
-    if int(epochs.get(str(user_id), 0)) != (user.session_epoch or 0):
-        _end_account_session(request, user_id, is_default)
+    # A cookie whose epoch is behind the account's (revoked by a password reset/change or "log out
+    # everywhere") is refused — and so is one with no epoch at all, which only a build before the
+    # one-account session wrote: its holder signs in once more.
+    epoch = request.session.get("epoch")
+    if epoch is None or int(epoch) != (user.session_epoch or 0):
+        request.session.clear()
         raise refused(401, "not_authenticated")
-    # Always keep the session default in the switchable list — covers sessions created before
-    # multi-session existed (their account_ids was never seeded), so the switcher isn't empty.
-    default_id = request.session.get("user_id")
-    accounts = request.session.get("account_ids") or []
-    if default_id and default_id not in accounts:
-        accounts.append(default_id)
-        request.session["account_ids"] = accounts[-MAX_SESSION_ACCOUNTS:]
     # Attribute this request's log lines to the account. Here, not in the request middleware:
     # this is the one place a session becomes an account, and the middleware runs outside both the
     # session middleware and this task's context. `request.state` is shared across middleware layers
@@ -357,25 +325,17 @@ def _session_user(request: Request, db: Session, user_id: int | None, is_default
 def optional_current_user(request: Request, db: Session = Depends(get_db)) -> User | None:
     """Like `current_user` but returns None instead of raising 401 when there's no valid session.
     Used by the bootstrap /api/me probe so the logged-out landing doesn't log a failed request to
-    the browser console (a non-2xx fetch is a console error no matter how the app handles it).
-    The one lenient resolution (`strict=False`): a tab naming an account no longer signed in here gets
-    the default account, which is how it learns who it now is — see `resolved_user_id`. That includes an
-    account refused right here, which `_session_user` has just taken out of the wallet."""
-    user_id, is_default = resolved_user_id(request, strict=False)
+    the browser console (a non-2xx fetch is a console error no matter how the app handles it)."""
+    user_id = session_user_id(request)
+    if user_id is None:
+        return None
     try:
-        return _session_user(request, db, user_id, is_default)
-    # silent-ok: this is the anonymous case as much as the refused one — every landing page hit
-    # comes through here. The second attempt below is the handling, and it reports.
+        return _session_user(request, db, user_id)
     except HTTPException:
-        if is_default:
-            return None
-    try:
-        return _session_user(request, db, *resolved_user_id(request, strict=False))
-    except HTTPException:
-        # Both the pinned account AND the default one were refused, so the tab is signed out
-        # without being told why — and it got here from a session that named a real account.
+        # A session that named an account, refused: the browser is signed out without being told
+        # why, so say it here.
         log.info(
-            "a session was resolved to nobody: neither the named nor the default account held",
+            "a session was refused: its account no longer holds",
             extra=logs.event("auth.session.probe_rejected", user_id=user_id),
         )
         return None

backend/app/debugsession.py

@@ -26,6 +26,7 @@ from uuid import uuid4
 from sqlalchemy import and_, delete, func, not_, select, update
 from sqlalchemy.orm import Session, defer
 
+from app.userscope import owned_by, owned_row
 from app import diagnostics
 from app.models import DebugScreenshot, DebugSession, LogEvent, User
 
@@ -76,7 +77,9 @@ def open_session(db: Session, user: User) -> DebugSession | None:
 
 def _unclosed(db: Session, user: User) -> DebugSession | None:
     return db.scalar(
-        select(DebugSession).where(DebugSession.user_id == user.id, DebugSession.ended_at.is_(None))
+        select(DebugSession).where(
+            owned_by(DebugSession.user_id, user), DebugSession.ended_at.is_(None)
+        )
     )
 
 
@@ -126,12 +129,8 @@ def from_header(db: Session, user: User, value: str | None) -> DebugSession | No
     """The session a request names, if it is the caller's own and still live; else None."""
     if not value or len(value) != _ID_LEN or not all(c in "0123456789abcdef" for c in value):
         return None
-    session = db.get(DebugSession, value)
-    if (
-        session is None
-        or session.user_id != user.id
-        or not is_live(session, datetime.now(timezone.utc))
-    ):
+    session = owned_row(db, DebugSession, value, user)
+    if session is None or not is_live(session, datetime.now(timezone.utc)):
         return None
     return session
 
@@ -354,7 +353,7 @@ def stored_screenshot_bytes(db: Session, user_id: int) -> int:
         db.scalar(
             select(func.coalesce(func.sum(DebugScreenshot.size), 0))
             .join(DebugSession, DebugSession.id == DebugScreenshot.session_id)
-            .where(DebugSession.user_id == user_id)
+            .where(owned_by(DebugSession.user_id, user_id))
         )
         or 0
     )

backend/app/discover/pins.py

@@ -72,11 +72,11 @@ def resolve_ref(db: Session, user: User, kind: str, ref: str) -> tuple[str, obje
     # such pin target", which is the same answer this function gives for one that does not exist.
     except ValueError:
         return None
-    pl = db.get(Playlist, pid)
     # A playlist is per-user, unlike the other four (which are shared catalog rows whose PRIVACY
     # lives in the state tables). Someone else's list must read as "no such thing", not as a 403 —
     # the same reason `owned_or_404` 404s rather than 403s.
-    return (col, pl.id) if pl is not None and pl.user_id == user.id else None
+    pl = owned_row(db, Playlist, pid, user)
+    return (col, pl.id) if pl is not None else None
 
 
 def reorder(db: Session, user: User, ids: list[int]) -> None:

backend/app/discover/queries.py

@@ -93,7 +93,7 @@ def yt_in_progress(db: Session, user: User, limit: int = RAIL_LIMIT) -> list[tup
     q = (
         select(*feed_columns(user, st), st.progress_updated_at.label("progressed_at"))
         .join(Channel, Channel.id == Video.channel_id)
-        .join(st, and_(st.video_id == Video.id, st.user_id == user.id))
+        .join(st, and_(st.video_id == Video.id, owned_by(st.user_id, user)))
         .where(
             st.position_seconds > 0,
             st.status.notin_(("watched", "hidden")),
@@ -136,7 +136,7 @@ def yt_video_row(db: Session, user: User, video_id: str) -> dict | None:
     row = db.execute(
         select(*feed_columns(user, st))
         .join(Channel, Channel.id == Video.channel_id)
-        .outerjoin(st, and_(st.video_id == Video.id, st.user_id == user.id))
+        .outerjoin(st, and_(st.video_id == Video.id, owned_by(st.user_id, user)))
         .where(Video.id == video_id)
     ).first()
     return serialize(row) if row is not None else None
@@ -179,7 +179,7 @@ def playlists_summary(
         select(*feed_columns(user, st), PlaylistItem.playlist_id.label("_playlist"))
         .join(PlaylistItem, PlaylistItem.video_id == Video.id)
         .join(Channel, Channel.id == Video.channel_id)
-        .outerjoin(st, and_(st.video_id == Video.id, st.user_id == user.id))
+        .outerjoin(st, and_(st.video_id == Video.id, owned_by(st.user_id, user)))
         .where(PlaylistItem.playlist_id.in_(playlist_ids))
         .order_by(PlaylistItem.playlist_id, PlaylistItem.position.asc())
     ).all()

backend/app/downloads/folders.py

@@ -328,9 +328,14 @@ def create_own(db: Session, user_id: int, name: str) -> FileFolder:
     return folder
 
 
+def renamable(folder: FileFolder) -> bool:
+    """Only a folder of the user's own making takes a name: a source folder's is its origin's."""
+    return folder.kind == FolderKind.OWN
+
+
 def rename(db: Session, folder: FileFolder, name: str) -> None:
     """Rename one of the user's own folders (a source folder's name is its origin's)."""
-    if folder.kind != FolderKind.OWN:
+    if not renamable(folder):
         raise FolderError("file_folder_not_own")
     folder.name = name
     try:

backend/app/downloads/queries.py

@@ -296,13 +296,11 @@ def own_link(db: Session, user: User, link_id: int) -> DownloadLink | None:
     if link is None:
         return None
     target = (
-        db.get(DownloadJob, link.job_id)
+        owned_row(db, DownloadJob, link.job_id, user)
         if link.job_id is not None
-        else db.get(FileFolder, link.folder_id)
+        else owned_row(db, FileFolder, link.folder_id, user)
     )
-    if target is None or target.user_id != user.id:
-        return None
-    return link
+    return link if target is not None else None
 
 
 def links_to(

backend/app/downloads/runner.py

@@ -16,6 +16,7 @@ import shutil
 import subprocess
 import sys
 
+import app.tables  # noqa: F401 — a fresh interpreter: every table, before the first query
 from app import logs
 from app import logsink
 from app.config import settings

backend/app/feedquery.py

@@ -212,7 +212,7 @@ def filtered_query(
     # exactly. 'unwatched'/'all' include row-less 'new' videos, so they keep the outer join.
     state_required = show in ("watched", "hidden", "in_progress")
     join_state = query.join if state_required else query.outerjoin
-    query = join_state(state, and_(state.video_id == Video.id, state.user_id == user.id))
+    query = join_state(state, and_(state.video_id == Video.id, owned_by(state.user_id, user)))
 
     # Hide videos the maintenance job has flagged as currently unplayable (deleted/private/
     # abandoned). They're either deleted after a grace period or unhidden if they recover;

backend/app/main.py

@@ -28,6 +28,7 @@ log = logs.get_logger(__name__)
 from app import bodylimit, collation, logsink, state, sysconfig  # noqa: E402 — logging is configured first
 from app.config import settings  # noqa: E402 — logging is configured first
 from app.db import SessionLocal, engine  # noqa: E402 — logging is configured first
+import app.tables  # noqa: E402 — every table, before the first query
 from app.downloads import service as download_service  # noqa: E402 — logging is configured first
 from app.downloads import storage  # noqa: E402 — logging is configured first
 from app.plex import stream as plex_stream  # noqa: E402 — logging is configured first

backend/app/notifications.py

@@ -9,6 +9,7 @@ table can't grow without bound for a heavy user.
 from sqlalchemy import delete, select
 from sqlalchemy.orm import Session
 
+from app.userscope import owned_by
 from app.models import Notification
 
 # Keep at most this many READ notifications per user; older read ones are pruned. Unread
@@ -48,11 +49,13 @@ def create_notification(
 
 def trim_read(db: Session, user_id: int, cap: int = READ_SOFT_CAP) -> int:
     """Delete a user's oldest READ notifications beyond `cap`. Returns the number removed.
-    Idempotent and cheap; safe to call after marking things read."""
+    Idempotent and cheap; safe to call after marking things read. Flushes first, so a notice the
+    caller has just marked read counts; the caller commits."""
+    db.flush()
     ids = (
         db.execute(
             select(Notification.id)
-            .where(Notification.user_id == user_id, Notification.read.is_(True))
+            .where(owned_by(Notification.user_id, user_id), Notification.read.is_(True))
             .order_by(Notification.created_at.desc())
             .offset(cap)
         )
@@ -63,5 +66,4 @@ def trim_read(db: Session, user_id: int, cap: int = READ_SOFT_CAP) -> int:
         return 0
     # One bulk DELETE rather than a get+delete per row (the ids are already in hand).
     db.execute(delete(Notification).where(Notification.id.in_(ids)))
-    db.commit()
     return len(ids)

backend/app/plex/queries.py

@@ -108,20 +108,6 @@ def state(db: Session, user: User | int, item_id: int) -> PlexState | None:
     )
 
 
-def states(db: Session, user: User | int, item_ids: list[int]) -> dict[int, PlexState]:
-    """The user's state on each of these items that has one, by item id."""
-    if not item_ids:
-        return {}
-    return {
-        s.item_id: s
-        for s in db.execute(
-            select(PlexState).where(
-                owned_by(PlexState.user_id, user), PlexState.item_id.in_(item_ids)
-            )
-        ).scalars()
-    }
-
-
 # --- a show ----------------------------------------------------------------------------------
 
 

backend/app/plex/rollup.py

@@ -8,6 +8,7 @@ from datetime import datetime, timezone
 from sqlalchemy import and_, case, func, or_, select
 from sqlalchemy.orm import Session, aliased
 
+from app.models import User
 from app.userscope import owned_by
 from app.plex.models import PlexItem, PlexState
 from app.plex.cards import ShowState
@@ -106,7 +107,7 @@ def state_map(db: Session, user_id: int, show_ids: list[int]) -> dict[int, ShowS
     return {r.show_id: show_state(r.total, r.watched, r.inprog) for r in rows}
 
 
-def item_state_map(db: Session, user_id: int, item_ids: list[int]) -> dict[int, PlexState]:
+def item_state_map(db: Session, user_id: User | int, item_ids: list[int]) -> dict[int, PlexState]:
     """A user's PlexState rows for a set of leaf items (movies or episodes), keyed by item_id — the
     leaf analogue of `state_map` (which rolls a show's episodes up to a `ShowState`). One batched
     fetch, so the caller serializes cards without a per-card query. Empty in → empty dict (no `IN ()`)."""

backend/app/plex/service.py

@@ -19,7 +19,7 @@ from app.plex import people as plex_people
 from app.plex import tmdb as plex_tmdb
 from app.plex.lookups import by_rating_key
 from app.models import User
-from app.plex import queries
+from app.plex import queries, rollup
 from app.plex.models import (
     PlexCollection,
     PlexItem,
@@ -302,6 +302,36 @@ def mark_finished(db: Session, user_id: int, item_id: int, now: datetime) -> boo
     return False
 
 
+def state_row(
+    db: Session,
+    user: User | int,
+    item_id: int,
+    st: PlexState | None = None,
+    *,
+    synced: bool = False,
+) -> PlexState:
+    """The user's state row on this item, made if the read before found none. Made by the insert
+    itself (ON CONFLICT DO NOTHING) and then read: the first checkpoint of an item and the `final`
+    flush beside it routinely both read "none", and a plain add let the second one fail on
+    `uq_plex_user_item` — a 500, and the push it was carrying lost. Every first row goes through
+    here: a checkpoint, a status, a season marked at once, a pull from Plex. `synced` is what a row
+    made now says about Plex; a row another writer made first keeps its own."""
+    if st is not None:
+        return st
+    db.execute(
+        pg_insert(PlexState)
+        .values(
+            user_id=user if isinstance(user, int) else user.id,
+            item_id=item_id,
+            synced_to_plex=synced,
+        )
+        .on_conflict_do_nothing(constraint="uq_plex_user_item")
+    )
+    made = queries.state(db, user, item_id)
+    assert made is not None  # inserted now, or committed by the request that won
+    return made
+
+
 def clear_progress(db: Session, st: PlexState | None, now: datetime) -> None:
     """A checkpoint too early to keep: a state that held nothing else goes, any other forgets its
     position."""
@@ -325,9 +355,7 @@ def checkpoint(
 ) -> PlexState:
     """Record a resume position. `dirty` marks it not yet mirrored to Plex — set before a push, so
     the reconcile re-pushes it if the push fails and the push can settle it once Plex confirms."""
-    if st is None:
-        st = PlexState(user_id=user.id, item_id=item_id)
-        db.add(st)
+    st = state_row(db, user, item_id, st)
     st.position_seconds = position
     st.progress_updated_at = now
     if dirty:
@@ -345,9 +373,7 @@ def set_status(
     db: Session, user: User, item_id: int, st: PlexState | None, status: str
 ) -> PlexState:
     """Set a watched or hidden status; watched also clears the resume point."""
-    if st is None:
-        st = PlexState(user_id=user.id, item_id=item_id)
-        db.add(st)
+    st = state_row(db, user, item_id, st)
     st.status = status
     if status == "watched":
         st.watched_at = datetime.now(timezone.utc)
@@ -364,15 +390,14 @@ def bulk_state(
     (item id, rating key, action) pushes a linked Plex account needs. Unwatching keeps the user's
     private "hidden" marks."""
     now = datetime.now(timezone.utc)
-    existing = queries.states(db, user_id, [e.id for e in eps])
+    existing = rollup.item_state_map(db, user_id, [e.id for e in eps])
     to_push: list[tuple[int, str, str]] = []
     for e in eps:
         st = existing.get(e.id)
         prev = st.status if st is not None else "new"
         if watched:
-            if st is None:
-                st = PlexState(user_id=user_id, item_id=e.id)
-                db.add(st)
+            st = state_row(db, user_id, e.id, st)
+            prev = st.status  # a first checkpoint beside this may have made it meanwhile
             st.status = "watched"
             st.watched_at = now
             st.position_seconds = 0

backend/app/plex/watch_sync.py

@@ -32,6 +32,8 @@ from app.db import SessionLocal
 from app.userscope import owned_by
 from app.plex.models import PlexItem, PlexLibrary, PlexLink, PlexState
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
+from app.plex import queries
+from app.plex.service import state_row
 from app.plex.sync import (
     _TYPE_EPISODE,
     _TYPE_MOVIE,
@@ -252,15 +254,7 @@ def push_state_to_plex(
         # Flag the row synced — but an "unwatched" via status=new deletes the row, so there may be
         # nothing to flag; that's fine (unscrobble still happened). Skip the flag if the row was
         # re-edited since we captured `expect_ts` (leave it dirty for its own push / the reconcile).
-        st = (
-            db.execute(
-                select(PlexState).where(
-                    owned_by(PlexState.user_id, user_id), PlexState.item_id == item_id
-                )
-            )
-            .scalars()
-            .first()
-        )
+        st = queries.state(db, user_id, item_id)
         if st is not None and _row_matches(st, expect_ts):
             st.synced_to_plex = True
             db.commit()
@@ -394,15 +388,7 @@ def _pull_apply(
     """Bring one Plex-side positive signal into Siftlode under last-write-wins. Returns
     "watched"/"in_progress" if it changed the row, else None. Never clears a row (un-watch is the
     full reconcile's job) — this only pulls in watched/resume."""
-    st = (
-        db.execute(
-            select(PlexState).where(
-                owned_by(PlexState.user_id, user_id), PlexState.item_id == item_id
-            )
-        )
-        .scalars()
-        .first()
-    )
+    st = queries.state(db, user_id, item_id)
     if _same_state(st, status, pos):
         if st is not None and not st.synced_to_plex:
             st.synced_to_plex = True  # already matches Plex → just settle the flag, no churn
@@ -423,8 +409,9 @@ def _pull_apply(
         # "almost always already pushed" assumption above excludes.
         return None
     if st is None:
-        st = PlexState(user_id=user_id, item_id=item_id)
-        db.add(st)
+        st = state_row(db, user_id, item_id, synced=True)
+        if not st.synced_to_plex:  # a local change made it first, beside this pull: the guard above
+            return None
     if status == "watched":
         st.status, st.position_seconds, st.watched_at, st.progress_updated_at = (
             "watched",

backend/app/quota.py

@@ -16,6 +16,7 @@ from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.engine import CursorResult
 from sqlalchemy.orm import Session
 
+from app.userscope import owned_by
 from app import logs, sysconfig
 from app.db import SessionLocal
 from app.models import ApiQuotaUsage, QuotaEvent
@@ -173,7 +174,7 @@ def actions_today(db: Session, user_id: int, action: str) -> int:
             select(func.count())
             .select_from(QuotaEvent)
             .where(
-                QuotaEvent.user_id == user_id,
+                owned_by(QuotaEvent.user_id, user_id),
                 QuotaEvent.action == action,
                 QuotaEvent.created_at >= pacific_day_start_utc(),
             )

backend/app/reader/models.py

@@ -11,12 +11,14 @@ from sqlalchemy import (
     DateTime,
     Float,
     ForeignKey,
+    Index,
     Integer,
     JSON,
     String,
     Text,
     UniqueConstraint,
     func,
+    text,
 )
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
@@ -93,6 +95,15 @@ class Playlist(Base, TimestampMixin, UpdatedAtMixin):
     sync phases; the foundation phase only uses local playlists.)"""
 
     __tablename__ = "playlists"
+    __table_args__ = (
+        # One Watch later per user, held by the database: two first saves at once each made one.
+        Index(
+            "uq_playlist_watch_later",
+            "user_id",
+            unique=True,
+            postgresql_where=text("kind = 'watch_later'"),
+        ),
+    )
 
     id: Mapped[int] = mapped_column(primary_key=True)
     user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), index=True)

backend/app/reader/service.py

@@ -9,7 +9,7 @@ unique key, a row lock taken before a presence check. The comfort shelf's writes
 
 from datetime import datetime, timezone
 
-from sqlalchemy import exists, func, select, update
+from sqlalchemy import exists, func, select, text, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
 
@@ -239,24 +239,33 @@ def clear_state(db: Session, user: User, video_id: str) -> None:
 
 def set_progress(db: Session, user: User, video_id: str, position: int) -> None:
     """The player's resume point. 0 clears it: a row holding nothing else goes, one with a status
-    (watched, hidden) keeps it with the position zeroed. The status itself is never changed here."""
-    row = queries.video_state(db, user, video_id)
+    (watched, hidden) keeps it with the position zeroed. The status itself is never changed here.
+    A position is one upsert on (user, video): the first checkpoint and the end-of-playback mark
+    beside it both read "no row", and a plain add let the second one fail on `uq_user_video`."""
     now = datetime.now(timezone.utc)
-    if not position:
-        if row is None:
-            return
-        if row.status == "new":
-            db.delete(row)
-        else:
-            row.position_seconds = 0
-            row.progress_updated_at = now
-        db.flush()
+    if position:
+        db.execute(
+            pg_insert(VideoState)
+            .values(
+                user_id=user.id,
+                video_id=video_id,
+                position_seconds=position,
+                progress_updated_at=now,
+            )
+            .on_conflict_do_update(
+                constraint="uq_user_video",
+                set_={"position_seconds": position, "progress_updated_at": now, "updated_at": now},
+            )
+        )
         return
+    row = queries.video_state(db, user, video_id)
     if row is None:
-        row = VideoState(user_id=user.id, video_id=video_id)
-        db.add(row)
-    row.position_seconds = position
-    row.progress_updated_at = now
+        return
+    if row.status == "new":
+        db.delete(row)
+    else:
+        row.position_seconds = 0
+        row.progress_updated_at = now
     db.flush()
 
 
@@ -319,17 +328,25 @@ def create_playlist(db: Session, user: User, name: str) -> Playlist:
 
 
 def watch_later(db: Session, user: User) -> Playlist:
-    """The user's built-in Watch later playlist, created on first use."""
+    """The user's built-in Watch later playlist, created on first use. Created by the insert itself
+    (ON CONFLICT DO NOTHING on the one-per-user index) and then read: the first two saves at once
+    both read "none", and each used to make a list of its own."""
     pl = queries.watch_later(db, user)
     if pl is None:
-        pl = Playlist(
-            user_id=user.id,
-            name="Watch later",
-            kind="watch_later",
-            position=_next_playlist_position(db, user.id),
+        db.execute(
+            pg_insert(Playlist)
+            .values(
+                user_id=user.id,
+                name="Watch later",
+                kind="watch_later",
+                position=_next_playlist_position(db, user.id),
+            )
+            .on_conflict_do_nothing(
+                index_elements=["user_id"], index_where=text("kind = 'watch_later'")
+            )
         )
-        db.add(pl)
-        db.flush()  # the id, for the item the caller adds next
+        pl = queries.watch_later(db, user)
+        assert pl is not None  # inserted now, or committed by the request that won
     return pl
 
 

backend/app/routes/_common.py

@@ -89,8 +89,9 @@ def owned_or_404(
 ) -> M:
     """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."""
+    A core route calls it directly. A unit's route cannot (it may not name a unit's model as a value):
+    it asks its unit's `queries.own_x`, which goes through the same `owned_row`, and answers
+    `not_found` itself."""
     obj = owned_row(db, model, id_, user, owner_attr=owner_attr, lock=lock)
     if obj is None:
         raise not_found(what)

backend/app/routes/auth.py

@@ -5,9 +5,10 @@ helpers) stays in app/auth.py, imported below."""
 
 import secrets
 from datetime import datetime, timedelta, timezone
-from typing import NamedTuple
+from typing import Literal, NamedTuple
 from urllib.parse import urlencode
 
+from authlib.common.security import generate_token
 from authlib.integrations.starlette_client import OAuth, OAuthError
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
 from fastapi.responses import JSONResponse, RedirectResponse
@@ -16,6 +17,7 @@ from sqlalchemy import select, update
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
+from app.userscope import owned_by
 from app import apitokens
 from app import email as email_mod
 from app import logs
@@ -24,10 +26,11 @@ from app import sysconfig
 from app.auth import (
     _YOUTUBE_SCOPES,
     BASE_SCOPES,
-    MAX_SESSION_ACCOUNTS,
+    EXPECTED_ACCOUNT_HEADER,
     PASSWORD_MIN_LEN,
     READ_SCOPES,
     WRITE_SCOPES,
+    built_for_another_account,
     current_user,
     env_admin_canonicals,
     env_allowed_canonicals,
@@ -36,7 +39,9 @@ from app.auth import (
     is_allowed,
     log,
     operator_contact,
-    resolved_user_id,
+    optional_current_user,
+    session_user_id,
+    stamp_session,
 )
 from app.config import settings
 from app.db import SessionLocal, get_db
@@ -319,6 +324,25 @@ class SetPasswordIn(BaseModel):
     current_password: str | None = None
 
 
+# A connect in flight, in the session: `{state, uid, explicit}`. It names the OAuth state of the flow
+# that set it, because the session is the browser's, not the flow's: a callback coming back with
+# another state (an older flow, which authlib then refuses) must not spend the marker of the connect
+# still open, or that connect would return as a plain sign-in — signing someone else in, or storing
+# a YouTube grant on whichever account the Google identity already belongs to.
+_LINK_MARKER = "oauth_link"
+
+# Where a navigation from a tab showing another account than the one signed in lands: the app, which
+# boots as the account signed in now and says why (the frontend's `ACCOUNT_CHANGED_FLAG`).
+ACCOUNT_CHANGED_LANDING = "/?account=changed"
+
+
+def _take_link_marker(request: Request) -> dict | None:
+    marker = request.session.get(_LINK_MARKER)
+    if not isinstance(marker, dict) or marker.get("state") != request.query_params.get("state"):
+        return None
+    return request.session.pop(_LINK_MARKER)
+
+
 @router.get("/login")
 async def login(request: Request, db: Session = Depends(get_db)):
     # access_type=offline ensures a refresh_token on first authorization. We avoid
@@ -329,6 +353,10 @@ async def login(request: Request, db: Session = Depends(get_db)):
         # Google sign-in isn't configured on this instance — land back on the login page (the UI
         # hides the button, so this is just a safety net for a stale/direct hit).
         return RedirectResponse(url="/")
+    # A sign-in, never a link. Starting it retires every earlier flow's state (authlib keeps only the
+    # newest), so a connect's marker left from before — abandoned at Google, or still open in
+    # another tab — names a flow that can no longer finish.
+    request.session.pop(_LINK_MARKER, None)
     return await client.authorize_redirect(
         request,
         _oauth_redirect_uri(request),
@@ -349,24 +377,23 @@ async def callback(
     if client is None:
         return RedirectResponse(url="/")
     # Linking mode: an already-authenticated account is attaching this Google identity (a
-    # password account enabling YouTube or connecting SSO). The markers are set by /auth/link and
-    # /auth/upgrade; when present we attach to the current user instead of identifying by sub.
-    # Pop them BEFORE the token exchange: if the user aborts Google's consent screen the exchange
-    # throws below, and a marker left behind would silently turn the NEXT clean sign-in into a link
-    # attempt. Popping up front means an aborted link flow leaves no residue in the session.
-    link_uid = request.session.pop("oauth_link_uid", None)
-    link_explicit = request.session.pop("oauth_link_explicit", False)
+    # password account enabling YouTube or connecting SSO). The marker is set by
+    # /auth/google/connect; when it is this flow's we attach to the current user instead of
+    # identifying by sub. Taken BEFORE the token exchange: if the user aborts Google's consent screen
+    # the exchange throws below, and a marker left behind would silently turn the NEXT clean sign-in
+    # into a link attempt. A connect that never comes back here at all is cleared by /auth/login.
+    link = _take_link_marker(request)
     try:
         token = await client.authorize_access_token(request)
     except OAuthError as exc:
         # The user cancelled or denied consent at Google — land back with a friendly notice instead
-        # of a raw 400 JSON error page. An already-signed-in user (adding another account via
-        # /auth/login, or linking/upgrading via /auth/link|upgrade) never sees the pre-auth login
-        # banner, so surface a neutral toast via ?oauth=cancelled; a fresh sign-in cancel lands on
-        # the login page with the oauth_cancelled banner instead. Keyed on the live session, not on
-        # link_uid, so the add-account path (no marker) is covered too.
+        # of a raw 400 JSON error page. An already-signed-in user (signing in again via /auth/login,
+        # or connecting via /auth/google/connect) never sees the pre-auth login banner, so
+        # surface a neutral toast via ?oauth=cancelled; a fresh sign-in cancel lands on the login page
+        # with the oauth_cancelled banner instead. Keyed on the live session, not on link_uid, so a
+        # sign-in started while signed in (no marker) is covered too.
         log.info("Google OAuth cancelled/failed: %s", exc.error)
-        if request.session.get("user_id") is not None:
+        if session_user_id(request) is not None:
             return RedirectResponse(url="/?oauth=cancelled")
         return RedirectResponse(url="/?login=oauth_cancelled")
 
@@ -377,8 +404,8 @@ async def callback(
     sub = userinfo["sub"]
     email = (userinfo.get("email") or "").lower()
 
-    if link_uid is not None:
-        return _complete_link(request, db, link_uid, link_explicit, sub, userinfo, token)
+    if link is not None:
+        return _complete_link(request, db, link["uid"], link["explicit"], sub, userinfo, token)
 
     if not is_allowed(db, email):
         # No uid to name — having no account here is the branch. And the address is left out on
@@ -579,19 +606,16 @@ def _complete_link(
     token: dict,
 ):
     """Attach the just-authorized Google identity to the already-signed-in account that started
-    the link/upgrade. No is_allowed gate — they're already an active user. Refuses to hijack a
+    the connect. No is_allowed gate — they're already an active user. Refuses to hijack a
     Google identity owned by another account, or to silently swap a different linked identity.
-    `explicit` (the popped oauth_link_explicit marker) distinguishes a "Connect Google" click from
-    a YouTube upgrade — the caller pops it up front so an aborted flow leaves nothing behind."""
-    # SEC-11: the marker must name an account signed into THIS browser — the session default OR any
-    # account in the wallet — not only the default. A tab acting as a secondary account links Google to
-    # ITSELF (the marker was set from current_user, which resolves the ?account= it navigated with), so
-    # accepting wallet membership stops the identity/token landing on the default account A instead of B.
-    accounts = request.session.get("account_ids") or []
-    if link_uid != request.session.get("user_id") and link_uid not in accounts:
-        return RedirectResponse(url="/?link=error")
-    user = db.get(User, link_uid)
-    if user is None:
+    `explicit` (from the link marker) distinguishes a "Connect Google" click from a YouTube grant —
+    the caller takes the marker up front so an aborted flow leaves nothing behind."""
+    # The marker must name the account still signed into THIS browser, and that session must still
+    # hold: a sign-in as someone else between the start and the callback replaced it (the identity
+    # must not land on the newcomer), and a session revoked meanwhile ("log out everywhere", a
+    # password change, a suspension) must not finish what it started.
+    user = optional_current_user(request, db)
+    if user is None or user.id != link_uid:
         return RedirectResponse(url="/?link=error")
     other = db.execute(
         select(User).where(User.google_sub == sub, User.id != user.id)
@@ -611,45 +635,31 @@ def _complete_link(
     _store_token(db, user, token)
     db.commit()
     log.info("Google linked: uid=%s scopes=%s", user.id, token.get("scope"))
-    # An explicit "Connect Google" lands on Settings with a confirmation; a YouTube upgrade
+    # An explicit "Connect Google" lands on Settings with a confirmation; a YouTube grant
     # (wizard / Settings access rows) returns to the app so the onboarding flow resumes as before.
     return RedirectResponse(url="/?link=ok" if explicit else "/")
 
 
 @router.post("/logout")
 async def logout(request: Request):
-    """Sign the requesting tab's active account out of this browser (removing it from the wallet).
-    Per-tab aware: the account is taken from the X-Siftlode-Account header when present, so logging
-    out in one tab doesn't disturb another tab running a different account. If the account being
-    removed was the session default, promote the most recent remaining account (or clear the
-    session when none remain)."""
-    # A tab still pinned to an account already signed out in another tab resolves to nobody, so it
-    # signs nobody out — it used to fall back to the default and sign THAT account out in its place.
-    active, is_default = resolved_user_id(request)
-    remaining = [a for a in (request.session.get("account_ids") or []) if a != active]
-    request.session["account_ids"] = remaining
-    if is_default:
-        if remaining:
-            request.session["user_id"] = remaining[-1]
-            return JSONResponse({"ok": True, "switched": True})
-        request.session.clear()
-        return JSONResponse({"ok": True, "switched": False})
-    # A non-default (per-tab) account signed out: it's gone from the wallet and the session default
-    # is untouched. The tab drops its own override and falls back to the default on reload.
-    return JSONResponse({"ok": True, "switched": False})
+    """Sign this browser out: the session holds one account, and it ends — unless the tab asking was
+    built for another account than the one signed in now (a sign-in as someone else in another tab):
+    its Sign out would end THAT person's session (see `EXPECTED_ACCOUNT_HEADER`)."""
+    signed_in = session_user_id(request)
+    if signed_in is not None and built_for_another_account(
+        signed_in, request.headers.get(EXPECTED_ACCOUNT_HEADER)
+    ):
+        raise refused(401, "account_changed")
+    request.session.clear()
+    return JSONResponse({"ok": True})
 
 
 def _establish_session(request: Request, user: User) -> None:
     """Sign `user` in for this browser session — the ONE sign-in path, shared by the Google callback
-    and password login, so both join the same account switcher and both stamp `last_login_at` (the
-    caller commits). Multi-session: every account that authenticated in this browser is remembered so
-    the user can switch between them; only accounts that actually proved themselves HERE land in that
-    wallet (it is the proof they may be switched to)."""
-    accounts = [a for a in (request.session.get("account_ids") or []) if a != user.id]
-    accounts.append(user.id)
-    request.session["account_ids"] = accounts[-MAX_SESSION_ACCOUNTS:]
+    and password login, so both stamp `last_login_at` (the caller commits). One account per session:
+    the sign-in replaces whoever was signed in here before."""
     request.session["user_id"] = user.id
-    _remember_epoch(request, user)
+    stamp_session(request, user)
     user.last_login_at = datetime.now(timezone.utc)
 
 
@@ -1124,7 +1134,7 @@ def password_reset_confirm(body: TokenPasswordIn, db: Session = Depends(get_db))
     # Burn any other outstanding reset tokens for this user.
     for row in db.execute(
         select(AuthToken).where(
-            AuthToken.user_id == user.id,
+            owned_by(AuthToken.user_id, user),
             AuthToken.kind.in_(_PASSWORD_TOKEN_KINDS),
             AuthToken.used_at.is_(None),
         )
@@ -1134,15 +1144,6 @@ def password_reset_confirm(body: TokenPasswordIn, db: Session = Depends(get_db))
     return {"ok": True}
 
 
-def _remember_epoch(request: Request, user: User) -> None:
-    """Record this account's current `session_epoch` in the signed cookie (SA4), so `current_user`
-    can later reject the cookie if the account's epoch was bumped (password reset/change, or
-    "log out everywhere"). Per-account so one account's revocation doesn't evict the others."""
-    epochs = dict(request.session.get("epochs") or {})
-    epochs[str(user.id)] = user.session_epoch
-    request.session["epochs"] = epochs
-
-
 def bump_session_epoch(db: Session, user: User) -> None:
     """Invalidate every EXISTING signed cookie for this account by advancing its epoch (SA4). Cookies
     minted before the bump carry a now-stale epoch and are rejected by `current_user`. The account's
@@ -1219,35 +1220,11 @@ def logout_others(
     # session at a newer epoch than the DB (see set_password).
     bump_session_epoch(db, user)
     db.commit()
-    _remember_epoch(request, user)
+    stamp_session(request, user)
     log.info("Logout-others: uid=%s (epoch=%s)", user.id, user.session_epoch)
     return {"ok": True}
 
 
-@router.get("/link")
-async def link_google(
-    request: Request,
-    user: User = Depends(current_user),
-    db: Session = Depends(get_db),
-):
-    """Start linking a Google account to the signed-in (e.g. password) account. Requests only
-    the identity scopes — YouTube access is granted separately via /auth/upgrade. The callback
-    sees `oauth_link_uid` and attaches the identity instead of creating a new account."""
-    client = google_oauth(db)
-    if client is None:
-        return RedirectResponse(url="/?link=error")
-    request.session["oauth_link_uid"] = user.id
-    request.session["oauth_link_explicit"] = True
-    return await client.authorize_redirect(
-        request,
-        _oauth_redirect_uri(request),
-        access_type="offline",
-        prompt="select_account",
-        include_granted_scopes="true",
-        scope=BASE_SCOPES,
-    )
-
-
 @router.post("/set-password")
 def set_password(
     body: SetPasswordIn,
@@ -1271,35 +1248,57 @@ def set_password(
     # can't leave the cookie at a newer epoch than the DB (which would wrongly 401 THIS session).
     bump_session_epoch(db, user)
     db.commit()
-    _remember_epoch(request, user)
+    stamp_session(request, user)
     log.info("Password set/changed: uid=%s", user.id)
     return {"ok": True}
 
 
-@router.get("/upgrade")
-async def upgrade(
+# What each Google connect asks Google for. `identity` attaches a Google sign-in to the account
+# (Settings → Connect Google) and lets the person pick which Google account; `read` and `write` grant
+# YouTube access (the onboarding wizard, the Settings access rows) and always show the consent screen,
+# so a scope granted earlier and since revoked at Google is asked for again.
+_CONNECT: dict[str, tuple[str, str]] = {
+    "identity": (BASE_SCOPES, "select_account"),
+    "read": (READ_SCOPES, "consent"),
+    "write": (WRITE_SCOPES, "consent"),
+}
+
+
+@router.get("/google/connect")
+async def google_connect(
     request: Request,
-    access: str = "read",
+    access: Literal["identity", "read", "write"],
+    expect: str | None = None,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ):
-    """Incremental consent for the onboarding wizard. `access=read` grants YouTube
-    read-only (enough to build the feed); `access=write` additionally grants management
-    (unsubscribe). The shared callback stores whatever Google returns, so `can_read` /
-    `can_write` flip on once granted. Anything other than an explicit `write` defaults to
-    the least-privileged read scope."""
+    """Attach Google to the signed-in account: its identity, or YouTube read/write access on top.
+    The shared callback sees the link marker and attaches what Google returns to THIS account —
+    without it a password account (no google_sub) would get a brand-new, separate Google user
+    created instead. It stores whatever scopes Google grants, so `can_read` / `can_write` flip on
+    once granted.
+
+    `expect` is the account the tab was built for. A navigation carries no headers, so the check
+    every request gets (`EXPECTED_ACCOUNT_HEADER`) rides the query here: a tab still showing the
+    account signed in before would otherwise attach a Google identity to the one signed in now."""
+    if built_for_another_account(user.id, expect):
+        return RedirectResponse(url=ACCOUNT_CHANGED_LANDING)
     client = google_oauth(db)
     if client is None:
-        return RedirectResponse(url="/")
-    # Attach the grant to THIS account in the callback. Without it a password account (no
-    # google_sub) would get a brand-new, separate Google user created instead of being linked.
-    request.session["oauth_link_uid"] = user.id
-    scope = WRITE_SCOPES if access == "write" else READ_SCOPES
+        return RedirectResponse(url="/?link=error")
+    scope, prompt = _CONNECT[access]
+    state = generate_token(48)
+    request.session[_LINK_MARKER] = {
+        "state": state,
+        "uid": user.id,
+        "explicit": access == "identity",
+    }
     return await client.authorize_redirect(
         request,
         _oauth_redirect_uri(request),
+        state=state,
         access_type="offline",
-        prompt="consent",
+        prompt=prompt,
         include_granted_scopes="true",
         scope=scope,
     )

backend/app/routes/debug_sessions.py

@@ -18,6 +18,7 @@ from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
+from app.userscope import owned_by
 from app import audit, debugsession, logs, logsink
 from app.audit import AuditAction
 from app.auth import current_user
@@ -95,7 +96,7 @@ def stop_session(
 def list_sessions(user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
     sessions = db.scalars(
         select(DebugSession)
-        .where(DebugSession.user_id == user.id)
+        .where(owned_by(DebugSession.user_id, user))
         .order_by(DebugSession.started_at.desc())
         .limit(LIST_MAX)
     ).all()
@@ -219,6 +220,7 @@ def send_issue(sid: str, user: User = Depends(current_user), db: Session = Depen
         raise refused(409, "issue_sending")
     new = session.issue_url is None
     if not new and not debugsession.unfinished(session):
+        db.commit()  # nothing to send: the lock ends here, not when the request's session closes
         return {"ok": True, "session": _view(db, session)}
     key = str(user.id)
     if new:

backend/app/routes/files.py

@@ -375,6 +375,9 @@ def update_folder(
     folder = own_folder(db, user, folder_id)
     sent = body.model_fields_set
     if "name" in sent:
+        # Which folder may be renamed is answered before what the name is, as it always was.
+        if not folders.renamable(folder):
+            raise refused(409, "file_folder_not_own")
         try:
             folders.rename(db, folder, _folder_name(body.name or ""))
         except folders.FolderError as e:

backend/app/routes/me.py

@@ -9,11 +9,9 @@ from app.auth import (
     count_admins,
     count_pending_activations,
     current_user,
-    drop_from_wallet,
     google_enabled,
     has_read_scope,
     has_write_scope,
-    is_allowed,
     optional_current_user,
     purge_user,
 )
@@ -26,79 +24,10 @@ from app.db import get_db
 from app.models import Invite, User
 from app.utils import iso
 from app.refusal import refused
-from app.routes._common import not_found
 
 router = APIRouter(prefix="/api/me", tags=["me"])
 
 
-@router.get("/accounts")
-def my_accounts(
-    request: Request,
-    user: User = Depends(current_user),
-    db: Session = Depends(get_db),
-) -> list[dict]:
-    """The accounts that have authenticated in this browser session (switchable without a
-    new Google sign-in). The active one is flagged."""
-    ids = request.session.get("account_ids") or [user.id]
-    rows = {u.id: u for u in db.execute(select(User).where(User.id.in_(ids))).scalars()}
-    out = []
-    for uid in ids:  # preserve recency order from the session
-        u = rows.get(uid)
-        if u is not None:
-            out.append(
-                {
-                    "id": u.id,
-                    "email": u.email,
-                    "display_name": u.display_name,
-                    "avatar_url": u.avatar_url,
-                    "active": u.id == user.id,
-                }
-            )
-    return out
-
-
-class SwitchAccountIn(BaseModel):
-    user_id: int
-
-
-@router.post("/switch")
-def switch_account(
-    body: SwitchAccountIn,
-    request: Request,
-    user: User = Depends(current_user),
-    db: Session = Depends(get_db),
-) -> dict:
-    """Switch the active account to another one already authenticated in this browser. No
-    Google round-trip — but only accounts present in the session list (proof they signed in
-    here) are allowed, and access is re-checked in case the invite was revoked since."""
-    target = body.user_id
-    if target not in (request.session.get("account_ids") or []):
-        raise refused(403, "not_your_account")
-    # An account `_session_user` would refuse — gone, deactivated, suspended, or its session revoked — is
-    # refused here too, and dropped from the switch list the way `_session_user` drops it. Made the session
-    # default instead, the next request's current_user would refuse it as the DEFAULT and clear the whole
-    # wallet session, logging out every account here. (B-core-9)
-    u = db.get(User, target)
-    if u is None:
-        drop_from_wallet(request.session, target)
-        raise not_found("account")
-    if not is_allowed(db, u.email):
-        raise refused(403, "account_no_access")
-    if not u.is_active:
-        drop_from_wallet(request.session, target)
-        raise refused(403, "account_no_access")
-    if u.is_suspended:
-        drop_from_wallet(request.session, target)
-        raise refused(403, "account_suspended")
-    # Revoked: a password reset/change or "log out everywhere" bumped the account's epoch.
-    epochs = request.session.get("epochs") or {}
-    if int(epochs.get(str(target), 0)) != (u.session_epoch or 0):
-        drop_from_wallet(request.session, target)
-        raise refused(403, "account_signed_out")
-    request.session["user_id"] = target
-    return {"ok": True, "user_id": target}
-
-
 @router.get("")
 def get_me(
     user: User | None = Depends(optional_current_user), db: Session = Depends(get_db)
@@ -187,17 +116,11 @@ def delete_my_account(
     surfaces)."""
     if user.role == "admin" and count_admins(db) <= 1:
         raise refused(400, "only_admin_delete")
-    user_id = user.id
     # Full erasure (cascades) + access-request cleanup + Google-grant revocation; shared with the
-    # admin delete path. Capture the id first — `user` is detached once purge_user deletes the row.
+    # admin delete path.
     purge_user(db, user, background)
-    # Drop this account from the browser session; switch to another signed-in account if any.
-    remaining = [a for a in (request.session.get("account_ids") or []) if a != user_id]
-    if remaining:
-        request.session["account_ids"] = remaining
-        request.session["user_id"] = remaining[-1]
-    else:
-        request.session.clear()
+    # The session's one account is gone: so is the session.
+    request.session.clear()
     return {"deleted": True}
 
 
@@ -213,7 +136,13 @@ def update_preferences(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    # Merge so partial updates don't wipe other keys.
+    # Merge so partial updates don't wipe other keys — over the stored row read again under a row
+    # lock: a client saves keys one at a time (several at once on a boot that moves this browser's
+    # copies to the account), and two merges over the same earlier read would keep only the last.
+    # FOR NO KEY UPDATE, as bump_session_epoch: it still orders two merges, and a transaction that
+    # only added a row referring to the account (a playlist pull, then minutes of YouTube) does not
+    # hold the save up.
+    db.refresh(user, with_for_update={"key_share": True})
     merged = dict(user.preferences or {})
     merged.update(preferences.root)
     user.preferences = merged

backend/app/routes/notifications.py

@@ -5,6 +5,7 @@ from fastapi import APIRouter, Depends, Query
 from sqlalchemy import func, select, update
 from sqlalchemy.orm import Session
 
+from app.userscope import owned_by
 from app.auth import current_user
 from app.db import get_db
 from app.models import Notification, User
@@ -36,7 +37,7 @@ def list_notifications(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    where = [Notification.user_id == user.id]
+    where = [owned_by(Notification.user_id, user)]
     if not include_dismissed:
         where.append(Notification.dismissed.is_(False))
     total = db.scalar(select(func.count()).select_from(Notification).where(*where)) or 0
@@ -61,7 +62,7 @@ def unread_count(user: User = Depends(current_user), db: Session = Depends(get_d
         select(func.count())
         .select_from(Notification)
         .where(
-            Notification.user_id == user.id,
+            owned_by(Notification.user_id, user),
             Notification.read.is_(False),
             Notification.dismissed.is_(False),
         )
@@ -77,8 +78,8 @@ def mark_read(
 ) -> dict:
     n = owned_or_404(db, Notification, notification_id, user, what="notification")
     n.read = True
-    db.commit()
     trim_read(db, user.id)
+    db.commit()
     return {"ok": True}
 
 
@@ -86,11 +87,11 @@ def mark_read(
 def mark_all_read(user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
     db.execute(
         update(Notification)
-        .where(Notification.user_id == user.id, Notification.read.is_(False))
+        .where(owned_by(Notification.user_id, user), Notification.read.is_(False))
         .values(read=True)
     )
-    db.commit()
     trim_read(db, user.id)
+    db.commit()
     return {"ok": True}
 
 
@@ -113,7 +114,7 @@ def clear_all(user: User = Depends(current_user), db: Session = Depends(get_db))
     """Dismiss every (still-visible) notification for this user."""
     db.execute(
         update(Notification)
-        .where(Notification.user_id == user.id, Notification.dismissed.is_(False))
+        .where(owned_by(Notification.user_id, user), Notification.dismissed.is_(False))
         .values(dismissed=True, read=True)
     )
     db.commit()

backend/app/routes/plex/detail.py

@@ -100,7 +100,7 @@ def show_detail(
         raise not_found("show")
     seasons = queries.seasons(db, sh)
     eps = queries.episodes(db, sh)
-    states = queries.states(db, user, [e.id for e in eps])
+    states = rollup.item_state_map(db, user, [e.id for e in eps])
     by_season: dict[int | None, list] = {}
     all_cards: list[dict] = []  # every episode, in season/episode order → show-level rollup
     for e in eps:
@@ -247,7 +247,7 @@ def _collection_strips(db: Session, it: "PlexItem", user_id: int, lang: str) ->
     for col in ordered:
         rk = col.rating_key
         members = queries.library_movies_in(db, it.library_id, rk, lang, limit=60)
-        states = queries.states(db, user_id, [m.id for m in members])
+        states = rollup.item_state_map(db, user_id, [m.id for m in members])
         out.append(
             {
                 "id": rk,

backend/app/routes/plex/playback.py

@@ -19,7 +19,7 @@ from fastapi.responses import FileResponse
 from pydantic import BaseModel
 from sqlalchemy.orm import Session
 
-from app.auth import current_user, resolved_user_id
+from app.auth import current_user, session_user_id
 from app.db import SessionLocal, get_db
 from app.models import User
 from app.plex import imgcache, queries, service, subtitles
@@ -42,7 +42,7 @@ def _require_session(request: Request) -> int:
     """Lightweight auth for the high-fan-out image proxies: validate the signed session cookie WITHOUT
     a DB user-load, so these endpoints never hold a pool connection for the auth. Poster images are
     low-sensitivity; a valid session is enough."""
-    uid, _ = resolved_user_id(request)
+    uid = session_user_id(request)
     if not uid:
         raise refused(401, "not_authenticated")
     return uid

backend/app/routes/plex/playlists.py

@@ -9,7 +9,7 @@ from sqlalchemy.orm import Session
 from app.auth import current_user
 from app.db import get_db
 from app.models import User
-from app.plex import queries, service
+from app.plex import queries, rollup, service
 from app.plex.cards import display_title, leaf_card, norm_lang
 from app.refusal import refused
 from app.routes._common import not_found
@@ -99,7 +99,7 @@ def playlist_detail(
     lang = norm_lang(lang)
     pl = _own_playlist(db, user, pid)
     items = queries.playlist_items(db, pl.id)
-    states = queries.states(db, user, [it.id for it in items])
+    states = rollup.item_state_map(db, user, [it.id for it in items])
     shows = queries.shows_by_ids(db, {it.show_id for it in items if it.show_id})
     cards = [
         leaf_card(

backend/app/routes/quota.py

@@ -10,6 +10,7 @@ from fastapi import APIRouter, Depends, Query
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
+from app.userscope import owned_by
 from app import quota
 from app.auth import admin_user, current_user
 from app.db import get_db
@@ -27,7 +28,7 @@ def _sum(db: Session, *conds) -> int:
 @router.get("/my-usage")
 def my_usage(user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
     now = datetime.now(timezone.utc)
-    mine = QuotaEvent.user_id == user.id
+    mine = owned_by(QuotaEvent.user_id, user)
     by_action = {
         action: int(units)
         for action, units in db.execute(

backend/app/routes/tokens.py

@@ -16,6 +16,7 @@ from pydantic import BaseModel, Field
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
+from app.userscope import owned_by
 from app import apitokens, audit
 from app.apitokens import GRANT_COLUMNS, Right
 from app.audit import AuditAction
@@ -86,7 +87,7 @@ def _serialize(db: Session, token: ApiToken) -> dict:
 @router.get("")
 def list_tokens(user: User = Depends(current_user), db: Session = Depends(get_db)) -> list[dict]:
     tokens = (
-        db.execute(select(ApiToken).where(ApiToken.user_id == user.id).order_by(ApiToken.id))
+        db.execute(select(ApiToken).where(owned_by(ApiToken.user_id, user)).order_by(ApiToken.id))
         .scalars()
         .all()
     )
@@ -134,7 +135,7 @@ def create_token(
     if (epoch or 0) != (user.session_epoch or 0):
         raise refused(401, "not_authenticated")
     count = db.execute(
-        select(func.count(ApiToken.id)).where(ApiToken.user_id == user.id)
+        select(func.count(ApiToken.id)).where(owned_by(ApiToken.user_id, user))
     ).scalar_one()
     if count >= MAX_TOKENS:
         raise refused(409, "api_token_limit", limit=MAX_TOKENS)

backend/app/userscope.py

@@ -1,10 +1,11 @@
 """Whose a row is, and who an account is to the others — one place for both.
 
 **Ownership.** A user-owned table says whose a row is in one column (`user_id`, or `to_user_id` for
-something handed to them). A unit's reads and writes name that column through `owned_by` and fetch a
+something handed to them). Every read and write names that column through `owned_by` and fetches a
 row by id through `owned_row`, never with an inline `Model.user_id == …`: the rule "a row owned by
-someone else is answered like a missing one" then lives here, and a contract test
-(`test_unit_fences.py`) holds a switched-on unit to it.
+someone else is answered like a missing one" then lives here. A contract test
+(`test_unit_fences.py`) holds every module, core included, to the filter's form; a rule this module
+cannot say (own or shared, built-in or own) is written out where it applies, with its reason.
 
 **Recipients.** "An active, non-suspended account" — the download share-by-email and the recipient
 picker filter on it. Kept here so the two forms (SQL clauses for a query, a Python check for a loaded

backend/app/worker.py

@@ -31,6 +31,7 @@ from functools import partial
 from sqlalchemy import text
 from sqlalchemy.orm import Session
 
+import app.tables  # noqa: F401 — every table, before the first query
 from app import logs
 from app import logsink
 from app import sysconfig

backend/requirements.lock

@@ -5,7 +5,8 @@
 # scans it, blocking. A security fix, or a yt-dlp release YouTube's changes force, may be ONE pin
 # bumped in place instead of a full regeneration, which would move every other package too — then
 # `pip install -r requirements.lock && pip check` must pass. In place so far: urllib3 2.7.0 -> 2.8.0 (PYSEC-2026-4175/4176/4177); yt-dlp 2026.7.4 -> 2026.8.19
-# (it marks the clients that need a stream PO token, so the downloader stops fetching into a 403).
+# (it marks the clients that need a stream PO token, so the downloader stops fetching into a 403);
+# certifi 2026.7.22 -> 2026.10.19 (GHSA-6q48-6c7w-9gw2).
 APScheduler==3.11.3
 Authlib==1.7.2
 Mako==1.4.1
@@ -21,7 +22,7 @@ argon2-cffi-bindings==25.1.0
 argon2-cffi==25.1.0
 bgutil-ytdlp-pot-provider==1.3.1
 brotli==1.2.0
-certifi==2026.7.22
+certifi==2026.10.19
 cffi==2.1.1
 charset-normalizer==3.5.1
 click==8.4.2

backend/tests/conftest.py

@@ -105,6 +105,11 @@ def pytest_configure(config):
         )
 
 
+def _write_xact(db) -> str | None:
+    """The id of the open transaction if it has written anything, else None (a read never takes one)."""
+    return db.scalar(text("SELECT pg_current_xact_id_if_assigned()::text"))
+
+
 def _request_dep(db, unfinished: list[str]):
     """`get_db` for a test request: the test's own session, plus the check a shared session hides.
 
@@ -114,15 +119,16 @@ def _request_dep(db, unfinished: list[str]):
     and the suite stays green over a handler that forgot to commit (deep review, debt burn). So a
     request that ends normally with a write it did not commit — flushed, or still only staged — is
     recorded, and the test fails on it at teardown. Only the ROOT transaction's end clears it: a
-    savepoint released inside the handler commits nothing. The test's own staged rows are flushed before the request starts — they are the
-    test's business, not the handler's. A request that raises is rolled back, as production's
+    savepoint released inside the handler commits nothing. What the test itself staged or wrote is
+    committed before the request starts — it is the test's business, not the handler's, and a
+    request then begins with no write open, so any write left at its end is the handler's. A request that raises is rolled back, as production's
     `close()` rolls it back: without that, what a failing handler flushed but never committed stayed
     readable to the rest of the test — the one state production cannot be in (an issue created
     on the tracker before a failed upload was kept only by an explicit commit, and nothing saw it
     missing)."""
 
     def dep(conn: HTTPConnection):
-        db.flush()
+        db.commit()
         state = {"dirty": False}
 
         def flushed(session, ctx):
@@ -138,7 +144,12 @@ def _request_dep(db, unfinished: list[str]):
         try:
             yield db
             staged = db.new or db.deleted or any(db.is_modified(o) for o in db.dirty)
-            if state["dirty"] or staged:
+            # Core DML (`db.execute(update(...))`) fires no flush and stages nothing; the database
+            # itself says whether a write is open — the request began with none, and a transaction
+            # that wrote and was not committed holds an id (see `release_read_connection`). A row
+            # lock (`FOR UPDATE`) takes one too: the handler ends what it locked.
+            core_dml = _write_xact(db) is not None
+            if state["dirty"] or staged or core_dml:
                 unfinished.append(f"{conn.scope.get('method', 'WS')} {conn.url.path}")
         except Exception:
             db.rollback()
@@ -220,7 +231,7 @@ def _configured(monkeypatch):
 @pytest.fixture
 def client(db, override_dep, _configured):
     """A TestClient wired to the test DB that goes through the REAL auth/session stack — no
-    `current_user` override — so login, the wallet gate and epoch revoke are exercised end to end.
+    `current_user` override — so login, the one-account session and epoch revoke are exercised end to end.
     Starlette's SessionMiddleware round-trips the signed cookie, so a login in one call authenticates
     the next on this same instance. No lifespan (the scheduler / HLS sweep stay off)."""
     override_dep(get_db, db.info["request"])

backend/tests/test_auth_session.py

@@ -1,21 +1,25 @@
 """Auth / session security core (TEST-1), DB-lane.
 
-The wallet impersonation gate, epoch-based session revocation, single-use tokens and the
-enumeration-safe uniform 401 are the security mag, and had zero tests (only `_oauth_redirect_uri` was
-covered). Starlette's SessionMiddleware round-trips the signed cookie under TestClient, so the whole
-browser-less flow is exercisable. Uses the real auth stack via the `client` fixture (NO current_user
-override) so login, the wallet gate and epoch revoke are the code under test.
+One account per browser session, epoch-based session revocation, single-use tokens and the
+enumeration-safe uniform 401 are the security mag. Starlette's SessionMiddleware round-trips the
+signed cookie under TestClient, so the whole browser-less flow is exercisable. Uses the real auth
+stack via the `client` fixture (NO current_user override) so login, the session and epoch revoke are
+the code under test.
 
 Note: `/api/me` is the bootstrap probe — it returns 200 `{authenticated: False}` when logged out, not a
 401. A revoked session is therefore checked on a PROTECTED endpoint (`/api/feed`), which does 401.
 """
 
+import base64
+import json
 from datetime import timedelta
+from pathlib import Path
 
 import pytest
 from fastapi.testclient import TestClient
+from itsdangerous import TimestampSigner
 
-from app.auth import ACTIVE_ACCOUNT_HEADER
+from app.config import settings
 from app.main import app
 
 _PW = "correct horse battery"
@@ -46,74 +50,48 @@ def test_wrong_password_and_unknown_email_give_a_byte_identical_401(client, make
     assert wrong_pw.json() == unknown.json()
 
 
-def test_a_non_wallet_account_header_falls_back_to_the_default(client, make_user):
-    # The X-Siftlode-Account header may only re-target an account already signed into THIS browser
-    # (in the session wallet). A header naming someone else must be ignored, not honored — otherwise
-    # it's an impersonation gate hole.
-    make_user(email="alice2@example.com", password=_PW)
-    mallory = make_user(email="mallory@example.com", password=_PW)
-    assert _login(client, "alice2@example.com", _PW).status_code == 200
-    me = client.get("/api/me", headers={ACTIVE_ACCOUNT_HEADER: str(mallory.id)})
-    assert me.status_code == 200
-    assert me.json()["email"] == "alice2@example.com"  # still Alice, not Mallory
+def _cookie(payload: dict) -> str:
+    """A session cookie signed the way SessionMiddleware signs one — for a cookie an older build wrote."""
+    data = base64.b64encode(json.dumps(payload).encode())
+    return TimestampSigner(str(settings.secret_key)).sign(data).decode()
 
 
-def test_a_tab_pinned_to_an_account_signed_out_elsewhere_acts_as_nobody(client, make_user):
-    # Two accounts in one browser: a tab pinned to Alice, Bob the default. Alice signs out in another
-    # tab. The pinned tab used to go on acting as the default, Bob — its player checkpoints and pref
-    # saves landed in his account, and its own Sign out signed HIM out.
-    alice = make_user(email="alice3@example.com", password=_PW)
+def test_signing_in_as_another_account_replaces_the_first(client, make_user):
+    # One account per browser session: a second sign-in is a fresh session, not a second account
+    # beside the first — so signing out leaves nobody signed in here.
+    make_user(email="alice3@example.com", password=_PW)
     make_user(email="bob3@example.com", password=_PW)
     assert _login(client, "alice3@example.com", _PW).status_code == 200
-    assert _login(client, "bob3@example.com", _PW).status_code == 200  # Bob is now the default
-    tab = {ACTIVE_ACCOUNT_HEADER: str(alice.id)}
-    assert client.get("/api/feed", headers=tab).status_code == 200
-    assert client.post("/auth/logout", headers=tab).status_code == 200  # Alice signs out
+    assert _login(client, "bob3@example.com", _PW).status_code == 200
+    assert client.get("/api/me").json()["email"] == "bob3@example.com"
 
-    assert client.get("/api/feed", headers=tab).status_code == 401
-    assert client.post("/auth/logout", headers=tab).status_code == 200
-    assert client.get("/api/feed").status_code == 200  # Bob is still signed in, the session intact
-    # The bootstrap probe still answers as the default: how the stale tab learns who it is now.
-    assert client.get("/api/me", headers=tab).json()["email"] == "bob3@example.com"
+    assert client.post("/auth/logout").status_code == 200
+    assert client.get("/api/feed").status_code == 401
+    assert client.get("/api/me").json() == {"authenticated": False}
 
 
-@pytest.mark.parametrize("ended", ["revoked", "suspended"])
-def test_a_tab_pinned_to_an_account_whose_session_ended_comes_back_as_the_default(
-    client, make_user, db, ended
-):
-    # A tab pinned to Alice, Bob the default. Alice's session then ends while she is still in this
-    # browser's wallet ("log out everywhere" on another device, or an admin suspends her). The tab's
-    # bootstrap probe used to answer "signed out": the landing page with Bob still signed in, and no way
-    # off it but closing the tab (signing in as anyone else there kept the tab pinned to Alice).
+def test_no_header_or_parameter_picks_another_account(client, make_user):
+    # Alice signed in here before Bob: nothing a request carries makes it act as her any more.
     alice = make_user(email="alice4@example.com", password=_PW)
     make_user(email="bob4@example.com", password=_PW)
     assert _login(client, "alice4@example.com", _PW).status_code == 200
     assert _login(client, "bob4@example.com", _PW).status_code == 200
-    tab = {ACTIVE_ACCOUNT_HEADER: str(alice.id)}
-    assert client.get("/api/feed", headers=tab).status_code == 200
-    if ended == "revoked":
-        alice.session_epoch = (alice.session_epoch or 0) + 1
-    else:
-        alice.is_suspended = True
-    db.commit()
+    me = client.get(f"/api/me?account={alice.id}", headers={"X-Siftlode-Account": str(alice.id)})
+    assert me.json()["email"] == "bob4@example.com"
 
-    assert client.get("/api/me", headers=tab).json()["email"] == "bob4@example.com"
-    assert client.get("/api/feed", headers=tab).status_code == 401  # still nobody, never Bob
-    assert client.get("/api/feed").status_code == 200  # Bob's session is intact
+
+@pytest.mark.parametrize("path", ["/api/me/accounts", "/api/me/switch"])
+def test_there_is_no_account_list_or_switch(client, make_user, path):
+    make_user(email="alice5@example.com", password=_PW)
+    assert _login(client, "alice5@example.com", _PW).status_code == 200
+    r = client.get(path) if path.endswith("accounts") else client.post(path, json={"user_id": 1})
+    assert r.status_code in (404, 405)
 
 
 @pytest.mark.parametrize("ended", ["revoked", "suspended", "deactivated"])
-def test_switching_to_an_account_whose_session_ended_refuses_it_and_drops_it_from_the_list(
-    client, make_user, db, monkeypatch, ended
-):
-    # The account switcher lists this browser's wallet. A revoked account was dropped from it on a refused
-    # switch, but a suspended one stayed, refused on every click; a deactivated one was not refused at all —
-    # made the default, the next request found it inactive and signed every account here out.
-    monkeypatch.setattr("app.routes.me.is_allowed", lambda _db, _email: True)  # both hold an invite
-    alice = make_user(email="alice5@example.com", password=_PW)
-    make_user(email="bob5@example.com", password=_PW)
-    assert _login(client, "alice5@example.com", _PW).status_code == 200
-    assert _login(client, "bob5@example.com", _PW).status_code == 200
+def test_a_session_whose_account_ended_signs_the_browser_out(client, make_user, db, ended):
+    alice = make_user(email="alice6@example.com", password=_PW)
+    assert _login(client, "alice6@example.com", _PW).status_code == 200
     if ended == "revoked":
         alice.session_epoch = (alice.session_epoch or 0) + 1
     elif ended == "suspended":
@@ -121,10 +99,111 @@ def test_switching_to_an_account_whose_session_ended_refuses_it_and_drops_it_fro
     else:
         alice.is_active = False
     db.commit()
+    assert client.get("/api/feed").status_code == 401
+    assert "user_id" not in _session(client)  # the refusal ended the session, not just this request
+    assert client.get("/api/me").json() == {"authenticated": False}
 
-    assert client.post("/api/me/switch", json={"user_id": alice.id}).status_code == 403
-    assert [a["email"] for a in client.get("/api/me/accounts").json()] == ["bob5@example.com"]
-    assert client.get("/api/feed").status_code == 200  # Bob is still signed in
+
+def test_a_cookie_from_the_multi_account_build_signs_in_again(client, make_user):
+    # The old session held a wallet and one epoch per account. It is not read: whoever holds one
+    # signs in once more.
+    alice = make_user(email="alice7@example.com", password=_PW)
+    old = {"user_id": alice.id, "account_ids": [alice.id], "epochs": {str(alice.id): 0}}
+    client.cookies.set("session", _cookie(old))
+    assert client.get("/api/feed").status_code == 401
+    assert client.get("/api/me").json() == {"authenticated": False}
+
+
+def test_deleting_the_account_signs_the_browser_out(client, make_user):
+    make_user(email="alice8@example.com", password=_PW)
+    assert _login(client, "alice8@example.com", _PW).status_code == 200
+    assert client.delete("/api/me/account").status_code == 200
+    # The cookie names nobody now: the probe answers signed out without looking the account up.
+    assert "user_id" not in _session(client)
+
+
+def _session(client) -> dict:
+    """The decoded payload of the client's session cookie."""
+    raw = client.cookies.get("session")
+    if not raw:
+        return {}
+    data = TimestampSigner(str(settings.secret_key)).unsign(raw.encode())
+    return json.loads(base64.b64decode(data))
+
+
+@pytest.mark.parametrize("signed_in_as", ["starter", "someone_else"])
+def test_a_google_link_lands_only_on_the_account_still_signed_in(db, make_user, signed_in_as):
+    # The link marker names who started it; a sign-in as someone else before the callback must not
+    # get that Google identity attached to the account that started it from the other person's session.
+    from starlette.requests import Request
+
+    from app.routes.auth import _complete_link
+
+    starter, other = make_user(), make_user()
+    session = {"user_id": starter.id if signed_in_as == "starter" else other.id, "epoch": 0}
+    request = Request({"type": "http", "session": session, "headers": []})
+    resp = _complete_link(request, db, starter.id, True, "sub-123", {"email": ""}, {"scope": ""})
+    db.refresh(starter)
+    if signed_in_as == "starter":
+        assert resp.headers["location"] == "/?link=ok"
+        assert starter.google_sub == "sub-123"
+    else:
+        assert resp.headers["location"] == "/?link=error"
+        assert starter.google_sub is None
+
+
+def test_no_app_code_reads_a_second_account():
+    # The multi-account machinery is gone; a module reading its session keys or its header again
+    # would bring back a session that names more than one account.
+    app_dir = Path(__file__).parent.parent / "app"
+    hits = [
+        f"{path.relative_to(app_dir)}: {word}"
+        for path in app_dir.rglob("*.py")
+        for word in ("account_ids", '"epochs"', "x-siftlode-account", 'query_params.get("account")')
+        if word in path.read_text(encoding="utf-8").lower()
+    ]
+    assert hits == []
+
+
+def test_a_tab_built_for_the_account_signed_in_before_is_refused(client, make_user):
+    # Two tabs of one browser: one signed in as someone else, so the cookie is Bob's under both. The
+    # tab still showing Alice says so with every request; acting as Bob there would put her player
+    # positions, pref saves and Sign out on his account. Refused, and the session stays Bob's.
+    alice = make_user(email="alice5@example.com", password=_PW)
+    bob = make_user(email="bob5@example.com", password=_PW)
+    assert _login(client, "alice5@example.com", _PW).status_code == 200
+    assert _login(client, "bob5@example.com", _PW).status_code == 200
+
+    stale = client.get("/api/feed", headers={"X-Siftlode-Expect-Account": str(alice.id)})
+    assert stale.status_code == 401
+    assert stale.json()["detail"]["reason"] == "account_changed"
+    assert (
+        client.get("/api/feed", headers={"X-Siftlode-Expect-Account": str(bob.id)}).status_code
+        == 200
+    )
+    assert client.get("/api/feed").status_code == 200
+    # Nor may its Sign out end Bob's session.
+    assert (
+        client.post(
+            "/auth/logout", headers={"X-Siftlode-Expect-Account": str(alice.id)}
+        ).status_code
+        == 401
+    )
+    # The probe answers who is signed in now, so the stale tab can reload as Bob.
+    probe = client.get("/api/me", headers={"X-Siftlode-Expect-Account": str(alice.id)})
+    assert probe.json()["email"] == "bob5@example.com"
+
+
+def test_setting_a_password_keeps_the_caller_signed_in(client, make_user):
+    # The change ends every OTHER session (the epoch moves); the caller is stamped with the new one.
+    make_user(email="dave@example.com", password=_PW)
+    assert _login(client, "dave@example.com", _PW).status_code == 200
+    r = client.post(
+        "/auth/set-password",
+        json={"password": "a brand new passphrase", "current_password": _PW},
+    )
+    assert r.status_code == 200
+    assert client.get("/api/feed").status_code == 200
 
 
 def test_logout_others_revokes_the_other_session_but_keeps_the_caller(client, make_user):

backend/tests/test_autotag_orphans.py

@@ -8,6 +8,8 @@ drops an unknown id, so the view silently showed the whole feed under its old na
 from sqlalchemy import select
 
 from app.catalog.models import Channel
+from app.db import SessionLocal
+from app.sync.autotag import run_autotag_all
 from app.reader.models import ChannelTag, SavedView, Tag
 from app.reader import service as reader_service
 
@@ -66,3 +68,15 @@ def test_a_view_kept_tag_list_larger_than_a_bind_parameter_limit_still_cleans_up
     db.commit()
     assert reader_service.prune_orphan_system_tags(db) == 1
     db.commit()
+
+
+def test_the_job_commits_its_cleanup(db):
+    """The prune only flushes; the job ends its own transaction. Read from a session of its own,
+    the orphan is gone only once the job committed — the job's session would see its own delete
+    either way."""
+    orphan = Tag(user_id=None, name="Cooking", category="topic")
+    db.add(orphan)
+    db.commit()
+    assert run_autotag_all(db, only_missing=True)["orphan_tags_removed"] == 1
+    with SessionLocal() as fresh:
+        assert fresh.execute(select(Tag).where(Tag.name == "Cooking")).first() is None

backend/tests/test_entry_points.py

@@ -0,0 +1,69 @@
+"""Every process the app runs as sees every table before its first query.
+
+The units declare their tables in their own `models` modules, and a core model names a unit's by
+string (`User.subscriptions` → `Subscription`). A fresh interpreter that never imported the unit's
+module fails to configure its mappers on its first query: the download child once did exactly that,
+and every job failed, while this suite stayed green — it imports `app.tables` in-process, which hides
+the gap. So each entry point is imported here in a clean interpreter, and must register the whole
+schema on its own.
+"""
+
+import ast
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import app.tables  # noqa: F401
+from app.db import Base
+
+BACKEND = Path(__file__).parent.parent
+APP = BACKEND / "app"
+
+# Each `python -m` module the deployment starts, and the API's app module.
+ENTRY_POINTS = ("app.main", "app.worker", "app.downloads.runner")
+
+# The table list goes out on one marked line: the API's logging writes to the same stdout, and a
+# line it logs while importing is not the probe's answer.
+_MARK = "entry-point-tables:"
+_PROBE = (
+    "import importlib, json, sys\n"
+    "importlib.import_module(sys.argv[1])\n"
+    "from sqlalchemy.orm import configure_mappers\n"
+    "from app.db import Base\n"
+    "configure_mappers()\n"
+    f"print({_MARK!r} + json.dumps(sorted(Base.metadata.tables)))\n"
+)
+
+
+def test_each_entry_point_registers_the_whole_schema_on_its_own():
+    whole = sorted(Base.metadata.tables)
+    for module in ENTRY_POINTS:
+        r = subprocess.run(
+            [sys.executable, "-c", _PROBE, module],
+            cwd=BACKEND,
+            capture_output=True,
+            text=True,
+            timeout=120,
+            check=False,
+        )
+        assert r.returncode == 0, (module, r.stderr[-2000:])
+        answer = [ln for ln in r.stdout.splitlines() if ln.startswith(_MARK)]
+        assert len(answer) == 1, (module, r.stdout[-2000:])
+        assert json.loads(answer[0].removeprefix(_MARK)) == whole, module
+
+
+def test_every_module_that_runs_as_a_process_is_listed():
+    mains = set()
+    for path in APP.rglob("*.py"):
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        for node in tree.body:
+            if (
+                isinstance(node, ast.If)
+                and isinstance(node.test, ast.Compare)
+                and isinstance(node.test.left, ast.Name)
+                and node.test.left.id == "__name__"
+            ):
+                rel = path.relative_to(BACKEND).with_suffix("").as_posix()
+                mains.add(rel.replace("/", "."))
+    assert mains <= set(ENTRY_POINTS), mains - set(ENTRY_POINTS)

backend/tests/test_files_api.py

@@ -124,6 +124,9 @@ def test_only_an_own_folder_is_renamed_and_only_by_its_user(db, make_user, as_us
     assert clash.json()["detail"]["reason"] == "file_folder_name_taken"
     no = c.patch(f"/api/files/folders/{src.id}", json={"name": "YouTube 2"})
     assert no.status_code == 409 and no.json()["detail"]["reason"] == "file_folder_not_own"
+    # Which folder is answered before what the name is: a blank one is still "not yours to name".
+    blank = c.patch(f"/api/files/folders/{src.id}", json={"name": " "})
+    assert blank.status_code == 409 and blank.json()["detail"]["reason"] == "file_folder_not_own"
     stranger = as_user(make_user()).patch(f"/api/files/folders/{own.id}", json={"name": "X"})
     assert stranger.status_code == 404
     db.refresh(own)

backend/tests/test_google_callback.py

@@ -7,6 +7,7 @@ the refused sign-in that doubles as an access request, and the link flow's confl
 """
 
 import pytest
+from authlib.integrations.starlette_client import OAuthError
 from sqlalchemy import select
 from starlette.responses import RedirectResponse
 
@@ -19,15 +20,20 @@ _PW = "correct horse battery"
 
 class _FakeGoogle:
     """authlib's client, reduced to the two calls the routes make: the redirect out to Google and
-    the token exchange when Google redirects back."""
+    the token exchange when Google redirects back. Like authlib, it honours only the newest flow's
+    state: starting a flow retires every earlier one."""
 
     def __init__(self, userinfo: dict):
         self.userinfo = userinfo
+        self.asked: dict = {}
 
-    async def authorize_redirect(self, _request, _redirect_uri, **_kw):
+    async def authorize_redirect(self, _request, _redirect_uri, **kw):
+        self.asked = kw
         return RedirectResponse(url="/fake-google")
 
-    async def authorize_access_token(self, _request):
+    async def authorize_access_token(self, request):
+        if request.query_params.get("state") != self.asked.get("state"):
+            raise OAuthError(error="mismatching_state")
         return {"userinfo": self.userinfo, "access_token": "at", "scope": "openid email profile"}
 
 
@@ -44,9 +50,13 @@ def google(monkeypatch):
     return fake
 
 
-def _sign_in(client, google, **userinfo):
+def _sign_in(client, google, state: str | None = None, **userinfo):
+    """Google redirecting back: by default with the state of the flow started last."""
     google.userinfo = {"email_verified": True, **userinfo}
-    return client.get("/auth/callback", follow_redirects=False)
+    state = state or google.asked.get("state")
+    return client.get(
+        "/auth/callback", params={"state": state} if state else {}, follow_redirects=False
+    )
 
 
 def _rows(db, model, column, value):
@@ -218,12 +228,20 @@ def test_a_refused_sign_in_records_a_request_in_the_reported_language(
     assert _rows(db, User, User.email, "new@example.com") == []
 
 
-def _start_link(client, email: str):
+def _password_login(client, email: str):
     assert (
         client.post("/auth/password-login", json={"email": email, "password": _PW}).status_code
         == 200
     )
-    assert client.get("/auth/link", follow_redirects=False).headers["location"] == "/fake-google"
+
+
+def _connect(client, access: str):
+    return client.get(f"/auth/google/connect?access={access}", follow_redirects=False)
+
+
+def _start_link(client, email: str):
+    _password_login(client, email)
+    assert _connect(client, "identity").headers["location"] == "/fake-google"
 
 
 def test_linking_an_identity_another_account_holds_is_a_conflict(client, db, google, make_user):
@@ -258,3 +276,151 @@ def test_linking_a_free_identity_attaches_it(client, db, google, make_user):
     assert r.headers["location"] == "/?link=ok"
     db.refresh(me)
     assert (me.google_sub, me.google_email) == ("sub-free", "me3.google@example.com")
+
+
+def test_a_connect_abandoned_at_google_leaves_the_next_sign_in_a_sign_in(
+    client, db, google, make_user, monkeypatch
+):
+    # A connect left at Google's screen (Back, a closed tab) never reaches the callback that pops
+    # its marker. "Sign in as someone else" afterwards must sign that person in, not link their
+    # Google identity onto the account still signed in here.
+    me = make_user(email="me4@example.com")
+    make_user(email="them4@example.com", google_sub="sub-them4", password=None)
+    monkeypatch.setattr(settings, "allowed_emails", "them4@example.com")
+    _start_link(client, "me4@example.com")
+    assert client.get("/auth/login", follow_redirects=False).headers["location"] == "/fake-google"
+
+    r = _sign_in(client, google, sub="sub-them4", email="them4@example.com")
+
+    assert r.headers["location"] == "/"
+    assert client.get("/api/me").json()["email"] == "them4@example.com"
+    db.refresh(me)
+    assert me.google_sub is None
+
+
+def test_a_link_whose_session_was_revoked_meanwhile_does_not_finish(client, db, google, make_user):
+    # "Log out everywhere" (or a password change) between the start and the callback: the cookie
+    # still names the account, but its session no longer holds, so it may not attach an identity.
+    me = make_user(email="me5@example.com")
+    _start_link(client, "me5@example.com")
+    me.session_epoch = (me.session_epoch or 0) + 1
+    db.commit()
+
+    r = _sign_in(client, google, sub="sub-late", email="late@example.com")
+
+    assert r.headers["location"] == "/?link=error"
+    db.refresh(me)
+    assert me.google_sub is None
+
+
+def test_an_older_flow_coming_back_leaves_the_connect_in_flight_a_link(
+    client, db, google, make_user
+):
+    # Two round-trips from one browser: an older one (another tab's, or Back to Google's screen)
+    # returns after a connect started. Its state is refused, and it must not spend the connect's
+    # marker: the connect itself, coming back, would then land as a plain sign-in.
+    me = make_user(email="me6@example.com")
+    _start_link(client, "me6@example.com")
+
+    older = _sign_in(client, google, state="an-older-flow", sub="sub-6", email="g6@example.com")
+    assert older.headers["location"] == "/?oauth=cancelled"
+    r = _sign_in(client, google, sub="sub-6", email="g6@example.com")
+
+    assert r.headers["location"] == "/?link=ok"
+    db.refresh(me)
+    assert me.google_sub == "sub-6"
+
+
+def test_a_connect_from_a_tab_showing_another_account_starts_nothing(client, google, make_user):
+    # A navigation carries no headers, so the tab names the account it was built for in the query.
+    # One still showing the account signed in before must not start a link onto the one signed in
+    # now: it lands on the app, which boots as that one and says why.
+    me = make_user(email="me7@example.com")
+    _password_login(client, "me7@example.com")
+
+    r = client.get(
+        f"/auth/google/connect?access=identity&expect={me.id + 1}", follow_redirects=False
+    )
+
+    assert r.headers["location"] == auth_routes.ACCOUNT_CHANGED_LANDING == "/?account=changed"
+    assert google.asked == {}
+    assert client.get("/api/me").json()["email"] == "me7@example.com"
+
+
+def test_a_connect_naming_the_signed_in_account_goes_to_google(client, google, make_user):
+    me = make_user(email="me8@example.com")
+    _password_login(client, "me8@example.com")
+
+    r = client.get(f"/auth/google/connect?access=identity&expect={me.id}", follow_redirects=False)
+
+    assert r.headers["location"] == "/fake-google"
+    assert google.asked["state"]
+
+
+@pytest.mark.parametrize(
+    ("access", "scope", "prompt"),
+    [
+        ("identity", "openid email profile", "select_account"),
+        ("read", auth_routes.READ_SCOPES, "consent"),
+        ("write", auth_routes.WRITE_SCOPES, "consent"),
+    ],
+)
+def test_one_connect_route_asks_google_for_what_the_access_needs(
+    client, google, make_user, access, scope, prompt
+):
+    make_user(email=f"ask-{access}@example.com")
+    _password_login(client, f"ask-{access}@example.com")
+
+    assert _connect(client, access).headers["location"] == "/fake-google"
+
+    assert (google.asked["scope"], google.asked["prompt"]) == (scope, prompt)
+    assert google.asked["access_type"] == "offline"
+
+
+@pytest.mark.parametrize("access", ["read", "write"])
+def test_a_youtube_grant_attaches_to_the_password_account_and_returns_to_the_app(
+    client, db, google, make_user, access
+):
+    me = make_user(email=f"grant-{access}@example.com")
+    _password_login(client, f"grant-{access}@example.com")
+    _connect(client, access)
+
+    r = _sign_in(client, google, sub=f"sub-grant-{access}", email=f"g-{access}@example.com")
+
+    # Back to the app, not the "linked" notice: the onboarding wizard picks up where it was.
+    assert r.headers["location"] == "/"
+    db.refresh(me)
+    assert me.google_sub == f"sub-grant-{access}"
+    assert _rows(db, User, User.google_sub, f"sub-grant-{access}") == [me]
+
+
+@pytest.mark.parametrize("access", ["", "admin", "READ"])
+def test_an_unknown_access_starts_no_connect(client, google, make_user, access):
+    make_user(email="odd@example.com")
+    _password_login(client, "odd@example.com")
+
+    assert _connect(client, access).status_code == 422
+    assert google.asked == {}
+
+
+def test_a_connect_needs_a_signed_in_account(client, google):
+    assert _connect(client, "identity").status_code == 401
+    assert google.asked == {}
+
+
+@pytest.mark.parametrize("access", ["identity", "read", "write"])
+def test_without_google_configured_a_connect_says_it_failed(client, make_user, monkeypatch, access):
+    monkeypatch.setattr(auth_routes, "google_oauth", lambda _db: None)
+    make_user(email=f"nog-{access}@example.com")
+    _password_login(client, f"nog-{access}@example.com")
+
+    assert _connect(client, access).headers["location"] == "/?link=error"
+
+
+@pytest.mark.parametrize("path", ["/auth/link", "/auth/upgrade", "/auth/upgrade?access=write"])
+def test_the_old_connect_routes_are_gone(client, google, make_user, path):
+    make_user(email="old@example.com")
+    _password_login(client, "old@example.com")
+
+    assert client.get(path, follow_redirects=False).status_code == 404
+    assert google.asked == {}

backend/tests/test_me_preferences.py

@@ -0,0 +1,74 @@
+"""PUT /api/me/preferences merges the keys it is sent into the stored ones, DB-lane.
+
+A client saves its preferences a key at a time, and several at once on the boot that moves this
+browser's copies to the account. Each merge must start from the row as stored when it runs, not as
+the request first read it — two merges over the same earlier read keep only the last one's keys.
+"""
+
+from fastapi import Depends, Request
+from sqlalchemy import event, update
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session
+
+from app.auth import current_user
+from app.db import SessionLocal, get_db
+from app.models import User
+
+_PW = "correct horse battery"
+
+
+def test_a_save_keeps_a_key_another_save_stored_after_this_one_read_the_account(
+    client, db, make_user, override_dep
+):
+    user = make_user(email="prefs@example.com", password=_PW)
+    assert (
+        client.post("/auth/password-login", json={"email": "prefs@example.com", "password": _PW})
+    ).status_code == 200
+
+    def read_then_another_save(request: Request, session: Session = Depends(get_db)) -> User:
+        # The account as this request reads it, then a second save committing in the meantime.
+        caller = current_user(request, session)
+        with SessionLocal() as other:
+            other.execute(
+                update(User)
+                .where(User.id == caller.id)
+                .values(preferences={"seenVersion": "1.2.3"})
+            )
+            other.commit()
+        return caller
+
+    override_dep(current_user, read_then_another_save)
+    r = client.put("/api/me/preferences", json={"startOnHome": False})
+
+    assert r.status_code == 200
+    db.expire_all()
+    assert db.get(User, user.id).preferences == {"seenVersion": "1.2.3", "startOnHome": False}
+
+
+def test_the_merge_reads_the_account_under_a_lock_that_orders_merges_and_nothing_else(
+    client, make_user
+):
+    # The re-read above is half of it: two merges that both read before either commits would still
+    # keep only the last, unless the read takes a lock the other merge waits for. FOR NO KEY UPDATE
+    # is that lock, and the weakest one: a plain FOR UPDATE would also wait behind any transaction
+    # that only added a row referring to the account (a playlist pull, then minutes of YouTube).
+    make_user(email="prefs-lock@example.com", password=_PW)
+    assert (
+        client.post(
+            "/auth/password-login", json={"email": "prefs-lock@example.com", "password": _PW}
+        )
+    ).status_code == 200
+    sent: list[str] = []
+
+    def record(_conn, _cursor, statement, *_rest):
+        sent.append(statement)
+
+    event.listen(Engine, "before_cursor_execute", record)
+    try:
+        assert client.put("/api/me/preferences", json={"startOnHome": False}).status_code == 200
+    finally:
+        event.remove(Engine, "before_cursor_execute", record)
+
+    locks = [s for s in sent if "FROM users" in s and " FOR " in s]
+    assert locks, sent
+    assert all(s.rstrip().endswith("FOR NO KEY UPDATE") for s in locks), locks

backend/tests/test_migration_0112.py

@@ -0,0 +1,90 @@
+"""Migration 0112's data step, DB-lane: a user who already has two Watch later lists keeps the oldest,
+with the other's videos moved in after its own (one it already held is not added twice) and a Home
+pin of the other moved onto it, and the one-per-user index then refuses a second list.
+
+The schema half is checked by test_migrations.py; a video or a pin lost on the way is invisible there.
+"""
+
+from datetime import datetime, timezone
+
+import pytest
+from alembic import command
+from alembic.config import Config
+from sqlalchemy import text
+from sqlalchemy.exc import IntegrityError
+
+from app.catalog.models import Channel, Video
+from app.db import engine
+
+
+def _lists(conn, user_id: int, n: int) -> list[int]:
+    values = ", ".join(f"(:u, 'Watch later', 'watch_later', {i})" for i in range(n))
+    return list(
+        conn.execute(
+            text(
+                f"INSERT INTO playlists (user_id, name, kind, position) VALUES {values} RETURNING id"
+            ),
+            {"u": user_id},
+        ).scalars()
+    )
+
+
+def _pin(conn, user_id: int, playlist_id: int, position: int) -> None:
+    conn.execute(
+        text("INSERT INTO comfort_pins (user_id, playlist_id, position) VALUES (:u, :p, :pos)"),
+        {"u": user_id, "p": playlist_id, "pos": position},
+    )
+
+
+def test_a_second_watch_later_is_folded_into_the_first(db, make_user):
+    user, other = make_user(), make_user()
+    db.add(Channel(id="UCm", title="M"))
+    now = datetime.now(timezone.utc)
+    for v in ("v1", "v2", "v3"):
+        db.add(Video(id=v, channel_id="UCm", published_at=now, duration_seconds=60))
+    db.commit()
+    cfg = Config("alembic.ini")
+    command.downgrade(cfg, "0111_audit_request_id")
+    try:
+        with engine.begin() as conn:
+            first, second, third = _lists(conn, user.id, 3)
+            theirs, their_second = _lists(conn, other.id, 2)
+            conn.execute(
+                text(
+                    "INSERT INTO playlist_items (playlist_id, video_id, position) VALUES"
+                    " (:a, 'v1', 0), (:b, 'v2', 0), (:b, 'v1', 1), (:c, 'v3', 0)"
+                ),
+                {"a": first, "b": second, "c": theirs},
+            )
+            # The user pinned two of the copies, the kept one neither: the first on the shelf moves.
+            _pin(conn, user.id, third, 0)
+            _pin(conn, user.id, second, 1)
+            # The other pinned both: the kept one's pin stays, and is the only one.
+            _pin(conn, other.id, their_second, 0)
+            _pin(conn, other.id, theirs, 1)
+    finally:
+        command.upgrade(cfg, "head")
+
+    with engine.connect() as conn:
+        lists = conn.execute(
+            text("SELECT id, user_id FROM playlists WHERE kind = 'watch_later' ORDER BY id")
+        ).all()
+        assert [tuple(r) for r in lists] == [(first, user.id), (theirs, other.id)]
+        items = conn.execute(
+            text(
+                "SELECT playlist_id, video_id, position FROM playlist_items ORDER BY playlist_id, position"
+            )
+        ).all()
+        assert [tuple(r) for r in items] == [(first, "v1", 0), (first, "v2", 1), (theirs, "v3", 0)]
+        pins = conn.execute(
+            text("SELECT user_id, playlist_id, position FROM comfort_pins ORDER BY user_id")
+        ).all()
+        assert [tuple(r) for r in pins] == [(user.id, first, 0), (other.id, theirs, 1)]
+    with pytest.raises(IntegrityError), engine.begin() as conn:
+        conn.execute(
+            text(
+                "INSERT INTO playlists (user_id, name, kind, position)"
+                " VALUES (:u, 'Watch later', 'watch_later', 2)"
+            ),
+            {"u": user.id},
+        )

backend/tests/test_override_dep_convention.py

@@ -82,3 +82,42 @@ def test_a_request_that_raises_leaves_nothing_it_did_not_commit(db):
         request.throw(RuntimeError("the handler failed"))
     assert db.scalar(select(User).where(User.email == "rolled-back-probe@example.com")) is None
     assert db.info["unfinished"] == []  # a failing request is rolled back, not reported
+
+
+def test_the_commit_check_sees_a_core_dml_write(db, make_user):
+    """`db.execute(update(...))` flushes nothing and stages nothing, so the session's own bookkeeping
+    never sees it: a handler whose only write is Core DML and that forgot its commit passed. The
+    database's transaction id is what tells — also when the test itself had a write open before the
+    request, which the handler's write would otherwise share. A committed one must still pass."""
+    import pytest
+    from sqlalchemy import update
+    from starlette.requests import HTTPConnection
+
+    from app.models import User
+
+    user = make_user()
+
+    def drive(commit: bool, *, test_wrote: bool = False) -> None:
+        if test_wrote:  # the test's own write, open and uncommitted, as the request starts
+            db.execute(update(User).where(User.id == user.id).values(display_name="test"))
+        conn = HTTPConnection(
+            {"type": "http", "method": "POST", "path": "/probe", "headers": [], "query_string": b""}
+        )
+        request = db.info["request"](conn)
+        session = next(request)
+        session.execute(update(User).where(User.id == user.id).values(display_name="dml"))
+        if commit:
+            session.commit()
+        with pytest.raises(StopIteration):
+            next(request)
+
+    drive(commit=True)
+    assert db.info["unfinished"] == []
+    drive(commit=False)
+    assert db.info["unfinished"] == ["POST /probe"]
+    db.info["unfinished"].clear()  # recorded as it should be — not this test's failure
+    drive(commit=True, test_wrote=True)
+    assert db.info["unfinished"] == []
+    drive(commit=False, test_wrote=True)
+    assert db.info["unfinished"] == ["POST /probe"]
+    db.info["unfinished"].clear()

backend/tests/test_owner_scoping.py

@@ -0,0 +1,248 @@
+"""The core's owner filters, each held by a second account whose rows must not count, show or change.
+
+Every one of these reads or writes a user-owned table through `userscope.owned_by`; the fence holds
+the form (no inline `Model.user_id == …`), these hold that the filter is there at all. Each test gives
+a second account the same kind of rows, so a filter that went missing answers with theirs. DB lane.
+"""
+
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import func, select
+
+from app import debugsession, notifications, quota
+from app.catalog.models import Channel, Video
+from app.downloads.models import DownloadJob, DownloadProfile
+from app.models import DebugScreenshot, DebugSession, Notification, QuotaEvent
+from app.reader.models import Playlist, PlaylistItem, VideoState
+from app.routes import tokens as tokens_routes
+from app.routes.auth import RESET_TTL, _issue_token
+
+
+def _notify(db, user, n=1, *, read=False):
+    for i in range(n):
+        db.add(Notification(user_id=user.id, type="t", title=f"n{i}", read=read))
+    db.commit()
+
+
+def _visible(db, user) -> int:
+    return db.scalar(
+        select(func.count())
+        .select_from(Notification)
+        .where(Notification.user_id == user.id, Notification.dismissed.is_(False))
+    )
+
+
+def test_the_notification_list_shows_only_mine(db, make_user, as_user):
+    me, other = make_user(), make_user()
+    _notify(db, me)
+    _notify(db, other, 2)
+    body = as_user(me).get("/api/me/notifications").json()
+    assert (body["total"], len(body["items"])) == (1, 1)
+
+
+def test_the_unread_count_counts_only_mine(db, make_user, as_user):
+    me, other = make_user(), make_user()
+    _notify(db, me)
+    _notify(db, other, 2)
+    assert as_user(me).get("/api/me/notifications/unread_count").json() == {"count": 1}
+
+
+def test_reading_all_reads_only_mine(db, make_user, as_user):
+    me, other = make_user(), make_user()
+    _notify(db, me)
+    _notify(db, other, 2)
+    assert as_user(me).post("/api/me/notifications/read_all").status_code == 200
+    assert as_user(other).get("/api/me/notifications/unread_count").json() == {"count": 2}
+
+
+def test_clearing_all_dismisses_only_mine(db, make_user, as_user):
+    me, other = make_user(), make_user()
+    _notify(db, me)
+    _notify(db, other, 2)
+    assert as_user(me).post("/api/me/notifications/clear").status_code == 200
+    db.expire_all()
+    assert (_visible(db, me), _visible(db, other)) == (0, 2)
+
+
+def test_trimming_read_notifications_trims_only_mine(db, make_user):
+    me, other = make_user(), make_user()
+    _notify(db, me, 3, read=True)
+    _notify(db, other, 3, read=True)
+    assert notifications.trim_read(db, me.id, cap=1) == 2
+    db.commit()
+    assert _visible(db, other) == 3
+
+
+def test_todays_actions_count_only_mine(db, make_user):
+    me, other = make_user(), make_user()
+    quota.log_action(me.id, quota.QuotaAction.VIDEOS_SEARCH)
+    quota.log_action(other.id, quota.QuotaAction.VIDEOS_SEARCH)
+    quota.log_action(other.id, quota.QuotaAction.VIDEOS_SEARCH)
+    assert quota.actions_today(db, me.id, quota.QuotaAction.VIDEOS_SEARCH) == 1
+
+
+def test_my_usage_sums_only_mine(db, make_user, as_user):
+    me, other = make_user(), make_user()
+    db.add_all(
+        [
+            QuotaEvent(user_id=me.id, action="videos.list", units=5),
+            QuotaEvent(user_id=other.id, action="videos.list", units=7),
+        ]
+    )
+    db.commit()
+    body = as_user(me).get("/api/quota/my-usage").json()
+    assert (body["today"], body["all_time"], body["by_action"]) == (5, 5, {"videos.list": 5})
+
+
+def test_the_token_ceiling_counts_only_mine(db, make_user, as_user, monkeypatch):
+    monkeypatch.setattr(tokens_routes, "MAX_TOKENS", 1)
+    me, other = make_user(), make_user()
+    first = as_user(other).post("/api/tokens", json={"name": "theirs", "preset": "hub"})
+    assert first.status_code == 200, first.text
+    r = as_user(me).post("/api/tokens", json={"name": "mine", "preset": "hub"})
+    assert r.status_code == 200, r.text
+
+
+def test_a_reset_burns_only_my_other_links(client, db, make_user):
+    me, other = make_user(), make_user()
+    mine = _issue_token(db, me, "reset", RESET_TTL)
+    theirs = _issue_token(db, other, "reset", RESET_TTL)
+    db.commit()
+    r = client.post(
+        "/auth/password-reset/confirm", json={"token": mine, "password": "a brand new passphrase"}
+    )
+    assert r.json() == {"ok": True}
+    assert client.post("/auth/password-reset/check", json={"token": theirs}).json() == {"ok": True}
+
+
+def test_screenshot_storage_counts_only_mine(db, make_user):
+    me, other = make_user(), make_user()
+    now = datetime.now(timezone.utc)
+    for i, (user, size) in enumerate([(me, 10), (other, 1000)]):
+        db.add(
+            DebugSession(
+                id=f"s{i}",
+                user_id=user.id,
+                level="DEBUG",
+                started_at=now,
+                until=now + timedelta(hours=1),
+            )
+        )
+        db.flush()
+        db.add(
+            DebugScreenshot(
+                session_id=f"s{i}", created_at=now, mime="image/png", size=size, data=b"x" * size
+            )
+        )
+    db.commit()
+    assert debugsession.stored_screenshot_bytes(db, me.id) == 10
+
+
+# --- the units' owner filters, through their routes --------------------------------------------
+# The same rule one layer up: a second account acting on the SAME video, list or profile id must
+# reach only its own row. Each test holds the first account's row unchanged afterwards.
+
+
+def _videos(db, *ids):
+    db.add(Channel(id="UCo", title="O"))
+    db.flush()
+    for vid in ids:
+        db.add(
+            Video(
+                id=vid,
+                channel_id="UCo",
+                published_at=datetime.now(timezone.utc),
+                duration_seconds=3600,
+            )
+        )
+    db.commit()
+
+
+def _video_state(db, user, vid="v1"):
+    db.expire_all()
+    row = db.execute(
+        select(VideoState).where(VideoState.user_id == user.id, VideoState.video_id == vid)
+    ).scalar_one_or_none()
+    return None if row is None else (row.status, row.position_seconds)
+
+
+def test_unmarking_a_video_leaves_another_users_state(db, make_user, as_user):
+    me, other = make_user(), make_user()
+    _videos(db, "v1")
+    db.add(VideoState(user_id=other.id, video_id="v1", status="watched"))
+    db.commit()
+    r = as_user(me).post("/api/videos/v1/state", json={"status": "new"})
+    assert r.status_code == 200, r.text
+    assert _video_state(db, other) == ("watched", 0)
+
+
+def test_clearing_a_video_leaves_another_users_state(db, make_user, as_user):
+    me, other = make_user(), make_user()
+    _videos(db, "v1")
+    db.add(VideoState(user_id=other.id, video_id="v1", status="hidden", position_seconds=90))
+    db.commit()
+    assert as_user(me).delete("/api/videos/v1/state").status_code == 200
+    assert _video_state(db, other) == ("hidden", 90)
+
+
+def test_a_resume_point_is_set_and_cleared_on_my_own_row_only(db, make_user, as_user):
+    me, other = make_user(), make_user()
+    _videos(db, "v1")
+    db.add(VideoState(user_id=other.id, video_id="v1", status="hidden", position_seconds=90))
+    db.commit()
+    client = as_user(me)
+    body = {"position_seconds": 600, "duration_seconds": 3600}
+    assert client.post("/api/videos/v1/progress", json=body).status_code == 200
+    assert (_video_state(db, me), _video_state(db, other)) == (("new", 600), ("hidden", 90))
+    body = {"position_seconds": 0, "duration_seconds": 3600}
+    assert client.post("/api/videos/v1/progress", json=body).status_code == 200
+    assert (_video_state(db, me), _video_state(db, other)) == (None, ("hidden", 90))
+
+
+def _watch_later_ids(db, user):
+    db.expire_all()
+    return sorted(
+        db.execute(
+            select(PlaylistItem.video_id)
+            .join(Playlist, Playlist.id == PlaylistItem.playlist_id)
+            .where(Playlist.user_id == user.id, Playlist.kind == "watch_later")
+        ).scalars()
+    )
+
+
+def test_watch_later_adds_and_removes_use_my_own_list(db, make_user, as_user):
+    me, other = make_user(), make_user()
+    _videos(db, "v1", "v2")
+    theirs = as_user(other).post("/api/playlists/watch-later", json={"video_id": "v1"}).json()
+    client = as_user(me)
+    mine = client.post("/api/playlists/watch-later", json={"video_id": "v2"}).json()
+    assert mine["playlist_id"] != theirs["playlist_id"]
+    # Their saved video is not on my list, so removing it from mine leaves theirs alone.
+    assert client.delete("/api/playlists/watch-later/v1").status_code == 200
+    assert (_watch_later_ids(db, me), _watch_later_ids(db, other)) == (["v2"], ["v1"])
+
+
+def test_another_users_private_profile_is_refused_like_a_missing_one(db, make_user, as_user):
+    me, other = make_user(), make_user()
+    theirs = DownloadProfile(user_id=other.id, name="Theirs", spec={"format": "best"})
+    builtin = DownloadProfile(user_id=None, name="Best", spec={"format": "best"}, is_builtin=True)
+    db.add_all([theirs, builtin])
+    db.commit()
+    client = as_user(me)
+
+    def enqueue(profile_id):
+        return client.post(
+            "/api/downloads", json={"source": "dQw4w9WgXcQ", "profile_id": profile_id}
+        )
+
+    missing = enqueue(theirs.id + builtin.id + 1)
+    refused = enqueue(theirs.id)
+    assert (refused.status_code, refused.json()) == (404, missing.json())
+    assert refused.json()["detail"] == {"code": "not_found", "reason": "profile"}
+    db.expire_all()
+    assert db.execute(select(DownloadJob)).first() is None
+    # A built-in is everyone's to use.
+    r = enqueue(builtin.id)
+    assert r.status_code == 200, r.text
+    db.expire_all()
+    assert db.execute(select(DownloadJob.profile_id)).scalars().all() == [builtin.id]

backend/tests/test_plex_image_sizes.py

@@ -48,7 +48,7 @@ def _setup(db, make_user, monkeypatch, tmp_path) -> TestClient:
     )
     db.commit()
     monkeypatch.setattr(app_state, "_configured_cache", True)
-    monkeypatch.setattr(playback, "resolved_user_id", lambda request: (user.id, True))
+    monkeypatch.setattr(playback, "session_user_id", lambda request: user.id)
     monkeypatch.setattr(playback, "PlexClient", _FakePlex)
     monkeypatch.setattr(imgcache, "CACHE_DIR", tmp_path)
     _FakePlex.calls = []

backend/tests/test_plex_service.py

@@ -12,7 +12,7 @@ from datetime import datetime, timezone
 
 from sqlalchemy import select
 
-from app.plex import library, queries, service
+from app.plex import library, queries, rollup, service
 from app.plex.models import PlexCollection, PlexItem, PlexLibrary, PlexShow, PlexState
 from app.plex.query import LibraryFilters
 
@@ -71,9 +71,9 @@ def test_a_users_watch_state_is_theirs_alone(db, make_user):
     _state(db, owner, it, status="watched")
     assert queries.state(db, owner, it.id).status == "watched"
     assert queries.state(db, stranger, it.id) is None
-    assert queries.states(db, stranger, [it.id]) == {}
-    assert set(queries.states(db, owner, [it.id])) == {it.id}
-    assert queries.states(db, owner, []) == {}
+    assert rollup.item_state_map(db, stranger, [it.id]) == {}
+    assert set(rollup.item_state_map(db, owner, [it.id])) == {it.id}
+    assert rollup.item_state_map(db, owner, []) == {}
 
 
 def test_the_grid_shows_the_callers_state_and_hides_only_what_they_hid(db, make_user):
@@ -421,3 +421,32 @@ def test_only_the_owners_own_link_pushes_their_watch_state(db, make_user):
     db.commit()
     assert watch_sync.link_for_push(db, owner.id).id == link.id
     assert watch_sync.link_for_push(db, other.id) is None
+
+
+def test_a_first_write_that_lost_the_race_updates_the_winners_row(db, make_user):
+    """The first checkpoint of an item and the `final` flush beside it both read "no state"; the one
+    that writes second must land on the row the first made, not fail on `uq_plex_user_item`."""
+    user = make_user()
+    it = _movie(db, _lib(db), "m-race")
+    _state(db, user, it, position_seconds=10)  # the request that won, committed
+    st = service.checkpoint(db, user, it.id, None, 42, NOW, dirty=True)  # read "none" before it
+    assert (st.position_seconds, st.synced_to_plex) == (42, False)
+    st = service.set_status(db, user, it.id, None, "hidden")
+    assert st.status == "hidden"
+    db.commit()
+    rows = db.scalars(select(PlexState).where(PlexState.item_id == it.id)).all()
+    assert [(r.position_seconds, r.status) for r in rows] == [(42, "hidden")]
+
+
+def test_a_season_marked_beside_a_first_checkpoint_updates_its_row(db, make_user, monkeypatch):
+    """Marking a season reads every episode's state once; a first checkpoint that made one row since
+    must be updated, not collided with on `uq_plex_user_item`."""
+    user = make_user()
+    lib = _lib(db)
+    ep = _movie(db, lib, "e-race")
+    _state(db, user, ep, position_seconds=10)  # the checkpoint that won, committed
+    monkeypatch.setattr(rollup, "item_state_map", lambda *a, **k: {})  # read before it committed
+    service.bulk_state(db, user.id, [ep], watched=True)
+    db.commit()
+    rows = db.scalars(select(PlexState).where(PlexState.item_id == ep.id)).all()
+    assert [(r.status, r.position_seconds) for r in rows] == [("watched", 0)]

backend/tests/test_plex_subtitle_auth.py

@@ -32,7 +32,7 @@ def test_a_suspended_account_cannot_drive_the_subtitle_extractor(
     monkeypatch.setattr(app_state, "_configured_cache", True)
     # A validly SIGNED cookie for that account — which is all the old gate looked at.
     for mod in (auth, playback):
-        monkeypatch.setattr(mod, "resolved_user_id", lambda request: (user.id, True))
+        monkeypatch.setattr(mod, "session_user_id", lambda request: user.id)
     monkeypatch.setattr(subtitles, "CACHE_DIR", tmp_path)
     pool = _NoPool()
     monkeypatch.setattr(subtitles, "_WIN_POOL", pool)

backend/tests/test_plex_watch_sync.py

@@ -14,6 +14,7 @@ from types import SimpleNamespace
 from sqlalchemy import select
 
 from app.models import User
+from app.plex import queries
 from app.plex.models import PlexItem, PlexLibrary, PlexState
 from app.plex.watch_sync import _pull_apply, _reconcile_inprogress_movies
 from app.routes.plex.playback import (
@@ -385,3 +386,30 @@ def test_should_push_resume_periodic_is_throttled():
     )
     # Once the window elapses, the next tick pushes again.
     assert _should_push_resume(*key, now + timedelta(seconds=_PUSH_THROTTLE_S), final=False) is True
+
+
+def test_a_pull_that_lost_the_race_keeps_the_local_change_it_met(db, monkeypatch):
+    """The pull read "no state", and a first local checkpoint made one before it wrote: that row is
+    still waiting for its push, so the pull leaves it (the dirty guard), and fails on nothing."""
+    item_id, user_id = _seed_item_and_user(db)
+    now = datetime.now(timezone.utc)
+    db.add(PlexState(user_id=user_id, item_id=item_id, position_seconds=300, synced_to_plex=False))
+    db.commit()
+    real = queries.state
+    stale = [True]
+    monkeypatch.setattr(
+        queries, "state", lambda d, u, i: None if stale and stale.pop() else real(d, u, i)
+    )
+    assert _pull_apply(db, user_id, item_id, "new", 120, plex_ts=now) is None
+    db.commit()
+    rows = db.scalars(select(PlexState).where(PlexState.item_id == item_id)).all()
+    assert [(r.position_seconds, r.synced_to_plex) for r in rows] == [(300, False)]
+
+
+def test_a_first_pull_makes_a_row_in_step_with_plex(db):
+    item_id, user_id = _seed_item_and_user(db)
+    now = datetime.now(timezone.utc)
+    assert _pull_apply(db, user_id, item_id, "new", 120, plex_ts=now) == "in_progress"
+    db.commit()
+    rows = db.scalars(select(PlexState).where(PlexState.item_id == item_id)).all()
+    assert [(r.position_seconds, r.synced_to_plex) for r in rows] == [(120, True)]

backend/tests/test_reader_service.py

@@ -308,3 +308,36 @@ def test_a_pin_is_one_per_thing_and_only_its_owners(db, make_user):
     pins.remove(db, pins.own_pin(db, user, pin.id))
     db.commit()
     assert db.execute(select(ComfortPin)).first() is None
+
+
+def test_a_watch_later_save_that_lost_the_race_uses_the_winners_list(db, make_user, monkeypatch):
+    """The first two saves at once both read "no Watch later"; the second must land in the list the
+    first made, not make one of its own."""
+    user = make_user()
+    won = service.watch_later(db, user)
+    db.commit()
+    real = queries.watch_later
+    stale = [True]  # this request's first read happened before the winner committed
+
+    def read(d, u):
+        return None if stale and stale.pop() else real(d, u)
+
+    monkeypatch.setattr(queries, "watch_later", read)
+    assert service.watch_later(db, user).id == won.id
+    db.commit()
+    assert [p.id for p in queries.playlists_for(db, user) if p.kind == "watch_later"] == [won.id]
+
+
+def test_a_first_resume_point_beside_the_watched_mark_lands_on_its_row(db, make_user, monkeypatch):
+    """The first checkpoint of a video and the end-of-playback mark both read "no row"; the
+    checkpoint that writes second must update the mark's row, not fail on `uq_user_video`."""
+    user = make_user()
+    _videos(db, "v1")
+    service.mark(db, user, "v1", "watched")  # the mark that won, committed
+    db.commit()
+    monkeypatch.setattr(queries, "video_state", lambda *a, **k: None)  # read before it committed
+    service.set_progress(db, user, "v1", 90)
+    db.commit()
+    db.expire_all()
+    rows = db.execute(select(VideoState)).scalars().all()
+    assert [(r.status, r.position_seconds) for r in rows] == [("watched", 90)]

backend/tests/test_route_commits.py

@@ -0,0 +1,383 @@
+"""Writes driven through HTTP, each read back: the handler called its unit and committed.
+
+A route's helper only flushes; the handler commits. The `db` fixture fails a test whose request left
+a write uncommitted, so every test here drives one successful write through its route and then
+reads the result back. The read-back holds that the handler called its unit; it runs in the
+request's own session, so it sees a write that was never committed — the commit is the fixture's
+to hold (a test that must see it committed reads from a session of its own). The services' own
+tests hold what each write does; these hold that the route finishes it. Nothing here reaches
+YouTube or Plex: the YouTube client is a stub and no user has a Plex link. Needs the DB.
+"""
+
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from sqlalchemy import select
+
+from app import quota
+from app.auth import require_write_scope
+from app.catalog.models import Channel, ExploredChannel, SearchFind, Subscription, Video
+from app.downloads.models import DownloadJob, DownloadProfile, DownloadShare
+from app.plex.models import PlexItem, PlexLibrary, PlexSeason, PlexShow, PlexState
+from app.db import SessionLocal
+from app.models import Notification
+from app.notifications import READ_SOFT_CAP
+from app.reader.models import SavedView, Tag, VideoState
+from app.routes import channels
+
+NOW = datetime.now(timezone.utc)
+
+
+def _video(db, vid="v1", **kw):
+    if db.get(Channel, "UCr") is None:
+        db.add(Channel(id="UCr", title="R"))
+        db.flush()
+    db.add(Video(id=vid, channel_id="UCr", published_at=NOW, duration_seconds=60, **kw))
+    db.commit()
+
+
+# --- tags ------------------------------------------------------------------------------------
+
+
+def test_a_tag_made_through_the_route_is_listed_back(db, make_user, as_user):
+    user = make_user()
+    client = as_user(user)
+    r = client.post("/api/tags", json={"name": "Science"})
+    assert r.status_code == 200, r.text
+    assert [t["name"] for t in client.get("/api/tags").json()] == ["Science"]
+
+
+def test_a_tag_renamed_through_the_route_is_listed_back(db, make_user, as_user):
+    user = make_user()
+    tag = Tag(user_id=user.id, name="Old")
+    db.add(tag)
+    db.commit()
+    client = as_user(user)
+    assert client.patch(f"/api/tags/{tag.id}", json={"name": "New"}).status_code == 200
+    assert [t["name"] for t in client.get("/api/tags").json()] == ["New"]
+
+
+def test_a_tag_deleted_through_the_route_is_gone(db, make_user, as_user):
+    user = make_user()
+    tag = Tag(user_id=user.id, name="Gone")
+    db.add(tag)
+    db.commit()
+    client = as_user(user)
+    assert client.delete(f"/api/tags/{tag.id}").json() == {"deleted": tag.id}
+    assert client.get("/api/tags").json() == []
+
+
+# --- watch state ------------------------------------------------------------------------------
+
+
+def _state(db, user, vid="v1"):
+    db.expire_all()
+    return db.execute(
+        select(VideoState).where(VideoState.user_id == user.id, VideoState.video_id == vid)
+    ).scalar_one_or_none()
+
+
+def test_a_video_marked_watched_through_the_route_stays_watched(db, make_user, as_user):
+    user = make_user()
+    _video(db)
+    r = as_user(user).post("/api/videos/v1/state", json={"status": "watched"})
+    assert r.status_code == 200, r.text
+    assert _state(db, user).status == "watched"
+
+
+def test_a_video_unmarked_through_the_route_stays_unmarked(db, make_user, as_user):
+    # "new" is its own branch of the handler, with its own commit.
+    user = make_user()
+    _video(db)
+    db.add(VideoState(user_id=user.id, video_id="v1", status="watched"))
+    db.commit()
+    r = as_user(user).post("/api/videos/v1/state", json={"status": "new"})
+    assert r.status_code == 200, r.text
+    assert _state(db, user) is None
+
+
+def test_a_video_state_cleared_through_the_route_is_gone(db, make_user, as_user):
+    user = make_user()
+    _video(db)
+    db.add(VideoState(user_id=user.id, video_id="v1", status="hidden", position_seconds=90))
+    db.commit()
+    assert as_user(user).delete("/api/videos/v1/state").status_code == 200
+    assert _state(db, user) is None
+
+
+# --- saved views ------------------------------------------------------------------------------
+
+
+def test_views_reordered_through_the_route_list_back_in_that_order(db, make_user, as_user):
+    user = make_user()
+    a = SavedView(user_id=user.id, source="feed", name="A", filters={}, position=0)
+    b = SavedView(user_id=user.id, source="feed", name="B", filters={}, position=1)
+    db.add_all([a, b])
+    db.commit()
+    client = as_user(user)
+    assert client.post("/api/saved-views/reorder", json={"ids": [b.id, a.id]}).status_code == 200
+    listed = client.get("/api/saved-views").json()
+    assert [(v["name"], v["position"]) for v in listed] == [("B", 0), ("A", 1)]
+
+
+# --- download profiles and shares -------------------------------------------------------------
+
+_SPEC = {"format": "best"}
+
+
+def _profile(db, user, name="Mine"):
+    p = DownloadProfile(user_id=user.id, name=name, spec=_SPEC, is_builtin=False, sort_order=101)
+    db.add(p)
+    db.commit()
+    return p
+
+
+def _profile_names(client):
+    return [p["name"] for p in client.get("/api/downloads/profiles").json()]
+
+
+def test_a_profile_made_through_the_route_is_listed_back(db, make_user, as_user):
+    user = make_user()
+    client = as_user(user)
+    r = client.post("/api/downloads/profiles", json={"name": "Phone", "spec": _SPEC})
+    assert r.status_code == 200, r.text
+    assert _profile_names(client) == ["Phone"]
+
+
+def test_a_profile_renamed_through_the_route_is_listed_back(db, make_user, as_user):
+    user = make_user()
+    p = _profile(db, user)
+    client = as_user(user)
+    r = client.patch(f"/api/downloads/profiles/{p.id}", json={"name": "Renamed"})
+    assert r.status_code == 200, r.text
+    assert _profile_names(client) == ["Renamed"]
+
+
+def test_a_profile_deleted_through_the_route_is_gone(db, make_user, as_user):
+    user = make_user()
+    p = _profile(db, user)
+    client = as_user(user)
+    assert client.delete(f"/api/downloads/profiles/{p.id}").json() == {"deleted": p.id}
+    assert _profile_names(client) == []
+
+
+def test_a_share_taken_back_through_the_route_is_gone(db, make_user, as_user):
+    owner, friend = make_user(), make_user()
+    job = DownloadJob(
+        user_id=owner.id, source_kind="youtube", source_ref="dQw4w9WgXcQ", profile_snapshot={}
+    )
+    db.add(job)
+    db.flush()
+    db.add(DownloadShare(job_id=job.id, from_user_id=owner.id, to_user_id=friend.id))
+    db.commit()
+    r = as_user(owner).delete(f"/api/downloads/{job.id}/share/{friend.email}")
+    assert r.json() == {"ok": True}
+    db.expire_all()
+    assert db.execute(select(DownloadShare)).first() is None
+
+
+# --- channels ---------------------------------------------------------------------------------
+
+
+class _YouTube:
+    """The YouTube client, answering every write the channel routes make."""
+
+    def __init__(self, db, user):
+        pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+    def insert_subscription(self, channel_id):
+        return "yt-sub-1"
+
+    def delete_subscription(self, sub_id):
+        return None
+
+    def get_channels(self, ids):
+        return []
+
+
+@pytest.fixture
+def youtube(monkeypatch):
+    monkeypatch.setattr(channels, "YouTubeClient", _YouTube)
+    monkeypatch.setattr(quota, "backfill_reserve_reached", lambda: False)
+
+
+def _channel(db, cid="UCc", **kw):
+    ch = Channel(id=cid, title="C", details_synced_at=NOW, **kw)
+    db.add(ch)
+    db.commit()
+    return ch
+
+
+def _subscription(db, user, cid="UCc"):
+    db.expire_all()
+    return db.execute(
+        select(Subscription).where(Subscription.user_id == user.id, Subscription.channel_id == cid)
+    ).scalar_one_or_none()
+
+
+def test_a_subscribe_through_the_route_is_recorded(db, make_user, as_user, override_dep, youtube):
+    user = make_user()
+    _channel(db)
+    client = as_user(user)
+    override_dep(require_write_scope, lambda: user)
+    assert client.post("/api/channels/UCc/subscribe").json() == {"ok": True, "subscribed": "UCc"}
+    assert _subscription(db, user).yt_subscription_id == "yt-sub-1"
+
+
+def test_an_explore_through_the_route_is_recorded(db, make_user, as_user, youtube, monkeypatch):
+    user = make_user()
+    _channel(db)
+    # The ingest pages YouTube; what the route itself records is the exploration.
+    monkeypatch.setattr(channels, "details_stale", lambda ch, now: False)
+    monkeypatch.setattr(
+        channels,
+        "explore_ingest_page",
+        lambda db, yt, ch, token: {"ingested": 0, "next_page_token": None},
+    )
+    r = as_user(user).post("/api/channels/UCc/explore")
+    assert r.status_code == 200, r.text
+    db.expire_all()
+    assert db.execute(select(ExploredChannel.user_id)).scalars().all() == [user.id]
+    assert db.get(Channel, "UCc").from_explore is True
+
+
+def test_an_unsubscribe_through_the_route_drops_the_subscription(
+    db, make_user, as_user, override_dep, youtube
+):
+    user = make_user()
+    _channel(db)
+    db.add(Subscription(user_id=user.id, channel_id="UCc", yt_subscription_id="yt-sub-1"))
+    db.commit()
+    client = as_user(user)
+    override_dep(require_write_scope, lambda: user)
+    r = client.delete("/api/channels/UCc/subscription")
+    assert r.json() == {"ok": True, "unsubscribed": "UCc"}
+    assert _subscription(db, user) is None
+
+
+def test_a_backfill_reset_through_the_route_is_kept(db, make_user, as_user, monkeypatch):
+    admin, reader = make_user(role="admin"), make_user()
+    _channel(db, backfill_done=True, backfill_cursor="page-9", recent_synced_at=NOW)
+    db.add(Subscription(user_id=reader.id, channel_id="UCc", deep_requested=False))
+    db.commit()
+    # The recent pull afterwards reaches YouTube; the reset is the route's own write.
+    monkeypatch.setattr(channels, "run_recent_backfill", lambda *a, **kw: None)
+    r = as_user(admin).post("/api/channels/UCc/reset-backfill")
+    assert r.status_code == 200, r.text
+    db.expire_all()
+    ch = db.get(Channel, "UCc")
+    assert (ch.backfill_done, ch.backfill_cursor, ch.recent_synced_at) == (False, None, None)
+    assert _subscription(db, reader).deep_requested is True
+
+
+# --- live search ------------------------------------------------------------------------------
+
+
+def test_search_results_cleared_through_the_route_are_gone(db, make_user, as_user):
+    user = make_user()
+    _video(db, "s1", via_search=True)
+    db.add(SearchFind(user_id=user.id, video_id="s1"))
+    db.commit()
+    r = as_user(user).post("/api/search/clear", json={"video_ids": ["s1"]})
+    assert r.json() == {"ok": True, "removed": 1}
+    db.expire_all()
+    assert db.get(Video, "s1") is None
+    assert db.execute(select(SearchFind)).first() is None
+
+
+# --- Plex show and season marks ---------------------------------------------------------------
+
+
+def _show(db):
+    lib = PlexLibrary(plex_key="2", title="Shows", kind="show", enabled=True)
+    db.add(lib)
+    db.flush()
+    sh = PlexShow(rating_key="sh1", library_id=lib.id, title="Show")
+    db.add(sh)
+    db.flush()
+    se = PlexSeason(rating_key="se1", show_id=sh.id, season_number=1)
+    db.add(se)
+    db.flush()
+    for n in (1, 2):
+        db.add(
+            PlexItem(
+                rating_key=f"e{n}",
+                library_id=lib.id,
+                kind="episode",
+                title=f"E{n}",
+                show_id=sh.id,
+                season_id=se.id,
+                season_number=1,
+                episode_number=n,
+            )
+        )
+    db.commit()
+
+
+def _plex_marks(db, user):
+    db.expire_all()
+    return sorted(
+        db.execute(
+            select(PlexItem.rating_key, PlexState.status)
+            .join(PlexState, PlexState.item_id == PlexItem.id)
+            .where(PlexState.user_id == user.id)
+        ).all()
+    )
+
+
+def test_a_show_marked_watched_through_the_route_stays_watched(db, make_user, as_user):
+    user = make_user()
+    _show(db)
+    r = as_user(user).post("/api/plex/show/sh1/state", json={"watched": True})
+    assert r.json() == {"ok": True, "changed": 2, "watched": True}
+    assert _plex_marks(db, user) == [("e1", "watched"), ("e2", "watched")]
+
+
+def test_a_season_marked_watched_through_the_route_stays_watched(db, make_user, as_user):
+    user = make_user()
+    _show(db)
+    r = as_user(user).post("/api/plex/season/se1/state", json={"watched": True})
+    assert r.json() == {"ok": True, "changed": 2, "watched": True}
+    assert _plex_marks(db, user) == [("e1", "watched"), ("e2", "watched")]
+
+
+def _read_past_the_cap(db, user) -> list[Notification]:
+    """READ_SOFT_CAP read notices, oldest first, and one unread notice after them."""
+    base = datetime(2024, 1, 1, tzinfo=timezone.utc)
+    rows = [
+        Notification(
+            user_id=user.id,
+            type="t",
+            title=f"n{i}",
+            read=i < READ_SOFT_CAP,
+            created_at=base + timedelta(minutes=i),
+        )
+        for i in range(READ_SOFT_CAP + 1)
+    ]
+    db.add_all(rows)
+    db.commit()
+    return rows
+
+
+def _committed_notices(user) -> tuple[int, bool]:
+    """What another session sees: how many of the user's notices are left, and whether the oldest is."""
+    with SessionLocal() as s:
+        ids = s.scalars(select(Notification.title).where(Notification.user_id == user.id)).all()
+    return len(ids), "n0" in ids
+
+
+@pytest.mark.parametrize("path", ["{id}/read", "read_all"])
+def test_reading_a_notice_past_the_cap_commits_the_trim(db, make_user, as_user, path):
+    """Marking a notice read makes READ_SOFT_CAP + 1 read ones: the handler commits the read flag and
+    the trim of the oldest together, and the trim counts the notice just read."""
+    user = make_user()
+    rows = _read_past_the_cap(db, user)
+    r = as_user(user).post("/api/me/notifications/" + path.format(id=rows[-1].id))
+    assert r.json() == {"ok": True}
+    assert _committed_notices(user) == (READ_SOFT_CAP, False)

backend/tests/test_unit_fences.py

@@ -5,17 +5,14 @@ What it may not do is build SQL, call the session's data methods, change a model
 import a unit's tables: when a route did those, ownership, the commit and the conditional `WHERE`
 lived in a different place in each handler, and a fix in one never reached its siblings.
 
-The rule is switched on unit by unit. `ALLOWED` pins what each HTTP file still does today, and the
-pin is exact: a count that rises fails (new database work in a route), and one that falls fails
-until its entry is lowered (the fence only tightens, as `baseline.json` does for basedpyright). An
-empty `ALLOWED` is the end state — a file listed there is a debt, not an exemption.
+The rule has no exemptions: a single `select()` in a unit's route file fails it.
 
 A core route (identity, admin, ops) is not a unit's HTTP layer and may use the session; it may
 still not reach into a unit's tables. A route may NAME a unit's model as a type (under
 `TYPE_CHECKING`), never use one as a value.
 
-Below the HTTP layer, a fenced unit's own code keeps to its edges (`FENCED`, `READS`): see the
-second half of this file.
+Below the HTTP layer, a unit's own code keeps to its edges (`READS`): see the second half of this
+file. Whose a row is, every module says through `userscope` — a core one too.
 """
 
 import ast
@@ -107,10 +104,6 @@ UNIT_ROUTES = {
     "plex/": "plex",
 }
 
-# What each HTTP file still does, by file: the debt a unit's sprint pays off. Exact counts. A core
-# route's count is only the unit tables it imports; it is paid by the sprint of the unit it reaches.
-ALLOWED: dict[str, int] = {}
-
 # The session methods that read or write data. `commit` and `rollback` stay with the handler.
 SESSION_DATA = {
     "add",
@@ -257,19 +250,13 @@ def test_every_listed_route_exists():
     rels = [rel for rel, _ in _http_files()]
     for key in UNIT_ROUTES:
         assert any(rel == key or (key.endswith("/") and rel.startswith(key)) for rel in rels), key
-    assert set(ALLOWED) <= set(rels), set(ALLOWED) - set(rels)
 
 
-def test_no_http_file_does_database_work_beyond_its_pin():
-    drift = {}
-    for rel, src in _http_files():
-        found = violations(src, _unit_of(rel))
-        pinned = ALLOWED.get(rel, 0)
-        if len(found) != pinned:
-            drift[rel] = (pinned, len(found), found if len(found) > pinned else "lower its pin")
-    assert drift == {}, (
-        "an HTTP file's database work moved off its pin (pinned, now, what): move new work into"
-        " the unit's queries/service; when a count fell, lower ALLOWED to it"
+def test_no_http_file_does_database_work():
+    hits = {rel: found for rel, src in _http_files() if (found := violations(src, _unit_of(rel)))}
+    assert hits == {}, (
+        "a route does database work: reads go through the unit's queries, writes through its"
+        " service; a core route reaches a unit's tables through that unit's queries too"
     )
 
 
@@ -307,11 +294,11 @@ def test_the_detector_sees_each_kind_of_database_work():
 
 
 # --- inside a unit: its package --------------------------------------------------------------
-# A unit whose sprint has landed is fenced beyond its HTTP layer too. Its own code reads another
-# unit's tables only along a declared edge (the feed joins Video with VideoState in one query; a
-# boundary that split it would cost the speed the app is for), and writes another unit's tables
-# never — that goes through the owner's service. Whose a row is, it says through `userscope`, and
-# it commits only where a job owns its session.
+# Every unit is fenced beyond its HTTP layer too. Its own code reads another unit's tables only
+# along a declared edge (the feed joins Video with VideoState in one query; a boundary that split
+# it would cost the speed the app is for), and writes another unit's tables never — that goes
+# through the owner's service. It commits only where a job owns its session. Whose a row is, it
+# says through `userscope`, and so does core code: the owner filter is checked in every module.
 
 # Each unit's code outside the HTTP layer: its package, and the entry point that runs its jobs.
 UNIT_PACKAGES = {
@@ -341,9 +328,7 @@ UNIT_PACKAGES = {
     # pages' reads and writes.
     "plex": ("plex/",),
 }
-# The units fenced so far; the rest join with their sprint.
-FENCED = {"capture", "reader", "catalog", "plex"}
-# Whose tables a unit's own code may READ. Core code reads a fenced unit's tables through its queries.
+# Whose tables a unit's own code may READ. Core code reads a unit's tables through its queries.
 READS = {
     "capture": {"catalog", "plex"},
     "reader": {"catalog", "plex"},
@@ -352,7 +337,7 @@ READS = {
 }
 # The columns that say whose a row is.
 OWNER_COLUMNS = {"user_id", "to_user_id", "from_user_id", "created_by"}
-# Where a fenced unit's code may commit: the jobs that own their session (the worker and what it
+# Where a unit's code may commit: the jobs that own their session (the worker and what it
 # runs, the GC, the backfill — none of them inside a request), and the one write that must commit
 # where it stands: an upload's rows and the file it placed on disk land together or not at all, so
 # a failed commit can remove the file (`upload.ingest_upload`). Everything else flushes; the handler
@@ -423,7 +408,38 @@ UNIT_COMMITS = {
         "plex/watch_sync.py:run_plex_watch_reconcile",
     },
 }
+# Where core code may commit, each with why. Everything else in core flushes and leaves the commit
+# to its caller, as a unit's code does; a route's own helpers are held by test_route_conventions.
+CORE_COMMITS = {
+    # Quota spend and a background run's row are durable whatever the caller does next: each opens
+    # a session of its own.
+    "quota.py",
+    "jobruns.py",
+    # The scheduler's jobs own their session.
+    "scheduler.py",
+    # The instance's one settings row: created on first read, and the setup steps that finish it.
+    "state.py",
+    # A token's last-used stamp lands ahead of the route: a read-only route never commits, and a
+    # write route's rollback must not take it along. The expiry warning is a scheduled job.
+    "apitokens.py:_token_caller",
+    "apitokens.py:warn_expiring",
+    # An account's erasure is one operation shared by the self-service and the admin delete; the
+    # Google revoke and the confirmation run after it, in the background.
+    "auth.py:purge_user",
+    # The undelivered-email notice opens its own session (its callers are often background tasks).
+    "email.py:_alert_admins",
+    # One notice, committed unless its caller batches (`commit=False`).
+    "notifications.py:create_notification",
+    # A refreshed (or dead) YouTube grant must persist even when the call that needed it fails and
+    # its caller rolls back.
+    "youtube/client.py:_access_token",
+    "youtube/client.py:_drop_dead_grant",
+}
 SQL_WRITES = {"insert", "update", "delete", "pg_insert"}
+ALL_MODEL_NAMES = set(UNIT_MODEL_NAMES) | CORE_MODELS
+# The column methods that compare an owner column as a filter does (`Model.user_id.in_(ids)`).
+# `.is_(None)` is not one: it asks for the rows nobody owns (the system's own tags).
+OWNER_METHODS = {"in_", "not_in", "notin_", "__eq__", "__ne__"}
 
 
 def _package_unit(rel: str) -> str | None:
@@ -455,6 +471,64 @@ def _imported_models(tree: ast.AST) -> dict[str, str]:
     return out
 
 
+def _model_aliases(tree: ast.AST) -> dict[str, str]:
+    """Every other name a module binds to a model, by that name: an import under another name, and
+    `x = aliased(Model)` — an alias is the same table, and its owner column the same filter."""
+    out = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and "models" in (node.module or ""):
+            for alias in node.names:
+                if alias.name in ALL_MODEL_NAMES:
+                    out[alias.asname or alias.name] = alias.name
+    for node in ast.walk(tree):
+        if (
+            isinstance(node, ast.Assign)
+            and isinstance(node.value, ast.Call)
+            and _called_name(node.value) == "aliased"
+            and node.value.args
+            and isinstance(node.value.args[0], ast.Name)
+        ):
+            source = node.value.args[0].id
+            model = out.get(source, source if source in ALL_MODEL_NAMES else None)
+            for target in node.targets:
+                if model and isinstance(target, ast.Name):
+                    out[target.id] = model
+    return out
+
+
+def _called_name(call: ast.Call) -> str | None:
+    func = call.func
+    return func.id if isinstance(func, ast.Name) else getattr(func, "attr", None)
+
+
+def _sql_write_names(tree: ast.AST) -> tuple[set[str], set[str]]:
+    """The names a module calls SQLAlchemy's statement writes by — `insert`/`update`/`delete` as
+    imported, under any alias — and the names it binds SQLAlchemy's modules to (`sa.update(...)`)."""
+    functions, modules = set(SQL_WRITES), set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and (node.module or "").split(".")[0] == "sqlalchemy":
+            for alias in node.names:
+                if alias.name in {"insert", "update", "delete"}:
+                    functions.add(alias.asname or alias.name)
+                elif alias.name in {"dialects", "postgresql", "sql"}:
+                    modules.add(alias.asname or alias.name)
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name.split(".")[0] == "sqlalchemy":
+                    modules.add(alias.asname or alias.name.split(".")[0])
+    return functions, modules
+
+
+def _written_table(call: ast.Call) -> str | None:
+    """The name of what a statement write's first argument names: `Model`, or `Model.__table__`."""
+    if not call.args:
+        return None
+    arg = call.args[0]
+    if isinstance(arg, ast.Attribute) and arg.attr == "__table__":
+        arg = arg.value
+    return arg.id if isinstance(arg, ast.Name) else None
+
+
 def _enclosing_functions(tree: ast.AST) -> dict[ast.AST, str]:
     out = {}
     for fn in ast.walk(tree):
@@ -465,64 +539,82 @@ def _enclosing_functions(tree: ast.AST) -> dict[ast.AST, str]:
 
 
 def package_violations(rel: str, source: str) -> list[str]:
-    """What a module outside the HTTP layer does against a fenced unit's boundary, as `line: what`."""
+    """What a module outside the HTTP layer does against a unit's boundary, as `line: what`."""
     tree = ast.parse(source)
     mine = _package_unit(rel)
     found = []
     models = _imported_models(tree)
     for name in models.values():
         theirs = UNIT_MODEL_NAMES[name]
-        if theirs == mine or (mine not in FENCED and theirs not in FENCED):
+        if theirs == mine:
             continue
         if theirs not in READS.get(mine or "", set()):
             found.append(f"0: {mine or 'core'} imports {theirs}'s {name}")
+    write_functions, sql_modules = _sql_write_names(tree)
     for node in ast.walk(tree):
-        if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Name):
+        if not isinstance(node, ast.Call):
             continue
+        func = node.func
         written = None
-        if node.func.id in models:
-            written = models[node.func.id]
-        elif node.func.id in SQL_WRITES and node.args and isinstance(node.args[0], ast.Name):
-            written = models.get(node.args[0].id)
+        if isinstance(func, ast.Name) and func.id in models:
+            written = models[func.id]
+        elif (isinstance(func, ast.Name) and func.id in write_functions) or (
+            isinstance(func, ast.Attribute)
+            and func.attr in {"insert", "update", "delete"}
+            and isinstance(_root(func), ast.Name)
+            and _root(func).id in sql_modules
+        ):
+            written = models.get(_written_table(node) or "")
         if written is None:
             continue
         theirs = UNIT_MODEL_NAMES[written]
-        if theirs != mine and (mine in FENCED or theirs in FENCED):
+        if theirs != mine:
             found.append(f"{node.lineno}: {mine or 'core'} writes {theirs}'s {written}")
-    if mine in FENCED:
-        found += _owner_filters(tree)
-        functions = _enclosing_functions(tree)
-        allowed = UNIT_COMMITS.get(mine, set())
-        for node in ast.walk(tree):
-            if (
-                isinstance(node, ast.Call)
-                and isinstance(node.func, ast.Attribute)
-                and node.func.attr == "commit"
-                and rel not in allowed
-                and f"{rel}:{functions.get(node)}" not in allowed
-            ):
-                found.append(f"{node.lineno}: commits in {functions.get(node)}")
+    found += _owner_filters(tree)
+    functions = _enclosing_functions(tree)
+    allowed = UNIT_COMMITS.get(mine, set()) if mine is not None else CORE_COMMITS
+    for node in ast.walk(tree):
+        if (
+            isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and node.func.attr == "commit"
+            and rel not in allowed
+            and f"{rel}:{functions.get(node)}" not in allowed
+        ):
+            found.append(f"{node.lineno}: commits in {functions.get(node)}")
     return sorted(found, key=lambda v: int(v.split(":")[0]))
 
 
 def _owner_filters(tree: ast.AST) -> list[str]:
     """A comparison on a table's owner column written inline (`Model.user_id == …`), not through
     `userscope.owned_by`."""
+    names = {name: name for name in ALL_MODEL_NAMES} | _model_aliases(tree)
+
+    def owner_column(node: ast.expr) -> bool:
+        return (
+            isinstance(node, ast.Attribute)
+            and isinstance(node.value, ast.Name)
+            and node.value.id in names
+            and node.attr in OWNER_COLUMNS
+        )
+
     found = []
     for node in ast.walk(tree):
         if isinstance(node, ast.Compare):
             for side in (node.left, *node.comparators):
-                if (
-                    isinstance(side, ast.Attribute)
-                    and isinstance(side.value, ast.Name)
-                    and side.value.id in set(UNIT_MODEL_NAMES) | CORE_MODELS
-                    and side.attr in OWNER_COLUMNS
-                ):
+                if owner_column(side):
                     found.append(f"{node.lineno}: filters {side.value.id}.{side.attr} inline")
+        elif isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+            if node.func.attr in OWNER_METHODS and owner_column(node.func.value):
+                found.append(f"{node.lineno}: filters an owner column with {node.func.attr}")
+            elif node.func.attr == "filter_by" and any(
+                k.arg in OWNER_COLUMNS for k in node.keywords
+            ):
+                found.append(f"{node.lineno}: filters an owner column with filter_by")
     return found
 
 
-def test_a_fenced_units_code_keeps_to_its_edges():
+def test_a_units_code_keeps_to_its_edges():
     hits = {rel: found for rel, src in _app_files() if (found := package_violations(rel, src))}
     assert hits == {}, (
         "read another unit's tables only along READS, write them only through their service, say"
@@ -530,12 +622,8 @@ def test_a_fenced_units_code_keeps_to_its_edges():
     )
 
 
-def test_a_fenced_units_routes_filter_owners_through_userscope():
-    hits = {
-        rel: found
-        for rel, src in _http_files()
-        if _unit_of(rel) in FENCED and (found := _owner_filters(ast.parse(src)))
-    }
+def test_every_route_filters_owners_through_userscope():
+    hits = {rel: found for rel, src in _http_files() if (found := _owner_filters(ast.parse(src)))}
     assert hits == {}
 
 
@@ -543,11 +631,32 @@ def test_every_unit_package_exists():
     for prefixes in UNIT_PACKAGES.values():
         for p in prefixes:
             assert (APP / p).exists(), p
-    for commits in UNIT_COMMITS.values():
+    for commits in (*UNIT_COMMITS.values(), CORE_COMMITS):
         for entry in commits:
             assert (APP / entry.split(":")[0]).exists(), entry
 
 
+def test_every_listed_commit_is_still_there():
+    """An entry names a commit that exists: one left behind by a rename, or by a function that no
+    longer commits, would go on allowing a commit to whatever takes its name next."""
+    stale = []
+    for commits in (*UNIT_COMMITS.values(), CORE_COMMITS):
+        for entry in commits:
+            rel, _, name = entry.partition(":")
+            tree = ast.parse((APP / rel).read_text(encoding="utf-8"))
+            functions = _enclosing_functions(tree)
+            committing = {
+                functions.get(node)
+                for node in ast.walk(tree)
+                if isinstance(node, ast.Call)
+                and isinstance(node.func, ast.Attribute)
+                and node.func.attr == "commit"
+            }
+            if (name not in committing) if name else not committing:
+                stale.append(entry)
+    assert stale == []
+
+
 PACKAGE_CASES = {
     # (module path, source): violations
     ("downloads/x.py", "from app.models import Video"): 0,  # capture reads catalog
@@ -562,6 +671,23 @@ PACKAGE_CASES = {
     ("sync/videos.py", "from app.models import Playlist"): 1,  # no catalog→reader edge
     ("downloads/x.py", "q = DownloadJob.user_id == 1"): 1,
     ("downloads/x.py", "q = owned_by(DownloadJob.user_id, 1)"): 0,
+    ("quota.py", "q = QuotaEvent.user_id == 1"): 1,  # core too
+    ("downloads/x.py", "from app.downloads.models import DownloadJob as J\nq = J.user_id == 1"): 1,
+    ("downloads/x.py", "st = aliased(VideoState)\nq = st.user_id == 1"): 1,
+    ("downloads/x.py", "q = DownloadJob.user_id.in_([1])"): 1,
+    ("downloads/x.py", "q = select(DownloadJob).filter_by(user_id=1)"): 1,
+    ("downloads/x.py", "q = Tag.user_id.is_(None)"): 0,  # the rows nobody owns
+    (
+        "downloads/x.py",
+        "from sqlalchemy import update as up\nfrom app.models import Video\nup(Video)",
+    ): 1,
+    (
+        "downloads/x.py",
+        "import sqlalchemy as sa\nfrom app.models import Video\nsa.update(Video)",
+    ): 1,
+    ("downloads/x.py", "from app.models import Video\nupdate(Video.__table__)"): 1,
+    ("notifications.py", "def f(db):\n    db.commit()"): 1,  # core flushes too
+    ("state.py", "def f(db):\n    db.commit()"): 0,
     ("downloads/x.py", "def f(db):\n    db.commit()"): 1,
     ("downloads/gc.py", "def f(db):\n    db.commit()"): 0,
     ("downloads/upload.py", "def ingest_upload(db):\n    db.commit()"): 0,

docs/DESIGN.md

@@ -275,7 +275,9 @@ Also in force:
 - **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. The band
+  Built as: the band is `PageShell`'s toolbar slot (`PageToolbar`), above the one scroller; the floating
+  header over it is its header slot (`PageHeader`: the page's own pills, the palette's Jump-to pill where a
+  page has none, `PageHeaderDefault`). 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

docs/development.md

@@ -36,6 +36,32 @@ The dev server also serves the **design lab** at `http://localhost:5173/design-l
 decisions and the chosen patterns, rendered with the app's real CSS. It never reaches a production build
 (see [`DESIGN.md`](DESIGN.md)).
 
+## Adding a page
+
+A frontend page is one folder, `frontend/src/modules/<id>/` (the layering is in
+[`CLAUDE.md`](../CLAUDE.md) § Architecture shape):
+
+1. The page itself, default-exported, and anything only it uses. Header content (a search box, a toggle) the
+   page renders into the floating header itself through `PageHeader`; the shell knows no page.
+2. `module.ts`: its `ModuleDef` (`lib/moduleDef.ts`): id, label keys, icon, an optional `gate`, the page as a
+   `lazyWithPreload(() => import(…))`, and optionally a rail and a `Store`. Of its own folder it imports statically
+   only its store (a `…Provider` / `…Store` file); the page and the rail load lazily.
+3. `index.ts`, the module's public face: the definition, and only what other folders must read (its store's
+   hooks). Another folder reaches the module through this file or not at all.
+4. The id in `lib/urlState`'s `PAGES`, and the definition in `features/navigation/moduleRegistry.ts`, in
+   nav-rail order. The rail, the palette, the `g` chords, the tab title and the root's stores all read from there.
+5. Its strings in both locales (`src/i18n/locales`).
+6. A page with a side rail also names its panel below the module, in `lib/` (rails share one layout
+   and collapse machinery, which lib may not learn from a module): the `PanelId` and its default group
+   order, storage and pref keys in `lib/panelLayout.ts`, its collapse flag in `lib/useRail.ts`
+   (`COLLAPSE`), and those keys in `lib/storage.ts`. The rail calls `useRail("<id>")` and hands what it
+   returns to `ui/FilterRail`; tsc names each table still missing the new id.
+
+What holds it: `moduleRegistry.contract.test.ts` (every id defined once, from its own folder, lazily),
+`moduleStores.contract.test.tsx` (no store reads another module), the `local/layers` lint rule (imports only go
+down, a module only through its face) and `chunkGuard` in the build (no lazy page on the boot path), plus the
+i18n parity test.
+
 ## The gate
 
 A change is done when this is green, from the repo root:
@@ -105,7 +131,7 @@ npm run lint          # eslint (typed rules included; warnings fail)
 npm run format:check  # prettier
 npm run knip          # unused files/exports/deps
 npm run test          # vitest (incl. the compiler and gate-register contracts)
-npx vite build        # the production bundle (devOnlyGuard fails it on dev-only code)
+npx vite build        # the production bundle (devOnlyGuard fails it on dev-only code, chunkGuard on a lazy page loaded at boot)
 npm audit --omit=dev --audit-level=high   # what ships to the browser, at high or above
 ```
 

docs/gates.md

@@ -61,7 +61,8 @@ them itself (`no-undef`, `no-redeclare`, `no-dupe-keys`, …), nor the formattin
 | src tests · ui tests · lib tests | `local/literal-a11y-text`, `local/input-primitive`, `local/surface-role`, `local/glyph-link` — off | A test renders throwaway markup (a raw input as a focus target, an untranslated label) that is not product UI. `local/button-primitive` stays on: in a test file (and in a control primitive) it only refuses a raw `<button disabled>`, which drops focus there as anywhere. | — |
 | design-lab | `local/literal-a11y-text` — off | The dev-only design lab (never in the bundle — devOnlyGuard fails the build if it is) holds the owner's working copy, not product copy. | — |
 | e2e | `react-hooks/*`, `react-refresh/*`, `local/*`, `no-console`, `no-restricted-globals`, `no-restricted-properties`, `no-restricted-syntax` — not applied | Playwright specs drive a browser from Node: no React, no product UI, and they print to the console on purpose. They get the base + typed rules + the playwright rules. | — |
-| ts configs | `react-hooks/*`, `react-refresh/*`, `local/*`, `no-console`, `no-restricted-globals`, `no-restricted-properties`, `no-restricted-syntax` — not applied | The build configs (vite, vitest, playwright, reactPlugin, devOnlyGuard) run in Node at build time. | — |
+| ts configs · tool tests | `react-hooks/*`, `react-refresh/*`, `local/*`, `no-console`, `no-restricted-globals`, `no-restricted-properties`, `no-restricted-syntax` — not applied | The build configs (vite, vitest, playwright, reactPlugin, devOnlyGuard, chunkGuard) run in Node at build time. Their unit tests beside them (`tool tests`: `chunkGuard.test.ts`) are linted the same way, plus `vitest/no-focused-tests` and `vitest/no-disabled-tests`, since vitest runs them. | — |
+| src root tests · design-lab | `local/layers` — not applied (inside the rule: its `free` check, which the effective config cannot show) | The app-wide tests at `src/` root exercise a behaviour across modules (a write failure reported the same way in Plex and Files, the playlist editors' failures), so they render module-private components directly; the dev-only design lab shows every component. Neither ships. Every other layer, test or not, is held. | 3 imports of module-private files (`PlaylistEditFailures.dom.test.tsx` → `modules/plex/PlexPlaylistView`; `WriteFailureReporting.dom.test.tsx` → `modules/plex/PlexCollectionEditor`, `modules/files/UploadDialog`); design-lab 0 |
 | js configs | `@typescript-eslint/*`, `react-hooks/*`, `react-refresh/*`, `local/*`, `no-console`, `no-restricted-globals`, `no-restricted-properties`, `no-restricted-syntax`, `no-var`, `prefer-const`, `prefer-rest-params`, `prefer-spread`, `no-array-constructor`, `no-unused-expressions` — not applied | `eslint.config.js` and `postcss.config.js`: plain-JS build config, linted with `js.configs.recommended` only. | — |
 | repo scripts | `scripts/*.mjs` — not in the eslint or prettier lane; `js.configs.recommended` + Prettier via `src/lib/repoScripts.contract.test.ts` | They sit at the repo root, and an ESLint config cannot reach past its own directory. The contract test lints and format-checks them from the repo root, to the same bar as the `js configs` row; no typed rules, as they are in no tsc project. | 0 lint hits; 2 files reformatted (E32 review) |
 | everywhere | ignored paths: `dist`, `node_modules`, `playwright-report`, `test-results`, `e2e/.auth` | Build output, installed packages, test artefacts, a live Playwright session. Generated, not written. | — |
@@ -107,14 +108,14 @@ project checks needs a row.
 
 | Scope | Narrowed | Why | Measured |
 | --- | --- | --- | --- |
-| check | e2e (Playwright) not in `check` | It needs the :8080 stack built from the tree (minutes). It runs in `check-full`, and `release` rebuilds the stack and requires it (E32 D2) — nothing ships without it. | 5 specs × 3 engines |
+| check | e2e (Playwright) not in `check` | It needs the :8080 stack built from the tree (minutes). It runs in `check-full`, and `release` rebuilds the stack and requires it (E32 D2) — nothing ships without it. | 9 specs: 6 × 3 engines, 3 on chromium only (the row below) |
+| e2e | `a11y.spec.ts` `member.spec.ts` `devices.spec.ts` run on chromium only (`CHROMIUM_ONLY`, the webkit and ipad projects' `testIgnore`) | What they hold does not change with the engine: the axe scan reads the DOM and the accessibility tree, which the engines build alike; the member spec checks which pages and requests a role gets; the devices spec opens its own desktop and iPad contexts. Run three times they would triple their time and catch nothing more. What an engine does change (layout, events) the other specs hold on all three. | 3 of 9 specs |
 | pushes | no server-side gate (no CI) | Owner decision 2026-10-04. The gate (`scripts/check.sh`) runs on the dev machine before work is handed over, and `release` runs it, then e2e, before anything is merged and Trivy before the image is pushed — the CI only repeated that, after the merge. Its runner shared the git host's container, and one run there starved Gitea of memory until it stopped answering. What it added — a fresh `npm ci` on Linux — the image build does at publish. | — |
 | coverage | not in the gate; no threshold | Owner decision E32 D4: never enforced; "every regression test seen red" is the bar, and a percentage invites tests written to move it. Out of the lanes since E35: read once, by hand, it found 5 bugs; as a lane it was a number nobody acted on, and the slowest vitest run (the one that flaked). On demand: docs/development.md. | frontend 80% / backend 78% of lines (E32 S1) |
 | CVE gate | HIGH/CRITICAL with a fix available only | `--ignore-unfixed` + `--severity HIGH,CRITICAL`: a finding with no fix cannot be acted on by an upgrade; it shows in the scan output. A fixable one fails the publish, and the only way past it is `.trivyignore.yaml`. | 0 open (E32 S1) |
 | npm audit | `--omit=dev --audit-level=high` | What ships to the browser, at high or above. The dev toolchain's advisories were burned down by hand in E32 S1 (18 → 0). | 0 |
 | knip | `entry` — one file added | Not a narrowing: knip's Vite plugin reads entries from index.html only, so the shared link's page (`watch.html` → `src/watchMain.tsx`) is named here, or the lane reports that whole entry unused. It adds files to the lane, never takes any out. | 1 entry |
-| unit fence | the database work the HTTP layer still does, pinned | `backend/tests/test_unit_fences.py`: a unit's route file may not build SQL, call the session's data methods, set a model's attributes or import a unit's tables; a core route may not import a unit's tables. Switched on unit by unit: `ALLOWED` pins each file's count exactly, so a rise fails and a fall fails until the pin is lowered — the list may only shrink. End state: empty, and the pin mechanism goes. A unit in `FENCED` is held below its HTTP layer too: its code reads another unit's tables only along `READS`, writes them never, filters owners through `userscope`, and commits only where `UNIT_COMMITS` names a job's own session. | 826 in 23 files (E42 S0) → 667 in 19 (S1: Capture 0, fenced) → 525 in 14 (S2: Reader 0, fenced) → 354 in 9 (S3: Catalog 0, fenced; core routes 0) → 178 in 4 (S4a: Plex browse, detail, people, collections 0) → 0 (S4b: Plex 0, fenced — every unit fenced) |
-| React Compiler | the functions it skips, pinned | `components/compilerCoverage.contract.test.ts` — the list may only shrink. End state: only VirtualGrid (TanStack Virtual, an IncompatibleLibrary) remains. | 93 (E32 S1) → 29 (E32 S3) → 1, VirtualGrid (E32 S4) |
+| React Compiler | the functions it skips, pinned | `src/compilerCoverage.contract.test.ts` — the list may only shrink. End state: only VirtualGrid (TanStack Virtual, an IncompatibleLibrary) remains. | 93 (E32 S1) → 29 (E32 S3) → 1, VirtualGrid (E32 S4) |
 
 ## Accepted findings
 

docs/self-hosting.md

@@ -65,6 +65,11 @@ the server logs) can run setup. Then click through:
 
 That's it. You can change any of the optional settings later under the admin **Configuration** page.
 
+> **Set a password even if you sign in with Google** (Settings → Account → Password). If Google
+> sign-in stops working — the client secret rotated, the consent revoked, Google down — email and
+> password still let you in. An account that only ever used Google is otherwise locked out until an
+> admin creates a set-password link for it (Users).
+
 > The setup wizard only exists until you finish it. After that, the setup routes are disabled and
 > the token is invalidated — there's no setup surface left on a configured instance.
 

frontend/chunkGuard.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { bootLeaks, type ChunkLike } from "./chunkGuard";
+
+const APP = "/r/src/shell/App.tsx";
+const chunk = (fileName: string, moduleIds: string[], imports: string[] = [], isEntry = false) =>
+  ({ fileName, moduleIds, imports, isEntry }) satisfies ChunkLike;
+
+describe("a lazily imported module", () => {
+  const lazy = new Set([APP, "/r/src/modules/plex/PlexBrowse.tsx"]);
+
+  it("is a leak in the entry chunk, in a chunk the entry imports, or in the App chunk", () => {
+    const P = "/r/src/modules/plex/PlexBrowse.tsx";
+    for (const chunks of [
+      [chunk("index.js", ["/r/src/main.tsx", P], [], true)],
+      [chunk("index.js", ["/r/src/main.tsx"], ["shared.js"], true), chunk("shared.js", [P])],
+      [chunk("index.js", ["/r/src/main.tsx"], [], true), chunk("App.js", [APP, P])],
+      [
+        chunk("index.js", ["/r/src/main.tsx"], [], true),
+        chunk("App.js", [APP], ["s.js"]),
+        chunk("s.js", [P]),
+      ],
+    ])
+      expect(bootLeaks(chunks, lazy, "src/shell/App.tsx")).toEqual([
+        `${P} (${chunks[chunks.length - 1]!.fileName})`,
+      ]);
+  });
+
+  it("is not a leak in its own chunk, or in one only another lazy chunk loads — and App itself is lazy by design", () => {
+    const chunks = [
+      chunk("index.js", ["/r/src/main.tsx"], ["react.js"], true),
+      chunk("react.js", ["/r/node_modules/react/index.js"]),
+      chunk("App.js", [APP], ["react.js"]),
+      chunk("PlexBrowse.js", ["/r/src/modules/plex/PlexBrowse.tsx"], ["react.js"]),
+    ];
+    expect(bootLeaks(chunks, lazy, "src/shell/App.tsx")).toEqual([]);
+  });
+
+  it("is checked on Windows paths too", () => {
+    const win = "D:\\r\\src\\modules\\plex\\PlexBrowse.tsx";
+    const chunks = [chunk("index.js", ["D:\\r\\src\\main.tsx", win], [], true)];
+    expect(bootLeaks(chunks, new Set([win]), "src/shell/App.tsx")).toHaveLength(1);
+  });
+});

frontend/chunkGuard.ts

@@ -0,0 +1,73 @@
+import type { Plugin } from "vite";
+
+// A lazily imported page, rail, dialog or player must stay out of the chunks loaded at boot. A page
+// is imported with import()/lazy() so it is fetched only when it is opened, and Rollup honours that
+// only while nothing on the boot path imports the same module statically: one static import — a
+// module's index.ts re-exporting it is the easy way — and the module joins a boot chunk, the import()
+// becomes a no-op, and nothing says so. That rule used to be a hope; this makes it a build failure,
+// naming each module and the boot chunk it landed in. The boot path is the entry chunks and what they
+// import, plus the shell (App, itself loaded lazily but fetched at boot alongside the identity probe)
+// and what it imports.
+const SHELL = "src/shell/App.tsx";
+
+export interface ChunkLike {
+  fileName: string;
+  isEntry: boolean;
+  /** The chunks this one imports statically. */
+  imports: string[];
+  moduleIds: string[];
+}
+
+const posix = (id: string) => id.split("\\").join("/");
+
+/** Every lazily imported module (`lazy`: module ids) that sits in a boot chunk, as "id (chunk)". The
+ *  shell's own module (`shell`, a path under the project) is exempt: it is lazy so that the public
+ *  pages never load it, and its chunk is the shell. */
+export function bootLeaks(chunks: ChunkLike[], lazy: Set<string>, shell: string): string[] {
+  const byName = new Map(chunks.map((c) => [c.fileName, c]));
+  const isShell = (id: string) => posix(id).endsWith(`/${shell}`);
+  const boot = new Set<ChunkLike>();
+  const visit = (c: ChunkLike | undefined) => {
+    if (!c || boot.has(c)) return;
+    boot.add(c);
+    c.imports.forEach((name) => visit(byName.get(name)));
+  };
+  chunks.filter((c) => c.isEntry || c.moduleIds.some(isShell)).forEach(visit);
+  const leaks: string[] = [];
+  for (const c of boot)
+    for (const id of c.moduleIds)
+      if (lazy.has(id) && !isShell(id)) leaks.push(`${posix(id)} (${c.fileName})`);
+  return leaks.sort();
+}
+
+export function chunkGuard(): Plugin {
+  return {
+    name: "siftlode-chunk-guard",
+    apply: "build",
+    generateBundle(_options, bundle) {
+      const lazy = new Set(
+        [...this.getModuleIds()].filter(
+          (id) => (this.getModuleInfo(id)?.dynamicImporters.length ?? 0) > 0,
+        ),
+      );
+      const chunks: ChunkLike[] = Object.values(bundle).flatMap((o) =>
+        o.type === "chunk"
+          ? [
+              {
+                fileName: o.fileName,
+                isEntry: o.isEntry,
+                imports: o.imports,
+                moduleIds: o.moduleIds,
+              },
+            ]
+          : [],
+      );
+      const leaks = bootLeaks(chunks, lazy, SHELL);
+      if (leaks.length)
+        this.error(
+          `lazily imported, yet loaded at boot: ${leaks.join(", ")}. ` +
+            "Something on the boot path imports it statically (an index.ts re-export?): import it lazily there too, or not at all.",
+        );
+    },
+  };
+}

frontend/e2e/README.md

@@ -25,7 +25,8 @@ that one error again and passes every other failure straight on. Don't run two e
 same machine at once.
 
 **Browsers** — every flow runs in three projects: `chromium` (Desktop Chrome), `webkit` (Desktop
-Safari) and `ipad` (iPad gen 7 landscape: 1080×810, touch, mobile). Install the engines once per
+Safari) and `ipad` (iPad gen 7 landscape: 1080×810, touch, mobile) — except `a11y`, `member` and
+`devices`, which run on chromium only (`CHROMIUM_ONLY`; why is in the `docs/gates.md` row). Install the engines once per
 machine with `npx playwright install chromium webkit`; run one project with
 `npx playwright test --project=ipad`. WebKit catches what every iOS browser inherits from the engine
 (JS, CSS/layout, event order). It does **not** reproduce iPad media refusals: Playwright's WebKit
@@ -57,9 +58,15 @@ admin so the suite can reach the admin-only pages / render branches, matching th
 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` (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
+one in-progress + one watched + one saved video, prefs pinned to `language: en`. A second account,
+the plain **member** `e2e-member@siftlode.local`, gets the same baseline and its own session
+(`e2e/.auth/member.json`). Two specs run as it: `member.spec.ts`, holding what a non-admin sees (no
+admin entry, no admin call, no failed request, an admin link lands on the feed), and `devices.spec.ts`,
+which signs it in on a desktop and an iPad at once and changes its channel layout on the server (put
+back in a `finally`) — a spec that reads the member's server prefs must not run beside it. Credentials come from `E2E_EMAIL` (default
+`e2e@siftlode.local`), `E2E_MEMBER_EMAIL` (default `e2e-member@siftlode.local`) and `E2E_PASSWORD`
+(both accounts) — **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/devices.spec.ts

@@ -0,0 +1,61 @@
+import { test, expect, devices, type Browser, type Page } from "@playwright/test";
+import { MEMBER_STORAGE, gotoPage, openApp } from "./helpers";
+
+// One member on two devices, a desktop and an iPad, each with its own browser storage. A preference is
+// a choice about the account, so a change on one device shows on the other; a device setting (here
+// performance mode, for a weak GPU) stays on the device it was set on. Kept in browser storage only, a
+// preference used to stay on the one device it was changed on.
+
+async function device(browser: Browser, descriptor: (typeof devices)[string]): Promise<Page> {
+  const context = await browser.newContext({
+    ...descriptor,
+    baseURL: test.info().project.use.baseURL,
+    locale: "en-US",
+    storageState: MEMBER_STORAGE,
+  });
+  return context.newPage();
+}
+
+const savedPrefs = (page: Page) =>
+  page.waitForResponse(
+    (r) => r.url().includes("/me/preferences") && r.request().method() === "PUT",
+  );
+
+async function pickLayout(page: Page, from: string, to: string): Promise<void> {
+  await page.getByRole("button", { name: `Layout: ${from}` }).click();
+  await Promise.all([savedPrefs(page), page.getByRole("menuitemradio", { name: to }).click()]);
+  await expect(page.getByRole("button", { name: `Layout: ${to}` })).toBeVisible();
+}
+
+test("a preference follows the member to another device, a device setting stays", async ({
+  browser,
+}) => {
+  const desktop = await device(browser, devices["Desktop Chrome"]);
+  const ipad = await device(browser, devices["iPad (gen 7) landscape"]);
+  try {
+    await openApp(desktop);
+    await gotoPage(desktop, "channels");
+    await pickLayout(desktop, "Table", "Cards");
+    await gotoPage(desktop, "settings");
+    await desktop.getByRole("switch", { name: "Performance mode" }).click();
+    await expect(desktop.locator("html")).toHaveAttribute("data-perf", "1");
+    // The Settings prefs save as one payload: the next one (a hints change) would carry performance
+    // mode if it went to the account. Waited for, so the iPad below cannot simply load first.
+    const hints = desktop.getByRole("switch", { name: "Show hints" });
+    const [save] = await Promise.all([savedPrefs(desktop), hints.click()]);
+    expect(Object.keys(save.request().postDataJSON() as object)).not.toContain("performanceMode");
+    await Promise.all([savedPrefs(desktop), hints.click()]);
+
+    await openApp(ipad);
+    await expect(ipad.locator("html")).not.toHaveAttribute("data-perf", "1");
+    await gotoPage(ipad, "channels");
+    await expect(ipad.getByRole("button", { name: "Layout: Cards" })).toBeVisible();
+  } finally {
+    // The member is shared by the suite: put the layout back (performance mode went with the
+    // desktop's storage).
+    await gotoPage(desktop, "channels");
+    await pickLayout(desktop, "Cards", "Table");
+    await desktop.context().close();
+    await ipad.context().close();
+  }
+});

frontend/e2e/global.setup.ts

@@ -1,20 +1,24 @@
-import { test as setup, expect } from "@playwright/test";
+import { test as setup, expect, type Page } from "@playwright/test";
 import { execFileSync } from "node:child_process";
 import { mkdirSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { MEMBER_STORAGE } from "./helpers";
 import { retryConnect } from "./retryConnect";
 
 /**
  * One-time setup for the characterization net (the `setup` project the tests depend on):
  *   1. preflight — the localdev :8080 stack must be up (owned by `siftlode dev`);
- *   2. seed — reset the dedicated E2E account to a known baseline, in-container (idempotent);
- *   3. authenticate ONCE via password-login and persist the session + `en` locale to
- *      storageState, so the real specs never re-auth (auth endpoints are rate-limited).
+ *   2. seed — reset the dedicated E2E accounts to a known baseline, in-container (idempotent);
+ *   3. authenticate each ONCE via password-login and persist its session + `en` locale to its own
+ *      storageState, so the real specs never re-auth (auth endpoints are rate-limited). The suite
+ *      runs as the admin; `member.spec.ts` and `devices.spec.ts` run as the plain member, from
+ *      MEMBER_STORAGE.
  */
 
 const STORAGE = "e2e/.auth/state.json";
 const EMAIL = process.env.E2E_EMAIL || "e2e@siftlode.local";
+const MEMBER_EMAIL = process.env.E2E_MEMBER_EMAIL || "e2e-member@siftlode.local";
 // 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 ?? "";
@@ -27,14 +31,44 @@ const SEED_SCRIPT = resolve(HERE, "../../scripts/e2e_seed.py");
 // The in-container seed only makes sense when the target is the local stack.
 const isLocalTarget = /\/\/(127\.0\.0\.1|localhost)[:/]/.test(BASE_URL);
 
-setup("seed + authenticate", async ({ page }) => {
+/** Sign `email` in on `page`'s context and save that context as `path`. */
+async function signIn(page: Page, email: string, path: string): Promise<void> {
+  // These requests run in Node and share the page's cookie jar — so the `session` cookie the login
+  // receives is what storageState saves below — and a localhost connect the machine dropped is
+  // tried again (retryConnect).
+  const api = retryConnect(page.request);
+  const login = await api.post("/auth/password-login", { data: { email, password: PASSWORD } });
+  expect(
+    login.ok(),
+    `password-login failed for ${email} — is the E2E account seeded?`,
+  ).toBeTruthy();
+
+  const me = await (await api.get("/api/me")).json();
+  expect(me.authenticated, `session not established after login (${email})`).toBeTruthy();
+
+  // Pin the UI locale, suppress the first-login onboarding wizard (a full-screen overlay that
+  // would intercept every click — the test accounts have no YouTube connection, so it auto-opens),
+  // and opt the account out of starting on Home. A bare URL lands on Home, and the feed, channel
+  // and player flows this net locks all open "/" expecting the feed; the opt-out is the one
+  // Settings → Appearance → Startup writes. Both flags are the account's local state, held for the
+  // account the browser records as their owner (`siftlode.owner`, see storage.ts claimLocalData).
+  await page.goto("/");
+  await page.evaluate((id: number) => {
+    localStorage.setItem("siftlode.owner", String(id));
+    localStorage.setItem("siftlode.lang", "en");
+    localStorage.setItem("siftlode.onboarding.dismissed", "1");
+    localStorage.setItem("siftlode.startOnHome", "0");
+  }, me.id);
+  mkdirSync(dirname(path), { recursive: true });
+  await page.context().storageState({ path });
+}
+
+setup("seed + authenticate", async ({ page, browser }) => {
   expect(
     PASSWORD,
     "E2E_PASSWORD is not set — run the suite through `siftlode e2e` (it reads the secret store)",
   ).not.toBe("");
 
-  // These requests run in Node (sharing the page's cookie jar), so a localhost connect the machine
-  // dropped is tried again (retryConnect).
   const api = retryConnect(page.request);
 
   // 1. Preflight: fail fast (with a useful message) if the stack isn't running.
@@ -55,6 +89,8 @@ setup("seed + authenticate", async ({ page }) => {
           "-e",
           `E2E_EMAIL=${EMAIL}`,
           "-e",
+          `E2E_MEMBER_EMAIL=${MEMBER_EMAIL}`,
+          "-e",
           `E2E_PASSWORD=${PASSWORD}`,
           CONTAINER,
           "python",
@@ -69,28 +105,12 @@ setup("seed + authenticate", async ({ page }) => {
     }
   }
 
-  // 3. Authenticate. page.request shares the browser context's cookie jar, so the `session`
-  //    cookie it receives is captured by storageState below.
-  const login = await api.post("/auth/password-login", {
-    data: { email: EMAIL, password: PASSWORD },
-  });
-  expect(login.ok(), "password-login failed — is the E2E account seeded?").toBeTruthy();
-
-  const me = await (await api.get("/api/me")).json();
-  expect(me.authenticated, "session not established after login").toBeTruthy();
-
-  // 4. Pin the UI locale, suppress the first-login onboarding wizard (a full-screen overlay
-  //    that would intercept every click — the test account has no YouTube connection, so it
-  //    auto-opens), and opt the account out of starting on Home. A bare URL lands on
-  //    Home, and the feed, channel and player flows this net locks all open "/" expecting the
-  //    feed; the opt-out is the one Settings → Appearance → Startup writes. Both flags are
-  //    per-account: `siftlode.onboarding.dismissed.<id>`, `siftlode.startOnHome.<id>`.
-  await page.goto("/");
-  await page.evaluate((id: number) => {
-    localStorage.setItem("siftlode.lang", "en");
-    localStorage.setItem(`siftlode.onboarding.dismissed.${id}`, "1");
-    localStorage.setItem(`siftlode.startOnHome.${id}`, "0");
-  }, me.id);
-  mkdirSync(dirname(STORAGE), { recursive: true });
-  await page.context().storageState({ path: STORAGE });
+  // 3. Authenticate each account in its own context: one cookie jar holds one session.
+  await signIn(page, EMAIL, STORAGE);
+  const memberContext = await browser.newContext({ storageState: { cookies: [], origins: [] } });
+  try {
+    await signIn(await memberContext.newPage(), MEMBER_EMAIL, MEMBER_STORAGE);
+  } finally {
+    await memberContext.close();
+  }
 });

frontend/e2e/helpers.ts

@@ -1,5 +1,9 @@
 import { expect, type Page } from "@playwright/test";
 
+/** The plain member's saved session (global.setup.ts signs it in); `member.spec.ts` and
+ *  `devices.spec.ts` run from it. */
+export const MEMBER_STORAGE = "e2e/.auth/member.json";
+
 /** Open the app and wait for the authenticated shell (the nav rail) to be ready. */
 export async function openApp(page: Page, path = "/"): Promise<void> {
   await page.goto(path);

frontend/e2e/member.spec.ts

@@ -0,0 +1,97 @@
+import { test, expect, type Page, type Request, type Response } from "@playwright/test";
+import { MEMBER_STORAGE, openApp } from "./helpers";
+
+// What a plain member (not an admin) sees. The rest of the suite runs as the admin, so without this
+// spec nothing end to end holds the member's shell: the backend refuses the admin routes (pytest),
+// but a member shown an admin entry, sent to an admin page or met by a refused request would pass.
+test.use({ storageState: MEMBER_STORAGE });
+
+const ADMIN_PAGES = ["scheduler", "config", "users", "activity"];
+// The pages every member has; Plex joins them only where the instance enables it.
+const CORE = [
+  "home",
+  "feed",
+  "channels",
+  "playlists",
+  "notifications",
+  "files",
+  "stats",
+  "settings",
+];
+
+const isApi = (url: string) => new URL(url).pathname.startsWith("/api/");
+
+/** Collect every admin call and every failed API answer the page gets while `run` goes. `run` is
+ *  handed `settled`, which waits until no API request of the page is in flight: an error state
+ *  renders only once its request has answered, and a check made before that passes on a page that
+ *  is still loading. */
+async function watchRequests(
+  page: Page,
+  run: (settled: () => Promise<void>) => Promise<void>,
+): Promise<string[]> {
+  const bad: string[] = [];
+  const pending = new Set<Request>();
+  const onRequest = (r: Request) => {
+    if (!isApi(r.url())) return;
+    pending.add(r);
+    if (new URL(r.url()).pathname.startsWith("/api/admin")) bad.push(`admin call ${r.url()}`);
+  };
+  const onDone = (r: Request) => pending.delete(r);
+  const onResponse = (r: Response) => {
+    if (isApi(r.url()) && r.status() >= 400) bad.push(`${r.status()} ${r.url()}`);
+  };
+  const settled = () => expect.poll(() => pending.size, { timeout: 15_000 }).toBe(0);
+  page.on("request", onRequest);
+  page.on("requestfinished", onDone);
+  page.on("requestfailed", onDone);
+  page.on("response", onResponse);
+  try {
+    await run(settled);
+    await settled();
+  } finally {
+    page.off("request", onRequest);
+    page.off("requestfinished", onDone);
+    page.off("requestfailed", onDone);
+    page.off("response", onResponse);
+  }
+  return bad;
+}
+
+test.describe("a member", () => {
+  test("gets no admin entry, and every page of the rail opens without an error", async ({
+    page,
+  }) => {
+    const bad = await watchRequests(page, async (settled) => {
+      await openApp(page);
+      await expect(page.getByTestId("nav-admin")).toHaveCount(0);
+
+      const rail = page
+        .getByRole("navigation", { name: "Primary navigation" })
+        .locator('[data-testid^="nav-"]');
+      const ids = (await rail.evaluateAll((els) => els.map((el) => el.getAttribute("data-testid"))))
+        .filter((id): id is string => id !== null)
+        .map((id) => id.replace(/^nav-/, ""));
+      expect(ids).toEqual(expect.arrayContaining(CORE));
+      expect(ids.filter((id) => ADMIN_PAGES.includes(id))).toEqual([]);
+
+      for (const id of ids) {
+        await page.getByTestId(`nav-${id}`).click();
+        await expect(page.getByTestId(`nav-${id}`)).toHaveAttribute("aria-current", "page");
+        await settled();
+        // An error state is a `role=alert` StateMessage; a page that failed to load shows one.
+        await expect(page.getByRole("alert"), `error state on ${id}`).toHaveCount(0);
+      }
+    });
+    expect(bad).toEqual([]);
+  });
+
+  test("a link to an admin page opens no admin page", async ({ page }) => {
+    for (const id of ADMIN_PAGES) {
+      const bad = await watchRequests(page, () => openApp(page, `/?page=${id}`));
+      expect(bad, id).toEqual([]);
+      await expect(page.getByTestId("nav-admin")).toHaveCount(0);
+      // The member lands on the feed instead, and the rail says so.
+      await expect(page.getByTestId("nav-feed")).toHaveAttribute("aria-current", "page");
+    }
+  });
+});

frontend/e2e/settings.spec.ts

@@ -5,7 +5,9 @@ import { openApp, gotoPage } from "./helpers";
 // Appearance change persists on its own via PUT /me/preferences and a transient indicator confirms
 // it; leaving Settings after a change is no longer guarded.
 test.describe("settings auto-save", () => {
-  const TOGGLE = "Performance mode"; // an Appearance switch (locale pinned to en)
+  // An Appearance switch saved to the account (locale pinned to en). Not performance mode: that one
+  // is the device's and is never sent.
+  const TOGGLE = "Show hints";
 
   // The save is debounced (~500ms), so wait for the PUT rather than assuming it's synchronous.
   const putPrefs = (page: Page) =>

frontend/eslint.config.js

@@ -7,6 +7,8 @@ import globals from "globals";
 import eslintComments from "@eslint-community/eslint-plugin-eslint-comments";
 import vitest from "@vitest/eslint-plugin";
 import playwright from "eslint-plugin-playwright";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 // Flat config (ESLint 9). Deliberately NARROW: the high-value rules here are react-hooks' (the
 // hook rules and the React Compiler's diagnostics). The 33 inline `exhaustive-deps` suppressions this
@@ -99,7 +101,8 @@ const localeFormat = {
     // 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);
+    // Every folder that holds components (CLAUDE.md "Architecture shape"), not lib/ below them.
+    const component = /\/src\/(components|shell|modules|features|watch)\//.test(path);
     const importedFromI18n = (node) => {
       for (let scope = context.sourceCode.getScope(node); scope; scope = scope.upper) {
         const v = scope.set.get(node.name);
@@ -418,8 +421,105 @@ const glyphLink = {
     };
   },
 };
+// The app's layers (CLAUDE.md "Architecture shape"), bottom up: lib/ → components/ui/ → features/ →
+// modules/ → shell/. An import may go down, never up — with one door: a module's index.ts, its public
+// face, which features/ may read too (the module stores are mounted at the root and read app-wide).
+// Anything else of ANOTHER module is reached through that face, or lazily by import(), which is a
+// chunk boundary and so the way a page is opened. Measured on the import, resolved to its file, so
+// every spelling of a path is the same path. lib/ and ui/ keep their own `no-restricted-imports`
+// blocks below; this rule adds the folders above them.
+const SRC_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "src");
+const RANK = { lib: 0, ui: 1, features: 2, modules: 3, shell: 4 };
+function placeOf(abs) {
+  const rel = path.relative(SRC_DIR, abs).split(path.sep).join("/");
+  if (rel.startsWith("..")) return null;
+  const parts = rel.replace(/\.(tsx?|jsx?)$/, "").split("/");
+  const [top, unit] = parts;
+  if (top === "lib") return { layer: "lib" };
+  if (top === "components") return unit === "ui" ? { layer: "ui" } : { layer: "other" };
+  if (top === "features" || top === "modules") {
+    // `modules/plex` and `modules/plex/index` are the unit's public face.
+    const face = parts.length === 2 || (parts.length === 3 && parts[2] === "index");
+    return { layer: top, unit, face };
+  }
+  if (top === "shell") return { layer: "shell" };
+  // main.tsx, watch/, i18n/, content/, design-lab/, the app-wide tests at the root. The two entries —
+  // the app's main.tsx and the shared /watch page (watch/ + watchMain.tsx) — sit above every layer.
+  const root = parts.length === 1;
+  const entry = top === "watch" || (root && (top === "main" || top === "watchMain"));
+  return { layer: "other", top: root ? "root" : top, entry };
+}
+const layers = {
+  meta: {
+    type: "problem",
+    messages: {
+      up: "{{from}} sits below {{to}}: it may not import from it (`{{spec}}`). Move the shared piece down, or take it as a prop.",
+      face: "`{{spec}}` is one of {{unit}}'s own files: reach another unit through its index.ts (its public face), or lazily with import().",
+      entry:
+        "`{{spec}}` is an entry (the app's main.tsx or the shared /watch page): no layer imports one, or the app and the /watch page stop being separable.",
+    },
+  },
+  create(context) {
+    const file = context.filename;
+    const from = placeOf(file);
+    // The dev-only lab and the app-wide tests at the root look at everything on purpose.
+    const free =
+      !from ||
+      (from.layer === "other" && from.top === "design-lab") ||
+      (from.layer === "other" && from.top === "root" && /\.test(kit)?\.|\.testkit\./.test(file));
+    const check = (node, spec, lazy) => {
+      if (free || typeof spec !== "string" || !spec.startsWith(".")) return;
+      const to = placeOf(path.resolve(path.dirname(file), spec));
+      if (!to) return;
+      if (to.layer === "other") {
+        if (to.entry && from.layer !== "other")
+          context.report({ node, messageId: "entry", data: { spec } });
+        return;
+      }
+      const fromRank = from.layer === "other" ? 5 : RANK[from.layer];
+      if (
+        to.layer === "shell" &&
+        from.layer !== "shell" &&
+        !(from.layer === "other" && from.top === "root")
+      )
+        return context.report({
+          node,
+          messageId: "up",
+          data: { from: from.layer, to: "shell", spec },
+        });
+      const door = to.layer === "modules" && (to.face || lazy) && from.layer === "features";
+      if (RANK[to.layer] > fromRank && !door)
+        return context.report({
+          node,
+          messageId: "up",
+          data: { from: from.layer, to: to.layer, spec },
+        });
+      const sameUnit = to.layer === from.layer && to.unit === from.unit;
+      if (to.layer === "modules" && !sameUnit && !to.face && !lazy)
+        context.report({ node, messageId: "face", data: { spec, unit: `modules/${to.unit}` } });
+    };
+    return {
+      ImportDeclaration: (n) => check(n.source, n.source.value, false),
+      ExportNamedDeclaration: (n) => n.source && check(n.source, n.source.value, false),
+      ExportAllDeclaration: (n) => check(n.source, n.source.value, false),
+      ImportExpression: (n) => {
+        // A template literal with nothing substituted is a plain path to TypeScript and Rollup too.
+        const s = n.source;
+        if (s.type === "Literal") check(s, s.value, true);
+        else if (s.type === "TemplateLiteral" && s.expressions.length === 0)
+          check(s, s.quasis[0].value.cooked, true);
+      },
+      TSImportType: (n) => {
+        const lit = n.argument?.literal ?? n.argument;
+        if (lit?.type === "Literal") check(lit, lit.value, false);
+      },
+    };
+  },
+};
+
 const localRules = {
   rules: {
+    layers,
     "glyph-link": glyphLink,
     "sortable-a11y": sortableA11y,
     "jsx-comment-text": jsxCommentText,
@@ -536,7 +636,7 @@ export default tseslint.config(
       // function the compiler skips over a suppression is caught by the coverage contract below.
       // `todo` does NOT see every such shape — a conditional, a loop
       // or an optional call inside a try skips the function with no lint hit at all — so the full
-      // per-function picture is components/compilerCoverage.contract.test.ts.
+      // per-function picture is src/compilerCoverage.contract.test.ts.
       "react-hooks/todo": "error",
       "react-hooks/memo-dependencies": "error",
       "react-hooks/invariant": "error",
@@ -566,6 +666,7 @@ export default tseslint.config(
       "local/literal-a11y-text": "error",
       "local/glyph-link": "error",
       "local/sortable-a11y": "error",
+      "local/layers": "error",
       "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
       // tsc already enforces these under strict + noUnusedLocals/Parameters — let it own them so a
       // finding is reported once, by one tool, and this config stays about hooks + refresh safety.
@@ -760,7 +861,14 @@ export default tseslint.config(
     // Outside src: the e2e suite and the TypeScript build-tool configs went unlinted — the
     // flat config named only src/**, so `eslint .` skipped them without a word. The same base and
     // typed rules as the app; Node globals, since none of it runs in the browser.
-    files: ["e2e/**/*.ts", "*.config.ts", "reactPlugin.ts", "devOnlyGuard.ts"],
+    files: [
+      "e2e/**/*.ts",
+      "*.config.ts",
+      "reactPlugin.ts",
+      "devOnlyGuard.ts",
+      "chunkGuard.ts",
+      "chunkGuard.test.ts",
+    ],
     extends: [js.configs.recommended, ...tseslint.configs.recommended],
     languageOptions: {
       ecmaVersion: 2022,
@@ -775,6 +883,16 @@ export default tseslint.config(
       "no-undef": "off",
     },
   },
+  {
+    // The unit tests of the build tools beside them (chunkGuard's): vitest runs them, so a stray
+    // `.only` / `.skip` there is the same silent skip as in src.
+    files: ["*.test.ts"],
+    plugins: { vitest },
+    rules: {
+      "vitest/no-focused-tests": "error",
+      "vitest/no-disabled-tests": "error",
+    },
+  },
   {
     files: ["e2e/**/*.ts"],
     plugins: { playwright },

frontend/playwright.config.ts

@@ -17,9 +17,11 @@ import { defineConfig, devices } from "@playwright/test";
 
 const BASE_URL = process.env.PW_BASE_URL || "http://127.0.0.1:8080";
 const STORAGE_STATE = "e2e/.auth/state.json";
-// The axe scan reads the DOM and the accessibility tree, which the engines build alike: one engine
-// answers for all, so the other projects leave it out instead of tripling its time.
-const CHROMIUM_ONLY = /a11y\.spec\.ts/;
+// The axe scan reads the DOM and the accessibility tree, which the engines build alike, and the
+// member spec checks which pages and requests a role gets, which no engine changes, and the devices
+// spec opens its own desktop and iPad contexts: one engine answers for all, so the other projects
+// leave them out instead of tripling their time.
+const CHROMIUM_ONLY = /(a11y|member|devices)\.spec\.ts/;
 
 export default defineConfig({
   testDir: "./e2e",

frontend/reactPlugin.ts

@@ -15,7 +15,7 @@ import reactCompiler from "babel-plugin-react-compiler";
 // there is no logger here, so a skipped component still works and simply re-renders everything under
 // it. This comment used to say "its rules are also linted"; it was false while `react-hooks/refs` was
 // off, and 95 functions sat uncompiled behind it. What actually holds the line now is
-// src/components/compilerCoverage.contract.test.ts, which runs THIS compiler over the shipped source
+// src/compilerCoverage.contract.test.ts, which runs THIS compiler over the shipped source
 // and fails on any skip not on its list; the react-hooks lint rules are the early warning. None of
 // them is off (three run at the preset's warn, which `--max-warnings 0` fails — docs/gates.md), but
 // three of the compiler's diagnostics cannot report under the installed plugin (eslint.config.js

frontend/src/App.tsx

@@ -1,498 +0,0 @@
-import { lazy, Suspense, useEffect, useRef, useState } from "react";
-import { qk } from "./lib/queryKeys";
-import { saveLanguage } from "./lib/saveLanguage";
-import { useTranslation } from "react-i18next";
-import { useQuery, useQueryClient } from "@tanstack/react-query";
-import { api, setUnauthorizedHandler, type Me } from "./lib/api";
-import { notifyActionError } from "./lib/actionErrors";
-import { setLanguage, type LangCode } from "./i18n";
-import { clearParams } from "./lib/urlState";
-import type { Page } from "./lib/urlState";
-import {
-  PREF_KEY,
-  saveLayoutLocal,
-  seedLayout,
-  type PanelId,
-  type PanelLayout,
-} from "./lib/panelLayout";
-import { notify, removeByMetaKind } from "./lib/notifications";
-import { LS } from "./lib/storage";
-import { usePref } from "./lib/usePref";
-import { useVerifyEntry } from "./lib/useVerifyEntry";
-import { useNavigation, useNavigationActions } from "./components/navigationContext";
-import { useFeedFilters, useFeedFiltersActions } from "./components/feedFiltersContext";
-import { useFeedView, useFeedViewActions } from "./components/feedViewContext";
-import { moduleDef, moduleOrder } from "./lib/modules";
-import { PAGE_CONTENT, PAGE_RAIL, preloadPages } from "./components/moduleRegistry";
-import { lazyWithPreload } from "./lib/lazyWithPreload";
-import { LoadingState } from "./components/ui/QueryState";
-// Persistent shell — always mounted, so eagerly imported.
-import Welcome from "./components/Welcome";
-import SetupWizard from "./components/SetupWizard";
-import Header from "./components/Header";
-import NavSidebar from "./components/NavSidebar";
-import BackToTop from "./components/ui/BackToTop";
-import PageShell from "./components/ui/PageShell";
-import { SkipLink } from "./components/ui/SkipLink";
-import { pageTitleKey } from "./lib/pageMeta";
-import DebugRecorder from "./components/DebugRecorder";
-import Toaster from "./components/ui/Toaster";
-import KeyboardHelp from "./components/ui/KeyboardHelp";
-import AppCommandPalette from "./components/AppCommandPalette";
-import DownloadIntake from "./components/DownloadIntake";
-import DownloadTray from "./components/DownloadTray";
-import { useGlobalKeymap } from "./lib/keymap";
-import ErrorDialog from "./components/ErrorDialog";
-import VersionBanner from "./components/VersionBanner";
-import VerifyBanner from "./components/VerifyBanner";
-import { focusAccessRequestsTab } from "./lib/adminUsersTab";
-import { focusSettingsTab } from "./lib/settingsTab";
-// The built app version, NOT imported from releaseNotes — importing anything from that module
-// pulls the release-notes loader into the eager App chunk and defeats the lazy ReleaseNotes
-// split. FRONTEND_VERSION equals the newest release note's version by release convention (both bump together).
-import { FRONTEND_VERSION } from "./lib/version";
-import { applyDiagnostics } from "./lib/diagnostics";
-
-// The page modules (and their side rails) are code-split per route via the module registry
-// (components/moduleRegistry). App keeps only the persistent-shell chunks + the channel page and the
-// two modals, which sit outside the registry-driven content column.
-const ChannelPage = lazyWithPreload(() => import("./components/ChannelPage"));
-const About = lazy(() => import("./components/About"));
-const ReleaseNotes = lazy(() => import("./components/ReleaseNotes"));
-
-export default function App() {
-  const { t, i18n } = useTranslation();
-  const { page, channelView, ytSearch } = useNavigation();
-  const { setPage, enterYtSearch } = useNavigationActions();
-  // An emailed verification link is confirmed HERE, above the signed-in/signed-out branch below, so
-  // it works in a browser that already holds a session. It used to be handled inside Welcome, which
-  // that branch never renders when signed in — the token was silently dropped. Signed out, the
-  // outcome goes to the auth card's banners; signed in, to the top-of-app bar.
-  const verifyEntry = useVerifyEntry();
-  // The global feed filters live in FeedFiltersProvider (per-account persistence + the account-load
-  // effect + share-link capture all moved there). App reads them to hand to <Feed> and to the
-  // handlers that mutate the feed view (onShowInFeed, tag-click, the feed scrollKey).
-  const filters = useFeedFilters();
-  const { setFilters } = useFeedFiltersActions();
-  // The feed's view mode (card/row/tile density) lives in FeedViewProvider — server-synced, shared
-  // by the feed page and the channel page. App reads it only to hand to <Feed>/<ChannelPage>.
-  const view = useFeedView();
-  const { setView } = useFeedViewActions();
-  const queryClient = useQueryClient();
-  // Per-panel "customize" layouts (order/collapsed/hidden of each side panel's group cards),
-  // persisted per-account. One record so feed/plex/playlists share the same mechanism. Seeded from
-  // the account's server preferences — BootGate mounts App only once `me` is cached — so a layout
-  // changed on another device is right on the first paint; the local copy covers a key the server
-  // has never stored.
-  const [panelLayouts, setPanelLayouts] = useState<Record<PanelId, PanelLayout>>(() => {
-    const prefs = queryClient.getQueryData<Me | null>(qk.me())?.preferences;
-    return {
-      feed: seedLayout("feed", prefs),
-      plex: seedLayout("plex", prefs),
-      playlists: seedLayout("playlists", prefs),
-      files: seedLayout("files", prefs),
-    };
-  });
-  const [aboutOpen, setAboutOpen] = useState(false);
-  const [notesOpen, setNotesOpen] = useState(false);
-  const [notesHighlight, setNotesHighlight] = useState<string | undefined>(undefined);
-
-  function openReleaseNotes(highlight?: string) {
-    setNotesHighlight(highlight);
-    setNotesOpen(true);
-  }
-
-  function setPanelLayout(panel: PanelId, next: PanelLayout) {
-    setPanelLayouts((prev) => ({ ...prev, [panel]: next }));
-    saveLayoutLocal(panel, next);
-    api
-      .savePrefs({ [PREF_KEY[panel]]: next })
-      .catch((e: unknown) => notifyActionError(e, t("errors.writeFailed.prefs")));
-  }
-
-  // Collapse state for the two full-height panels (left nav + filter sidebar). Persisted to the
-  // user's preferences (via usePref) so it follows the account across devices, seeded from the `me`
-  // cache at mount; the localStorage mirror covers an account whose server prefs never stored it.
-  // Default unpinned (tab + hover-expand overlay); accounts that explicitly pin keep their choice.
-  const [filterCollapsed, setFilterCollapsed] = usePref<boolean>("filterCollapsed", true, {
-    localKey: LS.filterCollapsed,
-    parse: Boolean,
-  });
-  // The Playlists rail has its own collapse flag (it's a list/navigator, not filters).
-  const [playlistsCollapsed, setPlaylistsCollapsed] = usePref<boolean>("playlistsCollapsed", true, {
-    localKey: LS.playlistsCollapsed,
-    parse: Boolean,
-  });
-  // The Files rail is the library's folder list — how you move around it, not a filter you set once —
-  // so it starts pinned open (the owner's mockup), and has its own flag.
-  const [filesCollapsed, setFilesCollapsed] = usePref<boolean>("filesCollapsed", false, {
-    localKey: LS.filesCollapsed,
-    parse: Boolean,
-  });
-  const railCollapse = {
-    filter: [filterCollapsed, setFilterCollapsed],
-    playlists: [playlistsCollapsed, setPlaylistsCollapsed],
-    files: [filesCollapsed, setFilesCollapsed],
-  } as const;
-  // (The feed filters + page/channel now LIVE in the address bar — FeedFiltersProvider and
-  // NavigationProvider read them on load and keep them mirrored — so there's no query to strip here.)
-
-  // Passive observers (enabled:false) of the setup-status and `me` queries BootGate fetches, polls
-  // and waits for: App mounts only once both have answered, so their caches are always populated here.
-  const setupQuery = useQuery({
-    queryKey: qk.setupStatus(),
-    queryFn: api.setupStatus,
-    enabled: false,
-  });
-  const needsSetup = setupQuery.data?.configured === false;
-  const meQuery = useQuery({ queryKey: qk.me(), queryFn: api.me, enabled: false });
-  // The signed-in account, or null/undefined while signed out. Hoisted here because half a dozen
-  // effects below depend on it, and a dep list is only honest if it names the value the body reads.
-  const me = meQuery.data;
-
-  // The `global` key scope: `h` opens the cheat sheet, Mod+K the jump-to palette, Shift+W jumps to
-  // Home ("mit nézzek?"). Bound only once signed in, because that is where the overlays are mounted
-  // (bottom of this tree) and where the modules exist at all — see useGlobalKeymap on why binding it
-  // above the signed-out branch is worse than not binding it.
-  // A global key can fire while an overlay is open; `setPage` closes every overlay before it pushes,
-  // so Shift+W over the player lands on Home with the player closed — also when Home is already the
-  // page underneath (owner decision 2026-09-09: the key always ends with the answer on screen).
-  // The `page` scope rides the same binding: the `g` chords jump to a module, but only to one this
-  // account can reach (the nav rail's own list, plus Settings, which is not in the rail's order).
-  useGlobalKeymap(!!me, setPage, me ? [...moduleOrder(me), "settings"] : []);
-
-  // The account's consented diagnostics level, applied to this tab's log: raised, the log is
-  // kept in more detail and streamed to the server until the level lapses. A debug session that is
-  // recording raises it for its own run and tags what it keeps. A lapse (its own timer, or the
-  // server saying it is off) refetches `me`, so Settings and the recorder show what is in force.
-  // Re-running this on every `me` refetch is FREE and therefore the deps are the honest ones:
-  // applyDiagnostics computes an effective-level key and returns early when it has not moved
-  // (lib/diagnostics.ts), so an unchanged level is a no-op. It does refresh the `lapsed` callback
-  // before that early return, which is the half we WANT re-run. The old dep list picked out four
-  // primitive fields to dodge the fresh object identity a refetch produces; that is the checker's
-  // job to verify, not a comment's to assert, and it silently missed any other field the module
-  // may come to read.
-  const diagnostics = me?.diagnostics;
-  const debugSession = me?.debug_session;
-  useEffect(() => {
-    applyDiagnostics(
-      diagnostics,
-      debugSession,
-      () => void queryClient.invalidateQueries({ queryKey: qk.me() }),
-    );
-  }, [diagnostics, debugSession, queryClient]);
-
-  // Fetch the code of every module this account can open — and the channel page — once the first page
-  // is on screen, so a module's first visit renders at once instead of flashing the chunk fallback.
-  // Idle-scheduled so it never competes with the first page's own requests (Safari has no
-  // requestIdleCallback, hence the timer).
-  // Depending on the whole `me` rather than its id is both honest and MORE correct: the module set
-  // is derived from `me` through each module's own gate (lib/modules moduleOrder), so a permission
-  // change — an admin grant, a Plex server appearing — alters it without the id moving, and the old
-  // `[me.id]` dep never re-preloaded for those. Re-running costs nothing: `preload()` is idempotent
-  // (lazyWithPreload memoises the pending promise), so a refetch that changes nothing fetches
-  // nothing; only the idle callback is re-scheduled.
-  useEffect(() => {
-    if (!me) return;
-    const run = () => {
-      preloadPages([...moduleOrder(me), "settings"]);
-      ChannelPage.preload().catch(() => {});
-    };
-    const idle = window.requestIdleCallback as typeof window.requestIdleCallback | undefined;
-    if (idle) {
-      const id = idle(run, { timeout: 3000 });
-      return () => window.cancelIdleCallback(id);
-    }
-    const id = window.setTimeout(run, 1000);
-    return () => window.clearTimeout(id);
-  }, [me]);
-
-  // Measure the scrollbar's gutter width once and publish it as --sbw, so the floating header and the
-  // toolbar band can pad their right edge to line up with the scrolled cards (the app scroller reserves
-  // that gutter via scrollbar-gutter: stable). It's a device constant, so a one-shot mount measure is enough.
-  useEffect(() => {
-    const probe = document.createElement("div");
-    probe.style.cssText =
-      "position:absolute;top:-9999px;width:100px;height:100px;overflow:scroll;scrollbar-gutter:stable";
-    document.body.appendChild(probe);
-    const w = probe.offsetWidth - probe.clientWidth;
-    document.body.removeChild(probe);
-    document.documentElement.style.setProperty("--sbw", `${w}px`);
-  }, []);
-
-  // Once signed in, drop any leftover ONE-TIME query params from the pre-login flow (?access, ?verify,
-  // ?reset) — but NOT the nav/filter params, which the logged-in app now reads from and keeps in the
-  // URL. Gated on auth so the logged-out Welcome page still reads its params first.
-  // Keyed on "is there a session at all", which is the whole condition the body tests. Re-running
-  // on an account switch was never the point — by then the params are already gone and a second
-  // clearParams is a no-op.
-  const signedIn = !!me;
-  useEffect(() => {
-    if (signedIn) clearParams("access", "verify", "reset");
-  }, [signedIn]);
-
-  // Any request that 401s means the session ended server-side. If we were signed in (cached
-  // `me` is a user object), reload to the login page at once (also covers any click that hits
-  // the API). Guarded on a cached user so a stray 401 while logged out (cached `me` is null)
-  // can't loop the public landing.
-  useEffect(() => {
-    setUnauthorizedHandler(() => {
-      if (queryClient.getQueryData(qk.me())) {
-        queryClient.clear();
-        window.location.reload();
-      }
-    });
-    return () => setUnauthorizedHandler(null);
-  }, [queryClient]);
-
-  // Returning from an in-app Google link/upgrade round-trip (auth.py redirects to ?link=…).
-  // Surface the outcome, refresh `me` (can_read/can_write/has_google may have flipped), land on
-  // Settings → Account so the new state is visible, then strip the param for a clean URL.
-  // "Exactly once per mount" is now ENFORCED by the ref rather than asserted by an empty dep list:
-  // `t` changes identity on a language switch, so the honest dep list would otherwise re-fire the
-  // toast when the user changes language. (The old `[]` got away with it only because clearParams
-  // had already removed the param — an invariant held by a side effect two lines further down.)
-  const linkAnswered = useRef(false);
-  const { refetch: refetchMe } = meQuery;
-  useEffect(() => {
-    if (linkAnswered.current) return;
-    const result = new URLSearchParams(window.location.search).get("link");
-    if (!result) return;
-    linkAnswered.current = true;
-    if (result === "ok") {
-      notify({ level: "success", message: t("settings.account.googleLink.linked") });
-      void refetchMe();
-      focusSettingsTab("account");
-      setPage("settings");
-    } else {
-      const key = result === "conflict" || result === "mismatch" ? result : "error";
-      notify({ level: "error", message: t(`settings.account.googleLink.${key}`) });
-    }
-    clearParams("link");
-  }, [t, setPage, refetchMe]);
-
-  // A Google OAuth flow started while already signed in (add-another-account, link, or upgrade) was
-  // cancelled at Google's consent screen. The backend only emits this for a live session, so a
-  // neutral toast is the right feedback — the pre-auth login banner would never render here.
-  // Same one-shot shape as the `?link=` handler above, same reason for the ref.
-  const oauthAnswered = useRef(false);
-  useEffect(() => {
-    if (oauthAnswered.current) return;
-    if (new URLSearchParams(window.location.search).get("oauth") !== "cancelled") return;
-    oauthAnswered.current = true;
-    notify({ level: "info", message: t("settings.account.googleCancelled") });
-    clearParams("oauth");
-  }, [t]);
-
-  // Deep-link from the "new access request" admin email (?admin=access-requests) → jump straight to
-  // the admin Users → Access requests view. Snapshot the param up front (read once at mount); act once
-  // `me` is known, and only for an admin (others just land on their default page).
-  const [adminDeepLink] = useState(() => new URLSearchParams(window.location.search).get("admin"));
-  // Ref-guarded like the two above, and here it closes a real hole rather than only satisfying the
-  // checker: the snapshot lives for the whole session, so with honest deps a later role change —
-  // or any `me` refetch, under the old id-only key — would yank the user to Users long after the
-  // deep link was answered.
-  const adminDeepLinkAnswered = useRef(false);
-  useEffect(() => {
-    if (adminDeepLinkAnswered.current) return;
-    if (adminDeepLink !== "access-requests" || !me) return;
-    adminDeepLinkAnswered.current = true;
-    if (me.role === "admin") {
-      focusAccessRequestsTab();
-      setPage("users");
-    }
-    clearParams("admin");
-  }, [adminDeepLink, me, setPage]);
-
-  // Nudge admins when access requests are waiting (in lieu of a server-push bell). Keyed on the
-  // pending COUNT so it re-resolves the moment an approval/denial changes it — not only on a
-  // fresh load (which is why the notice used to linger until F5 after an approval).
-  // Honest deps, and `t` among them is a fix rather than a concession: the nudge is a persisted
-  // toast whose text is translated at issue time, so a language switch must re-issue it. It did not
-  // before — the notice stayed in the old language until the count changed.
-  const role = me?.role;
-  const pendingInvites = me?.pending_invites ?? 0;
-  const pendingActivations = me?.pending_activations ?? 0;
-  useEffect(() => {
-    if (role !== "admin") return;
-    // Keep a single, current nudge: drop any prior one (persisted copies reload as dismissed
-    // history, so they'd otherwise pile up one-per-reload) before re-issuing the live notice.
-    removeByMetaKind("access-requests");
-    // Both kinds of "someone is waiting on you": a request needing a decision, and a sign-up whose
-    // address was approved before they registered. The second used to produce NO signal at all —
-    // nothing lands in the queue for it — which is how the 2026-09-03 registrant went unnoticed.
-    const pending = pendingInvites + pendingActivations;
-    if (pending > 0) {
-      notify({
-        level: "warning",
-        title: t("common.accessRequestsTitle"),
-        message: t("common.accessRequestsMessage", { count: pending }),
-        // Durable inbox link (survives reload, unlike a live action callback); the toast also
-        // gets a click via the action.
-        meta: { kind: "access-requests" },
-        action: {
-          label: t("common.accessRequestsReview"),
-          onClick: () => {
-            focusAccessRequestsTab();
-            // Clicked inside whatever overlay hosts the toast; setPage closes it before pushing.
-            setPage("users");
-          },
-        },
-      });
-    }
-  }, [role, pendingInvites, pendingActivations, t, setPage]);
-
-  // Language is edited outside the Settings page (sidebar/login), so it stays instant.
-  function changeLanguage(code: LangCode) {
-    setLanguage(code);
-    // Also from the signed-out login page, where the save 401s — `req` marks that as handled, so
-    // the reporter stays quiet there.
-    saveLanguage(queryClient, code).catch((e: unknown) =>
-      notifyActionError(e, t("errors.writeFailed.prefs")),
-    );
-  }
-
-  // First-run: a fresh instance is in setup mode (all other routes are locked) → show the wizard.
-  if (needsSetup) return <SetupWizard />;
-  // /api/me answers 200 always (null body = logged out), and BootGate has already handled a failed
-  // probe — so no data here means "not signed in" → the public landing.
-  if (!me) return <Welcome verify={verifyEntry} />;
-
-  // Shown while a page's chunk is still on its way: only if its visit beats the preload above (or the
-  // preload failed), and like every loading state it stays invisible for a load that is quick anyway.
-  const pageFallback = <LoadingState className="flex-1 justify-center" />;
-
-  // Scroll restore/reset key for the shared normal-page scroller (see PageScroller): the same
-  // page/feed-filters returns you to where you were (bug 1); a changed feed filter is a new key, so
-  // the fresh result set starts at the top (bug 3). `q` is normalised out so typing in the search
-  // box doesn't reset the scroll on every keystroke; the live-YouTube sub-view gets its own key.
-  const normalScrollKey =
-    page !== "feed"
-      ? `page:${page}`
-      : ytSearch != null
-        ? `yt:${ytSearch}`
-        : `feed:${JSON.stringify({ ...filters, q: "" })}`;
-
-  // The module registry drives the render from `page` alone — no per-page chrome conditionals. A
-  // page the account can't reach (a gated module via stale nav / a deep link) falls back to the feed,
-  // exactly as the old ternary's fallthrough did. A channel page overlays the content column, so no
-  // side rail shows behind it.
-  const pageGate = moduleDef(page).gate;
-  const activePage: Page = !pageGate || pageGate(me!) ? page : "feed";
-  const { Component: PageContent, maxWidth } = PAGE_CONTENT[activePage];
-  const railDef = channelView ? undefined : PAGE_RAIL[activePage];
-
-  return (
-    <div className="h-dvh flex text-fg">
-      <SkipLink label={t("nav.skipToContent")} />
-      <NavSidebar
-        me={me!}
-        onOpenAbout={() => setAboutOpen(true)}
-        onChangeLanguage={changeLanguage}
-        language={i18n.language as LangCode}
-      />
-      {/* The active page's side rail (feed filters / plex filters / playlists list), if it has one.
-          A floating collapsible column beside the nav rail; hidden while a channel page overlays the
-          content. feed + plex share the filter-rail collapse flag, playlists and files have their own. */}
-      {railDef && (
-        <Suspense fallback={null}>
-          <railDef.Rail
-            layout={panelLayouts[railDef.panelId]}
-            setLayout={(l) => setPanelLayout(railDef.panelId, l)}
-            collapsed={railCollapse[railDef.collapse][0]}
-            onToggleCollapse={() => {
-              const [collapsed, setCollapsed] = railCollapse[railDef.collapse];
-              setCollapsed(!collapsed);
-            }}
-          />
-        </Suspense>
-      )}
-      {/* `@container/appmain`: the floating header + its search box adapt to THIS column's width
-          (which shrinks when the filter sidebar is open), not the viewport — a viewport breakpoint
-          can't see the sidebar-driven narrowing. NB: `container-type: inline-size` implies
-          `contain: layout`, making this column a containing block for `position: fixed` descendants
-          too — safe today because floating-ui menus render via FloatingPortal (to document.body) and
-          the toasts below are absolute; keep any new fixed overlay inside here body-portalled. */}
-      <div className="@container/appmain relative flex-1 min-w-0 flex flex-col">
-        {channelView ? (
-          <PageShell scrollKey={`channel:${channelView.id}`}>
-            <Suspense fallback={pageFallback}>
-              <ChannelPage
-                key={channelView.id}
-                channelId={channelView.id}
-                initialName={channelView.name}
-                me={me!}
-                view={view}
-                setView={setView}
-                onShowInFeed={() => {
-                  // Keep the rest of the feed's filters — the point is "this channel, the way I
-                  // normally read": unwatched, my tags, my date window.
-                  // ADD to the picked set, don't replace it: channels OR together now, so arriving
-                  // from a second channel page should widen the feed, not silently drop the first.
-                  // Deduped — clicking it again for a channel already picked is a no-op.
-                  setFilters({
-                    ...filters,
-                    channelIds: [...new Set([...filters.channelIds, channelView.id])],
-                  });
-                  // setPage already leaves an open channel page and pushes a clean history entry.
-                  // Calling closeChannel() first ran history.back(), whose popstate landed AFTER this
-                  // and restored whatever page the channel had been opened from.
-                  setPage("feed");
-                }}
-              />
-            </Suspense>
-          </PageShell>
-        ) : (
-          <PageShell
-            title={t(pageTitleKey(activePage))}
-            scrollKey={normalScrollKey}
-            maxWidth={maxWidth}
-            header={<Header me={me!} onYtSearch={enterYtSearch} />}
-            banners={
-              <>
-                <VerifyBanner entry={verifyEntry} />
-                <VersionBanner onOpen={() => openReleaseNotes(FRONTEND_VERSION)} />
-              </>
-            }
-          >
-            <Suspense fallback={pageFallback}>
-              <PageContent />
-            </Suspense>
-          </PageShell>
-        )}
-        {/* Toasts rise from the bottom-left, by the notification bell in the nav rail.
-            Anchored inside the content column so they clear the sidebar automatically
-            (collapsed or expanded) without tracking its width. */}
-        <Toaster />
-        {/* The running downloads, bottom-right in the same column (the toasts keep the left). */}
-        <DownloadTray />
-      </div>
-      {/* The two app-wide overlays: the keyboard cheat sheet (`h`) and the jump-to palette (Mod+K).
-          Mounted once, outside the page area, so every surface answers "what can I press here" and
-          "take me to X" the same way. Their keys are bound by useGlobalKeymap above. */}
-      <KeyboardHelp />
-      <AppCommandPalette />
-      {/* The one download dialog: the Files link box, a link pasted onto any page, the palette. */}
-      <DownloadIntake />
-      {/* The debug recorder: its start dialog, and its pill docked under the toasts. */}
-      {me && <DebugRecorder />}
-      <Suspense fallback={null}>
-        {aboutOpen && (
-          <About
-            onClose={() => setAboutOpen(false)}
-            onOpenReleaseNotes={() => {
-              setAboutOpen(false);
-              openReleaseNotes();
-            }}
-          />
-        )}
-        {notesOpen && (
-          <ReleaseNotes onClose={() => setNotesOpen(false)} highlight={notesHighlight} />
-        )}
-      </Suspense>
-      <ErrorDialog />
-      {/* Re-binds to the active page's scroll container on navigation (page or channel change). */}
-      <BackToTop dep={channelView ? `chan:${channelView.id}` : page} />
-    </div>
-  );
-}

frontend/src/PlaylistEditFailures.dom.test.tsx

@@ -20,20 +20,20 @@ vi.mock("react-i18next", async (importOriginal) => {
     }),
   };
 });
-vi.mock("./confirmContext", () => ({ useConfirm: () => async () => true }));
+vi.mock("./components/ui/confirmContext", () => ({ useConfirm: () => async () => true }));
 const { notify } = vi.hoisted(() => ({
   notify: vi.fn((_n: { level: string; message: string }) => 0),
 }));
-vi.mock("../lib/notifications", async (importOriginal) => ({
-  ...(await importOriginal<typeof import("../lib/notifications")>()),
+vi.mock("./lib/notifications", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./lib/notifications")>()),
   notify,
 }));
 
-import PlexPlaylistView from "./PlexPlaylistView";
-import AddToPlaylist, { AddToPlaylistAt } from "./AddToPlaylist";
-import PlexPlaylistAdd from "./PlexPlaylistAdd";
-import TagManager from "./TagManager";
-import { api, HttpError, type PlexCard } from "../lib/api";
+import PlexPlaylistView from "./modules/plex/PlexPlaylistView";
+import AddToPlaylist, { AddToPlaylistAt } from "./features/video/AddToPlaylist";
+import PlexPlaylistAdd from "./features/plexCards/PlexPlaylistAdd";
+import TagManager from "./features/channel/TagManager";
+import { api, HttpError, type PlexCard } from "./lib/api";
 
 beforeAll(() => {
   class Stub {

frontend/src/WriteFailureReporting.dom.test.tsx

@@ -17,19 +17,19 @@ vi.mock("react-i18next", async (importOriginal) => {
     useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
   };
 });
-vi.mock("./confirmContext", () => ({ useConfirm: () => async () => true }));
+vi.mock("./components/ui/confirmContext", () => ({ useConfirm: () => async () => true }));
 const { notify } = vi.hoisted(() => ({
   notify: vi.fn((_n: { level: string; title?: string; message: string }) => 0),
 }));
-vi.mock("../lib/notifications", async (importOriginal) => ({
-  ...(await importOriginal<typeof import("../lib/notifications")>()),
+vi.mock("./lib/notifications", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./lib/notifications")>()),
   notify,
 }));
 
-import PlexCollectionEditor from "./PlexCollectionEditor";
-import UploadDialog from "./UploadDialog";
-import DownloadDialog from "./DownloadDialog";
-import { api, HttpError } from "../lib/api";
+import PlexCollectionEditor from "./modules/plex/PlexCollectionEditor";
+import UploadDialog from "./modules/files/UploadDialog";
+import DownloadDialog from "./features/downloads/DownloadDialog";
+import { api, HttpError } from "./lib/api";
 
 beforeAll(() => {
   class Stub {

frontend/src/compilerCoverage.contract.test.ts

@@ -26,15 +26,15 @@ const KNOWN_SKIPS: CompileReport["skipped"] = {
 // The files a regression hurt most: compiled, and they must stay so (a positive check too, so a
 // harness that compiled nothing could not pass as "no skips").
 const MUST_COMPILE: Record<string, string[]> = {
-  "components/Channels.tsx": ["Channels"],
+  "modules/channels/Channels.tsx": ["Channels"],
   "components/ui/DataTable.tsx": ["DataTable"],
   // Under every button and every popover in the app.
   "components/ui/FocusSafeButton.tsx": ["FocusSafeButton"],
   "components/ui/anchoredPopoverHooks.ts": ["useAnchoredPopover"],
   "components/ui/AnchoredPopover.tsx": ["PopoverSurfaceInner"],
   // The two players — the largest components here, and the last to compile.
-  "components/PlexPlayer.tsx": ["PlexPlayer"],
-  "components/PlayerModal.tsx": ["PlayerModal"],
+  "modules/plex/PlexPlayer.tsx": ["PlexPlayer"],
+  "features/player/PlayerModal.tsx": ["PlayerModal"],
   "lib/playerModalHooks.ts": ["useYtProgress"],
 };
 

frontend/src/compilerSkips.testkit.ts

@@ -7,7 +7,7 @@ import reactCompiler from "babel-plugin-react-compiler";
 // word (`panicThreshold` is "none" and the build has no logger), so this is the only place a skip is
 // visible at all. Used by compilerCoverage.contract.test.ts.
 
-const SRC = new URL("../", import.meta.url);
+const SRC = new URL("./", import.meta.url);
 
 /** Every file the production build compiles: src, minus tests and test kits. */
 export function shippedSources(): string[] {

frontend/src/components/Header.tsx

@@ -1,137 +0,0 @@
-import { forwardRef, type ReactNode } from "react";
-import { useTranslation } from "react-i18next";
-import { YouTubeIcon } from "../lib/brandIcons";
-import type { Me } from "../lib/api";
-import SearchBar from "./SearchBar";
-import { useFiles, useFilesActions } from "./filesContext";
-import PlexSearchBox from "./PlexSearchBox";
-import PlexScopeToggle from "./PlexScopeToggle";
-import PlexViewToggle from "./PlexViewToggle";
-import FeedScopeToggle from "./FeedScopeToggle";
-import SyncStatus from "./SyncStatus";
-import { useNavigation } from "./navigationContext";
-import { useFeedFilters, useFeedFiltersActions } from "./feedFiltersContext";
-import { usePlaylists, usePlaylistsActions } from "./playlistsContext";
-import { useChannels, useChannelsActions } from "./channelsContext";
-import { PaletteLauncher } from "./PaletteLauncher";
-
-// The floating top header: a row of glass pills over the content — the module's SearchBar where it
-// has one, and the per-user sync chip at the right end.
-// `forwardRef` so PageShell can attach a ref to the header's root box and measure its real (possibly
-// wrapped) height — that measurement + the `--hdr-h` content pad it drives live in PageShell, which
-// owns both the header slot and the padded content wrapper.
-const Header = forwardRef<
-  HTMLDivElement,
-  {
-    me: Me;
-    // Trigger a live YouTube search for the current term (feed only).
-    onYtSearch: (q: string) => void;
-  }
->(function Header({ me, onYtSearch }, ref) {
-  const { t } = useTranslation();
-  const { page } = useNavigation();
-  const filters = useFeedFilters();
-  const { setFilters } = useFeedFiltersActions();
-  // Each module's search term lives in its own provider (shared with that module's rail/content):
-  // playlists name filter, Plex search term, channels name filter. The channel sync chip's
-  // "go to full history" jump is a ChannelsProvider action.
-  const { search: playlistsSearch } = usePlaylists();
-  const { setSearch: setPlaylistsSearch } = usePlaylistsActions();
-  const { search: channelsSearch } = useChannels();
-  const { search: filesSearch } = useFiles();
-  const { setSearch: setFilesSearch } = useFilesActions();
-  const { setSearch: setChannelsSearch, goToFullHistory: onGoToFullHistory } = useChannelsActions();
-  // Drop input focus on Go/Enter for the live-filter modules (feed's Go escalates to YouTube).
-  const blur = () => (document.activeElement as HTMLElement | null)?.blur?.();
-
-  // Per-page SearchBar wiring — null for modules without a search.
-  // A page without a search field still gets the palette's entry (PaletteLauncher).
-  let search: ReactNode = <PaletteLauncher />;
-  if (page === "feed") {
-    const trimmed = filters.q.trim();
-    search = (
-      <SearchBar
-        value={filters.q}
-        placeholder={t("header.searchPlaceholder")}
-        onChange={(q) => {
-          // When a search first appears, rank the feed by relevance — set atomically with the
-          // query (race-free vs. per-keystroke updates). Only overrides the default "newest"
-          // sort; a custom sort the user chose is left alone. Cleared in Feed.
-          const startSearch = !filters.q.trim() && !!q.trim() && filters.sort === "newest";
-          setFilters({ ...filters, q, ...(startSearch ? { sort: "relevance" } : {}) });
-        }}
-        onGo={() => onYtSearch(trimmed)}
-        goLabel={t("header.searchYoutube")}
-        goTitle={t(
-          me.search_source === "api" ? "header.searchYoutubeTipApi" : "header.searchYoutubeTip",
-        )}
-        goIcon={<YouTubeIcon className="w-4 h-4" />}
-        goDisabled={!trimmed}
-      />
-    );
-  } else if (page === "plex" && me.plex_enabled) {
-    search = <PlexSearchBox />;
-  } else if (page === "channels") {
-    search = (
-      <SearchBar
-        value={channelsSearch}
-        placeholder={t("channels.searchPlaceholder")}
-        onChange={setChannelsSearch}
-        onGo={blur}
-      />
-    );
-  } else if (page === "files") {
-    search = (
-      <SearchBar
-        value={filesSearch}
-        placeholder={t("files.searchPlaceholder")}
-        onChange={setFilesSearch}
-        onGo={blur}
-      />
-    );
-  } else if (page === "playlists") {
-    search = (
-      <SearchBar
-        value={playlistsSearch}
-        placeholder={t("playlists.searchPlaceholder")}
-        onChange={setPlaylistsSearch}
-        onGo={blur}
-      />
-    );
-  }
-
-  return (
-    // Absolutely positioned within the (relative) content column, so its left edge tracks the
-    // actual left zone: it sits just inside the content, reclaiming the space when the nav rail is
-    // slim and/or no filter sidebar is present — no hard-coded offset.
-    <div
-      ref={ref}
-      // left-4 / right = 1rem + the scrollbar gutter defines the full content column; max-w-[--content-mw]
-      // + mx-auto then centres the header band on the SAME width the page's content uses, so on a max-width
-      // page (Plex/Channels/Playlists) the band lines up with the centred grid, not the whole column. `none`
-      // (feed) = full width. Matches the toolbar band below it. `justify-center` then centres the search-box
-      // group (search + scope toggle / sync chip) within that band, so the box sits centred over the cards
-      // once the column is wider than the box's max-w — not hugged to the left edge.
-      className="pointer-events-none absolute top-3 left-4 right-[calc(1rem+var(--sbw))] mx-auto max-w-[var(--content-mw,none)] z-chrome flex flex-wrap items-center justify-center gap-x-3 gap-y-2"
-    >
-      {search}
-      {/* Mine/Library scope sits right of the feed search box — relocated here from the filter sidebar
-          so the primary "what am I browsing" control is always in reach (mirrors Plex's scope toggle). */}
-      {page === "feed" && <FeedScopeToggle />}
-      {/* Library scope (movie/show/both) sits right of the search box on Plex — relocated here from
-          the filter sidebar so the primary "what am I browsing" control is always in reach. The
-          Discover ⟷ Browse toggle sits right beside it (driven via the PlexViewBridge). */}
-      {page === "plex" && me.plex_enabled && <PlexScopeToggle />}
-      {page === "plex" && me.plex_enabled && <PlexViewToggle />}
-      {/* Per-user sync status — it used to cost the nav rail a whole block. It sits with the other
-          pills rather than pinned to the far right: on a wide window that just strands it. Only on
-          the two modules it says anything about: the feed those subscriptions fill, and the manager
-          where you curate them. It's noise on Plex (a different source entirely), playlists, etc. */}
-      {(page === "feed" || page === "channels") && (
-        <SyncStatus isAdmin={me.role === "admin"} onGoToFullHistory={onGoToFullHistory} />
-      )}
-    </div>
-  );
-});
-
-export default Header;

frontend/src/components/PlexViewBridge.tsx

@@ -1,28 +0,0 @@
-import { useState, type ReactNode } from "react";
-import {
-  PlexViewPublishContext,
-  PlexViewReadContext,
-  type PlexViewControls,
-} from "./plexViewContext";
-
-// A one-way bridge so the always-mounted Header can host the Plex Discover ⟷ Browse toggle even though
-// the sub-view state lives in (and is owned by) the plex-only PlexBrowse. PlexBrowse PUBLISHES its
-// current top-level view + opener here (on mount and on view change) and clears it on unmount; the
-// Header READS it to render the toggle beside the library-scope pill.
-//
-// Why a bridge and not a global sub-view provider: PlexBrowse's `useHistorySubview` REMOUNTS every time
-// you enter the plex page, re-seeding the view from history (a page switch clears ?v + drops _sub, so
-// each plex entry starts at the Discover root). Lifting that hook to an always-mounted provider would
-// lose the remount and let the view go stale across navigation. Keeping it in PlexBrowse preserves the
-// reseed; the bridge only mirrors the small slice the header needs.
-//
-// The contexts + hooks live in plexViewContext.ts.
-
-export function PlexViewBridge({ children }: { children: ReactNode }) {
-  const [controls, setControls] = useState<PlexViewControls | null>(null);
-  return (
-    <PlexViewPublishContext.Provider value={setControls}>
-      <PlexViewReadContext.Provider value={controls}>{children}</PlexViewReadContext.Provider>
-    </PlexViewPublishContext.Provider>
-  );
-}

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

@@ -1,58 +0,0 @@
-// @vitest-environment jsdom
-//
-// The Settings prefs are seeded from the account's server prefs in the `me` cache — BootGate mounts the
-// tree only once it is there. The adopt effect this replaced corrected them AFTER mounting; with it
-// gone, a seed that read only this browser's copy would never show a performance mode or hints setting
-// changed on another device. And the seed is not an edit: it must not be saved straight back.
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { act, cleanup, render } from "@testing-library/react";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { PrefsProvider } from "./PrefsProvider";
-import { usePrefs } from "./prefsContext";
-import { api } from "../lib/api";
-import { ACTIVE_ACCOUNT_KEY } from "../lib/activeAccount";
-import { accountKey, LS } from "../lib/storage";
-import { qk } from "../lib/queryKeys";
-
-const seen: { perf: boolean; hints: boolean }[] = [];
-function Probe() {
-  const { perf, hints } = usePrefs();
-  seen.push({ perf, hints });
-  return null;
-}
-
-beforeEach(() => {
-  localStorage.clear();
-  sessionStorage.setItem(ACTIVE_ACCOUNT_KEY, "5");
-  seen.length = 0;
-  vi.useFakeTimers();
-});
-afterEach(() => {
-  cleanup();
-  vi.useRealTimers();
-  vi.restoreAllMocks();
-});
-
-describe("PrefsProvider seed", () => {
-  it("renders the account's server prefs from the first render, and does not save them back", () => {
-    localStorage.setItem(accountKey(LS.perfMode, 5)!, "0"); // this browser last had it off
-    localStorage.setItem(accountKey(LS.hints, 5)!, "1");
-    const save = vi.spyOn(api, "savePrefs").mockResolvedValue(undefined as never);
-    const qc = new QueryClient();
-    qc.setQueryData(qk.me(), { id: 5, preferences: { performanceMode: true, hints: false } });
-    render(
-      <QueryClientProvider client={qc}>
-        <PrefsProvider>
-          <Probe />
-        </PrefsProvider>
-      </QueryClientProvider>,
-    );
-
-    expect(seen[0]).toEqual({ perf: true, hints: false });
-    // past the auto-save debounce
-    act(() => {
-      vi.advanceTimersByTime(1000);
-    });
-    expect(save).not.toHaveBeenCalled();
-  });
-});

frontend/src/components/SavedViewsProvider.tsx

@@ -1,265 +0,0 @@
-import { useEffect, useEffectEvent, useMemo, useRef, useState, type ReactNode } from "react";
-import { useTranslation } from "react-i18next";
-import { useQuery, useQueryClient } from "@tanstack/react-query";
-import { qk } from "../lib/queryKeys";
-import {
-  api,
-  coercePlexFilters,
-  getActiveAccount,
-  plexFiltersSignature,
-  type FeedFilters,
-  type PlexFilters,
-  type SavedView,
-} from "../lib/api";
-import { filtersToParams, hasFilterParams } from "../lib/urlState";
-import { pickDefaultToSeed, preferSticky } from "../lib/savedViews";
-import { notifyActionError } from "../lib/actionErrors";
-import { accountKey, LS } from "../lib/storage";
-import { useConfirm } from "./confirmContext";
-import { useNavigation } from "./navigationContext";
-import { useFeedFilters, useFeedFiltersActions } from "./feedFiltersContext";
-import { usePlex, usePlexActions } from "./plexContext";
-import {
-  asFilters,
-  SavedViewsCtx,
-  type SavedViewsContext,
-  type ViewSource,
-} from "./savedViewsContext";
-
-// Saved "smart views" now serve TWO modules — the feed and Plex — keyed by `source`. This one provider
-// switches which module it operates on by the active page (both filter providers are global, so it can
-// read either), so the shared UI (popover / modal / chip) works on the feed page against feed views and
-// on the plex page against plex views without a second provider or an App-layout change.
-//
-// The context, its value type and the hook live in savedViewsContext.ts.
-
-// The per-source wiring the generic logic runs on: the live filters, how to apply a view's, a stable
-// signature for matching, coercion, and what to strip before saving (the feed's transient shuffle seed).
-interface ViewConfig {
-  source: ViewSource;
-  filters: Record<string, unknown>;
-  setFilters: (f: Record<string, unknown>) => void;
-  keyOf: (f: Record<string, unknown>) => string;
-  asFilters: (raw: Record<string, unknown>) => Record<string, unknown>;
-  stripForSave: (f: Record<string, unknown>) => Record<string, unknown>;
-  /** Whether this module is a genuinely fresh start the starred default may seed on first load: no
-   *  stored filters for the active account, and — feed only — no URL filter override. */
-  canSeedDefault: () => boolean;
-}
-
-const feedKeyOf = (f: Record<string, unknown>) =>
-  filtersToParams(asFilters(f as unknown as FeedFilters)).toString();
-const plexKeyOf = (f: Record<string, unknown>) => plexFiltersSignature(coercePlexFilters(f));
-
-// True once this account has its own persisted filters for `lsKey` — the signal that the last
-// view / manual tweaks (not the default) should win. Account unknown or localStorage unavailable →
-// report "stored" so a default never seeds blind over an indeterminate state.
-function storedFiltersPresent(lsKey: string): boolean {
-  const key = accountKey(lsKey, getActiveAccount());
-  if (!key) return true;
-  try {
-    return localStorage.getItem(key) != null;
-  } catch {
-    return true;
-  }
-}
-// Feed also yields to a URL that carries filter params (a shared/bookmarked view).
-function feedCanSeedDefault(): boolean {
-  if (hasFilterParams(new URLSearchParams(window.location.search))) return false;
-  return !storedFiltersPresent(LS.filters);
-}
-// Plex views are facets-only, so LS.plexFilters is the "has the user set this module's filters" key.
-function plexCanSeedDefault(): boolean {
-  return !storedFiltersPresent(LS.plexFilters);
-}
-
-export function SavedViewsProvider({ children }: { children: ReactNode }) {
-  const { t } = useTranslation();
-  const qc = useQueryClient();
-  const confirm = useConfirm();
-  const { page } = useNavigation();
-
-  // Both filter providers are global — read both, then use the one the active page owns.
-  const feedFilters = useFeedFilters();
-  const { setFilters: setFeedFilters } = useFeedFiltersActions();
-  const { filters: plexFilters } = usePlex();
-  const { setFilters: setPlexFilters } = usePlexActions();
-
-  const cfg: ViewConfig = useMemo(() => {
-    if (page === "plex") {
-      return {
-        source: "plex",
-        filters: plexFilters as unknown as Record<string, unknown>,
-        setFilters: (f) => setPlexFilters(f as unknown as PlexFilters),
-        keyOf: plexKeyOf,
-        asFilters: (raw) => coercePlexFilters(raw) as unknown as Record<string, unknown>,
-        stripForSave: (f) => f, // Plex has no transient field to drop
-        canSeedDefault: plexCanSeedDefault,
-      };
-    }
-    return {
-      source: "feed",
-      filters: feedFilters as unknown as Record<string, unknown>,
-      setFilters: (f) => setFeedFilters(f as unknown as FeedFilters),
-      keyOf: feedKeyOf,
-      asFilters: (raw) =>
-        asFilters(raw as unknown as FeedFilters) as unknown as Record<string, unknown>,
-      // Strip the transient shuffle seed so a saved "shuffle" view re-rolls fresh on apply.
-      stripForSave: (f) => {
-        const { seed: _seed, ...rest } = f;
-        return rest;
-      },
-      canSeedDefault: feedCanSeedDefault,
-    };
-  }, [page, feedFilters, plexFilters, setFeedFilters, setPlexFilters]);
-
-  const source = cfg.source;
-  // Passive observer of the account BootGate fetches: the providers mount for a signed-out tab too
-  // (the public landing), and saved views are per-account, so asking for "nobody's" views only logs
-  // a 401 on the landing page. Enabled once a signed-in account is cached.
-  const { data: me } = useQuery({ queryKey: qk.me(), queryFn: api.me, enabled: false });
-  const viewsQuery = useQuery({
-    queryKey: qk.savedViews(source),
-    queryFn: () => api.savedViews(source),
-    enabled: !!me,
-  });
-  const views = useMemo(() => viewsQuery.data ?? [], [viewsQuery.data]);
-
-  const [stickyId, setStickyId] = useState<number | null>(null);
-  const [modalOpen, setModalOpen] = useState(false);
-
-  // Switching modules (feed ⟷ plex) starts fresh: a feed view can't be the sticky/active one on plex,
-  // and a feed modal shouldn't linger open on plex. Adjusted DURING RENDER against the previous
-  // source rather than from an effect, so the first plex render never commits carrying the feed's
-  // sticky id — which is exactly long enough for a stale view chip to paint.
-  const [prevSource, setPrevSource] = useState(source);
-  if (prevSource !== source) {
-    setPrevSource(source);
-    setStickyId(null);
-    setModalOpen(false);
-  }
-
-  // The ONE default-application path for both modules. On the views query's FIRST resolve for a
-  // source, seed the starred default view's filters — but only into a genuinely fresh module (no
-  // stored filters, no URL override; see cfg.canSeedDefault). Applying via cfg.setFilters persists
-  // it, so it happens once and the normal last-view-wins path takes over, exactly as the storage
-  // semantics document. This replaced the feed-only localStorage mirror that raced FeedFiltersProvider's
-  // login effect (on a fresh browser the feed could seed DEFAULT_FILTERS and never re-apply until a
-  // reload) — and it gives Plex the default it previously never applied at all. Per-source guard so a
-  // 60s background refetch never re-seeds over the filters you're editing. canSeedDefault() reads the
-  // per-account stored-filters key, which is always readable here: BootGate pins the tab's account
-  // before this provider mounts.
-  const seededRef = useRef<Set<ViewSource>>(new Set());
-  // `cfg` re-memoizes on every filter edit, so it is read through an effect event: the seed must
-  // fire on the views query's first resolve for a source and never again, which `seededRef`
-  // enforces. Listing cfg would re-arm nothing (the guard still holds) but would re-run the effect
-  // on every keystroke in the filter bar.
-  const latestCfg = useEffectEvent(() => cfg);
-  useEffect(() => {
-    const data = viewsQuery.data;
-    if (!data || seededRef.current.has(source)) return;
-    seededRef.current.add(source);
-    const c = latestCfg();
-    const def = pickDefaultToSeed(data, c.canSeedDefault());
-    // The name follows by itself: `preferSticky` picks the starred default among same-filter views.
-    if (def) c.setFilters(c.asFilters(def.filters));
-  }, [viewsQuery.data, source]);
-
-  const currentKey = cfg.keyOf(cfg.filters);
-  const activeView = useMemo(
-    () =>
-      preferSticky(
-        views.filter((v) => cfg.keyOf(v.filters) === currentKey),
-        stickyId,
-      ),
-    [views, currentKey, stickyId, cfg],
-  );
-  // The sticky id follows whichever view is active — also adjusted during render. It converges by
-  // construction: preferSticky returns the sticky match when there is one, so the very write below
-  // makes its own condition false on the next pass.
-  if (activeView && activeView.id !== stickyId) setStickyId(activeView.id);
-
-  const stickyView = useMemo(
-    () => (stickyId == null ? null : (views.find((v) => v.id === stickyId) ?? null)),
-    [views, stickyId],
-  );
-  const displayView = activeView ?? stickyView;
-  const isDirty = displayView != null && activeView == null;
-
-  const refresh = () => void qc.invalidateQueries({ queryKey: qk.savedViews(source) });
-  async function runViewMutation(fn: () => Promise<unknown>, failMsg: string): Promise<boolean> {
-    let ok = true;
-    try {
-      await fn();
-    } catch (e) {
-      notifyActionError(e, failMsg);
-      ok = false;
-    }
-    refresh();
-    return ok;
-  }
-
-  const value: SavedViewsContext = {
-    source,
-    views,
-    loading: viewsQuery.isLoading,
-    activeViewId: activeView?.id ?? null,
-    displayView,
-    isDirty,
-    modalOpen,
-    openModal: () => setModalOpen(true),
-    closeModal: () => setModalOpen(false),
-    apply: (v) => {
-      cfg.setFilters(cfg.asFilters(v.filters));
-      setStickyId(v.id);
-    },
-    clearActive: () => setStickyId(null),
-    create: async (name) => {
-      const clean = name.trim();
-      if (!clean) return false;
-      return runViewMutation(
-        () => api.createView(clean, cfg.stripForSave(cfg.filters), source),
-        t("views.actionFailed"),
-      );
-    },
-    rename: async (id, name) => {
-      const next = name.trim();
-      if (!next) return false;
-      return runViewMutation(() => api.updateView(id, { name: next }), t("views.actionFailed"));
-    },
-    updateFilters: (id, filters) =>
-      runViewMutation(() => api.updateView(id, { filters }), t("views.actionFailed")),
-    saveCurrent: async (id) => {
-      const filters = cfg.stripForSave(cfg.filters);
-      const ok = await runViewMutation(
-        () => api.updateView(id, { filters }),
-        t("views.actionFailed"),
-      );
-      return ok ? filters : null;
-    },
-    toggleDefault: (v) =>
-      runViewMutation(
-        () => api.updateView(v.id, { is_default: !v.is_default }),
-        t("views.actionFailed"),
-      ).then(() => undefined),
-    remove: async (v) => {
-      const ok = await confirm({
-        message: t("views.deleteConfirm", { name: v.name }),
-        confirmLabel: t("views.delete"),
-        danger: true,
-      });
-      if (!ok) return false;
-      if (stickyId === v.id) setStickyId(null);
-      return runViewMutation(() => api.deleteView(v.id), t("views.actionFailed"));
-    },
-    reorder: async (nextIds) => {
-      qc.setQueryData<SavedView[]>(
-        qk.savedViews(source),
-        nextIds.map((id) => views.find((v) => v.id === id)!).filter(Boolean),
-      );
-      await runViewMutation(() => api.reorderViews(nextIds), t("views.reorderFailed"));
-    },
-  };
-
-  return <SavedViewsCtx.Provider value={value}>{children}</SavedViewsCtx.Provider>;
-}

frontend/src/components/legal/LegalLayout.tsx

@@ -12,7 +12,7 @@ import { useTranslation } from "react-i18next";
 import { setLanguage, type LangCode } from "../../i18n";
 import { formatDate } from "../../lib/format";
 import { send } from "../../lib/http";
-import LanguageSwitcher from "../LanguageSwitcher";
+import LanguageSwitcher from "../ui/LanguageSwitcher";
 import { SURFACE } from "../ui/surfaces";
 
 // The day the text last changed materially — bump it with every edit of either body.

frontend/src/components/moduleRegistry.tsx

@@ -1,102 +0,0 @@
-import type { ComponentType } from "react";
-import { lazyWithPreload, type PreloadableComponent } from "../lib/lazyWithPreload";
-import type { Page } from "../lib/urlState";
-import type { PanelId, PanelLayout } from "../lib/panelLayout";
-import Sidebar from "./Sidebar";
-import PlaylistsRail from "./PlaylistsRail";
-import { Feed, FeedPage } from "./modulePages";
-
-// The RENDER half of the module registry: which component (and side rail) each page renders. The
-// metadata half — nav order, label, icon, gate — lives in lib/modules.ts (imported by NavSidebar /
-// Header / App's gate check). Together they let App drive the whole shell from `page` alone, with no
-// `page === X` chrome conditionals.
-//
-// Every content entry is a PROP-FREE component: it reads `me` from useMe() and its module-local state
-// from the scoped providers, so App renders `<Content />` uniformly. The two that need per-render
-// wiring get a thin wrapper in modulePages (FeedPage supplies the GLOBAL feed scope; the channel page
-// threads its own isolated scope to <Feed> directly — see the scope note in FeedFiltersProvider).
-
-// Route-level code splitting: each page is its own lazy chunk (admin-only pages never reach
-// non-admins; the logged-out landing pulls only the shell). Rendered inside App's <Suspense>. Each
-// one is preloadable: App fetches the chunks of every page the account can reach once the first page
-// is on screen (preloadPages below), so switching modules never shows the chunk fallback.
-const Home = lazyWithPreload(() => import("./Home"));
-const Channels = lazyWithPreload(() => import("./Channels"));
-const Playlists = lazyWithPreload(() => import("./Playlists"));
-const PlexBrowse = lazyWithPreload(() => import("./PlexBrowse"));
-const PlexSidebar = lazyWithPreload(() => import("./PlexSidebar"));
-const NotificationsPanel = lazyWithPreload(() => import("./NotificationsPanel"));
-const Files = lazyWithPreload(() => import("./Files"));
-const FilesRail = lazyWithPreload(() => import("./FilesRail"));
-const Stats = lazyWithPreload(() => import("./Stats"));
-const Scheduler = lazyWithPreload(() => import("./Scheduler"));
-const ConfigPanel = lazyWithPreload(() => import("./ConfigPanel"));
-const AdminUsers = lazyWithPreload(() => import("./AdminUsers"));
-const Activity = lazyWithPreload(() => import("./Activity"));
-const SettingsPanel = lazyWithPreload(() => import("./SettingsPanel"));
-
-export type PageDef = {
-  // Prop-free by construction: reads `me` + module state from hooks/providers. Preloadable by type, so
-  // a new page cannot silently opt out of preloadPages.
-  Component: PreloadableComponent<object>;
-  // The content column's max width. The header + toolbar centre on this same width (via --content-mw)
-  // so the floating chrome lines up with the centred content instead of spanning the whole column.
-  // MUST match the max-w the page's own content wrapper uses. Omit for a full-width page (feed).
-  maxWidth?: string;
-};
-
-// page id → the component App renders in the content column (+ its shell chrome config).
-export const PAGE_CONTENT: Record<Page, PageDef> = {
-  home: { Component: Home, maxWidth: "80rem" },
-  // The two wrappers preload the lazy chunk they render.
-  feed: { Component: Object.assign(FeedPage, { preload: Feed.preload }) },
-  channels: { Component: Channels, maxWidth: "96rem" },
-  playlists: { Component: Playlists, maxWidth: "64rem" },
-  plex: { Component: PlexBrowse, maxWidth: "100rem" },
-  notifications: { Component: NotificationsPanel, maxWidth: "48rem" },
-  files: { Component: Files, maxWidth: "80rem" },
-  stats: { Component: Stats },
-  scheduler: { Component: Scheduler },
-  config: { Component: ConfigPanel },
-  users: { Component: AdminUsers, maxWidth: "48rem" },
-  activity: { Component: Activity },
-  settings: { Component: SettingsPanel },
-};
-
-// The uniform side-rail contract — shell layout/collapse only; the rail reads its module state from
-// its provider and `me` from useMe().
-type RailProps = {
-  layout: PanelLayout;
-  setLayout: (l: PanelLayout) => void;
-  collapsed: boolean;
-  onToggleCollapse: () => void;
-};
-
-// Which collapse flag a rail uses (feed + plex share the filter rail's flag; playlists and files
-// have their own).
-type RailCollapseKey = "filter" | "playlists" | "files";
-
-export type RailDef = {
-  Rail: ComponentType<RailProps>;
-  // The persisted panel-layout record this rail edits (App owns the panelLayouts map).
-  panelId: PanelId;
-  collapse: RailCollapseKey;
-};
-
-// page id → its side rail (only the pages that have one). App renders it in the rail slot.
-export const PAGE_RAIL: Partial<Record<Page, RailDef>> = {
-  feed: { Rail: Sidebar, panelId: "feed", collapse: "filter" },
-  plex: { Rail: PlexSidebar, panelId: "plex", collapse: "filter" },
-  playlists: { Rail: PlaylistsRail, panelId: "playlists", collapse: "playlists" },
-  files: { Rail: FilesRail, panelId: "files", collapse: "files" },
-};
-
-/** Fetch the code of these pages and of their side rails now, ahead of their first visit. Errors are
- *  swallowed: a chunk that fails to preload is simply fetched (and its failure surfaced) on visit. */
-export function preloadPages(pages: Page[]): void {
-  for (const p of pages) {
-    PAGE_CONTENT[p].Component.preload().catch(() => {});
-    const rail = PAGE_RAIL[p]?.Rail as Partial<PreloadableComponent<RailProps>> | undefined;
-    rail?.preload?.().catch(() => {});
-  }
-}

frontend/src/components/plexViewContext.ts

@@ -1,15 +0,0 @@
-import { createContext, useContext } from "react";
-import { type Sub } from "./plexSubUrl";
-
-// The read + publish sides of the Plex view bridge (see PlexViewBridge for why it is a bridge), split
-// out of that file so it exports only components (Fast Refresh).
-export type PlexViewControls = {
-  kind: Sub["kind"]; // the current top-level plex view — the header controls derive their state from it
-  open: (v: Sub) => void;
-};
-
-export const PlexViewReadContext = createContext<PlexViewControls | null>(null);
-export const PlexViewPublishContext = createContext<(c: PlexViewControls | null) => void>(() => {});
-
-export const usePlexViewControls = () => useContext(PlexViewReadContext);
-export const usePublishPlexView = () => useContext(PlexViewPublishContext);

frontend/src/components/prefsContext.ts

@@ -1,25 +0,0 @@
-import { createContext, useContext } from "react";
-import { DEFAULT_THEME } from "../lib/theme";
-import { getNotifSettings } from "../lib/notifications";
-import type { PrefsController } from "./SettingsPanel";
-
-// The Settings-page preferences context + hook, split out of PrefsProvider so that file exports only
-// components (Fast Refresh).
-
-export const PrefsContext = createContext<PrefsController>({
-  theme: DEFAULT_THEME,
-  setTheme: () => {},
-  perf: false,
-  setPerf: () => {},
-  hints: true,
-  setHints: () => {},
-  railLabels: false,
-  setRailLabels: () => {},
-  notif: getNotifSettings(),
-  setNotif: () => {},
-  saveState: "idle",
-});
-
-export function usePrefs(): PrefsController {
-  return useContext(PrefsContext);
-}

frontend/src/components/ui/ConfirmProvider.tsx

@@ -1,7 +1,7 @@
 import { useCallback, useState, type ReactNode } from "react";
 import { useTranslation } from "react-i18next";
-import Modal, { ModalFooter } from "./ui/Modal";
-import { Button } from "./ui/Button";
+import Modal, { ModalFooter } from "./Modal";
+import { Button } from "./Button";
 import { ChoiceContext, type ChoiceFn, type ChoiceOptions } from "./confirmContext";
 
 // The dialog behind useConfirm()/useChoice() (see confirmContext.ts for the hooks and their contract).

frontend/src/components/ui/FilterRail.tsx

@@ -1,18 +1,18 @@
 import { useState, type ReactNode } from "react";
 import { useTranslation } from "react-i18next";
-import { defaultLayout, type PanelId, type PanelLayout } from "../lib/panelLayout";
-import SidePanel from "./ui/SidePanel";
-import PanelGroups, { type PanelItem } from "./ui/PanelGroups";
+import { type PanelLayout } from "../../lib/panelLayout";
+import SidePanel from "./SidePanel";
+import PanelGroups, { type PanelItem } from "./PanelGroups";
 
 // The shared filter-rail shell, extracted from the three rails that all render the same SidePanel
 // chrome around a PanelGroups body: the feed Sidebar, the PlexSidebar, and the PlaylistsRail. It owns
 // the customize (reorder/hide) `editing` state and the fixed title-bar wiring (edit toggle, reset to
 // the layout default, edit hint); each rail supplies only what actually differs — its identity
 // (title/icon), the active-filter count + Clear-all action, its `items`, and any content below the
-// groups (`children`, e.g. the feed's tag manager). `kind` is the PanelId (also the layout key), so
-// `children` defaults to nothing for the rails that need none.
+// groups (`children`, e.g. the feed's tag manager; nothing for the rails that need none). What Reset
+// goes back to is the rail's (`onResetLayout`, from lib/useRail), so this shell names no page.
 export default function FilterRail({
-  kind,
+  onResetLayout,
   title,
   icon,
   count,
@@ -28,7 +28,8 @@ export default function FilterRail({
   titleActionLabel,
   children,
 }: {
-  kind: PanelId;
+  /** Puts the groups back in the rail's default order (lib/useRail's `onResetLayout`). */
+  onResetLayout: () => void;
   title: string;
   icon: ReactNode;
   count?: number;
@@ -56,7 +57,7 @@ export default function FilterRail({
       onToggleCollapse={onToggleCollapse}
       editing={editing}
       onToggleEditing={() => setEditing((e) => !e)}
-      onReset={() => setLayout(defaultLayout(kind))}
+      onReset={onResetLayout}
       editHint={t("sidebar.editHint")}
       actions={actions}
       iconExpanded={iconExpanded}

frontend/src/components/ui/LanguageSwitcher.tsx

@@ -1,12 +1,12 @@
 import { useState } from "react";
 import { Globe } from "lucide-react";
-import { MenuCheck } from "./ui/MenuCheck";
-import { LANGUAGES, type LangCode } from "../i18n";
-import { PopoverItem, PopoverSurface } from "./ui/AnchoredPopover";
-import { useAnchoredPopover } from "./ui/anchoredPopoverHooks";
-import { Pressable } from "./ui/Pressable";
-import { RAIL_GLYPH, RAIL_ROW } from "./ui/NavRail";
-import { SURFACE } from "./ui/surfaces";
+import { MenuCheck } from "./MenuCheck";
+import { LANGUAGES, type LangCode } from "../../i18n";
+import { PopoverItem, PopoverSurface } from "./AnchoredPopover";
+import { useAnchoredPopover } from "./anchoredPopoverHooks";
+import { Pressable } from "./Pressable";
+import { RAIL_GLYPH, RAIL_ROW } from "./NavRail";
+import { SURFACE } from "./surfaces";
 
 // Compact language picker (globe + current code). Presentational: the parent decides what
 // changing the language does (set it; persist server-side when signed in).

frontend/src/components/ui/NavRail.dom.test.tsx

@@ -119,7 +119,7 @@ describe("NavRailAction", () => {
   });
 
   it("the nav rail holds no toolbar icon button", () => {
-    const src = readFileSync(resolve(__dirname, "../NavSidebar.tsx"), "utf8");
+    const src = readFileSync(resolve(__dirname, "../../shell/NavSidebar.tsx"), "utf8");
     expect(src).not.toMatch(/<IconButton[\s>]/);
   });
 });

frontend/src/components/ui/PageShell.header.dom.test.tsx

@@ -0,0 +1,176 @@
+// @vitest-environment jsdom
+//
+// The floating header knows no page: a page fills it through PageHeader (a portal into the header's
+// root box), and the shell's PageHeaderDefault shows only while no page does. These pin the slot's
+// three promises: the page's pills land IN the header, the default steps aside for them and comes
+// back when the next page has none, and a shell without a header (the channel page) renders the
+// page's pills nowhere.
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { render, cleanup, screen } from "@testing-library/react";
+import PageShell, { PageHeader, PageHeaderDefault } from "./PageShell";
+
+vi.mock("./PageScroller", () => ({
+  default: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+}));
+
+beforeEach(() => {
+  vi.stubGlobal(
+    "ResizeObserver",
+    class {
+      observe() {}
+      disconnect() {}
+    },
+  );
+});
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+const hdr = <div data-testid="hdr" />;
+const fallback = (
+  <PageHeaderDefault>
+    <span>default</span>
+  </PageHeaderDefault>
+);
+
+describe("the header slot", () => {
+  it("puts a page's pills inside the header box", () => {
+    render(
+      <PageShell header={hdr}>
+        <PageHeader>
+          <span>search</span>
+        </PageHeader>
+      </PageShell>,
+    );
+    expect(screen.getByTestId("hdr").textContent).toBe("search");
+  });
+
+  it("shows the default on a page with no header of its own", () => {
+    render(<PageShell header={hdr}>{fallback}</PageShell>);
+    expect(screen.getByTestId("hdr").textContent).toBe("default");
+  });
+
+  it("hides the default while a page fills the header, and brings it back on the next page", () => {
+    const page = (own: boolean) => (
+      <PageShell header={hdr}>
+        {own && (
+          <PageHeader>
+            <span>search</span>
+          </PageHeader>
+        )}
+        {fallback}
+      </PageShell>
+    );
+    const { rerender } = render(page(true));
+    expect(screen.getByTestId("hdr").textContent).toBe("search");
+    rerender(page(false));
+    expect(screen.getByTestId("hdr").textContent).toBe("default");
+    rerender(page(true));
+    expect(screen.getByTestId("hdr").textContent).toBe("search");
+  });
+
+  it("keeps the default hidden while one of two PageHeaders on a page remains", () => {
+    const page = (both: boolean) => (
+      <PageShell header={hdr}>
+        <PageHeader>
+          <span>search</span>
+        </PageHeader>
+        {both && (
+          <PageHeader>
+            <span>toggle</span>
+          </PageHeader>
+        )}
+        {fallback}
+      </PageShell>
+    );
+    const { rerender } = render(page(true));
+    rerender(page(false));
+    expect(screen.getByTestId("hdr").textContent).toBe("search");
+  });
+
+  it("pads the content by the filled header before paint, not when the observer catches up", () => {
+    // jsdom does no layout: the header's height here is one 40px row per pill in it. The observer
+    // never fires in this test, so only a measurement made as the pills arrive can see them.
+    const height = (el: HTMLElement) => 40 * el.childElementCount;
+    const page = (own: boolean) => (
+      <PageShell header={hdr}>
+        {own && (
+          <PageHeader>
+            <span>search</span>
+            <span>scope</span>
+          </PageHeader>
+        )}
+        {fallback}
+      </PageShell>
+    );
+    const { rerender, container } = render(<PageShell header={hdr}>{null}</PageShell>);
+    Object.defineProperty(screen.getByTestId("hdr"), "offsetHeight", {
+      get() {
+        return height(this as HTMLElement);
+      },
+      configurable: true,
+    });
+    const pad = () =>
+      (container.querySelector('[class*="pt-(--hdr-h)"]') as HTMLElement).style.getPropertyValue(
+        "--hdr-h",
+      );
+    rerender(page(false));
+    expect(pad()).toBe("44px"); // the default alone: one row
+    rerender(page(true));
+    expect(pad()).toBe("84px"); // the page's two pills, the default gone
+  });
+
+  it("re-measures when one page's pills replace another's in the same commit", () => {
+    // Feed → Playlists: the leaving page's claim and the arriving page's land in one commit, so the
+    // number of claims never changes — the pad must follow the new pills all the same.
+    const height = (el: HTMLElement) => 40 * el.childElementCount;
+    const Feed = () => (
+      <PageHeader>
+        <span>search</span>
+        <span>scope</span>
+      </PageHeader>
+    );
+    const Playlists = () => (
+      <PageHeader>
+        <span>search</span>
+      </PageHeader>
+    );
+    const page = (which: "feed" | "playlists") => (
+      <PageShell header={hdr}>
+        {which === "feed" ? <Feed /> : <Playlists />}
+        {fallback}
+      </PageShell>
+    );
+    const { rerender, container } = render(<PageShell header={hdr}>{null}</PageShell>);
+    Object.defineProperty(screen.getByTestId("hdr"), "offsetHeight", {
+      get() {
+        return height(this as HTMLElement);
+      },
+      configurable: true,
+    });
+    const pad = () =>
+      (container.querySelector('[class*="pt-(--hdr-h)"]') as HTMLElement).style.getPropertyValue(
+        "--hdr-h",
+      );
+    rerender(page("feed"));
+    expect(pad()).toBe("84px");
+    rerender(page("playlists"));
+    expect(pad()).toBe("44px");
+    rerender(page("feed"));
+    expect(pad()).toBe("84px");
+  });
+
+  it("renders a page's pills nowhere in a shell without a header", () => {
+    render(
+      <PageShell>
+        <PageHeader>
+          <span>search</span>
+        </PageHeader>
+        {fallback}
+      </PageShell>,
+    );
+    expect(screen.queryByText("search")).toBeNull();
+    expect(screen.queryByText("default")).toBeNull();
+  });
+});

frontend/src/components/ui/PageShell.tsx

@@ -13,6 +13,7 @@ import {
 import { createPortal } from "react-dom";
 import PageScroller from "./PageScroller";
 import { PageToolbarSlot } from "./pageToolbarSlot";
+import { PageHeaderSlot } from "./pageHeaderSlot";
 import { PageHeadingProvider } from "./pageHeading";
 import { PageMenuSlot, type PageMenuOpener } from "./pageMenuSlot";
 import { isBackgroundPoint } from "../../lib/backgroundTarget";
@@ -29,6 +30,31 @@ export function PageToolbar({ children }: { children: ReactNode }) {
   return slot ? createPortal(children, slot) : null;
 }
 
+// A page renders its controls in the floating header (its search box, scope toggles, sync chip)
+// through this, the same way as PageToolbar: a portal, so the controls stay in the page's own React
+// subtree and reach its state directly (Plex's toggles drive the sub-view that lives in PlexBrowse).
+// The header itself knows no page. Claiming the header hides the shell's default (PageHeaderDefault).
+export function PageHeader({ children }: { children: ReactNode }) {
+  const slot = useContext(PageHeaderSlot);
+  const claim = slot?.claim;
+  useLayoutEffect(() => claim?.(), [claim]);
+  return slot?.target ? createPortal(children, slot.target) : null;
+}
+
+// What the header shows on a page that renders no PageHeader of its own (the palette's entry). App
+// renders it beside the page, inside the page's Suspense, so a page still loading shows no default
+// that its own controls would replace a moment later.
+export function PageHeaderDefault({ children }: { children: ReactNode }) {
+  const slot = useContext(PageHeaderSlot);
+  const shown = !!slot?.target && !slot.claimed;
+  const showDefault = slot?.showDefault;
+  useLayoutEffect(() => {
+    showDefault?.(shown);
+    return () => showDefault?.(false);
+  }, [shown, showDefault]);
+  return shown && slot?.target ? createPortal(children, slot.target) : null;
+}
+
 // The page shell: the fixed chrome around a single scrollable content region. It formalizes "what
 // is fixed vs what scrolls" per module, so the chrome App used to hand-assemble around every page
 // (a floating Header + a top-padded wrapper + PageScroller, plus the channel page's separate
@@ -38,6 +64,7 @@ export function PageToolbar({ children }: { children: ReactNode }) {
 //  - `header`  — floats (absolute, height `var(--hdr-h)`) over the content column; the wrapper pads
 //                its top by that height so nothing hides under it. Omit it (channel page) → no pad
 //                and no fixed top band, so the module's own banner can scroll from the very top.
+//                The header is an empty band: the page fills it through PageHeader.
 //  - `title`   — the page's name as a visually hidden `h1` (B4): the nav rail and the tab title are
 //                the visible identity, and a screen reader still lands on a named page. A view that
 //                shows its own title renders it through `PageHeading`, and this one steps aside.
@@ -123,6 +150,29 @@ export default function PageShell({
   // the measurement to the live node re-runs it every time the header mounts/unmounts, so it stays correct.
   const [headerEl, setHeaderEl] = useState<HTMLDivElement | null>(null);
   const [contentEl, setContentEl] = useState<HTMLDivElement | null>(null);
+  // How many PageHeaders fill the header right now: a count, not a flag, so of two on one page the one
+  // that leaves releases only its own claim.
+  const [headerClaims, setHeaderClaims] = useState(0);
+  // Bumped by every claim and every release. The count alone cannot say the pills changed: when one
+  // page's PageHeader replaces another's in one commit (feed → playlists), the release and the claim
+  // net to the same count, and the measurement below would not re-run.
+  const [headerGeneration, setHeaderGeneration] = useState(0);
+  const claimHeader = useCallback(() => {
+    setHeaderClaims((n) => n + 1);
+    setHeaderGeneration((g) => g + 1);
+    return () => {
+      setHeaderClaims((n) => n - 1);
+      setHeaderGeneration((g) => g + 1);
+    };
+  }, []);
+  // Whether the shell's default is in the header (PageHeaderDefault reports it).
+  const [defaultShown, setDefaultShown] = useState(false);
+  // The pills arrive by portal AFTER this shell mounted (with the page's chunk), so the first measurement
+  // saw an empty header; the ResizeObserver catches up only a frame or more later, and until then the
+  // content sat under the pills (the feed toolbar jumped 55px on a tablet). So the measurement also re-runs
+  // here, before paint, whenever what fills the header changes (a claim made or released, the default
+  // shown or gone); the observer still covers a change within a page's own pills (Plex's view switch
+  // appearing).
   useLayoutEffect(() => {
     if (!headerEl || !contentEl) {
       // No header (channel page) → drop any stale pad so a leftover value can't linger.
@@ -136,7 +186,13 @@ export default function PageShell({
     const ro = new ResizeObserver(apply);
     ro.observe(headerEl);
     return () => ro.disconnect();
-  }, [headerEl, contentEl]);
+  }, [headerEl, contentEl, headerGeneration, defaultShown]);
+  const headerSlot = {
+    target: headerEl,
+    claimed: headerClaims > 0,
+    claim: claimHeader,
+    showDefault: setDefaultShown,
+  };
   // How many views below render their own page `h1` right now (see ./pageHeading).
   const [ownHeadings, setOwnHeadings] = useState(0);
   const registerOwnHeading = useCallback(() => {
@@ -173,26 +229,28 @@ export default function PageShell({
     : header;
   return (
     <PageToolbarSlot.Provider value={toolbarSlot}>
-      <PageMenuSlot.Provider value={registerPageMenu}>
-        <PageHeadingProvider value={registerOwnHeading}>
-          {measuredHeader}
-          <div
-            ref={setContentEl}
-            className={`flex-1 min-w-0 min-h-0 flex flex-col ${header ? "pt-(--hdr-h)" : ""}`}
-            onPointerDown={(e) => {
-              lastPointer.current = e.pointerType;
-            }}
-            onContextMenu={onContextMenu}
-          >
-            {title && ownHeadings === 0 && <h1 className="sr-only">{title}</h1>}
-            {banners}
-            {/* pr-[--sbw]: the toolbar band isn't the scroller, so without this it would run the
+      <PageHeaderSlot.Provider value={headerSlot}>
+        <PageMenuSlot.Provider value={registerPageMenu}>
+          <PageHeadingProvider value={registerOwnHeading}>
+            {measuredHeader}
+            <div
+              ref={setContentEl}
+              className={`flex-1 min-w-0 min-h-0 flex flex-col ${header ? "pt-(--hdr-h)" : ""}`}
+              onPointerDown={(e) => {
+                lastPointer.current = e.pointerType;
+              }}
+              onContextMenu={onContextMenu}
+            >
+              {title && ownHeadings === 0 && <h1 className="sr-only">{title}</h1>}
+              {banners}
+              {/* pr-[--sbw]: the toolbar band isn't the scroller, so without this it would run the
               scrollbar-gutter's width past the scrolled cards on the right. Pad it back to card width. */}
-            <div ref={setToolbarSlot} className="shrink-0 pr-[var(--sbw)]" />
-            <PageScroller scrollKey={scrollKey}>{children}</PageScroller>
-          </div>
-        </PageHeadingProvider>
-      </PageMenuSlot.Provider>
+              <div ref={setToolbarSlot} className="shrink-0 pr-[var(--sbw)]" />
+              <PageScroller scrollKey={scrollKey}>{children}</PageScroller>
+            </div>
+          </PageHeadingProvider>
+        </PageMenuSlot.Provider>
+      </PageHeaderSlot.Provider>
     </PageToolbarSlot.Provider>
   );
 }

frontend/src/components/ui/README.md

@@ -1,7 +1,7 @@
 # `components/ui/` — the platform layer
 
 Everything in this directory is a **platform component**: generic, reusable, and **domain-free**.
-Everything in `components/` above it is a **module component**: it knows about videos, channels,
+Everything above it — `features/`, `modules/` and `shell/` under `src/` — knows about videos, channels,
 playlists, Plex or downloads.
 
 That boundary is the whole point of this directory. Before E10 S1 these 33 modules sat flat among
@@ -18,9 +18,9 @@ A component belongs here **iff its props and imports name no domain concept**. I
 - generic helpers from `lib/` (`layerStack`, `history`, `columnSort`, `useScrollFade`, …),
 - i18n, React, and third-party UI libraries.
 
-It may **not** import a feature component (`../Feed`) or a domain API slice (`lib/api/*`). This is
-enforced by `no-restricted-imports` in `eslint.config.js` — not by this README, which is only the
-explanation. If a primitive needs domain data, take it as a prop or a render-prop and let the module
+It may **not** import anything from `features/`, `modules/` or `shell/`, or a domain API slice
+(`lib/api/*`). This is enforced in `eslint.config.js` (`no-restricted-imports` and `local/layers`) — not
+by this README, which is only the explanation. If a primitive needs domain data, take it as a prop or a render-prop and let the module
 supply it. The same goes for its words: a primitive translates only from the platform i18n
 namespaces (`common`, `errors`, `datatable`, `keys`, `palette`, `sidebar`, `notifications`, `time` —
 `uiI18n.contract.test.ts`); what a value means where it is used arrives as a prop (`PriorityStepper`'s
@@ -35,13 +35,13 @@ Counter-examples, deliberately NOT here: `PosterTile` (knows about Plex montage
 
 ## What lives here
 
-| area                   | components                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| overlays & anchoring   | `AnchoredPopover` + `anchoredPopoverHooks` (the popover engine: arrows, typeahead, Escape, anchor-flip), `ActionMenu`, `MembershipMenu` (the body of a "which sets is it in" menu: checkbox rows + a field naming a new set), `ContextMenu` + `useContextMenu` (the SAME menu, opened by right-click / long-press / Shift+F10 / a row's `MoreButton` "…" via `buttonProps`; `anchor` for a panel a row opens; `PageMenu` for a page's background menu), `Modal` (+ `ModalFooter`; `initialFocus` by purpose, C4), `Overlay`, `SidePanel`, `Tooltip`, `Toaster` (+ `toastLevels`, `overlayOrder`; `lib/toastDock` docks one control under the stack, in every host), `CommandPalette`, `KeyboardHelp`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| actions & inputs       | `Button`, `IconButton`, `Pressable` (`selectable` when its text is a title or a name), `Chip` + `chipStyles`, `DragHandle` + `OrderButtons` / `useOrderItems` (the non-drag reorder, WCAG 2.5.7) (one per button family, docs/DESIGN.md; a raw `<button>` or a bare `FocusSafeButton` outside the control primitives — eslint `BUTTON_PRIMITIVES` — is a lint error), `Input` + `fieldStyles`, `RenameField` (a name typed in place of the name: Enter or blur saves, Escape cancels; the caller hands the keyboard back), `Meter` (how full something is against a limit — one danger line for every place showing the same measure), `TimecodeField` + `useTimecodeField` / `TimecodeError` (a cut's time typed in: the draft, held by the caller, until Enter or blur takes it, then the value as it landed; unreadable stays once offered, marked invalid, and the caller places the line saying how to type one in its flow, outside a label; a draft goes when the value moves under it), `NativeControls`, `MenuCheck` (the drawn check of a menu row or a whole-row checkbox button; its tick is the `chosen` colour, which `media-marks` turns amber on the player chrome), `mediaChrome` (`MEDIA_CHOSEN`, a chosen tab or toggle on the chrome), `SelectTrigger` (the field family; a raw `<input>` is a lint error), `useReturnFocus`, `surfaces` (the B5 glass roles; a bare glass class is a lint error), `Badge` (a static label), `LinkButton` / `IconLink` (a link wearing the button face) over `buttonStyles`, `Skeleton` (B8 first loads, through `LoadingState shape`), `NavRail` (B7; `NavRailGroup` folds a set of rare pages into one row with a panel), `form`, `DraftSaveBar`, `Combobox`, `FilterSelect`, `SegmentedToggle`, `SortControl`, `ColumnSortControl`, `PriorityStepper`, `UndoToolbar` |
-| data display           | `DataTable` (+ `progressiveRows`: a long page mounts in steps), `tableHeader` + `tableAlign`, `HiddenFilterCue` (names a filter whose column is off screen), `Pager` + `pagerContent`, `VirtualGrid` + `gridColumns` (the column/width maths, incl. the ultrawide `maxCols` cap), `readAhead`, `Carousel`, `MediaCard` + `mediaCardStyles` (the one media card, docs/DESIGN.md "Media card") + `MediaPreview` / `useMediaPreview` (its mouse-rest preview), `NavGrid` (a plain grid, list or table body the keyboard walks — `DataTable`, `VirtualGrid` and `Carousel` take `keyboardNav`), `RemoteImage` (every network picture: no Referer, retries past the negative cache, a fallback instead of the broken-image mark — a bare `<img>` is linted out), `Avatar`, `CountBadge`, `ItemCount`, `FilterChipGroup`, `RelativeTime` ("3d ago" with the exact minute on hover, docs/DESIGN.md "Copy"), `ClampedText` (a long text clamped to a few lines; More / Less only when it is cut), `StatTiles` + `StatTile` / `StatBars` (number tiles, a breakdown as horizontal bars), `RangeTrack` + `RulerTicks` (a time track over a window of a media item: regions, slider ends the arrows step, a playhead, a background slot — the editor's cuts, the players' clip panel), `CropFrame` (a crop frame over a picture, on the picture and not its bars: drag, edges, corners, the arrows; the editor's crop, the players' clip crop)                                                                                                                                                                                                                                                                                                                                                                                         |
-| page & panel structure | `PageShell` + `pageToolbarSlot` + `pageHeading`, `PageScroller`, `Headings` (`PageHeading`, `SectionLabel`), `SkipLink` + `landmarks`, `FilterFold` (B4), `scrollFold` (`useScrollFold`: a fixed header that folds once its content scrolls), `PanelGroup`, `PanelGroups`, `Tabs`, `BackToTop`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| state & messaging      | `QueryState`, `Banner`, `InlineNotice`, `CrashBoundary`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| area                   | components                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| overlays & anchoring   | `AnchoredPopover` + `anchoredPopoverHooks` (the popover engine: arrows, typeahead, Escape, anchor-flip), `ActionMenu`, `MembershipMenu` (the body of a "which sets is it in" menu: checkbox rows + a field naming a new set), `ContextMenu` + `useContextMenu` (the SAME menu, opened by right-click / long-press / Shift+F10 / a row's `MoreButton` "…" via `buttonProps`; `anchor` for a panel a row opens; `PageMenu` for a page's background menu), `Modal` (+ `ModalFooter`; `initialFocus` by purpose, C4), `Overlay`, `SidePanel`, `Tooltip`, `Toaster` (+ `toastLevels`, `overlayOrder`; `lib/toastDock` docks one control under the stack, in every host), `CommandPalette`, `KeyboardHelp`, `ConfirmProvider` + `confirmContext` (`useConfirm` / `useChoice`: the app's promise-based confirm, mounted once at the root; a decision with more than two outcomes is one `useChoice`, never two chained confirms), `dialogFocus` (the focus half of the dialog contract: `Modal`'s, and the wizard's own shell), `menuGroups` (one menu from its groups, a rule only between non-empty ones), `pageMenuSlot` + `pageMenuItems` (a page's background menu, mirroring its own toolbar)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| actions & inputs       | `Button`, `IconButton`, `Pressable` (`selectable` when its text is a title or a name), `Chip` + `chipStyles`, `DragHandle` + `OrderButtons` / `useOrderItems` (the non-drag reorder, WCAG 2.5.7) (one per button family, docs/DESIGN.md; a raw `<button>` or a bare `FocusSafeButton` outside the control primitives — eslint `BUTTON_PRIMITIVES` — is a lint error), `Input` + `fieldStyles`, `RenameField` (a name typed in place of the name: Enter or blur saves, Escape cancels; the caller hands the keyboard back), `Meter` (how full something is against a limit — one danger line for every place showing the same measure), `TimecodeField` + `useTimecodeField` / `TimecodeError` (a cut's time typed in: the draft, held by the caller, until Enter or blur takes it, then the value as it landed; unreadable stays once offered, marked invalid, and the caller places the line saying how to type one in its flow, outside a label; a draft goes when the value moves under it), `NativeControls`, `MenuCheck` (the drawn check of a menu row or a whole-row checkbox button; its tick is the `chosen` colour, which `media-marks` turns amber on the player chrome), `mediaChrome` (`MEDIA_CHOSEN`, a chosen tab or toggle on the chrome), `SelectTrigger` (the field family; a raw `<input>` is a lint error), `useReturnFocus`, `surfaces` (the B5 glass roles; a bare glass class is a lint error), `Badge` (a static label), `LinkButton` / `IconLink` (a link wearing the button face) over `buttonStyles`, `Skeleton` (B8 first loads, through `LoadingState shape`), `NavRail` (B7; `NavRailGroup` folds a set of rare pages into one row with a panel), `form`, `DraftSaveBar`, `Combobox`, `FilterSelect`, `SegmentedToggle`, `SortControl`, `ColumnSortControl`, `PriorityStepper`, `UndoToolbar`, `ViewSwitcher` (a list's display modes behind one toolbar icon), `copyItems` (`useCopyItems`: the "Copy title" / "Copy link" rows every object's menu ends with) + `useCopyFeedback` (a Copy button's "Copied" moment), `MatchToggle` (a multi-value filter's any/all switch), `LanguageSwitcher` (presentational: the caller decides what a change does), `sortableA11y` (what a screen reader hears during a keyboard reorder) |
+| data display           | `DataTable` (+ `progressiveRows`: a long page mounts in steps), `tableHeader` + `tableAlign`, `HiddenFilterCue` (names a filter whose column is off screen), `Pager` + `pagerContent`, `VirtualGrid` + `gridColumns` (the column/width maths, incl. the ultrawide `maxCols` cap), `readAhead`, `Carousel`, `MediaCard` + `mediaCardStyles` (the one media card, docs/DESIGN.md "Media card") + `MediaPreview` / `useMediaPreview` (its mouse-rest preview), `NavGrid` (a plain grid, list or table body the keyboard walks — `DataTable`, `VirtualGrid` and `Carousel` take `keyboardNav`), `RemoteImage` (every network picture: no Referer, retries past the negative cache, a fallback instead of the broken-image mark — a bare `<img>` is linted out), `Avatar`, `CountBadge`, `ItemCount`, `FilterChipGroup`, `RelativeTime` ("3d ago" with the exact minute on hover, docs/DESIGN.md "Copy"), `ClampedText` (a long text clamped to a few lines; More / Less only when it is cut), `StatTiles` + `StatTile` / `StatBars` (number tiles, a breakdown as horizontal bars), `RangeTrack` + `trackPosition` + `RulerTicks` (a time track over a window of a media item: regions, slider ends the arrows step, a playhead, a background slot — the editor's cuts, the players' clip panel), `CropFrame` (a crop frame over a picture, on the picture and not its bars: drag, edges, corners, the arrows; the editor's crop, the players' clip crop), `reveal` (a card's hover chrome: hover or keyboard focus on a mouse, never on touch)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| page & panel structure | `PageShell` + `pageToolbarSlot` + `pageHeaderSlot` (`PageHeader`: a page fills the floating header) + `pageHeading`, `PageScroller`, `Headings` (`PageHeading`, `SectionLabel`), `SkipLink` + `landmarks`, `FilterFold` (B4), `scrollFold` (`useScrollFold`: a fixed header that folds once its content scrolls), `PanelGroup`, `PanelGroups`, `Tabs` + `tabPanel`, `BackToTop` + `backToTopState` (PageScroller keeps the page's end clear of it), `FilterRail` (the filter-rail shell a rail fills with its groups: title bar, customize, reset), `stickyTop` (a sticky header at the scroller's top turns its top fade off)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| state & messaging      | `QueryState`, `Banner`, `InlineNotice`, `CrashBoundary`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 
 ## The size contract (E10 S1c)
 

frontend/src/components/ui/Toaster.hosts.test.ts

@@ -18,12 +18,12 @@ import { readSources } from "../../lib/rawSources.testkit";
 // BOTH patterns: `../**/*.tsx` from this directory does not match the siblings in `ui/` itself, so
 // ui/Modal.tsx — the overlay behind every dialog in the app — was never checked by this guard at all
 // (found by a later review).
-const sources = readSources(__dirname, ["../**/*.tsx", "./*.tsx"]);
+const sources = readSources(__dirname, ["../../**/*.tsx", "!../../design-lab/**"]);
 
 // Overlays with nothing a toast could be about: a lazy chunk's black placeholder while the player
 // loads, and the signed-out landing page's screenshot zoom (the app's Toaster is not even mounted
 // there — App renders Welcome instead of the shell).
-const EXEMPT = new Set(["../PlexBrowse.tsx", "../Welcome.tsx"]);
+const EXEMPT = new Set(["../../modules/plex/PlexBrowse.tsx", "../../shell/Welcome.tsx"]);
 
 /** Every class string in the file (quoted or templated), including multi-line ones. */
 const classStrings = (src: string): string[] =>
@@ -67,9 +67,9 @@ describe("full-screen overlays host their own toasts", () => {
     expect(paths).toEqual(
       expect.arrayContaining([
         "./Modal.tsx",
-        "../PlayerModal.tsx",
-        "../PlexPlayer.tsx",
-        "../OnboardingWizard.tsx",
+        "../../features/player/PlayerModal.tsx",
+        "../../modules/plex/PlexPlayer.tsx",
+        "../../features/wizard/OnboardingWizard.tsx",
       ]),
     );
   });

frontend/src/components/ui/ViewSwitcher.tsx

@@ -1,11 +1,11 @@
 import { useState } from "react";
 import { type LucideIcon } from "lucide-react";
 import clsx from "clsx";
-import { PopoverItem, PopoverSurface } from "./ui/AnchoredPopover";
-import { useAnchoredPopover } from "./ui/anchoredPopoverHooks";
-import { MenuCheck } from "./ui/MenuCheck";
-import { SelectTrigger } from "./ui/SelectTrigger";
-import { SURFACE } from "./ui/surfaces";
+import { PopoverItem, PopoverSurface } from "./AnchoredPopover";
+import { useAnchoredPopover } from "./anchoredPopoverHooks";
+import { MenuCheck } from "./MenuCheck";
+import { SelectTrigger } from "./SelectTrigger";
+import { SURFACE } from "./surfaces";
 
 export interface ViewOption<T extends string> {
   id: T;

frontend/src/components/ui/copyItems.tsx

@@ -1,16 +1,17 @@
 import { useTranslation } from "react-i18next";
 import { Copy, Link2 } from "lucide-react";
 
-import { copyText } from "../lib/clipboard";
-import { notify } from "../lib/notifications";
-import { type ActionMenuItem } from "./ui/ActionMenu";
+import { copyText } from "../../lib/clipboard";
+import { notify } from "../../lib/notifications";
+import { type ActionMenuItem } from "./ActionMenu";
 
 // "Copy title" and "Copy link", the two rows every object's menu ends its middle group with
 // (DESIGN.md C1, "Text stays selectable"): on touch the long-press belongs to the context menu, so the text a
 // finger cannot select is copied from here. One builder, so every object says it the same way and
 // the clipboard write always runs inside the gesture (`inGesture`, which Safari insists on).
 //
-// A feature file, not `ui/`: it speaks the app's notifications.
+// Domain-free: it speaks through lib/notifications, the platform's toast service, so any module's menu
+// can end with it.
 
 type Named = "title" | "name";
 

frontend/src/components/ui/hiddenFilterCue.contract.test.ts

@@ -6,9 +6,9 @@ import { describe, expect, it } from "vitest";
 // or have no header at all. Each renders the hidden-filter cue, so no filter narrows its rows unseen.
 describe("every view that filters rows by column", () => {
   it("renders the hidden-filter cue", () => {
-    const root = new URL("../", import.meta.url);
+    const root = new URL("../../", import.meta.url);
     const sites = readdirSync(root, { recursive: true, encoding: "utf8" })
-      .filter((f) => f.endsWith(".tsx") && !f.includes(".test."))
+      .filter((f) => f.endsWith(".tsx") && !f.includes(".test.") && !f.startsWith("design-lab"))
       .map((f) => [f, readFileSync(new URL(f.replace(/\\/g, "/"), root), "utf8")] as const)
       .filter(([, src]) => /filterRows\(/.test(src));
     expect(sites.length).toBeGreaterThanOrEqual(3);

frontend/src/components/ui/menuCheck.contract.test.ts

@@ -1,7 +1,8 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 
-const root = new URL("../", import.meta.url);
+// The whole app source (shell, modules, features, ui): the checkable menus live in all of them.
+const root = new URL("../../", import.meta.url);
 const sources = () =>
   readdirSync(root, { recursive: true, encoding: "utf8" })
     .filter((f) => f.endsWith(".tsx") && !f.includes(".test."))

frontend/src/components/ui/pageHeaderSlot.ts

@@ -0,0 +1,17 @@
+import { createContext } from "react";
+
+// The floating header's slot (see PageHeader in PageShell): the node a page portals its header
+// controls into, whether a page has claimed it, and how a page claims it. The value is null with no
+// shell and the target null in a shell without a header (the channel page): a page renders its header
+// nowhere there. Its own
+// module so PageShell exports only components (Fast Refresh).
+export type PageHeaderSlotValue = {
+  target: HTMLElement | null;
+  claimed: boolean;
+  /** Claim the header for this page's controls; the returned function releases it. */
+  claim: () => () => void;
+  /** The default (PageHeaderDefault) reports whether it is in the header, so PageShell re-measures. */
+  showDefault: (shown: boolean) => void;
+};
+
+export const PageHeaderSlot = createContext<PageHeaderSlotValue | null>(null);

frontend/src/components/ui/pageMenuScope.contract.test.ts

@@ -7,9 +7,9 @@ import { readSources } from "../../lib/rawSources.testkit";
 // stats, users, downloads) keep the browser's menu. A page that starts rendering one fails here until
 // that decision is taken again.
 const files = readSources(__dirname, [
-  "../**/*.tsx",
-  "!../**/*.test.*",
-  "!../design-lab/**",
+  "../../**/*.tsx",
+  "!../../**/*.test.*",
+  "!../../design-lab/**",
   "!./**",
 ]) as Record<string, string>;
 
@@ -17,14 +17,14 @@ describe("the pages with a background menu", () => {
   it("are the five the owner chose", () => {
     const users = Object.entries(files)
       .filter(([, code]) => /<PageMenu\b|\busePageMenu\(/.test(code))
-      .map(([path]) => path.replace(/^\.\.\//, ""))
+      .map(([path]) => path.replace(/^(\.\.\/)+/, ""))
       .sort();
     expect(users).toEqual([
-      "Channels.tsx",
-      "Feed.tsx",
-      "NotificationsPanel.tsx",
-      "Playlists.tsx",
-      "PlexBrowse.tsx",
+      "modules/channels/Channels.tsx",
+      "modules/feed/Feed.tsx",
+      "modules/notifications/NotificationsPanel.tsx",
+      "modules/playlists/Playlists.tsx",
+      "modules/plex/PlexBrowse.tsx",
     ]);
   });
 });

frontend/src/components/ui/pressableSelectable.contract.test.ts

@@ -10,66 +10,74 @@ import { readSources } from "../../lib/rawSources.testkit";
 // someone decides.
 
 const files = readSources(__dirname, [
-  "../**/*.tsx",
-  "!../**/*.test.*",
-  "!../design-lab/**",
+  "../../**/*.tsx",
+  "!../../**/*.test.*",
+  "!../../design-lab/**",
 ]) as Record<string, string>;
 
 /** file → [how many plain Pressables, why they are not titles]. */
 const PLAIN: Record<string, [number, string]> = {
-  "ApiTokens.tsx": [
+  "modules/settings/ApiTokens.tsx": [
     1,
     "a token kind's tile in the new-token dialog (an option: its text is its label)",
   ],
-  "DownloadTray.tsx": [
+  "features/downloads/DownloadTray.tsx": [
     2,
     "the folded pill (its summary is its label); a failure's reason, which opens its details",
   ],
-  "FileCard.tsx": [1, "a card's picture (named by aria-label; its title is the caption)"],
-  "FilesRail.tsx": [2, "the load-error retry; the New-folder command"],
-  "Home.tsx": [
+  "modules/files/FileCard.tsx": [
+    1,
+    "a card's picture (named by aria-label; its title is the caption)",
+  ],
+  "modules/files/FilesRail.tsx": [2, "the load-error retry; the New-folder command"],
+  "modules/home/Home.tsx": [
     2,
     "the hero's picture and a shelf tile's picture (each named by aria-label; its title sits outside)",
   ],
-  "LanguageSwitcher.tsx": [1, "an option row"],
-  "NavSidebar.tsx": [4, "the account trigger and its menu rows"],
-  "PaletteLauncher.tsx": [2, "launcher controls"],
-  "PlaylistsRail.tsx": [1, "the load-error retry"],
-  "PlexCollectionEditor.tsx": [1, "a checkbox row in a picker"],
-  "PlexInfo.tsx": [1, "the rating filter (a number)"],
-  "PlexPlayerSettings.tsx": [1, "the clock's date-style options"],
-  "PlexPlaylistAdd.tsx": [1, "a checkbox row in a picker"],
-  "PlexPlaylistView.tsx": [1, "a show's poster stack (aria-hidden)"],
-  "PlexSearchBox.tsx": [1, "a listbox option"],
-  "plexCards.tsx": [1, "a card's picture (named by aria-label; its title is the caption)"],
-  "Scheduler.tsx": [1, "the interval editor trigger"],
-  "SettingsPanel.tsx": [1, "a colour swatch"],
-  "SyncStatus.tsx": [1, "the status pill trigger"],
-  "TagManager.tsx": [1, "a suggestion in a picker"],
-  "UploadDialog.tsx": [1, "the drop zone"],
-  "VideoEditor.tsx": [2, "timeline glyphs"],
-  "Welcome.tsx": [1, "a screenshot (zoom)"],
-  "playlistColumns.tsx": [1, "the thumbnail"],
-  "plexDetailUi.tsx": [2, "a switch row and the poster"],
-  "plexViews.tsx": [1, "the rating filter (a number)"],
-  "ui/ActionMenu.tsx": [1, "a menu row"],
-  "ui/BackToTop.tsx": [1, "a control"],
-  "ui/CommandPalette.tsx": [1, "a command row"],
-  "ui/NavRail.tsx": [
+  "components/ui/LanguageSwitcher.tsx": [1, "an option row"],
+  "shell/NavSidebar.tsx": [3, "the account trigger and its menu rows"],
+  "features/header/PaletteLauncher.tsx": [2, "launcher controls"],
+  "modules/playlists/PlaylistsRail.tsx": [1, "the load-error retry"],
+  "modules/plex/PlexCollectionEditor.tsx": [1, "a checkbox row in a picker"],
+  "modules/plex/PlexInfo.tsx": [1, "the rating filter (a number)"],
+  "modules/plex/PlexPlayerSettings.tsx": [1, "the clock's date-style options"],
+  "features/plexCards/PlexPlaylistAdd.tsx": [1, "a checkbox row in a picker"],
+  "modules/plex/PlexPlaylistView.tsx": [1, "a show's poster stack (aria-hidden)"],
+  "modules/plex/PlexSearchBox.tsx": [1, "a listbox option"],
+  "features/plexCards/plexCards.tsx": [
+    1,
+    "a card's picture (named by aria-label; its title is the caption)",
+  ],
+  "modules/scheduler/Scheduler.tsx": [1, "the interval editor trigger"],
+  "modules/settings/SettingsPanel.tsx": [1, "a colour swatch"],
+  "modules/channels/SyncStatus.tsx": [1, "the status pill trigger"],
+  "features/channel/TagManager.tsx": [1, "a suggestion in a picker"],
+  "modules/files/UploadDialog.tsx": [1, "the drop zone"],
+  "modules/files/VideoEditor.tsx": [2, "timeline glyphs"],
+  "shell/Welcome.tsx": [1, "a screenshot (zoom)"],
+  "modules/playlists/playlistColumns.tsx": [1, "the thumbnail"],
+  "modules/plex/plexDetailUi.tsx": [2, "a switch row and the poster"],
+  "modules/plex/plexViews.tsx": [1, "the rating filter (a number)"],
+  "components/ui/ActionMenu.tsx": [1, "a menu row"],
+  "components/ui/BackToTop.tsx": [1, "a control"],
+  "components/ui/CommandPalette.tsx": [1, "a command row"],
+  "components/ui/NavRail.tsx": [
     2,
     "the action rows (About, Sign out) and the group row that opens its panel; a page row is a link",
   ],
-  "ui/PanelGroup.tsx": [2, "a group's collapse toggle and its label"],
-  "ui/SidePanel.tsx": [2, "panel controls"],
-  "ui/tableHeader.tsx": [1, "a column's sort header"],
+  "components/ui/PanelGroup.tsx": [2, "a group's collapse toggle and its label"],
+  "components/ui/SidePanel.tsx": [2, "panel controls"],
+  "components/ui/tableHeader.tsx": [1, "a column's sort header"],
 };
 
 function scan(): { plain: Record<string, number>; selectable: number } {
   const plain: Record<string, number> = {};
   let selectable = 0;
   for (const [path, code] of Object.entries(files)) {
-    // Glob keys are relative to this folder: `./x.tsx` is ui/, `../x.tsx` is components/.
-    const rel = path.startsWith("./") ? `ui/${path.slice(2)}` : path.replace(/^\.\.\//, "");
+    // Glob keys are relative to this folder (`./x.tsx` is ui/); the table keys them from src/.
+    const rel = path.startsWith("./")
+      ? `components/ui/${path.slice(2)}`
+      : path.replace(/^(\.\.\/)+/, "");
     for (const m of code.matchAll(/<Pressable\b/g)) {
       if (/\sselectable\b(?!=)/.test(openingTag(code, m.index))) selectable++;
       else plain[rel] = (plain[rel] ?? 0) + 1;

frontend/src/components/ui/useCopyFeedback.dom.test.ts

@@ -10,8 +10,8 @@ vi.mock("react-i18next", async (importOriginal) => ({
   ...(await importOriginal<typeof import("react-i18next")>()),
   useTranslation: () => ({ i18n: { language: "en" }, t: (key: string) => key }),
 }));
-vi.mock("../lib/clipboard", () => ({ copyText: h.copyText }));
-vi.mock("../lib/notifications", () => ({ notify: h.notify }));
+vi.mock("../../lib/clipboard", () => ({ copyText: h.copyText }));
+vi.mock("../../lib/notifications", () => ({ notify: h.notify }));
 
 import { useCopyFeedback } from "./useCopyFeedback";