portal-mojo 0.2.7 → 0.2.9

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

@@ -17,12 +17,21 @@ is a Promise that resolves when its dialog closes.
 | `modal.detail((close) => <DetailView …/>)` | detail-sized shell for record views |
 | `modal.drawer<T>({title, content\|render, …})` | `T \| null` — right slide-over (below) |
 | `formModal({title, fields, initial?, submitText?, intro?})` | `FormData \| null` (see forms.md) |
+| `modal.closeAll()` | closes every open modal/drawer; each await resolves `null` |
 
 Patterns:
 - Danger confirms: `danger: true` styles the confirm button destructively.
 - Batch prepare: open a `formModal` INSIDE a flow to collect once-per-batch
   input; resolve null to cancel the whole thing.
 - Stacked dialogs are fine (disable-reason form over a detail modal).
+- `canDismiss` also covers the dialog closing natively without a cancelable
+  `cancel` (Chromium's second Escape with no click between, Android back):
+  a locked modal reopens with focus inside; an unlocked one resolves `null`.
+  A `dismissable: false` drawer reopens the same way.
+- The stack ends with the session: `'logout'` / `'unauthorized'` auth events,
+  or the signed-in uid changing (another tab), close every open dialog
+  (`null`), so a host remounted after sign-in never brings a previous user's
+  dialog back.
 
 ## confirmGuardrail — the "are you sure, and here is why" stop
 
@@ -64,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
 
@@ -103,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.
 
@@ -130,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.
@@ -66,6 +66,18 @@ handle.dismiss(); // optional early resolution
 - `onUndo` typically fires the inverse mutation; surface ITS failure with a
   normal `toast.error` — the undo toast itself is done by then.
 
+## toast.action / actionToast
+
+```ts
+toast.action('Your other sessions stay signed in.', 'Sign out everywhere else', () => revokeOthers(), { timeout: 10000 });
+```
+
+The undo card with a named button: a follow-up OFFER after something
+already happened (not an inverse). Clicking dismisses at once and calls
+`onAction`; otherwise the card auto-dismisses after `timeout` (default
+10000ms). Returns `{ dismiss }`. Surface the action's own outcome with a
+normal toast.
+
 ## toast.progress / progressToast
 
 ```ts

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.

package/docs/markdown.md

@@ -24,8 +24,8 @@ tab or a cold first frame still shows the document.
 | `debounceMs` | `0` | Wait this long after `source` stops changing before calling the server. Set it for text that grows token by token (a streaming assistant reply) so one reply is one request. |
 | `className` | — | Extra classes on the wrapper. `md` is always present. |
 
-Renders one `<div class="md">`. Styling lives in the consuming app —
-`apps/portal/src/theme/markdown.css`, tokens only, both themes; both render
+Renders one `<div class="md">`. Styling ships in `portal-mojo/styles.css` —
+`packages/portal-mojo/src/styles/components/markdown.css`, tokens only, both themes; both render
 paths emit the same element set, so one stylesheet dresses both.
 
 ### No loading jump, by construction
@@ -175,7 +175,7 @@ that is what lets a cache hit paint on the first frame.
 | `client/markdown-sanitize.ts` | the allowlist sanitizer — the security boundary |
 | `client/markdown-parse.ts` | markdown → block AST, plus the HTML emitter the **mock** uses |
 | `client/markdown-fallback.tsx` | AST → React elements (the fallback path) |
-| `apps/portal/src/theme/markdown.css` | `.md` styling, tokens only, both themes |
+| `packages/portal-mojo/src/styles/components/markdown.css` | `.md` styling, tokens only, both themes |
 
 ## Fallback coverage
 

package/docs/menus-and-access.md

@@ -140,7 +140,7 @@ converging it onto flat sections is a named follow-up.
 ## Group context (A3)
 
 Product portals place `<GroupProvider>` at the app root. `useActiveGroup() → {group, member,
-loading, setActiveGroup, clearActiveGroup}`. The active group id rides the
+loading, accessDenied, setActiveGroup, clearActiveGroup}`. The active group id rides the
 REAL `?group=` search param (hash-safe, deep-linkable) with localStorage
 fallback; activating a group fetches the caller's member record
 (`/api/group/<id>/member`) whose permissions feed `useCan`.
@@ -148,3 +148,23 @@ fallback; activating a group fetches the caller's member record
 embedded-parent rows, kind chips); `RequiresGroup` wraps pages that need a
 group and shows the pick-a-group state otherwise. Do not install these in the
 standalone Admin shell; they belong to group-scoped product navigation.
+
+A cached group and membership remain resolved during network errors and server
+5xx responses. The URL, stored selection and active-group signal stay in place.
+An unresolved initial group still follows the URL/stored fallback chain.
+Group 401/403/404 suppress the cached group immediately and run that fallback;
+membership 401/403/404 keep the group identity but expose `member: null` and
+`accessDenied: true`. These definitive denials do not retry.
+Once denied, a later network failure or selecting an old switcher row cannot
+restore cached grants. Recovery requires successful guarded group and member
+reads; membership-only denial requires a successful member read.
+
+A private workspace must treat `accessDenied === true` as a boundary: cancel
+pending work, hide cached private results and remove temporary preview URLs.
+Removing `member` only removes member-derived grants; user/system grants may
+still satisfy `useCan`. This flag is not a loading state. Global Admin clears
+it along with the group/member context. The server checks every request.
+Provider requests check their candidate group, selection generation and authenticated actor both
+before dispatch and after resolving, and consume TanStack's cancellation signal.
+Provider teardown invalidates pending request closures even if another query
+observer keeps their cache key alive.

package/docs/multiselect-dropdown.md

@@ -107,7 +107,7 @@ element the user just clicked.
    construction.
 3. `null`/`undefined` are the only "nothing selected" — `0` and `''` are
    selections.
-4. Both themes, tokens only: `apps/portal/src/theme/multiselect-dropdown.css`
+4. Both themes, tokens only: `packages/portal-mojo/src/styles/components/multiselect-dropdown.css`
    (reuses `.tbl-check`, `.btn`, `.field-*`; the popover shell supplies the
    surface/border/shadow).
 

package/docs/popover.md

@@ -101,7 +101,7 @@ it (source parity).
 
 ## Styling
 
-`.mojo-popover` lives in `apps/portal/src/theme/popover.css` — tokens
+`.mojo-popover` lives in `packages/portal-mojo/src/styles/components/popover.css` — tokens
 only, both themes. It neutralizes the UA `[popover]` stylesheet
 (`inset: 0` centering, `margin: auto`, border, padding, Canvas colors)
 and restores the mission-control look (`.filter-menu` family: `--surface`

package/docs/record-feed.md

@@ -221,8 +221,8 @@ surfaces local rejection through the same alert region.
 
 ## Styling
 
-Import `theme/record-feed.css` after the token declarations (the portal and
-showcase theme aggregators already do). It uses only the mission-control
+`src/styles/components/record-feed.css` ships in `portal-mojo/styles.css`;
+the app declares the tokens. It uses only the mission-control
 tokens and supports both `data-theme` values. Override the default bounded
 height with `--record-feed-height` on a wrapper/component class.