portal-mojo 0.2.8 → 0.2.9

package/README.md

@@ -9,6 +9,8 @@ npm install portal-mojo react react-dom react-router-dom @tanstack/react-query
 ```
 
 **Per-component reference docs (written for AI context): [`docs/`](docs/README.md).**
+**Upgrading from 0.2:** raw calls now reject a flat HTTP-200 refusal — see
+[Upgrading to 0.3](docs/client.md#upgrading-to-03).
 Live demos for everything: run `npm run dev:showcase` → **Develop → Components**.
 
 ## Subpath surfaces
@@ -63,18 +65,64 @@ are identical in both forms.
 
 ## What the consuming app must provide
 
-- **Theme tokens + component CSS.** Components render semantic classes
-  (`panel`, `chip`, `tbl`, …) styled by the app's `theme.css` under
+- **A CSS entry that imports the package stylesheet.** Components render
+  semantic classes (`panel`, `chip`, `tbl`, …). Their rules ship with the
+  package as `portal-mojo/styles.css`. In the app's Tailwind CSS entry, in
+  this order:
+
+  ```css
+  @import "tailwindcss";
+  @import "portal-mojo/styles.css";
+
+  :root { /* the app's tokens, light */ }
+  :root[data-theme="dark"] { /* the app's tokens, dark */ }
+  @theme inline { /* the app's own token-to-utility bridge, if it has one */ }
+
+  /* the app's own overrides, outside any layer */
+  ```
+
+  - **Import it from the CSS entry only**, never from TypeScript, and with
+    no `layer()` of your own. The file carries the package's Tailwind
+    `@source` and its own cascade layer. Both need the app's Tailwind pass,
+    and Tailwind rejects an `@source` inside a layered import.
+  - **No `@source` line for this package.** The stylesheet scans the
+    package's own markup, so utility classes used in package components are
+    generated without the app knowing the install path.
+  - **App rules always win.** Package rules sit in the `portal-mojo` cascade
+    layer, ordered after Tailwind's `utilities`. A rule the app writes
+    outside a layer beats a package rule whatever its specificity or order.
+    Package rules still beat Tailwind utilities.
+  - **`!important` is the exception.** For important declarations the layer
+    order runs backwards, so a package `!important` (a handful, in
+    `calendar`, `detailview`, `loading`, `admin-dns` and `core`) beats an
+    unlayered app `!important`. To override one, write the app rule with
+    `!important` inside one of Tailwind's layers, for example
+    `@layer components { … }`.
+- **Theme tokens.** The package ships no token values. The app declares
+  every name in `src/styles/required-tokens.json`, under
   `data-theme="light"` **and** `"dark"` (reference set:
-  `apps/portal/src/theme.css`).
-  This includes the `.guardrail*` rules behind `confirmGuardrail`
-  (reference: `apps/portal/src/theme/guardrail.css`) — the package ships no
-  CSS, so an app that opens a guardrail must carry that block.
-- **Tailwind scan of this package.** In an installed app's CSS:
-  `@source "../node_modules/portal-mojo/src";` (adjust the relative path from
-  that CSS file). Utility classes used in package components are generated by
-  the app's Tailwind pass. Monorepo development may scan
-  `../../../packages/portal-mojo/src` instead.
+  `apps/portal/src/theme.css`). `npm run verify:package` keeps that list
+  equal to what the package styles read.
+
+### Migrating from copied theme files
+
+Apps that copied the reference app's component CSS switch to the import:
+
+1. Delete the copied component files and the copied component body of
+   `theme.css` (everything that is not a token block or `@theme inline`).
+2. Keep the token blocks and `@theme inline`. Check them against
+   `src/styles/required-tokens.json`.
+3. Import `portal-mojo/styles.css` from the Tailwind entry, right after
+   `tailwindcss`, and drop any `@source` line that pointed at this package.
+4. Keep the app's own override files after it, outside any layer.
+5. Re-check every override. It now beats the package rule it targets
+   whatever its specificity or position, so an override that used to lose
+   now applies.
+
+An app that keeps its old copies beside the import still renders: the
+copies are unlayered and win. It just stops receiving package fixes for
+those rules until the copies go.
+
 - **bootstrap-icons.** Components emit `bi bi-*` classes; the app imports the
   icon font once.
 - **Providers.** Every shell supplies `QueryClientProvider` (spread

package/docs/DetailView.md

@@ -73,7 +73,8 @@ receives a viewport-height limit; page/embedded bodies have no modal minimum
 or maximum. At narrow container widths an in-flow section button expands the
 same filtered rail entries, including rich, zero and dot badges. No native
 select stringification or second top-layer overlay is involved. The chrome
-lives in `theme/detailview.css` in both consuming apps.
+lives in `packages/portal-mojo/src/styles/components/detailview.css` and ships in
+`portal-mojo/styles.css`.
 
 ## Permission-gated sections (fail-closed)
 
@@ -191,7 +192,7 @@ get rows. See [Admin modal policy](admin-modals.md) for lifecycle exceptions.
   cache.
 - **Badges are state, not commands** — to "setBadge", change the value
   your `badges` prop is built from.
-- The styles for the C1 chrome live in `apps/portal/src/theme/detailview.css`
+- The styles for the C1 chrome live in `packages/portal-mojo/src/styles/components/detailview.css`
   (`.rail-badge`, `.rail-dot`, `.dv-menu*`, `.dv-keep`) — tokens only,
   both themes.
 

package/docs/README.md

@@ -35,6 +35,8 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [admin-dns-certificates.md](admin-dns-certificates.md) | Certificate custody and ACME lifecycle — in-zone requests, delegation readiness, house gates, renewal-aware bounded polling, and the no-material boundary |
 | [admin-dns-registrar.md](admin-dns-registrar.md) | Domain search/quote/purchase, one-use token custody, durable-ledger reconciliation, scoped registrant PII, and manual House adoption |
 | [admin-storage.md](admin-storage.md) | Global S3 buckets, masked storage backends, explicit policy-backed File uploads, capability-safe FileView/shares, and finite rendition convergence |
+| [admin-media-rendering.md](admin-media-rendering.md) | Storage → Media rendering: the three FILEMAN_RENDITIONS_* settings as a descriptor-driven form — delta-from-defaults writes, inline 400 routing, reset by writing `{}` |
+| [admin-edge.md](admin-edge.md) | Edge vhosts by template kind with a shape-first wizard, `site_api` routes and their create order, declared upstreams, and the fleet blocklist with log-first modes. |
 | [admin-shortlinks.md](admin-shortlinks.md) | Global shortlink operations, destination-free caches, bounded click history, and reconciled one-shot mutations |
 | [admin-messaging.md](admin-messaging.md) | SES domains/mailboxes/sent/templates plus public contact requests, with write-only credentials and offline HTML previews |
 | [admin-phonehub.md](admin-phonehub.md) | Global Phone Hub: evidence-backed lookup, sanitized SMS audits, and write-only provider configuration |
@@ -88,8 +90,10 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 4. **Controlled inputs, one value pipeline.** A control can never display a
    value its state doesn't hold. Unknown option values fall back to a
    default WITH a `console.warn` — never to rendering nothing.
-5. **Both themes, day one.** Style with tokens from `apps/portal/src/theme.css`
-   (`--surface`, `--ink`, `--mute`, `--accent`, …) and verify under
+5. **Both themes, day one.** Component CSS lives in
+   `packages/portal-mojo/src/styles/`. Style with the app's tokens
+   (`--surface`, `--ink`, `--mute`, `--accent`, …; reference values in
+   `apps/portal/src/theme.css`) and verify under
    `data-theme="light"` AND `"dark"`.
 6. **django-mojo datetimes are epoch SECONDS** on the wire. `fmt.*` accepts
    them directly; do not `new Date(epochSeconds)` without ×1000.

package/docs/account.md

@@ -221,9 +221,10 @@ caller's preferences ▸ one "General" row.
    `onSignOut` both places). Lazy-load it if the shell entry is budgeted:
    `import('portal-mojo/account').then((m) => m.openAccountModal(props))`
    (apps/portal does this).
-2. Copy the CSS (the package ships none): `theme/account.css`, plus
-   `theme/user-admin.css` (API-key rows) and `theme/group-admin.css`
-   (`.ga-secret-*` token reveal) if the app doesn't already ship them.
+2. Import `portal-mojo/styles.css` from the app's Tailwind CSS entry and
+   declare the colour tokens. `account.css`, `user-admin.css` (API-key rows)
+   and `group-admin.css` (`.ga-secret-*` token reveal) ship in it; there is
+   nothing to copy. The showcase still carries its own copies.
 3. Mount `ModalHost` + `ToastHost`, and a fresh-auth handler (apps/portal's
    `FreshAuthHost`, registered through `setFreshAuthHandler`) inside the
    authenticated tree. Without a handler a 440 just fails with the

package/docs/admin-bouncer.md

@@ -110,9 +110,9 @@ accepted it. No batch or action endpoints are invented, so partial failures use
 ## Styling and showcase
 
 The package emits semantic `bouncer-*` classes and imports no application CSS.
-Consumers must include `theme/admin-bouncer.css` after the shared token
-definitions. The repository keeps matching leaf files in `apps/portal` and
-`apps/showcase`, consistent with the current intentional theme duplication.
+Its styles live in `src/styles/components/admin-bouncer.css` and ship in
+`portal-mojo/styles.css`; the app declares the tokens. The showcase still
+carries its own copy until it adopts the package stylesheet.
 
 The showcase's `AdminBouncerDemo` switches among the three real package pages
 so only one URL-backed top-level table is mounted at a time. Open signal/device

package/docs/admin-credentials.md

@@ -178,9 +178,10 @@ and confirmed rotation are explicit button actions.
 ## Styling contract
 
 Credential components render the existing semantic `ga-*` classes and never
-import an application stylesheet. A consuming portal or showcase must include
-the `group-admin.css` semantic rules in its theme entry, as the repository's
-`apps/portal/src/theme.css` and `apps/showcase/src/theme.css` do today.
+import an application stylesheet. The `ga-*` rules ship in
+`portal-mojo/styles.css`
+(`packages/portal-mojo/src/styles/components/group-admin.css`); a consuming
+app imports that one stylesheet from its Tailwind entry.
 
 ## Personal keys are separate
 

package/docs/admin-devices-geoip.md

@@ -34,7 +34,7 @@ import {
 Account-security triage: who logged in from a new country, what is this IP,
 and is this device shared across accounts. Demo: showcase → Admin →
 **Devices, logins & GeoIP**. Styles:
-`apps/{portal,showcase}/src/theme/admin-devices.css` (byte-identical).
+`packages/portal-mojo/src/styles/components/admin-devices.css`.
 
 ## Sections
 

package/docs/admin-dns-certificates.md

@@ -107,8 +107,8 @@ sticky delegation, staging, unconfigured, and malformed-response evidence.
 Its only custody fixture is a private `material_present` boolean; no PEM is
 stored or serialized.
 
-Portal and Showcase both import `theme/admin-dns-certificates.css`, which uses
-semantic tokens only. The executable demo is **Develop → Components → DNS
+`src/styles/components/admin-dns-certificates.css` ships in
+`portal-mojo/styles.css` and uses semantic tokens only. The executable demo is **Develop → Components → DNS
 certificates & ACME** with manager, viewer, platform-house, and unconfigured
 legs. Run:
 

package/docs/admin-dns-records.md

@@ -62,4 +62,4 @@ Confirmation shows identity, TTL, unchanged/removed/added values, and contextual
 
 The central mock is the only DNS state owner and mirrors id-less envelopes, global-versus-tenant authorization, active/provider/credential gates, complete replacement, Route 53 delete, GoDaddy floor/refusal/spent placeholders, Mojo, unknown records, and structured types. Mutation verification is mock-only. Live verification may read a zone and open/cancel an editor, but must never POST or DELETE DNS records.
 
-Both Portal and Showcase import `theme/admin-dns.css`; all colors use theme tokens. Run `npm run verify:admin-dns-records` with the orchestration-owned typecheck/build/browser pass.
+`src/styles/components/admin-dns.css` ships in `portal-mojo/styles.css`; all colors use theme tokens. Run `npm run verify:admin-dns-records` with the orchestration-owned typecheck/build/browser pass.

package/docs/admin-edge.md

@@ -0,0 +1,210 @@
+# Edge Admin
+
+```ts
+import {
+    EDGE_ADMIN_SECTION, VhostsPage, VhostDetail, VhostWizard, openVhostWizard,
+    UpstreamsPage, BlocklistPage, EdgeVhostModel, EdgeRouteModel,
+    EdgeUpstreamModel, EdgeBlocklistModel, buildVhostPayload,
+} from 'portal-mojo/admin';
+```
+
+The same names are on `portal-mojo/admin/infrastructure`.
+
+`EDGE_ADMIN_SECTION` contributes Infrastructure routes at `edge/vhosts` and
+`edge/upstreams` (or the same paths under an embedded `/system` mount). The
+fleet blocklist is a route of Network Security, at
+`security/network/edge-blocklist`. There are no record routes: a vhost opens in
+`modal.detail`.
+
+Consumer contract: django-mojo `mojo/apps/edge/`. The mock in
+`client/mock.ts` returns the same graphs and the same refusals, word for word
+where the server has words.
+
+## Permissions
+
+- Vhosts, routes, upstreams — view: `sys.view_dns | sys.manage_dns | sys.security`.
+- Vhosts, routes — change or delete: `sys.manage_dns | sys.security`.
+- Upstreams — switch on or off: `sys.manage_dns | sys.security`.
+- Upstreams — declare or retire: `me.is_superuser === true`. The server gate
+  is `require_platform_admin`, which also refuses API keys.
+- Blocklist — view: `sys.view_security | sys.manage_security | sys.security`
+  (`EDGE_BLOCKLIST_VIEW_PERMS`). This is wider than `SECURITY_VIEW_PERMS`: the
+  server lets `manage_security` view, and manage does not imply view on the
+  client, so the clause is spelled out.
+- Blocklist — change or delete: `sys.manage_security | sys.security`.
+
+A section gate and a route gate both apply. A security-only operator is denied
+every DNS-gated section, which is why the blocklist does not live under Edge.
+The blocklist has no group: a member-scoped grant and `?group=` open nothing.
+
+**House rows.** A vhost on a group-less domain is platform property. It never
+appears in a non-superuser's list, even with a global grant, and its detail,
+its routes and creating one are refused to everyone else. The vhost graphs
+carry `domain: basic`, which has no `group`, so house-ness cannot be read off a
+vhost row. The wizard's domain picker passes `group__isnull: false` for
+non-superusers so a house domain is never offered to someone who would be
+refused at Finish.
+
+## Endpoints
+
+| Address | Verbs | Notes |
+|---|---|---|
+| `/api/edge/vhost` (+`/<id>`) | list, read, create, update, delete | `list` graph for tables, `default` for one row |
+| `/api/edge/route` (+`/<id>`) | list, read, create, update, delete | `site_api` vhosts only; filter `vhost` |
+| `/api/edge/upstream` (+`/<id>`) | list, read, update | update writes `is_enabled` only; no create, no delete |
+| `/api/edge/upstream/declare` | POST | `{name, kind, host+port \| socket_path, group?}`; platform administrators |
+| `/api/edge/upstream/retire` | POST | `{upstream}`; disables, keeps the row; platform administrators |
+| `/api/edge/blocklist` (+`/<id>`) | list, read, create, update, delete | fleet-wide |
+
+## The four kinds
+
+The wizard never shows a kind dropdown over one long form. Its first step is
+four cards in plain words; the following steps show only that shape's settings.
+
+| Kind | Card | Needs | May carry | Refuses |
+|---|---|---|---|---|
+| `api` | API host | `upstream` | `quiet_paths`, `serve_static` | `spa`, `redirect_to` |
+| `site` | Static site or SPA | — | `spa` | `upstream`, `quiet_paths`, `serve_static`, `redirect_to` |
+| `site_api` | Site + API paths | routes | `spa`, `serve_static`, `quiet_paths` | whole-host `upstream`, `redirect_to` |
+| `redirect` | Redirect | `redirect_to` | — | everything else |
+
+`buildVhostPayload(draft, { create })` is the one place a draft becomes a
+request. It sends each knob the chosen kind does not carry as its empty value,
+so a draft that visited another shape cannot leak that shape's settings, and
+an edit that changes kind clears what the old kind held. It never sends
+`mojosec_policy`. A vhost that carries an edge evidence policy therefore cannot
+change kind, or its single-page-app switch on a `site`, from here: the server
+requires the policy's response class to match and refuses, and its message is
+shown.
+
+Shared rules, each mirrored by a validator in `edge/models.ts`:
+
+- `label`: empty serves the bare domain, `*` the wildcard, otherwise one DNS
+  label. The address (`server_name`) is derived, never typed.
+- `body_size_mb`: whole number, 1 to 4096, default 50. Not offered for a
+  redirect.
+- `pool`: must be one the deployment declares (`EDGE_POOLS`, default
+  `["default"]`). The refusal names the declared set.
+- `domain`: set once. An edit shows it read-only and never sends it.
+- `redirect_to`: a host name. No scheme, path, port or wildcard.
+- A route prefix or quiet path starts with `/`, uses letters, digits, `.`,
+  `_`, `-` and `/`, and has no `//` or `..`. A route prefix cannot be `/`.
+
+## What is checked when
+
+The server checks most things on every save. Two things are checked **only
+when the row is enabled**:
+
+- the certificate belongs to the vhost's domain and covers its address;
+- no other enabled row has the same domain and label.
+
+So a disabled row may hold a certificate that does not cover it yet, and may
+share a name with a live row. That is how a replacement is staged: create it
+disabled, then disable the old one and enable the new one. The wizard warns
+when the chosen certificate does not cover the address (`certificateCovers`,
+which knows that a wildcard covers exactly one label and never the apex) and
+still lets the row be saved disabled.
+
+## The create order for `site_api`
+
+A quiet path on a `site_api` vhost must sit under one of its route prefixes,
+and the server reads those prefixes from the stored row. A create that carries
+quiet paths is therefore always refused with "none declared". The only order
+that works is:
+
+1. create the vhost, **disabled** and without quiet paths;
+2. create its routes, one at a time;
+3. save the vhost once more with the quiet paths and the enablement the user
+   chose.
+
+The wizard does exactly this. Step 3 always runs, so the enable-time checks
+happen at the end and a failure part-way never leaves a live vhost with no
+routes. If a step is refused the wizard stays open and says which step and
+what already exists. Finishing again continues from there: it never posts the
+vhost a second time and never repeats a route that landed.
+
+The server will store an enabled `site_api` vhost with no routes. The wizard
+does not: at least one valid route is required at the settings step and again
+at review.
+
+In edit mode routes are read-only, with a pointer to the detail view, which
+owns adding, changing and deleting them. Changing a `site_api` vhost to
+another kind while it has routes is blocked with the count; the server refuses
+it too. Until the stored routes have been read, or if that read fails, the
+wizard does not judge quiet paths against them and leaves that to the server.
+
+## Vhost detail
+
+The detail follows the admin modal contract (`admin-modals.md`). The header
+switch enables and disables. Edit and Delete are in the header menu, shown
+only with the manage grant. Delete asks for confirmation, names the address,
+says its routes go with it, and points at Disable as the choice that can be
+undone. A refused enable shows the server's message in the overview. Routes
+are content: the Routes section lists them and owns add, change and delete.
+
+## Upstreams
+
+An upstream is a destination a vhost may proxy to. Only `is_enabled` can be
+written on one; its name and destination are fixed when it is declared. The
+list shows the active group's upstreams and the shared ones. Retiring disables
+the row and keeps it: vhosts and routes that reach it stop being served and
+are not repointed. The retire control names that consequence before it acts.
+The wizard's upstream pickers list enabled upstreams only.
+
+## Blocklist
+
+An entry matches an IP network or a user-agent pattern, in one of four modes:
+`log` (recorded, still served — the default), `enforce` (refused), `allow` (an
+exemption) and `off`. Create an entry in `log`, watch the edge watch log for
+it, then switch it to `enforce`. A change reaches the fleet in about ten
+minutes.
+
+An `ip` value is stored as its network: `10.1.2.3/8` is saved as `10.0.0.0/8`.
+The editor shows the saved value from the response.
+
+## Not built here
+
+- **Claim-reserved.** The plan for this page asked for a superuser control to
+  claim a reserved name. django-mojo removed the reserved-name mechanism, its
+  field and its action (commit `bc2c57b1`, in every release since v1.7.1), so
+  there is nothing for such a control to call.
+- **`mojosec_policy`.** Shown read-only on the vhost detail. It is set by the
+  platform and never sent from here.
+- **Web apps, releases and alias addresses.** An alias address appears in the
+  vhost list like any other row; `alias_of` is in no graph, so it cannot be
+  told apart, and a refused edit shows the server's message.
+
+## Pitfalls
+
+- Do not send `quiet_paths` on a `site_api` create. See the create order.
+- Do not treat a saved, enabled row as proof the certificate covers it from
+  the client check alone; the server's answer on save is the proof.
+- The mock's messages for database uniqueness (a second enabled vhost on one
+  name, a repeated route prefix, a repeated blocklist value, a repeated
+  upstream name) are the mock's own words. The server reports these from a
+  database constraint, and its wording was not measured.
+- The server parses a blocklist address with Python's `ipaddress` and compiles
+  a user-agent pattern with Python's `re`, and the mock follows Python, not
+  JavaScript: `010.1.2.3` and `\q` are refused, `10.0.0.0/255.0.0.0`,
+  `(?i)bot` and `a*+` are accepted. The reason after "does not compile" is the
+  mock's own wording. The editor's own check is only a first pass and never
+  compiles the pattern; the server's answer on save is the verdict.
+- A vhost update that names an upstream or certificate that does not exist is
+  refused by the mock with the same words as a missing one. The server's
+  wording for an unknown id was not measured.
+- The declare-upstream dialog and the blocklist editor refuse Escape and the
+  backdrop while their write is in flight, and the editor's save and delete
+  share one pending state. `npm run verify:admin-edge` holds each write open
+  and checks this.
+
+## Themes and showcase
+
+Styles live in `src/styles/components/admin-edge.css` and ship in
+`portal-mojo/styles.css`; the app declares the tokens. They are built from
+tokens only, so both themes render from one sheet. The showcase still carries
+its own identical copy until it adopts the package stylesheet. The showcase
+demo (Develop → Components → Admin → Edge) runs the shipped pages against the
+mock under five identities: platform administrator, DNS manager, DNS viewer,
+security manager and security viewer.
+
+`npm run verify:admin-edge` is the executable contract.

