Answer prose round 1: 0 🔴, 3 🟡 (0 misread); the pageError comment is true, nested-group removal is unambiguous, the trade-off lives only at the guard

Release-Bump: minor

.gitea/workflows/registry-cleanup.yml

@@ -19,4 +19,4 @@ jobs:
         run: |
           docker run --rm -v "$PWD:/repo" -w /repo \
             -e REGISTRY_TOKEN -e REGISTRY_USER -e REPO_TOKEN -e REPOSITORY -e SERVER_URL \
-            node:24.22.1-alpine3.24 node registry-cleanup/cleanup.ts
+            node:24.22.2-alpine3.24 node registry-cleanup/cleanup.ts

.gitea/workflows/release.yml

@@ -21,7 +21,7 @@ jobs:
           GIT_TAG: ${{ github.ref_name }}
         run: |
           set -euo pipefail
-          docker run --rm -v "$PWD:/repo" -w /repo node:24.22.1-alpine3.24 \
+          docker run --rm -v "$PWD:/repo" -w /repo node:24.22.2-alpine3.24 \
             node release-tooling/contract-version.ts "$GIT_TAG" src/plugin-host/plugin.ts
       - name: Promote the commit-hash image to semver + latest
         env:
@@ -98,9 +98,9 @@ jobs:
           VERSION=${INPUT_VERSION:-${GIT_TAG#v}}
           VERSION=${VERSION#v}
           # An empty dispatch input falls back to the branch name, so gate this like a tag.
-          docker run --rm -v "$PWD:/repo" -w /repo node:24.22.1-alpine3.24 \
+          docker run --rm -v "$PWD:/repo" -w /repo node:24.22.2-alpine3.24 \
             node release-tooling/contract-version.ts "$VERSION" src/plugin-host/plugin.ts
           docker run --rm -v "$PWD:/repo" -w /repo \
             -e DOCKERHUB_REPO -e DOCKERHUB_TOKEN -e DOCKERHUB_USER \
-            node:24.22.1-alpine3.24 \
+            node:24.22.2-alpine3.24 \
             node release-tooling/dockerhub-overview.ts "$VERSION"

.gitea/workflows/renovate.yml

@@ -21,7 +21,7 @@ jobs:
             -e RENOVATE_PLATFORM=gitea \
             -e RENOVATE_REPOSITORIES=${{ github.repository }} \
             -e RENOVATE_TOKEN \
-            renovate/renovate:44.181.9
+            renovate/renovate:44.186.6
 
   # After the renovate job, cut ONE tag covering the renovate-bot commits merged to main since the
   # last tag (batch per run). Targets origin/main — the real post-merge tip; the checkout SHA is the
@@ -58,11 +58,11 @@ jobs:
           if [ -z "$BUMPS" ]; then
             echo "Renovate commits since ${LATEST}, but none carry Release-Bump — nothing reached a running Plainpages; skipping"; exit 0
           fi
-          NEXT=$(docker run --rm -v "$PWD:/repo" -w /repo node:24.22.1-alpine3.24 \
+          NEXT=$(docker run --rm -v "$PWD:/repo" -w /repo node:24.22.2-alpine3.24 \
                  node release-tooling/next-version.ts "$LATEST" $BUMPS)
           # Read the constant off origin/main, not the checkout, which lags the merges this run made.
           git show origin/main:src/plugin-host/plugin.ts \
-            | docker run -i --rm -v "$PWD:/repo" -w /repo node:24.22.1-alpine3.24 \
+            | docker run -i --rm -v "$PWD:/repo" -w /repo node:24.22.2-alpine3.24 \
                      node release-tooling/contract-version.ts "$NEXT" -
           echo "Releasing $LATEST -> $NEXT"
           git tag "$NEXT" origin/main

AGENTS.md

@@ -213,14 +213,17 @@ Revisit only if the stated reason stops holding.
   form, a delete-confirm page) is the exception to `actionForMethod` and gates on `:write`. Two
   grant-specific guards go with it: you cannot revoke your own **direct** grants (self-lockout would
   need a `curl` against Keto to undo), and a permission held *through a group* renders
-  ticked-but-disabled, because unticked stated the opposite of the truth. **Known gap:** the group
-  paths are unguarded — unticking a permission on a group you belong to, leaving it, or deleting it
-  can still strip your own access. The robust "last effective holder" check needs a reverse Keto
-  query and is deferred.
+  ticked-but-disabled, because unticked stated the opposite of the truth. The group paths are
+  guarded too: unticking a permission on a group you are in, removing yourself (or a nested group you
+  are in) from its members, or deleting the group is refused when you would lose a permission you
+  don't hold directly.
 - **`users:write` and `groups:write` are equivalent to full administrative access**: `groups:write`
   adds you to any group, including one holding every permission; `users:write` mints a recovery code
   for any account. The containment the split buys is real on the **read** half only (`users:read` is
   a safe helpdesk grant). Don't let the per-resource naming imply otherwise in docs.
+- **The CSRF token is deliberately unbound to the session** (`src/auth/csrf.ts`; README → Security
+  model): the usual cost of a signed double-submit token, covered by `SameSite=Lax` and HSTS.
+  **Valid while the session cookie stays `SameSite=Lax` or stricter.**
 - **Plainpages says "user" everywhere; Ory's word is "identity".** House style, not a renamed
   concept. The single exception is the `Identity` DTO in `src/auth/kratos-admin.ts`, which mirrors
   Kratos' wire shape — don't rename it.
@@ -243,7 +246,8 @@ Revisit only if the stated reason stops holding.
 - **`locale` is a host-owned query param** — in `parseListQuery`'s reserved set, so a localized list
   page doesn't hand a plugin a phantom `locale` filter. The i18n view locals (`t`, `locale`, `locales`,
   `localeHref`, `localeParam`, `localeSwitch`, `dir`) are likewise reserved, merged after a handler's
-  `data` so a collision loses the key instead of breaking the shell.
+  `data` so a collision loses the key instead of breaking the shell — as is `assetHref`
+  (`src/http/static.ts`), which stays undocumented for plugins because calling it is not yet contract.
 - **Catalogs are checked at boot, not at render.** Every locale is compared against its set's `en-US`
   — keys, string-vs-plural kind, and the plural categories `Intl.PluralRules` requires — and a
   mismatch stops startup. A plugin may ship fewer locales than the host (its strings fall back to
@@ -355,6 +359,7 @@ Docker Compose. **Never run `node`, `npm`, or `tsc` on the host.**
 ```bash
 docker compose up                                       # dev server, live reload
 docker compose run --rm --no-deps web npm run typecheck  # strict type check (--no-deps: skip Ory)
+docker compose -f compose.yml -f e2e-tests/compose.visual.yml run --user "$(id -u):$(id -g)" --rm --no-deps --build e2e npm run typecheck  # the E2E specs
 docker compose run --rm --no-deps web npm test           # tests
 docker compose -f compose.yml up --build -d              # production
 ```
@@ -367,7 +372,7 @@ docker compose -f compose.yml up --build -d              # production
    stack up and a *minimal* plugin live. Nothing comes before Quick start. Keep its commands
    copy-pasteable; deeper detail lives in its own section, linked.
 2. **Returning developer (rest).** A **Contents** ToC right after Quick start, then sections ordered
-   by **what an adopter reaches for first**, not by architectural layering: Overview → Users, groups
+   by **what an adopter reaches for first**, not by architectural layering: Goals → Audience → Overview → Glossary → Users, groups
    & permissions → Building plugins → menu/blocks/interactivity → Configuration → Auth → Email →
    Architecture → Testing → Production → Observability → JWT-rotation runbook → Project-layout file
    map → Extending. Place a new section by how early an adopter needs it. **Users, groups &
@@ -388,7 +393,7 @@ one-time setup. A file-map or table row gets a clause, not a paragraph.
   If a file genuinely must be plain JavaScript, use `.js`; `"type": "module"` is set in both
   `package.json`s, so `.js` is ESM.
 - **No build step** and no compiled artifacts — do not add a bundler or `tsc` emit.
-- Before finishing a change, run the typecheck and tests above; both must pass.
+- Before finishing a change, run the typechecks and tests above; all must pass.
 - Tests use the built-in `node --test` runner — no test framework dependency.
 - English everywhere.
 - Pin all dependencies and Docker images to exact, human-readable **semantic versions** — never
@@ -430,11 +435,9 @@ one-time setup. A file-map or table row gets a clause, not a paragraph.
   Don't funnel many routes into one dispatcher that re-parses `ctx.url.pathname`: it duplicates the
   URL shape, ignores the router's params, and has to re-handle HEAD. Factor shared per-request setup
   into a small `withX` wrapper — see `examples/plugins/admin/`.
-- **`handleRequest` (`src/http/app.ts`) is a known complexity hotspot** — ~160 lines tracking
-  canonical host, static, locale, session + re-mint, CSRF, chrome, hooks, plugin routing, builtin
-  routing, 405/404 and error mapping. The pure parts are already extracted and separately tested;
-  what remains is orchestration. Planned split along those seams; don't grow it further without
-  taking one out.
+- **A function stays within 50 lines and complexity 20** (ESLint's defaults, measured by
+  `src/function-limits.test.ts`). Split one that outgrows them; never add it to the test's
+  `grandfathered` list or raise a ceiling there.
 - Reviews are maintainer-triggered (e.g. via the larv-review skill) — never auto-run reviewer agents.
 - **A user-visible string belongs in a catalog, not in the code or a view.** Core strings go in
   `src/i18n/locales/en-US.ts` (then every other locale, or the boot fails); a plugin's go in its own
@@ -460,3 +463,13 @@ Default to **no comment**. Delete one that restates the adjacent code, repeats a
 elsewhere, justifies self-evident code, or records history. Write one only for what a competent
 reader of *this* codebase could not infer: a surprising why, a footgun, an invariant, an external
 constraint. See [Prose discipline](#prose-discipline).
+
+## Scoring run
+
+The comprehension panel's seats fill their prompts from these fields.
+
+- **Language:** strict TypeScript on Node 24, with EJS views and plain CSS
+- **Kind:** a server-rendered web GUI host with a plugin system
+- **Domain:** web authentication, authorization and server-rendered admin GUIs
+- **Domain docs:** the Ory Kratos, Keto and Hydra documentation
+- **3am question:** a visitor on an old TV browser reports that the sign-in button is blank. Which file and rule?

CHANGELOG.md

@@ -4,6 +4,116 @@ The release version **is** the plugin contract version (`HOST_API_VERSION`), so
 contract break: a plugin's `apiVersion` must match the host's `major.minor` or discovery refuses it
 at boot. Entries start at 0.3.0.
 
+## Unreleased
+
+### The admin example stops an administrator locking themselves out through a group
+
+On the Groups screen, unticking a permission on a group you are in, removing yourself (or a nested
+group you are in) from its members, or deleting the group is refused when it would take away a
+permission you don't hold directly. The page names the permissions, and another administrator can
+make the change. The check errs towards refusing: it also refuses when you would keep the permission
+through another group, or keep your membership another way.
+
+### The admin example titles a read-only user page "View user"
+
+A holder of `users:read` without `users:write` sees the user page titled "View user", with a "View"
+breadcrumb, instead of "Edit user".
+
+### Browsers cache stylesheets instead of downloading them on every page
+
+Every `/public/` URL the host renders carries `?v=<hash of the file>` and is cached for a year as
+immutable: the shell's stylesheets, favicon and logo, the `styles` a plugin passes to the shell, and
+the stylesheets of the standalone error and consent pages. A changed file gets a new hash, so
+browsers fetch it at once. A plugin names its stylesheets exactly as before. Any other `/public/` URL, such as a script
+a plugin's own markup links, is cached for five minutes, then revalidated with `ETag` or
+`Last-Modified`. A cache or CDN in front of Plainpages may now store `/public/` responses.
+
+### A language chosen on a sign-in link no longer drops an absolute return target
+
+`/login?return_to=<absolute URL>&locale=sv-SE` passed the visitor to the dashboard after sign-in and
+dropped the OAuth2 login challenge in `return_to`. The target now reaches Kratos, and the chosen
+language is lost across that round-trip instead.
+
+### The admin example refuses a permission save made from an out-of-date page
+
+Two administrators editing one user's or group's permissions no longer overwrite each other. The
+form carries a token for the grants it showed. A save that would change something, made after those
+grants changed, is refused with "These permissions changed while you had the page open", and the page
+shows the current grants. A POST with no token is refused the same way, so a script posting to
+`/admin/users/:id/permissions` or `/admin/groups/:name/permissions` must first read the token from the
+page's `baseline` field.
+
+### The admin example confirms a permission save and reports a partial one
+
+A save now lands on the page with "Permissions saved." If the permission service fails midway, the
+page says the save stopped part-way instead of showing the generic error page. On a user, the
+changes that landed still reach the user's live sessions at once when the revocation denylist is on.
+
+### A read-only holder sees View, not Edit, on the admin example's users list
+
+A holder of `users:read` without `users:write` gets a "View" row action with an eye icon. The admin
+example's catalogs gain `admin.grants.partial`, `admin.grants.saved`, `admin.grants.stale` and
+`admin.users.view`, so a translated catalog mounted under `locales/plugins/admin/` must add them.
+
+### Every page carries a smaller icon sprite
+
+`i-chart`, `i-copy` and `i-download` are gone from the inlined icon sprite, so a plugin that
+referenced one now renders a blank icon. Nothing in the host or the example plugins used them. Pick
+another id from `views/partials/icons.ejs`, or inline your own SVG.
+
+### The README defines its terms and states its intended scale
+
+A new Glossary defines host, plugin, manifest, chrome, nav fragment, permission name, system plugin
+and denylist. Plugin dependencies also states the scale Plainpages is sized for: a handful of plugins
+per deployment.
+
+### The mobile nav stays reachable on engines without `:has()`
+
+At 860px and narrower, an engine without `:has()` (Chromium below 105, such as webOS TV 22 and 23,
+and Firefox below 121) hid the sidebar off-canvas with no way to open it, so the pages the nav links
+to could not be reached. Now the sidebar moves off-canvas, behind the hamburger, only where `:has()`
+works. Elsewhere it stays in the flow above the content and the hamburger is hidden.
+
+### The whole nav tree shows on engines without `:has()`
+
+On an engine without `:has()` (Chromium below 105, such as webOS TV 22 and 23, and Firefox below 121)
+every nested nav entry was hidden with nothing to open it. Now the tree folds only where `:has()`
+works and stays fully open elsewhere, with its toggles hidden. The theme switch, which also needs
+`:has()`, is hidden there.
+
+### Button and badge text meets 4.5:1 contrast
+
+The primary button and the current page button take their text colour from the new `--on-accent`
+token: white in light mode, near-black in dark mode, where white on the accent was 2.7:1. The
+light-mode success, warning and info badge text is darker. A plugin that overrides `--accent` or
+`--l-accent` should set `--l-on-accent` and `--d-on-accent` to match.
+
+### Unused auth stylesheet rules are gone
+
+`public/css/auth.css` no longer holds the `.auth-view` screen switch, `.tpl-*` preview controls,
+`.forgot-alert`, `.register-alert`, `.remember` and `.auth-foot`; no core view used them. A plugin
+view that did must carry its own rules.
+
+### Colours render on engines without `oklch()`
+
+The theme palette in `public/css/styles.css` is hex, not `oklch()`. On an engine older than
+Chromium 111 (Tizen 2024, webOS TV 24) `var(--accent)` was invalid, so the primary button was white
+text on no background. A plugin that sets a colour custom property, such as `--accent` or `--l-accent`,
+should use hex, `rgb()` or `hsl()` too.
+
+### One horizontal inset across the content pane
+
+The topbar, filter bar, pager, form page and empty-table message inset their content by `--pad-x`
+(12px), as table cells do, instead of 16px. A plugin that overrides `--pad-x` now moves all of them
+together.
+
+### Pages are not kept by a shared cache
+
+Every page and JSON response now carries `Cache-Control: private, no-store`, so a cache or reverse
+proxy in front of Plainpages can't store a signed-in page and serve it to the next visitor. A route
+whose page is the same for everyone can still set its own `cache-control` through
+`RouteResult.headers`; assets are unchanged.
+
 ## 0.4.0
 
 **Breaking.** Set `apiVersion: "0.4.0"`. The app shell no longer bounds the content column, so a page

Dockerfile

@@ -1,5 +1,5 @@
 # Node 24 runs TypeScript directly (type stripping) — no build step. Pinned exact tag.
-FROM node:24.22.1-alpine3.24
+FROM node:24.22.2-alpine3.24
 
 # Above WORKDIR so dev's `.:/app` bind mount can't shadow them; a volume at /app/node_modules
 # instead leaves a root-owned dir in the checkout (the daemon creates mount destinations as root).

README.md

@@ -70,7 +70,10 @@ From here, render real pages against the app shell and fetch upstream data — s
 
 ## Contents
 
+- [Goals](#goals)
+- [Audience](#audience)
 - [Overview](#overview)
+- [Glossary](#glossary)
 - [Users, groups & permissions](#users-groups--permissions)
   - [naming a permission](#naming-a-permission)
   - [a worked example](#a-worked-example)
@@ -121,6 +124,64 @@ From here, render real pages against the app shell and fetch upstream data — s
 - [Project layout](#project-layout)
 - [Extending the core](#extending-the-core)
 
+## Goals
+
+1. **Achieve:** Less boilerplate for a server-rendered web GUI: a new project starts at
+   its own domain, not at sign-in, a menu or a table.
+   - Signal: a new plugin reaches a working, gated page with a menu, tables, filters and
+     forms built only from the core building blocks.
+   - Counter-signal: the core grows features only one project needs.
+   - Why: boilerplate removed by absorbing a project's domain only moves it into the core.
+2. **Achieve:** Every building block works for the person using it: a non-technical user
+   gets what they meant on the first try, and can't hurt themselves by accident.
+   - Signal: bugs users hit in a shipped flow get fixed and stay fixed, such as a pasted
+     code being refused, a double click acting twice, or an admin locking themselves out.
+   - Counter-signal: a fix adds client-side JavaScript, or a setting every plugin has to
+     know about.
+   - Why: a fix that breaks zero-JS or simplicity moves the irritation from users to every
+     plugin author.
+3. **Maintain:** Plainpages solves only the parts every project shares: auth, the GUI
+   building blocks (menu, tables, filters, forms) and the plugin structure. Everything
+   else is a plugin.
+4. **Maintain:** Every page is a server-rendered document that works with zero JavaScript,
+   on old and embedded browsers too. A newer browser only makes it nicer.
+5. **Maintain:** State lives in the URL. Only state the URL can't carry lives in the
+   database, never in local storage or JavaScript. A cookie carries only what must be bound
+   to the browser: the session and its CSRF token.
+6. **Maintain:** The frontend is semantic: the HTML says what each thing is, and the CSS
+   styles meaning, not looks. That keeps every page accessible.
+7. **Achieve:** Hackable: a plugin can change anything, and Plainpages stays out of its way.
+   - Signal: a plugin replaces any page, partial, menu entry or string without forking the
+     host, and fewer plugins need a host change to get unblocked.
+   - Counter-signal: plugins break on upgrade with no version signal, or a plugin mistake
+     shows up at runtime instead of at boot.
+   - Why: freedom that breaks silently costs more than the boilerplate it saved.
+8. **Achieve:** Speed: pages render fast and stay small.
+   - Signal: server time per page and bytes sent per page fall.
+   - Counter-signal: a building block loses a feature or accessibility to save bytes.
+   - Why: a fast page that does less only moves the work back into each plugin.
+9. **Achieve:** LLM-friendly: an LLM builds a correct plugin from the README and the
+   examples alone.
+   - Signal: an agent given only those writes a plugin that passes discovery and its E2E
+     test on the first try.
+   - Counter-signal: the README grows to restate what the code already shows.
+   - Why: docs that pass the test by growing cost every later reader, human or LLM.
+10. **Maintain:** Every behaviour is an explicit configuration choice, the same in every
+   environment.
+
+## Audience
+
+- **Developers starting a web GUI project, and the LLMs that build plugins with them.**
+  They may rely on `@plainpages/plugin-api`, the core partials and the packaging promises,
+  all versioned by `apiVersion`. A change that breaks a plugin takes a major bump.
+- **Operators** who self-host Plainpages. They may rely on semver-tagged images, on
+  configuration through environment variables and the drop-in mounts (`plugins/`,
+  `config/`, `locales/`), and on upgrades within a minor version that need no change on
+  their side.
+- **Visitors** to a site built on Plainpages, on any browser, including the older engines in
+  TVs, kiosks, thin clients and embedded panels. They may rely on pages that load fast and
+  work without JavaScript, with a keyboard and a screen reader.
+
 ## Overview
 
 Plainpages gives you the boring-but-hard parts of a web app — a design system, a menu,
@@ -136,11 +197,9 @@ public front with an authenticated area behind it.
 - **You add:** everything else domain-specific, as **plugins** — built from the same building
   blocks the admin plugin uses.
 
-**Priorities:** simplicity, few dependencies, strict TypeScript, no build step, Docker-only,
-environment-agnostic (no `NODE_ENV` — every behaviour is an explicit config toggle). Identity,
-sessions, SSO, OAuth2 and permission checks are delegated to **Ory** sidecar services. The shape
-doesn't change as it grows: every plugin is the same self-contained folder, the hot path is the
-same I/O-free JWT check, and there is no app database.
+Identity, sessions, SSO, OAuth2 and permission checks are delegated to **Ory** sidecar
+services. The shape doesn't change as it grows: every plugin is the same self-contained folder,
+the hot path is the same I/O-free JWT check, and the host stores nothing of its own.
 
 **Plugins are the extension model.** The plugin API is the product's main surface: powerful,
 predictable, and overloadable — a plugin can take over as much of a page as it wants. The host
@@ -152,6 +211,24 @@ feature removes the need for JS (theme switching, popovers, disclosure) we use i
 avoid is shipping a client-side runtime, not using the platform. Markup is semantic and accessible
 (see [AGENTS.md](AGENTS.md)).
 
+## Glossary
+
+- **Host** — the `web` container: the Node process that discovers plugins, serves every page and
+  owns no state of its own. Everything outside it (a plugin's upstream, Ory) is reached over the network.
+- **Plugin** — a folder under `plugins/` that adds domain features.
+- **Manifest** — the object a plugin's `plugin.ts` exports as its default: its routes, nav,
+  permissions and hooks. The host checks it at boot and refuses a bad one ([The manifest](#the-manifest)).
+- **Chrome** — everything on a page that isn't the page's own content: brand, menu, user, theme and
+  CSRF token. A handler gets it as `ctx.chrome` ([RequestContext](#requestcontext)).
+- **Nav fragment** — the `nav` entries one plugin contributes. The host merges every plugin's
+  fragment into the one global menu and filters it per user ([The menu system](#the-menu-system)).
+- **Permission name** — a `<resource>:<action>` string such as `scheduling:write`, granted in Keto and
+  carried in the session JWT's `permissions` claim ([Naming a permission](#naming-a-permission)).
+- **System plugin** — a plugin that administers Plainpages' own identity stack, through the
+  privileged `ctx.system` ([System capabilities](#system-capabilities-the-ctxsystem-surface)).
+- **Denylist** — the optional in-memory list, per instance, of subjects revoked just now, so a
+  deactivation or a user's own permission change lands before the JWT expires ([Instant revoke](#instant-revoke-the-optional-denylist)).
+
 ## Users, groups & permissions
 
 Authorization here is two hops: a **user** — directly, or through a **group** — is granted a
@@ -433,6 +510,9 @@ export async function listThings(ctx: RequestContext) {
   nested names like `"things/edit"` work, out-of-bounds names are refused. The template may
   `include()` the core building-block partials and its own. To load the plugin's own CSS, pass its
   `/public/<id>/x.css` href in the shell's `styles` slot — see the reference's `views/shifts.ejs`.
+  The host adds the file's content hash to every `/public/` href the shell renders, so browsers and
+  any cache in front of Plainpages keep the file for a year; a `/public/` URL your own markup writes
+  is kept for five minutes, then revalidated.
 - **Finer authorization than the route `permission`** uses the guards from `@plainpages/plugin-api`:
   `requireSession(ctx)`, `can(ctx, permission)` (coarse JWT-claim check, zero I/O), and
   `check(keto, ctx, {namespace, object, relation})` (a live Keto check; anonymous ⇒ denied). Throw
@@ -735,6 +815,9 @@ included, since the plugin folder *is* the repo. A baked image needs no extra st
   above every plugin, and a plugin resolves it from there — nothing to declare, just import it. A
   copy inside your plugin's own `node_modules` would shadow it with a *second* instance of the host's
   contract, turning a sign-in redirect into a 500, so discovery refuses one there at boot.
+- **Plainpages is sized for a handful of plugins per deployment, about ten.** Each plugin carries
+  its own dependency tree, so every one adds to disk use and to the memory of the `web` process;
+  hundreds of plugins is not a goal.
 - **The host never upgrades or dedupes your dependencies.** Two plugins depending on the same package
   each get their own copy at their own version, so neither can break the other by upgrading — and
   keeping yours current, and audited, is yours to own. Renovate here watches every manifest in this
@@ -961,6 +1044,15 @@ underneath it — cramped, but nothing is unreachable. List state
 (`?q=…&status=…&sort=…&page=…`) lives **in the URL**, so a view is bookmarkable and shareable; the
 URL is the only state the UI keeps.
 
+**Two browser floors** serve goal 4. Every page's content and actions stay reachable on
+Chromium 87, Safari 15 and Firefox 115, the engines in years-old TVs, kiosks and Qt panels. Only
+features [Baseline Widely available](https://web-platform-dx.github.io/baseline/) (in every
+major engine for 30 months) may shape how a page looks; anything newer, like popovers or anchor
+positioning, only enhances. A feature the floor engines lack, such as `:has()`, may
+decorate a page but never decide whether something shows or can be read. A colour is hex, `rgb()` or
+`hsl()`, never `oklch()`: a custom property holding it passes unchecked, and the `var()` reading it
+then renders transparent.
+
 **A field whose options depend on another field is asked for in steps, one GET form each**, so every
 choice is in the URL, and nothing typed is lost to one because nothing is typed until they are made.
 Once the query names a value, that field renders read-only (`field` with `readonly`, and a `link` back
@@ -1083,7 +1175,7 @@ Rules worth knowing:
   edit/new/remove/save`, `filter.*`, `pagination.*`, `table.*` — and a plugin's lookup falls through
   to them. Keep your catalog for your domain words.
 - **Reserved view locals:** `t`, `locale`, `locales`, `localeHref`, `localeParam`, `localeSwitch`,
-  `dir`. They are merged after your `data`, so a colliding key of yours is ignored rather than
+  `dir`, and the host-internal `assetHref`. They are merged after your `data`, so a colliding key of yours is ignored rather than
   breaking the shell. `locale` is likewise reserved in `parseListQuery`, never returned as a filter.
 
 **Kratos writes the auth flow's own text** (field labels, validation errors), tagging each string
@@ -1106,7 +1198,7 @@ The app is **environment-agnostic**: no `NODE_ENV`, every behaviour its own expl
 | --- | --- | --- |
 | `APP_URL` | _unset_ (dev: `http://localhost:3000`) | the canonical public URL — the **single source** for the host this deployment lives on; set ⇒ off-host visitors are redirected here, unset ⇒ no redirect (see [Canonical host](#canonical-host-one-public-url)) |
 | `PORT` | `3000` | web listen port |
-| `CACHE_TEMPLATES` | `false` | cache compiled EJS templates (`true` in prod) |
+| `CACHE_TEMPLATES` | `false` | cache compiled EJS templates and `/public/` asset versions (`true` in prod) |
 | `SECURE_COOKIES` | `false` | mark our session/CSRF cookies `Secure` (`true` in prod https; off in dev http) |
 | `REQUIRE_SECURE_SECRETS` | `false` | when `true`, `CSRF_SECRET` — and `PLUGIN_DB_SECRET` once storage is configured, and every plugin setting declared `secret` — must be supplied and differ from the dev throwaway |
 | `LOG_LEVEL` | `info` | min severity logged: `error`/`warn`/`info`/`verbose`/`debug`/`silly`/`none` |
@@ -1319,6 +1411,11 @@ authorization graph, so treat it the same. `compose.yml` publishes none of the s
 so a stolen cookie jar is worth 30 days of re-mintable access, not ten minutes. Only our two cookies
 obey `SECURE_COOKIES`; the Kratos one takes its flags from Kratos' own config.
 
+**The CSRF token isn't bound to the session.** It is a signed double-submit token, so an attacker who
+can write cookies on your origin can plant one they know. `SameSite=Lax` keeps a cross-site page
+out, and HSTS (`SECURE_COOKIES=true`) a network attacker. A hostile page on a sibling subdomain can
+still set cookies, so host nothing untrusted on one.
+
 **Offboarding is not instant by default** — a revoked permission or deactivated identity lands
 within one token TTL, unless the [denylist](#instant-revoke-the-optional-denylist) is on.
 
@@ -1393,12 +1490,13 @@ session lives in Kratos and the data lives outside the process.
 
 ## Testing
 
-Type check and unit tests run off the Ory stack — `--no-deps` keeps `web` from dragging up its
-`depends_on` services:
+Type checks and unit tests run off the Ory stack — `--no-deps` keeps each service from dragging up
+its `depends_on` services:
 
 ```bash
 docker compose run --rm --no-deps web npm run typecheck   # strict tsc --noEmit
 docker compose run --rm --no-deps web npm test            # node --test (units)
+docker compose -f compose.yml -f e2e-tests/compose.visual.yml run --user "$(id -u):$(id -g)" --rm --no-deps --build e2e npm run typecheck   # the E2E specs
 ```
 
 ### End-to-end (Playwright)
@@ -1437,7 +1535,7 @@ Ory-backed ones share one backend and stay on Chromium.
 
 ### The full gate (one command)
 
-`ci.sh` is the whole gate in one reproducible command — typecheck → unit tests →
+`ci.sh` is the whole gate in one reproducible command — typecheck (the specs in `e2e-tests/` too) → unit tests →
 each E2E suite against its own fresh stack, with a guaranteed `down -v` after each (even on
 failure) and a non-zero exit on the first failure. Run it locally before a release, or wire
 it into your CI service:
@@ -1580,6 +1678,11 @@ Every response carries security headers (`src/http/security-headers.ts`): a stri
 so a branding logo must live under `/public/` or be a `data:` URI; a plugin route can override any
 header per-response via `RouteResult.headers`.
 
+Every page and JSON response is `Cache-Control: private, no-store`, so a cache in front of `web`
+never keeps one user's page for the next. A route may override it only for a page that is the same for
+every visitor: no user, no CSRF token, no `Set-Cookie`, since the host adds a fresh CSRF cookie to
+every plugin route.
+
 A deep link reached while signed out — or after the session JWT lapses mid-task — bounces to the
 themed sign-in and returns to the **page that was requested** (`return_to`, validated host-relative
 by `localPath` in `src/http/safe-url.ts`, so a crafted value can't turn login completion into an open
@@ -1713,7 +1816,7 @@ unnecessary here — the signature itself is already invalid.
 ```
 src/                 The app — strict tsc, no build step. *.test.ts sit beside their module.
   server.ts          Entry point; config.ts env loader; logger.ts structured log + trace span + tracedFetch
-  *.test.ts          Topology guards with no source counterpart (compose/kratos/keto/hydra/postgres/ci-gate)
+  *.test.ts          Guards with no source counterpart (compose/kratos/keto/hydra/postgres/ci-gate/function-limits)
   http/              Request pipeline: app.ts (createApp), builtin-routes, context, body, cookie,
                      static, safe-url (safeUrl + localPath), security-headers
   auth/              Identity + the session-JWT hot path: jwt · jwt-middleware · jwks · gen-jwks (CLI) ·
@@ -1725,8 +1828,8 @@ src/                 The app — strict tsc, no build step. *.test.ts sit beside
   plugin-host/       plugin.ts (the contract) · plugin-api.ts (the `@plainpages/plugin-api` barrel) · system.ts
                      (ctx.system) · discovery · router · hooks · view-resolver · storage (the rules) ·
                      storage-provisioning (the DDL; bootstrap-only, holds the driver)
-  ui/                chrome (the one global menu) · shell-context · dashboard · nav (composeNav) ·
-                     menu-config (`#menu-config`) · icons (lucide sprite builder) · list-query · paginate
+  ui/                chrome (`ctx.chrome`: menu, brand, user) · nav (composeNav) · menu-config
+                     (`#menu-config`) · icons (lucide sprite builder) · list-query · paginate
 
 plugin-api/          The `@plainpages/plugin-api` package — the author barrel, linked into /node_modules
 views/               Core EJS in the one app shell: home, index, auth, oauth-consent, error, 403/404/500/503,

ci.sh

@@ -53,6 +53,11 @@ docker compose build web
 step "Typecheck"
 docker compose run --rm --no-deps web npm run typecheck
 
+# The specs import @playwright/test, which only the runner image installs, so they typecheck there
+# rather than in the web image. --no-deps skips web; the visual file just names the e2e service.
+step "Typecheck e2e-tests"
+docker compose -f compose.yml -f e2e-tests/compose.visual.yml run --user "$(id -u):$(id -g)" --rm --no-deps --build e2e npm run typecheck
+
 step "Unit tests"
 units=$(docker compose run --rm --no-deps web npm test 2>&1) || { echo "$units"; exit 1; }
 echo "$units" | grep -E '^. (tests|pass|fail) ' || true

compose.override.yml

@@ -49,7 +49,7 @@ services:
   # backs it (PLUGIN_SETTING_SCHEDULING_UPSTREAM above points here). Stand-in for the customer's real service —
   # stdlib-only, in-memory, no auth. Prod points PLUGIN_SETTING_SCHEDULING_UPSTREAM at the real backend instead.
   shifts-upstream:
-    image: node:24.22.1-alpine3.24
+    image: node:24.22.2-alpine3.24
     command: node /srv/server.ts
     restart: unless-stopped
     volumes:
@@ -58,7 +58,7 @@ services:
   # Dev mail catcher — Kratos recovery/verification emails land here (web UI on 8025).
   # kratos.yml points the courier at smtp://mailpit:1025; prod uses a real SMTP via env.
   mailpit:
-    image: axllent/mailpit:v1.32.0
+    image: axllent/mailpit:v1.33.0
     ports:
       - "8025:8025"
     restart: unless-stopped

docs/comprehension-history.md

@@ -0,0 +1,108 @@
+# Comprehension history
+
+## 2026-10-31T00:16:02Z, PR #181 at 56ff987, against eed1050
+
+Ruling: better
+
+| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
+|---|---|---|---|---|---|
+| Mid A | same | better | same | better | better |
+| Inherited architect | same | better | same | better | better |
+
+Mid A, decided by:
+
+- Self-sufficiency, Locality: `public/css/styles.css:24` `:root`: the comment above the hex palette says why a colour must not be oklch(), where a colour is edited
+- Locality: `src/ui/stylesheet-floor.test.ts:11` `declares no oklch() colour`: a colour edit that breaks the browser floor fails a test instead of an old engine
+
+Inherited architect, decided by:
+
+- Self-sufficiency, Locality: `public/css/styles.css:24` `:root`: the comment above the hex palette says why a colour must not be oklch(), where a colour is edited
+- Locality: `src/ui/stylesheet-floor.test.ts:11` `declares no oklch() colour`: a red gate explains the symptom in the file it lands on
+- Self-sufficiency: `README.md:1027` "Two browser floors": the colour rule now sits beside the floor rule
+
+## 2026-10-31T00:43:19Z, PR #182 at 19987ba, against 3e70768
+
+Ruling: better
+
+| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
+|---|---|---|---|---|---|
+| Mid A | better | better | better | better | better |
+| Inherited architect | better | better | better | better | better |
+
+Mid A, decided by:
+
+- Navigation, Shape, Self-sufficiency, Overall: `public/css/auth.css:1` `auth.css`: about 120 lines of rules for markup no view renders are gone, so a cold reader no longer rules them out first
+- Locality, Self-sufficiency, Overall: `public/css/styles.css:31` `--on-accent`: the text colour on the accent is one token where four hard-coded `#fff` stood
+- Self-sufficiency, Navigation, Overall: `public/css/styles.css:287` `@supports not selector(:has(a))`: the nav comment, the partial's header and the rule all say the tree folds only where `:has()` works
+- Locality: `public/css/styles.css:241` `@supports selector(:has(a))`: the nav-fold behaviour now sits in two blocks about 50 lines apart, the second order-dependent; the comment names it
+
+Inherited architect, decided by:
+
+- Navigation, Shape, Overall: `public/css/auth.css:1` `auth.css`: the false `:target` banner and the phantom state machine are gone, so every selector left names something a view emits
+- Self-sufficiency, Overall: `views/partials/nav-tree.ejs:4` `nav-tree.ejs`: the header and `public/css/styles.css:194` now say the branch folds only where `:has()` works; the old text was untrue on old engines
+- Locality, Overall: `public/css/styles.css:31` `--l-on-accent`: one token feeds `.btn-primary`, `.page-btn[aria-current]` and `.brand-mark`
+- Locality: `public/css/styles.css:287` `@supports not selector(:has(a))`: its `.nav-disc` rule sits about 85 lines from the nav rules it overrides, and `stylesheet-floor.test.ts` guards the order for `.theme-switch` only
+- Self-sufficiency: `src/ui/stylesheet-contrast.test.ts:29` `stylesheet-contrast.test.ts`: the darker badge colours now have a stated 4.5:1 reason someone can find
+
+## 2026-10-31T01:09:38Z, PR #183 at 0f20b38, against 364b047
+
+Ruling: better
+
+| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
+|---|---|---|---|---|---|
+| Mid A | same | same | same | better | better |
+| Inherited architect | same | better | same | better | better |
+
+Mid A, decided by:
+
+- Self-sufficiency, Overall: `public/css/styles.css:1` `App Shell Template header`: the false `light-dark()` bullet is gone, so no reader has to work out which of two comments is lying
+- Self-sufficiency, Overall: `public/css/styles.css:687` `@supports selector(:has(a))` in `@media (max-width: 860px)`: the guard and its comment say what an engine without `:has()` gets, without opening the CHANGELOG
+
+Inherited architect, decided by:
+
+- Self-sufficiency, Overall: `public/css/styles.css:5` `Architecture` header: the false `light-dark()` bullet is gone, so the header no longer contradicts the TOKENS comment
+- Locality, Self-sufficiency, Overall: `public/css/styles.css:687` `@supports selector(:has(a))` in `@media (max-width: 860px)`: the guard and its comment put the dependency of the open state on `:has()` where an editor would change it
+
+## 2026-10-31T01:19:49Z, PR #184 at af157c9, against bb8e6bc
+
+Ruling: better
+
+| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
+|---|---|---|---|---|---|
+| Mid A | better | same | same | better | better |
+| Inherited architect | better | better | same | better | better |
+
+Mid A, decided by:
+
+- Self-sufficiency, Navigation, Overall: `public/css/styles.css:12` `TOKENS` header comment: says all three theme rules need `:has()`, names the engines without it and points to the `@supports not selector(:has(a))` block, where the old text called the swaps "rock-solid"
+- Navigation, Self-sufficiency, Overall: `README.md:214` `## Glossary`: defines host, plugin, manifest, chrome, nav fragment, permission name, system plugin and denylist and links each to its home section
+- Self-sufficiency: `README.md:815` `Plugin dependencies`: the scale bullet states the plugin count the per-plugin dependency design assumes
+
+Inherited architect, decided by:
+
+- Self-sufficiency, Locality, Overall: `public/css/styles.css:12` `1. TOKENS` comment: an editor of the theme mapping learns of the distant `:has()` fallback from the comment, where the old text said the swap could not fail
+- Navigation, Self-sufficiency, Overall: `README.md:214` `## Glossary`: a cold reader reaches "chrome" or "denylist" and their home sections in one hop
+- Self-sufficiency: `README.md:815` `### Plugin dependencies`: the scale bullet gives the plugin count the dependency design assumes
+
+## 2026-10-31T07:26:19Z, PR #187 at 10152d2, against b336dee
+
+Ruling: better
+
+| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
+|---|---|---|---|---|---|
+| Mid A | same | same | better | better | better |
+| Inherited architect | same | same | better | better | better |
+
+Mid A, decided by:
+
+- Self-sufficiency, Overall: `e2e-tests/mock-oidc.ts:18` `idToken`: the helpers' signatures now say what `res`, `nonce` and the `codes` map hold
+- Self-sufficiency: `e2e-tests/proxy.ts:14` `toKratos`: `(path: string): boolean` shows the routing predicate's contract
+- Self-sufficiency: `e2e-tests/tsconfig.json:2` `extends`: the specs are held to the host's strict flags, and the Dockerfile comment explains the path link
+- Shape, Overall: `src/ui/icons.ts:4` `ICON_NAMES`: the comment "the icons the UI actually references" is true again
+
+Inherited architect, decided by:
+
+- Self-sufficiency, Overall: `e2e-tests/mock-oidc.ts:18` `b64`: typed helpers replace a trace through the `createServer` callback
+- Self-sufficiency: `e2e-tests/proxy.ts:14` `toKratos`: the predicate's contract is readable on its own line
+- Self-sufficiency: `e2e-tests/Dockerfile:11` `COPY tsconfig.json`: the relative `extends` path works in the checkout and in the image, and a comment names the link
+- Shape, Overall: `src/ui/icons.ts:4` `ICON_NAMES`: the registry matches its description, with no dead ids

docs/reading-cost.md

@@ -0,0 +1,194 @@
+# Reading cost
+
+## Reading cost, chunk 57e864bce02a, finished 2026-10-30T23:59:00Z
+
+100624 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `src/http/app.test.ts` 9
+- `README.md` 7
+- `src/http/app.ts` 4
+- `todo.md` 3
+- `e2e-tests/playwright.config.ts` 2
+- `AGENTS.md` 1
+- `CHANGELOG.md` 1
+- `ci.sh` 1
+- `examples/plugins/scheduling/views/shifts.ejs` 1
+- `src/auth/csrf.ts` 1
+
+## Reading cost, chunk df5e30a4db5f, finished 2026-10-31T00:22:00Z
+
+80251 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `todo.md` 5
+- `README.md` 3
+- `CHANGELOG.md` 2
+- `public/css/styles.css` 2
+- `AGENTS.md` 1
+- `src/ui/stylesheet-floor.test.ts` 1
+- `src/ui/theme-switch.test.ts` 1
+
+## Reading cost, chunk 3bf0b1a97d77, finished 2026-10-31T00:48:14Z
+
+167985 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `public/css/styles.css` 17
+- `todo.md` 7
+- `README.md` 6
+- `public/css/auth.css` 5
+- `AGENTS.md` 1
+- `CHANGELOG.md` 1
+- `examples/plugins/scheduling/public/scheduling.css` 1
+- `examples/plugins/scheduling/views/overview.ejs` 1
+- `examples/plugins/scheduling/views/shifts.ejs` 1
+- `src/http/app.test.ts` 1
+
+## Reading cost, chunk 91d11dbe63f9, finished 2026-10-31T01:13:44Z
+
+69010 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `todo.md` 7
+- `README.md` 4
+- `public/css/styles.css` 4
+- `CHANGELOG.md` 1
+- `src/ui/stylesheet-floor.test.ts` 1
+
+## Reading cost, chunk 70e46c48db80, finished 2026-10-31T07:17:56Z
+
+70843 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `README.md` 18
+- `todo.md` 6
+- `public/css/styles.css` 5
+- `CHANGELOG.md` 2
+- `AGENTS.md` 1
+- `src/auth/jwt-middleware.ts` 1
+
+## Reading cost, chunk 9e8ffd0aa8dc, finished 2026-10-31T07:36:53Z
+
+98975 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `README.md` 9
+- `ci.sh` 3
+- `e2e-tests/visual.spec.ts` 3
+- `todo.md` 3
+- `CHANGELOG.md` 2
+- `e2e-tests/compose.visual.yml` 2
+- `e2e-tests/language.spec.ts` 2
+- `e2e-tests/mock-oidc.ts` 2
+- `src/ci-gate.test.ts` 2
+- `.dockerignore` 1
+
+## Reading cost, chunk 25b7840ff611, finished 2026-10-31T07:46:18Z
+
+73781 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `todo.md` 5
+- `README.md` 2
+- `src/http/app.ts` 2
+- `AGENTS.md` 1
+- `src/http/app.test.ts` 1
+- `src/ui/chrome.test.ts` 1
+- `src/ui/chrome.ts` 1
+- `views/index.ejs` 1
+- `views/partials/shell.ejs` 1
+
+## Reading cost, chunk e4d3bb0ac092, finished 2026-10-31T08:02:27Z
+
+154733 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `todo.md` 10
+- `README.md` 6
+- `package.json` 3
+- `.gitignore` 1
+- `.npmrc` 1
+- `AGENTS.md` 1
+- `ci.sh` 1
+- `public/css/styles.css` 1
+- `renovate.json` 1
+- `src/e2e-console-guard.test.ts` 1
+
+## Reading cost, chunk 2f36d29bd746, finished 2026-10-31T08:19:09Z
+
+85029 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `e2e-tests/full-flow.spec.ts` 4
+- `README.md` 3
+- `src/auth/routes.test.ts` 3
+- `todo.md` 3
+- `src/auth/kratos-public.ts` 2
+- `src/http/app.test.ts` 2
+- `ci.sh` 1
+- `compose.yml` 1
+- `e2e-tests/auth-refresh.spec.ts` 1
+- `src/auth/flow-view.ts` 1
+
+## Reading cost, chunk 3373527a4f72, finished 2026-10-31T08:52:59Z
+
+138664 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `examples/plugins/admin/admin-users.ts` 8
+- `README.md` 7
+- `src/http/app.test.ts` 7
+- `e2e-tests/full-flow.spec.ts` 3
+- `examples/plugins/admin/admin-groups.ts` 3
+- `examples/plugins/admin/admin-users.test.ts` 3
+- `examples/plugins/admin/i18n/en-US.ts` 3
+- `src/ui/icons.ts` 3
+- `todo.md` 3
+- `CHANGELOG.md` 2
+
+## Reading cost, chunk 0118907cad57, finished 2026-10-31T09:32:49Z
+
+116614 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `src/http/app.test.ts` 11
+- `README.md` 7
+- `src/http/app.ts` 6
+- `src/ui/shell.test.ts` 5
+- `e2e-tests/visual.spec.ts` 4
+- `src/http/static.ts` 4
+- `todo.md` 3
+- `src/auth/flow-view.ts` 2
+- `views/partials/shell.ejs` 2
+- `AGENTS.md` 1
+
+## Reading cost reset, 2026-10-31T09:34:55Z
+
+## Reading cost, chunk 55cc9f01b477, finished 2026-10-31T09:42:24Z
+
+94244 new input tokens before the first commit.
+
+Read most (opens and searches):
+
+- `src/http/app.test.ts` 6
+- `README.md` 4
+- `src/http/app-plugins.test.ts` 4
+- `todo.md` 3
+- `AGENTS.md` 2
+- `docs/reading-cost.md` 2
+- `examples/plugins/admin/README.md` 2
+- `ci.sh` 1
+- `examples/plugins/admin/admin-clients.test.ts` 1
+- `examples/plugins/admin/admin-grants.test.ts` 1

e2e-tests/Dockerfile

@@ -8,6 +8,8 @@ COPY e2e-tests/package.json e2e-tests/package-lock.json ./
 RUN npm ci
 
 COPY e2e-tests/ ./
+# e2e-tests/tsconfig.json extends it, so the specs are held to the host's strictness flags.
+COPY tsconfig.json /tsconfig.json
 
 # Runs as the invoking `--user` so artifacts land owned by them, not root — and an arbitrary uid has
 # no passwd entry here, so its home would be the unwritable `/`. npm's cache follows HOME.

e2e-tests/compose.full.yml

@@ -53,7 +53,7 @@ services:
 
   # The reference plugin's upstream (examples/shifts-upstream) so /scheduling/shifts shows real rows.
   shifts-upstream:
-    image: node:24.22.1-alpine3.24
+    image: node:24.22.2-alpine3.24
     command: ["node", "/server.ts"]
     volumes:
       - ./examples/shifts-upstream/server.ts:/server.ts:ro
@@ -66,7 +66,7 @@ services:
   # Mock OIDC provider for the SSO login test — stdlib Node, auto-approves, signs an id_token Kratos
   # verifies via its jwks. Reachable as the same host (mock-oidc:9000) by both the browser and Kratos.
   mock-oidc:
-    image: node:24.22.1-alpine3.24
+    image: node:24.22.2-alpine3.24
     command: ["node", "/mock-oidc.ts"]
     environment:
       ISSUER: http://mock-oidc:9000
@@ -81,7 +81,7 @@ services:
 
   # Same-origin gateway: Kratos-owned paths → kratos, everything else → web (e2e-tests/proxy.ts).
   proxy:
-    image: node:24.22.1-alpine3.24
+    image: node:24.22.2-alpine3.24
     command: ["node", "/proxy.ts"]
     depends_on:
       web:

e2e-tests/full-flow.spec.ts

@@ -1,5 +1,5 @@
 import type { Browser, Page } from "@playwright/test";
-import { expect, test, watchedPage } from "./console-guard.ts";
+import { allowConsole, expect, test, watchedPage } from "./console-guard.ts";
 import { randomUUID } from "node:crypto";
 
 // Full browser E2E: the real Playwright UI against the live stack via the same-origin
@@ -136,7 +136,7 @@ test.describe.serial("authenticated admin journey", () => {
     await expect(page.locator("tr", { hasText: email })).toHaveCount(0);
   });
 
-  test("groups CRUD: create a group (writes go to Keto), see it listed, then grant it a permission", async () => {
+  test("groups CRUD: create a group (writes go to Keto), see it listed, then grant it a permission", async ({ browser }) => {
     // A Keto set exists only while it has ≥1 member, so create needs a first member (the form
     // enforces it); pick the first option (a user) from the required picker.
     const group = `e2e-grp-${suffix}`;
@@ -150,6 +150,10 @@ test.describe.serial("authenticated admin journey", () => {
     // Permissions are declared in plugin code, so the group's detail page offers them as a fixed
     // checkbox list rather than a create form — there is no Permissions screen to visit.
     await page.goto(`/admin/groups/${group}`);
+    allowConsole(/status of 409 .*\/admin\/groups\/[^/]+\/permissions/); // the stale save below, refused on purpose
+    // A second browser signed in as the same admin, opened before the save below, so its form carries the old grants.
+    const staleTab = await watchedPage(await browser.newContext({ storageState: await page.context().storageState() }));
+    await staleTab.goto(`/admin/groups/${group}`);
     const scheduling = page.locator('input[name="permission"][value="scheduling:read"]');
     await expect(scheduling).toHaveCount(1); // declared by the reference plugin, so it's on offer
     await expect(scheduling).not.toBeChecked();
@@ -157,7 +161,16 @@ test.describe.serial("authenticated admin journey", () => {
     await page.locator('form:has(input[name="permission"]) button[type="submit"]').click();
 
     await expect(page).toHaveURL(new RegExp(`/admin/groups/${group}`));
+    await expect(page.getByText("Permissions saved.")).toBeVisible();
     await expect(page.locator('input[name="permission"][value="scheduling:read"]')).toBeChecked();
+
+    // The other tab no longer matches Keto, so its save is refused and shows the grant made above.
+    await staleTab.locator('input[name="permission"][value="scheduling:write"]').check();
+    await staleTab.locator('form:has(input[name="permission"]) button[type="submit"]').click();
+    await expect(staleTab.getByText("changed while you had the page open")).toBeVisible();
+    await expect(staleTab.locator('input[name="permission"][value="scheduling:read"]')).toBeChecked();
+    await expect(staleTab.locator('input[name="permission"][value="scheduling:write"]')).not.toBeChecked();
+    await staleTab.context().close();
   });
 
   test("OAuth2 clients CRUD: register a client (writes go to Hydra), see the one-time secret once, then delete it via the confirm step", async () => {
@@ -240,6 +253,17 @@ test("return_to: a deep link while logged out returns to that page after login",
   await expect(page.locator("h1")).toHaveText("Users");
 });
 
+test("settings: an anonymous visit signs in first, then lands on the settings page", async ({ page }) => {
+  test.setTimeout(90_000);
+  await page.goto("/settings");
+  await expect(page).toHaveURL(/\/login(\?|$)/);
+  await page.fill('input[name="identifier"]', ADMIN_EMAIL);
+  await page.fill('input[name="password"]', ADMIN_PASSWORD);
+  await page.locator('.auth-form button[type="submit"]').click();
+  await expect(page).toHaveURL(/\/settings(\?|$)/);
+  await expect(page.locator("h1")).toHaveText("Account settings");
+});
+
 test("mocked SSO login: the provider button signs a user in via OIDC", async ({ page }) => {
   test.setTimeout(90_000);
   await page.goto("/login");

e2e-tests/mock-oidc.ts

@@ -2,7 +2,7 @@
 // never leaves the compose network. Auto-approves /authorize (no provider login UI), then signs an
 // RS256 id_token Kratos verifies against /jwks. stdlib only, in-memory, NOT app code. The single
 // host (mock-oidc:9000) is reachable by both the browser (/authorize) and Kratos (token/jwks).
-import { createServer } from "node:http";
+import { createServer, type ServerResponse } from "node:http";
 import { createSign, generateKeyPairSync, randomUUID } from "node:crypto";
 
 const ISSUER = process.env.ISSUER ?? "http://mock-oidc:9000";
@@ -15,8 +15,8 @@ const KID = "mock-1";
 const { privateKey, publicKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
 const jwk = { ...publicKey.export({ format: "jwk" }), alg: "RS256", kid: KID, use: "sig" };
 
-const b64 = (o) => Buffer.from(JSON.stringify(o)).toString("base64url");
-function idToken(nonce) {
+const b64 = (o: unknown): string => Buffer.from(JSON.stringify(o)).toString("base64url");
+function idToken(nonce: string): string {
   const now = Math.floor(Date.now() / 1000);
   const header = b64({ alg: "RS256", kid: KID, typ: "JWT" });
   const payload = b64({
@@ -27,8 +27,8 @@ function idToken(nonce) {
   return `${header}.${payload}.${sig}`;
 }
 
-const codes = new Map(); // single-use auth code → the nonce Kratos sent (echoed into the id_token)
-const json = (res, body) => { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify(body)); };
+const codes = new Map<string, string>(); // single-use auth code → the nonce Kratos sent (echoed into the id_token)
+const json = (res: ServerResponse, body: unknown): void => { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify(body)); };
 
 createServer((req, res) => {
   const url = new URL(req.url ?? "/", ISSUER);

e2e-tests/package-lock.json

@@ -6,7 +6,9 @@
     "": {
       "name": "plainpages-e2e",
       "devDependencies": {
-        "@playwright/test": "1.64.1"
+        "@playwright/test": "1.64.1",
+        "@types/node": "24.19.2",
+        "typescript": "7.0.2"
       }
     },
     "node_modules/@playwright/test": {
@@ -25,6 +27,356 @@
         "node": ">=20"
       }
     },
+    "node_modules/@types/node": {
+      "version": "24.19.2",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.19.2.tgz",
+      "integrity": "sha512-93d49wCWJkCyN87MxLpNN6KXPCwFw7bVUg79mGUV1OS40JGWwVCr8n61DXCSqz7CV6/VfPkb7xec7uP2M+QHWQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": ">=7.24.0 <7.24.7"
+      }
+    },
+    "node_modules/@typescript/typescript-aix-ppc64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-aix-ppc64/-/typescript-aix-ppc64-7.0.2.tgz",
+      "integrity": "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-darwin-arm64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-darwin-arm64/-/typescript-darwin-arm64-7.0.2.tgz",
+      "integrity": "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-darwin-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-darwin-x64/-/typescript-darwin-x64-7.0.2.tgz",
+      "integrity": "sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-freebsd-arm64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-freebsd-arm64/-/typescript-freebsd-arm64-7.0.2.tgz",
+      "integrity": "sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-freebsd-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-freebsd-x64/-/typescript-freebsd-x64-7.0.2.tgz",
+      "integrity": "sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-arm": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-arm/-/typescript-linux-arm-7.0.2.tgz",
+      "integrity": "sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-arm64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-arm64/-/typescript-linux-arm64-7.0.2.tgz",
+      "integrity": "sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-loong64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-loong64/-/typescript-linux-loong64-7.0.2.tgz",
+      "integrity": "sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-mips64el": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-mips64el/-/typescript-linux-mips64el-7.0.2.tgz",
+      "integrity": "sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-ppc64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-ppc64/-/typescript-linux-ppc64-7.0.2.tgz",
+      "integrity": "sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-riscv64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-riscv64/-/typescript-linux-riscv64-7.0.2.tgz",
+      "integrity": "sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-s390x": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-s390x/-/typescript-linux-s390x-7.0.2.tgz",
+      "integrity": "sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-x64/-/typescript-linux-x64-7.0.2.tgz",
+      "integrity": "sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-netbsd-arm64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-netbsd-arm64/-/typescript-netbsd-arm64-7.0.2.tgz",
+      "integrity": "sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-netbsd-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-netbsd-x64/-/typescript-netbsd-x64-7.0.2.tgz",
+      "integrity": "sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-openbsd-arm64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-openbsd-arm64/-/typescript-openbsd-arm64-7.0.2.tgz",
+      "integrity": "sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-openbsd-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-openbsd-x64/-/typescript-openbsd-x64-7.0.2.tgz",
+      "integrity": "sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-sunos-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-sunos-x64/-/typescript-sunos-x64-7.0.2.tgz",
+      "integrity": "sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-win32-arm64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-win32-arm64/-/typescript-win32-arm64-7.0.2.tgz",
+      "integrity": "sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-win32-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-win32-x64/-/typescript-win32-x64-7.0.2.tgz",
+      "integrity": "sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
     "node_modules/playwright": {
       "version": "1.64.1",
       "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.64.1.tgz",
@@ -53,6 +405,48 @@
       "engines": {
         "node": ">=20"
       }
+    },
+    "node_modules/typescript": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz",
+      "integrity": "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc"
+      },
+      "engines": {
+        "node": ">=16.20.0"
+      },
+      "optionalDependencies": {
+        "@typescript/typescript-aix-ppc64": "7.0.2",
+        "@typescript/typescript-darwin-arm64": "7.0.2",
+        "@typescript/typescript-darwin-x64": "7.0.2",
+        "@typescript/typescript-freebsd-arm64": "7.0.2",
+        "@typescript/typescript-freebsd-x64": "7.0.2",
+        "@typescript/typescript-linux-arm": "7.0.2",
+        "@typescript/typescript-linux-arm64": "7.0.2",
+        "@typescript/typescript-linux-loong64": "7.0.2",
+        "@typescript/typescript-linux-mips64el": "7.0.2",
+        "@typescript/typescript-linux-ppc64": "7.0.2",
+        "@typescript/typescript-linux-riscv64": "7.0.2",
+        "@typescript/typescript-linux-s390x": "7.0.2",
+        "@typescript/typescript-linux-x64": "7.0.2",
+        "@typescript/typescript-netbsd-arm64": "7.0.2",
+        "@typescript/typescript-netbsd-x64": "7.0.2",
+        "@typescript/typescript-openbsd-arm64": "7.0.2",
+        "@typescript/typescript-openbsd-x64": "7.0.2",
+        "@typescript/typescript-sunos-x64": "7.0.2",
+        "@typescript/typescript-win32-arm64": "7.0.2",
+        "@typescript/typescript-win32-x64": "7.0.2"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "7.24.6",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
+      "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==",
+      "dev": true,
+      "license": "MIT"
     }
   }
 }

e2e-tests/package.json

@@ -4,9 +4,12 @@
   "description": "Playwright E2E: design-system parity (visual), auth refresh, OAuth2 login/consent, and the full browser flow (login/menu/CRUD/plugin/logout).",
   "type": "module",
   "scripts": {
-    "test": "playwright test"
+    "test": "playwright test",
+    "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@playwright/test": "1.64.1"
+    "@playwright/test": "1.64.1",
+    "@types/node": "24.19.2",
+    "typescript": "7.0.2"
   }
 }

e2e-tests/playwright.config.ts

@@ -10,6 +10,7 @@ export default defineConfig({
   testDir: ".",
   outputDir: "artifacts/test-output",
   fullyParallel: true,
+  workers: 4, // Playwright's default is half the cores, so a run's parallelism would depend on the machine
   forbidOnly: true,
   reporter: [["list"], ["html", { open: "never", outputFolder: "artifacts/report" }]],
   use: {

e2e-tests/proxy.ts

@@ -11,7 +11,7 @@ const PORT = Number(process.env.PORT ?? 80);
 
 // Kratos public owns these prefixes (self-service flows, sessions, its well-known/schemas); the
 // browser hits them via the flow action + OIDC callbacks. Everything else is the web app.
-const toKratos = (path) => ["/self-service", "/sessions", "/.well-known/ory", "/schemas"].some((p) => path === p || path.startsWith(`${p}/`));
+const toKratos = (path: string): boolean => ["/self-service", "/sessions", "/.well-known/ory", "/schemas"].some((p) => path === p || path.startsWith(`${p}/`));
 
 createServer((req, res) => {
   const target = toKratos(req.url ?? "/") ? KRATOS : WEB;

e2e-tests/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": { "lib": ["ESNext", "DOM"] },
+  "include": ["*.ts"]
+}

e2e-tests/visual.spec.ts

@@ -10,6 +10,15 @@ const SESSION_COOKIE = "plainpages_jwt"; // src/auth/login.ts — web verifies i
 const shot = (page: Page, name: string): Promise<Buffer> =>
   page.screenshot({ fullPage: true, path: `artifacts/screenshots/${test.info().project.name}/${name}.png` });
 
+// Either side of the stylesheet's 860px and 560px breakpoints.
+const VIEWPORTS = [
+  { name: "desktop-xl", width: 1920, height: 1080 },
+  { name: "laptop", width: 1280, height: 800 },
+  { name: "tablet", width: 768, height: 1024 },
+  { name: "phone", width: 390, height: 844 },
+  { name: "phone-small", width: 320, height: 568 },
+] as const;
+
 // Sign a session JWT with the committed dev tokenizer key (bind-mounted at /repo/jwks.json), so the
 // gated dashboard renders for a "signed-in" user without standing up Ory — web verifies it
 // with the same key by `kid`, exactly as it verifies a real Kratos-tokenizer JWT.
@@ -34,7 +43,7 @@ for (const [name, path, tail] of [
   ["the starter dashboard", "/dashboard", ".form-actions .btn"],
   ["the public landing", "/", ".landing-actions .btn"],
 ] as const) {
-  for (const width of [1280, 390]) {
+  for (const { width } of VIEWPORTS) {
     test(`${name} scrolls to its end at ${width}px wide`, async ({ page }) => {
       await page.setViewportSize({ width, height: 200 });
       await page.goto(path);
@@ -77,13 +86,21 @@ test("captures the live pages for review", async ({ page }) => {
   await page.goto("/dashboard");
   await page.locator("#theme-dark").check({ force: true }); // visually-hidden radio
   await shot(page, "live-03-dark");
-
-  await page.setViewportSize({ width: 390, height: 844 });
-  await page.goto("/dashboard");
-  await shot(page, "live-04-mobile");
-  await page.setViewportSize({ width: 1280, height: 800 });
 });
 
+// The page is a document, so a column wider than the viewport can only show as sideways scroll.
+for (const { name, width, height } of VIEWPORTS) {
+  for (const [path, label] of [["/dashboard", "dashboard"], ["/", "landing"], ["/scheduling", "plugin"]] as const) {
+    test(`the ${label} page fits ${width}px wide, with no sideways scroll`, async ({ page }) => {
+      await page.setViewportSize({ width, height });
+      await page.goto(path);
+      const [scrollWidth, clientWidth] = await page.evaluate(() => [document.documentElement.scrollWidth, document.documentElement.clientWidth] as const);
+      expect(scrollWidth).toBeLessThanOrEqual(clientWidth);
+      await shot(page, `live-${label}-${name}`);
+    });
+  }
+}
+
 test("every icon <use> resolves to a defined <symbol> (no broken graphics)", async ({ page }) => {
   await page.goto("/dashboard");
   const missing = await page.evaluate(() => {
@@ -148,6 +165,21 @@ test("mobile layout hides the sidebar off-canvas behind the hamburger", async ({
   expect(offCanvas).toBe(true);
 });
 
+test("the hamburger opens the drawer over the scrim, and a link in it navigates", async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto("/dashboard");
+  await page.locator(".hamburger").click();
+
+  const sidebar = page.locator(".sidebar");
+  await expect(sidebar).toBeInViewport({ ratio: 1 });
+  // A click is refused while the scrim sits above the drawer, which a lower z-index would cause.
+  await sidebar.locator("summary").first().click(); // the dashboard is the current page, so its links are in a folded branch
+  const link = sidebar.locator(".nav-children a.nav-self").first();
+  const target = await link.getAttribute("href");
+  await link.click();
+  await expect(page).toHaveURL((url) => url.pathname === target?.split("?")[0]);
+});
+
 test("Sign-out is a CSRF-guarded POST form: the token is issued on the page, a tokenless POST is refused", async ({ page }) => {
   await page.goto("/dashboard");
   // The page issues a CSRF cookie and embeds the same token in the Sign-out form (double-submit).
@@ -174,6 +206,68 @@ test("the public landing at / is ungated and links to sign in + register", async
   await shot(page, "live-05-public-landing");
 });
 
+// Measured on the rendered elements, so a theme block that drops --on-accent fails here.
+const contrastOf = (el: Element): number => {
+  const luminance = (rgb: string): number => {
+    const [r = 0, g = 0, b = 0] = (rgb.match(/[\d.]+/g) ?? []).map((c) => {
+      const v = Number(c) / 255;
+      return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  };
+  const style = getComputedStyle(el);
+  const [hi = 0, lo = 0] = [luminance(style.color), luminance(style.backgroundColor)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+};
+for (const [name, colorScheme, forceDark] of [["light", "light", false], ["dark", "dark", false], ["forced dark", "light", true]] as const) {
+  test(`text on the accent reaches 4.5:1 in ${name} mode`, async ({ page, context }) => {
+    await context.clearCookies();
+    await page.emulateMedia({ colorScheme });
+    await page.goto("/");
+    if (forceDark) await page.locator("#theme-dark").check({ force: true });
+    // No page of this stack has a second page of results, so add the current-page button.
+    await page.locator("#main-content").evaluate((el) => el.insertAdjacentHTML("beforeend", '<a class="page-btn" aria-current="page" href="#">2</a>'));
+    for (const selector of [".landing .btn-primary", ".brand-mark", ".page-btn"]) {
+      await expect.poll(() => page.locator(selector).first().evaluate(contrastOf), { message: selector }).toBeGreaterThanOrEqual(4.5); // polls past the colour transition
+    }
+  });
+}
+
+test("a nav branch is folded until its toggle opens it — no JavaScript", async ({ page }) => {
+  await page.goto("/dashboard");
+  const child = page.locator('.sidebar a[href="/scheduling"]');
+  await expect(child).toBeHidden();
+  await page.locator('.sidebar summary[aria-label="Toggle Scheduling"]').click();
+  await expect(child).toBeVisible();
+});
+
+test("the reference plugin's lead text is inset by --pad-x, like the bars around it", async ({ page }) => {
+  await page.goto("/scheduling");
+  const [inset, padX] = await page.locator(".scheduling-page > p").evaluate((p) => [
+    p.getBoundingClientRect().left - (p.parentElement as HTMLElement).getBoundingClientRect().left,
+    parseFloat(getComputedStyle(document.documentElement).getPropertyValue("--pad-x")),
+  ] as const);
+  expect(inset).toBe(padX);
+});
+
+// transferSize is 0 only for a response the browser's own cache served; a 304 still costs a round trip.
+test("a repeat page view fetches no stylesheet again", async ({ page }) => {
+  const stylesheets = (): Promise<{ name: string; transferSize: number }[]> => page.evaluate(() =>
+    performance.getEntriesByType("resource")
+      .filter((entry): entry is PerformanceResourceTiming => entry instanceof PerformanceResourceTiming && entry.initiatorType === "link" && entry.name.includes(".css"))
+      .map(({ name, transferSize }) => ({ name, transferSize })));
+
+  await page.goto("/");
+  const first = await stylesheets();
+  expect(first.length, "the landing links styles.css and auth.css").toBeGreaterThanOrEqual(2);
+  for (const { name, transferSize } of first) expect(transferSize, `${name} on the first view`).toBeGreaterThan(0);
+
+  await page.goto("/");
+  const repeat = await stylesheets();
+  expect(repeat.map(({ name }) => name)).toEqual(first.map(({ name }) => name));
+  for (const { name, transferSize } of repeat) expect(transferSize, `${name} on the repeat view`).toBe(0);
+});
+
 test("unknown routes serve the 404 page (a real user-facing flow, covered end-to-end)", async ({ page }) => {
   allowConsole(/status of 404 .*\/no-such-page$/); // the navigation under test, which Chromium and WebKit log — not a sub-resource of it
   const res = await page.goto("/no-such-page");

examples/plugins/admin/README.md

@@ -62,4 +62,4 @@ property of a user or a group, edited as a checkbox list on those two screens (`
 
 The three screens hold **no state** — everything lives in Ory. Handlers are thin, so their builders
 unit-test as pure functions with no host; the HTTP routing/gate/CSRF is covered in
-`src/http/app.test.ts` (which mounts this plugin) and end-to-end in `e2e-tests/full-flow.spec.ts`.
+`src/http/app-admin.test.ts` (which mounts this plugin) and end-to-end in `e2e-tests/full-flow.spec.ts`.

examples/plugins/admin/admin-clients.test.ts

@@ -1,6 +1,6 @@
 // Built-in OAuth2 clients admin screen: the pure view-model + Hydra-payload builders. A client
 // is an Ory Hydra OAuth2 client (apps that log in *through* us); writes go only to Hydra. The
-// HTTP routing/gate/CSRF + live Hydra calls (incl. the one-time secret) are exercised in app.test.ts.
+// HTTP routing/gate/CSRF + live Hydra calls (incl. the one-time secret) are exercised in src/http/app-admin.test.ts.
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import {

examples/plugins/admin/admin-grants.test.ts

@@ -1,9 +1,10 @@
 // The pure half of permission granting: what a submitted checkbox set changes, and the picker the
-// two screens render from it. The Keto writes and the HTTP round trip are covered in app.test.ts.
+// two screens render from it. The Keto writes and the HTTP round trip are covered in src/http/app-admin.test.ts.
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import type { PermissionDecl } from "@plainpages/plugin-api";
-import { buildPermissionPicker, grantDiff, grantTuple, groupSubject, userSubject } from "./admin-grants.ts";
+import type { KetoClient } from "@plainpages/plugin-api";
+import { applyGrants, baselineToken, buildPermissionPicker, grantDiff, grantTuple, groupSubject, isStale, userSubject } from "./admin-grants.ts";
 
 const declared: PermissionDecl[] = [
   { description: "View users", name: "users:read" },
@@ -81,3 +82,48 @@ test("buildPermissionPicker says so when no plugin declares a permission, rather
   assert.deepEqual(picker.choices, []);
   assert.ok(picker.empty);
 });
+
+test("baselineToken depends on the offered grants held, not on their order or on undeclared ones", () => {
+  const token = baselineToken(declared, ["users:read", "users:write"]);
+  assert.match(token, /^[0-9a-f]+$/);
+  assert.equal(baselineToken(declared, ["users:write", "users:read"]), token);
+  assert.equal(baselineToken(declared, ["users:read", "users:write", "legacy:thing"]), token); // undeclared: never shown, never saved
+  assert.notEqual(baselineToken(declared, ["users:read"]), token);
+  assert.notEqual(baselineToken(declared, []), token);
+  assert.notEqual(baselineToken(declared, []), ""); // an empty set is a state too, not an absent token
+  assert.equal(buildPermissionPicker({ action: "/x", declared, direct: ["users:read", "users:write"] }).baseline, token);
+});
+
+test("isStale refuses a missing or old token, but only for a save that would change something", () => {
+  const held = ["users:read"];
+  const change = grantDiff(declared, held, ["users:read", "users:write"]);
+  const nothing = grantDiff(declared, held, ["users:read"]);
+  const current = new URLSearchParams({ baseline: baselineToken(declared, held) });
+  const old = new URLSearchParams({ baseline: baselineToken(declared, []) });
+  assert.equal(isStale(current, declared, held, change), false);
+  assert.equal(isStale(old, declared, held, change), true);
+  assert.equal(isStale(new URLSearchParams(), declared, held, change), true); // no token at all
+  assert.equal(isStale(old, declared, held, nothing), false); // a repeated save has nothing to refuse
+});
+
+test("applyGrants applies writes then deletes, and on a Keto failure stops and reports what was applied", async () => {
+  const log: string[] = [];
+  const keto = (failOn?: string): KetoClient => ({
+    check: async () => false,
+    deleteTuple: async (tp) => { if (tp.object === failOn) throw new Error("boom"); log.push(`delete ${tp.object}`); },
+    expand: async () => ({ type: "leaf" }),
+    listRelations: async () => ({ nextPageToken: null, tuples: [] }),
+    writeTuple: async (tp) => { if (tp.object === failOn) throw new Error("boom"); log.push(`write ${tp.object}`); },
+  });
+  const diff = { grant: ["a:read", "b:read"], revoke: ["c:read"] };
+
+  const ok = await applyGrants(keto(), userSubject("u1"), diff);
+  assert.deepEqual(ok, { applied: diff });
+  assert.deepEqual(log, ["write a:read", "write b:read", "delete c:read"]);
+
+  log.length = 0;
+  const failed = await applyGrants(keto("b:read"), userSubject("u1"), diff);
+  assert.deepEqual(failed.applied, { grant: ["a:read"], revoke: [] });
+  assert.ok(failed.error instanceof Error);
+  assert.deepEqual(log, ["write a:read"]); // nothing after the failure was attempted
+});

examples/plugins/admin/admin-grants.ts

@@ -6,11 +6,17 @@
 // what the installed plugins declare in code. Nothing here invents a name, which is why the old
 // Permissions screen is gone: a grant is a property of a user or a group, edited where they are.
 
+import { createHash } from "node:crypto";
 import type { KetoClient, PermissionDecl, RelationTuple, SubjectSet, Translate } from "@plainpages/plugin-api";
 
 const PERMISSION_NS = "Permission";
 const GRANTED = "granted";
 export const PERMISSIONS_FIELD = "permission"; // the checkbox name the two forms post
+export const BASELINE_FIELD = "baseline"; // the hidden field carrying baselineToken
+export const SAVED_NOTICE = "permissions-saved"; // the `info-msg` a successful save redirects with
+
+// Only that exact value counts, so a crafted link can't put words on the page.
+export const isSavedNotice = (url: URL): boolean => url.searchParams.get("info-msg") === SAVED_NOTICE;
 
 export type GrantSubject = { subject_id: string } | { subject_set: SubjectSet };
 
@@ -53,6 +59,7 @@ export interface PermissionChoice {
 
 export interface PermissionPicker {
   action: string;
+  baseline: string; // baselineToken of the direct grants this form was rendered from
   choices: PermissionChoice[];
   empty: string | undefined; // set when no plugin declares a permission — the picker has nothing to offer
   error?: string; // a rejected save (e.g. the self-revoke guard), rendered above the list
@@ -60,6 +67,7 @@ export interface PermissionPicker {
   hint: string;
   inheritedNote: string | undefined; // set when at least one choice is group-held, to explain the disabled row
   legend: string;
+  notice?: string; // a confirmation, rendered above the list
   // Set for a group: its members hold these transitively, so a change reaches them at their next
   // re-mint rather than at once. The user picker revokes live tokens, so it says nothing.
   pending: string | undefined;
@@ -90,6 +98,7 @@ export function buildPermissionPicker(opts: {
   }));
   return {
     action: opts.action,
+    baseline: baselineToken(opts.declared, opts.direct),
     choices,
     empty: opts.declared.length === 0 ? t("admin.grants.none") : undefined,
     field: PERMISSIONS_FIELD,
@@ -107,7 +116,7 @@ export function buildPermissionPicker(opts: {
 // What a submitted set changes. Pure so the diff is testable without Keto: only declared names are
 // considered, so a crafted POST cannot grant something no plugin gates on, and a held-but-undeclared
 // name (left over from an uninstalled plugin) is never silently revoked by an unrelated save.
-export function grantDiff(declared: readonly PermissionDecl[], held: string[], wanted: string[]): { grant: string[]; revoke: string[] } {
+export function grantDiff(declared: readonly PermissionDecl[], held: string[], wanted: string[]): GrantChange {
   const offered = new Set(declared.map((d) => d.name));
   const heldSet = new Set(held);
   const wantedSet = new Set(wanted.filter((name) => offered.has(name)));
@@ -117,7 +126,32 @@ export function grantDiff(declared: readonly PermissionDecl[], held: string[], w
   };
 }
 
-export async function applyGrants(keto: KetoClient, subject: GrantSubject, diff: { grant: string[]; revoke: string[] }): Promise<void> {
-  for (const name of diff.grant) await keto.writeTuple(grantTuple(name, subject));
-  for (const name of diff.revoke) await keto.deleteTuple(grantTuple(name, subject));
+// A token for the direct grants a form was rendered from. Like grantDiff it covers only the declared
+// names the form offered. It is a digest so an empty set is still a token; it is a guard against a
+// stale page, not a secret, since anyone who can read the page can compute it.
+export function baselineToken(declared: readonly PermissionDecl[], held: string[]): string {
+  const offered = new Set(declared.map((d) => d.name));
+  return createHash("sha256").update(held.filter((name) => offered.has(name)).sort().join("\n")).digest("hex").slice(0, 16);
+}
+
+// True when the form's token is missing or no longer matches Keto *and* the save would change
+// something. A save that changes nothing, such as a double-clicked Save whose first POST landed, is
+// harmless, so it is not refused.
+export const isStale = (form: { get(name: string): string | null }, declared: readonly PermissionDecl[], held: string[], diff: GrantChange): boolean =>
+  (diff.grant.length > 0 || diff.revoke.length > 0) && form.get(BASELINE_FIELD) !== baselineToken(declared, held);
+
+export interface GrantChange { grant: string[]; revoke: string[] }
+
+// KetoClient writes one tuple per call, so the writes and deletes run one by one and stop at the first
+// failure. What was applied by then is returned beside the error, so the caller can still revoke live
+// tokens and tell the admin the save is only partly done.
+export async function applyGrants(keto: KetoClient, subject: GrantSubject, diff: GrantChange): Promise<{ applied: GrantChange; error?: unknown }> {
+  const applied: GrantChange = { grant: [], revoke: [] };
+  try {
+    for (const name of diff.grant) { await keto.writeTuple(grantTuple(name, subject)); applied.grant.push(name); }
+    for (const name of diff.revoke) { await keto.deleteTuple(grantTuple(name, subject)); applied.revoke.push(name); }
+  } catch (error) {
+    return { applied, error };
+  }
+  return { applied };
 }

examples/plugins/admin/admin-groups.test.ts

@@ -1,7 +1,7 @@
 // Built-in Groups admin screen: the pure view-model + Keto-tuple builders. A group is a
 // Keto subject set (Group:<name>#members); membership tuples carry users (subject_id) or nested
 // groups (subject_set). The HTTP routing/gate/CSRF + live Keto/Kratos calls are exercised over
-// HTTP in app.test.ts.
+// HTTP in src/http/app-admin.test.ts.
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import {

examples/plugins/admin/admin-groups.ts

@@ -7,8 +7,8 @@
 // each returning a RouteResult.
 
 import { can, type KetoClient, type KratosAdmin, paginate, parseListQuery, type RelationQuery, type RelationTuple, type RequestContext, type RouteHandler, type RouteResult, type SubjectSet, type Translate, type User } from "@plainpages/plugin-api";
-import { applyGrants, buildPermissionPicker, effectivePermissions, grantDiff, grantTuple, groupSubject, heldPermissions, type PermissionPicker, PERMISSIONS_FIELD } from "./admin-grants.ts";
-import { ADMIN_EN, type AdminAction, ADMIN_GROUPS_BASE, buildConfirmModel, guardedForm, notFound, permissionName, requirePermission, unavailable } from "./admin-shared.ts";
+import { applyGrants, buildPermissionPicker, effectivePermissions, grantDiff, grantTuple, groupSubject, heldPermissions, isSavedNotice, isStale, type PermissionPicker, PERMISSIONS_FIELD, SAVED_NOTICE, userSubject } from "./admin-grants.ts";
+import { ADMIN_EN, type AdminAction, ADMIN_GROUPS_BASE, buildConfirmModel, guardedForm, notFound, partialSave, permissionName, requirePermission, unavailable } from "./admin-shared.ts";
 import type { FieldConfig } from "./admin-users.ts";
 
 const GROUP_NS = "Group";
@@ -293,6 +293,32 @@ async function groupExists(keto: KetoClient, name: string): Promise<boolean> {
   return page.tuples.length > 0;
 }
 
+const isMember = (keto: KetoClient, actor: string, group: string): Promise<boolean> =>
+  keto.check({ namespace: GROUP_NS, object: group, relation: MEMBERS, subject_id: `user:${actor}` });
+
+// The self-lockout guard, the group-side twin of the Users screen's self-revoke one: of the permissions
+// a change takes from a group the actor is in, those they don't hold directly. One they also hold
+// through another group is included, since telling those apart needs a reverse Keto query.
+async function lostToSelf(keto: KetoClient, actor: string, taken: readonly string[]): Promise<string[]> {
+  if (taken.length === 0) return [];
+  const direct = new Set(await heldPermissions(keto, userSubject(actor)));
+  return taken.filter((name) => !direct.has(name));
+}
+
+// Leaving a group takes everything it confers, including through its own parents.
+async function lostOnLeaving({ ctx, keto, user }: GroupsDeps, group: string): Promise<string[]> {
+  return lostToSelf(keto, user.id, await effectivePermissions(keto, groupSubject(group), ctx.declaredPermissions));
+}
+
+async function lostOnDelete(deps: GroupsDeps, group: string): Promise<string[]> {
+  return (await isMember(deps.keto, deps.user.id, group)) ? lostOnLeaving(deps, group) : [];
+}
+
+async function refuseSelfLockout(deps: GroupsDeps, name: string, action: string, lost: string[]): Promise<RouteResult> {
+  deps.ctx.log.warn("admin: refused a group change that would lock the actor out", { action, actor: deps.user.id, group: name, lost: lost.join(",") });
+  return { ...(await groupDetailPage(deps, name, { pageError: deps.ctx.t("admin.groups.error.selfLockout", { permissions: lost.join(", ") }) })), status: 400 };
+}
+
 // Shared per-request deps for the Groups screen, resolved by `withGroups`: the gate (`groups:read` on
 // a GET, `groups:write` on a POST) + the Keto and Kratos capabilities (else a themed 503). Each route
 // below is a thin handler over these.
@@ -347,36 +373,54 @@ export const groupsCreate = withGroups(async (deps) => {
 // GET /admin/groups/new — the create form.
 export const groupsNewForm = withGroups((deps) => groupFormResult(deps, {}), "write");
 
-// GET /admin/groups/:name — the detail + membership page.
-export const groupsDetail = withGroupName(async ({ ctx, keto, kratosAdmin }, name) => {
+// The detail + membership page. `notice` and `error` ride the permission picker; `pageError` tops the
+// page, for any change refused because it would lock the actor out.
+async function groupDetailPage({ ctx, keto, kratosAdmin }: GroupsDeps, name: string, say: { error?: string; notice?: string; pageError?: string } = {}): Promise<RouteResult> {
   const { emailById, options } = await memberCandidates(keto, kratosAdmin);
   const members = (await pagedTuples(keto, { namespace: GROUP_NS, object: name, relation: MEMBERS })).map((t) => memberView(t, emailById));
   const subject = groupSubject(name);
   const [direct, effective] = await Promise.all([heldPermissions(keto, subject), effectivePermissions(keto, subject, ctx.declaredPermissions)]);
-  const permissions = buildPermissionPicker({
-    action: `${detailHref(name)}/permissions`,
-    declared: ctx.declaredPermissions,
-    direct,
-    effective, // a group nested in another group inherits its permissions too
-    readOnly: !can(ctx, permissionName("groups", "write")),
-    t: ctx.t,
-    transitive: true, // members inherit, so a change here lands at their next re-mint, not at once
-  });
-  return { data: { chrome: ctx.chrome, model: buildGroupDetailModel({ canWrite: !permissions.readOnly, candidates: options, csrfToken: ctx.chrome.csrfToken, group: { name }, members, permissions, t: ctx.t }) }, view: "group-detail" };
-});
+  const permissions: PermissionPicker = {
+    ...buildPermissionPicker({
+      action: `${detailHref(name)}/permissions`,
+      declared: ctx.declaredPermissions,
+      direct,
+      effective, // a group nested in another group inherits its permissions too
+      readOnly: !can(ctx, permissionName("groups", "write")),
+      t: ctx.t,
+      transitive: true, // members inherit, so a change here lands at their next re-mint, not at once
+    }),
+    ...(say.error ? { error: say.error } : {}),
+    ...(say.notice ? { notice: say.notice } : {}),
+  };
+  return { data: { chrome: ctx.chrome, model: buildGroupDetailModel({ canWrite: !permissions.readOnly, candidates: options, csrfToken: ctx.chrome.csrfToken, group: { name }, members, permissions, t: ctx.t, ...(say.pageError ? { error: say.pageError } : {}) }) }, view: "group-detail" };
+}
+
+// GET /admin/groups/:name — the detail + membership page.
+export const groupsDetail = withGroupName((deps, name) =>
+  groupDetailPage(deps, name, isSavedNotice(deps.ctx.url) ? { notice: deps.ctx.t("admin.grants.saved") } : {}));
 
 // POST /admin/groups/:name/permissions — the submitted checkboxes are the desired set. Members hold
 // a group's permissions transitively, so the change reaches them at their next login or re-mint —
 // the documented instant-revoke tradeoff for anything held through a group.
-export const groupsPermissions = withGroupName(async ({ ctx, keto, user }, name) => {
+export const groupsPermissions = withGroupName(async (deps, name) => {
+  const { ctx, keto, user } = deps;
   const form = (await guardedForm(ctx))!;
   const subject = groupSubject(name);
-  const diff = grantDiff(ctx.declaredPermissions, await heldPermissions(keto, subject), form.getAll(PERMISSIONS_FIELD));
-  await applyGrants(keto, subject, diff);
-  if (diff.grant.length > 0 || diff.revoke.length > 0) {
-    ctx.log.info("admin: group permissions changed", { actor: user.id, granted: diff.grant.join(","), group: name, revoked: diff.revoke.join(",") });
+  const held = await heldPermissions(keto, subject);
+  const diff = grantDiff(ctx.declaredPermissions, held, form.getAll(PERMISSIONS_FIELD));
+  if (isStale(form, ctx.declaredPermissions, held, diff)) return { ...(await groupDetailPage(deps, name, { error: ctx.t("admin.grants.stale") })), status: 409 };
+  const lost = diff.revoke.length > 0 && await isMember(keto, user.id, name) ? await lostToSelf(keto, user.id, diff.revoke) : [];
+  if (lost.length > 0) return refuseSelfLockout(deps, name, "save", lost);
+  const { applied, error } = await applyGrants(keto, subject, diff);
+  if (applied.grant.length > 0 || applied.revoke.length > 0) {
+    ctx.log.info("admin: group permissions changed", { actor: user.id, granted: applied.grant.join(","), group: name, revoked: applied.revoke.join(",") });
   }
-  return { redirect: detailHref(name) };
+  if (error) {
+    ctx.log.error("admin: group permissions only partly saved", { actor: user.id, error: String(error), group: name });
+    return partialSave(ctx, async () => ({ ...(await groupDetailPage(deps, name, { error: ctx.t("admin.grants.partial") })), status: 502 }));
+  }
+  return { redirect: `${detailHref(name)}?info-msg=${SAVED_NOTICE}` };
 });
 
 // POST /admin/groups/:name/members — add a member (skip an invalid member or a self-nest).
@@ -388,19 +432,24 @@ export const groupsAddMember = withGroupName(async ({ ctx, keto }, name) => {
 });
 
 // GET /admin/groups/:name/delete — the deliberate confirm step.
-export const groupsDeleteConfirm = withGroupName((deps, name) => {
+export const groupsDeleteConfirm = withGroupName(async (deps, name) => {
+  const lost = await lostOnDelete(deps, name);
+  if (lost.length > 0) return refuseSelfLockout(deps, name, "delete", lost);
   const base = detailHref(name);
   const tt = deps.ctx.t;
-  return Promise.resolve({ data: { chrome: deps.ctx.chrome, model: buildConfirmModel({
+  return { data: { chrome: deps.ctx.chrome, model: buildConfirmModel({
     breadcrumbs: [{ href: ADMIN_GROUPS_BASE, label: tt("admin.groups.title") }, { href: base, label: name }, { label: tt("common.delete") }],
     cancelHref: base, confirmAction: `${base}/delete`, confirmLabel: tt("admin.groups.delete"),
     message: tt("admin.groups.deleteMessage", { name }), title: tt("admin.groups.delete"),
-  }) }, view: "confirm" });
+  }) }, view: "confirm" };
 }, "write");
 
 // POST /admin/groups/:name/delete — remove every member tuple (the group ceases to exist).
-export const groupsDelete = withGroupName(async ({ ctx, keto, user }, name) => {
+export const groupsDelete = withGroupName(async (deps, name) => {
+  const { ctx, keto, user } = deps;
   await guardedForm(ctx); // CSRF-verify the POST
+  const lost = await lostOnDelete(deps, name);
+  if (lost.length > 0) return refuseSelfLockout(deps, name, "delete", lost);
   // Drop what the group *holds* before what it *contains*: a Keto set exists only through its
   // tuples, so leaving the grants behind would resurrect every permission the moment someone
   // re-created a group with the same name.
@@ -413,9 +462,15 @@ export const groupsDelete = withGroupName(async ({ ctx, keto, user }, name) => {
 });
 
 // POST /admin/groups/:name/members/delete — remove one member.
-export const groupsRemoveMember = withGroupName(async ({ ctx, keto }, name) => {
+export const groupsRemoveMember = withGroupName(async (deps, name) => {
+  const { ctx, keto, user } = deps;
   const form = (await guardedForm(ctx))!;
   const tuple = memberTuple(name, (form.get("member") ?? "").trim());
-  if (tuple) await keto.deleteTuple(tuple);
+  if (!tuple) return { redirect: detailHref(name) };
+  // Removing the actor, or a nested group they are in, can take them out of this group.
+  const removesSelf = tuple.subject_set ? await isMember(keto, user.id, tuple.subject_set.object) : tuple.subject_id === `user:${user.id}`;
+  const lost = removesSelf ? await lostOnLeaving(deps, name) : [];
+  if (lost.length > 0) return refuseSelfLockout(deps, name, "remove", lost);
+  await keto.deleteTuple(tuple);
   return { redirect: detailHref(name) };
 });

examples/plugins/admin/admin-shared.test.ts

@@ -1,6 +1,6 @@
 // Direct units for the admin plugin's shared nav + auth helpers. They're security-critical
 // (requirePermission/guardedForm gate every admin write) and reused across all three screens, so pin the
-// contract here in isolation; the HTTP routing/gate/CSRF is exercised end-to-end in src/http/app.test.ts.
+// contract here in isolation; the HTTP routing/gate/CSRF is exercised end-to-end in src/http/app-admin.test.ts.
 // Import only from the @plainpages/plugin-api barrel — the same contract boundary the plugin code uses.
 import assert from "node:assert/strict";
 import type { IncomingMessage, ServerResponse } from "node:http";

examples/plugins/admin/admin-shared.ts

@@ -83,6 +83,16 @@ export function unavailable(ctx: RequestContext, what: string): RouteResult {
   return { data: { chrome: ctx.chrome, message: ctx.t("admin.unavailable.message", { what }), title: ctx.t("admin.unavailable.title") }, status: 503, view: "notice" };
 }
 
+// The page a partial permission save reports on reads Keto again. If that read fails too, the report
+// stands alone on the notice page, so the admin still hears that part of the save landed.
+export async function partialSave(ctx: RequestContext, render: () => Promise<RouteResult>): Promise<RouteResult> {
+  try {
+    return await render();
+  } catch {
+    return { data: { chrome: ctx.chrome, message: ctx.t("admin.grants.partial"), title: ctx.t("admin.unavailable.title") }, status: 502, view: "notice" };
+  }
+}
+
 // Model for the shared destructive-confirm page (views/confirm.ejs). The view reads the shell fields
 // (brand/csrf/theme/user/nav) from ctx.chrome; this carries only the page body + title/breadcrumbs.
 export function buildConfirmModel(opts: {

examples/plugins/admin/admin-users.test.ts

@@ -1,5 +1,5 @@
 // Users admin screen (example plugin): the pure view-model + Kratos-payload builders. The HTTP
-// routing/gate/CSRF + live Kratos calls are exercised over HTTP in src/http/app.test.ts.
+// routing/gate/CSRF + live Kratos calls are exercised over HTTP in src/http/app-admin.test.ts.
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import type { Identity } from "@plainpages/plugin-api";
@@ -60,6 +60,14 @@ test("buildUsersListModel filters by search + status, sorts, and paginates", ()
 
   // Edit link points at the per-identity route.
   assert.match(all.table.rows[0]!.actions![0]!.href!, new RegExp(`/admin/users/${people[0]!.id}$`));
+  assert.deepEqual([all.table.rows[0]!.actions![0]!.icon, all.table.rows[0]!.actions![0]!.label], ["i-edit", "Edit"]);
+});
+
+// The detail page of a `users:read` holder is read-only, so the row action must not promise an edit.
+test("buildUsersListModel: a read-only holder's row action says View, with the same target", () => {
+  const people: Identity[] = [{ id: "u1", traits: { email: "a@x.io" } }];
+  const action = buildUsersListModel({ canWrite: false, identities: people, url: "http://x/admin/users" }).table.rows[0]!.actions![0]!;
+  assert.deepEqual([action.icon, action.label, action.href], ["i-eye", "View", "/admin/users/u1"]);
 });
 
 test("buildUserFormModel: create mode has an editable email + password, no edit actions", () => {
@@ -92,6 +100,19 @@ test("buildUserFormModel: edit mode prefills, locks email, and exposes state/del
   assert.equal(buildUserFormModel({ identity: identity(4, { state: "inactive" }) }).edit!.nextLabel, "Reactivate");
 });
 
+test("buildUserFormModel: the title and breadcrumb say New, Edit, or View for a users:read holder", () => {
+  const cases: [Parameters<typeof buildUserFormModel>[0], string, string][] = [
+    [{}, "New user", "New"],
+    [{ identity: identity(3) }, "Edit user", "Edit"],
+    [{ canWrite: false, identity: identity(3) }, "View user", "View"],
+  ];
+  for (const [opts, title, crumb] of cases) {
+    const m = buildUserFormModel(opts);
+    assert.equal(m.title, title);
+    assert.deepEqual(m.breadcrumbs, [{ href: "/admin/users", label: "Users" }, { label: crumb }]);
+  }
+});
+
 test("createIdentityPayload: schema/state/traits, name only when given, password only when set", () => {
   assert.deepEqual(createIdentityPayload({ email: "a@b.c", first: "Ada", last: "Lovelace", password: "" }), {
     schema_id: "default",

examples/plugins/admin/admin-users.ts

@@ -4,8 +4,8 @@
 // a shared `withUser` gate.
 
 import { can, type Identity, type KetoClient, type KratosAdmin, KratosError, paginate, parseListQuery, type RecoveryCode, type RequestContext, type RouteHandler, type RouteResult, type Translate, type User } from "@plainpages/plugin-api";
-import { applyGrants, buildPermissionPicker, effectivePermissions, grantDiff, heldPermissions, type PermissionPicker, PERMISSIONS_FIELD, userSubject } from "./admin-grants.ts";
-import { ADMIN_EN, type AdminAction, ADMIN_USERS_BASE, buildConfirmModel, guardedForm, notFound, permissionName, requirePermission, unavailable } from "./admin-shared.ts";
+import { applyGrants, buildPermissionPicker, effectivePermissions, grantDiff, heldPermissions, isSavedNotice, isStale, type PermissionPicker, PERMISSIONS_FIELD, SAVED_NOTICE, userSubject } from "./admin-grants.ts";
+import { ADMIN_EN, type AdminAction, ADMIN_USERS_BASE, buildConfirmModel, guardedForm, notFound, partialSave, permissionName, requirePermission, unavailable } from "./admin-shared.ts";
 
 const SCHEMA_ID = "default"; // matches kratos.yml identity.default_schema_id
 const DEFAULT_PAGE_SIZE = 25;
@@ -138,12 +138,12 @@ export function buildUsersListModel(opts: {
     canWrite: opts.canWrite !== false,
     filterBar: listFilterBar(state, all.length, t),
     pagination: listPagination(state, page, t),
-    table: listTable(rows, state, sort, t),
+    table: listTable(rows, state, sort, t, opts.canWrite !== false),
     title: t("admin.users.title"),
   };
 }
 
-function listTable(rows: UserView[], state: ListState, sort: { dir: "asc" | "desc"; field: string } | null, t: Translate) {
+function listTable(rows: UserView[], state: ListState, sort: { dir: "asc" | "desc"; field: string } | null, t: Translate, canWrite: boolean) {
   return {
     actions: true,
     caption: t("admin.users.title"),
@@ -153,7 +153,7 @@ function listTable(rows: UserView[], state: ListState, sort: { dir: "asc" | "des
       return { href: listHref(state, { page: 1, sort: next }), label: t(c.label), sort: dir, sortable: true };
     }),
     rows: rows.map((u) => ({
-      actions: [{ href: `${ADMIN_USERS_BASE}/${encodeURIComponent(u.id)}`, icon: "i-edit", label: t("common.edit") }],
+      actions: [{ href: `${ADMIN_USERS_BASE}/${encodeURIComponent(u.id)}`, icon: canWrite ? "i-edit" : "i-eye", label: t(canWrite ? "common.edit" : "admin.users.view") }],
       cells: [
         { user: { initials: u.initials, name: u.name } },
         u.email,
@@ -243,8 +243,9 @@ export function buildUserFormModel(opts: {
   if (!editing) fields.push({ autocomplete: "new-password", hint: t("admin.users.field.passwordHint"), icon: "i-lock", id: "password", label: t("admin.users.field.password"), name: "password", optional: true, type: "password" });
 
   const canWrite = opts.canWrite !== false;
+  const mode = !editing ? "new" : canWrite ? "edit" : "view";
   return {
-    breadcrumbs: [{ href: ADMIN_USERS_BASE, label: t("admin.users.title") }, { label: editing ? t("common.edit") : t("common.new") }],
+    breadcrumbs: [{ href: ADMIN_USERS_BASE, label: t("admin.users.title") }, { label: t({ edit: "common.edit", new: "common.new", view: "admin.users.view" }[mode]) }],
     canWrite, // the view drops every write affordance when false; the host already 403s the POSTs
     edit: editing ? {
       deleteAction: `${idPath}/delete`,
@@ -258,7 +259,7 @@ export function buildUserFormModel(opts: {
     form: { action: idPath, cancelHref: ADMIN_USERS_BASE, csrfToken: opts.csrfToken ?? "", fields, submitLabel: editing ? t("admin.users.save") : t("admin.users.create") },
     permissions: editing ? opts.permissions : undefined,
     recovery: opts.recovery,
-    title: editing ? t("admin.users.edit") : t("admin.users.new"),
+    title: t({ edit: "admin.users.edit", new: "admin.users.new", view: "admin.users.viewTitle" }[mode]),
   };
 }
 
@@ -329,7 +330,7 @@ export const usersNewForm = withUser(({ ctx }) => Promise.resolve(formResult(ctx
 
 // GET /admin/users/:id — the edit form, prefilled.
 export const usersEditForm = withTarget(async (deps, identity, id) => {
-  const permissions = await userPermissionPicker(deps, id);
+  const permissions = await userPermissionPicker(deps, id, undefined, isSavedNotice(deps.ctx.url) ? deps.ctx.t("admin.grants.saved") : undefined);
   return formResult(deps.ctx, { canWrite: canWriteUsers(deps.ctx), identity, ...(permissions ? { permissions } : {}) });
 });
 
@@ -338,7 +339,7 @@ const canWriteUsers = (ctx: RequestContext): boolean => can(ctx, permissionName(
 // The checkbox list of declared permissions: ticked where this user holds one, and disabled where
 // the grant comes from a group (real, but removed on that group). Undefined when Keto isn't wired —
 // the rest of the edit page still works.
-async function userPermissionPicker(deps: UsersDeps, id: string, error?: string): Promise<PermissionPicker | undefined> {
+async function userPermissionPicker(deps: UsersDeps, id: string, error?: string, notice?: string): Promise<PermissionPicker | undefined> {
   if (!deps.keto) return undefined;
   const subject = userSubject(id);
   const [direct, effective] = await Promise.all([
@@ -355,6 +356,7 @@ async function userPermissionPicker(deps: UsersDeps, id: string, error?: string)
       t: deps.ctx.t,
     }),
     ...(error ? { error } : {}),
+    ...(notice ? { notice } : {}),
   };
 }
 
@@ -366,21 +368,30 @@ export const usersPermissions = withTarget(async (deps, identity, id) => {
   const form = (await guardedForm(ctx))!;
   if (!keto) return unavailable(ctx, ctx.t("admin.capability.keto"));
   const subject = userSubject(id);
-  const diff = grantDiff(ctx.declaredPermissions, await heldPermissions(keto, subject), form.getAll(PERMISSIONS_FIELD));
+  const held = await heldPermissions(keto, subject);
+  const refuse = async (error: string, status: number): Promise<RouteResult> => {
+    const permissions = await userPermissionPicker(deps, id, error);
+    return { ...formResult(ctx, { canWrite: canWriteUsers(ctx), identity, ...(permissions ? { permissions } : {}) }), status };
+  };
+  const diff = grantDiff(ctx.declaredPermissions, held, form.getAll(PERMISSIONS_FIELD));
+  if (isStale(form, ctx.declaredPermissions, held, diff)) return refuse(ctx.t("admin.grants.stale"), 409);
   // Self-lockout guard, matching the self-deactivate/self-delete ones: revoking your own grants can
   // remove the last `users:write` on the deployment, and the instant-revoke hook lands it on the very
   // next request — leaving a `curl` against Keto as the only way back in.
   if (id === user.id && diff.revoke.length > 0) {
     ctx.log.warn("admin: refused a self-revoke of permissions", { actor: user.id, refused: diff.revoke.join(",") });
-    const permissions = await userPermissionPicker(deps, id, ctx.t("admin.grants.selfRevoke"));
-    return { ...formResult(ctx, { canWrite: canWriteUsers(ctx), identity, ...(permissions ? { permissions } : {}) }), status: 400 };
+    return refuse(ctx.t("admin.grants.selfRevoke"), 400);
   }
-  await applyGrants(keto, subject, diff);
-  if (diff.grant.length > 0 || diff.revoke.length > 0) {
+  const { applied, error } = await applyGrants(keto, subject, diff);
+  if (applied.grant.length > 0 || applied.revoke.length > 0) {
     revoke?.(id);
-    ctx.log.info("admin: user permissions changed", { actor: user.id, granted: diff.grant.join(","), revoked: diff.revoke.join(","), target: id });
+    ctx.log.info("admin: user permissions changed", { actor: user.id, granted: applied.grant.join(","), revoked: applied.revoke.join(","), target: id });
   }
-  return { redirect: `${ADMIN_USERS_BASE}/${encodeURIComponent(id)}` };
+  if (error) {
+    ctx.log.error("admin: user permissions only partly saved", { actor: user.id, error: String(error), target: id });
+    return partialSave(ctx, () => refuse(ctx.t("admin.grants.partial"), 502));
+  }
+  return { redirect: `${ADMIN_USERS_BASE}/${encodeURIComponent(id)}?info-msg=${SAVED_NOTICE}` };
 });
 
 // POST /admin/users/:id — save edits; a Kratos 4xx re-renders the form (400).

examples/plugins/admin/i18n/en-US.ts

@@ -53,9 +53,12 @@ const messages = {
   "admin.grants.inherited": "Greyed-out permissions come from a group. Change them on that group.",
   "admin.grants.legend": "Permissions",
   "admin.grants.none": "No installed plugin declares a permission, so there is nothing to grant.",
+  "admin.grants.partial": "Saving stopped part-way because the permission service failed, so only some changes were applied. Check the permissions and make any remaining changes again.",
   "admin.grants.pending": "Members get this at their next sign-in (up to 10 minutes).",
   "admin.grants.save": "Save permissions",
+  "admin.grants.saved": "Permissions saved.",
   "admin.grants.selfRevoke": "You can't revoke your own permissions — ask another administrator, so you can't lock yourself out.",
+  "admin.grants.stale": "These permissions changed while you had the page open, so nothing was saved. The list now shows the current state. Review it and save again.",
 
   "admin.groups.actions": "Group actions",
   "admin.groups.addMember": "Add a member",
@@ -65,6 +68,7 @@ const messages = {
   "admin.groups.create": "Create group",
   "admin.groups.delete": "Delete group",
   "admin.groups.deleteMessage": "Delete group {{name}}? This can't be undone.",
+  "admin.groups.error.selfLockout": "This change would lock you out of {{permissions}}, which you hold through this group. Ask another administrator to make it.",
   "admin.groups.field.name": "Group name",
   "admin.groups.field.nameHint": "Lowercase letters, digits, dashes and underscores.",
   "admin.groups.filter": "Filter groups",
@@ -149,6 +153,8 @@ const messages = {
   "admin.users.status.inactive": "Inactive",
   "admin.users.status.label": "Status",
   "admin.users.title": "Users",
+  "admin.users.view": "View",
+  "admin.users.viewTitle": "View user",
 };
 
 export type AdminMessages = typeof messages;

examples/plugins/admin/i18n/sv-SE.ts

@@ -53,9 +53,12 @@ const messages: AdminMessages = {
   "admin.grants.inherited": "Gråmarkerade behörigheter kommer från en grupp. Ändra dem på gruppen.",
   "admin.grants.legend": "Behörigheter",
   "admin.grants.none": "Ingen installerad plugin deklarerar någon behörighet, så det finns inget att tilldela.",
+  "admin.grants.partial": "Sparandet avbröts halvvägs eftersom behörighetstjänsten gav fel, så bara en del av ändringarna genomfördes. Kontrollera behörigheterna och gör de återstående ändringarna igen.",
   "admin.grants.pending": "Medlemmar får detta vid nästa inloggning (upp till 10 minuter).",
   "admin.grants.save": "Spara behörigheter",
+  "admin.grants.saved": "Behörigheterna är sparade.",
   "admin.grants.selfRevoke": "Du kan inte återkalla dina egna behörigheter — be en annan administratör, så att du inte låser ute dig själv.",
+  "admin.grants.stale": "Behörigheterna ändrades medan du hade sidan öppen, så ingenting sparades. Listan visar nu aktuellt läge. Granska den och spara igen.",
 
   "admin.groups.actions": "Gruppåtgärder",
   "admin.groups.addMember": "Lägg till en medlem",
@@ -65,6 +68,7 @@ const messages: AdminMessages = {
   "admin.groups.create": "Skapa grupp",
   "admin.groups.delete": "Radera grupp",
   "admin.groups.deleteMessage": "Ta bort gruppen {{name}}? Det går inte att ångra.",
+  "admin.groups.error.selfLockout": "Ändringen skulle låsa ute dig från {{permissions}}, som du har genom den här gruppen. Be en annan administratör att göra den.",
   "admin.groups.field.name": "Gruppnamn",
   "admin.groups.field.nameHint": "Små bokstäver, siffror, bindestreck och understreck.",
   "admin.groups.filter": "Filtrera grupper",
@@ -149,6 +153,8 @@ const messages: AdminMessages = {
   "admin.users.status.inactive": "Inaktiv",
   "admin.users.status.label": "Status",
   "admin.users.title": "Användare",
+  "admin.users.view": "Visa",
+  "admin.users.viewTitle": "Visa användare",
 };
 
 export default messages;

examples/plugins/admin/views/partials/permission-picker.ejs

@@ -7,13 +7,16 @@
   there) and every row when `readOnly` (the viewer holds :read but not :write). Neither can be diffed
   into an accidental revoke, because grantDiff compares against the direct grants only.
 
-  Locals: csrfToken, permissions ({ action, choices, empty, error, field, hint, inheritedNote, legend, pending, readOnly, submit }).
+  Locals: csrfToken, permissions ({ action, baseline, choices, empty, error, field, hint, inheritedNote, legend, notice, pending, readOnly, submit }).
 %>
   <section class="form-card" aria-labelledby="permissions-h">
     <h2 class="card-title" id="permissions-h"><%= permissions.legend %></h2>
 <% if (permissions.error) { -%>
 <%- include("partials/alert", { text: permissions.error, tone: "neg" }) %>
 <% } -%>
+<% if (permissions.notice) { -%>
+<%- include("partials/alert", { text: permissions.notice, tone: "pos" }) %>
+<% } -%>
 <% if (permissions.empty) { -%>
     <p class="cell-muted"><%= permissions.empty %></p>
 <% } else { -%>
@@ -26,8 +29,10 @@
 <% }) -%>
     </fieldset>
 <% } else { -%>
-    <form method="post" action="<%= localeHref(permissions.action) %>">
+    <%# The fragment brings the card, and the notice in it, into view on a long page. %>
+    <form method="post" action="<%= localeHref(permissions.action + '#permissions-h') %>">
       <input type="hidden" name="_csrf" value="<%= csrfToken %>">
+      <input type="hidden" name="baseline" value="<%= permissions.baseline %>">
       <fieldset class="check-group">
         <legend class="sr-only"><%= permissions.legend %></legend>
 <% permissions.choices.forEach((c) => { -%>

examples/plugins/scheduling/public/scheduling.css

@@ -4,3 +4,9 @@
 .scheduling-page .table-wrap {
   margin-top: var(--space-3, 0.75rem);
 }
+/* Inset what sits directly in the pane by --pad-x, as the filter bar, table and pager already are. */
+.scheduling-page > p,
+.scheduling-page > .alert,
+.scheduling-page > .btn {
+  margin-inline: var(--pad-x);
+}

examples/plugins/scheduling/views/shifts.ejs

@@ -2,7 +2,7 @@
   Scheduling · Shifts list (reference plugin). The handler fetched the rows from the upstream
   service; this view renders them with the core building blocks inside the native app shell
   (ctx.chrome). `include()` reaches the core partials (shell, nav-tree, filter-bar, data-table,
-  alert) — see docs/plugin-contract.md. Zero-JS: search round-trips the URL.
+  alert) — see the README. Zero-JS: search round-trips the URL.
   Data: chrome, title, breadcrumbs, count, filterBar, table, canWrite, newHref, error?
 %><%
   const navHtml = include("partials/nav-tree", { nodes: chrome.nav });

package-lock.json

@@ -8,12 +8,13 @@
       "dependencies": {
         "@larvit/log": "2.3.0",
         "ejs": "6.0.1",
-        "lucide-static": "1.61.0",
+        "lucide-static": "1.64.0",
         "postgres": "3.4.9"
       },
       "devDependencies": {
         "@types/ejs": "3.1.5",
         "@types/node": "24.19.2",
+        "acorn": "8.19.0",
         "typescript": "7.0.2"
       },
       "engines": {
@@ -386,6 +387,19 @@
         "node": ">=16.20.0"
       }
     },
+    "node_modules/acorn": {
+      "version": "8.19.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.19.0.tgz",
+      "integrity": "sha512-oJlA3XiRm7Cyk6qFD2Jn8ak9B7jSy0qy00ADO3+8dpT0LSjFihQYv4C02LFCSYJV3Q37xYwwRy5m+IpIiUzqWw==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
     "node_modules/ejs": {
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/ejs/-/ejs-6.0.1.tgz",
@@ -399,9 +413,9 @@
       }
     },
     "node_modules/lucide-static": {
-      "version": "1.61.0",
-      "resolved": "https://registry.npmjs.org/lucide-static/-/lucide-static-1.61.0.tgz",
-      "integrity": "sha512-yLAiQB3MWUJEstsEDAwenSA3m7vr1tdLvgnC16Q/XMxRRma0DWwMs8M2bWlvgShrIs1m2mWMJ+0AiahqQO4GrA==",
+      "version": "1.64.0",
+      "resolved": "https://registry.npmjs.org/lucide-static/-/lucide-static-1.64.0.tgz",
+      "integrity": "sha512-UxWmMteOXbKHI5E4f2qVtxCAAsI9gsInYK1lNw0nrOA0w4FkJeOVZ+UOV6aGA2377FZe3qyiFYq3lqjBKZ6OuA==",
       "license": "ISC"
     },
     "node_modules/postgres": {

package.json

@@ -18,12 +18,13 @@
   "dependencies": {
     "@larvit/log": "2.3.0",
     "ejs": "6.0.1",
-    "lucide-static": "1.61.0",
+    "lucide-static": "1.64.0",
     "postgres": "3.4.9"
   },
   "devDependencies": {
     "@types/ejs": "3.1.5",
     "@types/node": "24.19.2",
+    "acorn": "8.19.0",
     "typescript": "7.0.2"
   }
 }

public/css/auth.css

@@ -1,11 +1,3 @@
-/* =============================================================
-   Auth flow — login / register / forgot password
-   Built on the shared tokens in styles.css. Pure HTML/CSS:
-   - screens switch via :target (no JS)
-   - SSO is a config section toggled by a class/checkbox; providers
-     are a <ul> you extend by adding one <li class="sso-item">.
-   ============================================================= */
-
 .auth-stage {
   min-height: 100dvh;
   display: grid; place-items: center;
@@ -34,13 +26,6 @@
 .landing-actions { display: flex; flex-wrap: wrap; gap: 10px; justify-content: center; margin-top: 4px; }
 .landing-actions .btn { height: 40px; padding: 0 20px; font-size: var(--fz); }
 
-/* ---- screen switching via :target (login is the default) ---- */
-.auth-view { display: none; }
-#login { display: block; }
-#register:target, #forgot:target { display: block; }
-body:has(#register:target) #login,
-body:has(#forgot:target) #login { display: none; }
-
 /* card */
 .auth-card {
   background: var(--surface);
@@ -123,8 +108,6 @@ body:has(#forgot:target) #login { display: none; }
 
 .field-hint { font-size: var(--fz-xs); color: var(--text-faint); }
 
-.remember { margin-top: 2px; }
-
 /* full-width primary button (extends .btn / .btn-primary from styles.css) */
 .btn-block { width: 100%; justify-content: center; height: 40px; font-size: var(--fz); }
 
@@ -138,74 +121,6 @@ body:has(#forgot:target) #login { display: none; }
 .auth-aside a { color: var(--accent); }
 .auth-aside a:hover { text-decoration: underline; }
 
-/* legal footnote */
-.auth-foot { margin: 0; text-align: center; font-size: var(--fz-xs); color: var(--text-faint); }
-.auth-foot a { color: var(--text-muted); text-decoration: underline; }
-
-/* =============================================================
-   Template preview controls (delete this block + its markup for
-   production). Drives theme + SSO on/off with zero JS.
-   ============================================================= */
-.tpl-controls {
-  position: fixed; bottom: 16px; left: 50%; transform: translateX(-50%);
-  z-index: 50;
-  display: flex; align-items: center; gap: 12px;
-  padding: 6px 8px 6px 14px;
-  background: var(--surface); border: 1px solid var(--border);
-  border-radius: 99px; box-shadow: 0 6px 22px rgba(0,0,0,.12);
-}
-.tpl-label { font-size: var(--fz-xs); color: var(--text-faint);
-  text-transform: uppercase; letter-spacing: .05em; font-weight: 600; }
-.tpl-sep { width: 1px; height: 20px; background: var(--border); }
-.tpl-controls .theme-switch { width: 156px; }
-
-/* on/off switch */
-.tpl-toggle { display: inline-flex; align-items: center; gap: 8px;
-  font-size: var(--fz-sm); color: var(--text-muted); cursor: pointer; }
-.tpl-toggle input { position: absolute; opacity: 0; width: 0; height: 0; }
-.tpl-track { width: 32px; height: 18px; border-radius: 99px;
-  background: var(--border-2); position: relative; transition: background .15s ease; }
-.tpl-track::after { content: ""; position: absolute; top: 2px; left: 2px;
-  width: 14px; height: 14px; border-radius: 50%; background: #fff;
-  box-shadow: 0 1px 2px rgba(0,0,0,.3); transition: transform .15s ease; }
-.tpl-toggle:has(input:checked) .tpl-track { background: var(--accent); }
-.tpl-toggle:has(input:checked) .tpl-track::after { transform: translateX(14px); }
-.tpl-toggle:has(input:focus-visible) .tpl-track {
-  outline: 2px solid var(--focus); outline-offset: 2px; }
-
-@media (max-width: 520px) {
-  .tpl-label { display: none; }
-  .tpl-controls { gap: 10px; padding: 6px 10px; }
-}
-
-/* =============================================================
-   Forgot-password feedback (Post/Redirect/Get, no JS).
-   The form POSTs to its own URL; on the redirect-GET the server
-   re-renders #forgot with a state class so the matching alert shows:
-     <section id="forgot" class="auth-view state-sent"> … </section>
-   (state-sent | state-error). No extra view is added.
-   The preview radios below demonstrate the same states live.
-   ============================================================= */
-.forgot-alert { display: none; }
-#forgot.state-sent  .forgot-alert.is-sent,
-body:has(#fstate-sent:checked)  #forgot .forgot-alert.is-sent  { display: flex; }
-#forgot.state-error .forgot-alert.is-error,
-body:has(#fstate-error:checked) #forgot .forgot-alert.is-error { display: flex; }
-
-/* the Forgot-state control only appears while the forgot view is open */
-.tpl-forgot { display: none; }
-body:has(#forgot:target) .tpl-forgot { display: flex; }
-.tpl-controls .segmented { padding: 1px; }
-.tpl-controls .segmented label { padding: 3px 8px; }
-
-/* =============================================================
-   Field-level errors (e.g. "email already used"), server-driven.
-   The server re-renders the field's form with a state class and
-   adds aria-invalid="true" to the input:
-     <section id="register" class="auth-view state-email-taken"> … </section>
-   Reusable: drop a <p class="field-error"> under any field and gate
-   it on whatever state your server sets.
-   ============================================================= */
 .field-error {
   display: none; align-items: center; gap: 6px; margin: 0;
   font-size: var(--fz-xs); color: var(--neg);
@@ -213,36 +128,3 @@ body:has(#forgot:target) .tpl-forgot { display: flex; }
 .field.has-error .field-error { display: flex; }  /* server-rendered field shows its own error */
 .field-error > .ico { flex: 0 0 auto; color: var(--neg); }
 .field-error a { color: var(--neg); font-weight: 600; text-decoration: underline; }
-
-/* register form-level error banner (pairs with field-level errors) */
-.register-alert { display: none; }
-
-/* --- state A: email already taken — field-level error only --- */
-#register.state-email-taken .err-email,
-body:has(#rstate-taken:checked) #register .err-email { display: flex; }
-#register.state-email-taken #reg-email,
-body:has(#rstate-taken:checked) #register #reg-email { border-color: var(--neg); }
-
-/* --- state B: multiple errors — banner + several field errors together --- */
-#register.state-invalid .register-alert,
-body:has(#rstate-combined:checked) #register .register-alert { display: flex; }
-#register.state-invalid .err-email,
-#register.state-invalid .err-password,
-body:has(#rstate-combined:checked) #register .err-email,
-body:has(#rstate-combined:checked) #register .err-password { display: flex; }
-#register.state-invalid #reg-email,
-#register.state-invalid #reg-password,
-body:has(#rstate-combined:checked) #register #reg-email,
-body:has(#rstate-combined:checked) #register #reg-password { border-color: var(--neg); }
-
-/* red focus ring on any invalid register input */
-#register.state-email-taken #reg-email:focus,
-#register.state-invalid #reg-email:focus,
-#register.state-invalid #reg-password:focus,
-body:has(#rstate-taken:checked) #register #reg-email:focus,
-body:has(#rstate-combined:checked) #register #reg-email:focus,
-body:has(#rstate-combined:checked) #register #reg-password:focus { box-shadow: 0 0 0 2px var(--neg-bg); }
-
-/* the Register-state control only appears while the register view is open */
-.tpl-register { display: none; }
-body:has(#register:target) .tpl-register { display: flex; }

public/css/styles.css

@@ -2,8 +2,6 @@
    App Shell Template — pure HTML/CSS, no JavaScript
    -------------------------------------------------------------
    Architecture
-   - Design tokens via light-dark() so theme follows system by
-     default and can be forced Light / Dark via radio + :has().
    - Everything is a reusable "block": .nav-item, .filter,
      .chip, .badge, .btn, .menu, .table — combine freely.
    ============================================================= */
@@ -11,43 +9,48 @@
 /* ---------- 1. TOKENS ----------------------------------------
    Two raw palettes (--l-* light, --d-* dark) are defined once.
    A small mapping (--bg: var(--l-bg) ...) picks the active set.
-   Theme resolution (no JS):
+   Theme resolution (no JS); all three rules below need :has():
      • default + @media(dark)  → follows the OS  (Auto)
      • html:has(#theme-light)  → force light
      • html:has(#theme-dark)   → force dark
+   Engines without :has() (Chromium below 105, Firefox below 121,
+   Safari below 15.4) ignore all three and stay light; see the @supports not
+   selector(:has(a)) block further down.
    We avoid light-dark()/color-scheme for app colors because their
-   resolution is unreliable across engines; :has() variable swaps
-   are rock-solid. color-scheme is still set as a hint for native
-   widgets (date picker, scrollbars, selects).
+   resolution is unreliable across engines. color-scheme is still
+   set as a hint for native widgets (date picker, scrollbars,
+   selects).
 ------------------------------------------------------------- */
 :root {
+  /* Hex, never oklch: below Chromium 111 `var(--accent)` is invalid at computed-value time and the
+     primary button loses its background. A fallback declaration cannot catch that. */
   /* ---- raw LIGHT palette ---- */
   --l-bg:#f3f3f4; --l-surface:#ffffff; --l-surface-2:#f6f6f7; --l-surface-3:#fbfbfc;
   --l-border:#e5e5e8; --l-border-2:#d6d6da;
   --l-text:#18181b; --l-text-muted:#6b6b73; --l-text-faint:#9a9aa2;
-  --l-accent:oklch(0.52 0.12 256); --l-accent-bg:oklch(0.96 0.03 256);
-  --l-accent-bd:oklch(0.82 0.07 256); --l-focus:oklch(0.52 0.14 256);
-  --l-pos:oklch(0.54 0.13 150); --l-pos-bg:oklch(0.95 0.03 150); --l-pos-bd:oklch(0.83 0.07 150);
-  --l-neg:oklch(0.55 0.18 25);  --l-neg-bg:oklch(0.96 0.03 25);  --l-neg-bd:oklch(0.85 0.08 25);
-  --l-warn:oklch(0.55 0.12 75); --l-warn-bg:oklch(0.96 0.04 85); --l-warn-bd:oklch(0.84 0.08 85);
-  --l-info:oklch(0.54 0.12 245);--l-info-bg:oklch(0.96 0.03 245);--l-info-bd:oklch(0.83 0.07 245);
+  --l-accent:#3669ac; --l-accent-bg:#e5f3ff;
+  --l-accent-bd:#a7c7f2; --l-focus:#2a68b7; --l-on-accent:#ffffff;
+  --l-pos:#1f7a3d; --l-pos-bg:#e1f5e4; --l-pos-bd:#a8d5b0;
+  --l-neg:#c53637;  --l-neg-bg:#ffebe8;  --l-neg-bd:#febab4;
+  --l-warn:#8f5d00; --l-warn-bg:#fef0d4; --l-warn-bd:#e3c78e;
+  --l-info:#1d6aa5;--l-info-bg:#e2f5ff;--l-info-bd:#a2cdf2;
 
   /* ---- raw DARK palette ---- */
   --d-bg:#0d0d0f; --d-surface:#161619; --d-surface-2:#1d1d22; --d-surface-3:#1a1a1e;
   --d-border:#2a2a31; --d-border-2:#3a3a43;
   --d-text:#ededf0; --d-text-muted:#9b9ba6; --d-text-faint:#6a6a74;
-  --d-accent:oklch(0.70 0.12 256); --d-accent-bg:oklch(0.32 0.06 256);
-  --d-accent-bd:oklch(0.48 0.08 256); --d-focus:oklch(0.74 0.13 256);
-  --d-pos:oklch(0.74 0.14 150); --d-pos-bg:oklch(0.30 0.05 150); --d-pos-bd:oklch(0.45 0.07 150);
-  --d-neg:oklch(0.74 0.16 25);  --d-neg-bg:oklch(0.30 0.07 25);  --d-neg-bd:oklch(0.47 0.10 25);
-  --d-warn:oklch(0.80 0.13 85); --d-warn-bg:oklch(0.31 0.05 80); --d-warn-bd:oklch(0.48 0.07 80);
-  --d-info:oklch(0.74 0.12 245);--d-info-bg:oklch(0.31 0.06 245);--d-info-bd:oklch(0.47 0.08 245);
+  --d-accent:#6ba0e8; --d-accent-bg:#1d3351;
+  --d-accent-bd:#3f5f8a; --d-focus:#72adfb; --d-on-accent:#0d0d0f;
+  --d-pos:#62c37a; --d-pos-bg:#1a3520; --d-pos-bd:#376040;
+  --d-neg:#ff7e76;  --d-neg-bg:#4b1d1b;  --d-neg-bd:#8a423d;
+  --d-warn:#e4b750; --d-warn-bg:#3e2d10; --d-warn-bd:#72592c;
+  --d-info:#65b2f1;--d-info-bg:#12334c;--d-info-bd:#305f85;
 
   /* ---- active mapping: default = LIGHT ---- */
   --bg:var(--l-bg); --surface:var(--l-surface); --surface-2:var(--l-surface-2); --surface-3:var(--l-surface-3);
   --border:var(--l-border); --border-2:var(--l-border-2);
   --text:var(--l-text); --text-muted:var(--l-text-muted); --text-faint:var(--l-text-faint);
-  --accent:var(--l-accent); --accent-bg:var(--l-accent-bg); --accent-bd:var(--l-accent-bd); --focus:var(--l-focus);
+  --accent:var(--l-accent); --accent-bg:var(--l-accent-bg); --accent-bd:var(--l-accent-bd); --focus:var(--l-focus); --on-accent:var(--l-on-accent);
   --pos:var(--l-pos); --pos-bg:var(--l-pos-bg); --pos-bd:var(--l-pos-bd);
   --neg:var(--l-neg); --neg-bg:var(--l-neg-bg); --neg-bd:var(--l-neg-bd);
   --warn:var(--l-warn); --warn-bg:var(--l-warn-bg); --warn-bd:var(--l-warn-bd);
@@ -58,7 +61,7 @@
   --radius: 5px;
   --nav-w: 264px;
   --row-h: 34px;
-  --pad-x: 12px;
+  --pad-x: 12px;   /* side padding of the content pane's bars and form page, and of every table cell, so their text lines up */
   --fz: 13px;
   --fz-sm: 12px;
   --fz-xs: 11px;
@@ -74,7 +77,7 @@
     --bg:var(--d-bg); --surface:var(--d-surface); --surface-2:var(--d-surface-2); --surface-3:var(--d-surface-3);
     --border:var(--d-border); --border-2:var(--d-border-2);
     --text:var(--d-text); --text-muted:var(--d-text-muted); --text-faint:var(--d-text-faint);
-    --accent:var(--d-accent); --accent-bg:var(--d-accent-bg); --accent-bd:var(--d-accent-bd); --focus:var(--d-focus);
+    --accent:var(--d-accent); --accent-bg:var(--d-accent-bg); --accent-bd:var(--d-accent-bd); --focus:var(--d-focus); --on-accent:var(--d-on-accent);
     --pos:var(--d-pos); --pos-bg:var(--d-pos-bg); --pos-bd:var(--d-pos-bd);
     --neg:var(--d-neg); --neg-bg:var(--d-neg-bg); --neg-bd:var(--d-neg-bd);
     --warn:var(--d-warn); --warn-bg:var(--d-warn-bg); --warn-bd:var(--d-warn-bd);
@@ -88,7 +91,7 @@ html:has(#theme-dark:checked) {
   --bg:var(--d-bg); --surface:var(--d-surface); --surface-2:var(--d-surface-2); --surface-3:var(--d-surface-3);
   --border:var(--d-border); --border-2:var(--d-border-2);
   --text:var(--d-text); --text-muted:var(--d-text-muted); --text-faint:var(--d-text-faint);
-  --accent:var(--d-accent); --accent-bg:var(--d-accent-bg); --accent-bd:var(--d-accent-bd); --focus:var(--d-focus);
+  --accent:var(--d-accent); --accent-bg:var(--d-accent-bg); --accent-bd:var(--d-accent-bd); --focus:var(--d-focus); --on-accent:var(--d-on-accent);
   --pos:var(--d-pos); --pos-bg:var(--d-pos-bg); --pos-bd:var(--d-pos-bd);
   --neg:var(--d-neg); --neg-bg:var(--d-neg-bg); --neg-bd:var(--d-neg-bd);
   --warn:var(--d-warn); --warn-bg:var(--d-warn-bg); --warn-bd:var(--d-warn-bd);
@@ -101,7 +104,7 @@ html:has(#theme-light:checked) {
   --bg:var(--l-bg); --surface:var(--l-surface); --surface-2:var(--l-surface-2); --surface-3:var(--l-surface-3);
   --border:var(--l-border); --border-2:var(--l-border-2);
   --text:var(--l-text); --text-muted:var(--l-text-muted); --text-faint:var(--l-text-faint);
-  --accent:var(--l-accent); --accent-bg:var(--l-accent-bg); --accent-bd:var(--l-accent-bd); --focus:var(--l-focus);
+  --accent:var(--l-accent); --accent-bg:var(--l-accent-bg); --accent-bd:var(--l-accent-bd); --focus:var(--l-focus); --on-accent:var(--l-on-accent);
   --pos:var(--l-pos); --pos-bg:var(--l-pos-bg); --pos-bd:var(--l-pos-bd);
   --neg:var(--l-neg); --neg-bg:var(--l-neg-bg); --neg-bd:var(--l-neg-bd);
   --warn:var(--l-warn); --warn-bg:var(--l-warn-bg); --warn-bd:var(--l-warn-bd);
@@ -169,9 +172,9 @@ summary { list-style: none; cursor: pointer; }
 .brand-mark {
   width: 22px; height: 22px; border-radius: 5px; flex: 0 0 auto;
   background: var(--accent);
-  display: grid; place-items: center; color: #fff;
+  display: grid; place-items: center; color: var(--on-accent);
 }
-.brand-mark .ico { stroke: #fff; }
+.brand-mark .ico { stroke: var(--on-accent); }
 .brand-logo { width: 22px; height: 22px; border-radius: 5px; flex: 0 0 auto; object-fit: contain; }
 .brand-name { font-weight: 650; letter-spacing: -.01em; }
 .brand-sub { color: var(--text-faint); font-size: var(--fz-xs); margin-left: auto; }
@@ -189,9 +192,10 @@ summary { list-style: none; cursor: pointer; }
      • CLICKABLE = label is <a href>      → navigates on click.
        STATIC    = label is <span>        → not a navigation target.
    So "header" and "clickable" are independent: any combination works.
-   Children sit in a sibling <ul class="nav-children">, revealed by
-   :has() on THIS row's own <details open> (scoped with > so a node
-   only ever controls its own subtree — infinite depth, no JS).
+   Children sit in a sibling <ul class="nav-children">. Where :has() works, a
+   branch is folded unless THIS row's own <details open> (scoped with > so a node
+   only ever controls its own subtree — infinite depth, no JS). Without :has()
+   every branch stays open, since nothing could reopen one.
    ============================================================ */
 .nav-row { display: flex; align-items: center; gap: 2px; }
 
@@ -235,8 +239,10 @@ span.nav-self { cursor: default; }                 /* static / non-clickable */
 .nav-self[aria-current="page"] .ico { color: var(--accent); }
 
 /* children + infinite indentation with a guide line per level */
-.nav-node > .nav-children { display: none; }
-.nav-node:has(> .nav-row > .nav-disc[open]) > .nav-children { display: block; }
+@supports selector(:has(a)) {
+  .nav-node > .nav-children { display: none; }
+  .nav-node:has(> .nav-row > .nav-disc[open]) > .nav-children { display: block; }
+}
 .nav-children { padding-left: 22px; position: relative; }
 .nav-children::before {
   content: ""; position: absolute; left: 10px; top: 2px; bottom: 2px;
@@ -279,6 +285,13 @@ span.nav-self { cursor: default; }                 /* static / non-clickable */
   outline: 2px solid var(--focus); outline-offset: 1px;
 }
 
+/* Without :has() every branch is open and every theme rule is inert: neither control does anything.
+   After the base rules, since @supports adds no specificity. */
+@supports not selector(:has(a)) {
+  .nav-disc { visibility: hidden; }  /* keeps its width, so the labels stay aligned */
+  .theme-switch { display: none; }
+}
+
 .footer-actions { display: flex; align-items: center; gap: 4px; }
 .profile {
   display: flex; align-items: center; gap: 9px; flex: 1 1 auto;
@@ -309,7 +322,7 @@ span.nav-self { cursor: default; }                 /* static / non-clickable */
 }
 .btn:hover { background: var(--surface-2); }
 .btn-primary { background: var(--accent); border-color: var(--accent);
-  color: #fff; font-weight: 550; }
+  color: var(--on-accent); font-weight: 550; }
 .btn-primary:hover { filter: brightness(1.06); }
 .btn-ghost { background: transparent; border-color: transparent; }
 .btn-ghost:hover { background: var(--surface-2); }
@@ -336,7 +349,7 @@ span.nav-self { cursor: default; }                 /* static / non-clickable */
 .topbar {
   flex: 0 0 auto; height: 48px;
   display: flex; align-items: center; gap: 12px;
-  padding: 0 16px; border-bottom: 1px solid var(--border);
+  padding: 0 var(--pad-x); border-bottom: 1px solid var(--border);
   background: var(--surface);
 }
 .hamburger { display: none; }   /* shown only on narrow */
@@ -352,7 +365,7 @@ span.nav-self { cursor: default; }                 /* static / non-clickable */
 .filters {
   flex: 0 0 auto; background: var(--surface);
   border-bottom: 1px solid var(--border);
-  padding: 10px 16px;
+  padding: 10px var(--pad-x);
   display: flex; flex-direction: column; gap: 9px;
 }
 .filter-row {
@@ -584,7 +597,7 @@ table.table {
 .col-num { text-align: right; }
 .cell-strong { font-weight: 550; }
 .cell-muted { color: var(--text-muted); }
-.table-empty { text-align: center; color: var(--text-muted); padding: 28px 12px; }
+.table-empty { text-align: center; color: var(--text-muted); padding: 28px var(--pad-x); }
 .cell-mono { font-variant-numeric: tabular-nums;
   font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: var(--fz-sm); }
 
@@ -648,7 +661,7 @@ th[aria-sort="descending"] .sort-ico { transform: rotate(180deg); }
 .pager {
   flex: 0 0 auto;
   display: flex; align-items: center; gap: 12px;
-  padding: 8px 16px; border-top: 1px solid var(--border);
+  padding: 8px var(--pad-x); border-top: 1px solid var(--border);
   background: var(--surface); font-size: var(--fz-sm); color: var(--text-muted);
 }
 .pager .spacer { flex: 1 1 auto; }
@@ -663,29 +676,34 @@ th[aria-sort="descending"] .sort-ico { transform: rotate(180deg); }
 }
 .page-btn:hover { background: var(--surface-2); color: var(--text); }
 .page-btn[aria-current="page"] { background: var(--accent); border-color: var(--accent);
-  color: #fff; font-weight: 600; }
+  color: var(--on-accent); font-weight: 600; }
 .page-btn:disabled { opacity: .4; cursor: not-allowed; }
 
 /* ---------- 11. RESPONSIVE / HAMBURGER --------------------- */
 .scrim { display: none; }
 
 @media (max-width: 860px) {
-  .app { grid-template-columns: minmax(0, 1fr); }
-  .sidebar {
-    position: fixed; inset: 0 auto 0 0; width: min(86vw, var(--nav-w));
-    z-index: 60; transform: translateX(-100%);
-    box-shadow: 2px 0 24px rgba(0,0,0,.18);
-  }
-  .content { grid-column: 1; }
-  .hamburger { display: inline-flex; }
-
-  /* checkbox-driven open state */
-  body:has(#nav-toggle:checked) .sidebar { transform: translateX(0); }
-  body:has(#nav-toggle:checked) .scrim {
-    display: block; position: fixed; inset: 0; z-index: 50;
-    background: rgba(0,0,0,.42);
-  }
+  .app { grid-template-columns: minmax(0, 1fr); grid-template-rows: auto 1fr; }
+  .content { grid-column: 1; grid-row: 2; }
   .search { min-width: 150px; flex: 1 1 auto; }
+
+  /* Off-canvas only where :has() works: without it nothing can read #nav-toggle, so the sidebar
+     stays in the flow above the content and the hamburger stays hidden. */
+  @supports selector(:has(a)) {
+    .sidebar {
+      position: fixed; inset: 0 auto 0 0; width: min(86vw, var(--nav-w));
+      z-index: 60; transform: translateX(-100%);
+      box-shadow: 2px 0 24px rgba(0,0,0,.18);
+    }
+    .hamburger { display: inline-flex; }
+
+    /* checkbox-driven open state */
+    body:has(#nav-toggle:checked) .sidebar { transform: translateX(0); }
+    body:has(#nav-toggle:checked) .scrim {
+      display: block; position: fixed; inset: 0; z-index: 50;
+      background: rgba(0,0,0,.42);
+    }
+  }
 }
 @media (max-width: 560px) {
   .crumbs, .page-sub { display: none; }
@@ -696,7 +714,7 @@ th[aria-sort="descending"] .sort-ico { transform: rotate(180deg); }
 #nav-toggle { position: fixed; top: 0; left: 0; opacity: 0; pointer-events: none; }
 
 /* admin forms: create/edit user, account actions */
-.form-page { padding: 16px; display: flex; flex-direction: column; gap: 14px; max-width: 560px; }
+.form-page { padding: 16px var(--pad-x); display: flex; flex-direction: column; gap: 14px; max-width: 560px; }
 .form-card {
   display: flex; flex-direction: column; gap: 14px;
   padding: 18px; background: var(--surface);

release-tooling/dockerhub-overview.md.tmpl

@@ -131,7 +131,7 @@ services:
 
   # Catches Kratos' recovery/verification emails — UI on http://localhost:8025
   mailpit:
-    image: axllent/mailpit:v1.32.0
+    image: axllent/mailpit:v1.33.0
     ports:
       - "8025:8025"
     restart: unless-stopped
@@ -163,7 +163,7 @@ Every behaviour is an explicit env toggle read at boot — no `NODE_ENV`. The co
 | --- | --- | --- |
 | `ADMIN_EMAIL` / `ADMIN_PASSWORD` | `admin@plainpages.local` / `admin` | the seeded first admin (bootstrap service) |
 | `APP_URL` | unset | canonical public URL; off-host visitors are redirected to it |
-| `CACHE_TEMPLATES` | `false` | cache compiled templates (`true` in prod) |
+| `CACHE_TEMPLATES` | `false` | cache compiled templates and `/public/` asset versions (`true` in prod) |
 | `CSRF_SECRET` | dev throwaway | signs the CSRF token — set a real one in prod |
 | `KRATOS_*` / `KETO_*` / `HYDRA_*` URLs | compose defaults | the Ory sidecar endpoints |
 | `LOG_FORMAT` / `LOG_LEVEL` | `text` / `info` | `json` for structured prod logs |

src/auth/routes.test.ts

@@ -1,6 +1,6 @@
 // buildAuthRoutes registers only the endpoints the wired clients support — a missing client
 // means the path isn't in the table at all (the host then 404s). The endpoints' behaviour is
-// covered end-to-end through the app in src/http/app.test.ts.
+// covered end-to-end through the app in src/http/app-auth.test.ts.
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { AUTH_FLOWS } from "./flow-view.ts";

src/auth/routes.ts

@@ -38,11 +38,55 @@ const FORBIDDEN: RouteResult = { status: 403, view: "403" };
 const selfOrigin = (ctx: RequestContext, secure: boolean): string =>
   `${secure ? "https" : "http"}://${ctx.req.headers.host ?? "127.0.0.1:3000"}`;
 
+// Where Kratos lands the browser after sign-in, or undefined for its default. A host-relative
+// return_to (the gate's deep link) or a chosen language goes through /auth/complete, which mints the
+// session JWT first and carries the language across Kratos; any other target (the OAuth2 login
+// challenge) is passed as-is, since Kratos allow-lists it.
+function flowReturnTo(ctx: RequestContext, secureCookies: boolean): string | undefined {
+  const raw = ctx.url.searchParams.get("return_to");
+  const local = localPath(raw);
+  const chosen = chosenLocale(ctx);
+  if (raw && !local) return raw; // beside a chosen language too: the target wins, the language is lost
+  if (!local && !chosen) return undefined;
+  const complete = new URL(`${selfOrigin(ctx, secureCookies)}/auth/complete`);
+  if (local) complete.searchParams.set("return_to", ctx.localeHref(local));
+  if (chosen) complete.searchParams.set("locale", chosen);
+  return complete.toString();
+}
+
+// What a failed Kratos call returns instead of the flow; rethrows what is genuinely unexpected.
+function flowFailure(err: unknown, ctx: RequestContext, flowType: FlowType): RouteResult {
+  const pathname = ctx.url.pathname;
+  // Expired/unknown flow → restart by re-initialising (drop the stale ?flow=).
+  if (err instanceof KratosError && [403, 404, 410].includes(err.status)) return { redirect: pathname };
+  // No Kratos session on a page that needs one. /settings is public, since recovery lands there with
+  // a Kratos session but no app JWT, so the gate never sends an anonymous visitor to sign in.
+  // Not for /login itself, which would redirect to itself.
+  if (err instanceof KratosError && err.status === 401 && flowType !== "login") {
+    return { redirect: `/login?return_to=${encodeURIComponent(pathname)}` };
+  }
+  // Already authenticated at Kratos but no app JWT yet (e.g. straight after registration, whose
+  // `session` hook signs the user in but routes to verification, not /auth/complete — so ctx.user
+  // is null and the "already signed in" short-circuit can't fire). Initialising a login/
+  // registration flow then returns Kratos 400 `session_already_available`. Recover by completing
+  // login (mint the JWT from the live session), honouring return_to — never a 500.
+  if (err instanceof KratosError && err.status === 400 && err.body.includes("session_already_available")) {
+    const local = localPath(ctx.url.searchParams.get("return_to"));
+    return { redirect: local ? `/auth/complete?return_to=${encodeURIComponent(local)}` : "/auth/complete" };
+  }
+  // Ory unreachable (Kratos 5xx / connection refused / timeout): "Ory down ⇒ no logins" is
+  // documented, so render an honest 503 rather than the catch-all "error on our end" 500.
+  if (!(err instanceof KratosError) || err.status >= 500) {
+    ctx.log.warn("auth flow failed (Ory unreachable?)", { error: String(err), path: pathname });
+    return { status: 503, view: "503" };
+  }
+  throw err; // any other Kratos 4xx → the catch-all (genuinely unexpected)
+}
+
 // Themed Kratos self-service page (one route per AUTH_FLOWS entry: login/registration/recovery/
 // verification/settings).
 function flowPage(kratos: KratosPublic, flowType: FlowType, secureCookies: boolean): BuiltinRoute["handler"] {
   return async (ctx: RequestContext, csrf: RequestCsrf): Promise<RouteResult> => {
-    const pathname = ctx.url.pathname;
     // Already signed in? Re-authenticating / re-registering is pointless — send them to the app
     // dashboard. (/settings, /recovery, /verification stay reachable — a signed-in user can use those.)
     if (ctx.user && (flowType === "login" || flowType === "registration")) return { redirect: "/dashboard" };
@@ -54,49 +98,14 @@ function flowPage(kratos: KratosPublic, flowType: FlowType, secureCookies: boole
     try {
       if (!flowId) {
         // No flow yet: init one server-side, relay Kratos' CSRF cookie, bounce to ?flow=<id>.
-        // A `return_to` is baked into the flow so Kratos lands there after login instead of the
-        // default completion route. A first-party deep link (host-relative, from the gate's
-        // return_to) is wrapped through /auth/complete so the session JWT is minted before the
-        // user reaches the page; an absolute target (the OAuth2 login challenge) is passed
-        // as-is — Kratos allow-lists it. localPath rejects an off-origin "//evil.com".
-        const raw = ctx.url.searchParams.get("return_to");
-        const local = localPath(raw);
-        const chosen = chosenLocale(ctx);
-        let returnTo: string | undefined;
-        if (local || chosen) {
-          // The flow's return target is the host's, not Kratos' — so the language the visitor picked
-          // on the sign-in page survives the round-trip through Kratos and lands on the page after
-          // it. Without this the most-travelled path in the product (pick Swedish → sign in) drops
-          // straight back to Accept-Language.
-          const complete = new URL(`${selfOrigin(ctx, secureCookies)}/auth/complete`);
-          if (local) complete.searchParams.set("return_to", ctx.localeHref(local));
-          if (chosen) complete.searchParams.set("locale", chosen);
-          returnTo = complete.toString();
-        } else if (raw) returnTo = raw;
+        const returnTo = flowReturnTo(ctx, secureCookies);
         const { flow: initiated, setCookie } = await kratos.initBrowserFlow(flowType, { ...(cookie ? { cookie } : {}), ...(returnTo ? { returnTo } : {}) });
         if (setCookie.length) ctx.res.appendHeader("set-cookie", setCookie);
-        return { redirect: `${pathname}?flow=${initiated.id}` };
+        return { redirect: `${ctx.url.pathname}?flow=${initiated.id}` };
       }
       flow = await kratos.getFlow(flowType, flowId, cookie ? { cookie } : {});
     } catch (err) {
-      // Expired/unknown flow → restart by re-initialising (drop the stale ?flow=).
-      if (err instanceof KratosError && [403, 404, 410].includes(err.status)) return { redirect: pathname };
-      // Already authenticated at Kratos but no app JWT yet (e.g. straight after registration, whose
-      // `session` hook signs the user in but routes to verification, not /auth/complete — so ctx.user
-      // is null and the "already signed in" short-circuit above can't fire). Initialising a login/
-      // registration flow then returns Kratos 400 `session_already_available`. Recover by completing
-      // login (mint the JWT from the live session), honouring return_to — never a 500.
-      if (err instanceof KratosError && err.status === 400 && err.body.includes("session_already_available")) {
-        const local = localPath(ctx.url.searchParams.get("return_to"));
-        return { redirect: local ? `/auth/complete?return_to=${encodeURIComponent(local)}` : "/auth/complete" };
-      }
-      // Ory unreachable (Kratos 5xx / connection refused / timeout): "Ory down ⇒ no logins" is
-      // documented, so render an honest 503 rather than the catch-all "error on our end" 500.
-      if (!(err instanceof KratosError) || err.status >= 500) {
-        ctx.log.warn("auth flow failed (Ory unreachable?)", { error: String(err), path: pathname });
-        return { status: 503, view: "503" };
-      }
-      throw err; // any other Kratos 4xx → the catch-all (genuinely unexpected)
+      return flowFailure(err, ctx, flowType);
     }
     // Rendered inside the unified app shell, so set a fresh CSRF cookie when minted — the
     // shell's Sign-out form (shown on /settings, where the user is signed in) needs the token.

src/ci-gate.test.ts

@@ -29,14 +29,19 @@ test("the commit-hash image is pushed even when the gate no-ops", () => {
 	assert.doesNotMatch(step("docker push"), /^\s*if:/m);
 });
 
-test("every E2E suite the gate runs writes its artifacts as the invoking user", () => {
+test("every E2E runner container the gate starts runs as the invoking user", () => {
 	// The documented hand-run commands carry the same flag (src/compose.test.ts).
 	const runs = gate.split("\n").filter((l) => /docker compose .*\brun\b.*\be2e\b/.test(l));
-	assert.equal(runs.length, 2, "the suite helper and the devstack run");
+	assert.equal(runs.length, 3, "the e2e-tests typecheck, the suite helper and the devstack run");
 	for (const line of runs)
 		assert.match(line, /--user "\$\(id -u\):\$\(id -g\)"/, `runs as the caller: ${line.trim()}`);
 });
 
+test("the gate typechecks e2e-tests in the runner image, where @playwright/test resolves", () => {
+	assert.match(gate, /docker compose .*\brun\b.*--no-deps\b.*\be2e\b npm run typecheck/);
+	assert.match(read("e2e-tests/package.json"), /"typecheck": "tsc --noEmit"/);
+});
+
 test("only *.md counts as docs; a dirty tree and a rename both count as changed", () => {
 	assert.ok(gate.includes("\\.md$"), "the non-docs match is a *.md suffix test");
 	assert.match(gate, /git status --porcelain --no-renames/, "uncommitted code and a staged rename can never be skipped over");

src/compose.test.ts

@@ -129,7 +129,7 @@ test("the E2E runner writes its artifacts as the invoking user, never as root",
   // filter would otherwise leave that command silently unguarded.
   const documented = [read("README.md"), ...composeFiles("e2e-tests/").map(read)]
     .join("\n").split("\n").filter((l) => /docker compose .*\brun\b.*\be2e\b/.test(l));
-  assert.equal(documented.length, 6, "5 compose headers + 1 README block");
+  assert.equal(documented.length, 7, "5 compose headers + 2 README lines");
   for (const l of documented)
     assert.match(l, /--user "\$\(id -u\):\$\(id -g\)"/, `passes the uid: ${l.trim()}`);
   // An absent mount source is daemon-created as root, and then that uid can't write it at all.

src/function-limits.test.ts

@@ -0,0 +1,157 @@
+// The limits and the counting are ESLint's defaults: `max-lines-per-function` (blank lines and
+// comments count, an IIFE is not held to it) and `complexity`. Not ESLint itself: parsing TypeScript
+// takes typescript-eslint, which needs the compiler API TypeScript 7 no longer ships. So acorn parses
+// what Node's own type stripping leaves, which is the code Node runs.
+import assert from "node:assert/strict";
+import { globSync, readFileSync } from "node:fs";
+import { stripTypeScriptTypes } from "node:module";
+import { test } from "node:test";
+import { parse } from "acorn";
+
+const LIMITS = { lines: 50, complexity: 20 };
+
+// Each function over a limit, at its measurement. A ceiling follows its function down, and a metric
+// leaves the entry once it fits, so a function that shrank can't grow back.
+const grandfathered: Record<string, { lines?: number; complexity?: number }> = {
+  "src/http/app.ts createApp": { lines: 318, complexity: 28 },
+  "src/http/app.ts createApp > handleRequest": { lines: 167, complexity: 43 },
+  "src/auth/flow-view.ts buildFlowView": { complexity: 24 },
+  "src/auth/hydra-admin.ts createHydraAdmin": { lines: 87 },
+  "src/auth/kratos-admin.ts createKratosAdmin": { lines: 68 },
+  "src/auth/kratos-public.ts createKratosPublic": { lines: 60 },
+  "src/plugin-host/discovery.ts discoverPlugins": { lines: 74, complexity: 22 },
+  "src/plugin-host/discovery.ts shapeError": { complexity: 23 },
+  "src/config.ts loadConfig": { lines: 52 },
+  "release-tooling/dockerhub-overview.ts main": { lines: 57 },
+  "examples/plugins/admin/admin-users.ts buildUserFormModel": { complexity: 21 },
+};
+
+interface AstNode {
+  type: string;
+  loc: { start: { line: number }; end: { line: number } };
+  [key: string]: unknown;
+}
+
+interface Measured {
+  name: string;
+  lines: number;
+  complexity: number;
+}
+
+const isNode = (value: unknown): value is AstNode =>
+  typeof value === "object" && value !== null && typeof (value as { type?: unknown }).type === "string";
+
+const FUNCTIONS = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
+const BRANCHES = new Set([
+  "IfStatement", "ConditionalExpression", "LogicalExpression", "ForStatement", "ForInStatement",
+  "ForOfStatement", "WhileStatement", "DoWhileStatement", "CatchClause", "AssignmentPattern",
+]);
+
+function branches(node: AstNode): number {
+  if (BRANCHES.has(node.type)) return 1;
+  if (node.type === "SwitchCase") return node.test ? 1 : 0;
+  if (node.type === "AssignmentExpression") return ["&&=", "||=", "??="].includes(String(node.operator)) ? 1 : 0;
+  if (node.type === "MemberExpression" || node.type === "CallExpression") return node.optional === true ? 1 : 0;
+  return 0;
+}
+
+function nameOf(fn: AstNode, parent: AstNode | undefined): string {
+  let id = fn.id;
+  if (!id && parent?.type === "VariableDeclarator") id = parent.id;
+  if (!id && (parent?.type === "Property" || parent?.type === "MethodDefinition")) id = parent.key;
+  return isNode(id) && typeof id.name === "string" ? id.name : "anonymous";
+}
+
+// A function is named by the path of names from the outermost one, e.g. `createApp > handleRequest`,
+// so an entry above doesn't depend on line numbers.
+function measure(source: string): Measured[] {
+  const found: Measured[] = [];
+  const visit = (node: AstNode, parent: AstNode | undefined, enclosing: Measured | undefined): void => {
+    let current = enclosing;
+    if (FUNCTIONS.has(node.type)) {
+      const name = nameOf(node, parent);
+      const iife = parent?.type === "CallExpression" && parent.callee === node;
+      const lines = iife ? 0 : node.loc.end.line - node.loc.start.line + 1;
+      current = { name: enclosing ? `${enclosing.name} > ${name}` : name, lines, complexity: 1 };
+      found.push(current);
+    } else if (current) {
+      current.complexity += branches(node);
+    }
+    for (const value of Object.values(node)) {
+      for (const child of [value].flat()) if (isNode(child)) visit(child, node, current);
+    }
+  };
+  const program: unknown = parse(stripTypeScriptTypes(source), { ecmaVersion: "latest", sourceType: "module", locations: true });
+  assert.ok(isNode(program));
+  visit(program, undefined, undefined);
+  return found;
+}
+
+const root = new URL("..", import.meta.url);
+// The drop-in mounts hold an operator's code, not this repo's. Tests are left out: each is a flat
+// script, and a `describe` block wraps many of them.
+const files = globSync("**/*.ts", {
+  cwd: root,
+  exclude: ["**/node_modules/**", "plugins/**", "config/**", "locales/**", "**/*.d.ts", "**/*.test.ts", "**/*.spec.ts"],
+});
+// A list, not a map: two unnamed siblings share a key, and each must be checked.
+const measured = files.flatMap((file) =>
+  measure(readFileSync(new URL(file, root), "utf8")).map((m) => ({ ...m, key: `${file} ${m.name}` })),
+);
+const METRICS = ["lines", "complexity"] as const;
+
+test("measure counts lines and complexity as ESLint does", () => {
+  const source = [
+    "function outer(a = 1): void {",
+    "  if (a && b?.c) {}",
+    "  for (const x of y) {}",
+    "  for (const k in y) {}",
+    "  for (;;) break;",
+    "  while (a) a--;",
+    "  do {} while (a);",
+    "  try {} catch {}",
+    "  switch (a) { case 1: break; default: }",
+    "  a ||= 2; a &&= 3; a ??= 4;",
+    "  b?.();",
+    "  y.map(() => {});",
+    "  const inner = () => (a ? 1 : 2);",
+    "  const o = { prop() {}, key: function () {} };",
+    "  (function () { if (a) {} })();",
+    "}",
+    "class K { method() {} }",
+  ].join("\n");
+  assert.deepEqual(measure(source), [
+    { name: "outer", lines: 16, complexity: 16 },
+    { name: "outer > anonymous", lines: 1, complexity: 1 },
+    { name: "outer > inner", lines: 1, complexity: 2 },
+    { name: "outer > prop", lines: 1, complexity: 1 },
+    { name: "outer > key", lines: 1, complexity: 1 },
+    { name: "outer > anonymous", lines: 0, complexity: 2 },
+    { name: "method", lines: 1, complexity: 1 },
+  ]);
+});
+
+test(`every function fits ${LIMITS.lines} lines and complexity ${LIMITS.complexity}, or its grandfathered ceiling`, () => {
+  assert.ok(files.length > 50, "found too few files: is the glob broken?");
+  const over = measured.flatMap((m) =>
+    METRICS.filter((metric) => m[metric] > (grandfathered[m.key]?.[metric] ?? LIMITS[metric])).map(
+      (metric) => `${m.key}: ${metric} ${m[metric]}`,
+    ),
+  );
+  assert.deepEqual(over, [], "split the function; never raise a ceiling");
+});
+
+test("every grandfathered ceiling equals its function's measurement, which is over the limit", () => {
+  const stale = Object.entries(grandfathered).flatMap(([key, ceiling]) => {
+    const found = measured.filter((m) => m.key === key);
+    if (found.length === 0) return [`${key}: no such function; rename the entry if it moved, else delete it`];
+    return METRICS.flatMap((metric) => {
+      const allowed = ceiling[metric];
+      if (allowed === undefined) return [];
+      const now = Math.max(...found.map((m) => m[metric]));
+      if (now <= LIMITS[metric]) return [`${key}: ${metric} ${now} fits; delete it`];
+      return now < allowed ? [`${key}: ${metric} ${now}; lower the ceiling to it`] : [];
+    });
+  });
+  assert.deepEqual(stale, []);
+});

src/http/app-admin.test.ts

@@ -0,0 +1,609 @@
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import type { AddressInfo } from "node:net";
+import { dirname, join } from "node:path";
+import { test, type TestContext } from "node:test";
+import { fileURLToPath } from "node:url";
+import { createApp, type AppOptions } from "./app.ts";
+import { createDenylist } from "../auth/denylist.ts";
+import { CSRF_COOKIE, issueCsrfToken } from "../auth/csrf.ts";
+import { staticJwks } from "../auth/jwks.ts";
+import type { OAuth2Client } from "../auth/hydra-admin.ts";
+import type { RelationTuple } from "../auth/keto-client.ts";
+import type { Identity } from "../auth/kratos-admin.ts";
+import { SESSION_COOKIE } from "../auth/login.ts";
+import type { Plugin } from "../plugin-host/plugin.ts";
+import adminManifest from "../../examples/plugins/admin/plugin.ts";
+import { createI18n } from "../i18n/runtime.ts";
+import { loadI18n } from "../i18n/load.ts";
+import { ecJwk, fakeKeto, matchesTuple, mintJwt, stubAdmin, stubHydra } from "./app-harness.ts";
+
+// The HTTP-level admin tests mount the example plugin via createApp — stub Ory clients on
+// ctx.system, views from examples/plugins — exactly as an operator would after copying it in.
+const examplesPluginsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "examples", "plugins");
+const adminPlugin: Plugin = { ...adminManifest, id: "admin" };
+
+// Shared harness for the admin-screen HTTP tests: an app on a random port with an admin JWT +
+// CSRF cookie. get(path, permissions)/post(path, body) carry them; `token` is the matching CSRF field.
+const ADMIN_CSRF = "admin-secret";
+async function adminHarness(t: TestContext, opts: AppOptions = {}, sub = "admin1") {
+  // Mount the plugin's catalogs the way server.ts does, so its screens render words, not keys.
+  const i18n = createI18n(await loadI18n({ pluginIds: [adminPlugin.id], pluginsDir: examplesPluginsDir }));
+  const app = createApp({ csrfSecret: ADMIN_CSRF, i18n, jwks: staticJwks([ecJwk]), pluginsDir: examplesPluginsDir, plugins: [adminPlugin], ...opts });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+  const token = issueCsrfToken(ADMIN_CSRF);
+  const nowSec = Math.floor(Date.now() / 1000);
+  const cookie = (permissions: string[]) => `${SESSION_COOKIE}=${mintJwt({ email: "admin@x", exp: nowSec + 600, permissions, sub })}; ${CSRF_COOKIE}=${token}`;
+  const get = (path: string, permissions: string[] = ADMIN_ALL) => fetch(url + path, { headers: { cookie: cookie(permissions) }, redirect: "manual" });
+  const post = (path: string, body: string) =>
+    fetch(url + path, { body, headers: { "content-type": "application/x-www-form-urlencoded", cookie: cookie(ADMIN_ALL) }, method: "POST", redirect: "manual" });
+  return { get, post, token, url };
+}
+// What the plugin itself declares — the harness holds every screen's read and write, so a screen
+// test exercises the screen rather than the gate. assertAdminGate covers the refusals.
+const ADMIN_ALL = (adminManifest.permissions ?? []).map((p) => p.name);
+// The permission form's concurrency token, read off the page the way a browser would post it back.
+const baselineOf = (html: string): string => /name="baseline" value="([0-9a-f]+)"/.exec(html)?.[1] ?? "";
+// Every admin route is gated: anonymous → /login, a signed-in non-admin → 403.
+async function assertAdminGate(url: string, get: (path: string, permissions?: string[]) => Promise<Response>, path: string) {
+  const anon = await fetch(url + path, { redirect: "manual" });
+  assert.equal(anon.status, 303);
+  assert.equal(anon.headers.get("location"), `/login?return_to=${encodeURIComponent(path)}`); // remembers the page
+  assert.equal((await get(path, [])).status, 403);
+}
+
+
+// Built-in Users admin screen: gate + every CRUD action over HTTP against a mock Kratos admin.
+test("admin Users screen: gate, list/filter, create, edit, deactivate, delete, recovery (CSRF-guarded)", async (t) => {
+  const mk = (email: string, over: Partial<Identity> = {}): Identity =>
+    ({ id: randomUUID(), schema_id: "default", state: "active", traits: { email, name: { first: "Ada", last: "Lovelace" } }, ...over });
+  const store: Identity[] = [mk("ada@example.com"), mk("babbage@example.com", { state: "inactive" }), mk("you@example.com", { id: "admin1" })];
+  let lastCreate: { traits?: unknown } | undefined;
+  const kratosAdmin = stubAdmin({
+    createIdentity: async (payload) => { lastCreate = payload as { traits?: unknown }; const created = mk("grace@example.com"); store.push(created); return created; },
+    createRecoveryCode: async (id) => ({ code: "123456", link: `http://kratos/self-service/recovery?code=123456&id=${id}` }),
+    deleteIdentity: async (id) => { const i = store.findIndex((x) => x.id === id); if (i >= 0) store.splice(i, 1); },
+    getIdentity: async (id) => store.find((x) => x.id === id) ?? null,
+    listIdentities: async () => ({ identities: store, nextPageToken: null }),
+    updateIdentity: async (id, payload) => { const it = store.find((x) => x.id === id)!; Object.assign(it, payload); return it; },
+  });
+  const denylist = createDenylist(); // a deactivate/delete should revoke the target's live tokens instantly
+  const { get, post, token, url } = await adminHarness(t, { denylist, kratosAdmin });
+
+  await assertAdminGate(url, get, "/admin/users");
+
+  // Nav: the admin plugin's section composes into the one global menu, and each screen is filtered
+  // by its own read permission — proving the drop-in nav fragment. A user holding only users:read
+  // sees Users and nothing else; holding none of the three, composeNav drops the emptied header.
+  assert.match(await (await get("/dashboard")).text(), /href="\/admin\/users"/);
+  const usersOnlyNav = await (await get("/dashboard", ["users:read"])).text();
+  assert.match(usersOnlyNav, /href="\/admin\/users"/);
+  assert.doesNotMatch(usersOnlyNav, /href="\/admin\/groups"/);
+  assert.doesNotMatch(await (await get("/dashboard", ["scheduling:read"])).text(), /href="\/admin\/users"/);
+
+  // The read/write split: users:read opens the list but is refused on every mutation, and the
+  // resources don't leak — a users holder is not a groups holder.
+  assert.equal((await get("/admin/users", ["users:read"])).status, 200);
+  assert.equal((await get("/admin/groups", ["users:read", "users:write"])).status, 403);
+  const readOnlyPost = await fetch(url + "/admin/users", {
+    body: `_csrf=${token}&email=nope@example.com`,
+    headers: { "content-type": "application/x-www-form-urlencoded", cookie: `${SESSION_COOKIE}=${mintJwt({ email: "r@x", exp: Math.floor(Date.now() / 1000) + 600, permissions: ["users:read"], sub: "reader1" })}; ${CSRF_COOKIE}=${token}` },
+    method: "POST",
+    redirect: "manual",
+  });
+  assert.equal(readOnlyPost.status, 403);
+  assert.equal(store.some((i) => i.traits?.email === "nope@example.com"), false);
+
+  // List: the admin sees the rows + the "add" link; the status filter narrows server-side.
+  const listHtml = await (await get("/admin/users")).text();
+  assert.match(listHtml, /ada@example\.com/);
+  assert.match(listHtml, /href="\/admin\/users\/new"/);
+  assert.doesNotMatch(await (await get("/admin/users?status=inactive")).text(), /ada@example\.com/);
+
+  // Create: the form renders; a valid post creates the identity and redirects to the list.
+  assert.match(await (await get("/admin/users/new")).text(), /Create user/);
+  const created = await post("/admin/users", `_csrf=${token}&email=grace%40example.com&first=Grace&last=Hopper&password=`);
+  assert.equal(created.status, 303);
+  assert.equal(created.headers.get("location"), "/admin/users");
+  assert.deepEqual(lastCreate?.traits, { email: "grace@example.com", name: { first: "Grace", last: "Hopper" } });
+
+  // A create with no CSRF token is refused and creates nothing.
+  const before = store.length;
+  assert.equal((await post("/admin/users", "email=x%40y.z")).status, 403);
+  assert.equal(store.length, before);
+
+  // CSRF also guards a POST to an *existing* target (the per-route :id handlers), not just the
+  // collection: a delete with no token is refused (403) and removes nothing.
+  assert.equal((await post(`/admin/users/${store[1]!.id}/delete`, "")).status, 403);
+  assert.ok(store.some((x) => x.id === store[1]!.id));
+
+  // Edit: email is read-only + prefilled; a post rewrites the name.
+  const target = store[0]!;
+  const editHtml = await (await get(`/admin/users/${target.id}`)).text();
+  assert.match(editHtml, /name="email"[^>]*readonly/);
+  assert.match(editHtml, /value="ada@example\.com"/);
+  const updated = await post(`/admin/users/${target.id}`, `_csrf=${token}&first=Ada&last=King`);
+  assert.equal(updated.status, 303);
+  assert.deepEqual((target.traits as { name: unknown }).name, { first: "Ada", last: "King" });
+
+  // Deactivate (state toggle): active → inactive, and the target's live tokens are revoked at once.
+  await post(`/admin/users/${target.id}/state`, `_csrf=${token}`);
+  assert.equal(target.state, "inactive");
+  assert.equal(denylist.isRevoked(target.id, 0), true);
+
+  // Recovery: renders the edit page (200) showing the generated code (code-based; no admin-host link).
+  const rec = await post(`/admin/users/${target.id}/recovery`, `_csrf=${token}`);
+  assert.equal(rec.status, 200);
+  const recHtml = await rec.text();
+  assert.match(recHtml, /Recovery code generated/);
+  assert.match(recHtml, /<code>123456<\/code>/);
+  assert.doesNotMatch(recHtml, /self-service\/recovery\?code=/); // the unreachable admin-API link is gone
+
+  // Delete needs a deliberate confirm step (zero-JS): GET renders the interstitial, POST performs it.
+  const confirm = await (await get(`/admin/users/${target.id}/delete`)).text();
+  assert.match(confirm, /Cancel/);
+  assert.match(confirm, new RegExp(`action="/admin/users/${target.id}/delete"`));
+  const del = await post(`/admin/users/${target.id}/delete`, `_csrf=${token}`);
+  assert.equal(del.status, 303);
+  assert.ok(!store.some((x) => x.id === target.id));
+
+  // Self-protection: an admin can't delete or deactivate their own account (JWT sub = admin1).
+  assert.equal((await post(`/admin/users/admin1/delete`, `_csrf=${token}`)).status, 400);
+  assert.ok(store.some((x) => x.id === "admin1"));
+  assert.equal((await post(`/admin/users/admin1/state`, `_csrf=${token}`)).status, 400);
+  assert.equal(store.find((x) => x.id === "admin1")!.state, "active");
+
+  // Unknown id → 404; malformed %-encoding → 404 (not a 500), matching groups/permissions/clients.
+  assert.equal((await get(`/admin/users/${randomUUID()}`)).status, 404);
+  assert.equal((await get("/admin/users/%ZZ")).status, 404);
+});
+
+// Built-in Groups admin screen: gate + list/create/membership/delete over HTTP against a
+// fakeKeto (tuples are the only state) and a stub Kratos admin (resolves member emails).
+test("admin Groups screen: gate, list, create, detail/membership, delete (CSRF-guarded)", async (t) => {
+  const ada = "01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b01";
+  const grace = "01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b02";
+  const identities: Identity[] = [
+    { id: ada, schema_id: "default", state: "active", traits: { email: "ada@example.com" } },
+    { id: grace, schema_id: "default", state: "active", traits: { email: "grace@example.com" } },
+  ];
+  const tuples: RelationTuple[] = [{ namespace: "Group", object: "eng", relation: "members", subject_id: `user:${ada}` }];
+  const keto = fakeKeto(tuples);
+  const kratosAdmin = stubAdmin({ listIdentities: async () => ({ identities, nextPageToken: null }) });
+  const { get, post, token, url } = await adminHarness(t, { keto, kratosAdmin });
+
+  await assertAdminGate(url, get, "/admin/groups");
+
+  // List: the existing group shows + the "add" link.
+  const listHtml = await (await get("/admin/groups")).text();
+  assert.match(listHtml, /href="\/admin\/groups\/eng"/);
+  assert.match(listHtml, /href="\/admin\/groups\/new"/);
+
+  // Create: the form renders; a valid post writes the first-member tuple and redirects to the detail.
+  assert.match(await (await get("/admin/groups/new")).text(), /Create group/);
+  const created = await post("/admin/groups", `_csrf=${token}&name=design&member=user:${grace}`);
+  assert.equal(created.status, 303);
+  assert.equal(created.headers.get("location"), "/admin/groups/design");
+  assert.ok(tuples.some((tp) => tp.object === "design" && tp.subject_id === `user:${grace}`));
+
+  // An invalid name, a duplicate name, or a missing CSRF token are all refused, nothing written.
+  const before = tuples.length;
+  assert.equal((await post("/admin/groups", `_csrf=${token}&name=Bad Name&member=user:${grace}`)).status, 400);
+  assert.equal((await post("/admin/groups", `_csrf=${token}&name=eng&member=user:${grace}`)).status, 400); // already exists
+  assert.equal((await post("/admin/groups", `name=x&member=user:${grace}`)).status, 403);
+  assert.equal(tuples.length, before);
+
+  // Detail: lists the current member by email.
+  assert.match(await (await get("/admin/groups/eng")).text(), /ada@example\.com/);
+
+  // Add a member, then remove it.
+  await post("/admin/groups/eng/members", `_csrf=${token}&member=user:${grace}`);
+  assert.ok(tuples.some((tp) => tp.object === "eng" && tp.subject_id === `user:${grace}`));
+  await post("/admin/groups/eng/members/delete", `_csrf=${token}&member=user:${grace}`);
+  assert.ok(!tuples.some((tp) => tp.object === "eng" && tp.subject_id === `user:${grace}`));
+
+  // Give it a permission first, so the delete below has an orphan to avoid leaving behind.
+  const permissionsBaseline = baselineOf(await (await get("/admin/groups/eng")).text());
+  await post("/admin/groups/eng/permissions", `_csrf=${token}&baseline=${permissionsBaseline}&permission=users%3Aread`);
+  assert.ok(tuples.some((tp) => tp.namespace === "Permission" && tp.object === "users:read" && tp.subject_set?.object === "eng"));
+
+  // Delete the group: a confirm step (GET) then the POST removes every member tuple, back to the list.
+  assert.match(await (await get("/admin/groups/eng/delete")).text(), /Cancel/);
+  const del = await post("/admin/groups/eng/delete", `_csrf=${token}`);
+  assert.equal(del.status, 303);
+  assert.equal(del.headers.get("location"), "/admin/groups");
+  assert.ok(!tuples.some((tp) => tp.object === "eng"));
+  // …and the permissions it held go with it. A Keto set exists only through its tuples, so an
+  // orphaned grant would resurrect the moment someone re-created a group with the same name.
+  assert.ok(!tuples.some((tp) => tp.namespace === "Permission" && tp.subject_set?.object === "eng"));
+
+  // An invalid group name in the path → 404; malformed %-encoding doesn't 500.
+  assert.equal((await get("/admin/groups/Bad%20Name")).status, 404);
+  assert.equal((await get("/admin/groups/%ZZ")).status, 404);
+});
+
+// Granting permissions over HTTP. The offered set is the host's catalog (ctx.declaredPermissions),
+// so the checkboxes are a fixed list and the POST is the desired state.
+test("admin permission grants: the picker offers the declared catalog, and a save is the desired set", async (t) => {
+  const ada = randomUUID();
+  const identities: Identity[] = [{ id: ada, traits: { email: "ada@example.com" } }];
+  const tuples: RelationTuple[] = [{ namespace: "Permission", object: "users:read", relation: "granted", subject_id: `user:${ada}` }];
+  const keto = fakeKeto(tuples);
+  const kratosAdmin = stubAdmin({ getIdentity: async (id) => identities.find((i) => i.id === id) ?? null, listIdentities: async () => ({ identities, nextPageToken: null }) });
+  const denylist = createDenylist();
+  const { get, post, token } = await adminHarness(t, { denylist, keto, kratosAdmin });
+
+  // The user edit page renders one checkbox per declared permission, ticked where already held.
+  const edit = await (await get(`/admin/users/${ada}`)).text();
+  for (const name of ["users:read", "users:write", "groups:read", "groups:write", "oauth2-clients:read", "oauth2-clients:write"]) {
+    assert.match(edit, new RegExp(`value="${name.replace(":", ":")}"`), name);
+  }
+  assert.match(edit, /value="users:read"[^>]*checked/); // held → ticked
+  assert.doesNotMatch(edit, /value="groups:write"[^>]*checked/); // not held → unticked
+  assert.doesNotMatch(edit, /Permissions saved/); // no confirmation before a save
+
+  // Save a new set: users:write is added, users:read is dropped — the POST is the whole truth.
+  const baseline = baselineOf(edit);
+  const saved = await post(`/admin/users/${ada}/permissions`, `_csrf=${token}&baseline=${baseline}&permission=users%3Awrite&permission=groups%3Aread`);
+  assert.equal(saved.status, 303);
+  assert.deepEqual(
+    tuples.filter((tp) => tp.subject_id === `user:${ada}`).map((tp) => tp.object).sort(),
+    ["groups:read", "users:write"],
+  );
+  assert.equal(denylist.isRevoked(ada, 0), true); // a change to your own grants revokes live tokens
+
+  // The redirect lands on a page that confirms the save, and shows the new state.
+  const landing = saved.headers.get("location") ?? "";
+  assert.match(landing, new RegExp(`^/admin/users/${ada}\\?info-msg=permissions-saved$`));
+  const confirmed = await (await get(landing)).text();
+  assert.match(confirmed, /Permissions saved/);
+  assert.match(confirmed, /value="users:write"[^>]*checked/);
+
+  // A crafted POST can't grant something no plugin declares.
+  await post(`/admin/users/${ada}/permissions`, `_csrf=${token}&baseline=${baselineOf(confirmed)}&permission=users%3Awrite&permission=superuser%3Aall`);
+  assert.ok(!tuples.some((tp) => tp.object === "superuser:all"));
+
+  // The same picker on a group writes the group's subject_set, which Keto resolves transitively.
+  tuples.push({ namespace: "Group", object: "eng", relation: "members", subject_id: `user:${ada}` });
+  const groupBaseline = baselineOf(await (await get("/admin/groups/eng")).text());
+  const groupSaved = await post("/admin/groups/eng/permissions", `_csrf=${token}&baseline=${groupBaseline}&permission=groups%3Aread`);
+  assert.equal(groupSaved.headers.get("location"), "/admin/groups/eng?info-msg=permissions-saved");
+  assert.ok(tuples.some((tp) => tp.namespace === "Permission" && tp.object === "groups:read" && tp.subject_set?.object === "eng"));
+});
+
+// Two admins open the same page; the second save would silently undo the first.
+test("admin permission grants: a save from a stale page is refused, and the page re-renders the current state", async (t) => {
+  const ada = randomUUID();
+  const identities: Identity[] = [{ id: ada, traits: { email: "ada@example.com" } }];
+  const tuples: RelationTuple[] = [{ namespace: "Permission", object: "users:read", relation: "granted", subject_id: `user:${ada}` }];
+  const keto = fakeKeto(tuples);
+  const kratosAdmin = stubAdmin({ getIdentity: async (id) => identities.find((i) => i.id === id) ?? null, listIdentities: async () => ({ identities, nextPageToken: null }) });
+  const { get, post, token } = await adminHarness(t, { keto, kratosAdmin });
+  const stale = baselineOf(await (await get(`/admin/users/${ada}`)).text());
+
+  // Another admin grants users:write while this page is open.
+  tuples.push({ namespace: "Permission", object: "users:write", relation: "granted", subject_id: `user:${ada}` });
+  const before = JSON.stringify(tuples);
+  const refused = await post(`/admin/users/${ada}/permissions`, `_csrf=${token}&baseline=${stale}&permission=users%3Aread&permission=groups%3Aread`);
+  assert.equal(refused.status, 409);
+  const page = await refused.text();
+  assert.match(page, /changed while you had the page open/);
+  assert.equal(JSON.stringify(tuples), before, "nothing was applied");
+  assert.match(page, /value="users:write"[^>]*checked/); // the re-render shows the other admin's grant
+  assert.notEqual(baselineOf(page), stale);
+
+  // Saving from the re-rendered page goes through.
+  const retried = await post(`/admin/users/${ada}/permissions`, `_csrf=${token}&baseline=${baselineOf(page)}&permission=users%3Aread&permission=users%3Awrite&permission=groups%3Aread`);
+  assert.equal(retried.status, 303);
+  assert.ok(tuples.some((tp) => tp.object === "groups:read" && tp.subject_id === `user:${ada}`));
+
+  // A POST with no token at all (a crafted request, or a form rendered before this check existed) is stale too.
+  assert.equal((await post(`/admin/users/${ada}/permissions`, `_csrf=${token}&permission=users%3Aread`)).status, 409);
+
+  // Groups are checked the same way.
+  tuples.push({ namespace: "Group", object: "eng", relation: "members", subject_id: `user:${ada}` });
+  const groupStale = baselineOf(await (await get("/admin/groups/eng")).text());
+  tuples.push({ namespace: "Permission", object: "groups:read", relation: "granted", subject_set: { namespace: "Group", object: "eng", relation: "members" } });
+  const groupRefused = await post("/admin/groups/eng/permissions", `_csrf=${token}&baseline=${groupStale}&permission=users%3Aread`);
+  assert.equal(groupRefused.status, 409);
+  assert.match(await groupRefused.text(), /changed while you had the page open/);
+  assert.ok(tuples.some((tp) => tp.object === "groups:read" && tp.subject_set?.object === "eng"), "the group keeps its grant");
+});
+
+// A Keto error midway leaves some changes applied; the save says so and still revokes the user's live tokens.
+test("admin permission grants: a Keto failure midway reports a partial save and keeps what was applied", async (t) => {
+  const ada = randomUUID();
+  const identities: Identity[] = [{ id: ada, traits: { email: "ada@example.com" } }];
+  const tuples: RelationTuple[] = [];
+  let writes = 0;
+  const keto = fakeKeto(tuples, {
+    writeTuple: async (tp) => {
+      if (++writes === 2) throw new Error("keto unreachable");
+      tuples.push(tp);
+    },
+  });
+  const kratosAdmin = stubAdmin({ getIdentity: async (id) => identities.find((i) => i.id === id) ?? null, listIdentities: async () => ({ identities, nextPageToken: null }) });
+  const denylist = createDenylist();
+  const { get, post, token } = await adminHarness(t, { denylist, keto, kratosAdmin });
+  const baseline = baselineOf(await (await get(`/admin/users/${ada}`)).text());
+
+  const res = await post(`/admin/users/${ada}/permissions`, `_csrf=${token}&baseline=${baseline}&permission=groups%3Aread&permission=users%3Aread&permission=users%3Awrite`);
+  assert.equal(res.status, 502);
+  const page = await res.text();
+  assert.match(page, /stopped part-way/);
+  assert.match(page, /value="groups:read"[^>]*checked/); // the first write landed, and the page shows what is stored
+  assert.doesNotMatch(page, /value="users:write"[^>]*checked/);
+  assert.deepEqual(tuples.map((tp) => tp.object), ["groups:read"]);
+  assert.equal(denylist.isRevoked(ada, 0), true); // the half that was applied still revokes live tokens
+});
+
+// A double-clicked Save posts twice from one page; the second post finds the first one's result.
+// A save that changes nothing has nothing to refuse and nothing to revoke.
+test("admin permission grants: a save that changes nothing is not refused for a stale page and leaves live tokens alone", async (t) => {
+  const ada = randomUUID();
+  const identities: Identity[] = [{ id: ada, traits: { email: "ada@example.com" } }];
+  const tuples: RelationTuple[] = [{ namespace: "Permission", object: "users:read", relation: "granted", subject_id: `user:${ada}` }];
+  const kratosAdmin = stubAdmin({ getIdentity: async (id) => identities.find((i) => i.id === id) ?? null, listIdentities: async () => ({ identities, nextPageToken: null }) });
+  const denylist = createDenylist();
+  const { get, post, token } = await adminHarness(t, { denylist, keto: fakeKeto(tuples), kratosAdmin });
+  const stale = baselineOf(await (await get(`/admin/users/${ada}`)).text());
+  tuples.push({ namespace: "Permission", object: "users:write", relation: "granted", subject_id: `user:${ada}` });
+  const before = JSON.stringify(tuples);
+
+  const repeated = await post(`/admin/users/${ada}/permissions`, `_csrf=${token}&baseline=${stale}&permission=users%3Aread&permission=users%3Awrite`);
+  assert.equal(repeated.status, 303);
+  assert.equal(JSON.stringify(tuples), before);
+  assert.equal(denylist.isRevoked(ada, 0), false);
+});
+
+// Keto answered the writes but not the re-read: the report must still reach the admin.
+test("admin permission grants: a partial save is still reported when Keto cannot be read again", async (t) => {
+  const ada = randomUUID();
+  const identities: Identity[] = [{ id: ada, traits: { email: "ada@example.com" } }];
+  const tuples: RelationTuple[] = [];
+  let writes = 0;
+  let down = false;
+  let failureTakesKetoDown = true;
+  const keto = fakeKeto(tuples, {
+    listRelations: async (q = {}) => {
+      if (down) throw new Error("keto unreachable");
+      return { nextPageToken: null, tuples: tuples.filter((tp) => matchesTuple(tp, q)) };
+    },
+    writeTuple: async (tp) => {
+      if (++writes === 2) { down = failureTakesKetoDown; throw new Error("keto unreachable"); }
+      tuples.push(tp);
+    },
+  });
+  const kratosAdmin = stubAdmin({ getIdentity: async (id) => identities.find((i) => i.id === id) ?? null, listIdentities: async () => ({ identities, nextPageToken: null }) });
+  const { get, post, token } = await adminHarness(t, { keto, kratosAdmin });
+  const baseline = baselineOf(await (await get(`/admin/users/${ada}`)).text());
+
+  const res = await post(`/admin/users/${ada}/permissions`, `_csrf=${token}&baseline=${baseline}&permission=groups%3Aread&permission=users%3Aread`);
+  assert.equal(res.status, 502);
+  assert.match(await res.text(), /stopped part-way/);
+  assert.deepEqual(tuples.map((tp) => tp.object), ["groups:read"]);
+
+  // The same on a group, whose page needs Keto for its members as well.
+  down = false;
+  writes = 0;
+  tuples.length = 0;
+  tuples.push({ namespace: "Group", object: "eng", relation: "members", subject_id: `user:${ada}` });
+  const groupBaseline = baselineOf(await (await get("/admin/groups/eng")).text());
+  const groupRes = await post("/admin/groups/eng/permissions", `_csrf=${token}&baseline=${groupBaseline}&permission=groups%3Aread&permission=users%3Aread`);
+  assert.equal(groupRes.status, 502);
+  assert.match(await groupRes.text(), /stopped part-way/);
+  assert.ok(tuples.some((tp) => tp.object === "groups:read" && tp.subject_set?.object === "eng"), "the first write landed");
+
+  // With Keto still answering, the group page itself reports it and shows what is stored.
+  failureTakesKetoDown = false;
+  down = false;
+  writes = 0;
+  tuples.length = 1;
+  const again = await post("/admin/groups/eng/permissions", `_csrf=${token}&baseline=${baselineOf(await (await get("/admin/groups/eng")).text())}&permission=groups%3Aread&permission=users%3Aread`);
+  assert.equal(again.status, 502);
+  const page = await again.text();
+  assert.match(page, /stopped part-way/);
+  assert.match(page, /value="groups:read"[^>]*checked/);
+});
+
+// Revoking your own grants can remove the last users:write on the deployment, and the instant-revoke
+// hook lands it on the next request — recovery would be a curl against Keto. Guarded like
+// self-deactivate and self-delete are. (`admin1` is the harness's own sub.)
+test("admin permission grants: you can't revoke your own permissions, but you can still grant", async (t) => {
+  const identities: Identity[] = [{ id: "admin1", traits: { email: "you@example.com" } }];
+  const tuples: RelationTuple[] = [{ namespace: "Permission", object: "users:write", relation: "granted", subject_id: "user:admin1" }];
+  const keto = fakeKeto(tuples);
+  const kratosAdmin = stubAdmin({ getIdentity: async (id) => identities.find((i) => i.id === id) ?? null, listIdentities: async () => ({ identities, nextPageToken: null }) });
+  const { get, post, token } = await adminHarness(t, { keto, kratosAdmin });
+  const baseline = baselineOf(await (await get("/admin/users/admin1")).text());
+
+  const refused = await post("/admin/users/admin1/permissions", `_csrf=${token}&baseline=${baseline}`); // every box cleared
+  assert.equal(refused.status, 400);
+  assert.match(await refused.text(), /lock yourself out/);
+  assert.ok(tuples.some((tp) => tp.object === "users:write" && tp.subject_id === "user:admin1"), "nothing was revoked");
+
+  // Granting yourself more is not a lockout, so it goes through.
+  const granted = await post("/admin/users/admin1/permissions", `_csrf=${token}&baseline=${baseline}&permission=users%3Awrite&permission=groups%3Aread`);
+  assert.equal(granted.status, 303);
+  assert.ok(tuples.some((tp) => tp.object === "groups:read" && tp.subject_id === "user:admin1"));
+});
+
+// A check over the tuple array that expands nested groups.
+function resolvingCheck(tuples: RelationTuple[]) {
+  const reaches = (q: RelationTuple, ns: string, object: string, relation: string, seen: Set<string>): boolean => {
+    const key = `${ns}:${object}#${relation}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return tuples.some((tp) => tp.namespace === ns && tp.object === object && tp.relation === relation && (
+      (q.subject_id !== undefined && tp.subject_id === q.subject_id) ||
+      (q.subject_set !== undefined && tp.subject_set?.namespace === q.subject_set.namespace && tp.subject_set.object === q.subject_set.object) ||
+      (tp.subject_set !== undefined && reaches(q, tp.subject_set.namespace, tp.subject_set.object, tp.subject_set.relation, seen))));
+  };
+  return async (q: RelationTuple) => reaches(q, q.namespace, q.object, q.relation, new Set());
+}
+
+// A member value must be a UUID, so this test signs in as `you`.
+test("admin groups: you can't take away permissions you hold only through a group you are in", async (t) => {
+  const ada = "01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b01";
+  const you = "01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b02";
+  const identities: Identity[] = [{ id: you, traits: { email: "you@example.com" } }, { id: ada, traits: { email: "ada@example.com" } }];
+  const member = (group: string, subject: string): RelationTuple => ({ namespace: "Group", object: group, relation: "members", subject_id: subject });
+  const nested = (group: string, child: string): RelationTuple => ({ namespace: "Group", object: group, relation: "members", subject_set: { namespace: "Group", object: child, relation: "members" } });
+  const grant = (permission: string, group: string): RelationTuple => ({ namespace: "Permission", object: permission, relation: "granted", subject_set: { namespace: "Group", object: group, relation: "members" } });
+  const tuples: RelationTuple[] = [
+    member("eng", `user:${you}`), member("eng", `user:${ada}`), grant("users:write", "eng"), grant("groups:write", "eng"),
+    { namespace: "Permission", object: "groups:write", relation: "granted", subject_id: `user:${you}` }, // also held directly
+    nested("leads", "eng"), grant("oauth2-clients:write", "leads"), // reached through eng
+    member("social", `user:${you}`), // confers nothing
+    member("design", `user:${ada}`), grant("users:write", "design"), // you are not in it
+  ];
+  const keto = fakeKeto(tuples, { check: resolvingCheck(tuples) });
+  const kratosAdmin = stubAdmin({ getIdentity: async (id) => identities.find((i) => i.id === id) ?? null, listIdentities: async () => ({ identities, nextPageToken: null }) });
+  const { get, post, token } = await adminHarness(t, { keto, kratosAdmin }, you);
+  const baseline = baselineOf(await (await get("/admin/groups/eng")).text());
+  // A refusal renders that group's own page and names what you would lose.
+  const refusedWithMessage = async (res: Response, group: string, lost: string) => {
+    assert.equal(res.status, 400);
+    const html = await res.text();
+    assert.match(html, new RegExp(`lock you out of ${lost}, which`));
+    assert.match(html, new RegExp(`action="/admin/groups/${group}/members"`));
+  };
+
+  // Unticking users:write on eng would take it from you: refused, nothing revoked.
+  const before = JSON.stringify(tuples);
+  await refusedWithMessage(await post("/admin/groups/eng/permissions", `_csrf=${token}&baseline=${baseline}&permission=groups%3Awrite`), "eng", "users:write");
+  // Leaving eng, removing eng from leads, or deleting eng (the confirm step too) are refused the same
+  // way; leaving eng also loses what it gets from leads.
+  await refusedWithMessage(await post("/admin/groups/eng/members/delete", `_csrf=${token}&member=user:${you}`), "eng", "oauth2-clients:write, users:write");
+  await refusedWithMessage(await post("/admin/groups/leads/members/delete", `_csrf=${token}&member=group:eng`), "leads", "oauth2-clients:write");
+  await refusedWithMessage(await get("/admin/groups/eng/delete"), "eng", "oauth2-clients:write, users:write");
+  await refusedWithMessage(await post("/admin/groups/eng/delete", `_csrf=${token}`), "eng", "oauth2-clients:write, users:write");
+  assert.equal(JSON.stringify(tuples), before, "nothing changed");
+
+  // You hold groups:write directly too, so unticking it on eng costs you nothing.
+  assert.equal((await post("/admin/groups/eng/permissions", `_csrf=${token}&baseline=${baseline}&permission=users%3Awrite`)).status, 303);
+  // Removing someone else, leaving a group that confers nothing, and deleting a group you are not in all go through.
+  assert.equal((await post("/admin/groups/eng/members/delete", `_csrf=${token}&member=user:${ada}`)).status, 303);
+  assert.equal((await post("/admin/groups/social/members/delete", `_csrf=${token}&member=user:${you}`)).status, 303);
+  assert.equal((await post("/admin/groups/design/delete", `_csrf=${token}`)).status, 303);
+  assert.ok(!tuples.some((tp) => tp.object === "design" || tp.subject_set?.object === "design"));
+});
+
+// The read/write split is only honest if the UI models it: a users:read holder must not be shown
+// buttons that 403 on submit. The gate already refuses them (asserted above); this is the affordance.
+test("admin screens render no write affordance for a read-only holder", async (t) => {
+  const ada = randomUUID();
+  const identities: Identity[] = [{ id: ada, traits: { email: "ada@example.com" } }];
+  const keto = fakeKeto([{ namespace: "Group", object: "eng", relation: "members", subject_id: `user:${ada}` }]);
+  const kratosAdmin = stubAdmin({ getIdentity: async (id) => identities.find((i) => i.id === id) ?? null, listIdentities: async () => ({ identities, nextPageToken: null }) });
+  // Hydra is wired so the clients screen renders for real — without it the page is a 503 and the
+  // "no Register button" assertion below would pass without proving anything.
+  const reporting = { client_id: "existing", client_name: "Reporting" };
+  const hydra = stubHydra({ getClient: async (id) => (id === reporting.client_id ? reporting : null), listClients: async () => ({ clients: [reporting], nextPageToken: null }) });
+  const { get } = await adminHarness(t, { hydra, keto, kratosAdmin });
+  const readOnly = ["users:read", "groups:read"];
+
+  const list = await (await get("/admin/users", readOnly)).text();
+  assert.doesNotMatch(list, /href="\/admin\/users\/new"/); // no "New user"
+  assert.match(list, /ada@example\.com/); // but the list itself is there — that's the point of :read
+
+  // (The shell's own sign-out is a POST form, so assert on the affordances by name, not on <form>.)
+  const detail = await (await get(`/admin/users/${ada}`, readOnly)).text();
+  assert.doesNotMatch(detail, /Save changes/);
+  assert.doesNotMatch(detail, /Generate recovery code/);
+  assert.doesNotMatch(detail, /Delete user/);
+  assert.doesNotMatch(detail, /Save permissions/);
+  assert.match(detail, /type="checkbox"[^>]*disabled/); // the permissions are shown, just not editable
+
+  const group = await (await get("/admin/groups/eng", readOnly)).text();
+  assert.doesNotMatch(group, /Add a member/);
+  assert.doesNotMatch(group, /Delete group/);
+  assert.doesNotMatch(group, /Save permissions/);
+
+  // The OAuth2-clients screen is held to the same rule.
+  const clientsRes = await get("/admin/clients", ["oauth2-clients:read"]);
+  assert.equal(clientsRes.status, 200); // a real render, not the capability-missing 503
+  const clients = await clientsRes.text();
+  assert.match(clients, /Reporting/); // the list is there — that's what :read buys
+  assert.doesNotMatch(clients, /href="\/admin\/clients\/new"/);
+  // The detail page is where Delete lives, so check it too and not just the list.
+  const clientDetail = await (await get("/admin/clients/existing", ["oauth2-clients:read"])).text();
+  assert.match(clientDetail, /Reporting/);
+  assert.doesNotMatch(clientDetail, /clients\/existing\/delete/);
+
+  // A write-intent GET — a create form or a delete-confirm — refuses a reader outright rather than
+  // rendering a form whose submit would 403.
+  for (const path of ["/admin/users/new", "/admin/groups/new", `/admin/users/${ada}/delete`, "/admin/groups/eng/delete"]) {
+    assert.equal((await get(path, readOnly)).status, 403, path);
+  }
+  assert.equal((await get("/admin/clients/new", ["oauth2-clients:read"])).status, 403);
+
+  // A writer sees the affordances the reader didn't.
+  const writable = await (await get(`/admin/users/${ada}`, ["users:read", "users:write"])).text();
+  assert.match(writable, /Save changes/);
+  assert.match(writable, /Save permissions/);
+});
+
+// Built-in OAuth2 clients admin screen: gate + list/register/detail/delete over HTTP against an
+// in-memory Hydra. Registration shows the one-time client_secret on the post-create page (no PRG).
+test("admin OAuth2 clients screen: gate, list, register (one-time secret), detail, delete (CSRF-guarded)", async (t) => {
+  const store: OAuth2Client[] = [
+    { client_id: "existing", client_name: "Reporting", redirect_uris: ["https://reporting.example/cb"], scope: "openid", token_endpoint_auth_method: "client_secret_basic" },
+  ];
+  let seq = 0;
+  const hydra = stubHydra({
+    createClient: async (c) => { const created = { ...c, client_id: `gen-${++seq}`, client_secret: `secret-${seq}` }; store.push(created); return created; },
+    deleteClient: async (id) => { const i = store.findIndex((c) => c.client_id === id); if (i >= 0) store.splice(i, 1); },
+    getClient: async (id) => store.find((c) => c.client_id === id) ?? null,
+    listClients: async () => ({ clients: store, nextPageToken: null }),
+  });
+  const { get, post, token, url } = await adminHarness(t, { hydra });
+
+  await assertAdminGate(url, get, "/admin/clients");
+
+  // List: the existing client shows + the "register" link.
+  const listHtml = await (await get("/admin/clients")).text();
+  assert.match(listHtml, /href="\/admin\/clients\/existing"/);
+  assert.match(listHtml, /href="\/admin\/clients\/new"/);
+  assert.match(listHtml, /Reporting/);
+
+  // Register: the form renders (with confidential-vs-public guidance); a valid post creates the
+  // client and shows the one-time secret + id.
+  const formHtml = await (await get("/admin/clients/new")).text();
+  assert.match(formHtml, /Register client/);
+  assert.match(formHtml, /keep a secret/i); // guidance on the public-vs-confidential choice (apostrophes arrive escaped: t() text goes through <%= %>)
+  const created = await post("/admin/clients", `_csrf=${token}&name=Grafana&redirectUris=${encodeURIComponent("https://graf/cb")}&scope=openid+offline_access`);
+  assert.equal(created.status, 200); // not a redirect — the secret is shown once
+  const createdHtml = await created.text();
+  assert.match(createdHtml, /Client registered/);
+  assert.match(createdHtml, /secret-1/); // the one-time client_secret
+  assert.match(createdHtml, /gen-1/);    // the generated client_id
+  assert.ok(store.some((c) => c.client_name === "Grafana" && c.token_endpoint_auth_method === "client_secret_basic"));
+
+  // Invalid input (missing redirect URI) and a missing CSRF token are both refused, nothing created.
+  const before = store.length;
+  assert.equal((await post("/admin/clients", `_csrf=${token}&name=NoRedirect&redirectUris=`)).status, 400);
+  assert.equal((await post("/admin/clients", `name=x&redirectUris=${encodeURIComponent("https://x/cb")}`)).status, 403);
+  assert.equal(store.length, before);
+
+  // Detail: read-only info, never the secret again, a delete control.
+  const detail = await (await get("/admin/clients/existing")).text();
+  assert.match(detail, /reporting\.example\/cb/);
+  assert.doesNotMatch(detail, /Client secret/i); // the secret is shown only once, at creation
+  assert.match(detail, /delete and re-register/i); // no edit: the lifecycle guidance is surfaced
+  assert.match(detail, /href="\/admin\/clients\/existing\/delete"/);
+
+  // Delete: a confirm step (GET) then the POST removes the client, back to the list.
+  assert.match(await (await get("/admin/clients/existing/delete")).text(), /Cancel/);
+  const del = await post("/admin/clients/existing/delete", `_csrf=${token}`);
+  assert.equal(del.status, 303);
+  assert.equal(del.headers.get("location"), "/admin/clients");
+  assert.ok(!store.some((c) => c.client_id === "existing"));
+
+  // Unknown id → 404; malformed %-encoding doesn't 500.
+  assert.equal((await get("/admin/clients/does-not-exist")).status, 404);
+  assert.equal((await get("/admin/clients/%ZZ")).status, 404);
+});
+

src/http/app-auth.test.ts

@@ -0,0 +1,391 @@
+import assert from "node:assert/strict";
+import type { AddressInfo } from "node:net";
+import { test } from "node:test";
+import { createApp } from "./app.ts";
+import { CSRF_COOKIE, issueCsrfToken } from "../auth/csrf.ts";
+import { HydraError, type HydraAdmin } from "../auth/hydra-admin.ts";
+import { staticJwks } from "../auth/jwks.ts";
+import type { Identity } from "../auth/kratos-admin.ts";
+import { KratosError, type Flow, type FlowType, type KratosPublic, type Session, type UiNode } from "../auth/kratos-public.ts";
+import { SESSION_COOKIE } from "../auth/login.ts";
+import { createI18n } from "../i18n/runtime.ts";
+import { loadI18n } from "../i18n/load.ts";
+import { ecJwk, fakeKeto, mintJwt, mockKratos, OAUTH_SUBJECT, stubAdmin, stubHydra, withWhoami } from "./app-harness.ts";
+
+// A re-rendered login flow: csrf hidden, themed fields, a submit, and a failed-attempt message.
+const node = (attrs: Record<string, unknown>, label?: string): UiNode => ({ attributes: attrs, group: "default", messages: [], meta: label ? { label: { id: 1, text: label, type: "info" } } : {}, type: "input" });
+const loginFlow = (id: string): Flow => ({
+  id,
+  ui: {
+    action: `http://127.0.0.1:4433/self-service/login?flow=${id}`,
+    messages: [{ id: 4000006, text: "The provided credentials are invalid.", type: "error" }],
+    method: "post",
+    nodes: [
+      node({ name: "csrf_token", type: "hidden", value: "tok" }),
+      node({ name: "identifier", required: true, type: "email" }, "E-Mail"),
+      node({ name: "password", required: true, type: "password" }, "Password"),
+      node({ name: "method", type: "submit", value: "password" }, "Sign in"),
+      { attributes: { name: "provider", type: "submit", value: "google" }, group: "oidc", messages: [], meta: { label: { id: 1, text: "Sign in with Google", type: "info" } }, type: "input" },
+    ],
+  },
+});
+
+// GET dispatch for the themed auth pages: the same handler branches on session presence.
+test("themed auth GET: anonymous inits a flow (CSRF relay, stale→restart); a signed-in user is sent home, except /settings", async (t) => {
+  const app = createApp({ jwks: staticJwks([ecJwk]), kratos: mockKratos(async (_t, id) => { if (id === "stale") throw new KratosError("gone", 410, ""); return loginFlow(id); }) });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+
+  // Anonymous, no ?flow= → init one + relay Kratos' CSRF cookie.
+  const init = await fetch(url + "/login", { redirect: "manual" });
+  assert.equal(init.status, 303);
+  assert.equal(init.headers.get("location"), "/login?flow=new1");
+  assert.match(init.headers.get("set-cookie") ?? "", /csrf_token=abc/);
+  // A stale flow id (Kratos 410) bounces back to a fresh init.
+  const stale = await fetch(url + "/login?flow=stale", { redirect: "manual" });
+  assert.equal(stale.status, 303);
+  assert.equal(stale.headers.get("location"), "/login");
+
+  // Already signed in → /login + /registration short-circuit to the app dashboard; /settings stays reachable.
+  const signedIn = { headers: { cookie: `${SESSION_COOKIE}=${mintJwt({ email: "a@b.c", exp: Math.floor(Date.now() / 1000) + 600, permissions: [], sub: "u1" })}` }, redirect: "manual" as const };
+  for (const path of ["/login", "/registration"]) {
+    const res = await fetch(url + path, signedIn);
+    assert.equal(res.status, 303, `${path} while signed in → 303`);
+    assert.equal(res.headers.get("location"), "/dashboard");
+  }
+  assert.equal((await fetch(url + "/settings", signedIn)).headers.get("location"), "/settings?flow=new1");
+});
+
+test("themed auth GET: an existing Kratos session (no app JWT yet) recovers via /auth/complete, never 500", async (t) => {
+  // After registration's `session` hook the user holds a Kratos session but no app JWT — so ctx.user
+  // is null and the "already signed in" short-circuit can't fire. Initialising a login/registration
+  // flow then returns Kratos 400 `session_already_available`; recover by completing login (mint the
+  // JWT from the live session), preserving return_to — never fall through to the catch-all 500.
+  const sessionRace = new KratosError("Kratos init login flow failed (400)", 400, JSON.stringify({ error: { id: "session_already_available" } }));
+  const app = createApp({ jwks: staticJwks([ecJwk]), kratos: { ...mockKratos(async () => loginFlow("x")), initBrowserFlow: async () => { throw sessionRace; } } });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+
+  const recover = await fetch(url + "/login", { redirect: "manual" });
+  assert.equal(recover.status, 303);
+  assert.equal(recover.headers.get("location"), "/auth/complete");
+  // return_to is carried through so the deep link still lands after the JWT is minted.
+  const deep = await fetch(url + "/login?return_to=" + encodeURIComponent("/admin/users"), { redirect: "manual" });
+  assert.equal(deep.headers.get("location"), "/auth/complete?return_to=%2Fadmin%2Fusers");
+
+  // A genuinely unexpected Kratos 400 is still surfaced as a 500 (not masked as a session race).
+  const app2 = createApp({ jwks: staticJwks([ecJwk]), kratos: { ...mockKratos(async () => loginFlow("x")), initBrowserFlow: async () => { throw new KratosError("bad", 400, JSON.stringify({ error: { id: "security_csrf_violation" } })); } } });
+  await new Promise<void>((r) => app2.listen(0, r));
+  t.after(() => app2.close());
+  const url2 = `http://localhost:${(app2.address() as AddressInfo).port}`;
+  assert.equal((await fetch(url2 + "/login", { redirect: "manual" })).status, 500);
+});
+
+test("themed auth GET: an anonymous hit on /settings (Kratos 401) bounces to sign-in with the page as return_to, never 500", async (t) => {
+  let failure = new KratosError("Kratos init settings flow failed (401)", 401, "");
+  const throwing = async (): Promise<never> => { throw failure; };
+  const app = createApp({ jwks: staticJwks([ecJwk]), kratos: { ...mockKratos(throwing), initBrowserFlow: throwing } });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+
+  const init = await fetch(url + "/settings", { redirect: "manual" });
+  assert.equal(init.status, 303);
+  assert.equal(init.headers.get("location"), "/login?return_to=%2Fsettings");
+  const existing = await fetch(url + "/settings?flow=f1", { redirect: "manual" });
+  assert.equal(existing.headers.get("location"), "/login?return_to=%2Fsettings");
+  // /login redirecting to itself would loop, so a 401 there stays the catch-all 500.
+  assert.equal((await fetch(url + "/login", { redirect: "manual" })).status, 500);
+  // Only a 401 means "sign in": an Ory outage on /settings is still the honest 503.
+  failure = new KratosError("Kratos init settings flow failed (500)", 500, "");
+  assert.equal((await fetch(url + "/settings", { redirect: "manual" })).status, 503);
+});
+
+// return_to: a deep-link login lands back on the requested page. The gate redirects to
+// /login?return_to=<host-relative path>; /login bakes that into the Kratos flow so completion
+// returns there — but a first-party path must route via /auth/complete first (to mint the JWT).
+test("login return_to: a first-party deep link is wrapped through /auth/complete; an absolute target passes through as-is", async (t) => {
+  let lastReturnTo: string | undefined;
+  const kratos: KratosPublic = {
+    ...mockKratos(async (_t, id) => loginFlow(id)),
+    initBrowserFlow: async (_t: FlowType, opts = {}) => { lastReturnTo = opts.returnTo; return { flow: { id: "new1", ui: { action: "", method: "post", nodes: [] } }, setCookie: [] }; },
+  };
+  const app = createApp({ kratos });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+
+  // A host-relative deep link → wrapped: Kratos returns to <origin>/auth/complete?return_to=<path>,
+  // so the JWT is minted before the user lands on the page (query preserved, re-encoded).
+  await fetch(url + "/login?return_to=" + encodeURIComponent("/admin/users?q=1"), { redirect: "manual" });
+  assert.match(lastReturnTo ?? "", /^http:\/\/[^/]+\/auth\/complete\?return_to=%2Fadmin%2Fusers%3Fq%3D1$/);
+
+  // An absolute target (the OAuth2 login challenge) is passed to Kratos unchanged — Kratos
+  // allow-lists it. A protocol-relative "//evil.com" is likewise not wrapped (Kratos rejects it).
+  const abs = "http://localhost/oauth2/login?login_challenge=abc";
+  await fetch(url + "/login?return_to=" + encodeURIComponent(abs), { redirect: "manual" });
+  assert.equal(lastReturnTo, abs);
+  await fetch(url + "/login?return_to=" + encodeURIComponent("//evil.com"), { redirect: "manual" });
+  assert.equal(lastReturnTo, "//evil.com");
+});
+
+test("login return_to: a chosen language alone still routes through /auth/complete, so it survives the sign-in", async (t) => {
+  let lastReturnTo: string | undefined;
+  const kratos: KratosPublic = {
+    ...mockKratos(async (_t, id) => loginFlow(id)),
+    initBrowserFlow: async (_t: FlowType, opts = {}) => { lastReturnTo = opts.returnTo; return { flow: { id: "new1", ui: { action: "", method: "post", nodes: [] } }, setCookie: [] }; },
+  };
+  const app = createApp({ i18n: createI18n(await loadI18n()), kratos });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+
+  lastReturnTo = "unset";
+  await fetch(url + "/login", { redirect: "manual" });
+  assert.equal(lastReturnTo, undefined, "no target and no language: Kratos keeps its default");
+  await fetch(url + "/login?locale=sv-SE", { redirect: "manual" });
+  assert.match(lastReturnTo ?? "", /^http:\/\/[^/]+\/auth\/complete\?locale=sv-SE$/);
+  await fetch(url + "/login?locale=sv-SE&return_to=" + encodeURIComponent("/admin/users"), { redirect: "manual" });
+  assert.match(lastReturnTo ?? "", /^http:\/\/[^/]+\/auth\/complete\?return_to=%2Fadmin%2Fusers%3Flocale%3Dsv-SE&locale=sv-SE$/);
+
+  // An absolute target still reaches Kratos beside a chosen language; the language is lost instead.
+  const abs = "http://localhost/oauth2/login?login_challenge=abc";
+  await fetch(url + "/login?locale=sv-SE&return_to=" + encodeURIComponent(abs), { redirect: "manual" });
+  assert.equal(lastReturnTo, abs);
+});
+
+// "Ory down ⇒ no logins" is documented; the auth path should say so honestly (503), not the
+// generic "error on our end" 500 the catch-all renders.
+test("auth flow when Ory is unreachable → an honest 503, not the catch-all 500", async (t) => {
+  const boom = () => { throw new KratosError("kratos down", 503, ""); };
+  const down: KratosPublic = { ...mockKratos(async () => boom()), initBrowserFlow: async () => boom() };
+  const app = createApp({ kratos: down });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+
+  const init = await fetch(url + "/login", { redirect: "manual" }); // init (no ?flow=) with Kratos down
+  assert.equal(init.status, 503);
+  assert.match(await init.text(), /unavailable/i);
+  assert.equal((await fetch(url + "/login?flow=f1")).status, 503); // fetching a flow, Kratos down
+
+  // A network-level throw (refused/timeout — not a KratosError) is treated the same way.
+  const refused: KratosPublic = { ...mockKratos(async () => { throw new Error("ECONNREFUSED"); }), initBrowserFlow: async () => { throw new Error("ECONNREFUSED"); } };
+  const app2 = createApp({ kratos: refused });
+  await new Promise<void>((r) => app2.listen(0, r));
+  t.after(() => app2.close());
+  assert.equal((await fetch(`http://localhost:${(app2.address() as AddressInfo).port}/login`, { redirect: "manual" })).status, 503);
+});
+
+test("renders a fetched flow as the themed auth page: fields post straight to Kratos, errors surface", async (t) => {
+  const app = createApp({ kratos: mockKratos(async (_t, id) => loginFlow(id)) });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const html = await (await fetch(`http://localhost:${(app.address() as AddressInfo).port}/login?flow=f1`)).text();
+
+  // The form posts to flow.ui.action (Kratos owns CSRF); csrf rides as a hidden input.
+  assert.match(html, /<form class="auth-card" method="post" action="http:\/\/127\.0\.0\.1:4433\/self-service\/login\?flow=f1"/);
+  assert.match(html, /<input type="hidden" name="csrf_token" value="tok">/);
+  assert.match(html, /name="identifier"/);
+  assert.match(html, /name="password"[^>]*type="password"/);
+  assert.match(html, /<button type="submit"[^>]*name="method" value="password">Sign in<\/button>/);
+  assert.match(html, /<a href="\/registration">Create one<\/a>/); // alt link to register
+  // Configured OIDC provider → an SSO submit button in the same form (posts provider=google);
+  // `formnovalidate` so it bypasses the required email/password fields (SSO needs neither).
+  assert.match(html, /<div class="sso"/);
+  assert.match(html, /<button type="submit" class="sso-btn" name="provider" value="google" formnovalidate>.*Sign in with Google<\/span><\/button>/s);
+  // The flow-level error renders as an alert.
+  assert.match(html, /class="alert alert-neg"/);
+  assert.match(html, /The credentials are invalid\./); // 4000006 → our wording (README → Translating)
+});
+
+// Login completion: /auth/complete is where Kratos lands the browser after login.
+test("login completion (/auth/complete): a live session mints the JWT cookie; no session → /login, no cookie", async (t) => {
+  const identity: Identity = { id: "01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b55", traits: { email: "admin@plainpages.local" } };
+  let projected: unknown;
+  const kratos = withWhoami(async (o) => (o?.tokenizeAs ? { active: true, identity, tokenized: "h.p.s" } : { active: true, identity }) as Session);
+  const kratosAdmin = stubAdmin({ updateMetadataPublic: async (_id, meta) => { projected = meta; return identity; } });
+  const keto = fakeKeto([], { check: async () => true, listRelations: async () => ({ nextPageToken: null, tuples: [{ namespace: "Permission", object: "admin", relation: "granted", subject_id: `user:${identity.id}` }] }) });
+  const complete = async (app: ReturnType<typeof createApp>, cookie?: string, returnTo?: string) => {
+    await new Promise<void>((r) => app.listen(0, r));
+    t.after(() => app.close());
+    const q = returnTo ? `?return_to=${encodeURIComponent(returnTo)}` : "";
+    return fetch(`http://localhost:${(app.address() as AddressInfo).port}/auth/complete${q}`, { headers: cookie ? { cookie } : {}, redirect: "manual" });
+  };
+
+  // Live Kratos session: permissions from Keto → projection → tokenize → JWT cookie, land on the dashboard.
+  const ok = await complete(createApp({ keto, kratos, kratosAdmin }), "plainpages_session=s");
+  assert.equal(ok.status, 303);
+  assert.equal(ok.headers.get("location"), "/dashboard");
+  assert.match(ok.headers.get("set-cookie") ?? "", /^plainpages_jwt=h\.p\.s;.*HttpOnly/);
+  assert.deepEqual(projected, { permissions: ["admin"] }); // Keto permissions projected onto the identity for the tokenizer
+
+  // return_to: a safe host-relative target lands the user back where they were headed; an
+  // off-origin one is ignored (open-redirect guard) and falls back to the dashboard.
+  assert.equal((await complete(createApp({ keto, kratos, kratosAdmin }), "plainpages_session=s", "/admin/users?q=1")).headers.get("location"), "/admin/users?q=1");
+  assert.equal((await complete(createApp({ keto, kratos, kratosAdmin }), "plainpages_session=s", "//evil.com")).headers.get("location"), "/dashboard");
+
+  // No Kratos session: nothing minted, bounce to /login with no cookie.
+  const none = await complete(createApp({ keto: fakeKeto(), kratos: withWhoami(async () => null), kratosAdmin: stubAdmin({}) }));
+  assert.equal(none.status, 303);
+  assert.equal(none.headers.get("location"), "/login");
+  assert.equal(none.headers.get("set-cookie"), null);
+});
+
+test("logout (CSRF-guarded POST): valid token revokes the Kratos session + clears our JWT; bad token → 403", async (t) => {
+  const logoutUrl = "http://127.0.0.1:4433/self-service/logout?token=lt";
+  // Real Kratos keys off its own session cookie (plainpages_session), not our always-present CSRF cookie.
+  const kratos: KratosPublic = { ...mockKratos(async () => { throw new Error("unused"); }), createLogoutFlow: async (o) => (o?.cookie?.includes("plainpages_session") ? { logoutToken: "lt", logoutUrl } : null) };
+  const csrfSecret = "logout-secret";
+  const app = createApp({ csrfSecret, kratos });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+  const token = issueCsrfToken(csrfSecret);
+  const post = (cookie: string, body: string) =>
+    fetch(url + "/logout", { body, headers: { "content-type": "application/x-www-form-urlencoded", cookie }, method: "POST", redirect: "manual" });
+
+  // Valid double-submit (cookie token === form token) + active session → Kratos logout URL, JWT cleared.
+  const out = await post(`${CSRF_COOKIE}=${token}; ${SESSION_COOKIE}=x; plainpages_session=s`, `_csrf=${token}`);
+  assert.equal(out.status, 303);
+  assert.equal(out.headers.get("location"), logoutUrl);
+  assert.match(out.headers.getSetCookie().join("\n"), /plainpages_jwt=;.*Max-Age=0/);
+
+  // No active Kratos session → clear our cookie and land on /login ourselves.
+  const none = await post(`${CSRF_COOKIE}=${token}`, `_csrf=${token}`);
+  assert.equal(none.status, 303);
+  assert.equal(none.headers.get("location"), "/login");
+  assert.match(none.headers.getSetCookie().join("\n"), /plainpages_jwt=;.*Max-Age=0/);
+
+  // Missing field and a forged token are both refused (no Kratos call, no cookie cleared).
+  assert.equal((await post(`${CSRF_COOKIE}=${token}`, "")).status, 403);
+  assert.equal((await post(`${CSRF_COOKIE}=${token}`, "_csrf=forged.sig")).status, 403);
+  assert.equal((await post("", `_csrf=${token}`)).status, 403); // no cookie to match
+});
+
+
+const oauthSession = (): Session => ({ active: true, identity: { id: OAUTH_SUBJECT, traits: { email: "ada@x.io" } } });
+
+test("OAuth2 login challenge (/oauth2/login): a Kratos session accepts via Hydra; no session bounces to /login; missing challenge → 400", async (t) => {
+  const identity = { id: "01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b55" };
+  let acceptedSubject: string | undefined;
+  const hydra = stubHydra({ acceptLoginRequest: async (_c, b) => { acceptedSubject = b.subject; return { redirect: "http://127.0.0.1:4444/oauth2/auth?login_verifier=v" }; } });
+
+  const signedIn = createApp({ hydra, kratos: withWhoami(async () => ({ active: true, identity }) as Session) });
+  await new Promise<void>((r) => signedIn.listen(0, r));
+  t.after(() => signedIn.close());
+  const base = `http://localhost:${(signedIn.address() as AddressInfo).port}`;
+
+  // Signed in: accept the challenge with the Kratos identity → 303 to Hydra's resume URL.
+  const accept = await fetch(base + "/oauth2/login?login_challenge=chal1", { headers: { cookie: "plainpages_session=s" }, redirect: "manual" });
+  assert.equal(accept.status, 303);
+  assert.match(accept.headers.get("location") ?? "", /\/oauth2\/auth\?login_verifier=v/);
+  assert.equal(acceptedSubject, identity.id);
+
+  // Missing login_challenge → 400 (someone hit the endpoint directly).
+  assert.equal((await fetch(base + "/oauth2/login", { redirect: "manual" })).status, 400);
+
+  // Not signed in: bounce to the themed login, return_to carrying an absolute URL back to here.
+  const anon = createApp({ hydra: stubHydra(), kratos: withWhoami(async () => null) });
+  await new Promise<void>((r) => anon.listen(0, r));
+  t.after(() => anon.close());
+  const bounce = await fetch(`http://localhost:${(anon.address() as AddressInfo).port}/oauth2/login?login_challenge=chal1`, { redirect: "manual" });
+  assert.equal(bounce.status, 303);
+  const loc = bounce.headers.get("location") ?? "";
+  assert.match(loc, /^\/login\?return_to=/);
+  assert.match(decodeURIComponent(loc.split("return_to=")[1]!), /^http:\/\/[^/]+\/oauth2\/login\?login_challenge=chal1$/);
+});
+
+test("OAuth2 consent challenge (/oauth2/consent): skip auto-accepts; a third-party shows the screen; allow/deny POST; CSRF-guarded; missing challenge", async (t) => {
+  const csrfSecret = "consent-secret";
+  let granted: { grant_scope?: string[]; session?: unknown } | undefined;
+  const hydra = stubHydra({
+    acceptConsentRequest: async (_c, b) => { granted = b; return { redirect: "http://127.0.0.1:4444/oauth2/auth?consent_verifier=v" }; },
+    rejectConsentRequest: async () => ({ redirect: "http://acme.example/cb?error=access_denied" }),
+  });
+  const app = createApp({ csrfSecret, hydra, kratos: withWhoami(async () => oauthSession()) });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const base = `http://localhost:${(app.address() as AddressInfo).port}`;
+  const token = issueCsrfToken(csrfSecret);
+  const post = (body: string) =>
+    fetch(base + "/oauth2/consent", { body, headers: { "content-type": "application/x-www-form-urlencoded", cookie: `${CSRF_COOKIE}=${token}` }, method: "POST", redirect: "manual" });
+
+  // Third-party (default stub: not first-party, not skipped) → 200 consent screen listing the
+  // client + scopes, with a CSRF cookie its form echoes back; posts to our own /oauth2/consent.
+  const page = await fetch(base + "/oauth2/consent?consent_challenge=cons1", { redirect: "manual" });
+  assert.equal(page.status, 200);
+  const html = await page.text();
+  assert.match(html, /Authorize Acme Reports/);
+  assert.match(html, /openid/);
+  assert.match(html, /profile/);
+  assert.match(html, /action="\/oauth2\/consent"/);
+  // Informed consent: the screen names the account being authorized + offers a sign-out escape.
+  assert.match(html, /Signed in as.*ada@x\.io/s);
+  assert.match(html, /action="\/logout".*Sign out/s);
+  assert.match(page.headers.get("set-cookie") ?? "", /plainpages_csrf=/);
+
+  // Allow → 303 to Hydra, granting the scopes re-read from the challenge (never form-supplied) +
+  // id_token claims from the Kratos identity.
+  const allow = await post(`_csrf=${token}&consent_challenge=cons1&decision=allow`);
+  assert.equal(allow.status, 303);
+  assert.match(allow.headers.get("location") ?? "", /\/oauth2\/auth\?consent_verifier=v/);
+  assert.deepEqual(granted?.grant_scope, ["openid", "profile"]);
+  assert.deepEqual(granted?.session, { id_token: { email: "ada@x.io" } });
+
+  // Deny → 303 back to the client with access_denied.
+  const deny = await post(`_csrf=${token}&consent_challenge=cons1&decision=deny`);
+  assert.equal(deny.status, 303);
+  assert.equal(deny.headers.get("location"), "http://acme.example/cb?error=access_denied");
+
+  // Forged/missing CSRF → 403 (no Hydra call); missing challenge → 400.
+  assert.equal((await post("decision=allow")).status, 403);
+  assert.equal((await fetch(base + "/oauth2/consent", { redirect: "manual" })).status, 400);
+
+  // A Hydra-skipped client auto-accepts on GET (no screen) → 303 to Hydra.
+  const skip = createApp({ hydra: stubHydra({ getConsentRequest: async () => ({ challenge: "cons1", requested_scope: ["openid"], skip: true, subject: OAUTH_SUBJECT }) }), kratos: withWhoami(async () => oauthSession()) });
+  await new Promise<void>((r) => skip.listen(0, r));
+  t.after(() => skip.close());
+  const auto = await fetch(`http://localhost:${(skip.address() as AddressInfo).port}/oauth2/consent?consent_challenge=cons1`, { redirect: "manual" });
+  assert.equal(auto.status, 303);
+  assert.match(auto.headers.get("location") ?? "", /consent_verifier=v/);
+});
+
+test("OAuth2 RP-initiated logout (/oauth2/logout): accepts the logout challenge → 303 to Hydra; missing → 400", async (t) => {
+  let acceptedChallenge: string | undefined;
+  const hydra = stubHydra({ acceptLogoutRequest: async (c) => { acceptedChallenge = c; return { redirect: "http://acme.example/post-logout" }; } });
+  const app = createApp({ hydra, kratos: withWhoami(async () => null) });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const base = `http://localhost:${(app.address() as AddressInfo).port}`;
+
+  const ok = await fetch(base + "/oauth2/logout?logout_challenge=lc1", { redirect: "manual" });
+  assert.equal(ok.status, 303);
+  assert.equal(ok.headers.get("location"), "http://acme.example/post-logout");
+  assert.equal(acceptedChallenge, "lc1");
+
+  assert.equal((await fetch(base + "/oauth2/logout", { redirect: "manual" })).status, 400);
+});
+
+// All three OAuth2 challenge endpoints share one degrade contract (the documented "byte-identical"
+// behaviour): a stale/consumed challenge (Hydra 4xx — back button, slow login) → recoverable 400,
+// a genuine Hydra outage (5xx) → 500.
+test("OAuth2 challenge endpoints degrade identically: stale Hydra 4xx → 400, outage 5xx → 500", async (t) => {
+  const endpoints: { make: (status: number) => Partial<HydraAdmin>; path: string }[] = [
+    { make: (s) => ({ getLoginRequest: async () => { throw new HydraError("x", s, ""); } }), path: "/oauth2/login?login_challenge=x" },
+    { make: (s) => ({ getConsentRequest: async () => { throw new HydraError("x", s, ""); } }), path: "/oauth2/consent?consent_challenge=x" },
+    { make: (s) => ({ acceptLogoutRequest: async () => { throw new HydraError("x", s, ""); } }), path: "/oauth2/logout?logout_challenge=x" },
+  ];
+  for (const { make, path } of endpoints) {
+    for (const [status, expected] of [[410, 400], [503, 500]] as const) {
+      const app = createApp({ hydra: stubHydra(make(status)), kratos: withWhoami(async () => null) });
+      await new Promise<void>((r) => app.listen(0, r));
+      t.after(() => app.close());
+      const res = await fetch(`http://localhost:${(app.address() as AddressInfo).port}${path}`, { redirect: "manual" });
+      assert.equal(res.status, expected, `${path} ${status} → ${expected}`);
+    }
+  }
+});
+

src/http/app-harness.ts

@@ -0,0 +1,85 @@
+import { generateKeyPairSync, sign, type JsonWebKey } from "node:crypto";
+import type { AddressInfo } from "node:net";
+import type { TestContext } from "node:test";
+import { createApp } from "./app.ts";
+import type { HydraAdmin } from "../auth/hydra-admin.ts";
+import type { KetoClient, RelationTuple, SubjectSet } from "../auth/keto-client.ts";
+import type { KratosAdmin } from "../auth/kratos-admin.ts";
+import type { FlowType, KratosPublic } from "../auth/kratos-public.ts";
+import { SESSION_COOKIE } from "../auth/login.ts";
+import type { Plugin } from "../plugin-host/plugin.ts";
+
+// A session JWT signed with a throwaway test key; `staticJwks([ecJwk])` is the matching verify side.
+const ec = generateKeyPairSync("ec", { namedCurve: "P-256" });
+export const ecJwk: JsonWebKey = { ...(ec.publicKey.export({ format: "jwk" }) as JsonWebKey), alg: "ES256", kid: "test-kid" };
+const b64url = (i: Buffer | string): string => Buffer.from(i).toString("base64url");
+export function mintJwt(payload: Record<string, unknown>): string {
+  const input = `${b64url(JSON.stringify({ alg: "ES256", kid: "test-kid", typ: "JWT" }))}.${b64url(JSON.stringify(payload))}`;
+  return `${input}.${b64url(sign("SHA256", Buffer.from(input), { dsaEncoding: "ieee-p1363", key: ec.privateKey }))}`;
+}
+// A session cookie carrying `permissions`, valid for 10 min — the auth most tests need to reach a gated page.
+export const session = (permissions: string[] = []): string =>
+  `${SESSION_COOKIE}=${mintJwt({ email: "a@b.c", exp: Math.floor(Date.now() / 1000) + 600, permissions, sub: "u1" })}`;
+
+export async function startApp(t: TestContext, plugins: Plugin[], pluginsDir?: string): Promise<string> {
+  const app = createApp(pluginsDir ? { plugins, pluginsDir } : { plugins });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  return `http://localhost:${(app.address() as AddressInfo).port}`;
+}
+
+export function mockKratos(getFlow: KratosPublic["getFlow"]): KratosPublic {
+  return {
+    createLogoutFlow: async () => null,
+    getFlow,
+    initBrowserFlow: async (_t: FlowType) => ({ flow: { id: "new1", ui: { action: "", method: "post", nodes: [] } }, setCookie: ["csrf_token=abc; Path=/; HttpOnly"] }),
+    submitFlow: async () => { throw new Error("unused"); },
+    whoami: async () => null,
+  };
+}
+
+export const stubAdmin = (over: Partial<KratosAdmin>): KratosAdmin => ({
+  createIdentity: async () => { throw new Error("unused"); },
+  createRecoveryCode: async () => ({ code: "000000", link: "http://kratos/recover" }),
+  deleteIdentity: async () => {},
+  getIdentity: async () => null,
+  listIdentities: async () => ({ identities: [], nextPageToken: null }),
+  updateIdentity: async () => { throw new Error("unused"); },
+  updateMetadataPublic: async () => ({ id: "x" }),
+  ...over,
+});
+const sameSet = (a?: SubjectSet, b?: SubjectSet): boolean =>
+  (!a && !b) || (!!a && !!b && a.namespace === b.namespace && a.object === b.object && a.relation === b.relation);
+export const matchesTuple = (t: RelationTuple, f: Partial<RelationTuple>): boolean =>
+  (f.namespace === undefined || t.namespace === f.namespace) &&
+  (f.object === undefined || t.object === f.object) &&
+  (f.relation === undefined || t.relation === f.relation) &&
+  (f.subject_id === undefined || t.subject_id === f.subject_id) &&
+  (f.subject_set === undefined || sameSet(t.subject_set, f.subject_set));
+// A stateful in-memory KetoClient over a tuple array (writes mutate it); used by login + the admin screens.
+export const fakeKeto = (tuples: RelationTuple[] = [], over: Partial<KetoClient> = {}): KetoClient => ({
+  check: async () => false,
+  deleteTuple: async (f) => { for (let i = tuples.length - 1; i >= 0; i--) if (matchesTuple(tuples[i]!, f)) tuples.splice(i, 1); },
+  expand: async () => ({ type: "leaf" }),
+  listRelations: async (q = {}) => ({ nextPageToken: null, tuples: tuples.filter((t) => matchesTuple(t, q)) }),
+  writeTuple: async (tp) => { if (!tuples.some((t) => matchesTuple(t, tp) && sameSet(t.subject_set, tp.subject_set))) tuples.push(tp); },
+  ...over,
+});
+export const withWhoami = (whoami: KratosPublic["whoami"]): KratosPublic => ({ ...mockKratos(async () => { throw new Error("unused"); }), whoami });
+
+// OAuth2 login challenge: another app logs in *through* us; Hydra hands the browser here.
+export const stubHydra = (over: Partial<HydraAdmin> = {}): HydraAdmin => ({
+  acceptConsentRequest: async () => ({ redirect: "http://127.0.0.1:4444/oauth2/auth?consent_verifier=v" }),
+  acceptLoginRequest: async () => ({ redirect: "http://127.0.0.1:4444/oauth2/auth?login_verifier=v" }),
+  acceptLogoutRequest: async () => ({ redirect: "http://acme.example/post-logout" }),
+  createClient: async (c) => ({ ...c, client_id: "c1", client_secret: "s3cr3t" }),
+  deleteClient: async () => {},
+  getClient: async () => null,
+  getConsentRequest: async () => ({ challenge: "cons1", client: { client_name: "Acme Reports" }, requested_scope: ["openid", "profile"], skip: false, subject: OAUTH_SUBJECT }),
+  getLoginRequest: async () => ({ challenge: "chal1", skip: false, subject: "" }),
+  listClients: async () => ({ clients: [], nextPageToken: null }),
+  rejectConsentRequest: async () => ({ redirect: "http://acme.example/cb?error=access_denied" }),
+  rejectLoginRequest: async () => { throw new Error("unused"); },
+  ...over,
+});
+export const OAUTH_SUBJECT = "01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b55";

src/http/app-i18n.test.ts

@@ -0,0 +1,147 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test, type TestContext } from "node:test";
+import { createApp } from "./app.ts";
+import { staticJwks } from "../auth/jwks.ts";
+import { SESSION_COOKIE } from "../auth/login.ts";
+import type { Plugin } from "../plugin-host/plugin.ts";
+import { createI18n } from "../i18n/runtime.ts";
+import type { MenuConfig } from "../ui/menu-config.ts";
+import { loadI18n } from "../i18n/load.ts";
+import { ecJwk, mintJwt } from "./app-harness.ts";
+
+// ---- language (i18n) ----
+
+// The installed catalogs, as server.ts wires them: the shipped core locales (en-US + sv-SE).
+async function localeApp(t: TestContext): Promise<string> {
+  const app = createApp({ i18n: createI18n(await loadI18n()), jwks: staticJwks([ecJwk]) });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  return `http://localhost:${(app.address() as AddressInfo).port}`;
+}
+
+test("?locale serves that language and carries the choice onto the links the page renders", async (t) => {
+  const url = await localeApp(t);
+  const html = await (await fetch(`${url}/?locale=sv-SE`)).text();
+
+  assert.match(html, /<html lang="sv-SE" dir="ltr">/); // the document says what language it is in
+  assert.match(html, /Logga in/); // the landing page's own words
+  assert.doesNotMatch(html, /Operational web apps/);
+  // The chosen locale rides along, so clicking through the app stays in Swedish without a cookie.
+  assert.match(html, /href="\/login\?locale=sv-SE"/);
+  // …and the picker offers the other installed locale, pointing at this same page.
+  assert.match(html, /hreflang="en-US"/);
+  assert.match(html, /href="\/\?locale=en-US"/);
+});
+
+test("Accept-Language decides when the URL doesn't, and a lone language matches its region", async (t) => {
+  const url = await localeApp(t);
+  const swedish = await (await fetch(`${url}/`, { headers: { "accept-language": "sv;q=0.9, en;q=0.4" } })).text();
+  assert.match(swedish, /<html lang="sv-SE"/);
+  // The visitor never asked for a locale in the URL, so the links stay clean.
+  assert.match(swedish, /href="\/login"/);
+
+  const english = await (await fetch(`${url}/`, { headers: { "accept-language": "de-DE" } })).text();
+  assert.match(english, /<html lang="en-US"/); // nothing matches ⇒ the baseline
+});
+
+test("an uninstalled or malformed ?locale falls back instead of failing", async (t) => {
+  const url = await localeApp(t);
+  for (const bad of ["sv-FI", "klingon", "../../etc"]) {
+    const res = await fetch(`${url}/?locale=${encodeURIComponent(bad)}`);
+    assert.equal(res.status, 200);
+    assert.match(await res.text(), /<html lang="en-US"/, `expected en-US for ${bad}`);
+  }
+});
+
+test("a redirect the host emits keeps the visitor's language", async (t) => {
+  const url = await localeApp(t);
+  const res = await fetch(`${url}/dashboard?locale=sv-SE`, { redirect: "manual" }); // anonymous ⇒ sign in first
+  assert.equal(res.status, 303);
+  const location = res.headers.get("location") ?? "";
+  assert.match(location, /^\/login\?/);
+  assert.match(location, /locale=sv-SE/);
+});
+
+test("the error pages speak the visitor's language too", async (t) => {
+  const url = await localeApp(t);
+  const html = await (await fetch(`${url}/no-such-page?locale=sv-SE`)).text();
+  assert.match(html, /<html lang="sv-SE"/);
+  assert.match(html, /Sidan hittades inte/);
+});
+
+test("a plugin that owns a landing page, or short-circuits a hook, translates from its own catalog", async (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "pp-i18n-plugin-"));
+  mkdirSync(join(dir, "demo", "i18n"), { recursive: true });
+  t.after(() => rmSync(dir, { force: true, recursive: true }));
+  writeFileSync(join(dir, "demo", "i18n", "en-US.ts"), 'const m = { "demo.hello": "Hello from the plugin" };\nexport default m;\n');
+
+  // Every plugin-owned render path: the public landing, the gated dashboard, and a hook short-circuit.
+  const demo: Plugin = {
+    apiVersion: "1.0.0",
+    dashboard: (ctx) => ({ html: ctx.t("demo.hello") }),
+    home: (ctx) => ({ html: ctx.t("demo.hello") }),
+    hooks: { onRequest: (ctx) => (ctx.url.pathname === "/hooked" ? { html: ctx.t("demo.hello") } : undefined) },
+    id: "demo",
+  };
+  const i18n = createI18n(await loadI18n({ pluginIds: ["demo"], pluginsDir: dir }));
+  const app = createApp({ i18n, jwks: staticJwks([ecJwk]), plugins: [demo], pluginsDir: dir });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+  const nowSec = Math.floor(Date.now() / 1000);
+  const cookie = `${SESSION_COOKIE}=${mintJwt({ email: "a@b", exp: nowSec + 600, permissions: [], sub: "u1" })}`;
+
+  assert.equal(await (await fetch(`${url}/`)).text(), "Hello from the plugin");
+  assert.equal(await (await fetch(`${url}/hooked`)).text(), "Hello from the plugin");
+  assert.equal(await (await fetch(`${url}/dashboard`, { headers: { cookie } })).text(), "Hello from the plugin");
+});
+
+test("an error page renders without composing the menu — it exists for when the shell's data is what failed", async (t) => {
+  // The chrome getter is lazy on purpose; a render that reads no chrome must not trigger it, or a
+  // broken menu takes the error pages down with it.
+  let built = 0;
+  const menu: MenuConfig = { branding: { get name() { built++; return "Plainpages"; } }, override: {} };
+  const app = createApp({ jwks: staticJwks([ecJwk]), menu });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+
+  const res = await fetch(`${url}/no-such-page`);
+  assert.equal(res.status, 404);
+  assert.match(await res.text(), /Page not found/);
+  assert.equal(built, 0);
+});
+
+test("a POST-rendered page still offers the language picker, pointed at a page that answers GET", async (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "pp-post-lang-"));
+  mkdirSync(join(dir, "demo", "views"), { recursive: true });
+  t.after(() => rmSync(dir, { force: true, recursive: true }));
+  // The view renders the picker exactly as the shell does.
+  writeFileSync(join(dir, "demo", "views", "page.ejs"), `<%- include("partials/locale-switch") %>`);
+  const demo: Plugin = {
+    apiVersion: "1.0.0",
+    id: "demo",
+    routes: [
+      { handler: () => ({ view: "page" }), method: "GET", path: "/thing" },
+      { handler: () => ({ view: "page" }), method: "POST", path: "/thing" },
+      { handler: () => ({ view: "page" }), method: "POST", path: "/thing/act" }, // POST-only: no GET sibling
+    ],
+  };
+  const app = createApp({ i18n: createI18n(await loadI18n()), plugins: [demo], pluginsDir: dir });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+  const post = (path: string, headers: Record<string, string> = {}) => fetch(url + path, { headers, method: "POST" });
+
+  // A POST whose path also answers GET → the picker points at that page.
+  assert.match(await (await post("/demo/thing?locale=sv-SE")).text(), /href="\/demo\/thing\?locale=en-US"/);
+  // A POST-only path → the page the form was submitted from, so the link can't dead-end on a 405.
+  const fromForm = await post("/demo/thing/act?locale=sv-SE", { referer: `${url}/demo/thing?locale=sv-SE` });
+  assert.match(await fromForm.text(), /href="\/demo\/thing\?locale=en-US"/);
+  // …and with no referer to fall back on, the front page.
+  assert.match(await (await post("/demo/thing/act?locale=sv-SE")).text(), /href="\/\?locale=en-US"/);
+});

src/http/app-plugins.test.ts

@@ -0,0 +1,303 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { createApp } from "./app.ts";
+import { readFormBody } from "./body.ts";
+import { createDenylist } from "../auth/denylist.ts";
+import { CSRF_COOKIE, issueCsrfToken } from "../auth/csrf.ts";
+import { can, check, GuardError, requireSession } from "../auth/guards.ts";
+import { staticJwks } from "../auth/jwks.ts";
+import type { Identity } from "../auth/kratos-admin.ts";
+import { KratosError, type Session } from "../auth/kratos-public.ts";
+import { SESSION_COOKIE } from "../auth/login.ts";
+import type { Plugin } from "../plugin-host/plugin.ts";
+import { ecJwk, fakeKeto, mintJwt, startApp, stubAdmin, withWhoami } from "./app-harness.ts";
+
+// A test plugin exercising each RouteResult shape, a path param, and the permission gate.
+const demoPlugin: Plugin = {
+  apiVersion: "1.0.0",
+  id: "demo",
+  routes: [
+    { handler: (ctx) => ({ html: `<p>Hi ${ctx.params.name}</p>` }), method: "GET", path: "/hello/:name" },
+    { handler: () => ({ json: { ok: true } }), method: "GET", path: "/data" },
+    { handler: () => ({ redirect: "/demo/hello/world" }), method: "POST", path: "/go" },
+    { handler: () => ({ html: "secret" }), method: "GET", path: "/secret", permission: "demo:read" },
+    { handler: () => ({ html: "open to all" }), method: "GET", path: "/public-page", public: true }, // blessed public
+    { handler: () => ({ data: { who: "Plainpages" }, view: "page" }), method: "GET", path: "/page" },
+  ],
+};
+
+test("mounts plugin routes: params, html/json/redirect/view results, and the permission gate", async (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "pp-plugins-"));
+  mkdirSync(join(dir, "demo", "views"), { recursive: true });
+  mkdirSync(join(dir, "demo", "public"), { recursive: true });
+  // The view also include()s a core building-block partial, proving plugin views reuse them.
+  writeFileSync(join(dir, "demo", "views", "page.ejs"), `<h1>Hello <%= who %></h1><%- include("partials/theme-switch") %>`);
+  writeFileSync(join(dir, "demo", "public", "app.css"), ".demo{color:red}");
+  t.after(() => rmSync(dir, { force: true, recursive: true }));
+  const url = await startApp(t, [demoPlugin], dir);
+
+  // Path param + html
+  const hi = await fetch(url + "/demo/hello/world");
+  assert.equal(hi.status, 200);
+  assert.match(await hi.text(), /Hi world/);
+
+  // json
+  const data = await fetch(url + "/demo/data");
+  assert.match(data.headers.get("content-type") ?? "", /application\/json/);
+  assert.deepEqual(await data.json(), { ok: true });
+
+  // redirect (POST → 303 Location)
+  const go = await fetch(url + "/demo/go", { method: "POST", redirect: "manual" });
+  assert.equal(go.status, 303);
+  assert.equal(go.headers.get("location"), "/demo/hello/world");
+
+  // view rendered from the plugin's own views/, including a core partial
+  const page = await (await fetch(url + "/demo/page")).text();
+  assert.match(page, /Hello Plainpages/);
+  assert.match(page, /role="radiogroup"/); // core partials/theme-switch resolved
+
+  // static asset served from the plugin's own public/ at /public/<id>/
+  const css = await fetch(url + "/public/demo/app.css");
+  assert.equal(css.status, 200);
+  assert.match(css.headers.get("content-type") ?? "", /text\/css/);
+  assert.match(await css.text(), /\.demo/);
+  assert.equal((await fetch(url + "/public/demo/..%2f..%2fplugin.ts")).status, 403); // traversal still blocked
+
+  // gated route, anonymous → redirect to sign in (like the built-in screens), not a dead-end 403;
+  // the requested page is preserved as return_to so login lands the user back there.
+  const denied = await fetch(url + "/demo/secret", { redirect: "manual" });
+  assert.equal(denied.status, 303);
+  assert.equal(denied.headers.get("location"), "/login?return_to=%2Fdemo%2Fsecret");
+
+  // a route marked public is reachable anonymously — no gate, no redirect.
+  const open = await fetch(url + "/demo/public-page", { redirect: "manual" });
+  assert.equal(open.status, 200);
+  assert.match(await open.text(), /open to all/);
+
+  // known path + wrong method → 405 with Allow; unknown path → 404
+  const wrong = await fetch(url + "/demo/data", { method: "DELETE" });
+  assert.equal(wrong.status, 405);
+  assert.match(wrong.headers.get("allow") ?? "", /GET/);
+  assert.equal((await fetch(url + "/demo/nope")).status, 404);
+});
+
+test("a plugin view renders the native chrome; its forms are CSRF-guarded via ctx.verifyCsrf", async (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "pp-plugins-"));
+  mkdirSync(join(dir, "panelkit", "views"), { recursive: true });
+  // The view composes the core shell from ctx.chrome — branding, the global nav — and its own
+  // CSRF-guarded form carrying chrome.csrfToken (the representative way a plugin form gets the token,
+  // independent of the shell's auth-dependent profile/sign-out block).
+  writeFileSync(join(dir, "panelkit", "views", "panel.ejs"),
+    `<%- include("partials/shell", { body: '<form method="post" action="/panelkit/save"><input type="hidden" name="_csrf" value="' + chrome.csrfToken + '" /></form>', brand: chrome.brand, csrfToken: chrome.csrfToken, nav: include("partials/nav-tree", { nodes: chrome.nav }), title, user: chrome.user }) %>`);
+  t.after(() => rmSync(dir, { force: true, recursive: true }));
+
+  const plugin: Plugin = {
+    apiVersion: "1.0.0",
+    id: "panelkit",
+    nav: [{ href: "/panelkit/panel", icon: "i-grid", id: "panelkit", label: "Panel kit" }],
+    routes: [
+      { handler: (ctx) => ({ data: { chrome: ctx.chrome, title: "Panel" }, view: "panel" }), method: "GET", path: "/panel" },
+      {
+        handler: async (ctx) => {
+          const form = await readFormBody(ctx.req);
+          if (!ctx.verifyCsrf(form.get("_csrf"))) throw new GuardError(403, "bad csrf");
+          return { redirect: "/panelkit/panel" };
+        },
+        method: "POST", path: "/save",
+      },
+    ],
+  };
+
+  const secret = "test-csrf-secret";
+  const app = createApp({ csrfSecret: secret, plugins: [plugin], pluginsDir: dir });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+
+  // GET renders the shell: branding (DEFAULT_MENU), the (ungated) plugin nav, and a CSRF cookie
+  // whose token is embedded in the plugin's own form (double-submit).
+  const res = await fetch(url + "/panelkit/panel");
+  assert.equal(res.status, 200);
+  const body = await res.text();
+  assert.match(body, /class="brand-name">Plainpages/);
+  assert.match(body, /Panel kit/);
+  const cookieTok = /plainpages_csrf=([^;]+)/.exec(res.headers.get("set-cookie") ?? "")?.[1];
+  assert.ok(cookieTok, "a plugin route issues the CSRF cookie when fresh");
+  assert.equal(/name="_csrf" value="([^"]+)"/.exec(body)?.[1], cookieTok);
+
+  // POST with no token → 403 (ctx.verifyCsrf fails closed); matching cookie + field → 303.
+  assert.equal((await fetch(url + "/panelkit/save", { method: "POST", redirect: "manual" })).status, 403);
+  const tok = issueCsrfToken(secret);
+  const ok = await fetch(url + "/panelkit/save", {
+    body: `_csrf=${encodeURIComponent(tok)}`,
+    headers: { "content-type": "application/x-www-form-urlencoded", cookie: `${CSRF_COOKIE}=${tok}` },
+    method: "POST", redirect: "manual",
+  });
+  assert.equal(ok.status, 303);
+});
+
+// JWT middleware: a verified session cookie populates ctx.user/permissions, which the gate reads.
+test("a verified session JWT authorizes a permission-gated route; no cookie / expired token → sign in", async (t) => {
+  const app = createApp({ jwks: staticJwks([ecJwk]), plugins: [demoPlugin] });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+  const nowSec = Math.floor(Date.now() / 1000);
+  const secret = (cookie?: string) => fetch(url + "/demo/secret", { redirect: "manual", ...(cookie ? { headers: { cookie } } : {}) });
+
+  // Token carrying the gating permission → the handler runs (200).
+  const ok = await secret(`${SESSION_COOKIE}=${mintJwt({ email: "a@b.c", exp: nowSec + 600, permissions: ["demo:read"], sub: "u1" })}`);
+  assert.equal(ok.status, 200);
+  assert.equal(await ok.text(), "secret");
+
+  // No cookie and an expired token both render anonymous → the gate bounces to sign in (303 → /login,
+  // remembering the gated page as return_to).
+  const noCookie = await secret();
+  assert.equal(noCookie.status, 303);
+  assert.equal(noCookie.headers.get("location"), "/login?return_to=%2Fdemo%2Fsecret");
+  assert.equal((await secret(`${SESSION_COOKIE}=${mintJwt({ email: "a@b.c", exp: nowSec - 600, permissions: ["demo:read"], sub: "u1" })}`)).status, 303);
+
+  // The gated dashboard renders for any signed-in user; anonymous is bounced to sign in before any
+  // page renders (gate on /dashboard). The Admin section links come from the admin plugin — its nav
+  // composition + permission-filtering is covered in the admin-screen tests below.
+  const dash = await fetch(url + "/dashboard", { headers: { cookie: `${SESSION_COOKIE}=${mintJwt({ email: "a@b.c", exp: nowSec + 600, permissions: ["admin"], sub: "u1" })}` } });
+  assert.equal(dash.status, 200);
+  const anonDash = await fetch(url + "/dashboard", { redirect: "manual" });
+  assert.equal(anonDash.status, 303);
+  assert.equal(anonDash.headers.get("location"), "/login?return_to=%2Fdashboard");
+});
+
+test("revocation denylist: a revoked subject's token stops authorizing on the hot path; a fresh re-login passes", async (t) => {
+  const denylist = createDenylist(); // no Ory clients ⇒ a revoked token drops straight to anonymous (no re-mint)
+  const app = createApp({ denylist, jwks: staticJwks([ecJwk]), plugins: [demoPlugin] });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+  const nowSec = Math.floor(Date.now() / 1000);
+  const secret = (iat: number) => fetch(url + "/demo/secret", { redirect: "manual", headers: { cookie: `${SESSION_COOKIE}=${mintJwt({ email: "a@b.c", exp: nowSec + 600, iat, permissions: ["demo:read"], sub: "u1" })}` } });
+
+  assert.equal((await secret(nowSec)).status, 200); // before any revoke, the token authorizes
+
+  denylist.revoke("u1");
+  assert.equal((await secret(nowSec - 5)).status, 303); // the pre-revoke token now bounces to /login
+  assert.equal((await secret(nowSec + 5)).status, 200); // a fresh re-login (iat after the revoke) still works
+});
+
+test("session re-mint: an expired JWT backed by a live Kratos session is silently re-minted; a dead session clears it", async (t) => {
+  const identity: Identity = { id: "u1", traits: { email: "a@b.c" } };
+  const nowSec = Math.floor(Date.now() / 1000);
+  const freshJwt = mintJwt({ email: "a@b.c", exp: nowSec + 600, permissions: ["demo:read"], sub: "u1" });
+  const live = withWhoami(async (o) => (o?.tokenizeAs ? { active: true, identity, tokenized: freshJwt } : { active: true, identity }) as Session);
+  const keto = fakeKeto([], { check: async () => true, listRelations: async () => ({ nextPageToken: null, tuples: [{ namespace: "Permission", object: "demo:read", relation: "granted", subject_id: "user:u1" }] }) });
+  const expired = `${SESSION_COOKIE}=${mintJwt({ email: "a@b.c", exp: nowSec - 600, permissions: ["demo:read"], sub: "u1" })}; plainpages_session=s`;
+
+  // Live Kratos session: the lapsed token is re-minted — the gated route runs AND a fresh cookie rides the response.
+  const app = createApp({ jwks: staticJwks([ecJwk]), keto, kratos: live, kratosAdmin: stubAdmin({}), plugins: [demoPlugin] });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const ok = await fetch(`http://localhost:${(app.address() as AddressInfo).port}/demo/secret`, { headers: { cookie: expired } });
+  assert.equal(ok.status, 200);
+  assert.equal(await ok.text(), "secret");
+  assert.match(ok.headers.get("set-cookie") ?? "", /^plainpages_jwt=/);
+
+  // Kratos session gone: no re-mint, the stale cookie is cleared, the now-anonymous request bounces to sign in.
+  const dead = createApp({ jwks: staticJwks([ecJwk]), keto, kratos: withWhoami(async () => null), kratosAdmin: stubAdmin({}), plugins: [demoPlugin] });
+  await new Promise<void>((r) => dead.listen(0, r));
+  t.after(() => dead.close());
+  const denied = await fetch(`http://localhost:${(dead.address() as AddressInfo).port}/demo/secret`, { headers: { cookie: expired }, redirect: "manual" });
+  assert.equal(denied.status, 303);
+  assert.equal(denied.headers.get("location"), "/login?return_to=%2Fdemo%2Fsecret");
+  assert.match(denied.headers.get("set-cookie") ?? "", /^plainpages_jwt=;.*Max-Age=0/);
+
+  // Ory unreachable (not a dead session): whoami throws → degrade to anonymous (bounce to /login, not 500),
+  // and leave the cookie untouched so the token can re-mint once Ory recovers.
+  const down = createApp({ jwks: staticJwks([ecJwk]), keto, kratos: withWhoami(async () => { throw new KratosError("kratos down", 503, ""); }), kratosAdmin: stubAdmin({}), plugins: [demoPlugin] });
+  await new Promise<void>((r) => down.listen(0, r));
+  t.after(() => down.close());
+  const outage = await fetch(`http://localhost:${(down.address() as AddressInfo).port}/demo/secret`, { headers: { cookie: expired }, redirect: "manual" });
+  assert.equal(outage.status, 303);
+  assert.equal(outage.headers.get("location"), "/login?return_to=%2Fdemo%2Fsecret");
+  assert.equal(outage.headers.get("set-cookie"), null);
+});
+
+test("guards map to responses: requireSession → /login, a failed can/check → 403, success runs the handler", async (t) => {
+  const keto = { check: async (tuple: { object: string }) => tuple.object === "open" } as unknown as Parameters<typeof check>[0];
+  const guarded: Plugin = {
+    apiVersion: "1.0.0",
+    id: "guarded",
+    routes: [
+      { handler: (ctx) => ({ html: `hi ${requireSession(ctx).email}` }), method: "GET", path: "/me" },
+      { handler: (ctx) => { if (!can(ctx, "admin")) throw new GuardError(403, "no"); return { html: "ok" }; }, method: "GET", path: "/admin-only" },
+      { handler: async (ctx) => { if (!(await check(keto, ctx, { namespace: "Resource", object: ctx.params.id ?? "", relation: "view" }))) throw new GuardError(403, "no"); return { html: "seen" }; }, method: "GET", path: "/doc/:id" },
+      { handler: () => ({ html: "gated" }), method: "GET", path: "/gated", permission: "secret:read" }, // declarative route gate
+      { handler: () => ({ html: "mine" }), method: "GET", path: "/mine", session: true }, // declarative session gate
+    ],
+  };
+  const app = createApp({ jwks: staticJwks([ecJwk]), plugins: [guarded] });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+  const nowSec = Math.floor(Date.now() / 1000);
+  const auth = (permissions: string[]) => ({ headers: { cookie: `${SESSION_COOKIE}=${mintJwt({ email: "a@b.c", exp: nowSec + 600, permissions, sub: "u1" })}` } });
+
+  // requireSession: anonymous bounces to /login (remembering the page); a signed-in user reaches the handler.
+  const anon = await fetch(url + "/guarded/me", { redirect: "manual" });
+  assert.equal(anon.status, 303);
+  assert.equal(anon.headers.get("location"), "/login?return_to=%2Fguarded%2Fme");
+  const me = await fetch(url + "/guarded/me", auth([]));
+  assert.equal(me.status, 200);
+  assert.match(await me.text(), /hi a@b\.c/);
+
+  // can: signed-in but lacking the permission → 403 page; carrying it → 200.
+  assert.equal((await fetch(url + "/guarded/admin-only", auth([]))).status, 403);
+  assert.equal((await fetch(url + "/guarded/admin-only", auth(["admin"]))).status, 200);
+
+  // check (live Keto): the keto verdict gates the handler.
+  assert.equal((await fetch(url + "/guarded/doc/open", auth([]))).status, 200);
+  assert.equal((await fetch(url + "/guarded/doc/shut", auth([]))).status, 403);
+
+  // declarative route `permission` gate: anonymous → sign in, signed-in-without-permission → the 403 page, with → 200.
+  const gAnon = await fetch(url + "/guarded/gated", { redirect: "manual" });
+  assert.equal(gAnon.status, 303);
+  assert.equal(gAnon.headers.get("location"), "/login?return_to=%2Fguarded%2Fgated");
+  const gDenied = await fetch(url + "/guarded/gated", auth([]));
+  assert.equal(gDenied.status, 403);
+  assert.match(await gDenied.text(), /403/); // the rendered 403.ejs over HTTP
+  assert.equal((await fetch(url + "/guarded/gated", auth(["secret:read"]))).status, 200);
+
+  // declarative `session` gate: anonymous → sign in, and any signed-in user through, grant or none.
+  const sAnon = await fetch(url + "/guarded/mine", { redirect: "manual" });
+  assert.equal(sAnon.status, 303);
+  assert.equal(sAnon.headers.get("location"), "/login?return_to=%2Fguarded%2Fmine");
+  assert.equal((await fetch(url + "/guarded/mine", auth([]))).status, 200);
+});
+
+test("plugin hooks: onRequest can short-circuit a request and onResponse observes the handler result", async (t) => {
+  const seen: string[] = [];
+  const hooked: Plugin = {
+    apiVersion: "1.0.0",
+    hooks: {
+      onRequest: (c) => (c.url.pathname === "/hooked/blocked" ? { html: "blocked by hook", status: 403 } : undefined),
+      onResponse: (c, r) => void seen.push(`${c.url.pathname}:${r && "html" in r ? r.html : "?"}`),
+    },
+    id: "hooked",
+    routes: [{ handler: () => ({ html: "handler ran" }), method: "GET", path: "/ok" }],
+  };
+  const url = await startApp(t, [hooked]);
+
+  // onRequest short-circuits before routing — handler never runs; a fresh CSRF cookie still rides the
+  // response so a form the hook renders has its matching double-submit cookie.
+  const blocked = await fetch(url + "/hooked/blocked");
+  assert.equal(blocked.status, 403);
+  assert.match(await blocked.text(), /blocked by hook/);
+  assert.match(blocked.headers.get("set-cookie") ?? "", /plainpages_csrf=/);
+
+  // A normal route runs the handler; onResponse observed its result.
+  assert.match(await (await fetch(url + "/hooked/ok")).text(), /handler ran/);
+  assert.ok(seen.includes("/hooked/ok:handler ran"));
+});
+

src/http/app.ts

@@ -8,7 +8,6 @@ import { buildPluginChrome, type PageChrome } from "../ui/chrome.ts";
 import { buildContext, type RequestContext, type User } from "./context.ts";
 import { csrfCookie, ensureCsrfToken, verifyCsrfRequest } from "../auth/csrf.ts";
 import type { Denylist } from "../auth/denylist.ts";
-import { buildDashboardModel } from "../ui/dashboard.ts";
 import { PLUGINS_DIR } from "../plugin-host/discovery.ts";
 import { GuardError, loginRedirect } from "../auth/guards.ts";
 import { ENGLISH_I18N } from "../i18n/english.ts";
@@ -33,15 +32,17 @@ import { allowedMethods, matchRoute } from "../plugin-host/router.ts";
 import { buildAuthRoutes } from "../auth/routes.ts";
 import { securityHeaders } from "./security-headers.ts";
 import { localPath } from "./safe-url.ts";
-import { routePublic, serveStatic } from "./static.ts";
+import { publicAssets } from "./static.ts";
 import { renderPluginView } from "../plugin-host/view-resolver.ts";
 
+const NO_STORE = "private, no-store";
+
 const rootDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 
 export interface AppOptions {
   appUrl?: string; // canonical public URL (config.appUrl); off-host GET/HEAD visitors are 308'd here. Omitted ⇒ no redirect
   auth?: VerifyOptions; // expected JWT issuer/audience + clock skew (config); used with jwks
-  cache?: boolean; // cache compiled EJS templates (config.cacheTemplates); off ⇒ edits show live
+  cache?: boolean; // cache compiled EJS templates and /public/ asset versions (config.cacheTemplates); off ⇒ edits show live
   csrfSecret?: string; // HMAC key for the double-submit CSRF token (config.csrfSecret); random if omitted
   denylist?: Denylist; // optional instant-revoke; the hot path rejects revoked subjects, admin writes record revokes
   hydra?: HydraAdmin; // Hydra admin client; with kratos enables the OAuth2 login challenge
@@ -97,6 +98,7 @@ export function createApp(options: AppOptions = {}): Server {
   const anyResponseHooks = plugins.some((p) => p.hooks?.onResponse);
   const pluginsDir = options.pluginsDir ?? PLUGINS_DIR;
   const publicDir = options.publicDir ?? join(rootDir, "public");
+  const assets = publicAssets(publicDir, pluginsDir, pluginIds, { cache });
   const viewsDir = options.viewsDir ?? join(rootDir, "views");
   // Response security headers, fixed at boot (only HSTS depends on the https deployment signal).
   const secHeaderEntries = Object.entries(securityHeaders({ secure: secureCookies }));
@@ -130,10 +132,10 @@ export function createApp(options: AppOptions = {}): Server {
     t: ctx.t,
     url: ctx.url,
   });
-  // i18n locals go last: their names are reserved, so a handler's colliding key loses instead of
-  // breaking the shell around it.
-  const viewsFor = (ctx: RequestContext): ViewRenderer => (view, data) => render(view, { ...data, ...i18nLocals(localsOf(ctx)) });
-  const pluginViewsFor = (ctx: RequestContext, id: string): ViewRenderer => (view, data) => renderView(id, view, { ...data, ...i18nLocals(localsOf(ctx)) });
+  // i18n locals and `assetHref` go last: their names are reserved, so a handler's
+  // colliding key loses instead of breaking the shell around it.
+  const viewsFor = (ctx: RequestContext): ViewRenderer => (view, data) => render(view, { ...data, ...i18nLocals(localsOf(ctx)), assetHref: assets.href });
+  const pluginViewsFor = (ctx: RequestContext, id: string): ViewRenderer => (view, data) => renderView(id, view, { ...data, ...i18nLocals(localsOf(ctx)), assetHref: assets.href });
 
   const sendHtml = (res: ServerResponse, status: number, html: string): void => {
     res.writeHead(status, { "content-type": "text/html; charset=utf-8" });
@@ -166,7 +168,7 @@ export function createApp(options: AppOptions = {}): Server {
       await sendResult(ctx.res, result, pluginViewsFor(pluginCtx, dashboardPlugin.id), pluginCtx.localeHref);
       return null;
     }
-    return { data: { model: buildDashboardModel({ csrfToken: csrf.token, menu, user: ctx.user, nav: ctx.chrome.nav, t: ctx.t }) }, view: "index" };
+    return { data: { chrome: ctx.chrome }, view: "index" };
   };
 
   // The internal route table, matched after plugin routes: the auth/OAuth2 group (src/auth/
@@ -183,7 +185,7 @@ export function createApp(options: AppOptions = {}): Server {
   const handleRequest = async (req: IncomingMessage, res: ServerResponse, reqLog: Log): Promise<void> => {
     // Error pages can render before this request has a context at all (a throw on the way to one),
     // so they start on the built-in English and switch to the visitor's locale once it is resolved.
-    let renderPage: ViewRenderer = (view, data) => render(view, { ...data, ...ENGLISH_LOCALS });
+    let renderPage: ViewRenderer = (view, data) => render(view, { ...data, ...ENGLISH_LOCALS, assetHref: assets.href });
     try {
       const method = req.method ?? "GET";
       const url = new URL(req.url ?? "/", "http://localhost");
@@ -195,14 +197,18 @@ export function createApp(options: AppOptions = {}): Server {
 
       // Before auth: assets don't need a verified user, and the JWT cookie rides every request.
       if (pathname.startsWith("/public/") && (method === "GET" || method === "HEAD")) {
-        const { dir, subPath } = routePublic(pathname.slice("/public/".length), publicDir, pluginsDir, pluginIds);
-        await serveStatic(dir, subPath, res, method === "HEAD", (err) => reqLog.error("static stream error", { error: String(err) }));
+        await assets.serve(url, req, res, (err) => reqLog.error("static file error", { error: String(err) }));
         return;
       }
 
       // A cache in front of us must key on the language. Set after the static branch: an asset is
       // the same bytes in every language, and a Vary there fragments its entry per raw header.
       res.setHeader("vary", "accept-language");
+      // Fail closed: a cache in front of us must not keep a page that may carry a user's data. Not
+      // even the signed-out `/` is shared: it and the signed-in page have one URL, and a cache keyed
+      // on URL and Accept-Language would hand the signed-out one to a signed-in visitor. A route that
+      // is the same for everyone sets its own value in RouteResult.headers; the host doesn't police it.
+      res.setHeader("cache-control", NO_STORE);
 
       // Canonical host (APP_URL): send an off-host visitor to the configured origin so the browser,
       // the themed forms and the cross-origin Kratos POST share one cookie host — otherwise the

src/http/static.test.ts

@@ -0,0 +1,172 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, before, test } from "node:test";
+import { contentTypeFor, publicAssets, resolveStaticPath, routePublic } from "./static.ts";
+
+const IMMUTABLE = "public, max-age=31536000, immutable";
+const SHORT = "public, max-age=300";
+
+const root = mkdtempSync(join(tmpdir(), "static-test-"));
+const publicDir = join(root, "public");
+const pluginsDir = join(root, "plugins");
+mkdirSync(join(publicDir, "css"), { recursive: true });
+mkdirSync(join(pluginsDir, "demo", "public"), { recursive: true });
+writeFileSync(join(publicDir, "css", "a.css"), "body { color: red }");
+writeFileSync(join(pluginsDir, "demo", "public", "app.css"), ".demo {}");
+const assets = publicAssets(publicDir, pluginsDir, new Set(["demo"]), { cache: false });
+const assetHref = assets.href;
+
+const readErrors: Error[] = [];
+let base = "";
+const server = createServer((req, res) => void assets.serve(new URL(req.url ?? "/", "http://localhost"), req, res, (err) => readErrors.push(err)));
+before(() => new Promise<void>((r) => server.listen(0, () => {
+  base = `http://localhost:${(server.address() as AddressInfo).port}`;
+  r();
+})));
+after(() => {
+  server.close();
+  rmSync(root, { force: true, recursive: true });
+});
+
+test("resolveStaticPath blocks traversal and control chars, allows nested files", () => {
+  assert.equal(resolveStaticPath("/srv/public", "../app.ts"), null);
+  assert.equal(resolveStaticPath("/srv/public", "a\x00b"), null);
+  assert.equal(resolveStaticPath("/srv/public", "css/styles.css"), "/srv/public/css/styles.css");
+});
+
+test("contentTypeFor maps known and unknown extensions", () => {
+  assert.match(contentTypeFor("a.css"), /text\/css/);
+  assert.equal(contentTypeFor("a.bin"), "application/octet-stream");
+});
+
+test("routePublic sends a plugin-id segment to its public/ dir, everything else to core", () => {
+  const ids = new Set(["scheduling"]);
+  assert.deepEqual(routePublic("scheduling/app.css", "/core", "/plugins", ids), { dir: "/plugins/scheduling/public", subPath: "app.css" });
+  assert.deepEqual(routePublic("scheduling/img/logo.svg", "/core", "/plugins", ids), { dir: "/plugins/scheduling/public", subPath: "img/logo.svg" });
+  assert.deepEqual(routePublic("scheduling", "/core", "/plugins", ids), { dir: "/plugins/scheduling/public", subPath: "" }); // bare /public/<id>, no file
+  assert.deepEqual(routePublic("css/styles.css", "/core", "/plugins", ids), { dir: "/core", subPath: "css/styles.css" }); // not a plugin → core
+});
+
+test("assetHref versions a /public/ file, core or plugin, and leaves every other href alone", () => {
+  assert.match(assetHref("/public/css/a.css"), /^\/public\/css\/a\.css\?v=[\w-]+$/);
+  assert.match(assetHref("/public/demo/app.css"), /^\/public\/demo\/app\.css\?v=[\w-]+$/);
+  assert.notEqual(assetHref("/public/css/a.css"), assetHref("/public/demo/app.css"));
+  for (const href of ["/public/css/missing.css", "/public/css", "/public/css/a.css?x=1", "/public/css/a.css#top", "/public/..%2f..%2fetc/passwd", "/public/%E0%A4%A", "https://cdn.example/a.css", "data:image/svg+xml,<svg/>", "/elsewhere/a.css"]) {
+    assert.equal(assetHref(href), href, href);
+  }
+});
+
+test("assetHref changes when the file's content does", () => {
+  const file = join(publicDir, "css", "changing.css");
+  writeFileSync(file, "a {}");
+  const first = assetHref("/public/css/changing.css");
+  assert.equal(assetHref("/public/css/changing.css"), first);
+  writeFileSync(file, "a { color: blue }");
+  assert.notEqual(assetHref("/public/css/changing.css"), first);
+});
+
+test("assetHref changes when the file's size does, even with its mtime restored", () => {
+  const file = join(publicDir, "css", "resized.css");
+  writeFileSync(file, "a {}");
+  const { atime, mtime } = statSync(file);
+  const first = assetHref("/public/css/resized.css");
+  writeFileSync(file, "a { color: blue }");
+  utimesSync(file, atime, mtime);
+  assert.notEqual(assetHref("/public/css/resized.css"), first);
+});
+
+test("with cache on, assetHref keeps a known version; a request naming it after an edit gets the short cache and the new ETag", async () => {
+  const cached = publicAssets(publicDir, pluginsDir, new Set(), { cache: true });
+  const file = join(publicDir, "css", "cached.css");
+  writeFileSync(file, "a {}");
+  const stale = cached.href("/public/css/cached.css");
+  writeFileSync(file, "a { color: green }");
+  assert.equal(cached.href("/public/css/cached.css"), stale);
+
+  const res = await fetch(base + stale);
+  assert.equal(res.status, 200);
+  assert.equal(await res.text(), "a { color: green }");
+  assert.equal(res.headers.get("cache-control"), SHORT);
+  const fresh = assetHref("/public/css/cached.css");
+  assert.notEqual(fresh, stale);
+  assert.equal(res.headers.get("etag"), `"${fresh.split("?v=")[1]}"`);
+});
+
+test("a version hashed while rendering equals the ETag hashed while serving the same bytes", async () => {
+  writeFileSync(join(publicDir, "css", "served-first.css"), "p {}");
+  writeFileSync(join(publicDir, "css", "rendered-first.css"), "p {}");
+  const etag = (await fetch(base + "/public/css/served-first.css")).headers.get("etag");
+  assert.equal(etag, `"${assetHref("/public/css/rendered-first.css").split("?v=")[1]}"`);
+});
+
+test("a URL carrying the current version is cached for a year as immutable", async () => {
+  for (const method of ["GET", "HEAD"]) {
+    const res = await fetch(base + assetHref("/public/css/a.css"), { method });
+    assert.equal(res.status, 200, method);
+    assert.equal(res.headers.get("cache-control"), IMMUTABLE, method);
+  }
+  assert.equal((await fetch(base + assetHref("/public/demo/app.css"))).headers.get("cache-control"), IMMUTABLE);
+});
+
+test("an unversioned or stale-versioned URL is cached briefly, with an ETag and Last-Modified to revalidate", async () => {
+  const lastModified = statSync(join(publicDir, "css", "a.css")).mtime.toUTCString();
+  for (const path of ["/public/css/a.css", "/public/css/a.css?v=stale"]) {
+    const res = await fetch(base + path);
+    assert.equal(res.status, 200, path);
+    assert.equal(await res.text(), "body { color: red }", path);
+    assert.equal(res.headers.get("cache-control"), SHORT, path);
+    assert.match(res.headers.get("etag") ?? "", /^"[\w-]+"$/, path);
+    assert.equal(res.headers.get("last-modified"), lastModified, path);
+  }
+});
+
+test("If-None-Match naming the current ETag answers 304 with no body, for GET and HEAD", async () => {
+  const etag = (await fetch(base + "/public/css/a.css")).headers.get("etag") ?? "";
+  for (const method of ["GET", "HEAD"]) {
+    for (const ifNoneMatch of [etag, `W/${etag}`, `"other", ${etag}`, "*"]) {
+      const res = await fetch(base + "/public/css/a.css", { headers: { "if-none-match": ifNoneMatch }, method });
+      assert.equal(res.status, 304, `${method} ${ifNoneMatch}`);
+      assert.equal(await res.text(), "");
+      assert.equal(res.headers.get("etag"), etag);
+      assert.equal(res.headers.get("cache-control"), SHORT);
+    }
+  }
+  const versioned = await fetch(base + assetHref("/public/css/a.css"), { headers: { "if-none-match": etag } });
+  assert.equal(versioned.status, 304);
+  assert.equal(versioned.headers.get("cache-control"), IMMUTABLE);
+
+  assert.equal((await fetch(base + "/public/css/a.css", { headers: { "if-none-match": '"other"' } })).status, 200);
+});
+
+test("If-Modified-Since at or after the file's mtime answers 304; before it, or beside a failed If-None-Match, 200", async () => {
+  const lastModified = (await fetch(base + "/public/css/a.css")).headers.get("last-modified") ?? "";
+  for (const method of ["GET", "HEAD"]) {
+    const res = await fetch(base + "/public/css/a.css", { headers: { "if-modified-since": lastModified }, method });
+    assert.equal(res.status, 304, method);
+    assert.equal(await res.text(), "");
+  }
+  const earlier = new Date(Date.parse(lastModified) - 1000).toUTCString();
+  assert.equal((await fetch(base + "/public/css/a.css", { headers: { "if-modified-since": earlier } })).status, 200);
+  assert.equal((await fetch(base + "/public/css/a.css", { headers: { "if-modified-since": "not a date" } })).status, 200);
+  assert.equal((await fetch(base + "/public/css/a.css", { headers: { "if-modified-since": lastModified, "if-none-match": '"other"' } })).status, 200);
+});
+
+test("unsafe or missing paths answer 400, 403 and 404", async () => {
+  assert.equal((await fetch(base + "/public/%E0%A4%A")).status, 400);
+  assert.equal((await fetch(base + "/public/..%2f..%2fetc%2fpasswd")).status, 403);
+  assert.equal((await fetch(base + "/public/css/missing.css")).status, 404);
+  assert.equal((await fetch(base + "/public/css/a.css/x")).status, 404); // ENOTDIR
+  assert.equal((await fetch(base + "/public/css")).status, 404);
+  assert.deepEqual(readErrors, []);
+});
+
+test("a read failure other than a missing file answers 500 and reaches onError", async () => {
+  symlinkSync("loop.css", join(publicDir, "css", "loop.css")); // root reads a mode-000 file, so a symlink loop makes the failure
+  const res = await fetch(base + "/public/css/loop.css");
+  assert.equal(res.status, 500);
+  assert.deepEqual(readErrors.splice(0).map((err) => (err as NodeJS.ErrnoException).code), ["ELOOP"]);
+});

src/http/static.ts

@@ -1,6 +1,7 @@
-import { createReadStream } from "node:fs";
+import { createHash, type Hash } from "node:crypto";
+import { createReadStream, readFileSync, statSync, type Stats } from "node:fs";
 import { stat } from "node:fs/promises";
-import type { ServerResponse } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
 import { extname, isAbsolute, join, relative } from "node:path";
 
 const contentTypes: Record<string, string> = {
@@ -38,8 +39,8 @@ export interface StaticRoute {
 
 // Route a `/public/<rest>` request to a base dir + sub-path: a leading segment naming a discovered
 // plugin serves from plugins/<id>/public/, anything else from the core public/. Plugin ids are
-// URL-safe (no %-encoding), so the raw segment compares directly to the id set; serveStatic decodes
-// and traversal-guards the sub-path as before.
+// URL-safe (no %-encoding), so the raw segment compares directly to the id set; the caller decodes
+// and traversal-guards the sub-path.
 export function routePublic(restPath: string, publicDir: string, pluginsDir: string, pluginIds: Set<string>): StaticRoute {
   const slash = restPath.indexOf("/");
   const first = slash === -1 ? restPath : restPath.slice(0, slash);
@@ -49,28 +50,103 @@ export function routePublic(restPath: string, publicDir: string, pluginsDir: str
   return { dir: publicDir, subPath: restPath };
 }
 
+// Caching: the host renders every /public/ href through assetHref, which appends `?v=<hash of the
+// file's content>`. A request whose `v` is the current hash is cached for a year as immutable, so a
+// repeat page view downloads no asset; a changed file gets a new hash, and with it a new URL. Any other
+// request — an href a plugin's own markup emits, a stale `v` mid-deploy — is cached for five minutes,
+// then revalidated against the ETag (that same hash) or Last-Modified. A plugin has no way to version
+// its own hrefs yet: `assetHref` is a reserved local but not contract, since offering it is a minor.
+const IMMUTABLE = "public, max-age=31536000, immutable";
+const SHORT = "public, max-age=300";
+
+// An entry holds while the file's mtime and size match, so a file edited in place (a dev bind mount)
+// gets a new hash.
+const hashes = new Map<string, { hash: string; mtimeMs: number; size: number }>();
+
+function memoized(filePath: string, info: Stats): string | undefined {
+  const known = hashes.get(filePath);
+  return known?.mtimeMs === info.mtimeMs && known.size === info.size ? known.hash : undefined;
+}
+
+// The one definition of a version. Two readers feed it. A view renders synchronously, so hashFileSync
+// reads the file whole; hashFile streams it, so a large file doesn't stall every other request.
+function remember(filePath: string, info: Stats, sha256: Hash): string {
+  const hash = sha256.digest("base64url").slice(0, 16);
+  hashes.set(filePath, { hash, mtimeMs: info.mtimeMs, size: info.size });
+  return hash;
+}
+
+function hashFileSync(filePath: string, info: Stats): string {
+  return memoized(filePath, info) ?? remember(filePath, info, createHash("sha256").update(readFileSync(filePath)));
+}
+
+async function hashFile(filePath: string, info: Stats): Promise<string> {
+  const known = memoized(filePath, info);
+  if (known !== undefined) return known;
+  const sha256 = createHash("sha256");
+  for await (const chunk of createReadStream(filePath)) sha256.update(chunk);
+  return remember(filePath, info, sha256);
+}
+
+// Without `cache`, a stat per href picks up an edited file. With it, a known version skips the stat:
+// an edit reaches the hrefs once a request for the file hashes it again.
+function versioned(href: string, route: StaticRoute, cache: boolean): string {
+  try {
+    const filePath = resolveStaticPath(route.dir, decodeURIComponent(route.subPath));
+    if (filePath === null) return href;
+    const known = cache ? hashes.get(filePath) : undefined;
+    if (known) return `${href}?v=${known.hash}`;
+    const info = statSync(filePath);
+    return info.isFile() ? `${href}?v=${hashFileSync(filePath, info)}` : href;
+  } catch {
+    return href; // malformed %-encoding, or a missing or unreadable file: serving it answers the error
+  }
+}
+
+// RFC 9110 §13.1.2, weak comparison: `W/"x"` matches `"x"`, and `*` matches any existing file.
+function etagMatches(ifNoneMatch: string, etag: string): boolean {
+  return ifNoneMatch.split(",").some((tag) => {
+    const t = tag.trim();
+    return t === "*" || t.replace(/^W\//, "") === etag;
+  });
+}
+
+// RFC 9110 §13.2.2: If-None-Match, when present, decides alone; HTTP dates have whole seconds.
+function notModified(req: IncomingMessage, etag: string, info: Stats): boolean {
+  const ifNoneMatch = req.headers["if-none-match"];
+  if (ifNoneMatch !== undefined) return etagMatches(ifNoneMatch, etag);
+  const since = Date.parse(req.headers["if-modified-since"] ?? "");
+  return !Number.isNaN(since) && Math.floor(info.mtimeMs / 1000) * 1000 <= since;
+}
+
 function plain(res: ServerResponse, status: number, body: string): void {
   res.writeHead(status, { "content-type": "text/plain; charset=utf-8" }).end(body);
 }
 
-// onError handles a mid-stream read failure (headers already sent); defaults to console.error so
-// static.ts stays standalone, while app.ts passes the request logger for structured output.
-export async function serveStatic(dir: string, requestedPath: string, res: ServerResponse, head = false, onError: (err: Error) => void = (err) => console.error(err)): Promise<void> {
+interface StaticRequest extends StaticRoute {
+  version: string | null; // the request's `v` query parameter
+}
+
+async function serveStatic(route: StaticRequest, req: IncomingMessage, res: ServerResponse, onError: (err: Error) => void): Promise<void> {
   let decoded: string;
   try {
-    decoded = decodeURIComponent(requestedPath);
+    decoded = decodeURIComponent(route.subPath);
   } catch {
     return plain(res, 400, "Bad Request");
   }
 
-  const filePath = resolveStaticPath(dir, decoded);
+  const filePath = resolveStaticPath(route.dir, decoded);
   if (filePath === null) return plain(res, 403, "Forbidden");
 
   try {
     const info = await stat(filePath);
     if (!info.isFile()) return plain(res, 404, "Not Found");
-    res.writeHead(200, { "content-length": info.size, "content-type": contentTypeFor(filePath) });
-    if (head) return void res.end(); // headers only — skip opening the file
+    const hash = await hashFile(filePath, info);
+    const etag = `"${hash}"`;
+    const validators = { "cache-control": route.version === hash ? IMMUTABLE : SHORT, etag, "last-modified": info.mtime.toUTCString() };
+    if (notModified(req, etag, info)) return void res.writeHead(304, validators).end();
+    res.writeHead(200, { ...validators, "content-length": info.size, "content-type": contentTypeFor(filePath) });
+    if (req.method === "HEAD") return void res.end();
     // Headers are already sent, so a mid-stream read error can't become an HTTP status —
     // log and destroy the response to signal a truncated body, not a hung socket.
     createReadStream(filePath)
@@ -79,7 +155,24 @@ export async function serveStatic(dir: string, requestedPath: string, res: Serve
         res.destroy();
       })
       .pipe(res);
-  } catch {
-    plain(res, 404, "Not Found");
+  } catch (err) {
+    const { code } = err as NodeJS.ErrnoException;
+    if (code === "ENOENT" || code === "ENOTDIR") return plain(res, 404, "Not Found");
+    onError(err as Error);
+    plain(res, 500, "Internal Server Error");
   }
 }
+
+export interface PublicAssets {
+  href: (href: string) => string; // a /public/ href with its version; any other href unchanged
+  // onError receives every failure to read a file except a missing one, which answers 404.
+  serve: (url: URL, req: IncomingMessage, res: ServerResponse, onError: (err: Error) => void) => Promise<void>;
+}
+
+export function publicAssets(publicDir: string, pluginsDir: string, pluginIds: Set<string>, { cache }: { cache: boolean }): PublicAssets {
+  const route = (pathname: string): StaticRoute => routePublic(pathname.slice("/public/".length), publicDir, pluginsDir, pluginIds);
+  return {
+    href: (href) => (href.startsWith("/public/") && !/[?#]/.test(href) ? versioned(href, route(href), cache) : href),
+    serve: (url, req, res, onError) => serveStatic({ ...route(url.pathname), version: url.searchParams.get("v") }, req, res, onError),
+  };
+}

src/ui/chrome.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { buildPluginChrome } from "./chrome.ts";
+import { buildPluginChrome, shellUser } from "./chrome.ts";
 import { DEFAULT_MENU, type MenuConfig } from "./menu-config.ts";
 import type { NavNode } from "./nav.ts";
 import type { Plugin } from "../plugin-host/plugin.ts";
@@ -74,3 +74,16 @@ test("branding logo + default theme flow through when set", () => {
   assert.equal(chrome.brand.name, "Acme");
   assert.equal(chrome.theme, "dark");
 });
+
+test("branding name and sub are translated; an unknown key renders as itself", () => {
+  const t = (key: string): string => (key === "brand.sub" ? "Undertitel" : key);
+  const chrome = buildPluginChrome({ menu: { branding: { name: "Acme", sub: "brand.sub" }, override: {} }, t });
+  assert.equal(chrome.brand.name, "Acme");
+  assert.equal(chrome.brand.sub, "Undertitel");
+  assert.equal(buildPluginChrome({ menu: { branding: { name: "Acme" }, override: {} } }).brand.sub, undefined);
+});
+
+test("shellUser derives the profile from the real user; anonymous → Guest", () => {
+  assert.deepEqual(shellUser(null), { email: "", initials: "G", name: "Guest" });
+  assert.deepEqual(shellUser({ email: "ada@example.com", id: "u1", permissions: [] }), { email: "ada@example.com", initials: "AD", name: "ada" });
+});

src/ui/chrome.ts

@@ -8,10 +8,15 @@ import type { Translate } from "../i18n/translate.ts";
 import { type MenuConfig } from "./menu-config.ts";
 import { composeNav, type NavNode } from "./nav.ts";
 import type { Plugin } from "../plugin-host/plugin.ts";
-import { branding, shellUser, type ShellUser } from "./shell-context.ts";
 
 const DASHBOARD_NAV: NavNode = { href: "/dashboard", icon: "i-grid", id: "dashboard", label: "nav.dashboard", session: true };
 
+export interface ShellUser {
+  email: string;
+  initials: string;
+  name: string;
+}
+
 export interface PageChrome {
   brand: { logo?: string; name: string; sub?: string };
   csrfToken: string; // double-submit token for the shell's Sign-out form + a plugin's own forms
@@ -65,6 +70,26 @@ export function buildPluginChrome(opts: ChromeOptions): PageChrome {
   };
 }
 
+// The JWT holds only id/email/permissions, so the profile name is the email's local part.
+export function shellUser(user: User | null | undefined, t: Translate = ENGLISH): ShellUser {
+  if (!user) {
+    const guest = t("shell.guest");
+    return { email: "", initials: ([...guest][0] ?? "?").toUpperCase(), name: guest }; // by character: the word is translated
+  }
+  const local = user.email.split("@")[0] || user.email;
+  return { email: user.email, initials: (local.slice(0, 2) || "U").toUpperCase(), name: local };
+}
+
+function branding(menu: MenuConfig, t: Translate): { logo?: string; name: string; sub?: string; theme?: string } {
+  const b = menu.branding;
+  return {
+    ...(b.logo != null ? { logo: b.logo } : {}),
+    name: t(b.name),
+    ...(b.sub != null ? { sub: t(b.sub) } : {}),
+    ...(b.theme != null ? { theme: b.theme } : {}),
+  };
+}
+
 function translateNav(nodes: NavNode[], t: Translate): NavNode[] {
   return nodes.map((node) => ({
     ...node,

src/ui/dashboard.test.ts

@@ -1,28 +0,0 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-import { buildDashboardModel } from "./dashboard.ts";
-import type { NavNode } from "./nav.ts";
-
-// The default /dashboard is an instructional starter: no mock data, just the unified
-// menu + shell. The host passes the one global menu (ctx.chrome.nav); the model passes it through.
-const NAV: NavNode[] = [{ href: "/dashboard", label: "Dashboard" }, { children: [{ href: "/admin/users", label: "Users" }], label: "Admin" }];
-
-test("dashboard model: titled shell, passes the unified nav + csrf + user through", () => {
-  const m = buildDashboardModel({ csrfToken: "tok.sig", user: { email: "ada@x.io", id: "u1", permissions: ["admin"] }, nav: NAV });
-  assert.equal(m.shell.title, "Dashboard");
-  assert.equal(m.shell.csrfToken, "tok.sig");
-  assert.equal(m.shell.user.name, "ada"); // real signed-in identity, not a demo profile
-  assert.deepEqual(m.nav, NAV); // the host's menu is used verbatim — the dashboard builds no nav of its own
-});
-
-test("dashboard model: sensible defaults (empty nav, no token, Guest) and branding from menu", () => {
-  const m = buildDashboardModel();
-  assert.deepEqual(m.nav, []);
-  assert.equal(m.shell.csrfToken, "");
-  assert.equal(m.shell.user.name, "Guest");
-  assert.equal(m.shell.brand.name, "Plainpages");
-
-  const branded = buildDashboardModel({ menu: { branding: { name: "Acme Ops", sub: "Admin", theme: "dark" }, override: {} } });
-  assert.equal(branded.shell.brand.name, "Acme Ops");
-  assert.equal(branded.shell.theme, "dark");
-});

src/ui/dashboard.ts

@@ -1,29 +0,0 @@
-// Dashboard view model: the gated "/dashboard" app home. By default a short instructional
-// starter — what the dashboard is and how to replace it by exporting a `dashboard` handler from a
-// plugin (views/index.ejs holds the prose). A plugin owns the real one (PluginManifest.dashboard);
-// this placeholder renders until then. Pure: `nav` is the one global menu (ctx.chrome.nav), built
-// once per request by the host, so the dashboard shows the exact same menu as every other page.
-
-import type { User } from "../http/context.ts";
-import { ENGLISH } from "../i18n/english.ts";
-import type { Translate } from "../i18n/translate.ts";
-import { DEFAULT_MENU, type MenuConfig } from "./menu-config.ts";
-import type { NavNode } from "./nav.ts";
-import { buildShellContext } from "./shell-context.ts";
-
-export function buildDashboardModel(opts: { csrfToken?: string; menu?: MenuConfig; nav?: NavNode[]; t?: Translate; user?: User | null } = {}) {
-  const t = opts.t ?? ENGLISH;
-  return {
-    nav: opts.nav ?? [],
-    shell: buildShellContext({
-      breadcrumbs: [{ label: t("dashboard.title") }],
-      csrfToken: opts.csrfToken ?? "",
-      menu: opts.menu ?? DEFAULT_MENU,
-      t,
-      title: t("dashboard.title"),
-      user: opts.user ?? null,
-    }),
-  };
-}
-
-export type DashboardModel = ReturnType<typeof buildDashboardModel>;

src/ui/icons.ts

@@ -9,13 +9,11 @@ export const ICON_NAMES: Record<string, string> = {
   "i-bell": "bell",
   "i-box": "box",
   "i-cal": "calendar",
-  "i-chart": "chart-no-axes-column",
   "i-check-circle": "circle-check",
   "i-chev": "chevron-right",
   "i-cols": "columns-3",
-  "i-copy": "copy",
-  "i-download": "download",
   "i-edit": "pencil",
+  "i-eye": "eye",
   "i-globe": "globe",
   "i-grid": "layout-grid",
   "i-kebab": "ellipsis-vertical",

src/ui/shell-context.test.ts

@@ -1,32 +0,0 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-import { buildShellContext, shellUser } from "./shell-context.ts";
-
-test("shellUser derives the profile from the real user; anonymous → Guest", () => {
-  assert.deepEqual(shellUser(null), { email: "", initials: "G", name: "Guest" });
-  // Real user: name = email local part, email kept, initials = first two letters of the local part.
-  assert.deepEqual(shellUser({ email: "ada@example.com", id: "u1", permissions: [] }), { email: "ada@example.com", initials: "AD", name: "ada" });
-});
-
-test("buildShellContext maps branding + breadcrumbs, omitting unset optional fields", () => {
-  const bare = buildShellContext({ menu: { branding: { name: "Plainpages" }, override: {} }, title: "Users" });
-  assert.deepEqual(bare.brand, { name: "Plainpages" }); // no logo/sub when unset
-  assert.equal(bare.theme, undefined);
-  assert.equal(bare.csrfToken, "");
-  assert.equal(bare.user.name, "Guest");
-  assert.equal(bare.signInHref, undefined); // omitted unless supplied (a public built-in screen would set it)
-
-  const full = buildShellContext({
-    breadcrumbs: [{ href: "/", label: "Home" }, { label: "Users" }],
-    csrfToken: "tok.sig",
-    menu: { branding: { logo: "/l.svg", name: "Acme", sub: "Ops", theme: "dark" }, override: {} },
-    signInHref: "/login?return_to=%2Fx",
-    title: "Users",
-    user: { email: "a@b.c", id: "u1", permissions: ["admin"] },
-  });
-  assert.deepEqual(full.brand, { logo: "/l.svg", name: "Acme", sub: "Ops" });
-  assert.equal(full.theme, "dark");
-  assert.equal(full.csrfToken, "tok.sig");
-  assert.equal(full.breadcrumbs?.length, 2);
-  assert.equal(full.signInHref, "/login?return_to=%2Fx");
-});

src/ui/shell-context.ts

@@ -1,70 +0,0 @@
-// Shell view-model builder: the brand/theme/user/title block every app-shell page
-// (the home dashboard, the built-in admin screens) hands to shell.ejs. Pure. Extracted so the
-// shell user is the *real* signed-in identity — no hardcoded demo profile — and branding is
-// read from one place. The User carries no display name (the JWT holds only id/email/permissions), so
-// the profile shows the email's local part as the name with the full email beneath, initials from
-// the local part; anonymous ⇒ "Guest".
-
-import type { User } from "../http/context.ts";
-import { ENGLISH } from "../i18n/english.ts";
-import type { Translate } from "../i18n/translate.ts";
-import { type MenuConfig } from "./menu-config.ts";
-
-// The brand block both the chrome and the shell model carry. `name`/`sub` pass through `t`, so a
-// catalog key is translated and an operator's own wording renders as written.
-export function branding(menu: MenuConfig, t: Translate): { logo?: string; name: string; sub?: string; theme?: string } {
-  const b = menu.branding;
-  return {
-    ...(b.logo != null ? { logo: b.logo } : {}),
-    name: t(b.name),
-    ...(b.sub != null ? { sub: t(b.sub) } : {}),
-    ...(b.theme != null ? { theme: b.theme } : {}),
-  };
-}
-
-export interface ShellUser {
-  email: string;
-  initials: string;
-  name: string;
-}
-
-export interface ShellModel {
-  brand: { logo?: string; name: string; sub?: string };
-  breadcrumbs?: { href?: string; label: string }[];
-  csrfToken: string;
-  signInHref?: string; // anonymous "Sign in" target (mirrors PageChrome.signInHref); a gated screen omits it
-  theme?: string;
-  title: string;
-  user: ShellUser;
-}
-
-export function shellUser(user: User | null | undefined, t: Translate = ENGLISH): ShellUser {
-  if (!user) {
-    const guest = t("shell.guest");
-    return { email: "", initials: ([...guest][0] ?? "?").toUpperCase(), name: guest }; // by character: the word is translated
-  }
-  const local = user.email.split("@")[0] || user.email;
-  return { email: user.email, initials: (local.slice(0, 2) || "U").toUpperCase(), name: local };
-}
-
-export function buildShellContext(opts: {
-  breadcrumbs?: { href?: string; label: string }[];
-  csrfToken?: string;
-  menu: MenuConfig;
-  signInHref?: string;
-  t?: Translate;
-  title: string;
-  user?: User | null;
-}): ShellModel {
-  const t = opts.t ?? ENGLISH;
-  const { theme, ...brand } = branding(opts.menu, t);
-  return {
-    brand,
-    ...(opts.breadcrumbs ? { breadcrumbs: opts.breadcrumbs } : {}),
-    csrfToken: opts.csrfToken ?? "",
-    ...(opts.signInHref != null ? { signInHref: opts.signInHref } : {}),
-    ...(theme != null ? { theme } : {}),
-    title: opts.title,
-    user: shellUser(opts.user, t),
-  };
-}

src/ui/shell.test.ts

@@ -6,10 +6,10 @@ import ejs from "ejs";
 import { ENGLISH_LOCALS } from "../i18n/view-locals.ts";
 
 // A localeHref that marks what it touches, so a raw href in the chrome is visible to a test.
-const CARRYING = { ...ENGLISH_LOCALS, localeHref: (href: string) => `${href}?locale=sv-SE` };
+const CARRYING = { ...ENGLISH_LOCALS, assetHref: (href: string) => href, localeHref: (href: string) => `${href}?locale=sv-SE` };
 
 const shell = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "views", "partials", "shell.ejs");
-const render = (data: Record<string, unknown> = {}): Promise<string> => ejs.renderFile(shell, { ...ENGLISH_LOCALS, ...data });
+const render = (data: Record<string, unknown> = {}): Promise<string> => ejs.renderFile(shell, { ...ENGLISH_LOCALS, assetHref: (href: string) => href, ...data });
 
 test("app shell renders sidebar, topbar and the content slot", async () => {
   const html = await render({
@@ -90,6 +90,12 @@ test("app shell links extra per-page stylesheets via the styles slot (e.g. a plu
   assert.equal((none.match(/rel="stylesheet"/g) ?? []).length, 1);
 });
 
+test("app shell passes every /public/ reference through the host's assetHref, the plugin's styles included", async () => {
+  const html = await render({ assetHref: (href: string) => `${href}?v=1`, brand: { logo: "/public/brand/logo.svg", name: "Acme" }, styles: ["/public/scheduling/scheduling.css"] });
+  const refs = [...html.matchAll(/(?:href|src)="(\/public\/[^"]*)"/g)].map((m) => m[1]);
+  assert.deepEqual(refs, ["/public/css/styles.css?v=1", "/public/scheduling/scheduling.css?v=1", "/public/favicon.svg?v=1", "/public/brand/logo.svg?v=1"]);
+});
+
 test("app shell can disable the menu: no sidebar, focused single-column layout", async () => {
   const bare = await render({ menu: false, title: "Focus", body: '<section id="b">x</section>', nav: '<a href="/x">Overview</a>' });
   assert.doesNotMatch(bare, /<aside class="sidebar"/); // sidebar dropped

src/ui/stylesheet-contrast.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+
+const css = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "public", "css", "styles.css"), "utf8");
+
+const token = (name: string): string => {
+  const hex = new RegExp(`--${name}:\\s*(#[0-9a-f]{6})\\b`, "i").exec(css)?.[1];
+  assert.ok(hex, `--${name} is not a six-digit hex colour`);
+  return hex;
+};
+
+const luminance = (hex: string): number => {
+  const [r = 0, g = 0, b = 0] = [1, 3, 5].map((i) => {
+    const c = Number.parseInt(hex.slice(i, i + 2), 16) / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+
+const contrast = (a: string, b: string): number => {
+  const [hi = 0, lo = 0] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+};
+
+// WCAG AA for normal text.
+for (const theme of ["l", "d"]) {
+  for (const tone of ["pos", "neg", "warn", "info"]) {
+    test(`${tone} badge text reaches 4.5:1 in ${theme === "l" ? "light" : "dark"} mode`, () => {
+      assert.ok(contrast(token(`${theme}-${tone}`), token(`${theme}-${tone}-bg`)) >= 4.5);
+    });
+  }
+  test(`text on the accent reaches 4.5:1 in ${theme === "l" ? "light" : "dark"} mode`, () => {
+    assert.ok(contrast(token(`${theme}-on-accent`), token(`${theme}-accent`)) >= 4.5);
+  });
+}

src/ui/stylesheet-floor.test.ts

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+
+const cssDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "public", "css");
+
+// A custom property holding oklch() passes unchecked on an engine below Chromium 111, so the
+// var() that reads it is invalid at computed-value time: white text on no background.
+for (const file of readdirSync(cssDir).filter((f) => f.endsWith(".css"))) {
+  test(`${file} declares no oklch() colour`, () => {
+    assert.ok(!/oklch\(/i.test(readFileSync(join(cssDir, file), "utf8")));
+  });
+}
+
+const stylesheet = readFileSync(join(cssDir, "styles.css"), "utf8").replace(/\/\*[\s\S]*?\*\//g, "");
+
+// The index of the `}` closing the block whose `{` is the first one at or after `start`.
+function blockEnd(start: number): number {
+  let depth = 0;
+  for (let i = stylesheet.indexOf("{", start); i < stylesheet.length; i++) {
+    if (stylesheet[i] === "{") depth++;
+    if (stylesheet[i] === "}" && --depth === 0) return i;
+  }
+  throw new Error("unbalanced braces in styles.css");
+}
+
+// The text is all there is to check: Playwright's engines all support `:has()`, so no E2E sees the
+// stylesheet an older engine gets.
+// Chromium below 105 and Firefox below 121 have no `:has()`, and nothing else reveals a folded
+// branch there, so the fold may only exist where `:has()` works.
+test("styles.css folds .nav-children only inside @supports selector(:has(a))", () => {
+  const open = stylesheet.indexOf("@supports selector(:has(a)) {");
+  assert.ok(open >= 0, "no @supports selector(:has(a)) block");
+  const close = blockEnd(open);
+  const outside = stylesheet.slice(0, open) + stylesheet.slice(close + 1);
+  assert.ok(!/\.nav-children\s*\{[^}]*display:\s*none/.test(outside), "a .nav-children rule hides it outside the guard");
+  assert.match(stylesheet.slice(open, close), /\.nav-children\s*\{\s*display:\s*none/, "the fold rule is gone");
+});
+
+// `@supports` adds no specificity, so the hiding rule has to come after the base `.theme-switch` rule.
+test("styles.css hides the theme switch and the nav toggles where :has() is missing, after their base rules", () => {
+  const guard = stylesheet.indexOf("@supports not selector(:has(a)) {");
+  assert.ok(guard >= 0, "no @supports not selector(:has(a)) block");
+  const base = stylesheet.search(/^\.theme-switch\s*\{/m);
+  assert.ok(base >= 0 && base < guard, "the guard precedes the base .theme-switch rule");
+  const block = stylesheet.slice(guard, stylesheet.indexOf("\n}", guard));
+  assert.match(block, /\.theme-switch\s*\{\s*display:\s*none/);
+  assert.match(block, /\.nav-disc\s*\{\s*visibility:\s*hidden/);
+});
+
+// Without `:has()` nothing reads #nav-toggle, so an off-canvas sidebar there is unreachable and the
+// hamburger does nothing: the sidebar has to stay in the flow, with the hamburger hidden.
+test("styles.css moves the sidebar off-canvas at 860px only inside @supports selector(:has(a))", () => {
+  const open = stylesheet.indexOf("@media (max-width: 860px) {");
+  assert.ok(open >= 0, "no @media (max-width: 860px) block");
+  const close = blockEnd(open);
+  const media = stylesheet.slice(open, close);
+  const guard = media.indexOf("@supports selector(:has(a)) {");
+  assert.ok(guard >= 0, "no @supports selector(:has(a)) block inside the 860px media block");
+  const guardEnd = blockEnd(open + guard) - open;
+  const outside = media.slice(0, guard) + media.slice(guardEnd + 1);
+  const inside = media.slice(guard, guardEnd);
+  for (const offCanvas of [/translateX\(-100%\)/, /position:\s*fixed/, /#nav-toggle/, /\.hamburger/]) {
+    assert.doesNotMatch(outside, offCanvas, `${offCanvas} applies outside the guard`);
+    assert.match(inside, offCanvas, `${offCanvas} is gone from the guard`);
+  }
+});

todo.md

@@ -1,74 +1,121 @@
-# Primary todo
+# todo
 
-## Unfinnished work
+## Scoring
 
-- [ ] **Publish every release to Docker Hub, and give the Hub page its short description.** Today Hub's newest tag is 0.4.0 (2026-09-10), while git has v0.4.1–v0.4.12, and the overview still says 0.4.0. No `release.yml` run exists for the tags auto-release pushes as `renovate-bot`, so neither the images nor the overview reach Hub; find out why Gitea doesn't fire `push: tags` for them, fix it, and backfill the missing tags. The short description is empty. fejkdata already did this (`../fejkdata`, commits `51d924a` and `34c8234`), and two parts port directly: a `dockerhub/description.txt`-style one-liner, which here can ride the existing PATCH as its `description` field; and a unit test that the description opens a README sentence and every command the overview shows appears in the README. fejkdata also syncs the page on any push to `main` that changes it, with its own Read/Write/Delete token in an environment only `main` may use, so the image-push token needs no Delete scope. Decide whether that fits here, where `{{VERSION}}` must render a released tag.
-- [ ] Rename the plugin "admin" to something less generic, like "auth-admin" or "users-groups-admin".
-- [ ] Guard the group paths against self-lockout, or accept them explicitly. The self-revoke guard covers only your own *direct* grants on the Users screen; unticking a permission on a group you belong to, removing yourself from that group, or deleting it can all still strip your own effective access with no warning. Recorded in AGENTS.md as a known gap — the robust fix is a "last effective holder" check, which needs a reverse Keto query.
-- [ ] The permission picker has no concurrency baseline, so two operators editing the same user/group silently discard each other's change. Sketch: post the rendered set as a hidden baseline; if it no longer matches Keto, re-render with "this changed while you had the page open" rather than applying.
-- [ ] A grant whose plugin was uninstalled is invisible and unremovable in the GUI. `grantDiff` deliberately never revokes an undeclared name, but nothing *shows* it either — so it can't be audited or cleaned, and reinstalling that plugin silently reactivates access nobody remembers granting. Sketch: a read-only "held, but no installed plugin offers this" list with a remove action.
-- [ ] A plugin may gate a route on a permission it never declares — declaring stays optional on purpose. The cost is a dead end: the picker is built from declarations only, so that route is ungrantable from the GUI with no boot error and a permanent 403 as the operator's only clue. Sketch: a discovery *warning* (not an error) naming the gated-but-undeclared permission.
-- [ ] Saving permissions gives no confirmation, and a partial failure is silent. `applyGrants` loops writes then deletes with no transaction, so a Keto error midway leaves a half-applied set behind the generic error page; and a successful save is indistinguishable from "nothing changed". The `alert alert-pos` pattern the recovery-code banner uses is already available.
-- [ ] In Playwright tests, try different resolutions and sizes, from BIG desktop down to tiny phone.
-- [ ] Decide whether `e2e-tests/` should be typechecked. It is outside `tsconfig.include`, so the gate never checks its most logic-bearing file (`console-guard.ts`). Including it needs the DOM lib and `@playwright/test` present wherever `npm run typecheck` runs, which today is the `web` image that installs neither.
-- [ ] Decide whether Playwright's `workers` should be pinned. Unset, it sizes the pool from `os.cpus()`, which reports the host's cores regardless of a container CPU quota — and with `retries: 0` a starved runner turns a slow test straight into a red gate. Fine on the current act_runner; revisit if CI ever runs constrained.
-- [ ] Record the browser floor Plainpages requires, and whether the fallback is the contract or a courtesy. The stylesheet needs `:has()` (Dec 2023); the menus need the popover API (Safari 17) and CSS anchor positioning for placement (newer still, and unguarded — the `@supports` test covers popover only). An iPadOS 16 tablet, capped at Safari 16, therefore gets panels flowing inline rather than working menus. Either state a supported floor or accept the fallback for those devices; nobody has rendered that path on real hardware.
-- [ ] Decide whether the profile dropdown still earns a dropdown. It holds one item, Sign out, behind a click, and its "Signed in as X" head repeats what the trigger already shows.
-- [ ] Trim whitespace around the verification code — a copy+pasted code from the email fails, today as a browser `pattern` refusal rather than a Kratos rejection, now carrying a digits-only hint so that refusal isn't bare. The paste still fails. **Own session.** No zero-JS fix exists: `pattern` is rejective and cannot transform, so loosening it only lets the untrimmed value through. The real fix is a host-side proxy of the flow POST, which is feasible and half-built — `submitFlow` (`src/auth/kratos-public.ts:132`) already relays cookies and normalises a 422 `redirect_browser_to`, and has no callers outside tests. CSRF improves rather than breaks: the host already writes Kratos' cookie onto its own origin (`src/auth/routes.ts:77`), so the POST becomes same-origin, and `form-action 'self'` could finally join the CSP. Two risks: one `flow.ui.action` serves all five flows, so this rewrites the sign-in path, not just code entry; and Go's nosurf checks Referer only over https, which no test here covers. **Check first:** `kratos-admin.ts:75` returns a `recovery_link` alongside the code — if the stock courier mail carries one (unverified), a template change fixes the UX with no host code. Code entry has no E2E coverage today either way.
-- [ ] Guard against the double-clicked submit, without client-side JavaScript. A non-technical user clicks a button twice when nothing happens fast enough, so a second identical POST is an expected event, not misuse — today it creates two users, mints two recovery codes, or registers two OAuth2 clients. Constraints: HTML/CSS only, and it must not break an action that is *legitimately* repeatable. Sketch: a CSS-only affordance so the second click has nothing to hit, paired with the host recognising a duplicate on the server — same session, route and payload within a short window — then logging and dropping it. Open questions: what identifies "the same submission" (a one-time token minted into each rendered form beats hashing the payload, and the CSRF plumbing already mints per-request tokens), the window length, where the record lives given the app is stateless, and how a plugin declares a route repeatable.
-- [ ] Decide the caching contract for rendered pages. Responses carry `Vary: Accept-Language` but nothing sets `Cache-Control`, so a shared cache has no instruction and a signed-in page is not marked `private`. Either set the headers deliberately (public cacheable, gated `private, no-store`) or record in AGENTS.md that the reverse proxy owns this.
-- [ ] Decide whether the single generic Keto `Resource` namespace should become per-domain namespaces (`Shift`, `Document`, …), as Ory's own examples model it. One global `Resource` bucket is the project's own "no catch-all names" rule applied to namespaces. A design question, not a naming one.
-- [ ] Decide what `ICON_NAMES` (`src/ui/icons.ts`) actually is. `i-chart`, `i-copy`, `i-download` and `i-sliders` have no caller anywhere — so either they go, or the comment should say the palette is curated and may carry an id ahead of its first use. Not cosmetic: the sprite is inlined into every page, and the rule decides whether a future removal is routine cleanup or a plugin-facing regression.
-- [ ] Decide (once) whether the CSRF token staying unbound to `sub`/session is accepted. `src/auth/csrf.ts` signs `<nonce>.<HMAC(secret, nonce)>` with no session binding, so any validly-signed token passes for any user — an attacker who can write cookies on the origin can fix a token they know. Standard for unbound signed double-submit and plausibly fine behind `SameSite=Lax` + HSTS. Accepted ⇒ record it in AGENTS.md and README → Security model; not accepted ⇒ bind the nonce to `sub`.
-- [ ] Verify the documented Docker commands on macOS and fix whatever misbehaves — **macOS is a supported dev host**, but nothing here has been run on one. Two suspects, both from the `--user "$(id -u):$(id -g)"` idiom: a macOS `id -g` is `20`, which is `dialout` inside the noble image rather than a user group, and Docker Desktop remaps bind-mount ownership in its own VM layer. The same question covers rootless Docker, where README already says to *drop* the flag.
-- [ ] Map Kratos' 401 on a self-service flow init, so an anonymous `GET /settings` with no `?flow` renders instead of 500ing. `flowPage` (`src/auth/routes.ts`) maps 403/404/410 → restart the flow, 400 `session_already_available` → `/auth/complete`, and ≥500 → the themed 503, then rethrows everything else — and Kratos answers the settings-flow init with 401 when there is no session. `/settings` is correctly `public` (the recovery flow lands there with a live Kratos session but no app JWT), so the gate is not the fix: a 401 should redirect to `/login` with the page as `return_to`. No E2E covers an anonymous hit on a flow page that needs a session.
+`Score = 100 * V / (2**S + 8)`
 
-### Architectural review findings (2026-07-02)
+`Bar = 1`
 
-Prioritized. Overall verdict: architecture is sound; these are refinements.
+`Next ID = 44`
 
-- [ ] **MEDIUM — Add complexity/method-size static analysis to the CI gate.** Only `tsc --strict` today; a size/complexity rule would have caught the `app.ts` growth.
-- [ ] **LOW — The users list offers a pencil "Edit" row action to a `users:read` holder.** The link is harmless (it opens the read-only detail page), but the label contradicts what the reader can do. Needs `canWrite` threaded into `listTable` plus a `common.view` core catalog key and an `i-eye` entry in `ICON_NAMES`.
-- [ ] **MEDIUM→LOW — Add a list-page view-model helper in `src/ui/`.** Every list screen hand-rewrites the same ~40 lines bridging `parseListQuery`/`paginate` to the EJS partials; at minimum a `buildPaginationModel(page, hrefFor)` block.
-- [ ] **LOW→MEDIUM — Retire `src/ui/shell-context.ts`.** `ShellModel`/`buildShellContext` has one consumer left (dashboard) and duplicates `PageChrome` on almost every field. Fold the dashboard onto `ctx.chrome` + title/breadcrumbs; keep `shellUser` as the shared primitive.
-- [ ] **LOW — Fix stale doc references to removed `docs/plugin-contract.md`** in `views/index.ejs` (user-visible dashboard text; also links /scheduling as if pre-installed) and `examples/plugins/scheduling/views/shifts.ejs`.
-- [ ] **LOW — Decide (once) on a `ctx.system` facade.** `@plainpages/plugin-api` exposes raw Ory client shapes, so an Ory client refactor is a major `apiVersion` bump. AGENTS.md accepts this; revisit only if external plugin authors appear.
-- [ ] **LOW — README/AGENTS.md gaps:** state the intended lifetime/horizon explicitly, add a short domain glossary (host, manifest, chrome, nav fragment, permission token, system plugin, denylist…), and note the expected plugin-author population and plugin count — per-plugin dependency isolation prices N dependency trees on disk and in RSS, and that number is what says whether the trade needs revisiting (build-time dedupe for baked images stays open).
+## Items
 
-## Finnished work
+| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | 0.4.21 |  | owner | **Publish every release to Docker Hub, and give the Hub page its short description.** | 3 | 3 | 2 | 6 | 5 | 1 by 3 | 1.3 |
+| 32 | 0.4.21 |  |  | **Fail the gate on a stylesheet feature the browser floor lacks, unless it is guarded.** | 4 | 2 | 2 | 6 | 7 | code health by 2 | 1.1 |
+| 13 | 0.4.21 |  |  | **Accept a verification code pasted with surrounding whitespace.** | 4 | 2 | 3 | 7 | 7 | 2 by 8 | 1.0 |
+| 19 | 0.5.0 |  | question | **Run the documented Docker commands on macOS and fix whatever misbehaves.** | 2 | 2 | 1 | 3 | 3 | 1 by 3 | 3.3 |
+| 16 | 0.5.0 |  | question | **Decide whether the single Keto `Resource` namespace splits into per-domain namespaces.** | 3 | 2 | 3 | 6 | 6 | 7 by 2 | 0.5 |
+| 6 | 0.5.0 |  |  | **Warn at discovery when a route or nav node gates on a permission no plugin declares.** | 2 | 1 | 1 | 2 | 2 | 7 by 3, 9 by 3 | 8.0 |
+| 23 | 0.5.0 |  |  | **Give list pages one view-model helper from query to pagination, instead of ~40 hand-written lines each.** | 3 | 1 | 2 | 4 | 5 | 1 by 4, 9 by 2, code health by 3 | 7.9 |
+| 43 | 0.5.0 |  |  | **Let a plugin version the scripts and other `/public/` files its own markup links, so they are cached as immutable too.** | 2 | 2 | 1 | 3 | 3 | 8 by 3, 7 by 2 | 5.0 |
+| 28 | 0.5.0 |  |  | **Let a plugin add entries to the profile menu through the plugin API.** | 2 | 2 | 2 | 4 | 4 | 7 by 4, 1 by 2 | 4.2 |
+| 2 | 0.5.0 |  |  | **Rename the admin example plugin to a name that says what it administers.** | 3 | 1 | 2 | 4 | 6 | 9 by 3, code health by 2 | 2.6 |
+| 5 | 0.5.0 |  |  | **List grants that no installed plugin declares, with a remove action.** | 2 | 2 | 2 | 4 | 4 | 2 by 3 | 2.1 |
+| 41 | 0.5.0 |  |  | **Apply a permission save as one Keto call, so it cannot stop part-way.** | 2 | 2 | 2 | 4 | 3 | 2 by 2 | 2.1 |
+| 14 | 0.5.0 |  |  | **Drop a double-clicked duplicate submit, with no client-side JavaScript.** | 4 | 2 | 3 | 7 | 7 | 2 by 7, 1 by 4 | 1.4 |
 
-- [x] Configure a plugin at install time: the manifest declares `settings`, the operator sets one `PLUGIN_SETTING_<ID>_<KEY>` variable per key, and the resolved values arrive on `onBoot` typed from the declaration. Read-only admin screen at `/admin/plugin-settings`.
-- [x] Give a plugin persistent storage: `storage: true` provisions a Postgres database + login role named `plugin_<id>`, credentials arrive on `onBoot`, passwords are derived from `PLUGIN_DB_SECRET` rather than stored.
-- [x] Refuse a stray `package.json`/`node_modules` in `config/` by name, as plugin folders already are.
-- [x] Let Renovate reach the example plugins' manifests (`ignorePaths` overrides `config:recommended`).
-- [x] The seeded admin is granted each permission once — `seedPermissions` dedupes and the grant PUT is idempotent.
-- [x] Run the E2E runner as the invoking user so its artifacts aren't root-owned.
-- [x] Install node_modules above `WORKDIR /app` so no mount leaves a root-owned dir in the checkout.
-- [x] Enforce `<resource>:<action>` permission names at discovery; split `admin` per screen.
-- [x] Make the declared-permission catalog the fixed list; delete the Permissions screen, move granting onto Users and Groups.
-- [x] Fail a Playwright test on any browser console warning, error or uncaught exception, in every engine.
-- [x] Skip the CI gate when only markdown changed.
-- [x] Replace the `<details>` popup menus with the Popover API so an outside click dismisses them.
-- [x] Organize the files in src into folders.
-- [x] Move docs/plugin-contract.md into README.md and remove the docs folder.
-- [x] Move the scheduling example out of `plugins/` into `examples/`.
-- [x] Make `config/` an empty drop-in mount with the defaults as fallback.
-- [x] Turn the built-in admin pages into a drop-in example plugin.
-- [x] CI/CD — test on push to any branch except main.
-- [x] CI/CD — require a PR to main, gated on a green build, fast-forward-only.
-- [x] CI/CD — force-push mirror to GitHub after every merge to main.
-- [x] CI/CD — build and push the app image, tagged with the commit hash, as part of the gate.
-- [x] CI/CD — re-tag the hash image to semver on a `vX.Y.Z` tag.
-- [x] CI/CD — sync released tags to Docker Hub.
-- [x] Write README-dockerhub.md for the Docker Hub overview.
-- [x] CI/CD — set up the Renovate bot.
-- [x] CI/CD — give Renovate a read-only `GITHUB_COM_TOKEN` so github.com lookups aren't rate-limited.
-- [x] CI/CD — auto-release on Renovate updates, versioned from the `Release-Bump:` trailer.
-- [x] Add an e2e test for the admin plugin's OAuth2-clients (Hydra) screen.
-- [x] Document the auth security model in the README.
-- [x] Add i18n support.
-- [x] Settle the identity-vs-user vocabulary.
-- [x] Use one uniform verb per action in the English UI (sign in / sign out / create account).
-- [x] Remove the dead "Profile" link from the sidebar profile menu.
-- [x] Remove the unspecified "Settings"/"Preferences" cog from the sidebar footer.
-- [x] **HIGH — Split `handleRequest` in `src/http/app.ts`** — extract the built-in endpoints into named handlers on an internal route table.
+## Details
+
+### 1. Publish every release to Docker Hub, and give the Hub page its short description.
+
+Hub's newest tag is 0.4.0, while git has v0.4.1 onwards, and the overview still says 0.4.0. No
+`release.yml` run exists for the tags auto-release pushes as `renovate-bot`; find out why Gitea
+doesn't fire `push: tags` for them, fix it, and backfill the missing tags. fejkdata did this
+(`../fejkdata`, commits `51d924a` and `34c8234`), and two parts port directly: a one-line
+description riding the existing PATCH as its `description` field, and a unit test that the
+description opens a README sentence and every command the overview shows appears in the README.
+fejkdata also syncs the page on any push to `main`, with its own token in an environment only `main`
+may use; decide whether that fits here, where `{{VERSION}}` must render a released tag.
+
+### 32. Fail the gate on a stylesheet feature the browser floor lacks, unless it is guarded.
+
+Nothing checks README → "Two browser floors", and no E2E engine is old enough to show a break.
+Lint every stylesheet, the examples' included, against Chromium 87, Safari 15 and Firefox 115, and
+allow a feature only inside an `@supports` that guards it.
+
+### 13. Accept a verification code pasted with surrounding whitespace.
+
+A pasted code fails the browser's `pattern` check. No zero-JS fix exists: `pattern`
+cannot transform, so loosening it only lets the untrimmed value through to Kratos. **Check first:**
+`kratos-admin.ts` returns a `recovery_link` alongside the code; if the stock courier mail can carry
+one, a template change fixes this with no host code. Otherwise proxy the flow POST through the host:
+`submitFlow` (`src/auth/kratos-public.ts`) already relays cookies and normalises a 422
+`redirect_browser_to`, and has no callers outside tests. CSRF improves, since the POST becomes
+same-origin and `form-action 'self'` can join the CSP. Risks: one `flow.ui.action` serves all five
+flows, so this rewrites the sign-in path; and Go's nosurf checks Referer only over https, which no
+test covers. Code entry has no E2E coverage today.
+
+### 19. Run the documented Docker commands on macOS and fix whatever misbehaves.
+
+Needs a Mac. Two suspects, both from `--user "$(id -u):$(id -g)"`: a macOS `id -g` is `20`, which is
+`dialout` inside the noble image, and Docker Desktop remaps bind-mount ownership in its VM.
+
+### 16. Decide whether the single Keto `Resource` namespace splits into per-domain namespaces.
+
+Ory's own examples model `Shift`, `Document` and so on. One global `Resource` bucket is the
+project's "no catch-all names" rule applied to namespaces.
+
+### 6. Warn at discovery when a route or nav node gates on a permission no plugin declares.
+
+Declaring stays optional on purpose, but the picker is built from declarations only, so such a route
+is ungrantable from the GUI and answers a permanent 403. A warning, not an error.
+
+### 23. Give list pages one view-model helper from query to pagination, instead of ~40 hand-written lines each.
+
+Every list screen bridges `parseListQuery`/`paginate` to the partials by hand. At minimum a
+`buildPaginationModel(page, hrefFor)`. Exported through the barrel, so it is contract surface.
+
+### 43. Let a plugin version the scripts and other `/public/` files its own markup links, so they are cached as immutable too.
+
+The host versions every `/public/` href it renders (`src/http/static.ts`): the shell's stylesheets,
+favicon and logo, and a plugin's `styles`. A file a plugin's own markup links, such as fastjira's
+`board-drag.js`, keeps an unversioned URL and is revalidated every five minutes. Offering a way —
+`assetHref` documented as a view local, a `ctx.assetHref`, or a `scripts` slot in the shell — adds to
+the plugin API, hence a minor. Pick one with the plugin authors' panel, then document it in README →
+Reserved view locals.
+
+### 28. Let a plugin add entries to the profile menu through the plugin API.
+
+The profile dropdown stays a dropdown: Sign out is its only entry today, and it will gain more.
+`views/partials/shell.ejs` hand-rolls it (AGENTS.md → UI, the dropdown rule), so the entries need a
+manifest field that discovery checks, gated like a nav node.
+
+### 2. Rename the admin example plugin to a name that says what it administers.
+
+Candidates: `auth-admin`, `users-groups-admin`. The id is also the mount path, so the compose files,
+E2E stacks and README move with it.
+
+### 5. List grants that no installed plugin declares, with a remove action.
+
+`grantDiff` never revokes an undeclared name, and nothing shows one either, so it can't be audited or
+cleaned, and reinstalling its plugin silently reactivates access nobody remembers granting.
+
+### 41. Apply a permission save as one Keto call, so it cannot stop part-way.
+
+`applyGrants` writes and deletes one tuple per request and reports a partial save when one fails.
+**Check first:** Keto documents `PATCH /admin/relation-tuples`, which should apply a list of inserts
+and deletes in one transaction; confirm that against the Keto version `ory/` pins. If so, add the
+call to `KetoClient`, which is contract surface (`@plainpages/plugin-api`) and so needs 0.5.0, and the
+partial-failure path in the admin example can go.
+
+### 14. Drop a double-clicked duplicate submit, with no client-side JavaScript.
+
+A second identical POST is expected from a non-technical user, and today creates two
+users, mints two recovery codes, or registers two OAuth2 clients. It must not break a legitimately
+repeatable action. Sketch: a CSS-only affordance so the second click has nothing to hit, plus the
+host recognising a duplicate (same session, route and payload within a short window), logging and
+dropping it. Open: what identifies "the same submission" (a one-time token minted into each form
+beats hashing the payload), the window, where the record lives given the host is stateless, and how
+a plugin declares a route repeatable.

views/403.ejs

@@ -7,7 +7,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title><%= t("error.403.docTitle") %></title>
-    <link rel="stylesheet" href="/public/css/styles.css" />
+    <link rel="stylesheet" href="<%= assetHref("/public/css/styles.css") %>" />
   </head>
   <body>
     <main>

views/404.ejs

@@ -7,7 +7,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title><%= t("error.404.docTitle") %></title>
-    <link rel="stylesheet" href="/public/css/styles.css" />
+    <link rel="stylesheet" href="<%= assetHref("/public/css/styles.css") %>" />
   </head>
   <body>
     <main>

views/500.ejs

@@ -7,7 +7,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title><%= t("error.500.docTitle") %></title>
-    <link rel="stylesheet" href="/public/css/styles.css" />
+    <link rel="stylesheet" href="<%= assetHref("/public/css/styles.css") %>" />
   </head>
   <body>
     <main>

views/503.ejs

@@ -7,7 +7,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title><%= t("error.503.docTitle") %></title>
-    <link rel="stylesheet" href="/public/css/styles.css" />
+    <link rel="stylesheet" href="<%= assetHref("/public/css/styles.css") %>" />
   </head>
   <body>
     <main>

views/error.ejs

@@ -7,7 +7,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title><%= t("error.flow.docTitle") %></title>
-    <link rel="stylesheet" href="/public/css/styles.css" />
+    <link rel="stylesheet" href="<%= assetHref("/public/css/styles.css") %>" />
   </head>
   <body>
     <main>

views/index.ejs

@@ -1,10 +1,8 @@
 <%#
-  Dashboard: the gated post-login app home. The built-in default is a short instructional
-  starter — what /dashboard is and how to replace it from a plugin. Composes the app shell (the one
-  global menu via model.nav) around the prose. A plugin owns the real dashboard via a `dashboard`
-  handler; this renders until then. Data: model { nav, shell }.
+  The built-in /dashboard starter, shown until a plugin's `dashboard` handler replaces it.
+  Data: chrome (PageChrome).
 %><%
-  const nav = include("partials/nav-tree", { nodes: model.nav });
+  const nav = include("partials/nav-tree", { nodes: chrome.nav });
   // These four messages carry markup (<code> spans), so they render raw — the documented
   // markup-carrying case. They interpolate nothing, so there is no untrusted data to escape.
   const body = `
@@ -27,12 +25,11 @@
 -%>
 <%- include("partials/shell", {
   body,
-  brand: model.shell.brand,
-  breadcrumbs: model.shell.breadcrumbs,
-  csrfToken: model.shell.csrfToken,
+  brand: chrome.brand,
+  breadcrumbs: [{ label: t("dashboard.title") }],
+  csrfToken: chrome.csrfToken,
   nav,
-  signInHref: model.shell.signInHref,
-  theme: model.shell.theme,
-  title: model.shell.title,
-  user: model.shell.user,
+  theme: chrome.theme,
+  title: t("dashboard.title"),
+  user: chrome.user,
 }) %>

views/oauth-consent.ejs

@@ -11,9 +11,9 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title><%= t("consent.title", { client: consent.client }) %></title>
-    <link rel="stylesheet" href="/public/css/styles.css" />
-    <link rel="stylesheet" href="/public/css/auth.css" />
-    <link rel="icon" href="/public/favicon.svg" />
+    <link rel="stylesheet" href="<%= assetHref("/public/css/styles.css") %>" />
+    <link rel="stylesheet" href="<%= assetHref("/public/css/auth.css") %>" />
+    <link rel="icon" href="<%= assetHref("/public/favicon.svg") %>" />
   </head>
   <body>
     <%- include("partials/icons") %>

views/partials/icons.ejs

@@ -5,13 +5,11 @@
   <symbol id="i-bell" viewBox="0 0 24 24"><path d="M10.268 21a2 2 0 0 0 3.464 0" /><path d="M3.262 15.326A1 1 0 0 0 4 17h16a1 1 0 0 0 .74-1.673C19.41 13.956 18 12.499 18 8A6 6 0 0 0 6 8c0 4.499-1.411 5.956-2.738 7.326" /></symbol>
   <symbol id="i-box" viewBox="0 0 24 24"><path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z" /><path d="m3.3 7 8.7 5 8.7-5" /><path d="M12 22V12" /></symbol>
   <symbol id="i-cal" viewBox="0 0 24 24"><path d="M8 2v3" /><path d="M16 2v3" /><rect x="3" y="3" width="18" height="18" rx="2" /><path d="M3 9h18" /></symbol>
-  <symbol id="i-chart" viewBox="0 0 24 24"><path d="M5 21v-6" /><path d="M12 21V3" /><path d="M19 21V9" /></symbol>
   <symbol id="i-check-circle" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /><path d="m16 9-5.5 5.5L8 12" /></symbol>
   <symbol id="i-chev" viewBox="0 0 24 24"><path d="m9 18 6-6-6-6" /></symbol>
   <symbol id="i-cols" viewBox="0 0 24 24"><rect width="18" height="18" x="3" y="3" rx="2" /><path d="M9 3v18" /><path d="M15 3v18" /></symbol>
-  <symbol id="i-copy" viewBox="0 0 24 24"><rect width="14" height="14" x="8" y="8" rx="2" ry="2" /><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></symbol>
-  <symbol id="i-download" viewBox="0 0 24 24"><path d="M12 15V3" /><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /><path d="m7 10 5 5 5-5" /></symbol>
   <symbol id="i-edit" viewBox="0 0 24 24"><path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z" /><path d="m15 5 4 4" /></symbol>
+  <symbol id="i-eye" viewBox="0 0 24 24"><path d="M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0" /><circle cx="12" cy="12" r="3" /></symbol>
   <symbol id="i-globe" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20" /><path d="M2 12h20" /></symbol>
   <symbol id="i-grid" viewBox="0 0 24 24"><rect width="7" height="7" x="3" y="3" rx="1" /><rect width="7" height="7" x="14" y="3" rx="1" /><rect width="7" height="7" x="14" y="14" rx="1" /><rect width="7" height="7" x="3" y="14" rx="1" /></symbol>
   <symbol id="i-kebab" viewBox="0 0 24 24"><circle cx="12" cy="12" r="1" /><circle cx="12" cy="5" r="1" /><circle cx="12" cy="19" r="1" /></symbol>

views/partials/nav-tree.ejs

@@ -1,8 +1,8 @@
 <%#
   Recursive nav tree. Each node: { label, href?, icon?, count?, current?, open?, children? }.
   Shape is orthogonal: header (children → disclosure toggle + nested <ul>) vs leaf (spacer),
-  and clickable (href → <a>) vs static (<span>). The CSS reveals children only when the
-  sibling .nav-disc is [open]. `root` picks the outer class.
+  and clickable (href → <a>) vs static (<span>). Where :has() works, the CSS reveals children
+  only when the sibling .nav-disc is [open]; elsewhere it shows them all. `root` picks the outer class.
 %><%
   const nodes = locals.nodes || [];
   const root = locals.root !== false;

views/partials/shell.ejs

@@ -10,7 +10,8 @@
   (theme-switch default), `user`, `breadcrumbs`, `csrfToken` (the Sign-out form's hidden field),
   `signInHref` (anonymous "Sign in" target; default /login). `menu` (default true) — set false to
   drop the sidebar and render a focused single-column page. `t`, `locale`, `dir` and `localeSwitch`
-  come from the host with every render (README → Languages).
+  come from the host with every render (README → Languages), as does `assetHref`, which versions a
+  /public/ href so the browser caches it (src/http/static.ts).
 %><%
   const brand = locals.brand || { name: "Plainpages" };
   const title = locals.title || ""; // topbar heading; empty ⇒ no topbar <h1> (the body owns it)
@@ -29,9 +30,9 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title><%= docTitle %></title>
-    <link rel="stylesheet" href="/public/css/styles.css" />
-    <% styles.forEach((href) => { %><link rel="stylesheet" href="<%= href %>" />
-    <% }) %><link rel="icon" href="/public/favicon.svg" />
+    <link rel="stylesheet" href="<%= assetHref("/public/css/styles.css") %>" />
+    <% styles.forEach((href) => { %><link rel="stylesheet" href="<%= assetHref(href) %>" />
+    <% }) %><link rel="icon" href="<%= assetHref("/public/favicon.svg") %>" />
   </head>
   <body>
     <a class="skip-link" href="#main-content"><%= t("shell.skipToContent") %></a>
@@ -45,7 +46,7 @@
       <% if (menu) { %>
       <aside class="sidebar" aria-label="<%= t("shell.sidebar") %>">
         <div class="brand">
-          <% if (brand.logo) { %><img class="brand-logo" src="<%= brand.logo %>" alt="" /><% } else { %><span class="brand-mark"><svg class="ico ico-sm"><use href="#i-box" /></svg></span><% } %>
+          <% if (brand.logo) { %><img class="brand-logo" src="<%= assetHref(brand.logo) %>" alt="" /><% } else { %><span class="brand-mark"><svg class="ico ico-sm"><use href="#i-box" /></svg></span><% } %>
           <span class="brand-name"><%= brand.name %></span>
           <% if (brand.sub) { %><span class="brand-sub"><%= brand.sub %></span><% } %>
         </div>