@rapidmx/web-client 0.9.0 → 0.11.0

package/dist/apps/shared/components/contacts/ContactForm.js

@@ -114,5 +114,5 @@ export default function ContactForm({ contact, mailboxUid, folderUid, mailboxes,
             setSaving(false);
         }
     }
-    return (_jsxs("form", { onSubmit: handleSubmit, className: "max-w-xl flex flex-col gap-1", children: [_jsx("h1", { className: "text-xl font-bold uppercase tracking-wide mb-3", children: contact ? "Edit contact" : "New contact" }), error && _jsx(Alert, { children: error }), !contact && mailboxes && mailboxes.length > 1 && (_jsx(FormField, { label: "Mailbox", htmlFor: "contact-mailbox", children: _jsx("select", { id: "contact-mailbox", className: `${SELECT_CLASS} w-full`, value: targetMailboxUid, onChange: (e) => setTargetMailboxUid(e.target.value), children: mailboxes.map((mb) => (_jsxs("option", { value: mb.uid, children: [mb.displayName, mb.ownerUserUid ? "" : " (shared)"] }, mb.uid))) }) })), _jsx(FormField, { label: "Display name", htmlFor: "contact-displayName", children: _jsx("input", { id: "contact-displayName", type: "text", className: INPUT_CLASS, value: displayName, onChange: (e) => setDisplayName(e.target.value) }) }), _jsxs("div", { className: "grid grid-cols-1 sm:grid-cols-2 gap-3", children: [_jsx(FormField, { label: "First name", htmlFor: "contact-givenName", children: _jsx("input", { id: "contact-givenName", type: "text", className: INPUT_CLASS, value: givenName, onChange: (e) => setGivenName(e.target.value) }) }), _jsx(FormField, { label: "Last name", htmlFor: "contact-surname", children: _jsx("input", { id: "contact-surname", type: "text", className: INPUT_CLASS, value: surname, onChange: (e) => setSurname(e.target.value) }) })] }), _jsxs("div", { className: "grid grid-cols-1 sm:grid-cols-2 gap-3", children: [_jsx(FormField, { label: "Company", htmlFor: "contact-company", children: _jsx("input", { id: "contact-company", type: "text", className: INPUT_CLASS, value: company, onChange: (e) => setCompany(e.target.value) }) }), _jsx(FormField, { label: "Job title", htmlFor: "contact-jobTitle", children: _jsx("input", { id: "contact-jobTitle", type: "text", className: INPUT_CLASS, value: jobTitle, onChange: (e) => setJobTitle(e.target.value) }) })] }), _jsxs("label", { className: "flex items-center gap-2 text-sm mb-4", children: [_jsx("input", { type: "checkbox", checked: favorite, onChange: (e) => setFavorite(e.target.checked) }), "Favorite"] }), _jsx(FormField, { label: "Categories (comma-separated)", htmlFor: "contact-categories", children: _jsx("input", { id: "contact-categories", type: "text", className: INPUT_CLASS, value: categoriesText, onChange: (e) => setCategoriesText(e.target.value), placeholder: "VIP, Work" }) }), _jsx(FormField, { label: "Email", htmlFor: "contact-emails", children: _jsxs("div", { id: "contact-emails", className: "flex flex-col gap-2", children: [emails.map((email, i) => (_jsxs("div", { className: "flex gap-2", children: [_jsx("input", { type: "email", className: `${INPUT_CLASS} flex-1`, value: email.address, onChange: (e) => updateEmail(i, { address: e.target.value }), "aria-label": `Email address ${i + 1}` }), _jsx("select", { className: SELECT_CLASS, value: email.type, onChange: (e) => updateEmail(i, { type: e.target.value }), "aria-label": `Email type ${i + 1}`, children: ADDRESS_KINDS.map((kind) => (_jsx("option", { value: kind, children: kind }, kind))) }), _jsx("button", { type: "button", onClick: () => removeEmail(i), className: "text-sm text-danger px-2", "aria-label": `Remove email ${i + 1}`, children: "\u00D7" })] }, i))), _jsx("button", { type: "button", onClick: () => setEmails((prev) => [...prev, { address: "", type: "work" }]), className: "self-start text-xs font-medium text-primary-dark hover:underline", children: "+ Add email" })] }) }), _jsx(FormField, { label: "Phone", htmlFor: "contact-phones", children: _jsxs("div", { id: "contact-phones", className: "flex flex-col gap-2", children: [phones.map((phone, i) => (_jsxs("div", { className: "flex gap-2", children: [_jsx("input", { type: "tel", className: `${INPUT_CLASS} flex-1`, value: phone.phoneNumber, onChange: (e) => updatePhone(i, { phoneNumber: e.target.value }), "aria-label": `Phone number ${i + 1}` }), _jsx("select", { className: SELECT_CLASS, value: phone.type, onChange: (e) => updatePhone(i, { type: e.target.value }), "aria-label": `Phone type ${i + 1}`, children: ADDRESS_KINDS.map((kind) => (_jsx("option", { value: kind, children: kind }, kind))) }), _jsx("button", { type: "button", onClick: () => removePhone(i), className: "text-sm text-danger px-2", "aria-label": `Remove phone ${i + 1}`, children: "\u00D7" })] }, i))), _jsx("button", { type: "button", onClick: () => setPhones((prev) => [...prev, { phoneNumber: "", type: "work" }]), className: "self-start text-xs font-medium text-primary-dark hover:underline", children: "+ Add phone" })] }) }), _jsx(FormField, { label: "Address", htmlFor: "contact-address", children: _jsxs("div", { className: "flex flex-col gap-3", children: [addresses.map((address, i) => (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsxs("div", { className: "grid grid-cols-1 sm:grid-cols-2 gap-2", children: [_jsx("input", { type: "text", placeholder: "Street", className: INPUT_CLASS, value: address.street ?? "", onChange: (e) => updateAddress(i, { street: e.target.value }) }), _jsx("input", { type: "text", placeholder: "City", className: INPUT_CLASS, value: address.city ?? "", onChange: (e) => updateAddress(i, { city: e.target.value }) }), _jsx("input", { type: "text", placeholder: "State/Province", className: INPUT_CLASS, value: address.state ?? "", onChange: (e) => updateAddress(i, { state: e.target.value }) }), _jsx("input", { type: "text", placeholder: "Postal code", className: INPUT_CLASS, value: address.postalCode ?? "", onChange: (e) => updateAddress(i, { postalCode: e.target.value }) }), _jsx("input", { type: "text", placeholder: "Country", className: INPUT_CLASS, value: address.country ?? "", onChange: (e) => updateAddress(i, { country: e.target.value }) }), _jsx("select", { className: SELECT_CLASS, value: address.type, onChange: (e) => updateAddress(i, { type: e.target.value }), "aria-label": i === 0 ? "Address type" : `Address type ${i + 1}`, children: ADDRESS_KINDS.map((kind) => (_jsx("option", { value: kind, children: kind }, kind))) })] }), _jsx("button", { type: "button", onClick: () => removeAddress(i), className: "self-start text-xs font-medium text-danger hover:underline", "aria-label": i === 0 ? "Remove address" : `Remove address ${i + 1}`, children: "Remove address" })] }, i))), _jsx("button", { type: "button", onClick: () => setAddresses((prev) => [...prev, { type: "home" }]), className: "self-start text-xs font-medium text-primary-dark hover:underline", children: "+ Add address" })] }) }), _jsx(FormField, { label: "Notes", htmlFor: "contact-notes", children: _jsx("textarea", { id: "contact-notes", rows: 3, className: INPUT_CLASS, value: notes, onChange: (e) => setNotes(e.target.value) }) }), _jsxs("div", { className: "flex gap-3 mt-2", children: [_jsx(Button, { type: "submit", loading: saving, disabled: saving, className: "!w-auto", children: "Save" }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onCancel, children: "Cancel" })] })] }));
+    return (_jsxs("form", { onSubmit: handleSubmit, className: "@container flex min-h-0 flex-1 flex-col", children: [_jsx("div", { className: "min-h-0 flex-1 overflow-y-auto p-6", children: _jsxs("div", { className: "flex max-w-xl flex-col gap-1", children: [_jsx("h1", { className: "text-xl font-bold uppercase tracking-wide mb-3", children: contact ? "Edit contact" : "New contact" }), error && _jsx(Alert, { children: error }), !contact && mailboxes && mailboxes.length > 1 && (_jsx(FormField, { label: "Mailbox", htmlFor: "contact-mailbox", children: _jsx("select", { id: "contact-mailbox", className: `${SELECT_CLASS} w-full`, value: targetMailboxUid, onChange: (e) => setTargetMailboxUid(e.target.value), children: mailboxes.map((mb) => (_jsxs("option", { value: mb.uid, children: [mb.displayName, mb.ownerUserUid ? "" : " (shared)"] }, mb.uid))) }) })), _jsx(FormField, { label: "Display name", htmlFor: "contact-displayName", children: _jsx("input", { id: "contact-displayName", type: "text", className: INPUT_CLASS, value: displayName, onChange: (e) => setDisplayName(e.target.value) }) }), _jsxs("div", { className: "grid grid-cols-1 @md:grid-cols-2 gap-3", children: [_jsx(FormField, { label: "First name", htmlFor: "contact-givenName", children: _jsx("input", { id: "contact-givenName", type: "text", className: INPUT_CLASS, value: givenName, onChange: (e) => setGivenName(e.target.value) }) }), _jsx(FormField, { label: "Last name", htmlFor: "contact-surname", children: _jsx("input", { id: "contact-surname", type: "text", className: INPUT_CLASS, value: surname, onChange: (e) => setSurname(e.target.value) }) })] }), _jsxs("div", { className: "grid grid-cols-1 @md:grid-cols-2 gap-3", children: [_jsx(FormField, { label: "Company", htmlFor: "contact-company", children: _jsx("input", { id: "contact-company", type: "text", className: INPUT_CLASS, value: company, onChange: (e) => setCompany(e.target.value) }) }), _jsx(FormField, { label: "Job title", htmlFor: "contact-jobTitle", children: _jsx("input", { id: "contact-jobTitle", type: "text", className: INPUT_CLASS, value: jobTitle, onChange: (e) => setJobTitle(e.target.value) }) })] }), _jsxs("label", { className: "flex items-center gap-2 text-sm mb-4", children: [_jsx("input", { type: "checkbox", checked: favorite, onChange: (e) => setFavorite(e.target.checked) }), "Favorite"] }), _jsx(FormField, { label: "Categories (comma-separated)", htmlFor: "contact-categories", children: _jsx("input", { id: "contact-categories", type: "text", className: INPUT_CLASS, value: categoriesText, onChange: (e) => setCategoriesText(e.target.value), placeholder: "VIP, Work" }) }), _jsx(FormField, { label: "Email", htmlFor: "contact-emails", children: _jsxs("div", { id: "contact-emails", className: "flex flex-col gap-2", children: [emails.map((email, i) => (_jsxs("div", { className: "flex gap-2", children: [_jsx("input", { type: "email", className: `${INPUT_CLASS} flex-1`, value: email.address, onChange: (e) => updateEmail(i, { address: e.target.value }), "aria-label": `Email address ${i + 1}` }), _jsx("select", { className: SELECT_CLASS, value: email.type, onChange: (e) => updateEmail(i, { type: e.target.value }), "aria-label": `Email type ${i + 1}`, children: ADDRESS_KINDS.map((kind) => (_jsx("option", { value: kind, children: kind }, kind))) }), _jsx("button", { type: "button", onClick: () => removeEmail(i), className: "text-sm text-danger px-2", "aria-label": `Remove email ${i + 1}`, children: "\u00D7" })] }, i))), _jsx("button", { type: "button", onClick: () => setEmails((prev) => [...prev, { address: "", type: "work" }]), className: "self-start text-xs font-medium text-primary-dark hover:underline", children: "+ Add email" })] }) }), _jsx(FormField, { label: "Phone", htmlFor: "contact-phones", children: _jsxs("div", { id: "contact-phones", className: "flex flex-col gap-2", children: [phones.map((phone, i) => (_jsxs("div", { className: "flex gap-2", children: [_jsx("input", { type: "tel", className: `${INPUT_CLASS} flex-1`, value: phone.phoneNumber, onChange: (e) => updatePhone(i, { phoneNumber: e.target.value }), "aria-label": `Phone number ${i + 1}` }), _jsx("select", { className: SELECT_CLASS, value: phone.type, onChange: (e) => updatePhone(i, { type: e.target.value }), "aria-label": `Phone type ${i + 1}`, children: ADDRESS_KINDS.map((kind) => (_jsx("option", { value: kind, children: kind }, kind))) }), _jsx("button", { type: "button", onClick: () => removePhone(i), className: "text-sm text-danger px-2", "aria-label": `Remove phone ${i + 1}`, children: "\u00D7" })] }, i))), _jsx("button", { type: "button", onClick: () => setPhones((prev) => [...prev, { phoneNumber: "", type: "work" }]), className: "self-start text-xs font-medium text-primary-dark hover:underline", children: "+ Add phone" })] }) }), _jsx(FormField, { label: "Address", htmlFor: "contact-address", children: _jsxs("div", { className: "flex flex-col gap-3", children: [addresses.map((address, i) => (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsxs("div", { className: "grid grid-cols-1 @md:grid-cols-2 gap-2", children: [_jsx("input", { type: "text", placeholder: "Street", className: INPUT_CLASS, value: address.street ?? "", onChange: (e) => updateAddress(i, { street: e.target.value }) }), _jsx("input", { type: "text", placeholder: "City", className: INPUT_CLASS, value: address.city ?? "", onChange: (e) => updateAddress(i, { city: e.target.value }) }), _jsx("input", { type: "text", placeholder: "State/Province", className: INPUT_CLASS, value: address.state ?? "", onChange: (e) => updateAddress(i, { state: e.target.value }) }), _jsx("input", { type: "text", placeholder: "Postal code", className: INPUT_CLASS, value: address.postalCode ?? "", onChange: (e) => updateAddress(i, { postalCode: e.target.value }) }), _jsx("input", { type: "text", placeholder: "Country", className: INPUT_CLASS, value: address.country ?? "", onChange: (e) => updateAddress(i, { country: e.target.value }) }), _jsx("select", { className: SELECT_CLASS, value: address.type, onChange: (e) => updateAddress(i, { type: e.target.value }), "aria-label": i === 0 ? "Address type" : `Address type ${i + 1}`, children: ADDRESS_KINDS.map((kind) => (_jsx("option", { value: kind, children: kind }, kind))) })] }), _jsx("button", { type: "button", onClick: () => removeAddress(i), className: "self-start text-xs font-medium text-danger hover:underline", "aria-label": i === 0 ? "Remove address" : `Remove address ${i + 1}`, children: "Remove address" })] }, i))), _jsx("button", { type: "button", onClick: () => setAddresses((prev) => [...prev, { type: "home" }]), className: "self-start text-xs font-medium text-primary-dark hover:underline", children: "+ Add address" })] }) }), _jsx(FormField, { label: "Notes", htmlFor: "contact-notes", children: _jsx("textarea", { id: "contact-notes", rows: 3, className: INPUT_CLASS, value: notes, onChange: (e) => setNotes(e.target.value) }) })] }) }), _jsxs("div", { className: "rr-solid sticky bottom-14 z-10 flex shrink-0 gap-3 border-t border-border bg-surface px-6 py-3 md:bottom-0", children: [_jsx(Button, { type: "submit", loading: saving, disabled: saving, className: "!w-auto", children: "Save" }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onCancel, children: "Cancel" })] })] }));
 }

