portal-mojo 0.2.14 → 0.2.16

package/docs/DetailView.md

@@ -53,6 +53,11 @@ of the toolkit it must render inside the app's `QueryClientProvider`
 - `sections` mixes `{key, label, icon, render, permissions?}` entries with
   `{divider: 'Label'}` side-labels.
 - `initialSection` picks the starting rail entry.
+- `avatarUrl` shows an image in the header avatar (falls back to
+  `avatarName` initials / `icon` when absent or the image fails to load);
+  pass a pre-vetted URL (`safePreviewUrl`) kept in component state, never a
+  Query cache. `onAvatarClick` turns the avatar into a button with a camera
+  hover overlay (`avatarLabel` sets its label/tooltip).
 
 ## Page embedding — `onClose` is optional
 
@@ -172,6 +177,7 @@ permission behavior, not misconfig.
 | `Eyebrow` | small uppercase section heading inside a panel |
 | `FlatRow` | label + value row; `action` adds the edit pencil (`actionIcon` to override, e.g. `bi-plus-lg` for empty values) |
 | `SecurityItem` | icon + title + description row with a trailing slot (badge/button) |
+| `MetricCard compact` | dense one-line KPI card for detail-view snapshot rows (value never wraps; `title` for a tooltip such as the full timestamp) |
 
 Pencil actions open `formModal` with current values as `initial`. Current-record
 operations live in the header menu or focused dialogs; content rails never

package/docs/admin-identity-users.md

@@ -25,8 +25,13 @@ reason per batch; rows already in the target state are ineligible.
 
 The detail preserves all 14 sections: Overview, Profile, Personal, Security,
 OAuth, Groups, Sys Perms, conditional App Perms, API Keys, Devices, Logins,
-Audit, Notifications, and Metadata. Permission sections are labeled **System
-permissions** and **Product permissions** in the UI. Consuming apps install
+Audit, Notifications, and Metadata. Permission sections are labeled **Sys
+Perms** and **Product permissions** in the rail. Sys Perms opens with every
+granted key (catalog keys neutral, app-registered accent, out-of-catalog
+amber), then **Custom permissions**: out-of-catalog keys with remove (armed)
+and a grant input, then the catalog tabs. Remove sends
+`{permissions: {key: false}}` — django-mojo `User.set_permissions` deletes a
+key on a falsy value (the mock matches). Consuming apps install
 their product tabs with `registerFormTabs(USER_APP_PERMS_TABSET, tabs)`; the
 section stays absent when none are registered. User grants can cover multiple
 groups; use a Member product permission for a single group.
@@ -77,6 +82,10 @@ per endpoint, so `UserDetail` and the fleet-wide tables share one cache.
 
 ## Avatar uploads
 
+The header avatar shows the attached image (thumbnail fetched from
+`/api/fileman/file/<id>` into component state) and, for admins, is a button
+that opens the same manager as the kebab's "Manage avatar…".
+
 Manage avatar uses the shared `ImageField`: it uploads into the acting admin's
 personal File scope, then saves that completed positive numeric File id (or
 null to clear) on the target User. This matches django-mojo #1488's

package/docs/admin-members.md

@@ -116,6 +116,15 @@ new grant semantics: the backend still decides what each key authorizes.
 
 ## Composition
 
+`GroupMembersPanel` and `MemberDetail` gate writes on the system-pinned
+constants by default. A tenant composition that renders them for the active
+group passes the group-local gates instead (`MEMBER_GROUP_SAVE_PERMISSIONS`,
+`MEMBER_GROUP_INVITE_PERMISSIONS`) through `savePermissions`,
+`invitePermissions` and `directoryPermissions`; the server still decides. A
+product may also pass `roles` (`AdmissionRole[]`): the invite form then shows a
+role select, posts that role's grants with the invitation, and records the role
+label as `metadata.role`.
+
 `MEMBERS_ADMIN_SECTION` is root-relative and dual-mounts as `/members` in the
 standalone Admin and `/system/members` when embedded. It never consumes active
 group context. `GroupMembersPanel` is the reusable Group-detail composition;

package/docs/auth.md

@@ -25,8 +25,8 @@ onAuth('rotated', () => queryClient.invalidateQueries());  // same user, re-issu
 
 ## Session mechanics
 
