portal-mojo 0.2.8 → 0.2.10

package/docs/admin-modals.md

@@ -62,6 +62,7 @@ the inventory using `node scripts/verify-admin-modals.mjs --write-inventory`.
 | Storage/shortlinks | Bucket, FileManager, File, shortlink; owner/backend/test/CORS/upload/rendition/share | FileManager/shortlink/share active state; no File disable promise; bucket empty only |
 | Email/support | Domain, mailbox, sent message, template, contact; credentials/onboarding/audit/reconcile/test/template/status | Preserve evidence; separate mailbox directions and support status |
 | Phone/Push | Number, SMS, config, device, delivery, template; lookup/test/config editors | Config/template lifecycle; number/SMS/device/delivery evidence retained |
+| Edge | Vhost with nested routes; shape-first wizard, route editor, upstream declare/retire, blocklist entry editor | Vhost and upstream enabled state; upstreams retire and are never deleted; vhost, route and blocklist deletion are retained operations |
 | Assistant/settings | Conversation, Skill, Setting; feed continuation, scoped memory, typed settings editor | Owner-only continuation; Skill active selection; memory is scoped editing |
 
 ## Resource lifecycle matrix
@@ -84,6 +85,9 @@ the inventory using `node scripts/verify-admin-modals.mjs --write-inventory`.
 | Push config / template | Existing active selection with separate manage/test grants |
 | Assistant conversation | Retain history; no arbitrary REST save or invented archive |
 | Assistant Skill | Existing `is_active` save requires `sys.view_admin`; authoritative reload after mutation |
+| Edge vhost | Enable/disable from the header; Edit and Delete in the header menu. Disabling keeps the row and is how a replacement is staged |
+| Edge upstream | `is_enabled` only. Retire (platform administrators) disables and keeps the row; server `CAN_DELETE=False` |
+| Edge blocklist entry | Mode is the lifecycle: `off` parks an entry without losing it. Deletion is a retained operation |
 | Other logs/devices/history | Read-only by default, even where low-level REST supports DELETE |
 
 The public low-level exported delete APIs remain compatible. Built-in controls
@@ -101,6 +105,9 @@ conversation archival require backend work before new lifecycle UI is added.
 | DNS record-set removal | DNS manage gate, provider capability and record coordinator. Preview all values, apex/service impact and exact name/type; stale-state preflight and reconcile failures; no domain deletion |
 | Empty bucket | `sys.manage_aws OR sys.files`, then fresh auth; header to focused armed confirmation and exact case-sensitive bucket name. Removes objects, versions, markers and multipart uploads; retains bucket. Display partial/unknown outcomes and always refresh |
 | Jobs retention purge | `sys.manage_jobs OR sys.jobs`; dry-run estimate bound to normalized days/status plus generation. Editing/replacing preview resets arming. Ignore stale/unmounted responses; lock inputs/dismissal during execution. Report actual cutoff and cascade-inclusive counts; rejection requires another preview |
+| Edge vhost deletion | `sys.manage_dns OR sys.security`; house vhosts are platform administrators only. Header menu to a focused confirmation naming the address. Stops serving the name and deletes its routes with it; the confirmation points at Disable as the reversible choice |
+| Edge route removal | Same grant, inside the vhost's Routes content with an armed control naming the prefix. Requests under the prefix stop being proxied. A quiet path left without a covering route makes the vhost's next save fail, and the server's message is shown |
+| Edge blocklist entry removal | `sys.manage_security OR sys.security`; armed control in the entry's editor. The entry leaves every node within about ten minutes. `off` is the reversible choice |
 | Queue/consumer cleanup | Jobs manage grant, exact channel/scope and armed confirmation; queue clear sends `confirm:yes` only after consent and may cancel pending database jobs. Report partial outcomes |
 
 Other non-row removals retain their scoped editor semantics: rate-limit override

package/docs/admin-monitoring.md

@@ -93,7 +93,7 @@ current contract.
 ## Styling and showcase
 
 Monitoring components use semantic `monitoring-*` classes and application
-tokens only. A consuming app must include `admin-monitoring.css`. This repo's
-portal and showcase theme entries do so. The showcase's Admin Monitoring demo
-contains static request, response, JSON, and HTML-looking plain-text cases for
-both-theme verification without mutating a backend.
+tokens only. `admin-monitoring.css` ships in `portal-mojo/styles.css`. The
+showcase's Admin Monitoring demo contains static request, response, JSON, and
+HTML-looking plain-text cases for both-theme verification without mutating a
+backend.

package/docs/admin-network-security.md

@@ -33,8 +33,8 @@ Perimeter control: block an abusive IP right now, whitelist a customer's NAT,
 maintain country and datacenter CIDR sets synced to the firewall fleet, set
 geographic policy — and prove the policy does what you think with a built-in
 simulator before it bites real traffic. Demo: showcase → Admin → **Network