package/dist/apps/shared/components/contacts/ContactsSidebar.js

@@ -8,6 +8,7 @@ import { HiOutlineBars3 } from "react-icons/hi2";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { createContactList, listContactLists } from "@rapidmx/react-shared/contacts/contactsApi.js";
 import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
+import { notifyApiError } from "../../notifications/apiErrors.js";
 export function contactsViewKey(view) {
     switch (view.type) {
         case "list":
@@ -90,7 +91,8 @@ export default function ContactsSidebar({ mailboxUid, contacts, active, onSelect
             setAddingList(false);
         }
         catch (err) {
-            setListsError(err instanceof ApiRequestError ? err.message : "Could not create this list.");
+            // A pop-up: `listsError` is only the lists' own load failure.
+            notifyApiError(err, "Couldn't create the list");
         }
     }
     function handleSelect(view) {
@@ -101,5 +103,5 @@ export default function ContactsSidebar({ mailboxUid, contacts, active, onSelect
     // `Drawer` (see MailShell/ContactsShell for the identical pattern and the duplicate-id reasoning
     // behind the `idPrefix`).
     const navContent = (idPrefix) => (_jsxs(_Fragment, { children: [_jsxs("div", { className: "flex flex-col gap-0.5", children: [_jsx(NavItem, { label: "Your contacts", count: contacts.length, active: active.type === "all", onClick: () => handleSelect({ type: "all" }) }), _jsx(NavItem, { label: "Favorites", count: favoriteCount, active: active.type === "favorites", onClick: () => handleSelect({ type: "favorites" }) }), showDeleted && _jsx(NavItem, { label: "Deleted", active: active.type === "deleted", onClick: () => handleSelect({ type: "deleted" }) })] }), _jsxs("div", { children: [_jsxs("div", { className: "flex items-center justify-between px-2.5 mb-1", children: [_jsx("h2", { className: "text-xs font-bold uppercase tracking-wide text-text-muted", children: "Your contact lists" }), _jsx("button", { type: "button", onClick: () => setAddingList(true), "aria-label": "New contact list", className: "text-xs font-bold text-primary-dark hover:underline", children: "+" })] }), listsError && _jsx("p", { className: "px-2.5 text-xs text-danger", children: listsError }), _jsx("div", { className: "flex flex-col gap-0.5", children: lists.map((list) => (_jsx(NavItem, { label: list.name, count: listCounts.get(list.uid) ?? 0, active: active.type === "list" && active.uid === list.uid, onClick: () => handleSelect({ type: "list", uid: list.uid, name: list.name }) }, list.uid))) }), addingList && (_jsxs("form", { onSubmit: handleAddList, className: "flex items-center gap-1 px-2.5 mt-1", children: [_jsx("input", { type: "text", autoFocus: true, "aria-label": "New list name", id: `${idPrefix}-new-list-name`, value: newListName, onChange: (e) => setNewListName(e.target.value), className: "flex-1 text-xs py-1 px-1.5 border border-border rounded-sm bg-surface" }), _jsx("button", { type: "submit", className: "text-xs font-semibold text-primary-dark", children: "Add" })] }))] }), categories.length > 0 && (_jsxs("div", { children: [_jsx("h2", { className: "text-xs font-bold uppercase tracking-wide text-text-muted px-2.5 mb-1", children: "Categories" }), _jsx("div", { className: "flex flex-col gap-0.5", children: categories.map((name) => (_jsx(NavItem, { label: name, swatch: categoryColor(name), active: active.type === "category" && active.name === name, onClick: () => handleSelect({ type: "category", name }) }, name))) })] }))] }));
-    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "md:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open contacts menu", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) }), _jsx("nav", { "aria-label": "Contacts", className: "hidden md:flex w-56 shrink-0 border-r border-border flex-col gap-4 p-3 overflow-y-auto", children: navContent("desktop") }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Contacts", children: _jsx("div", { className: "flex flex-col gap-4", children: navContent("mobile") }) })] }));
+    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "lg:hidden m-3 mb-0 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open contacts menu", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) }), _jsx("nav", { "aria-label": "Contacts", className: "hidden lg:flex w-56 shrink-0 border-r border-border flex-col gap-4 p-3 overflow-y-auto", children: navContent("desktop") }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Contacts", children: _jsx("div", { className: "flex flex-col gap-4", children: navContent("mobile") }) })] }));
 }