package/docs/admin-identity-directories-sources.json

@@ -25,8 +25,8 @@
       "source_path": "apps/portal/src/pages/ApiKeysPage.tsx",
       "source_sha256": "3d338cf77c3110b72a9361565c1cced10a7fccc52c486e3dafda119d66c676b2",
       "package_path": "packages/portal-mojo/src/admin/identity/users/PersonalApiKeysPage.tsx",
-      "package_sha256": "f377d8a97b5c0ccbce745c333fdd7e4a5fd5f5a89b868b058677b31e3efe64ff",
-      "adaptation": "Expanded row facts and actions are presented in a native DetailView modal that observes the current API key record."
+      "package_sha256": "0c1e1efd34f515e4b5dc994ce34be1446eb13d1486deea3e9641565215edb6ad",
+      "adaptation": "Expanded row facts and actions are presented in a native DetailView modal that observes the current API key record. Every list and export is pinned to the signed-in user with fixedParams, and the table is not mounted before that user is known."
     },
     {
       "source_path": "apps/portal/src/pages/GroupDetail.tsx",

package/docs/admin-identity-directories.md

@@ -54,6 +54,15 @@ revoke remains armed because it rotates the secret and cannot be undone. There
 is no delete action. This page does not use the separate group credential
 endpoint.
 
+The page lists the signed-in user's own keys only. The endpoint serves every
+user's keys to a caller holding `users` or `manage_users` who sends no `user`,
+so the page passes `fixedParams={{ user: me.id }}`: every list and export
+request carries it, and it cannot be cleared from the URL, a saved view or a
+preset. Until the signed-in user is loaded the page shows a placeholder and
+mounts no table, so no unscoped list or export can go out. An administrator
+reads another user's keys per user, in that user's detail under Users. Plain
+users reach their own keys in "My account".
+
 The Personal API Keys route was added to the package identity section registry
 alongside Users, Members, Groups, Credentials and Sign-in. Compatibility page
 paths in the reference app re-export the package-owned pages, and its menu and

package/docs/admin-identity-users.md

@@ -1,7 +1,7 @@
 # Admin Users
 
-Reusable global User administration for django-mojo. Consumers must include
-the semantic `user-admin.css` stylesheet used by the portal and showcase.
+Reusable global User administration for django-mojo. Its semantic
+`user-admin.css` stylesheet ships in `portal-mojo/styles.css`.
 
 ```tsx
 import {

package/docs/admin-jobs.md

@@ -52,7 +52,7 @@ stuck work, purge history — plus the cron-style scheduled tasks whose backend
 django-mojo has always shipped and whose admin page web-mojo never wired up.
 
 Demo: showcase → Admin → **Jobs engine**. Styles:
-`apps/{portal,showcase}/src/theme/admin-jobs.css` (byte-identical).
+`packages/portal-mojo/src/styles/components/admin-jobs.css`.
 Verifier: `npm run verify:admin-jobs`.
 
 Wire facts below come from django-mojo `mojo/apps/jobs/` (`models/job.py`,
@@ -424,6 +424,6 @@ from hand-built `JobsStats` objects (and, for `JobRunnersStrip`, a demo-only
 branched for the demo.
 
 Styles are semantic `jobs-*` classes, tokens only, both themes:
-`apps/{portal,showcase}/src/theme/admin-jobs.css`, imported from each app's
-`theme.css`. The verifier asserts the two copies stay byte-identical and that
-neither contains a raw hex colour.
+`packages/portal-mojo/src/styles/components/admin-jobs.css`, imported by the
+package's `src/styles/index.css`. The verifier asserts that import and that
+the file contains no raw hex colour.

package/docs/admin-media-rendering.md

@@ -0,0 +1,142 @@
+# Media rendering admin
+
+```ts
+import {
+    MediaRenderingPage, readRenditionOptions, findCategoryRows, valueToDraft, draftToValue,
+    validateDraft, routeRenditionError, saveCategoryValue, resetCategory, fieldType,
+    renditionRoleLabel,
+} from 'portal-mojo/admin/infrastructure';
+```
+
+Storage → Media rendering edits how django-mojo's fileman builds thumbnails,
+previews and transcodes, and which of those run after an upload. It is a form
+over three ordinary `Setting` rows — `FILEMAN_RENDITIONS_IMAGE`, `_VIDEO`,
+`_DOCUMENT` — built entirely from the backend's descriptor (django-mojo #7728,
+`docs/web_developer/fileman/renditions.md`). Nothing about roles, defaults,
+fields, choices or limits is hardcoded: a role the framework adds appears
+without a portal release.
+
+## Route and access
+
+`STORAGE_ADMIN_SECTION` registers `storage/rendering` (label "Media
+rendering") with the Settings page's gate, `sys.manage_settings | sys.groups`
+— the page writes Setting rows, so it carries the Setting write audience, not
+the storage one. The section audience includes those two grants so a
+settings-only operator can reach the page; the other storage routes keep their
+own clauses. Member grants never satisfy the gate.
+
+The descriptor itself (`GET /api/fileman/renditions/options`) is readable by
+`manage_settings | manage_files | files | groups`; a `files`-only operator can
+read it elsewhere but cannot open this editor.
+
+Global scope only. There is no group selector; group-scoped overrides stay on
+the generic Settings page.
+
+## Wire contract
+
+**Read:** `GET /api/fileman/renditions/options` → `data.categories.<image|video|document>`:
+
+| Field | Used for |
+|---|---|
+| `key` | the Setting key to write |
+| `defaults` | one row per role, in served order; the greyed values |
+| `automatic_default` | the "runs on upload" default set |
+| `override` | the global **database** row, parsed, or `null`. A deployment-file value is applied but not reported here |
+| `effective` | defaults with the override (and any file value) applied; shown only as a read-only "In effect: …" hint where it differs from the draft |
+| `role_kinds`, `fields`, `choices`, `limits` | which fields a role renders, their enum values and inclusive numeric bounds |
+
+`data.engine` is read-only on this page (`ffmpeg`; the key stays on Settings
+until a second engine exists).
+
+**Row lookup:** `findCategoryRows(key)` lists `/api/settings?key=<KEY>&group__isnull=true`
+with raw `mojoList` — `SettingModel.normalizeListParams` strips `key`, so the
+model's list hook cannot do this. More than one global row for a key disables
+Save and Reset with a notice naming the ids: `Setting.Meta.ordering = ["key"]`
+leaves the server's `.first()` undefined among duplicates, so editing one could
+change a row the renderer never reads.
+
+**Write:** the whole category as one object — `POST /api/settings` to create
+(`{key, is_secret: false, group: null, value}`) or `POST /api/settings/<id>`
+to update (`{value}`). The value is sent as an object; the server stores it as
+JSON text. Imperative `mojoSave` under `withFreshAuth`; a failure rejects.
+
+**Reset = write `{}`.** The live `Setting` model declares no `CAN_DELETE`, so
+`DELETE /api/settings/<id>` answers 403 — the backend doc's DELETE instruction
+does not work live. `{}` is the documented "defaults" value and the endpoint
+reports it as `override: null`; the row stays, harmlessly. Reset is disabled
+when there is no row or the override is already null.
+
+## Mapper invariants (`rendition-settings.ts`)
+
+- **Draft seeds from `defaults ⊕ override`**, never from `effective`. Seeding
+  from `effective` would mark a deployment-file value as changed on an
+  untouched form and copy it into a DB row on the first Save.
+- **`draftToValue` emits deltas against the defaults**, not against the
+  previous override: a field restored to its default disappears from the row.
+  Empty role objects are omitted; `{}` means defaults. Save is disabled when
+  the emitted value equals the current override.
+- **One typing rule, `fieldType(category, kind, name)`**: `choice` when
+  `choices[kind][name]` exists, else `number` when the name is in `limits`
+  (checked in that order — the server lists a bound for every option name it
+  limits anywhere in the category, so document `quality`, a choice on pdf
+  roles, also appears under `limits`), `boolean`
+  when a default of that kind holds a boolean (today `audio`), else `string`.
+  Inputs coerce on change through `coerceFieldValue`; `<input type=number>`
+  strings never reach the payload (the server refuses `"300"`).
+- **`_automatic`** is compared as a set and emitted only when it differs from
+  `automatic_default`, in default order with additions appended in `defaults`
+  key order (the renderer runs roles in list order). Roles the defaults do not
+  declare are dropped on read, as the server's `merge` does.
+- **The mp4-only trio** (`codec`, `crf`, `preset`) is the one rule not in the
+  descriptor: it is hidden and stripped from the payload while a role's format
+  (draft, else default) is not `mp4`. Switching the format back restores the
+  draft values. Format wins over codec, exactly as the server validates.
+- A field with no default (image `format`/`quality` — renderer class
+  attributes, not `default_renditions`) renders unset with a "renderer
+  default" placeholder; setting it emits it, clearing it omits it again.
+
+## Validation and the 400 slot
+
+`validateDraft` mirrors the server's checks with the server's wording (whole
+number / between min and max / one of … / `2000k or 2M` / `HH:MM:SS`). It is
+**advisory**: inputs carry `min`/`max`/`step`, the hint shows inline as the
+admin types, but Save stays enabled and the server decides. Gating on the
+client copy would make the 400 path unreachable and drift from the server.
+
+A refused save routes through `routeRenditionError(message, knownRoles)`:
+
+| Message | Lands |
+|---|---|
+| `<role>.<option>: …` | under that field, same slot as the hint |
+| `<role>: …` | under that role's row |
+| `_automatic: …` | beside the "runs on upload" switches |
+| anything else, or a role not on screen | the panel-level alert |
+
+Never a generic toast.
+
+## Mock
+
+`client/renditions-mock.ts` copies the renderers' `default_renditions`,
+automatic roles, `OPTION_SCHEMA`, limits and the error grammar verbatim.
+`describeRenditions(globalRows)` serves the descriptor from the mock's global
+Setting rows; `validateRenditionSetting(key, value)` runs on every
+`/api/settings` create/update whose key is a rendition key and answers
+`{status: false, error, error_code: 400}` before the row mutates. DELETE stays
+403. The mock seeds `FILEMAN_RENDITIONS_VIDEO = {"video_hevc": {"crf": 24}}`
+so a changed field sits beside greyed defaults on first load. Personas with
+the gate: `security.manager@nativemojo.com`, `showcase.operator@nativemojo.com`
+(password `mojo`).
+
+## Pitfalls
+
+- `DocumentRenderer` on django-mojo `main` (2026-10-10) has no
+  `config_category`, so `FILEMAN_RENDITIONS_DOCUMENT` is validated and
+  described but not yet applied by the renderer. The Documents tab ships per
+  contract; the override takes effect once the renderer honours it.
+- Changing options never touches existing files: open a file under Storage →
+  Files and use **Regenerate renditions** to see the result.
+- `video_hevc` is never automatic unless `_automatic` names it; H.265 costs
+  several times the H.264 encode time and does not play in every browser, so
+  keep `video_mp4` as the compatibility rendition (the Video tab says so).
+
+Verification: `npm run verify:admin-media-rendering`.