-security**. Styles: `apps/{portal,showcase}/src/theme/admin-network.css`
-(byte-identical).
+security**. Styles:
+`packages/portal-mojo/src/styles/components/admin-network.css`.
 
 ## Surfaces
 

package/docs/admin-phonehub.md

@@ -13,7 +13,10 @@ Import `PhoneHubPage`, the three individual pages, models, permission clauses, a
 - `PhoneConfigModel` reads sanitized scalar/default-graph rows. Saves and `test_connection` use imperative, cache-free calls. The editor follows web-mojo's provider-conditional layout: selecting Twilio, AWS SNS, or Mojo Remote shows and submits only that provider's connection fields. Mojo Remote uses `https://api.mojoverify.com` when the saved URL is unset or the editor is switched to Mojo; an explicitly configured custom URL is preserved. Secret inputs are DOM refs, not React or Query state: blank means untouched and is omitted; replacement must be non-empty; clear sends `null` only after a separate confirmation. Switching providers resets pending clears, and hidden provider credentials remain untouched. Responses are allowlisted before cache reconciliation. This surface edits existing provider credentials; it does not provision Django user/group API keys.
 
 Connection tests read the provider's `success` verdict, not the outer REST
-`status`. A failed or missing verdict is an error; `test_mode` is a warning
+`status`. The real wire answers the test flat (the action dict verbatim, as
+the mock now does too), so the call passes `refusal: 'return'`: a failed
+verdict is an answer for inline display, not a rejected request. A failed or
+missing verdict is an error; `test_mode` is a warning
 that the provider was not contacted. Results persist inside the detail modal
 on both sections, alongside a toast. Scope is labeled in the header and
 Connection section. Editing is disabled while a connection test is pending, so an old response

package/docs/admin-storage.md