package/dist/apps/shared/components/contacts/ContactsToolbar.d.ts

@@ -14,12 +14,16 @@ export interface ContactsToolbarProps {
     /** A `.vcf` file the user picked via the toolbar's own hidden file input — parsing/import is the
      * page's responsibility (it has the mailbox/folder context and the actual `createContact` calls). */
     onImportFile: (file: File) => void;
+    /** The keyboard's "New contact" is registered by the page: the button names its shortcut in its tooltip and `aria-keyshortcuts`. */
+    shortcuts?: boolean;
 }
 /**
- * Contacts' Outlook-style ribbon toolbar. Deliberately presentational — every action is a callback the
+ * Contacts' Outlook-style ribbon toolbar, fitted to its column (`ResponsiveToolbar`): captions under the icons while there is room, then icons
+ * alone, then the rarely used actions - Import, Export, Add category, and so on up - in a "More" menu; the bar can never spill into the pane
+ * beside it. Every button keeps its tooltip (New contact its shortcut's) and accessible name in every layout. Deliberately presentational — every action is a callback the
  * page (`apps/www/contacts/index.tsx`) implements, since it owns the actual contact data, the current
  * selection, and the mailbox/folder context every real action (create/delete/email/favorite/category)
  * needs. "New contact list" isn't duplicated here — `ContactsSidebar` already has its own inline
  * "+ New list" affordance next to the "Your contact lists" heading.
  */
-export default function ContactsToolbar({ selectedCount, allSelectedFavorited, onNewContact, onEdit, onDelete, onEmail, onToggleFavorite, onAddCategory, onExportVCard, onImportFile, }: ContactsToolbarProps): React.JSX.Element;
+export default function ContactsToolbar({ selectedCount, allSelectedFavorited, onNewContact, onEdit, onDelete, onEmail, onToggleFavorite, onAddCategory, onExportVCard, onImportFile, shortcuts, }: ContactsToolbarProps): React.JSX.Element;

package/dist/apps/shared/components/contacts/ContactsToolbar.js

@@ -1,24 +1,24 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 ///////////////////////////////////////////////////////////////////////////////
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import { useRef } from "react";
 import { HiOutlineArrowDownTray, HiOutlineArrowUpTray, HiOutlineEnvelope, HiOutlinePencil, HiOutlineStar, HiOutlineTag, HiOutlineTrash, HiOutlineUserPlus, HiStar, } from "react-icons/hi2";
