@rapidmx/web-client 0.8.0 → 0.10.0

package/dist/apps/shared/components/admin/layout/AdminShell.js

@@ -11,9 +11,11 @@ import { getSetupStatus } from "@rapidmx/react-shared/admin/setupApi.js";
 import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
 import useBranding from "@rapidmx/react-shared/branding/useBranding.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
 import BottomTabBar from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
-import { BrandingFooter, BrandingHeader } from "../../layout/BrandingChrome.js";
+import { BrandingFooter } from "../../layout/BrandingChrome.js";
 import UserMenu from "../../layout/UserMenu.js";
+import { clearElevationAttempt, elevationAttemptedRecently, elevationUrl, isElevationRequired, recordElevationAttempt, } from "../elevation.js";
 import { signOutOfConsole } from "../signOut.js";
 import { mergePluginNavItems } from "../../../plugins/pluginNav.js";
 /** Sections shown in the persistent icon rail / mobile tab bar — every admin area reachable from
@@ -84,14 +86,24 @@ export function adminNavItems(pluginNav) {
     return mergePluginNavItems(NAV_ITEMS, pluginNav?.adminNav, ({ id, href, label }) => ({ id, href, label, icon: HiOutlinePuzzlePiece }), OFF_RAIL_ITEMS.map((item) => item.id));
 }
 /**
- * Gates every `apps/admin` page behind the `admin` trusted role. Uses `GET /api/admin/release-notes` (any
- * `BaseAdminRoute` endpoint works — this one is side-effect-free) purely as a canary: a 200 means the
- * caller's JWT carries a trusted role, a 403 means it doesn't. There is no local step-up/elevation flow
- * (that would need a cross-origin call to auth-server's own elevation endpoint — not wired up yet).
+ * Gates every `apps/admin` page behind the `admin` trusted role, and behind an elevated session. Uses
+ * `GET /api/admin/release-notes` (any `BaseAdminRoute` endpoint works — this one is side-effect-free) purely as a
+ * canary. The endpoint is class-level `@RequiresElevation()`, checked *before* the trusted-role check, so a 200 means the
+ * caller's JWT is elevated and carries a trusted role: show the console. Otherwise:
+ *
+ * 403 `api-104` means the JWT isn't elevated (an administrator's normal sign-in). There is no local step-up form; the
+ * browser is sent to auth-server's `/auth/elevate?return_to=<this page>`, which returns it here once the user has
+ * confirmed their identity (or to its own account page if they cancel). Sent at most once per
+ * `ELEVATION_RETRY_WINDOW_MS`, so an elevated cookie that never reaches this origin can't bounce the browser back
+ * and forth - see `elevation.ts`, and the "didn't take effect" alert with its own "Try again" below.
+ *
+ * 403 `api-103` (elevated, but not an administrator), any other 403, and 401 mean "no administrator access".
  */
 export default function AdminShell({ active, userUid, authServerUrl, pluginNav, children }) {
     const [status, setStatus] = useState("checking");
     const [error, setError] = useState(null);
+    // `branding` only feeds the footer below: the admin-configured header is for the webmail and public pages, not the
+    // console. `useBranding()` is still what injects the custom stylesheet and supplies the rail's icon.
     const { branding, iconSrc } = useBranding();
     useRedirectIfUnauthenticated(userUid, authServerUrl);
     useEffect(() => {
@@ -100,6 +112,8 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
         }
         apiFetch("/admin/release-notes")
             .then(async () => {
+            // Elevated (or elevation isn't needed): a later expiry of the elevation may send the user round again.
+            clearElevationAttempt();
             // Until first-run setup is finished, every other admin page sends the admin to the wizard. A failed
             // check never blocks the console - the admin can still reach setup from the Mailboxes page.
             if (active !== "setup") {
@@ -116,6 +130,19 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
             setStatus("authorized");
         })
             .catch((err) => {
+            if (isElevationRequired(err)) {
+                // Without auth-server's URL there is nowhere to send the browser to elevate.
+                if (!authServerUrl) {
+                    setStatus("denied");
+                }
+                else if (elevationAttemptedRecently()) {
+                    setStatus("elevationFailed");
+                }
+                else {
+                    startElevation(authServerUrl);
+                }
+                return;
+            }
             if (err instanceof ApiRequestError && (err.status === 403 || err.status === 401)) {
                 setStatus("denied");
                 return;
@@ -124,6 +151,16 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
             setStatus("error");
         });
     }, [userUid]);
+    /** Remembers the attempt, then sends the browser to auth-server to confirm the user's identity. */
+    function startElevation(authServer) {
+        recordElevationAttempt();
+        setStatus("elevating");
+        window.location.href = elevationUrl(authServer, window.location.href);
+    }
+    function handleRetryElevation() {
+        clearElevationAttempt();
+        startElevation(authServerUrl);
+    }
     function handleSignOut() {
         // Ends the auth-server session and tells other tabs, not just navigates - see `signOutOfConsole()`.
         void signOutOfConsole(authServerUrl);
@@ -132,6 +169,12 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
     if (!userUid || status === "checking") {
         content = _jsx("div", { className: "min-h-screen" });
     }
+    else if (status === "elevating") {
+        content = (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8", children: _jsx("p", { role: "status", className: "text-sm text-text-muted", children: "Redirecting to confirm your identity\u2026" }) }));
+    }
+    else if (status === "elevationFailed") {
+        content = (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8", children: _jsxs("div", { className: "w-full max-w-md flex flex-col items-start", children: [_jsx(Alert, { children: "Confirming your identity didn\u2019t take effect, so the administrator console is still locked. Try again, and if this keeps happening, sign out and sign back in." }), _jsx(Button, { type: "button", className: "!w-auto", onClick: handleRetryElevation, children: "Try again" })] }) }));
+    }
     else if (status === "denied") {
         content = (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8", children: _jsx("div", { className: "w-full max-w-md", children: _jsx(Alert, { children: "You do not have administrator access." }) }) }));
     }
@@ -148,5 +191,5 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
                                         : "text-text-muted hover:bg-surface-alt hover:text-text",
                                 ].join(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] }), _jsx(BottomTabBar, { apps: navItems, 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 }) })] })] }) }));
     }