-- JWT pair (`access_token`/`refresh_token`); single-flight refresh (3
-  concurrent 401s → ONE refresh POST); pre-request gate throws a synthetic
+- JWT pair (`access_token`/`refresh_token`); single-flight refresh (concurrent
+  gated HTTP requests and realtime reconnects → 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
@@ -34,7 +34,15 @@ onAuth('rotated', () => queryClient.invalidateQueries());  // same user, re-issu
   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.
+- Refresh POSTs have a 15-second deadline. A timed-out attempt releases the
+  shared flight so a later request or reconnect can try again. RealtimeProvider
+  uses this same gate before connecting and before sending authentication;
+  applications do not need a second refresh timer for WebSockets.
 - `useAuthSnapshot()` → `{authenticated, uid, email}` — live, cross-tab.
+- An internal session revision distinguishes same-tab renewal from explicit
+  replacement/clearing and cross-tab storage changes. Session-bound realtime
+  retains this fence across unmount/remount, so a late renewal cannot undo a
+  terminal server denial. It is an in-memory lifecycle fence, not authorization.
 - `logout()` is client-side (django-mojo has no logout endpoint) and emits
   `'logout'`.
 - Every flow that answers with a login grant adopts it only when it carries

package/docs/realtime.md

@@ -9,6 +9,23 @@ consumer permissions own topic subscriptions. Disabling the provider or losing
 the auth token closes the socket. A permission loss in one consumer must not
 disable this shared provider.
 
+The provider binds both owned and injected clients to the shared auth session.
+Before opening a socket and again when challenged, it waits for `ensureValidToken()`;
+HTTP and realtime share one refresh POST. A slow or temporarily failed renewal
+keeps the connection in `connecting`/`authenticating`/`backoff`, not `auth-failed`.
+Consumers should preserve their current workspace during these transient states.
+Confirmed refresh denial still fails closed. Token replacement invalidates old
+handshakes synchronously, including during a pending refresh.
+An in-flight renewal completing after an authentication failure or forced
+disconnect cannot clear that suspension. An intentional replacement session
+can authenticate again; ordinary token refresh cannot.
+
+For a non-React session consumer, call `const unbind = client.bindAuthSession()`
+before `client.setEnabled(true)`, and call `unbind()` on teardown. One binding
+owns the client at a time; unbinding closes the connection without aborting a
+renewal shared by HTTP. Standalone `connect(token)` clients keep explicit-token
+behavior and are responsible for their token lifecycle.
+
 ## Wire contract
 
 - URL is derived from the configured API origin as exactly `/ws/realtime/`
@@ -55,7 +72,10 @@ A top-level `{type:'error'}` frame is attributed in order:
 
 1. **During authentication** — auth failure: the client closes and suspends
    until the token value changes. Surfaces through the lifecycle status only;
-   no `error` event is dispatched.
+   no `error` event is dispatched. Exception: the exact direct
+   `message === 'Authentication timeout'` before credentials were sent on a
+   session-bound socket is a transport timeout and enters bounded retry.
+   The same error after credentials were sent remains an authentication failure.
 2. **While a subscribe/unsubscribe is pending** — that operation's denial
    (acknowledgements are uncorrelated, so denial is a generic `error`); the
    topic reports `denied`. Surfaces through the topic status only; no `error`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.14",
+    "version": "0.2.16",
     "description": "React portal toolkit for django-mojo — typed client + params store, mission-control UI, dependency-free SVG charts, admin section bundles.",
     "type": "module",
     "license": "Apache-2.0",

package/src/admin/identity/groups/group-sections/OverviewSection.tsx

@@ -52,11 +52,11 @@ export function OverviewSection({ group, openGroup, canViewCredentials, canViewA
 
     return (
         <>
-            <div className="grid gap-3 grid-cols-2 xl:grid-cols-4" style={{ marginBottom: 14 }}>
-                <MetricCard label="Members" value={memberCount} />
-                <MetricCard label="Sub-groups" value={subs ? subCount : '—'} />
-                <MetricCard label="API keys" value={canViewCredentials ? (keyPeek?.count ?? '—') : 'Unavailable'} />
-                <MetricCard label="Last activity" value={fmt.relative(group.last_activity, '—')} />
+            <div className="grid gap-2 mb-4 grid-cols-[repeat(auto-fit,minmax(7.5rem,1fr))]">
+                <MetricCard compact label="Members" value={memberCount} />
+                <MetricCard compact label="Sub-groups" value={subs ? subCount : '—'} />
+                <MetricCard compact label="API keys" value={canViewCredentials ? (keyPeek?.count ?? '—') : 'Unavailable'} />
+                <MetricCard compact label="Last activity" value={fmt.relative(group.last_activity, '—')} title={group.last_activity ? fmt.datetime(group.last_activity) : undefined} />
             </div>
 
             <Eyebrow>This group</Eyebrow>

package/src/admin/identity/members/GroupMembersPanel.tsx

@@ -3,7 +3,8 @@ import { useQueryClient } from '@tanstack/react-query';
 import { useCan, type Params } from '../../../client/runtime';
 import { Badge, Eyebrow, SecurityItem, fmt, modal } from '../../../ui';
 import { MemberDetail, type MemberNavigationCallbacks } from './MemberDetail';
-import { openMemberAdmissionDialog, type AdmissionGroup, type AdmissionMode } from './member-flows';
+import { openMemberAdmissionDialog, type AdmissionGroup, type AdmissionMode, type AdmissionRole } from './member-flows';
+import type { PermSpec } from '../../../client/runtime';
 import {
     MEMBER_GROUP_READ_PERMISSIONS,
     MEMBER_INVITE_PERMISSIONS,
@@ -59,24 +60,36 @@ function MemberItem({ member, onOpen }: { member: MemberRow; onOpen: () => void
 
 export interface GroupMembersPanelProps extends MemberNavigationCallbacks {
     group: AdmissionGroup;
+    /** Global Admin gates are system-pinned; a tenant composition passes its group-local gates. */
+    invitePermissions?: PermSpec;
+    savePermissions?: PermSpec;
+    directoryPermissions?: PermSpec;
+    /** Optional fixed roles offered on invite; each sets grants and the role label. */
+    roles?: AdmissionRole[];
 }
 
-export function GroupMembersPanel({ group, onNavigateUser, onNavigateGroup }: GroupMembersPanelProps) {
+export function GroupMembersPanel({
+    group, onNavigateUser, onNavigateGroup, roles,
+    invitePermissions = MEMBER_INVITE_PERMISSIONS,
+    savePermissions = MEMBER_SAVE_PERMISSIONS,
+    directoryPermissions = MEMBER_USER_DIRECTORY_PERMISSIONS,
+}: GroupMembersPanelProps) {
     const qc = useQueryClient();
     const [search, setSearch] = useState('');
     const [status, setStatus] = useState<StatusFilter>('active');
     const [start, setStart] = useState(0);
     useEffect(() => setStart(0), [search, status, group.id]);
     const query = MemberModel.useList(paramsFor(group.id, search, status, start));
-    const { can: canInvite } = useCan(MEMBER_INVITE_PERMISSIONS);
-    const { can: canCreate } = useCan(MEMBER_SAVE_PERMISSIONS);
-    const { can: canReadUsers } = useCan(MEMBER_USER_DIRECTORY_PERMISSIONS);
+    const { can: canInvite } = useCan(invitePermissions);
+    const { can: canCreate } = useCan(savePermissions);
+    const { can: canReadUsers } = useCan(directoryPermissions);
     const members = query.data?.rows ?? [];
     const count = query.data?.count ?? 0;
 
     const admit = (initialMode: AdmissionMode) => openMemberAdmissionDialog({
         group,
         initialMode,
+        roles,
         canInvite,
         canCreate,
         canReadUsers,
@@ -89,6 +102,7 @@ export function GroupMembersPanel({ group, onNavigateUser, onNavigateGroup }: Gr
                 id={member.id}
                 onClose={() => close(null)}
                 readPermissions={MEMBER_GROUP_READ_PERMISSIONS}
+                savePermissions={savePermissions}
                 onNavigateUser={onNavigateUser}
                 onNavigateGroup={onNavigateGroup}
             />

package/src/admin/identity/members/MemberDetail.tsx

@@ -33,6 +33,8 @@ export interface MemberDetailProps extends MemberNavigationCallbacks {
     onClose: () => void;
     /** Global Admin is system-pinned; fixed-group compositions pass their read gate. */
     readPermissions?: PermSpec;
+    /** Same for writes: a fixed-group composition passes the group-local save gate. */
+    savePermissions?: PermSpec;
 }
 
 function AuditTable({ memberId }: { memberId: number }) {
@@ -118,13 +120,14 @@ function GrantSummary({ member }: { member: MemberRow }) {
 export function MemberDetail({
     id, onClose, onNavigateUser, onNavigateGroup,
     readPermissions = MEMBER_READ_PERMISSIONS,
+    savePermissions = MEMBER_SAVE_PERMISSIONS,
 }: MemberDetailProps) {
     const qc = useQueryClient();
     const { can: canRead, isLoading: readLoading } = useCan(readPermissions);
     const query = MemberModel.useOne(canRead ? id : null);
     const save = MemberModel.useSave();
     const resend = MemberModel.useAction('resend_invite');
-    const { can: canSave } = useCan(MEMBER_SAVE_PERMISSIONS);
+    const { can: canSave } = useCan(savePermissions);
     useSyncExternalStore(subscribeMemberPermissions, memberPermissionsVersion, memberPermissionsVersion);
     useSyncExternalStore(subscribeFormTabs, formTabsVersion, formTabsVersion);
 
@@ -200,13 +203,13 @@ export function MemberDetail({
         ...(onNavigateUser && member.user ? [{ label: 'View user', icon: 'bi-person', onSelect: () => onNavigateUser(member.user!.id) }] : []),
         ...(onNavigateGroup && member.group ? [{ label: 'View group', icon: 'bi-people', onSelect: () => onNavigateGroup(member.group!.id) }] : []),
         { divider: true as const },
-        { label: 'Edit role label', icon: 'bi-person-badge', permissions: MEMBER_SAVE_PERMISSIONS, onSelect: () => { void editRole(); } },
-        { label: 'Resend invitation', icon: 'bi-envelope-arrow-up', permissions: MEMBER_SAVE_PERMISSIONS, onSelect: () => { void resendInvite(); } },
+        { label: 'Edit role label', icon: 'bi-person-badge', permissions: savePermissions, onSelect: () => { void editRole(); } },
+        { label: 'Resend invitation', icon: 'bi-envelope-arrow-up', permissions: savePermissions, onSelect: () => { void resendInvite(); } },
         {
             label: member.is_active ? 'Deactivate membership' : 'Activate membership',
             icon: member.is_active ? 'bi-toggle-off' : 'bi-toggle-on',
             danger: member.is_active,
-            permissions: MEMBER_SAVE_PERMISSIONS,
+            permissions: savePermissions,
             onSelect: () => { void setActive(!member.is_active); },
         },
     ];
@@ -231,10 +234,10 @@ export function MemberDetail({
                     key: 'Overview', label: 'Overview', icon: 'bi-grid-1x2', render: () => (
                         <>
                             <div className="detail-kpi-grid">
-                                <MetricCard label="Role label" value={role} />
-                                <MetricCard label="Status" value={member.is_active ? 'Active' : 'Inactive'} />
-                                <MetricCard label="Joined" value={fmt.relative(member.created)} />
-                                <MetricCard label="Effective grants" value={effectiveMemberGrants(member.permissions).length} />
+                                <MetricCard compact label="Role label" value={role} />
+                                <MetricCard compact label="Status" value={member.is_active ? 'Active' : 'Inactive'} />
+                                <MetricCard compact label="Joined" value={fmt.relative(member.created)} />
+                                <MetricCard compact label="Effective grants" value={effectiveMemberGrants(member.permissions).length} />
                             </div>
                             <Eyebrow>This membership</Eyebrow>
                             <FlatRow label="User" action={member.user && onNavigateUser ? () => onNavigateUser(member.user!.id) : undefined} actionTitle="View user">{userLabel}</FlatRow>

package/src/admin/identity/members/member-flows.tsx

@@ -5,11 +5,22 @@ import { MemberModel, type MemberRow } from './models';
 
 export interface AdmissionGroup extends Pick<Group, 'id' | 'name' | 'kind'> {}
 
+/** A fixed role a product offers on invite: the grants it sets and the label it records. */
+export interface AdmissionRole {
+    value: string;
+    label: string;
+    permissions: string[];
+    help?: string;
+}
+
 /** Email-only, with no user-directory lookup or existence-dependent branch. */
-export async function inviteMemberByEmail(groupId: number, email: string): Promise<MemberRow | null> {
+export async function inviteMemberByEmail(groupId: number, email: string, permissions?: string[]): Promise<MemberRow | null> {
     const response = await mojoCall('/api/group/member/invite', {
         method: 'POST',
-        body: { group: groupId, email: email.trim() },
+        body: {
+            group: groupId, email: email.trim(),
+            ...(permissions?.length ? { permissions: Object.fromEntries(permissions.map((name) => [name, true])) } : {}),
+        },
     });
     return (response.data ?? null) as MemberRow | null;
 }
@@ -70,6 +81,8 @@ export interface OpenMemberAdmissionOptions {
     initialMode?: AdmissionMode;
     queryClient?: QueryClient;
     onCreated?: (member: MemberRow) => void | Promise<void>;
+    /** Fixed roles shown as a select on the invite form; the first is the default. */
+    roles?: AdmissionRole[];
 }
 
 /** Shared explicit Invite/Add chooser used by global Members and GroupDetail. */
@@ -92,16 +105,29 @@ export async function openMemberAdmissionDialog(options: OpenMemberAdmissionOpti
     try {
         let member: MemberRow | null;
         if (mode === 'invite') {
+            const roles = options.roles ?? [];
             const data = await formModal({
                 title: `Invite a member to ${group.name}`,
                 submitText: 'Send invitation',
                 fields: [{
                     name: 'email', type: 'email', label: 'Email', required: true,
                     help: 'The same confirmation is shown whether this is a new, existing, or already-associated account.',
-                }],
+                }, ...(roles.length ? [{
+                    name: 'role', type: 'select' as const, label: 'Role', required: true,
+                    options: roles.map((role) => ({ value: role.value, label: role.label })),
+                    help: roles.map((role) => role.help ? `${role.label}: ${role.help}` : null).filter(Boolean).join(' '),
+                }] : [])],
+                ...(roles.length ? { initial: { role: roles[0].value } } : {}),
             });
             if (!data?.email) return null;
-            member = await inviteMemberByEmail(group.id, String(data.email));
+            const role = roles.find((candidate) => candidate.value === data.role) ?? roles[0];
+            member = await inviteMemberByEmail(group.id, String(data.email), role?.permissions);
+            // The role label is display-only; the grants above are the authority. A failed
+            // label write leaves a correctly permissioned member, so it is not fatal.
+            if (member && role) {
+                try { member = await mojoSave<MemberRow>(MemberModel.endpoint, member.id, { metadata: { role: role.label } }); }
+                catch { /* label stays "Member"; grants already applied */ }
+            }
             toast.success('Invitation request accepted');
         } else {
             const data = await formModal({

package/src/admin/identity/members/models.ts

@@ -15,6 +15,10 @@ export const MEMBER_GROUP_READ_PERMISSIONS = [
     'groups',
 ];
 
+/** Group-local write gates for fixed-group compositions (a tenant admin's own grants). */
+export const MEMBER_GROUP_SAVE_PERMISSIONS = ['manage_groups', 'manage_group', 'groups'];
+export const MEMBER_GROUP_INVITE_PERMISSIONS = ['manage_users', 'manage_members', 'manage_group', 'manage_groups'];
+
 /** Global Member Admin gates. `sys.` prevents active-group grants leaking in. */
 export const MEMBER_READ_PERMISSIONS = [
     'sys.view_members',

package/src/admin/identity/users/UserDetail.tsx

@@ -14,14 +14,15 @@
 // action (kebab + Profile cards + Security rows share them, the source's
 // Phase 4 dedup).
 //
-// Header deviations forced by DetailView's prop surface (read-only this
-// wave — MERGE-WIRE notes filed): chips are not clickable, so the org chip's
-// click-through lives in the kebab ("Open organization") and as an Overview
-// row link; the avatar slot renders initials (no image/click slot), so the
-// shared ImageField avatar manager hangs off the kebab;
-// presence/status/locked/warning render as chips instead of a two-row aux.
-import { useSyncExternalStore } from 'react';
-import { useCan, useMe } from '../../../client/runtime';
+// Header deviations forced by DetailView's prop surface: chips are not
+// clickable, so the org chip's click-through lives in the kebab ("Open
+// organization") and as an Overview row link; presence/status/locked/warning
+// render as chips instead of a two-row aux. The avatar shows the attached
+// image (preview URL fetched component-locally, never cached) and, for
+// admins, clicking it opens the shared ImageField avatar manager (also in
+// the kebab).
+import { useEffect, useState, useSyncExternalStore } from 'react';
+import { mojoCall, useCan, useMe } from '../../../client/runtime';
 import {
     DetailView,
     fmt,
@@ -31,6 +32,7 @@ import {
     type Chip,
     type DetailMenuEntry,
 } from '../../../ui';
+import { safePreviewUrl } from '../../../ui/safe-url';
 import { MEMBER_READ_PERMISSIONS } from '../members';
 import {
     USER_DEVICE_PERMISSIONS,
@@ -67,6 +69,23 @@ import {
     useAdminCaller,
 } from './sections/shared';
 
+/** Thumbnail URL for an attached avatar File. Like FileField, the
+ *  capability URL stays in component state — never in a Query cache. */
+function useAvatarPreview(fileId: number | null): string | null {
+    const [preview, setPreview] = useState<{ id: number; url: string | null } | null>(null);
+    useEffect(() => {
+        if (fileId == null) return;
+        const controller = new AbortController();
+        void mojoCall(`/api/fileman/file/${fileId}`, { signal: controller.signal }).then((envelope) => {
+            if (controller.signal.aborted) return;
+            const row = (envelope.data ?? {}) as { url?: unknown; thumbnail?: unknown };
+            setPreview({ id: fileId, url: safePreviewUrl(row.thumbnail) ?? safePreviewUrl(row.url) });
+        }, () => { /* no preview → initials */ });
+        return () => controller.abort();
+    }, [fileId]);
+    return fileId != null && preview?.id === fileId ? preview.url : null;
+}
+
 export interface UserDetailProps {
     id: number;
     onClose: () => void;
@@ -99,6 +118,7 @@ function UserDetailLoaded({ user, isAdmin, hasAppPerms, onClose, onOpenGroup }:
     onOpenGroup?: (groupId: number) => void;
 }) {
     const { data: me } = useMe();
+    const avatarUrl = useAvatarPreview(user.avatar?.id ?? null);
     const isSelf = me?.id === user.id;
     const canMembers = useCan(MEMBER_READ_PERMISSIONS).can;
     const canDevices = useCan(USER_DEVICE_PERMISSIONS).can;
@@ -220,6 +240,9 @@ function UserDetailLoaded({ user, isAdmin, hasAppPerms, onClose, onOpenGroup }:
     return (
         <DetailView<UserRow>
             avatarName={user.display_name || user.username}
+            avatarUrl={avatarUrl}
+            onAvatarClick={isAdmin ? actions.openAvatarModal : undefined}
+            avatarLabel={user.avatar ? 'Change or remove avatar' : 'Add avatar'}
             title={user.display_name || user.username || user.email || `User #${user.id}`}
             subtitle={[user.email, user.phone_number].filter(Boolean).join(' · ')}
             chips={chips}
@@ -237,7 +260,7 @@ function UserDetailLoaded({ user, isAdmin, hasAppPerms, onClose, onOpenGroup }:
                 { divider: 'Access' },
                 ...(canMembers ? [{ key: 'Groups', label: 'Groups', icon: 'bi-people', render: () => <GroupsSection user={user} onOpenGroup={onOpenGroup} /> }] : []),
                 {
-                    key: 'SysPerms', label: 'System permissions', icon: 'bi-shield-check',
+                    key: 'SysPerms', label: 'Sys Perms', icon: 'bi-shield-check',
                     permissions: ADMIN,
                     render: () => <SysPermsSection user={user} />,
                 },

package/src/admin/identity/users/sections/OverviewSection.tsx

@@ -77,11 +77,14 @@ export function OverviewSection({ user, shared, onOpenGroup }: {
     return (
         <>
             <Eyebrow>Account snapshot</Eyebrow>
-            <div className="grid gap-3 grid-cols-2 xl:grid-cols-4" style={{ marginBottom: 14 }}>
-                <MetricCard label="Devices" value={String(deviceTotal)} />
-                <MetricCard label="Last login" value={fmt.relative(lastLogin, '—')} />
-                <MetricCard label="Active sessions" value={String(sessionCount)} />
-                <MetricCard label="Groups" value={String(groupCount)} />
+            {/* Compact KPI strip: the modal body is narrow regardless of the
+                viewport, so columns auto-fit the container (not a viewport
+                breakpoint) and values stay on one line. */}
+            <div className="grid gap-2 mb-4 grid-cols-[repeat(auto-fit,minmax(7.5rem,1fr))]">
+                <MetricCard compact label="Devices" value={String(deviceTotal)} />
+                <MetricCard compact label="Last login" value={fmt.relative(lastLogin, '—')} title={lastLogin ? fmt.datetime(lastLogin) : undefined} />
+                <MetricCard compact label="Active sessions" value={String(sessionCount)} />
+                <MetricCard compact label="Groups" value={String(groupCount)} />
             </div>
 
             <Eyebrow>Identity</Eyebrow>

package/src/admin/identity/users/sections/PermissionsSection.tsx

@@ -9,13 +9,59 @@
 // USER_APP_PERMS_TABSET via registerFormTabs — the portal's
 // User.registerPermissions equivalent (UserDetail gates the section on the
 // registry being non-empty).
-import { Eyebrow, FormView } from '../../../../ui';
+//
+// Above the catalog, "Custom permissions" lists every granted key the
+// catalogs don't know (set by scripts, other apps, older catalogs) with
+// add/remove. django-mojo User.set_permissions DELETES a key on a falsy
+// value, so remove = `{permissions: {key: false}}`.
+import { useState, useSyncExternalStore, type FormEvent } from 'react';
+import { ArmedButton, Eyebrow, FormView, getFormTabs, subscribeFormTabs, toast } from '../../../../ui';
 import { UserModel, type UserRow } from '../models';
-import { SYSTEM_PERMISSION_TABS, USER_APP_PERMS_TABSET } from './permission-catalog';
+import {
+    CATEGORY_PERMISSIONS,
+    GRANULAR_PERMISSION_TABS,
+    SYSTEM_PERMISSION_TABS,
+    USER_APP_PERMS_TABSET,
+} from './permission-catalog';
+
+const SYSTEM_KEYS = new Set([
+    ...CATEGORY_PERMISSIONS.map((p) => p.name),
+    ...GRANULAR_PERMISSION_TABS.flatMap((t) => t.permissions.map((p) => p.name)),
+]);
+const PERM_KEY_RE = /^[a-z][a-z0-9_.:-]{0,63}$/;
+
+/** Every `permissions.<key>` an app registered under the App Perms tabset. */
+function useAppPermKeys(): string {
+    return useSyncExternalStore(
+        subscribeFormTabs,
+        () => getFormTabs(USER_APP_PERMS_TABSET)
+            .flatMap((t) => t.fields.map((f) => f.name))
+            .filter((n) => n.startsWith('permissions.'))
+            .map((n) => n.slice('permissions.'.length))
+            .join(','),
+        () => '',
+    );
+}
 
 export function SysPermsSection({ user }: { user: UserRow }) {
+    const appKeys = new Set(useAppPermKeys().split(',').filter(Boolean));
+    const perms = user.permissions ?? {};
+    const granted = Object.keys(perms).filter((k) => Boolean(perms[k])).sort();
+    const custom = Object.keys(perms).filter((k) => !SYSTEM_KEYS.has(k) && !appKeys.has(k)).sort();
     return (
         <>
+            <Eyebrow>Granted ({granted.length})</Eyebrow>
+            <div className="perm-granted">
+                {granted.length === 0
+                    ? <span className="dim">No system-level permissions granted.</span>
+                    : granted.map((k) => (
+                        <code key={k} className={`perm-key${SYSTEM_KEYS.has(k) ? '' : appKeys.has(k) ? ' perm-key-app' : ' perm-key-custom'}`}>{k}</code>
+                    ))}
+            </div>
+
+            <Eyebrow>Custom permissions</Eyebrow>
+            <CustomPermissions user={user} keys={custom} known={(k) => SYSTEM_KEYS.has(k) || appKeys.has(k)} />
+
             <Eyebrow>System permissions</Eyebrow>
             <p className="dim" style={{ margin: '0 0 12px' }}>Toggles autosave as soon as you flip them.</p>
             <FormView model={UserModel} row={user} tabs={SYSTEM_PERMISSION_TABS} />
@@ -23,6 +69,86 @@ export function SysPermsSection({ user }: { user: UserRow }) {
     );
 }
 
+function CustomPermissions({ user, keys, known }: { user: UserRow; keys: string[]; known: (key: string) => boolean }) {
+    const save = UserModel.useSave();
+    const [draft, setDraft] = useState('');
+    const [busy, setBusy] = useState<string | null>(null);
+    const perms = user.permissions ?? {};
+
+    const write = async (key: string, value: boolean) => {
+        setBusy(key);
+        try {
+            await save.mutateAsync({ id: user.id, changes: { permissions: { [key]: value } } });
+            toast.success(value ? `Granted ${key}` : `Removed ${key}`);
+            return true;
+        } catch (err) {
+            toast.error(err instanceof Error ? err.message : `Failed to update ${key}`);
+            return false;
+        } finally {
+            setBusy(null);
+        }
+    };
+
+    const key = draft.trim().toLowerCase();
+    const error = !key ? null
+        : !PERM_KEY_RE.test(key) ? 'Use lowercase letters, digits, and _ . : -'
+        : key === 'protected' ? 'Reserved key'
+        : known(key) ? 'Already in the catalog above — use its toggle'
+        : perms[key] ? 'Already granted'
+        : null;
+    const onAdd = async (e: FormEvent) => {
+        e.preventDefault();
+        if (!key || error) return;
+        if (await write(key, true)) setDraft('');
+    };
+
+    return (
+        <div className="perm-custom">
+            <p className="dim" style={{ margin: '0 0 10px' }}>Keys outside the catalog below — set by other apps, scripts, or older releases.</p>
+            {keys.length === 0
+                ? null
+                : (
+                    <div className="perm-custom-list">
+                        {keys.map((k) => {
+                            const v = perms[k];
+                            return (
+                                <div key={k} className="perm-custom-row">
+                                    <code className="perm-key perm-key-custom">{k}</code>
+                                    {v !== true && <span className="dim perm-custom-value" title="Stored value">{JSON.stringify(v)}</span>}
+                                    <ArmedButton
+                                        className="btn btn-compact"
+                                        icon="bi-x-lg"
+                                        label="Remove"
+                                        armedLabel="Confirm remove"
+                                        disabled={busy !== null}
+                                        onConfirm={async () => { await write(k, false); }}
+                                    />
+                                </div>
+                            );
+                        })}
+                    </div>
+                )}
+            <form className="perm-custom-add" onSubmit={(e) => void onAdd(e)}>
+                <input
+                    className="input"
+                    placeholder="permission_key"
+                    value={draft}
+                    onChange={(e) => setDraft(e.target.value)}
+                    aria-label="New permission key"
+                    aria-invalid={error ? true : undefined}
+                    disabled={busy !== null}
+                    spellCheck={false}
+                    autoCapitalize="off"
+                />
+                <button className="btn btn-primary" type="submit" disabled={!key || Boolean(error) || busy !== null}>
+                    <i className="bi bi-plus-lg" /> Grant
+                </button>
+            </form>
+            {error && <p className="field-error" style={{ margin: '4px 0 0' }}>{error}</p>}
+        </div>
+    );
+}
+
 export function AppPermsSection({ user }: { user: UserRow }) {
     return (
         <>

package/src/admin/identity/users/sections/actions.tsx

@@ -639,7 +639,7 @@ function AvatarModal({ user, onClose, onPendingChange }: { user: UserRow; onClos
     return (
         <div className="modal-pad">
             <h2 className="modal-title">Avatar</h2>
-            <p className="dim">Upload an image in your personal File scope, then attach its completed numeric File id to this user.</p>
+            <p className="dim">Upload a new image (cropped square), or clear the current one to fall back to initials.</p>
             <ImageField
                 value={relationId}
                 onChange={(value) => { void attach(value); }}

package/src/admin/security/devices/UserDeviceDetail.tsx

@@ -346,10 +346,10 @@ export function UserDeviceDetail({ id, onClose, onOpenUser }: {
                         <>
                             <Eyebrow>Overview</Eyebrow>
                             <div className="geoip-kpis">
-                                <MetricCard label="Locations" value={canLocations ? (locationCount ?? '—') : '—'} icon="bi-geo-alt" />
-                                <MetricCard label="Logins" value={canLogins ? (loginCount ?? '—') : '—'} icon="bi-box-arrow-in-right" />
-                                <MetricCard label="Days active" value={days ?? '—'} icon="bi-calendar-range" />
-                                <MetricCard label="Last seen" value={device.last_seen != null ? fmt.relative(device.last_seen) : 'Never'} icon="bi-clock-history" />
+                                <MetricCard compact label="Locations" value={canLocations ? (locationCount ?? '—') : '—'} icon="bi-geo-alt" />
+                                <MetricCard compact label="Logins" value={canLogins ? (loginCount ?? '—') : '—'} icon="bi-box-arrow-in-right" />
+                                <MetricCard compact label="Days active" value={days ?? '—'} icon="bi-calendar-range" />
+                                <MetricCard compact label="Last seen" value={device.last_seen != null ? fmt.relative(device.last_seen) : 'Never'} icon="bi-clock-history" />
                             </div>
 
                             <Eyebrow>Threat signals</Eyebrow>

package/src/admin/security/geoip/GeoIpDossier.tsx

@@ -538,10 +538,10 @@ export function GeoIpDossier({ id, onClose, onOpenLogin, onOpenLocation }: GeoIp
                             />
 
                             <div className="geoip-kpis">
-                                <MetricCard label="Risk score" value={row.risk_score != null ? `${row.risk_score} / 100` : '—'} icon="bi-speedometer2" />
-                                <MetricCard label="Incident events" value={canEvents ? (eventCount ?? '—') : '—'} icon="bi-shield-exclamation" />
-                                <MetricCard label="Logins from this IP" value={canLogins ? (loginCount ?? '—') : '—'} icon="bi-box-arrow-in-right" />
-                                <MetricCard label="Devices seen" value={canDevices ? (deviceCount ?? '—') : '—'} icon="bi-laptop" />
+                                <MetricCard compact label="Risk score" value={row.risk_score != null ? `${row.risk_score} / 100` : '—'} icon="bi-speedometer2" />
+                                <MetricCard compact label="Incident events" value={canEvents ? (eventCount ?? '—') : '—'} icon="bi-shield-exclamation" />
+                                <MetricCard compact label="Logins from this IP" value={canLogins ? (loginCount ?? '—') : '—'} icon="bi-box-arrow-in-right" />
+                                <MetricCard compact label="Devices seen" value={canDevices ? (deviceCount ?? '—') : '—'} icon="bi-laptop" />
                             </div>
 
                             <Eyebrow>Location &amp; network</Eyebrow>

package/src/client/auth.ts

@@ -61,13 +61,17 @@ export function sessionIsPersistent(): boolean {
 }
 
 export function setTokens(access: string, refresh?: string | null, persistent = true): void {
+    storeTokens(access, refresh, persistent, 'session');
+}
+
+function storeTokens(access: string, refresh: string | null | undefined, persistent: boolean, source: 'session' | 'refresh'): void {
     // Clear both storages first — a leftover token in the other storage must
     // never shadow this session (web-mojo wrote without clearing).
     clearTokens({ silent: true });
     const storage = persistent ? localStorage : sessionStorage;
     storage.setItem(ACCESS_KEY, access);
     if (refresh) storage.setItem(REFRESH_KEY, refresh);
-    notifyAuthChanged();
+    notifyAuthChanged(source);
 }
 
 export function clearTokens(opts: { silent?: boolean } = {}): void {
@@ -89,8 +93,14 @@ export interface AuthSnapshot {
 
 let snapshotCache: AuthSnapshot = { authenticated: false, uid: null, email: null };
 let snapshotKey = '∅';
+let sessionRevision = 0;
 const authListeners = new Set<() => void>();
 
+/** @internal Same-tab replacement fence; ordinary renewal does not advance it. */
+export function getAuthSessionRevision(): number {
+    return sessionRevision;
+}
+
 function computeSnapshot(): void {
     const access = getAccessToken();
     const refresh = getRefreshToken();
@@ -106,7 +116,8 @@ function computeSnapshot(): void {
     };
 }
 
-function notifyAuthChanged(): void {
+function notifyAuthChanged(source: 'session' | 'refresh' = 'session'): void {
+    if (source === 'session') sessionRevision += 1;
     computeSnapshot();
     for (const cb of authListeners) cb();
 }
@@ -212,10 +223,12 @@ async function doRefresh(): Promise<RefreshOutcome> {
     const superseded = (): boolean => getRefreshToken() !== refresh;
     const sessionUsable = (): boolean => checkTokenStatus().action !== 'logout';
     try {
-        const body = await mojoCall(REFRESH_PATH, { method: 'POST', body: { refresh_token: refresh } });
+        const body = await mojoCall(REFRESH_PATH, {
+            method: 'POST', body: { refresh_token: refresh }, signal: AbortSignal.timeout(15_000),
+        });
         if (superseded()) return { ok: sessionUsable() };
         const pkg = body.data as { access_token: string; refresh_token?: string };
-        setTokens(pkg.access_token, pkg.refresh_token, persistent);
+        storeTokens(pkg.access_token, pkg.refresh_token, persistent, 'refresh');
         emitAuth('refreshed');
         return { ok: true };
     } catch (error) {

package/src/client/mock.ts

@@ -5230,6 +5230,13 @@ function saveUser(user: MockUser, body: Record<string, unknown>, caller?: MockUs
         const existing = target[key];
         target[key] = isPlainObject(value) && isPlainObject(existing) ? mergeDicts(existing, value) : value;
     }
+    // User.set_permissions parity: a falsy value REMOVES the key (add_permission
+    // / remove_permission), so permissions only ever holds granted keys.
+    if (isPlainObject(fields.permissions)) {
+        for (const [key, value] of Object.entries(fields.permissions)) {
+            if (!value) delete user.permissions[key];
+        }
+    }
     let actionResp: Record<string, unknown> | null = null;
     for (const [action, value] of actionEntries) {
         const resp = runUserAction(user, action, value, caller);

package/src/client/realtime.ts

@@ -3,7 +3,8 @@ import {
     useSyncExternalStore, type PropsWithChildren,
 } from 'react';
 import { apiOrigin } from './client';
-import { getAccessToken, subscribeAuth } from './auth';
+import { ensureValidToken, getAccessToken, getAuthSessionRevision, getRefreshToken, subscribeAuth } from './auth';
+import { AuthRequiredError } from './errors';
 
 export type RealtimeLifecycleStatus =
     | 'disabled' | 'idle' | 'connecting' | 'authenticating' | 'ready'
@@ -106,6 +107,10 @@ export class RealtimeClient {
     private readonly topicTimeoutMs: number;
     private socket: RealtimeSocket | null = null;
     private token: string | null = null;
+    private authBinding: { unsubscribe: () => void } | null = null;
+    private authSessionRevision: number | null = null;
+    private preparing: object | null = null;
+    private authSent: RealtimeSocket | null = null;
     private enabled = false;
     private generation = 0;
     private reconnectAttempt = 0;
@@ -142,11 +147,44 @@ export class RealtimeClient {
         return () => this.statusListeners.delete(listener);
     };
 
+    /** Bind one session owner; renewal shares HTTP's single-flight auth gate. */
+    bindAuthSession(): () => void {
+        if (this.authBinding) throw new Error('Realtime client already has an auth session owner');
+        const binding = { unsubscribe: () => {} };
+        this.authBinding = binding;
+        this.stop(this.suspended ?? (this.enabled ? 'idle' : 'disabled'));
+        // Synchronous invalidation is essential: a React effect can run after
+        // an old refresh/handshake has completed for the previous account.
+        const syncSession = () => {
+            const revision = getAuthSessionRevision();
+            const replaced = this.authSessionRevision !== revision;
+            this.authSessionRevision = revision;
+            // A renewal already in flight when the server denied/revoked this
+            // connection is not an intentional replacement session. The fence
+            // also survives a renewal completed while no binding was mounted.
+            if (!replaced && this.suspended) {
+                this.token = getAccessToken();
+                return;
+            }
+            this.setToken(getAccessToken());
+        };
+        binding.unsubscribe = subscribeAuth(syncSession);
+        syncSession();
+        if (this.enabled) this.open();
+        return () => {
+            if (this.authBinding !== binding) return;
+            this.disconnect();
+            binding.unsubscribe();
+            this.authBinding = null;
+        };
+    }
+
     setEnabled(enabled: boolean): void {
         if (this.enabled === enabled) return;
         this.enabled = enabled;
         if (!enabled) this.stop('disabled');
-        else if (this.token) this.open();
+        else if (this.suspended) this.setLifecycle(this.suspended);
+        else if (this.hasCredentials()) this.open();
         else this.setLifecycle('idle');
     }
 
@@ -156,7 +194,7 @@ export class RealtimeClient {
         this.token = token;
         this.suspended = null;
         this.stop(this.enabled && token ? 'idle' : this.enabled ? 'idle' : 'disabled');
-        if (this.enabled && token) this.open();
+        if (this.enabled && this.hasCredentials()) this.open();
     }
 
     connect(token: string): void {
@@ -171,6 +209,8 @@ export class RealtimeClient {
 
     destroy(): void {
         this.disconnect();
+        this.authBinding?.unsubscribe();
+        this.authBinding = null;
         this.statusListeners.clear();
         this.topicListeners.clear();
         this.eventListeners.clear();
@@ -232,14 +272,18 @@ export class RealtimeClient {
     }
 
     nudge(): void {
-        if (!this.enabled || !this.token || this.suspended || this.socket || this.retryTimer == null) return;
+        if (!this.enabled || !this.hasCredentials() || this.suspended || this.socket || this.retryTimer == null) return;
         if (this.clock.now() < this.extendedBackoffUntil) return;
         this.clearRetry();
         this.open();
     }
 
+    private hasCredentials(): boolean {
+        return Boolean(this.token || (this.authBinding && getRefreshToken()));
+    }
+
     private open(): void {
-        if (!this.enabled || !this.token || this.suspended || this.socket) return;
+        if (!this.enabled || !this.hasCredentials() || this.suspended || this.socket || this.preparing) return;
         const run = this.generation;
         // Token refresh and provider remount use this same entry point; neither
         // may bypass a server admission deadline.
@@ -248,6 +292,47 @@ export class RealtimeClient {
             return;
         }
         this.setLifecycle('connecting');
+        this.prepareSession(run, null, () => this.openSocket(run));
+    }
+
+    private prepareSession(run: number, socket: RealtimeSocket | null, ready: () => void): void {
+        const binding = this.authBinding;
+        if (!binding) { ready(); return; }
+        if (this.preparing) return;
+        const attempt = {};
+        this.preparing = attempt;
+        const current = () => this.preparing === attempt && this.authBinding === binding
+            && this.enabled && !this.suspended && run === this.generation && this.socket === socket;
+        void Promise.resolve().then(() => {
+            if (current()) return ensureValidToken();
+        }).then(() => {
+            if (!current()) return;
+            this.preparing = null;
+            ready();
+        }).catch((error: unknown) => {
+            if (!current()) return;
+            this.preparing = null;
+            if (error instanceof AuthRequiredError) this.suspend('auth-failed', 4003, 'Authentication failed');
+            else this.retryAuthentication(run, socket);
+        });
+    }
+
+    private retryAuthentication(run: number, socket: RealtimeSocket | null): void {
+        this.preparing = null;
+        this.authSent = null;
+        this.socket = null;
+        this.clearHeartbeat();
+        this.resetTopicConnectionState();
+        this.scheduleReconnect(run, 0);
+        socket?.close(1000, 'Session renewal pending');
+    }
+
+    private openSocket(run: number): void {
+        // A renewal may have completed while an admission cooldown was set.
+        if (this.clock.now() < this.extendedBackoffUntil) {
+            this.scheduleReconnect(run, 0);
+            return;
+        }
         let socket: RealtimeSocket;
         try {
             socket = this.socketFactory(this.url);
@@ -267,6 +352,8 @@ export class RealtimeClient {
         socket.onerror = () => { /* close is the single retry path */ };
         socket.onclose = (event) => {
             if (!this.isCurrent(run, socket)) return;
+            this.preparing = null;
+            this.authSent = null;
             this.socket = null;
             this.clearHeartbeat();
             this.resetTopicConnectionState();
@@ -283,12 +370,16 @@ export class RealtimeClient {
         if (!frame || typeof frame.type !== 'string') return;
 
         if (frame.type === 'auth_required') {
-            if (this.lifecycle !== 'authenticating' || !this.token) return;
-            socket.send(JSON.stringify({ type: 'authenticate', token: this.token, prefix: 'bearer' }));
+            if (this.lifecycle !== 'authenticating' || !this.token || this.authSent === socket) return;
+            this.prepareSession(run, socket, () => {
+                // Latch before send: a transport may answer synchronously.
+                this.authSent = socket;
+                socket.send(JSON.stringify({ type: 'authenticate', token: this.token, prefix: 'bearer' }));
+            });
             return;
         }
         if (frame.type === 'auth_success') {
-            if (this.lifecycle !== 'authenticating') return;
+            if (this.lifecycle !== 'authenticating' || this.authSent !== socket) return;
             this.reconnectAttempt = 0;
             this.extendedBackoffUntil = 0;
             this.automaticUserTopic = (typeof frame.user_type === 'string' && (typeof frame.user_id === 'number' || typeof frame.user_id === 'string'))
@@ -325,6 +416,8 @@ export class RealtimeClient {
             // Fence queued frames before closing: late auth_success must not
             // clear the deadline or make this refused socket ready.
             this.extendedBackoffUntil = this.clock.now() + 60_000;
+            this.preparing = null;
+            this.authSent = null;
             this.socket = null;
             this.clearHeartbeat();
             this.resetTopicConnectionState();
@@ -335,7 +428,11 @@ export class RealtimeClient {
         }
         if (frame.type === 'error') {
             if (this.lifecycle === 'authenticating') {
-                this.suspend('auth-failed', 4003, 'Authentication failed');
+                // The server's admission timer can expire while renewal is
+                // pending. No credential was rejected in this specific case.
+                if (frame.message === 'Authentication timeout' && this.authBinding && this.authSent !== socket) {
+                    this.retryAuthentication(run, socket);
+                } else this.suspend('auth-failed', 4003, 'Authentication failed');
             } else if (this.topicOperation) {
                 this.denyCurrentTopic();
             } else {
@@ -492,6 +589,9 @@ export class RealtimeClient {
 
     private suspend(reason: 'auth-failed' | 'forced-disconnect', code: number, message: string): void {
         this.suspended = reason;
+        this.preparing = null;
+        this.authSent = null;
+        this.clearRetry();
         this.setLifecycle(reason);
         const socket = this.socket;
         this.socket = null;
@@ -502,6 +602,8 @@ export class RealtimeClient {
 
     private stop(status: RealtimeLifecycleStatus): void {
         this.generation += 1;
+        this.preparing = null;
+        this.authSent = null;
         this.clearRetry();
         this.clearHeartbeat();
         this.resetTopicConnectionState();
@@ -561,8 +663,7 @@ export type RealtimeProviderProps = PropsWithChildren<{
 
 export function RealtimeProvider({ children, enabled = true, client, socketFactory, origin }: RealtimeProviderProps) {
     const owned = useMemo(() => client ?? new RealtimeClient({ socketFactory, origin }), [client, socketFactory, origin]);
-    const token = useSyncExternalStore(subscribeAuth, getAccessToken, getAccessToken);
-    useEffect(() => { owned.setToken(token); }, [owned, token]);
+    useEffect(() => owned.bindAuthSession(), [owned]);
     useEffect(() => {
         owned.setEnabled(enabled);
         return () => owned.setEnabled(false);

package/src/styles/components/file-upload.css

@@ -100,7 +100,7 @@
 .file-field-preview img{inline-size:100%;block-size:100%;object-fit:cover}
 .file-field-main{display:grid;gap:3px;min-inline-size:0}.file-field-main>strong{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.file-field-status{color:var(--mute);font-size:12px}.file-field-status.is-replacement-failed,.file-field-status.is-attach-failed{color:var(--bad)}.file-field-status.is-completed-awaiting-attach{color:var(--warn)}
 .file-field-status.is-edit-failed{color:var(--bad)}.file-field-status.is-edit-ready{color:var(--warn)}.file-field-edit-actions{display:flex;align-items:center;flex-wrap:wrap;gap:5px;margin-top:4px}
-.file-field-actions{display:flex;align-items:center;justify-content:flex-end;gap:6px}.file-field-drop{min-block-size:auto;padding:7px 10px;border-style:solid}.file-field-drop span{display:flex;gap:6px;white-space:nowrap}
+.file-field-actions{display:flex;align-items:center;justify-content:flex-end;gap:6px}.file-field-actions .btn{white-space:nowrap}.file-field-drop{min-block-size:auto;padding:7px 10px;border-style:solid}.file-field-drop span{display:flex;gap:6px;white-space:nowrap}
 @media(max-width:640px){.file-field{grid-template-columns:auto minmax(0,1fr)}.file-field-actions{grid-column:1/-1;justify-content:flex-start;flex-wrap:wrap}}
 
 @media (max-width: 640px) {

package/src/styles/components/user-admin.css

@@ -187,3 +187,20 @@
     width: 72px; height: 72px; border-radius: 50%; object-fit: cover;
     box-shadow: var(--shadow);
 }
+
+/* Sys Perms — granted summary + custom (out-of-catalog) keys. */
+.perm-granted { display: flex; flex-wrap: wrap; gap: 6px; margin: 0 0 18px; }
+.perm-key {
+    font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: 12px;
+    padding: 2px 8px; border-radius: 6px; line-height: 1.6;
+    background: var(--surface2); color: var(--ink); border: 1px solid var(--line);
+}
+.perm-key-app { background: var(--accent-soft); color: var(--accent); border-color: transparent; }
+.perm-key-custom { background: var(--warn-soft); color: var(--warn); border-color: transparent; }
+.perm-custom-list { display: flex; flex-direction: column; margin: 0 0 12px; border-top: 1px solid var(--line); }
+.perm-custom-row { display: flex; align-items: center; gap: 10px; padding: 8px 0; border-bottom: 1px solid var(--line); }
+.perm-custom-row > :last-child { margin-left: auto; }
+.perm-custom-value { font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: 12px; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.perm-custom-add { display: flex; gap: 8px; max-width: 420px; }
+.perm-custom-add .input { flex: 1; min-width: 0; font-family: ui-monospace, "SF Mono", Menlo, monospace; }
+.perm-custom { margin-bottom: 18px; }

package/src/styles/core.css

@@ -494,6 +494,17 @@ button { font: inherit; color: inherit; }
     font-size: 17px; font-weight: 750;
 }
 .detail-avatar i { font-size: 22px; }
+.detail-avatar { position: relative; overflow: hidden; }
+.detail-avatar > img { width: 100%; height: 100%; object-fit: cover; display: block; }
+.detail-avatar-btn { border: 0; padding: 0; cursor: pointer; font-family: inherit; }
+.detail-avatar-btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.detail-avatar-overlay {
+    position: absolute; inset: 0; display: flex; align-items: center; justify-content: center;
+    background: rgb(0 0 0 / 0.45); color: #fff; opacity: 0; transition: opacity 0.12s ease;
+}
+.detail-avatar-overlay i { font-size: 18px; }
+.detail-avatar-btn:hover .detail-avatar-overlay,
+.detail-avatar-btn:focus-visible .detail-avatar-overlay { opacity: 1; }
 .detail-id { min-width: 0; }
 .detail-title { margin: 0; font-size: 19px; font-weight: 750; color: var(--ink-strong); letter-spacing: -0.015em; }
 .detail-sub { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; color: var(--mute); font-size: 13.5px; margin-top: 2px; }
@@ -629,6 +640,13 @@ button { font: inherit; color: inherit; }
 .metric-icon { color: var(--mute); font-size: 14px; }
 .metric-value { font-size: 26px; font-weight: 750; color: var(--ink-strong); letter-spacing: -0.02em; font-variant-numeric: tabular-nums; margin-top: 4px; }
 .metric-hint { font-size: 12px; color: var(--mute); margin-top: 2px; }
+.metric-compact { padding: 10px 12px; border-radius: 10px; box-shadow: none; min-width: 0; }
+.metric-compact .metric-label { font-size: 10px; letter-spacing: 0.08em; }
+.metric-compact .metric-value {
+    font-size: 17px; font-weight: 700; margin-top: 2px; line-height: 1.3;
+    white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.metric-compact .metric-hint { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .detail-kpi-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 12px; margin-bottom: 20px; }
 .detail-kpi-grid > .metric { min-width: 0; }
 @media (max-width: 600px) { .detail-kpi-grid { grid-template-columns: minmax(0, 1fr); } }

package/src/ui/DetailView.tsx

@@ -84,6 +84,14 @@ export type DetailMenuEntry<TCtx = unknown> = DetailMenuItem<TCtx> | { divider:
 
 export interface DetailViewProps<TCtx = unknown> {
     avatarName?: string;
+    /** Image for the header avatar; falls back to `avatarName` initials /
+     *  `icon` when absent or when the image fails to load. Callers pass a
+     *  pre-vetted URL (e.g. through `safePreviewUrl`). */
+    avatarUrl?: string | null;
+    /** Makes the header avatar a button (e.g. open an avatar manager). */
+    onAvatarClick?: () => void;
+    /** Accessible label/tooltip for the avatar button. */
+    avatarLabel?: string;
     icon?: string;
     title: string;
     subtitle?: string;
@@ -228,13 +236,18 @@ function railBadge(value: ReactNode): ReactNode {
 // ── The component ─────────────────────────────────────────────────────
 
 export function DetailView<TCtx = unknown>({
-    avatarName, icon, title, subtitle, chips = [], active,
+    avatarName, avatarUrl, onAvatarClick, avatarLabel, icon, title, subtitle, chips = [], active,
     sections, initialSection, badges, contextMenu, menuContext, onClose,
 }: DetailViewProps<TCtx>) {
     const [sectionsExpanded, setSectionsExpanded] = useState(false);
     const sectionToggleRef = useRef<HTMLButtonElement>(null);
     const can = useCanChecker();
     const warnOnce = useWarnOnce();
+    const [failedAvatarUrl, setFailedAvatarUrl] = useState<string | null>(null);
+    const showImage = Boolean(avatarUrl) && avatarUrl !== failedAvatarUrl;
+    const avatarInner = showImage
+        ? <img src={avatarUrl!} alt="" referrerPolicy="no-referrer" onError={() => setFailedAvatarUrl(avatarUrl ?? null)} />
+        : avatarName ? initials(avatarName) : <i className={`bi ${icon ?? 'bi-file-earmark'}`} />;
 
     // One-time schema lint: duplicate keys break activation + keep-alive
     // keying; badge keys must name a section; a never-matching
@@ -305,9 +318,20 @@ export function DetailView<TCtx = unknown>({
     return (
         <div className={`detail${onClose ? ' detail-modal-body' : ''}`}>
             <header className="detail-header">
-                <div className="detail-avatar">
-                    {avatarName ? initials(avatarName) : <i className={`bi ${icon ?? 'bi-file-earmark'}`} />}
-                </div>
+                {onAvatarClick ? (
+                    <button
+                        type="button"
+                        className="detail-avatar detail-avatar-btn"
+                        onClick={onAvatarClick}
+                        aria-label={avatarLabel ?? 'Change avatar'}
+                        title={avatarLabel ?? 'Change avatar'}
+                    >
+                        {avatarInner}
+                        <span className="detail-avatar-overlay" aria-hidden="true"><i className="bi bi-camera" /></span>
+                    </button>
+                ) : (
+                    <div className="detail-avatar">{avatarInner}</div>
+                )}
                 <div className="detail-id">
                     <h2 className="detail-title">{title}</h2>
                     <div className="detail-sub">

package/src/ui/ui.tsx

@@ -9,9 +9,18 @@ export function Badge({ tone, children }: { tone?: Tone; children: ReactNode })
     return <span className={`chip chip-${t}`}>{children === true ? 'Yes' : children === false ? 'No' : children}</span>;
 }
 
-export function MetricCard({ label, value, hint, icon }: { label: string; value: ReactNode; hint?: string; icon?: string }) {
+export function MetricCard({ label, value, hint, icon, compact, title }: {
+    label: string;
+    value: ReactNode;
+    hint?: string;
+    icon?: string;
+    /** Dense single-line card for detail-view KPI rows (value never wraps). */
+    compact?: boolean;
+    /** Tooltip — e.g. the full timestamp behind a relative value. */
+    title?: string;
+}) {
     return (
-        <div className="metric">
+        <div className={compact ? 'metric metric-compact' : 'metric'} title={title}>
             <div className="metric-top">
                 <span className="metric-label">{label}</span>
                 {icon && <i className={`bi ${icon} metric-icon`} />}