-function ToolbarButton({ label, icon: Icon, disabled, onClick, }) {
-    return (_jsxs("button", { type: "button", onClick: onClick, disabled: disabled, className: "flex flex-col items-center gap-1 text-xs text-text-muted hover:text-text disabled:opacity-40 disabled:cursor-not-allowed px-2.5 py-1.5 rounded-sm hover:not-disabled:bg-surface-alt", children: [_jsx(Icon, { size: 18, "aria-hidden": "true" }), _jsx("span", { children: label })] }));
-}
-function Divider() {
-    return _jsx("div", { className: "w-px self-stretch my-1 bg-border", "aria-hidden": "true" });
-}
+import { SHORTCUTS } from "../../keyboard/keymap.js";
+import { useShortcutProps } from "../../keyboard/useShortcutProps.js";
+import ResponsiveToolbar from "../layout/ResponsiveToolbar.js";
 /**
- * Contacts' Outlook-style ribbon toolbar. Deliberately presentational — every action is a callback the
+ * Contacts' Outlook-style ribbon toolbar, fitted to its column (`ResponsiveToolbar`): captions under the icons while there is room, then icons
+ * alone, then the rarely used actions - Import, Export, Add category, and so on up - in a "More" menu; the bar can never spill into the pane
+ * beside it. Every button keeps its tooltip (New contact its shortcut's) and accessible name in every layout. Deliberately presentational — every action is a callback the
  * page (`apps/www/contacts/index.tsx`) implements, since it owns the actual contact data, the current
  * selection, and the mailbox/folder context every real action (create/delete/email/favorite/category)
  * needs. "New contact list" isn't duplicated here — `ContactsSidebar` already has its own inline
  * "+ New list" affordance next to the "Your contact lists" heading.
  */
-export default function ContactsToolbar({ selectedCount, allSelectedFavorited, onNewContact, onEdit, onDelete, onEmail, onToggleFavorite, onAddCategory, onExportVCard, onImportFile, }) {
+export default function ContactsToolbar({ selectedCount, allSelectedFavorited, onNewContact, onEdit, onDelete, onEmail, onToggleFavorite, onAddCategory, onExportVCard, onImportFile, shortcuts, }) {
+    const newContactHint = useShortcutProps("New contact", SHORTCUTS.contacts.create, !!shortcuts);
     const importInputRef = useRef(null);
     const hasSelection = selectedCount > 0;
     function handleImportFileChosen(e) {
@@ -28,5 +28,23 @@ export default function ContactsToolbar({ selectedCount, allSelectedFavorited, o
             onImportFile(file);
         }
     }
-    return (_jsxs("div", { role: "toolbar", "aria-label": "Contacts actions", className: "border-b border-border bg-surface-alt flex items-center gap-0.5 px-2 py-1", children: [_jsx(ToolbarButton, { label: "New contact", icon: HiOutlineUserPlus, onClick: onNewContact }), _jsx(Divider, {}), _jsx(ToolbarButton, { label: "Edit", icon: HiOutlinePencil, disabled: selectedCount !== 1, onClick: onEdit }), _jsx(ToolbarButton, { label: "Delete", icon: HiOutlineTrash, disabled: !hasSelection, onClick: onDelete }), _jsx(Divider, {}), _jsx(ToolbarButton, { label: "Email", icon: HiOutlineEnvelope, disabled: !hasSelection, onClick: onEmail }), _jsx(ToolbarButton, { label: allSelectedFavorited ? "Unfavorite" : "Favorite", icon: allSelectedFavorited ? HiStar : HiOutlineStar, disabled: !hasSelection, onClick: onToggleFavorite }), _jsx(ToolbarButton, { label: "Add category", icon: HiOutlineTag, disabled: !hasSelection, onClick: onAddCategory }), _jsx(Divider, {}), _jsx(ToolbarButton, { label: "Export", icon: HiOutlineArrowUpTray, disabled: !hasSelection, onClick: onExportVCard }), _jsx(ToolbarButton, { label: "Import", icon: HiOutlineArrowDownTray, onClick: () => importInputRef.current?.click() }), _jsx("input", { ref: importInputRef, type: "file", accept: ".vcf", className: "sr-only", "aria-label": "Import contacts file", onChange: handleImportFileChosen })] }));
+    const actions = [
+        { id: "new", label: "New contact", icon: HiOutlineUserPlus, onClick: onNewContact, hint: shortcuts ? newContactHint : undefined, group: 0, rank: 99, essential: true },
+        { id: "edit", label: "Edit", icon: HiOutlinePencil, onClick: onEdit, disabled: selectedCount !== 1, group: 1, rank: 6 },
+        { id: "delete", label: "Delete", icon: HiOutlineTrash, onClick: onDelete, disabled: !hasSelection, group: 1, rank: 5 },
+        { id: "email", label: "Email", icon: HiOutlineEnvelope, onClick: onEmail, disabled: !hasSelection, group: 2, rank: 4 },
+        {
+            id: "favorite",
+            label: allSelectedFavorited ? "Unfavorite" : "Favorite",
+            icon: allSelectedFavorited ? HiStar : HiOutlineStar,
+            onClick: onToggleFavorite,
+            disabled: !hasSelection,
+            group: 2,
+            rank: 3,
+        },
+        { id: "category", label: "Add category", icon: HiOutlineTag, onClick: onAddCategory, disabled: !hasSelection, group: 2, rank: 2 },
+        { id: "export", label: "Export", icon: HiOutlineArrowUpTray, onClick: onExportVCard, disabled: !hasSelection, group: 3, rank: 1 },
+        { id: "import", label: "Import", icon: HiOutlineArrowDownTray, onClick: () => importInputRef.current?.click(), group: 3, rank: 0 },
+    ];
+    return (_jsx(ResponsiveToolbar, { label: "Contacts actions", actions: actions, children: _jsx("input", { ref: importInputRef, type: "file", accept: ".vcf", className: "sr-only", "aria-label": "Import contacts file", onChange: handleImportFileChosen }) }));
 }

package/dist/apps/shared/components/contacts/layout/ContactsShell.d.ts

@@ -18,4 +18,4 @@ export declare function useContactsShell(): ContactsShellContextValue;
  * sidebar is therefore just a mailbox switcher (when the caller has more than one); the actual contact
  * list/detail UI is `apps/www/contacts/index.tsx`'s own content, rendered as `children` here.
  */
-export default function ContactsShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }: PropsWithChildren<ContactsShellProps>): React.JSX.Element;
+export default function ContactsShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, children, }: PropsWithChildren<ContactsShellProps>): React.JSX.Element;

package/dist/apps/shared/components/contacts/layout/ContactsShell.js

@@ -11,6 +11,7 @@ import { listFolders, listMailboxes } from "@rapidmx/react-shared/mail/mailApi.j
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
 import AppShell from "../../layout/AppShell.js";
+import { useLocationSearch, useNavigate } from "../../../navigation/AppRouter.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 const ContactsShellContext = createContext({ mailboxes: [] });
 /** Reads the mailbox/folder Contacts is currently showing, as resolved by the enclosing `ContactsShell`. */