-    return (_jsxs(_Fragment, { children: [_jsx(BrandingHeader, { branding: branding }), content, _jsx(BrandingFooter, { branding: branding })] }));
+    return (_jsxs(_Fragment, { children: [content, _jsx(BrandingFooter, { branding: branding })] }));
 }

package/dist/apps/shared/components/admin/settings/BrandingForm.js

@@ -104,7 +104,7 @@ export default function BrandingForm({ branding, onChange, embedded = false }) {
             setSaving(false);
         }
     }
-    return (_jsxs("div", { className: "max-w-2xl", children: [!embedded && (_jsxs(_Fragment, { children: [_jsx("h1", { className: "text-xl font-bold uppercase tracking-wide mb-1", children: "Branding" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "Customize the logo, nav-header icon, product name, and chrome shown to every visitor of the webmail and admin console \u2014 including anonymous booking-page visitors." })] })), error && _jsx(Alert, { children: error }), saved && !error && _jsx("div", { className: "mb-4 text-sm text-success font-medium", children: "Saved." }), _jsxs("div", { className: "flex flex-col gap-6", children: [_jsxs("section", { className: "flex flex-col gap-3", children: [_jsx(SectionHeading, { className: "text-sm font-bold uppercase tracking-wide text-text-muted", children: "Logo" }), _jsxs("div", { className: "flex items-center gap-4", children: [_jsx("img", { src: branding.logoUrl || "/images/logo.svg", alt: "Current logo", width: "64", height: "64", className: "border border-border rounded-sm bg-surface-alt p-1" }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", loading: assetBusy === "logo-upload", disabled: assetBusy !== null, onClick: () => logoFileRef.current?.click(), children: "Upload logo" }), _jsx("input", { ref: logoFileRef, type: "file", accept: RASTER_IMAGE_ACCEPT, "aria-label": "Upload logo", className: "hidden", onChange: handleLogoFileChange }), branding.logoUrl && (_jsx(Button, { type: "button", variant: "text", disabled: assetBusy !== null, loading: assetBusy === "logo-delete", onClick: () => void runAsset("logo-delete", async () => {
+    return (_jsxs("div", { className: "max-w-2xl", children: [!embedded && (_jsxs(_Fragment, { children: [_jsx("h1", { className: "text-xl font-bold uppercase tracking-wide mb-1", children: "Branding" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "Customize the logo, nav-header icon, product name, and chrome shown to every visitor of the webmail and admin console \u2014 including anonymous booking-page visitors. The header appears on the webmail and public pages, not in the admin console; the footer appears in both." })] })), error && _jsx(Alert, { children: error }), saved && !error && _jsx("div", { className: "mb-4 text-sm text-success font-medium", children: "Saved." }), _jsxs("div", { className: "flex flex-col gap-6", children: [_jsxs("section", { className: "flex flex-col gap-3", children: [_jsx(SectionHeading, { className: "text-sm font-bold uppercase tracking-wide text-text-muted", children: "Logo" }), _jsxs("div", { className: "flex items-center gap-4", children: [_jsx("img", { src: branding.logoUrl || "/images/logo.svg", alt: "Current logo", width: "64", height: "64", className: "border border-border rounded-sm bg-surface-alt p-1" }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", loading: assetBusy === "logo-upload", disabled: assetBusy !== null, onClick: () => logoFileRef.current?.click(), children: "Upload logo" }), _jsx("input", { ref: logoFileRef, type: "file", accept: RASTER_IMAGE_ACCEPT, "aria-label": "Upload logo", className: "hidden", onChange: handleLogoFileChange }), branding.logoUrl && (_jsx(Button, { type: "button", variant: "text", disabled: assetBusy !== null, loading: assetBusy === "logo-delete", onClick: () => void runAsset("logo-delete", async () => {
                                                     await deleteBrandingLogo();
                                                     return { ...branding, logoUrl: undefined };
                                                 }), children: "Remove logo" }))] })] }), _jsxs("label", { className: "flex flex-col gap-1.5 text-sm", children: [_jsx("span", { className: "font-semibold", children: "Or use an external image URL" }), _jsxs("div", { className: "flex gap-2", children: [_jsx("input", { "aria-label": "Logo URL", className: INPUT_CLASS, value: logoUrlInput, onChange: (e) => setLogoUrlInput(e.target.value) }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", disabled: assetBusy !== null || logoUrlInput === (branding.logoUrl ?? ""), loading: assetBusy === "logo-url", onClick: () => void runAsset("logo-url", () => updateBranding({ logoUrl: logoUrlInput })), children: "Set" })] })] })] }), _jsxs("section", { className: "flex flex-col gap-3", children: [_jsx(SectionHeading, { className: "text-sm font-bold uppercase tracking-wide text-text-muted", children: "Icon" }), _jsx("p", { className: "text-xs text-text-muted -mt-1", children: "A compact mark for navigation headers, independent of the full logo above. Falls back to the logo, then a default asset, when not set." }), _jsxs("div", { className: "flex items-center gap-4", children: [_jsx("img", { src: branding.iconUrl || branding.logoUrl || "/images/logo.svg", alt: "Current icon", width: "64", height: "64", className: "border border-border rounded-sm bg-surface-alt p-1" }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", loading: assetBusy === "icon-upload", disabled: assetBusy !== null, onClick: () => iconFileRef.current?.click(), children: "Upload icon" }), _jsx("input", { ref: iconFileRef, type: "file", accept: RASTER_IMAGE_ACCEPT, "aria-label": "Upload icon", className: "hidden", onChange: handleIconFileChange }), branding.iconUrl && (_jsx(Button, { type: "button", variant: "text", disabled: assetBusy !== null, loading: assetBusy === "icon-delete", onClick: () => void runAsset("icon-delete", async () => {

package/dist/apps/shared/components/admin/settings/DomainDnsSetup.js

@@ -8,6 +8,7 @@ import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { getDnsSetup, getDomain, verifyDomain } from "@rapidmx/react-shared/admin/domainsApi.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import CopyButton from "@rapidmx/react-shared/components/buttons/CopyButton.js";
 const RECORD_TYPE_LABELS = {
     ownership: "Ownership (TXT)",
     mx: "MX",
@@ -15,6 +16,23 @@ const RECORD_TYPE_LABELS = {
     dkim: "DKIM",
     dmarc: "DMARC",
 };
+/** How each record is named in a Copy button's accessible name ("Copy value for the SPF record"). */
+const RECORD_TYPE_NAMES = {
+    ownership: "ownership TXT",
+    mx: "MX",
+    spf: "SPF",
+    dkim: "DKIM",
+    dmarc: "DMARC",
+};
+/** An MX record's recommended value is `"<priority> <mail server>"` - two separate fields in a DNS provider's form. */
+function splitMxValue(value) {
+    const match = /^(\d+)\s+(\S+)$/.exec(value.trim());
+    return match ? { priority: match[1], server: match[2] } : null;
+}
+/** A value to type into a DNS provider's form, shown in full (long DKIM keys wrap) with a Copy button beside it. */
+function CopyableValue({ value, copyLabel }) {
+    return (_jsxs("div", { className: "flex items-start gap-2", children: [_jsx("code", { className: "flex-1 min-w-0 text-xs break-all", children: value }), _jsx(CopyButton, { value: value, label: copyLabel })] }));
+}
 /**
  * A domain's status, its ownership TXT record with "Verify now", and the DNS setup checklist - shared by the domain
  * detail page and the setup wizard.
@@ -26,7 +44,6 @@ export default function DomainDnsSetup({ uid, onLoaded }) {
     const [error, setError] = useState(null);
     const [verifying, setVerifying] = useState(false);
     const [verifyError, setVerifyError] = useState(null);
-    const [copied, setCopied] = useState(false);
     function reload(id) {
         setLoading(true);
         setError(null);
@@ -62,22 +79,23 @@ export default function DomainDnsSetup({ uid, onLoaded }) {
             setVerifying(false);
         }
     }
-    async function handleCopy(value) {
-        try {
-            await navigator.clipboard.writeText(value);
-            setCopied(true);
-            setTimeout(() => setCopied(false), 2000);
-        }
-        catch {
-            // Clipboard access can be denied by the browser — the value is still selectable/copyable by hand.
-        }
-    }
     if (loading) {
         return _jsx("p", { className: "text-sm text-text-muted", children: "Loading\u2026" });
     }
     if (error || !domain) {
         return _jsx(Alert, { children: error ?? "Domain not found." });
     }
-    const ownershipValue = dnsSetup.find((c) => c.type === "ownership")?.recommendedValue ?? `rapidmx-domain-verification=${domain.verificationToken}`;
-    return (_jsxs("div", { className: "flex flex-col gap-5", children: [_jsxs("div", { className: "bg-surface border border-border rounded-md p-6", children: [_jsxs("dl", { className: "grid grid-cols-1 sm:grid-cols-2 gap-x-6 gap-y-3 text-sm", children: [_jsx("dt", { className: "text-text-muted", children: "Enabled" }), _jsx("dd", { children: domain.enabled ? "Yes" : "No" }), _jsx("dt", { className: "text-text-muted", children: "Verification" }), _jsx("dd", { children: domain.verified ? (_jsx("span", { className: "text-xs font-bold uppercase tracking-wide py-0.5 px-2 rounded-pill bg-success text-white", children: "Verified" })) : (_jsx("span", { className: "text-xs font-bold uppercase tracking-wide py-0.5 px-2 rounded-pill bg-surface-alt text-text-muted", children: "Unverified" })) }), _jsx("dt", { className: "text-text-muted", children: "Last checked" }), _jsx("dd", { children: domain.lastCheckedAt ? new Date(domain.lastCheckedAt).toLocaleString() : "Never" })] }), !domain.verified && (_jsxs("div", { className: "mt-5 pt-5 border-t border-border", children: [_jsxs("p", { className: "text-sm mb-2", children: ["Add the following TXT record to ", _jsx("strong", { children: domain.name }), " to prove ownership, then verify:"] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("code", { className: "flex-1 text-xs bg-surface-alt border border-border rounded-sm py-2 px-3 overflow-x-auto whitespace-nowrap", children: ownershipValue }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto shrink-0", onClick: () => handleCopy(ownershipValue), children: copied ? "Copied" : "Copy" })] }), verifyError && (_jsx("div", { className: "mt-3", children: _jsx(Alert, { children: verifyError }) })), _jsx(Button, { type: "button", className: "!w-auto mt-3", loading: verifying, disabled: verifying, onClick: handleVerify, children: verifyError ? "Try again" : "Verify now" })] }))] }), dnsSetup.length > 0 && (_jsxs("div", { className: "bg-surface border border-border rounded-md p-6", children: [_jsx("h2", { className: "text-sm font-bold uppercase tracking-wide mb-3", children: "DNS setup checklist" }), _jsx("div", { className: "overflow-x-auto", children: _jsxs("table", { className: "w-full text-sm border-collapse", children: [_jsx("thead", { children: _jsx("tr", { children: ["Record", "Status", "Recommended value"].map((h) => (_jsx("th", { className: "text-left text-xs uppercase tracking-wide text-text-muted py-2 px-2.5 border-b border-border", children: h }, h))) }) }), _jsx("tbody", { children: dnsSetup.map((check) => (_jsxs("tr", { children: [_jsx("td", { className: "py-2.5 px-2.5 border-b border-border", children: RECORD_TYPE_LABELS[check.type] }), _jsx("td", { className: "py-2.5 px-2.5 border-b border-border", children: !check.configured ? (_jsx("span", { className: "text-xs text-text-muted", children: "Not configured" })) : check.matches ? (_jsx("span", { className: "text-xs font-bold uppercase tracking-wide py-0.5 px-2 rounded-pill bg-success text-white", children: "Live" })) : (_jsx("span", { className: "text-xs font-bold uppercase tracking-wide py-0.5 px-2 rounded-pill bg-surface-alt text-text-muted", children: "Not found" })) }), _jsx("td", { className: "py-2.5 px-2.5 border-b border-border text-text-muted", children: _jsx("code", { className: "text-xs", children: check.recommendedValue ?? "—" }) })] }, check.type))) })] }) })] }))] }));
+    const ownership = dnsSetup.find((c) => c.type === "ownership");
+    const ownershipValue = ownership?.recommendedValue ?? `rapidmx-domain-verification=${domain.verificationToken}`;
+    const ownershipName = ownership?.recordName || domain.name;
+    return (_jsxs("div", { className: "flex flex-col gap-5", children: [_jsxs("div", { className: "bg-surface border border-border rounded-md p-6", children: [_jsxs("dl", { className: "grid grid-cols-1 sm:grid-cols-2 gap-x-6 gap-y-3 text-sm", children: [_jsx("dt", { className: "text-text-muted", children: "Enabled" }), _jsx("dd", { children: domain.enabled ? "Yes" : "No" }), _jsx("dt", { className: "text-text-muted", children: "Verification" }), _jsx("dd", { children: domain.verified ? (_jsx("span", { className: "text-xs font-bold uppercase tracking-wide py-0.5 px-2 rounded-pill bg-success text-white", children: "Verified" })) : (_jsx("span", { className: "text-xs font-bold uppercase tracking-wide py-0.5 px-2 rounded-pill bg-surface-alt text-text-muted", children: "Unverified" })) }), _jsx("dt", { className: "text-text-muted", children: "Last checked" }), _jsx("dd", { children: domain.lastCheckedAt ? new Date(domain.lastCheckedAt).toLocaleString() : "Never" })] }), !domain.verified && (_jsxs("div", { className: "mt-5 pt-5 border-t border-border", children: [_jsxs("p", { className: "text-sm mb-2", children: ["Add the following TXT record to ", _jsx("strong", { children: domain.name }), " to prove ownership, then verify:"] }), _jsxs("dl", { className: "grid grid-cols-[auto_1fr] items-start gap-x-4 gap-y-2 text-sm", children: [_jsx("dt", { className: "text-text-muted py-2", children: "Type" }), _jsx("dd", { className: "py-2", children: "TXT" }), _jsx("dt", { className: "text-text-muted py-2", children: "Name / host" }), _jsx("dd", { className: "bg-surface-alt border border-border rounded-sm py-1.5 px-3", children: _jsx(CopyableValue, { value: ownershipName, copyLabel: "Copy name for the ownership TXT record" }) }), _jsx("dt", { className: "text-text-muted py-2", children: "Value" }), _jsx("dd", { className: "bg-surface-alt border border-border rounded-sm py-1.5 px-3", children: _jsx(CopyableValue, { value: ownershipValue, copyLabel: "Copy value for the ownership TXT record" }) })] }), verifyError && (_jsx("div", { className: "mt-3", children: _jsx(Alert, { children: verifyError }) })), _jsx(Button, { type: "button", className: "!w-auto mt-3", loading: verifying, disabled: verifying, onClick: handleVerify, children: verifyError ? "Try again" : "Verify now" })] }))] }), dnsSetup.length > 0 && (_jsxs("div", { className: "bg-surface border border-border rounded-md p-6", children: [_jsx("h2", { className: "text-sm font-bold uppercase tracking-wide mb-3", children: "DNS setup checklist" }), _jsx("div", { className: "overflow-x-auto", children: _jsxs("table", { className: "w-full text-sm border-collapse", children: [_jsx("thead", { children: _jsx("tr", { children: ["Record", "Status", "Name / host", "Recommended value"].map((h) => (_jsx("th", { className: "text-left text-xs uppercase tracking-wide text-text-muted py-2 px-2.5 border-b border-border", children: h }, h))) }) }), _jsx("tbody", { children: dnsSetup.map((check) => (_jsxs("tr", { children: [_jsxs("td", { className: "py-2.5 px-2.5 border-b border-border", children: [RECORD_TYPE_LABELS[check.type], _jsxs("div", { className: "text-xs text-text-muted", children: ["Type: ", check.recordKind] })] }), _jsx("td", { className: "py-2.5 px-2.5 border-b border-border", children: !check.configured ? (_jsx("span", { className: "text-xs text-text-muted", children: "Not configured" })) : check.matches ? (_jsx("span", { className: "text-xs font-bold uppercase tracking-wide py-0.5 px-2 rounded-pill bg-success text-white", children: "Live" })) : (_jsx("span", { className: "text-xs font-bold uppercase tracking-wide py-0.5 px-2 rounded-pill bg-surface-alt text-text-muted", children: "Not found" })) }), _jsx("td", { className: "py-2.5 px-2.5 border-b border-border text-text-muted min-w-[10rem]", children: check.recordName ? (_jsx(CopyableValue, { value: check.recordName, copyLabel: `Copy name for the ${RECORD_TYPE_NAMES[check.type]} record` })) : (_jsx("code", { className: "text-xs", children: "\u2014" })) }), _jsx("td", { className: "py-2.5 px-2.5 border-b border-border text-text-muted", children: check.recommendedValue ? (_jsx(DnsRecordValue, { check: check, value: check.recommendedValue })) : (_jsx("code", { className: "text-xs", children: "\u2014" })) })] }, check.type))) })] }) }), _jsxs("p", { className: "text-xs text-text-muted mt-3", children: ["Some DNS providers want the name relative to the domain (for example ", _jsx("code", { children: "@" }), " for the domain itself) rather than the full name."] })] }))] }));
+}
+/** The value cell of a checklist row: an MX value as its two form fields (priority and mail server), anything else whole. */
+function DnsRecordValue({ check, value }) {
+    const recordName = RECORD_TYPE_NAMES[check.type];
+    const mx = check.type === "mx" ? splitMxValue(value) : null;
+    if (!mx) {
+        return _jsx(CopyableValue, { value: value, copyLabel: `Copy value for the ${recordName} record` });
+    }
+    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsxs("div", { className: "flex items-start gap-2", children: [_jsx("span", { className: "text-xs w-20 shrink-0 pt-1", children: "Priority" }), _jsx(CopyableValue, { value: mx.priority, copyLabel: `Copy priority for the ${recordName} record` })] }), _jsxs("div", { className: "flex items-start gap-2", children: [_jsx("span", { className: "text-xs w-20 shrink-0 pt-1", children: "Mail server" }), _jsx(CopyableValue, { value: mx.server, copyLabel: `Copy mail server for the ${recordName} record` })] })] }));
 }

package/dist/apps/shared/components/calendar/layout/CalendarShell.d.ts

@@ -37,4 +37,4 @@ export declare function useCalendarShell(): CalendarShellContextValue;
  * state — it lives in `apps/www/calendar/index.tsx`'s own local state, since navigating between
  * views/dates must be instant (no full page reload) and this framework has no client-side router.
  */
-export default function CalendarShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }: PropsWithChildren<CalendarShellProps>): React.JSX.Element;
+export default function CalendarShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, children, }: PropsWithChildren<CalendarShellProps>): React.JSX.Element;

package/dist/apps/shared/components/calendar/layout/CalendarShell.js

@@ -10,6 +10,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 } from "../../../navigation/AppRouter.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 const CalendarShellContext = createContext({
     calendarFolders: [],
@@ -29,16 +30,19 @@ export function useCalendarShell() {
  * state — it lives in `apps/www/calendar/index.tsx`'s own local state, since navigating between
  * views/dates must be instant (no full page reload) and this framework has no client-side router.
  */
-export default function CalendarShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, pluginNav, children, }) {
+export default function CalendarShell({ userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, children, }) {
     const [status, setStatus] = useState("checking");
     const [error, setError] = useState(null);
     const [mailboxes, setMailboxes] = useState([]);
     const [mailboxCalendars, setMailboxCalendars] = useState([]);
     const [requestedMailboxUid, setRequestedMailboxUid] = useState(null);
     const [folderRefreshToken, setFolderRefreshToken] = useState(0);
+    // 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();
     useEffect(() => {
-        setRequestedMailboxUid(new URLSearchParams(window.location.search).get("mailboxUid"));
-    }, []);
+        setRequestedMailboxUid(new URLSearchParams(search).get("mailboxUid"));
+    }, [search]);
     useEffect(() => {
         if (!userUid) {
             return;
@@ -100,5 +104,5 @@ export default function CalendarShell({ userUid, authServerUrl, impersonating, i
     else if (userUid && status === "ready") {
         inner = (_jsx("div", { className: "flex-1 min-w-0 flex flex-col", children: _jsx(CalendarShellContext.Provider, { value: contextValue, children: children }) }));
     }
-    return (_jsx(AppShell, { active: "calendar", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, pluginNav: pluginNav, children: inner }));
+    return (_jsx(AppShell, { active: "calendar", userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, trustedRoles: trustedRoles, pluginNav: pluginNav, children: inner }));
 }

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

@@ -14,6 +14,8 @@ 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
@@ -22,4 +24,4 @@ export interface ContactsToolbarProps {
  * 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

@@ -5,8 +5,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 ///////////////////////////////////////////////////////////////////////////////
 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 })] }));
+import { SHORTCUTS } from "../../keyboard/keymap.js";
+import { useShortcutProps } from "../../keyboard/useShortcutProps.js";
+function ToolbarButton({ label, icon: Icon, disabled, onClick, hint, }) {
+    return (_jsxs("button", { type: "button", onClick: onClick, disabled: disabled, ...hint, 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" });
@@ -18,7 +20,8 @@ function Divider() {
  * 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 +31,5 @@ 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 })] }));
+    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, hint: shortcuts ? newContactHint : undefined }), _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 })] }));
 }

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,9 @@ 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 })] })] }));
     }