@@ -8,8 +8,11 @@ import {
 ```
 
 `STORAGE_ADMIN_SECTION` contributes global/no-group Infrastructure routes at
-`storage/buckets`, `storage/backends`, and `storage/files` (or the same paths
-under an embedded `/system` mount). There are no record routes: buckets,
+`storage/buckets`, `storage/backends`, `storage/files` and `storage/rendering`
+(or the same paths under an embedded `/system` mount). `storage/rendering` is
+the Media rendering editor — see [admin-media-rendering.md](admin-media-rendering.md);
+it carries the Settings gate (`sys.manage_settings | sys.groups`), which the
+section audience therefore includes. There are no record routes: buckets,
 backends, nested files, and files use `modal.detail`.
 
 ## Permissions

package/docs/auth.md

@@ -28,6 +28,12 @@ onAuth('rotated', () => queryClient.invalidateQueries());  // same user, re-issu
 - JWT pair (`access_token`/`refresh_token`); single-flight refresh (3
   concurrent 401s → ONE refresh POST); pre-request gate throws a synthetic
   `AuthRequiredError` instead of firing doomed requests.
+- A temporary refresh failure (network, timeout or server unavailable) blocks
+  the protected request and rejects with the original transport error. It
+  keeps the session and emits `refresh-failed`, so cached workspaces can stay
+  open. Only expired/unusable credentials or confirmed refresh 401/403 emit
+  `unauthorized` and become `AuthRequiredError`. `refreshTokens()` still
+  resolves a boolean, and concurrent gated calls share one refresh POST.
 - `useAuthSnapshot()` → `{authenticated, uid, email}` — live, cross-tab.
 - `logout()` is client-side (django-mojo has no logout endpoint) and emits
   `'logout'`.

package/docs/calendar.md

@@ -101,7 +101,7 @@ Parse fns return `null` on invalid input, never throw; format fns return
 
 ## Styling
 
-`apps/portal/src/theme/calendar.css` — engine anatomy only
+`packages/portal-mojo/src/styles/components/calendar.css` — engine anatomy only
 (`mojo-calendar-*`: pane/head/nav/grid/weekday/cell + state classes), all
 colors via theme tokens; component tokens `--mojo-cal-anchor-fill`,
 `--mojo-cal-range-fill`, `--mojo-cal-range-fill-hover` (accent tints:

package/docs/client.md

@@ -34,6 +34,19 @@ status, semantic `error_code`, and structured safe failure evidence. Nothing out
 parses envelopes; `mojoCall(path, {method, params, body})` is the typed
 escape hatch for protocol modules and returns the unwrapped `Envelope`.
 
+**Replacement tokens.** An envelope may carry `tokens: {access_token,
+refresh_token}` beside `data`. django-mojo sends it when the request ended every
+other session of the caller's own account — today a save that changed the
+caller's own password (for example an admin using "Set password" on their own
+row). The tokens the request was sent with are already dead, so the boundary
+stores the new pair through the auth hook `tokensReplaced`, in the storage the
+session already lives in. Callers do nothing; the realtime socket reconnects
+with the new token. No `tokens` means no change. A token refresh that was in
+flight when the session was replaced is discarded when it answers, success or
+401: it was for the old session, and it neither overwrites the new pair nor
+reports it unauthorized. The same guard keeps a late refresh from signing a
+user back in after a sign-out.
+
 `FetchOpts.beforeSend` is an optional synchronous final validity check, invoked
 after the auth gate refreshes credentials and before headers/network activity.
 The packaged app uses it to recheck its source-generation binding at the cookie
@@ -45,6 +58,19 @@ shape. Modern envelopes use numeric top-level `code` plus a string semantic
 envelopes always reject. Structured `data` can contain deliberately safe
 recovery evidence, but callers must still avoid logging it indiscriminately.
 
+A handler's **flat refusal inside an HTTP 200** — a top-level
+`success:false`, as a model action answers — rejects too, on every call
+through the boundary (`mojoCall`, `mojoList`, `mojoGet`, `mojoSave`,
+`mojoDelete`, `mojoMetrics`, `mojoScopedCall`). It throws
+**`ActionRefusedError`**, a `MojoError` with `status: 200`, `message` = the
+server's `error` (or `message`) text, `errorCode` = the string refusal
+`code`, and `data`/`result.payload` = the full reply; a raw call's label is
+its request path. A wrapped `{status:true, data:{success:false}}` is **data**
+here — a successful POST can legitimately carry it. A call whose flat
+`success:false` is a real answer (a connection test) passes
+**`refusal: 'return'`** and reads the reply itself with `readActionResult`.
+See [Upgrading to 0.3](#upgrading-to-03).
+
 ## Functions
 
 | Fn | Wire | Returns |
@@ -62,6 +88,11 @@ desc; filters are Django lookups (`field`, `field__in=a,b`,
 triple is `dr_field/dr_start/dr_end`; datetimes serialize as epoch seconds;
 unknown params are silently ignored by the server.
 
+`mojoGet`, `mojoSave` and `mojoDelete` take an optional last argument,
+`{ unscoped?: boolean }` — the record-route opt-out from a registered
+endpoint scope (see "Record routes vs custom views" below). `defineModel`
+passes it for you.
+
 The executable mock coerces comparisons narrowly: both operands must be
 fully numeric for numeric comparison; temporal comparison only recognizes
 canonical `YYYY[-MM[-DD]]` or full ISO datetime shapes; everything else is
@@ -77,15 +108,21 @@ answer 440. Ordinary requests and real transports are unaffected.
 
 django-mojo POST_SAVE_ACTION handlers can refuse **inside an HTTP 200**, in
 two wire shapes — flat `{success:false, code, error}` or wrapped
-`{status:true, data:{success:false, …}}` — which the unwrap boundary
-deliberately passes through (envelope `status:false` is a different failure
-and already rejects). Never hand-sniff these shapes; there is one reader:
+`{status:true, data:{success:false, …}}`. The unwrap boundary rejects the
+flat shape for every call (see the envelope section above); the wrapped shape
+can be ordinary data on a successful POST, so only the action layer, which
+knows it posted an action, reads it as a refusal. `mojoAction` and
+`useAction` pass `refusal: 'return'` to unwrap and read the reply
+themselves, so their error names the action rather than the path (envelope
+`status:false` is a different failure and already rejects). Never
+hand-sniff these shapes; there is one reader:
 
 - `readActionResult(body)` → `{ok, code, error, payload}`. `payload` merges
   the envelope with the action dict (action fields win), so one-shot
   secrets/counters read from one place whichever direction they rode.
   Payload `status:false` (the `revoke_sessions` spelling) also refuses;
-  bodies with no flag resolve `ok: true`.
+  bodies with no flag resolve `ok: true`. A refusal with no string `error`
+  takes its text from a string `message`; numeric codes are ignored.
 - `mojoAction(endpoint, id, action, payload?)` — the raw-path primitive:
   POSTs `{[action]: payload ?? true}` to `endpoint/<id>` under
   `withFreshAuth`, normalizes the reply, and **REJECTS with
@@ -98,15 +135,18 @@ normalizer + cache maintenance; see defineModel.md "Action refusals" for
 `refusal: 'reject' | 'return'`); **raw one-off action POST →
 `mojoAction`**; **never** parse `success`/`status` off an action body at a
 call site. Diagnostics whose flag is a result datum (connection testers)
-either declare `refusal:'return'` on the model or stay as bespoke raw
-readers with a comment.
+either declare `refusal:'return'` on the model or, posted raw, pass
+`refusal: 'return'` to `mojoCall` and read the verdict with a comment.
 
 ## Endpoint scoping — the middle tier
 
-The model layer scopes reliably; everything hand-rolled with `useQuery` +
-`mojoCall` historically forgot the scope param — the largest bug class in the
-first consumer audit (eight files, every one a raw read or verb missing its
-`group`). The middle tier makes the raw path as safe as the blessed one:
+The model layer needs no scope on record routes — `<endpoint>/<id>` gets,
+saves, deletes and actions send none, because the server binds the row's own
+group (see "Record routes vs custom views" below). Everything hand-rolled
+with `useQuery` + `mojoCall` historically forgot the scope param — the largest
+bug class in the first consumer audit (eight files, every one a raw read or
+verb missing its `group`). The middle tier makes the raw path as safe as the
+blessed one:
 apps *declare* their scoped endpoint families once, and every helper —
 plus a dev tripwire in the transport itself — enforces the declaration.
 
@@ -130,13 +170,62 @@ query, below); `required: false` families only inject when a group is active.
 
 ### Where the group id comes from
 
-`GroupProvider` **owns** the active group — context stays the React-side
-source of truth — and mirrors its *resolved* group into a module-level
-signal (`setActiveGroupSignal` / `getActiveGroupId`) so plain functions can
-read it. Do not read `localStorage.active_group_id` yourself instead: the
-URL `?group=` param BEATS the stored id (group.tsx resolution order), and
-only the provider computes that resolution — the signal always reflects it.
-An explicit `group` option on any helper beats the signal.
+`GroupProvider` **owns** the active group. Three rules decide which group a
+request carries:
+
+1. **Hooks read the group context.** `useScopedQuery`, `useCan` and
+   `CollectionSelect` take the group from `GroupContext` at render time.
+   Under a mounted `GroupProvider`, `useScopedQuery` uses the context and
+   nothing else: a null context group means *no group*, never "whatever the
+   signal still holds". Only with no provider mounted at all does it fall
+   back to the signal.
+2. **Plain functions read the signal.** `mojoScopedCall` and `mojoRpc` have
+   no React context, so the provider mirrors its *resolved* group into a
+   module-level signal (`setActiveGroupSignal` / `getActiveGroupId`). It
+   writes the signal in the **layout phase** of the commit, before any child
+   query starts its fetch, so the first request after a group switch already
+   carries the new group.
+3. **An explicit `group` id wins everywhere**, on hooks and plain functions
+   alike. `group: null` differs: on `useScopedQuery` it means "unscoped by
+   choice"; on `mojoScopedCall` and `mojoRpc` a null `group` is treated as
+   not passed and the signal is used.
+
+Do not read `localStorage.active_group_id` yourself: the URL `?group=` param
+BEATS the stored id (group.tsx resolution order), and only the provider
+computes that resolution.
+
+**Recommended default**
+
+- Reads: `useScopedQuery`.
+- Writes and other calls from event handlers: `mojoRpc` / `mojoScopedCall`.
+- A query you write by hand with `useQuery`: put the group id in its key
+  (`['things', group?.id]`). The package cannot key a hand-rolled query for
+  you, and a key without the group serves one group's rows to the next.
+
+**While the group is resolving.** At boot, or on a switch the cache was not
+seeded for (`?group=`, or the fallback after a failed load), the provider
+reports `loading` with a null group. `useScopedQuery` holds a registered
+query, required or optional, **disabled** for that window, so nothing goes
+out under the previous group or unscoped. A query given an explicit `group`
+option is not held: it has nothing to wait for. A plain `mojoScopedCall` in the
+same window sees an empty signal: a required family throws in dev and an
+optional one goes out unscoped, exactly as at boot. Gate on `loading` or
+render under `RequiresGroup`.
+
+**Upgrading.** A blanket "invalidate everything when the group changes" is
+no longer needed for `useScopedQuery`, nor for hand-rolled queries whose key
+carries the group id.
+
+**Caveats**
+
+- A child's own `useLayoutEffect` runs before the provider's and still sees
+  the previous group in the signal. Use a hook, or pass `group` explicitly.
+- A fetch started during render (`useSuspenseQuery`, `fetchOptimistic`) runs
+  before the commit, so the signal is not yet current. Pass `group`
+  explicitly.
+- Signed out with a stored group, the provider is not `loading`, so an
+  optional family can fire once unscoped and again after sign-in. Scoped
+  product routes sit behind `RequireAuth`; nothing is held for this case.
 
 ### `useScopedQuery<T>(path, params?, {read?, group?, ...queryOpts})`
 
@@ -146,7 +235,8 @@ request params, and the group id rides the query key —
 cached rows, while invalidation by `[path]` prefix keeps working. Keep that
 key discipline if you write a raw scoped query by hand.
 
-When a REQUIRED scope has no active group, the query renders **disabled** —
+While the provider is still resolving its group, a registered query with no
+explicit `group` is held disabled (see above). When a REQUIRED scope has no active group, the query renders **disabled** —
 and a disabled query has *neither data nor error*. Do not draw an empty box
 or a spinner that never resolves: state the wait honestly at the call site
 ("select a brand to load …").
@@ -161,14 +251,21 @@ or a spinner that never resolves: state the wait honestly at the call site
   `withFreshAuth` with the scope injected; resolves `env.data as T`.
   Action-shaped `{key: payload}` saves belong to `mojoAction`, not here.
 
-### `mojoAction` body injection
+### `mojoAction` sends no scope
+
+`mojoAction(endpoint, id, action, payload?)` posts exactly
+`{[action]: payload}` to `<endpoint>/<id>` and never adds a scope key, on any
+family, with or without an active group. Two reasons:
+
+- A REST record route needs no group. django-mojo authorizes the request
+  against the **row's own** group, whatever the caller sends.
+- A `group` in the body is not only a selector there: the save handler
+  writes it as the row's `group` field, and its presence turns the action
+  into a full field save. An action on a record read outside the active
+  group could move that record to the active group.
 
-`mojoAction(endpoint, id, action, payload?)` consults the same registry:
-for a scope-registered family with an active group, the scope key is
-injected into the action POST body alongside `{[action]: payload}` — the
-wallet-verbs class: actions the backend refuses for brand-scoped operators
-without `group`. With nothing registered (the base admin) the injection is
-inert.
+The call is declared `unscoped: true`, so it passes the dev tripwire on a
+registered-REQUIRED family. Earlier versions injected the scope here.
 
 ### The dev tripwire — and `unscoped: true`
 
@@ -182,6 +279,25 @@ for the rare genuinely-global call to a scoped family, mark it
 skip the check (`import.meta.env.DEV` only); it is a development tripwire,
 not a runtime gate.
 
+### Record routes vs custom views
+
+Two kinds of URL end in an id, and only the caller knows which it has:
+
+- **REST record routes** — the model's own `<endpoint>/<id>` (get, save,
+  delete, POST_SAVE_ACTIONS). The server binds the row's group; send no
+  scope. `defineModel`'s record hooks, the generic `useModel` and
+  `useSaveModel` (with an id) and `mojoAction` already declare these
+  `unscoped: true`. A raw call to one does the same:
+  `mojoGet(endpoint, id, { unscoped: true })`.
+- **Custom views on a record path** — `requests/<id>/resend`, a download by
+  id, any view the backend gates with a group permission decorator. These
+  read the group from the request and **do** need it: keep using `mojoRpc` /
+  `mojoScopedCall` / `useScopedQuery`, which inject it.
+
+No path rule can tell the two apart, so the tripwire does not try. A
+collection create (`POST <endpoint>`) is not a record route: the group on
+the request decides where the new row lands, so pass it in the body.
+
 ## Mock admin contracts
 
 The mock carries measured GroupView/admin transports, not UI-shaped
@@ -313,7 +429,7 @@ confirm `completed` before the task returns success. Completed scalar
 ## `mojoQueryDefaults()`
 
 Spread into the app's `QueryClient` defaults. Provides: no retry on 4xx
-`MojoError`s (deterministic failures), `networkMode: 'always'` under the
+`MojoError`s or `ActionRefusedError` (deterministic failures), `networkMode: 'always'` under the
 mock ('online' live), and `refetchOnWindowFocus: false` (freshness comes
 from explicit refresh + opt-in autoRefresh — focus storms read as phantom
 fetches).
@@ -325,3 +441,20 @@ fetches).
   the semantic wire code, and `data` preserves safe structured evidence.
 - `AuthRequiredError` — thrown by the pre-request gate when a request needs
   a session that doesn't exist (synthetic 401; no network was touched).
+
+## Upgrading to 0.3
+
+0.3.0 is a breaking minor release: a raw call through the unwrap boundary
+now **rejects** a flat HTTP-200 refusal (top-level `success:false`) with
+`ActionRefusedError` instead of resolving it.
+
+- Find raw `mojoCall` / `mojoScopedCall` sites that read a top-level
+  `.success`. Those refusal checks are now dead code: delete them. Their
+  `catch` receives `ActionRefusedError`, which is a `MojoError`, so existing
+  `instanceof MojoError` handling keeps working.
+- A call whose flat `success:false` is a real answer, such as a connection
+  test, adds `refusal: 'return'` and keeps reading the reply.
+- Reads of a wrapped `data.success` are unaffected.
+- `err.errorCode` carries the refusal code and `err.data` the full reply, so
+  the server's reason is no longer lost.
+- `defineModel` actions and `mojoAction` behave as before.

package/docs/collection-multiselect.md

@@ -113,5 +113,5 @@ Sorting is the server's default unless `defaultParams` carries `sort`.
   a permanently empty picker in global context.
 - The dropdown's trigger/footer classes (`.multiselect-trigger`,
   `.multiselect-footer`, `.multiselect-done`) live in
-  `multiselect-dropdown.css` — consuming apps must import it alongside
-  `collection-multiselect.css` (the reference `theme.css` imports both).
+  `multiselect-dropdown.css` — `portal-mojo/styles.css` imports it alongside
+  `collection-multiselect.css`.

package/docs/combobox.md

@@ -101,5 +101,5 @@ strings.
   to the label, duplicating every row — not carried).
 - The dropdown is mounted in the shared top-layer Popover, so overflow
   containers and native dialogs do not clip it.
-- Styles live in `apps/portal/src/theme/combobox.css` (tokens only, both
-  themes); consuming apps must include it.
+- Styles live in `packages/portal-mojo/src/styles/components/combobox.css` (tokens only, both
+  themes) and ship in `portal-mojo/styles.css`.

package/docs/dataview.md

@@ -11,7 +11,7 @@ Point it at any record and get a sensible detail grid. Field **names** and
 **values** together pick the renderer, nested objects become nested grids,
 and anything that isn't a scalar lands in a JSON block with copy and
 collapse. Port of web-mojo `src/core/views/data/DataView.js` (1,153 lines).
-Styles: `apps/portal/src/theme/dataview.css`. Demo: **Develop → Components →
+Styles: `packages/portal-mojo/src/styles/components/dataview.css`. Demo: **Develop → Components →
 DataView**.
 
 ## DataView vs KnownFieldsCard

package/docs/datepicker.md

@@ -144,8 +144,8 @@ lean on the per-precision default.
 
 ## Styling
 
-`apps/portal/src/theme/datepicker.css` — trigger, clear ✕, popover content
-box, inline host. The grid itself is `theme/calendar.css` and the floating
-surface is `theme/popover.css`; this file adds nothing they already cover.
+`packages/portal-mojo/src/styles/components/datepicker.css` — trigger, clear ✕, popover content
+box, inline host. The grid itself is `components/calendar.css` and the floating
+surface is `components/popover.css`; this file adds nothing they already cover.
 Trigger metrics follow the house control (`.input`): `--surface2` fill,
 `--line` border, 8px radius, accent focus ring. Tokens only, both themes.

package/docs/daterange.md

@@ -164,7 +164,7 @@ carry them when the registry lands:
   `inline` is fluid to its host. Two panes + rail ≈ 850px — don't mount
   two-pane popovers inside narrow scroll containers, and keep dialogs on
   `months={1}`.
-- Styling lives in `apps/portal/src/theme/daterange.css` (trigger
+- Styling lives in `packages/portal-mojo/src/styles/components/daterange.css` (trigger
   `.mojo-daterange-*`, rail `.mojo-calendar-preset*`), tokens only, both
   themes; the calendar grid ships in `calendar.css`, the popover shell in
   `popover.css`.

package/docs/datetimepicker.md

@@ -222,7 +222,7 @@ not `new Date(epochSeconds)` without `× 1000`.
 
 ## Styling
 
-`apps/portal/src/theme/datetimepicker.css` — layout glue only
+`packages/portal-mojo/src/styles/components/datetimepicker.css` — layout glue only
 (`mojo-datetime-*`: `trigger` / `trigger-text` / `trigger-clear` /
 `popover-inner` / `row` / `cal-col` / `time-col` / `time-head` / `tz-row` /
 `tz-label` / `tz-host` / `foot`), tokens only, both themes. The grid, the

package/docs/defineModel.md

@@ -28,11 +28,11 @@ export const UserModel = defineModel<User>({
 | Member | Behavior |
 |---|---|
 | `useList(params?, {enabled?})` | `useQuery` list under key `[endpoint, params]` with `keepPreviousData`; `enabled:false` suppresses permission-hidden background reads |
-| `useOne(id \| null)` | one record, key `[endpoint, 'one', id]`; disabled while `id` is null |
-| `useSave()` | mutation `{id, changes}`; `id: null` creates. Handles one fresh-auth 440/retry, then writes the returned row into the one-record cache and invalidates `[endpoint]`. REJECTS on failure |
-| `useDelete()` | mutation `{id}`; removes the one-record cache entry + invalidates |
-| `useAction(name)` | mutation for ONE declared POST_SAVE_ACTION (below), with one fresh-auth 440/retry. THROWS at render time for an undeclared name |
-| `fetchOne(queryClient, id)` | imperative fetch through the same cache key — dedupes with mounted `useOne`s (prefetch pattern) |
+| `useOne(id \| null)` | one record, key `[endpoint, 'one', id]`; disabled while `id` is null. Sends no group scope |
+| `useSave()` | mutation `{id, changes}`; `id: null` creates. Handles one fresh-auth 440/retry, then writes the returned row into the one-record cache and invalidates `[endpoint]`. REJECTS on failure. With an id it sends no group scope; a create sends only your `changes` |
+| `useDelete()` | mutation `{id}`; removes the one-record cache entry + invalidates. Sends no group scope |
+| `useAction(name)` | mutation for ONE declared POST_SAVE_ACTION (below), with one fresh-auth 440/retry. THROWS at render time for an undeclared name. The body is exactly `{[key]: payload}`; sends no group scope |
+| `fetchOne(queryClient, id)` | imperative fetch through the same cache key — dedupes with mounted `useOne`s (prefetch pattern). Sends no group scope |
 | `invalidate(queryClient)` | invalidate everything under `[endpoint]` |
 | `keys.root / keys.list(params) / keys.one(id)` | key builders for targeted cache surgery |
 
@@ -45,6 +45,35 @@ only on final success. Delete remains unwrapped, as do direct `mojoCall`
 mutations; callers opt those in only when the endpoint is both sensitive and
 safe to retry once.
 
+## Group scope
+
+In a group portal an app registers its scoped endpoint families
+(`registerEndpointScope`, [client.md](client.md)). The model layer treats
+its two kinds of call differently:
+
+- **Record calls send no group.** `useOne`, `fetchOne`, `useSave` with an
+  id, `useDelete` and `useAction` all hit `<endpoint>/<id>`. django-mojo
+  authorizes those against the row's own group, so a client group adds
+  nothing — and a `group` in a save or action body is written to the row as
+  its `group` field. The hooks declare these calls `unscoped: true`, so a
+  registered-REQUIRED family never blocks them in development.
+- **A create sends only your `changes`.** `useSave` with `id: null` posts to
+  the collection, where the request's group decides where the row lands.
+  Put the group in `changes` yourself; on a REQUIRED family the dev tripwire
+  stops a create that carries none.
+
+List reads (`useList`) are scoped only by the params you pass.
+
+**Upgrading.** Record calls used to be stopped by the dev tripwire on a
+REQUIRED family, and `mojoAction` used to inject the group. If your portal
+grew a local wrapper to get past that — one that adds the group to an
+action or save on a record, or refuses to send when the active group
+changed since the record was read — delete it and call `M.useAction(verb)`
+(or `mojoAction`) directly. Remove any hand-added `group` from record-path
+bodies and params: it is at best ignored and at worst rewrites the row's
+group. Custom views on a record path (`<id>/resend`) are not model calls and
+keep their scope through `mojoRpc`.
+
 ## POST_SAVE_ACTIONS
 
 Backend contract (`mojo/models/rest.py on_rest_save`): an action is a key
@@ -75,8 +104,12 @@ reaches the client in one of two wire shapes:
 ```
 
 This is NOT the envelope failure: envelope-level `status:false` already
-rejects at the unwrap boundary (`MojoError`). The action-refusal layer sits
-above it and is handled by `useAction` automatically:
+rejects at the unwrap boundary (`MojoError`). Since 0.3 unwrap also rejects
+the flat shape for raw calls; `useAction` opts out of that check
+(`refusal: 'return'` on its own request) so the error names the action and
+honours the model's declared mode. No behaviour change for models. The
+action-refusal layer sits above the boundary and is handled by `useAction`
+automatically:
 
 - **`refusal: 'reject'` (default)** — a `success:false` (or payload
   `status:false`) reply REJECTS with **`ActionRefusedError`**, so a refusal

package/docs/detail-primitives.md

@@ -10,7 +10,7 @@ Six small pieces admin record pages are composed from, ported from
 web-mojo's `src/core/views/data/*` primitives plus its admin metadata
 section. They are presentational and stateless (except `MetadataSection`,
 which writes) — drop them inside a `DetailView` section, a `panel`, or a
-`modal.detail`. Styles: `apps/portal/src/theme/detail-primitives.css`.
+`modal.detail`. Styles: `packages/portal-mojo/src/styles/components/detail-primitives.css`.
 
 **All three trusted-HTML slots are gone.** web-mojo rendered
 `StatusPanel.meta`, `FlowStrip.value/hint` and `Timeline.detail` as

package/docs/feedback.md

@@ -73,10 +73,10 @@ disable, member `manage_group` / `manage_members` grants (through
 which of the watched keys changed (null/'' normalised), so a save confirms
 ONLY the fields that break things and passes silently otherwise.
 
-Styles: `apps/portal/src/theme/guardrail.css` (`.guardrail`,
+Styles: `packages/portal-mojo/src/styles/components/guardrail.css` (`.guardrail`,
 `.guardrail-effect/-why/-why-head/-undo/-type`, `.guardrail-icon`) over
-`--bad/--bad-soft` (danger) and `--warn/--warn-soft` (`danger: false`). The
-package ships no CSS — a consuming app carries that block (README).
+`--bad/--bad-soft` (danger) and `--warn/--warn-soft` (`danger: false`). It
+ships in `portal-mojo/styles.css`; the app declares the tokens (README).
 
 ## modal.drawer
 
@@ -112,7 +112,7 @@ title · meta) is web-mojo's `Modal.drawer()` carried over.
   otherwise there is no exit at all, so it falls back to dismissable with a
   `console.warn` (house rule: degenerate input → default + warn).
 - An unknown `width` warns and falls back to 480px.
-- Styles: `apps/portal/src/theme/drawer.css` (`.mojo-drawer`, `.drawer-panel`,
+- Styles: `packages/portal-mojo/src/styles/components/drawer.css` (`.mojo-drawer`, `.drawer-panel`,
   `.drawer-head/-eyebrow/-title/-meta`, `.drawer-body`) — tokens only, both
   themes. `DRAWER_EXIT_MS` in `modal.tsx` must match the closing keyframes.
 
@@ -139,10 +139,11 @@ and drawers), then returns to the page when the last modal closes. Modal-local
 ancestry keeps Undo and progress Cancel usable despite native dialog inertness.
 Moving the host preserves card state and timers and does not focus the toast.
 Mount it once; do not add per-dialog toast hosts or solve this with `z-index`.
-Custom app themes must include the updated toast CSS from
-`apps/portal/src/theme.css`: reset the popover's UA inset/margin/border/padding
-and background, hide closed popovers, and keep only the cards pointer-active.
-Updating the TypeScript package alone does not update a consumer's own theme.
+The toast CSS ships in `portal-mojo/styles.css`
+(`packages/portal-mojo/src/styles/core.css`): it resets the popover's UA
+inset/margin/border/padding and background, hides closed popovers, and keeps
+only the cards pointer-active. An app that still carries a copied theme keeps
+its old toast rules until it deletes the copy.
 The showcase's **Toasts inside modal** demo covers errors, Undo, progress,
 and nested opening/closing. `node scripts/verify-toast-modal.mjs` checks the
 mounted lifecycle; native visibility and interaction require browser checks.

package/docs/file-upload-ux.md

@@ -140,7 +140,7 @@ npm run verify:record-attachments
 
 It covers pure validation, lazy concurrency, capacity, stable/safe snapshots,
 consumer/destination dedupe, real progress updates, callback-only retry,
-truthful cancellation, known-id recovery, and byte-identical Portal/Showcase
-token CSS. The form contract adds strict relation normalization, explicit
+truthful cancellation, known-id recovery, and the package stylesheet importing
+the upload CSS. The form contract adds strict relation normalization, explicit
 attach states, owner-response reconciliation, orphan retention, safe previews,
 avatar #1488 semantics, and cache-boundary sanitization.

package/docs/idioms.md

@@ -47,7 +47,7 @@ Behavior contract (dom.js `armedButton` parity):
   live trigger). Fail-safe cost is one extra click, never an unintended fire.
 - Clicks `stopPropagation()` — safe inside clickable rows / expand rows.
 
-Styling: `apps/portal/src/theme/idioms.css` — `.armed-btn` (rest) /
+Styling: `packages/portal-mojo/src/styles/components/idioms.css` — `.armed-btn` (rest) /
 `.armed-btn.is-armed` (armed, pulsing; static under
 `prefers-reduced-motion`). Tokens only, both themes; the dark theme swaps
 the armed text color for contrast against the light --bad.

package/docs/loading.md

@@ -12,7 +12,7 @@ import {
 The "we're fetching / working" family. It **complements the skeleton
 silhouette**, which stays the default for anything whose shape is already
 known (see the decision table below). Live demo: portal → Develop →
-Components → **Loaders**. Styling: `apps/portal/src/theme/loading.css` —
+Components → **Loaders**. Styling: `packages/portal-mojo/src/styles/components/loading.css` —
 tokens only, both themes.
 
 Ported from web-mojo `src/core/views/feedback/BusyIndicator.js` (its only
@@ -210,7 +210,7 @@ clicked away mid-save, they keep where they went.
   restores focus to the element the inert switch blurred (see above). Its
   veil is `pointer-events: none`: `inert` already stopped the clicks, and a
   veil that swallowed them would break text selection after release.
-- **Reduced motion:** the spinner does not spin. `theme.css` kills every
+- **Reduced motion:** the spinner does not spin. `core.css` kills every
   animation with a universal `!important` rule — right for a skeleton
   (shimmer stops), wrong for a spinner (the ring would freeze mid-rotation
   with one colored quarter and read as a stuck control). `loading.css`

package/docs/location-address.md

@@ -73,4 +73,5 @@ field in that batch back to its shared server snapshot.
 
 The suggestion list uses the shared `Popover`, which is the sole owner of
 outside-mousedown and Escape dismissal. Styles live in
-`theme/location-address.css` and use design tokens in both themes.
+`src/styles/components/location-address.css` (shipped in
+`portal-mojo/styles.css`) and use design tokens in both themes.