@@ -24,7 +25,7 @@ export function useContactsShell() {
  * sidebar is therefore just a mailbox switcher (when the caller has more than one); the actual contact
  * list/detail UI is `apps/www/contacts/index.tsx`'s own content, rendered as `children` here.
  */
-export default function ContactsShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }) {
+export default function ContactsShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, children, }) {
     const [status, setStatus] = useState("checking");
     const [error, setError] = useState(null);
     const [mailboxes, setMailboxes] = useState([]);
@@ -32,9 +33,18 @@ export default function ContactsShell({ userUid, authServerUrl, impersonating, i
     const [folderError, setFolderError] = useState(null);
     const [requestedMailboxUid, setRequestedMailboxUid] = useState(null);
     const [drawerOpen, setDrawerOpen] = useState(false);
+    // Read from the router's location, so a mailbox change (a link, or `navigate()`) takes effect without a page load - and in an
+    // effect, not during render, so the server render and the hydrating render agree.
+    const search = useLocationSearch();
+    const navigate = useNavigate();
     useEffect(() => {
-        setRequestedMailboxUid(new URLSearchParams(window.location.search).get("mailboxUid"));
-    }, []);
+        setRequestedMailboxUid(new URLSearchParams(search).get("mailboxUid"));
+    }, [search]);
+    // Choosing a folder (or mailbox) changes the URL without a page load now, so the drawer that held the choice - which used to go
+    // with the page - is closed here.
+    useEffect(() => {
+        setDrawerOpen(false);
+    }, [search]);
     useEffect(() => {
         if (!userUid) {
             return;
@@ -85,9 +95,12 @@ export default function ContactsShell({ userUid, authServerUrl, impersonating, i
         // `id`/its `<label>`'s `htmlFor` need a distinct value per instance to avoid a duplicate-id
         // label-association break.
         const sidebarContent = (idPrefix) => (_jsxs(_Fragment, { children: [mailboxes.length > 1 && (_jsxs("div", { children: [_jsx("label", { className: "block text-xs font-bold uppercase tracking-wide text-text-muted mb-1", htmlFor: `${idPrefix}-contacts-mailbox-switcher`, children: "Mailbox" }), _jsx("select", { id: `${idPrefix}-contacts-mailbox-switcher`, className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: mailboxUid, onChange: (e) => {
-                                window.location.href = `/contacts?mailboxUid=${encodeURIComponent(e.target.value)}`;
+                                navigate(`/contacts?mailboxUid=${encodeURIComponent(e.target.value)}`);
                             }, children: mailboxes.map((mb) => (_jsxs("option", { value: mb.uid, children: [mb.displayName, mb.ownerUserUid ? "" : " (shared)"] }, mb.uid))) })] })), folderError && _jsx(Alert, { children: folderError })] }));
-        inner = (_jsxs(_Fragment, { children: [_jsx("aside", { className: "hidden md:flex w-56 shrink-0 bg-surface border-r border-border flex-col p-3 gap-3", children: sidebarContent("desktop") }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Mailbox", children: _jsx("div", { className: "flex flex-col gap-3", children: sidebarContent("mobile") }) }), _jsxs("main", { className: "flex-1 min-w-0 flex flex-col", children: [(mailboxes.length > 1 || folderError) && (_jsx("button", { type: "button", className: "md:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open mailbox switcher", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) })), _jsx(ContactsShellContext.Provider, { value: contextValue, children: children })] })] }));
+        // The mailbox switcher (or an error) is all this column holds: with a single mailbox and no error there is nothing to put in it, and an empty
+        // 224 px column beside the contacts' own menu is wasted room.
+        const hasSidebar = mailboxes.length > 1 || !!folderError;
+        inner = (_jsxs(_Fragment, { children: [hasSidebar && (_jsx("aside", { className: "hidden lg:flex w-56 shrink-0 bg-surface border-r border-border flex-col p-3 gap-3", children: sidebarContent("desktop") })), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Mailbox", children: _jsx("div", { className: "flex flex-col gap-3", children: sidebarContent("mobile") }) }), _jsxs("main", { className: "flex-1 min-w-0 flex flex-col", children: [hasSidebar && (_jsx("button", { type: "button", className: "lg:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open mailbox switcher", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) })), _jsx(ContactsShellContext.Provider, { value: contextValue, children: children })] })] }));
     }
-    return (_jsx(AppShell, { active: "contacts", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, pluginNav: pluginNav, children: inner }));
+    return (_jsx(AppShell, { active: "contacts", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, trustedRoles: trustedRoles, pluginNav: pluginNav, children: inner }));
 }

package/dist/apps/shared/components/escrow/layout/EscrowShell.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 ///////////////////////////////////////////////////////////////////////////////
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
@@ -13,6 +13,8 @@ import { getBranding } from "@rapidmx/react-shared/branding/brandingApi.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import BottomTabBar from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
 import UserMenu from "../../layout/UserMenu.js";
+import RailIcon from "../../layout/RailIcon.js";
+import AppearanceProvider from "../../../appearance/AppearanceProvider.js";
 import { signOutOfConsole } from "../../admin/signOut.js";
 const DEFAULT_ICON_SRC = "/images/logo.svg";
 const NAV_ITEMS = [
@@ -83,12 +85,13 @@ export default function EscrowShell({ active, userUid, authServerUrl, children }
     }
     else {
         const activeItem = NAV_ITEMS.find((item) => item.id === active);
-        content = (_jsx("div", { className: "min-h-screen flex flex-col bg-surface-alt", children: _jsxs("div", { className: "flex-1 flex min-h-0", children: [_jsxs("nav", { "aria-label": "Escrow sections", className: "hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1", children: [_jsx("img", { src: iconSrc, width: "96", height: "96", alt: "", className: "mb-3" }), NAV_ITEMS.map(({ id, href, label, icon: Icon }) => (_jsx("a", { href: href, "aria-label": label, "aria-current": id === active ? "page" : undefined, title: label, className: [
+        content = (_jsx("div", { className: "rr-frame-bg min-h-screen flex flex-col", children: _jsxs("div", { className: "flex-1 flex min-h-0", children: [_jsxs("nav", { "aria-label": "Escrow sections", className: "hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center pb-3 gap-1", children: [_jsx(RailIcon, { src: iconSrc }), NAV_ITEMS.map(({ id, href, label, icon: Icon }) => (_jsx("a", { href: href, "aria-label": label, "aria-current": id === active ? "page" : undefined, title: label, className: [
                                     "w-10 h-10 flex items-center justify-center rounded-sm",
                                     id === active
                                         ? "bg-primary/10 text-primary-dark"
                                         : "text-text-muted hover:bg-surface-alt hover:text-text",
-                                ].join(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] }), _jsx(BottomTabBar, { apps: NAV_ITEMS, active: active }), _jsxs("div", { className: "flex-1 flex flex-col min-w-0", children: [_jsxs("header", { className: "h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6", children: [_jsx("span", { className: "font-display font-bold text-lg uppercase tracking-wide", children: activeItem?.label }), _jsx(UserMenu, { userUid: userUid, authServerUrl: authServerUrl, onSignOut: handleSignOut })] }), _jsx("div", { className: "flex-1 pb-14 md:pb-0", children: _jsx("main", { className: "max-w-6xl mx-auto px-6 py-8", children: children }) })] })] }) }));
+                                ].join(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] }), _jsx(BottomTabBar, { apps: NAV_ITEMS, active: active }), _jsxs("div", { className: "flex-1 flex flex-col min-w-0", children: [_jsxs("header", { className: "rr-solid sticky top-0 z-30 h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6", children: [_jsx("span", { className: "font-display font-bold text-lg uppercase tracking-wide", children: activeItem?.label }), _jsx(UserMenu, { userUid: userUid, authServerUrl: authServerUrl, onSignOut: handleSignOut })] }), _jsx("div", { id: "app-content", className: "flex-1 pb-14 md:pb-0", children: _jsx("main", { className: "max-w-6xl mx-auto px-6 py-8", children: children }) })] })] }) }));
     }
-    return _jsx(_Fragment, { children: content });
+    // The user's own colours and background (`AppearanceProvider`), from what the last webmail page cached in this browser: the console never asks the server.
+    return (_jsx(AppearanceProvider, { userUid: userUid, lookUp: false, children: content }));
 }

package/dist/apps/shared/components/layout/AppShell.d.ts

@@ -2,6 +2,7 @@ import "../../styles/app.css";
 import React, { PropsWithChildren } from "react";
 import type { IconType } from "react-icons";
 import { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
+import type { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
 import { PluginNav, PluginNavProps } from "../../plugins/pluginNav.js";
 /** How long sign-out waits for auth-server's logout before navigating anyway. */
 export declare const LOGOUT_TIMEOUT_MS = 3000;
@@ -27,8 +28,17 @@ export interface AppShellProps extends PluginNavProps {
     impersonating?: boolean;
     /** Where `mailApi.ts`'s `stopImpersonating()` should call — see `MailShell`'s original doc comment. */
     impersonationBaseUrl?: string;
-    /** `true` when the caller's JWT carries a trusted role — shows an "Admin" item in the user menu below. */
+    /** `true` when the caller's JWT carries a trusted role — shows an "Admin Console" item in the user menu below. A token
+     * only carries one once elevated, so a real administrator with an ordinary session is `false` here; the user menu
+     * asks auth-server about them separately (see `UserMenu`'s `detectAdmin`). */
     trusted?: boolean;
+    /** The role names the server treats as trusted (its `trusted_roles` config, injected via the route's `fetchProps`) -
+     * what that lookup looks for. Absent means the server's own default, `["admin"]`. */
+    trustedRoles?: string[];
+    /** The deployment's branding as the server rendered the page (its `branding` prop). Used until the frame's own fetch answers, so a custom header is there from the first paint - and the frame knows to drop its own title bar - instead of appearing (and moving everything) once the request returns. */
+    branding?: Branding;
+    /** The signed-in user's stored appearance preferences as the server rendered the page (its `appearance` prop), so the first paint already wears the theme and background - see `AppearanceProvider`. */
+    appearance?: unknown;
 }
 export interface AppDef {
     id: AppShellApp;
@@ -39,11 +49,31 @@ export interface AppDef {
 export declare const APPS: AppDef[];
 /** `APPS` followed by the plugins' `appRail` items (generic icon), core ids winning - see `mergePluginNavItems`. */
 export declare function appRailItems(pluginNav?: PluginNav): NavItem[];
+/** What only the persistent frame (`AppRouter`) passes to the chrome it keeps mounted. */
+export interface AppChromeProps extends AppShellProps {
+    /** Changes whenever the router shows a different page: the chrome then moves focus to the content, scrolls to its top,
+     * sets the document title and announces the page. Absent outside the router, when nothing does. */
+    routeKey?: string;
+    /** The router is loading the next page's code - the content is `aria-busy`. */
+    busy?: boolean;
+    /** A screen that takes over the window (`FrameTakeover`) is showing: the rail, header, banner and footer are hidden - not
+     * unmounted, so what is inside them (and the page in the content region) keeps its state. */
+    hideChrome?: boolean;
+}
 /**
  * The persistent chrome shared by every webmail app (Mail, Calendar, Contacts, Tasks): a left icon rail for
- * switching apps (full page loads — see `MailShell`'s original doc comment on this framework having no
- * client-side router), a header with the current app's name and `UserMenu`, and the impersonation banner.
+ * switching apps, a header with the current app's name and `UserMenu`, and the impersonation banner.
  * Each app's own shell (e.g. `MailShell`) renders its own contextual sidebar + content as `children`, inside
  * the area to the right of the icon rail and below the header.
+ *
+ * Rendered by `AppRouter`, once, for the life of the page, so that moving between apps replaces only `children` - see
+ * `AppShell` below for what a page's own shell renders instead.
+ */
+export declare function AppChrome({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, branding: initialBranding, appearance, pluginNav, routeKey, busy, hideChrome, children, }: PropsWithChildren<AppChromeProps>): React.JSX.Element;
+/**
+ * What a page's own shell (`MailShell`, `CalendarShell`, ...) renders around its content. Outside the client-side router it
+ * is the whole `AppChrome`, as it always was. Inside it (`AppRouter`) the chrome is already mounted above the page - and stays
+ * mounted as the page is replaced - so this is only its children; everything it would have been given comes from the router
+ * frame instead (the props are the same for every page, and `active` is the route's).
  */
-export default function AppShell({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }: PropsWithChildren<AppShellProps>): React.JSX.Element;
+export default function AppShell(props: PropsWithChildren<AppShellProps>): React.JSX.Element;

package/dist/apps/shared/components/layout/AppShell.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 ///////////////////////////////////////////////////////////////////////////////
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
@@ -14,14 +14,33 @@ import { useIdleKeyTimeout } from "@rapidmx/react-shared/crypto/useIdleKeyTimeou
 import ComposeProvider from "../mail/compose/ComposeContext.js";
 import { flushComposeDrafts, markSigningOut } from "../mail/compose/composeFlushRegistry.js";
 import BottomTabBar from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
-import { BrandingFooter, BrandingHeader } from "./BrandingChrome.js";
+import { FrameBrandingFooter, FrameBrandingHeader, useBrandingHtml } from "./BrandingChrome.js";
+import RailIcon from "./RailIcon.js";
+import AppearanceProvider from "../../appearance/AppearanceProvider.js";
+import { clearAppearanceCache } from "../../appearance/appearanceCache.js";
 import UserMenu from "./UserMenu.js";
 import { UnlockPromptProvider } from "./UnlockPromptProvider.js";
 import { SIGN_OUT_CHANNEL, destroyAllLocalIndexes } from "../../search/localIndexRpcClient.js";
-import { authApiFetch } from "@rapidmx/react-shared/util/api.js";
+import { authApiFetch, setApiUnauthorizedObserver } from "@rapidmx/react-shared/util/api.js";
 import { destroyUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
 import { clearPinnedSignerCache } from "../mail/pinnedSigners.js";
 import { mergePluginNavItems } from "../../plugins/pluginNav.js";
+import { useInAppFrame } from "../../navigation/frameContext.js";
+import { APP_HREFS } from "../../navigation/appHrefs.js";
+import { useNavigate } from "../../navigation/routerContext.js";
+import { GlobalShortcuts } from "../../keyboard/GlobalShortcuts.js";
+import { ShortcutProvider } from "../../keyboard/ShortcutProvider.js";
+import ShortcutsDialog from "../../keyboard/ShortcutsDialog.js";
+import { inboxUnreadTotal } from "../../mail/folderCounts.js";
+import { MailConnectionContext, useMailConnection } from "../../mail/useMailConnection.js";
+import { useUnreadTitle } from "../../mail/useUnreadTitle.js";
+import UnlockBridge from "../../mail/outbox/UnlockBridge.js";
+import NotificationCenter from "../../notifications/NotificationCenter.js";
+import { useHeaderHeightRef } from "../../notifications/headerOffset.js";
+import NotificationHistoryDialog from "../../notifications/NotificationHistoryDialog.js";
+import { notifySessionExpired, setSignInUrl } from "../../notifications/apiErrors.js";
+import { useUnseenErrorCount } from "../../notifications/useNotifications.js";
+import { useSigningEnrollmentWatcher } from "../../signing/useSigningEnrollmentWatcher.js";
 /** How long sign-out waits for auth-server's logout before navigating anyway. */
 export const LOGOUT_TIMEOUT_MS = 3000;
 /**
@@ -46,10 +65,10 @@ async function logOutOfAuthServer(authServerUrl) {
     }
 }
 export const APPS = [
-    { id: "mail", href: "/", label: "Mail", icon: HiOutlineEnvelope },
-    { id: "calendar", href: "/calendar", label: "Calendar", icon: HiOutlineCalendarDays },
-    { id: "contacts", href: "/contacts", label: "Contacts", icon: HiOutlineUsers },
-    { id: "tasks", href: "/tasks", label: "Tasks", icon: HiOutlineClipboardDocumentList },
+    { id: "mail", href: APP_HREFS.mail, label: "Mail", icon: HiOutlineEnvelope },
+    { id: "calendar", href: APP_HREFS.calendar, label: "Calendar", icon: HiOutlineCalendarDays },
+    { id: "contacts", href: APP_HREFS.contacts, label: "Contacts", icon: HiOutlineUsers },
+    { id: "tasks", href: APP_HREFS.tasks, label: "Tasks", icon: HiOutlineClipboardDocumentList },
 ];
 /** Ids plugin `appRail` items can't take besides `APPS`' own - `"settings"` has no rail icon but is still a
  * core `active` value. */
@@ -60,16 +79,51 @@ export function appRailItems(pluginNav) {
 }
 /**
  * The persistent chrome shared by every webmail app (Mail, Calendar, Contacts, Tasks): a left icon rail for
- * switching apps (full page loads — see `MailShell`'s original doc comment on this framework having no
- * client-side router), a header with the current app's name and `UserMenu`, and the impersonation banner.
+ * switching apps, a header with the current app's name and `UserMenu`, and the impersonation banner.
  * Each app's own shell (e.g. `MailShell`) renders its own contextual sidebar + content as `children`, inside
  * the area to the right of the icon rail and below the header.
+ *
+ * Rendered by `AppRouter`, once, for the life of the page, so that moving between apps replaces only `children` - see
+ * `AppShell` below for what a page's own shell renders instead.
  */
-export default function AppShell({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }) {
+export function AppChrome({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, branding: initialBranding, appearance, pluginNav, routeKey, busy, hideChrome, children, }) {
     const [stoppingImpersonation, setStoppingImpersonation] = useState(false);
+    // The keyboard shortcuts dialog: opened by `?`/Ctrl+/ (`GlobalShortcuts`) and by the account menu's item.
+    const [shortcutsOpen, setShortcutsOpen] = useState(false);
+    // The pop-up history ("Recent notifications" in the account menu). The pop-ups themselves are drawn by `NotificationCenter`, below.
+    const [historyOpen, setHistoryOpen] = useState(false);
+    // Only the count is read, so the whole frame does not render again for every pop-up that comes and goes.
+    const unseenErrors = useUnseenErrorCount();
+    // The title bar's height for the pop-up stack, which sticks just below the header (a branding header publishes its own - `FrameBrandingHeader`).
+    const headerRef = useHeaderHeightRef();
     const signingOutRef = useRef(false);
-    const { branding, iconSrc } = useBranding();
+    const { branding: fetchedBranding, iconSrc: fetchedIconSrc } = useBranding();
+    // The server's copy until the fetch answers, so the frame's shape (a custom header replaces the title bar) never changes after the first paint.
+    const branding = fetchedBranding ?? initialBranding ?? null;
+    const iconSrc = fetchedBranding ? fetchedIconSrc : initialBranding?.iconUrl || initialBranding?.logoUrl || fetchedIconSrc;
+    // The custom header and footer, sanitized and with their `{USER_MENU}` / `{APP_TITLE}` placeholders (`undefined` until parsed, `null` when there is none).
+    const header = useBrandingHtml(branding?.headerHtml);
+    const footer = useBrandingHtml(branding?.footerHtml);
+    // The mailboxes, their folders and the one push connection live here, in the frame that stays mounted as the router swaps pages - so
+    // new-mail pop-ups, the folder counters and the tab title's unread count work in Calendar, Contacts, Tasks and Settings too, and moving
+    // between apps never opens a second socket (the server allows ten per user). `MailShell` reads them from `MailConnectionContext`. Outside
+    // the router (`AppShell` rendered as a page's own chrome: tests, plugin pages) it stays off, and a Mail shell owns its connection itself.
+    const inFrame = useInAppFrame();
+    const navigate = useNavigate();
+    const mail = useMailConnection({ userUid, enabled: inFrame, open: navigate });
+    // A signing certificate the user asked for is announced when it is issued (or fails), on whichever page they are - see the hook.
+    useSigningEnrollmentWatcher({ userUid, mailboxes: mail.mailboxes, enabled: inFrame });
     useRedirectIfUnauthenticated(userUid, authServerUrl);
+    // Any request this app makes that the server answers with a 401 - the session ended - raises one "Your session expired" pop-up with a
+    // Sign in action (see `notifySessionExpired()`), whichever request noticed first, a background refresh included.
+    useEffect(() => {
+        setSignInUrl(authServerUrl);
+        if (!userUid) {
+            return;
+        }
+        setApiUnauthorizedObserver(() => void notifySessionExpired());
+        return () => setApiUnauthorizedObserver(undefined);
+    }, [userUid, authServerUrl]);
     // Mounted here, not scoped to Mail/Settings (the only shells that actually read unlocked keys),
     // specifically so activity in *any* app resets the idle clock - see that hook's own doc comment.
     useIdleKeyTimeout();
@@ -109,6 +163,7 @@ export default function AppShell({ active, userUid, authServerUrl, impersonating
             markSigningOut();
             destroyUnlockedKeys();
             clearPinnedSignerCache();
+            clearAppearanceCache();
             // Bounded by its own timeout and never rejects - awaited so navigating doesn't kill the Worker mid-delete.
             void destroyAllLocalIndexes().then(() => {
                 window.location.href = authServerUrl ?? "/";
@@ -125,6 +180,7 @@ export default function AppShell({ active, userUid, authServerUrl, impersonating
         destroyUnlockedKeys();
         // Trusted signer pins read from contacts don't outlive the session either.
         clearPinnedSignerCache();
+        clearAppearanceCache();
         // Open compose windows save edits still waiting on their autosave debounce while the session is still
         // valid - logout invalidates it. Bounded the same way as logout itself, and never rejects.
         await flushComposeDrafts(LOGOUT_TIMEOUT_MS);
@@ -151,16 +207,65 @@ export default function AppShell({ active, userUid, authServerUrl, impersonating
             window.location.href = "/admin";
         }
     }
+    // What the persistent frame (`AppRouter`) needs on top of a page that never changes: the document title follows the page, and
+    // after the router replaces the page the keyboard focus, the scroll position and a screen reader are told about it - a
+    // page load did all of that by itself. Nothing here runs for a page shown outside the router (`routeKey` is undefined).
+    const contentRef = useRef(null);
+    const [announcement, setAnnouncement] = useState("");
+    const firstRouteKeyRef = useRef(routeKey);
+    const pageLabel = active === "settings" ? "Settings" : appRailItems(pluginNav).find((app) => app.id === active)?.label;
+    useEffect(() => {
+        if (routeKey !== undefined) {
+            const brand = branding?.title || branding?.companyName || "RapidMX";
+            document.title = pageLabel ? `${brand}: ${pageLabel}` : brand;
+        }
+    }, [routeKey, pageLabel, branding]);
+    // After the title effect above, so a page change (which rewrites the title) is followed by the unread count going back in front of it.
+    useUnreadTitle(inboxUnreadTotal(mail.mailboxFolders, mail.folderCounts.counts), {
+        enabled: inFrame,
+        resetKey: `${routeKey}|${pageLabel}|${branding?.title}|${branding?.companyName}`,
+    });
+    useEffect(() => {
+        if (routeKey === undefined || routeKey === firstRouteKeyRef.current) {
+            return;
+        }
+        setAnnouncement(pageLabel ?? "");
+        contentRef.current?.focus({ preventScroll: true });
+        window.scrollTo(0, 0);
+    }, [routeKey]);
     if (!userUid) {
         return _jsx("div", { className: "min-h-screen" });
     }
     const apps = appRailItems(pluginNav);
     // The header title: "settings" has no rail item, everything else is labelled by its own rail item.
     const activeLabel = active === "settings" ? "Settings" : apps.find((app) => app.id === active)?.label;
-    return (_jsx(UnlockPromptProvider, { children: _jsx(ComposeProvider, { userUid: userUid, trusted: !!trusted && !impersonating, children: _jsxs("div", { className: "min-h-screen flex flex-col bg-surface-alt", children: [_jsx(BrandingHeader, { branding: branding }), impersonating && (_jsxs("div", { className: "h-10 shrink-0 bg-warning text-warning-contrast flex items-center justify-center gap-3 text-sm font-medium px-4", children: [_jsxs("span", { children: ["You are viewing as ", _jsx("strong", { children: userUid }), "."] }), _jsx("button", { type: "button", onClick: handleStopImpersonating, disabled: stoppingImpersonation, className: "underline hover:no-underline disabled:opacity-60", children: stoppingImpersonation ? "Returning to admin…" : "Return to admin" })] })), _jsxs("div", { className: "flex-1 flex min-h-0", children: [_jsxs("nav", { "aria-label": "Apps", className: "hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1", children: [_jsx("img", { src: iconSrc, width: "96", height: "96", alt: "", className: "mb-3" }), apps.map(({ id, href, label, icon: Icon }) => (_jsx("a", { href: href, "aria-label": label, "aria-current": id === active ? "page" : undefined, title: label, className: [
-                                            "w-10 h-10 flex items-center justify-center rounded-sm",
-                                            id === active
-                                                ? "bg-primary/10 text-primary-dark"
-                                                : "text-text-muted hover:bg-surface-alt hover:text-text",
-                                        ].join(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] }), _jsx(BottomTabBar, { apps: apps, active: active }), _jsxs("div", { className: "flex-1 flex flex-col min-w-0", children: [_jsxs("header", { className: "h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6", children: [_jsx("span", { className: "font-display font-bold text-lg uppercase tracking-wide", children: activeLabel }), _jsx(UserMenu, { userUid: userUid, authServerUrl: authServerUrl, onSignOut: handleSignOut, showAdminLink: trusted, showSettingsLink: true })] }), _jsx("div", { className: "flex-1 flex min-h-0 pb-14 md:pb-0", children: children })] })] }), _jsx(BrandingFooter, { branding: branding })] }) }) }));
+    // A custom header (`Branding.headerHtml`) replaces the app's own title bar and the icon at the top of the rail: it is the top of the app, and the
+    // account menu moves into it. While it is still being parsed it already counts, so the frame's shape doesn't change under the user.
+    const customHeader = header !== null;
+    // Where the one account menu lives: the header's `{USER_MENU}`, else the footer's, else a small cell at the header's right end - never lost.
+    const menuInHeader = !!header?.hasUserMenu;
+    const menuInFooter = customHeader && !!header && !menuInHeader && !!footer?.hasUserMenu;
+    const renderUserMenu = (placement) => (_jsx(UserMenu, { userUid: userUid, authServerUrl: authServerUrl, onSignOut: handleSignOut, 
+        // An impersonating administrator acts as the impersonated user, so the console link is hidden then.
+        showAdminLink: !!trusted && !impersonating, detectAdmin: !trusted && !impersonating, trustedRoles: trustedRoles, showSettingsLink: true, showNotificationSettings: true, onShowShortcuts: () => setShortcutsOpen(true), onShowNotifications: () => setHistoryOpen(true), unseenErrors: unseenErrors, placement: placement }));
+    return (_jsx(AppearanceProvider, { userUid: userUid, initial: appearance, lookUp: inFrame, children: _jsx(ShortcutProvider, { children: _jsxs(MailConnectionContext.Provider, { value: inFrame ? mail : null, children: [_jsx(GlobalShortcuts, { authServerUrl: authServerUrl, onToggleHelp: () => setShortcutsOpen((open) => !open) }), _jsx(ShortcutsDialog, { open: shortcutsOpen, onClose: () => setShortcutsOpen(false) }), _jsxs(UnlockPromptProvider, { children: [_jsx(UnlockBridge, {}), _jsx(ComposeProvider, { userUid: userUid, trusted: !!trusted && !impersonating, children: _jsxs("div", { className: "rr-frame-bg min-h-screen flex flex-col", children: [!hideChrome && customHeader && (_jsx(FrameBrandingHeader, { parsed: header, userMenu: menuInHeader ? renderUserMenu("down") : undefined, fallbackMenu: header && !menuInHeader && !menuInFooter ? renderUserMenu("down") : undefined, appTitle: activeLabel })), impersonating && !hideChrome && (_jsxs("div", { className: "h-10 shrink-0 bg-warning text-warning-contrast flex items-center justify-center gap-3 text-sm font-medium px-4", children: [_jsxs("span", { children: ["You are viewing as ", _jsx("strong", { children: userUid }), "."] }), _jsx("button", { type: "button", onClick: handleStopImpersonating, disabled: stoppingImpersonation, className: "underline hover:no-underline disabled:opacity-60", children: stoppingImpersonation ? "Returning to admin…" : "Return to admin" })] })), _jsxs("div", { className: "flex-1 flex min-h-0", children: [!hideChrome && (_jsxs("nav", { "aria-label": "Apps", className: [
+                                                        "hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center gap-1",
+                                                        // Under a custom header the rail starts with the app icons; without one its own icon is flush with the top of the window.
+                                                        customHeader ? "py-3" : "pb-3",
+                                                    ].join(" "), children: [!customHeader && (_jsx(RailIcon, { src: iconSrc })), apps.map(({ id, href, label, icon: Icon }) => (_jsx("a", { href: href, "aria-label": label, "aria-current": id === active ? "page" : undefined, title: label, className: [
+                                                                "w-10 h-10 flex items-center justify-center rounded-sm",
+                                                                id === active
+                                                                    ? "bg-primary/10 text-primary-dark"
+                                                                    : "text-text-muted hover:bg-surface-alt hover:text-text",
+                                                            ].join(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] })), !hideChrome && _jsx(BottomTabBar, { apps: apps, active: active }), _jsxs("div", { className: "flex-1 flex flex-col min-w-0", children: [!hideChrome && !customHeader && (_jsxs("header", { ref: headerRef, className: "rr-solid sticky top-0 z-30 h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6", children: [_jsx("span", { className: "font-display font-bold text-lg uppercase tracking-wide", children: activeLabel }), renderUserMenu("down")] })), _jsx(NotificationCenter, {}), _jsx("div", { ref: contentRef, id: "app-content", tabIndex: -1, "aria-busy": busy || undefined, className: ["flex-1 flex min-h-0 outline-none", hideChrome ? "" : "pb-14 md:pb-0"].join(" "), children: children })] })] }), routeKey !== undefined && (_jsx("div", { role: "status", "aria-live": "polite", className: "sr-only", children: announcement })), !hideChrome && _jsx(FrameBrandingFooter, { parsed: footer, userMenu: menuInFooter ? renderUserMenu("up") : undefined, appTitle: activeLabel })] }) })] }), _jsx(NotificationHistoryDialog, { open: historyOpen, onClose: () => setHistoryOpen(false) })] }) }) }));
+}
+/**
+ * What a page's own shell (`MailShell`, `CalendarShell`, ...) renders around its content. Outside the client-side router it
+ * is the whole `AppChrome`, as it always was. Inside it (`AppRouter`) the chrome is already mounted above the page - and stays
+ * mounted as the page is replaced - so this is only its children; everything it would have been given comes from the router
+ * frame instead (the props are the same for every page, and `active` is the route's).
+ */
+export default function AppShell(props) {
+    const inFrame = useInAppFrame();
+    return inFrame ? _jsx(_Fragment, { children: props.children }) : _jsx(AppChrome, { ...props });
 }