-    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/layout/AppShell.d.ts

@@ -27,8 +27,13 @@ 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[];
 }
 export interface AppDef {
     id: AppShellApp;
@@ -39,11 +44,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, 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
@@ -22,6 +22,16 @@ import { authApiFetch } 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 NewMailToasts from "../mail/NewMailToasts.js";
 /** How long sign-out waits for auth-server's logout before navigating anyway. */
 export const LOGOUT_TIMEOUT_MS = 3000;
 /**
@@ -46,10 +56,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,15 +70,26 @@ 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, 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);
     const signingOutRef = useRef(false);
     const { branding, iconSrc } = useBranding();
+    // 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 });
     useRedirectIfUnauthenticated(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.
@@ -151,16 +172,54 @@ 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 })] }) }) }));
+    return (_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) }), _jsx(UnlockPromptProvider, { children: _jsx(ComposeProvider, { userUid: userUid, trusted: !!trusted && !impersonating, children: _jsxs("div", { className: "min-h-screen flex flex-col bg-surface-alt", children: [!hideChrome && _jsx(BrandingHeader, { branding: branding }), 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 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)))] })), !hideChrome && _jsx(BottomTabBar, { apps: apps, active: active }), _jsxs("div", { className: "flex-1 flex flex-col min-w-0", children: [!hideChrome && (_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, 
+                                                            // 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) })] })), _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(BrandingFooter, { branding: branding })] }) }) }), inFrame && (_jsx(NewMailToasts, { toasts: mail.notifications.toasts, onDismiss: mail.notifications.dismiss, offerDesktop: mail.notifications.offerDesktop, onEnableDesktop: () => void mail.notifications.enableDesktop(), onDeclineDesktop: mail.notifications.declineDesktop }))] }) }));
+}
+/**
+ * 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 });
 }

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

@@ -7,8 +7,9 @@ import { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
  */
 export declare function sanitizeBrandingHtml(html: string): string;
 /**
- * Renders the admin-configured `Branding.headerHtml`/`footerHtml` (see `useBranding()`), sanitized - shared by
- * the webmail and admin chromes. The escrow console deliberately renders no branding HTML at all.
+ * Renders the admin-configured `Branding.headerHtml`/`footerHtml` (see `useBranding()`), sanitized. The webmail
+ * chrome (`AppShell`) shows both; the admin console shows only the footer - its header is the console's own - and the
+ * escrow console deliberately renders no branding HTML at all.
  */
 export declare function BrandingHeader({ branding }: {
     branding: Branding | null;

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

@@ -42,8 +42,9 @@ function BrandingHtml({ html }) {
     return _jsx("div", { dangerouslySetInnerHTML: { __html: clean } });
 }
 /**
- * Renders the admin-configured `Branding.headerHtml`/`footerHtml` (see `useBranding()`), sanitized - shared by
- * the webmail and admin chromes. The escrow console deliberately renders no branding HTML at all.
+ * Renders the admin-configured `Branding.headerHtml`/`footerHtml` (see `useBranding()`), sanitized. The webmail
+ * chrome (`AppShell`) shows both; the admin console shows only the footer - its header is the console's own - and the
+ * escrow console deliberately renders no branding HTML at all.
  */
 export function BrandingHeader({ branding }) {
     return _jsx(BrandingHtml, { html: branding?.headerHtml });