@rapidmx/web-client 0.9.0 → 0.11.0

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

@@ -1,19 +1,78 @@
-import React from "react";
-import { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+import React, { ReactNode } from "react";
+import type { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+/** The attribute that marks the elements React fills in (`{USER_MENU}`, `{APP_TITLE}`). Stripped from the author's own HTML, so only
+ * this module's placeholders can carry it. */
+export declare const SLOT_ATTRIBUTE = "data-rr-slot";
+/** The variables a branding header or footer may contain, written in the HTML's text. */
+export declare const USER_MENU_VARIABLE = "{USER_MENU}";
+export declare const APP_TITLE_VARIABLE = "{APP_TITLE}";
 /**
  * Sanitizes admin-configured branding HTML before it's rendered. The server sanitizes on save too; this also
  * covers anything stored before that. Returns `""` where there's no DOM to sanitize with (server-side
  * rendering), so unsanitized HTML is never emitted.
  */
 export declare function sanitizeBrandingHtml(html: string): string;
+/** Branding HTML ready to render: sanitized, with its variables replaced by placeholder elements for React to fill. */
+export interface ParsedBrandingHtml {
+    html: string;
+    /** It contains a `{USER_MENU}` where the account menu can be rendered. */
+    hasUserMenu: boolean;
+}
 /**
- * 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.
+ * Sanitizes `html` (the same rules as `sanitizeBrandingHtml()`) and swaps the variables in its **text** for placeholder elements:
+ * `{USER_MENU}` becomes the slot the account menu is rendered into, `{APP_TITLE}` a slot holding the current app's name.
+ *
+ * - Only text is searched, after sanitizing - a variable in an attribute (`title="{USER_MENU}"`), a comment, or a `<script>` (which
+ * is gone) is never touched, and the author cannot write a placeholder themselves (`data-rr-slot` is stripped).
+ * - `{USER_MENU}` is replaced **once**, at its first place in the document; a second (or third) one is removed, so there is never
+ * more than one account menu (two would give two sets of duplicate ids and focus targets). One inside a link, or in text that
+ * can't hold an element (`<title>`, `<textarea>`), is removed too: a menu inside an `<a>` would navigate when clicked.
+ * - `{APP_TITLE}` is replaced everywhere it appears. Inside `<title>`-like raw text it stays as written.
+ * - Nothing is matched loosely: the names are upper-case, in braces, with no spaces.
+ *
+ * `null` when there is nothing to show (no DOM to sanitize with - server-side rendering - or the HTML is empty once sanitized).
  */
-export declare function BrandingHeader({ branding }: {
-    branding: Branding | null;
-}): React.JSX.Element;
-export declare function BrandingFooter({ branding }: {
+export declare function parseBrandingHtml(html: string): ParsedBrandingHtml | null;
+/**
+ * `parseBrandingHtml()` of `html`, done once the component is on the page (never while rendering: the server has no DOM to sanitize
+ * with, and rendering different HTML there than the hydrating client would leave the page without it). `null` when there is no HTML,
+ * or nothing is left of it; `undefined` while it has not been parsed yet - the frame reserves the header's place meanwhile.
+ */
+export declare function useBrandingHtml(html: string | undefined): ParsedBrandingHtml | null | undefined;
+export interface FrameBrandingHeaderProps {
+    /** `useBrandingHtml(branding.headerHtml)`. `null` renders nothing. */
+    parsed: ParsedBrandingHtml | null | undefined;
+    /** The account menu, rendered into the header's `{USER_MENU}` (when it has one). */
+    userMenu?: ReactNode;
+    /** Rendered at the right end of the header when it has no `{USER_MENU}` and the footer doesn't host the menu either - the account menu is never lost. */
+    fallbackMenu?: ReactNode;
+    appTitle?: string;
+}
+/**
+ * The frame's version of the admin-configured `Branding.headerHtml` (see `useBranding()`), sanitized, in a `<header>` that stays at the top of the window as the
+ * page scrolls. When it is there the app has no title bar of its own (`AppChrome`): the header is the top of the app, and the account
+ * menu lives in it - where the HTML writes `{USER_MENU}`, else in a small cell at its right end. The webmail chrome (`AppShell`) shows
+ * it; the admin console has no custom header (its header is the console's own) and the escrow console renders no branding HTML at all.
+ */
+export declare function FrameBrandingHeader({ parsed, userMenu, fallbackMenu, appTitle }: FrameBrandingHeaderProps): React.JSX.Element | null;
+export interface FrameBrandingFooterProps {
+    /** `useBrandingHtml(branding.footerHtml)`. */
+    parsed: ParsedBrandingHtml | null | undefined;
+    /** Rendered into the footer's `{USER_MENU}` - passed only when the header has none. */
+    userMenu?: ReactNode;
+    appTitle?: string;
+}
+/** The frame's version of the admin-configured `Branding.footerHtml`, sanitized. Its variables work as in the header; a `{USER_MENU}` here only takes the menu when the header has none. */
+export declare function FrameBrandingFooter({ parsed, userMenu, appTitle }: FrameBrandingFooterProps): React.JSX.Element;
+export interface BrandingChromeProps {
     branding: Branding | null;
-}): React.JSX.Element;
+    /** What `{APP_TITLE}` is replaced with - the page's own name. Nothing when absent. */
+    appTitle?: string;
+}
+/**
+ * The admin-configured `Branding.headerHtml`, sanitized, for pages that don't use a shell, such as public pages (the booking pages). There is no
+ * account menu there, so a `{USER_MENU}` in the HTML renders nothing. Renders nothing without branding or HTML.
+ */
+export declare function BrandingHeader({ branding, appTitle }: BrandingChromeProps): React.JSX.Element;
+/** The admin-configured `Branding.footerHtml`, sanitized, for pages that don't use a shell - see `BrandingHeader`. */
+export declare function BrandingFooter({ branding, appTitle }: BrandingChromeProps): React.JSX.Element;

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

@@ -1,5 +1,12 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
 import DOMPurify from "dompurify";
+import { useHeaderHeightRef } from "../../notifications/headerOffset.js";
 /** Elements that could run script, restyle the whole page, collect input, or embed another page - stripped on
  * top of DOMPurify's defaults (which already drop `<script>`, `on*` handlers, and `javascript:` URLs). */
 const FORBIDDEN_TAGS = [
@@ -23,6 +30,15 @@ const FORBIDDEN_TAGS = [
     "math",
 ];
 const FORBIDDEN_ATTRS = ["action", "formaction", "srcdoc"];
+/** The attribute that marks the elements React fills in (`{USER_MENU}`, `{APP_TITLE}`). Stripped from the author's own HTML, so only
+ * this module's placeholders can carry it. */
+export const SLOT_ATTRIBUTE = "data-rr-slot";
+/** The variables a branding header or footer may contain, written in the HTML's text. */
+export const USER_MENU_VARIABLE = "{USER_MENU}";
+export const APP_TITLE_VARIABLE = "{APP_TITLE}";
+const VARIABLE = /\{(USER_MENU|APP_TITLE)\}/g;
+/** Elements whose text is not markup a placeholder element could live in (raw text and RCDATA), and the ones a menu must not sit inside. */
+const RAW_TEXT_PARENTS = new Set(["TITLE", "TEXTAREA", "OPTION", "STYLE", "SCRIPT", "NOSCRIPT", "XMP", "IFRAME", "NOEMBED", "NOFRAMES", "PLAINTEXT"]);
 /**
  * Sanitizes admin-configured branding HTML before it's rendered. The server sanitizes on save too; this also
  * covers anything stored before that. Returns `""` where there's no DOM to sanitize with (server-side
@@ -34,21 +50,133 @@ export function sanitizeBrandingHtml(html) {
     }
     return DOMPurify.sanitize(html, { FORBID_TAGS: FORBIDDEN_TAGS, FORBID_ATTR: FORBIDDEN_ATTRS });
 }
-function BrandingHtml({ html }) {
-    const clean = html ? sanitizeBrandingHtml(html) : "";
-    if (!clean) {
+function slotElement(name) {
+    const span = document.createElement("span");
+    span.setAttribute(SLOT_ATTRIBUTE, name);
+    return span;
+}
+/**
+ * Sanitizes `html` (the same rules as `sanitizeBrandingHtml()`) and swaps the variables in its **text** for placeholder elements:
+ * `{USER_MENU}` becomes the slot the account menu is rendered into, `{APP_TITLE}` a slot holding the current app's name.
+ *
+ * - Only text is searched, after sanitizing - a variable in an attribute (`title="{USER_MENU}"`), a comment, or a `<script>` (which
+ * is gone) is never touched, and the author cannot write a placeholder themselves (`data-rr-slot` is stripped).
+ * - `{USER_MENU}` is replaced **once**, at its first place in the document; a second (or third) one is removed, so there is never
+ * more than one account menu (two would give two sets of duplicate ids and focus targets). One inside a link, or in text that
+ * can't hold an element (`<title>`, `<textarea>`), is removed too: a menu inside an `<a>` would navigate when clicked.
+ * - `{APP_TITLE}` is replaced everywhere it appears. Inside `<title>`-like raw text it stays as written.
+ * - Nothing is matched loosely: the names are upper-case, in braces, with no spaces.
+ *
+ * `null` when there is nothing to show (no DOM to sanitize with - server-side rendering - or the HTML is empty once sanitized).
+ */
+export function parseBrandingHtml(html) {
+    if (!DOMPurify.isSupported) {
+        return null;
+    }
+    const fragment = DOMPurify.sanitize(html, {
+        FORBID_TAGS: FORBIDDEN_TAGS,
+        FORBID_ATTR: [...FORBIDDEN_ATTRS, SLOT_ATTRIBUTE],
+        RETURN_DOM_FRAGMENT: true,
+    });
+    const walker = document.createTreeWalker(fragment, NodeFilter.SHOW_TEXT);
+    const texts = [];
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+        texts.push(node);
+    }
+    let hasUserMenu = false;
+    for (const text of texts) {
+        const parent = text.parentElement;
+        if (parent && RAW_TEXT_PARENTS.has(parent.tagName)) {
+            continue;
+        }
+        const inLink = !!parent?.closest("a");
+        // `split` with a capturing group alternates text and variable names: [text, name, text, name, ..., text].
+        const pieces = text.data.split(VARIABLE);
+        if (pieces.length === 1) {
+            continue;
+        }
+        const replacement = document.createDocumentFragment();
+        pieces.forEach((piece, index) => {
+            if (index % 2 === 0) {
+                if (piece) {
+                    replacement.appendChild(document.createTextNode(piece));
+                }
+            }
+            else if (piece === "APP_TITLE") {
+                replacement.appendChild(slotElement("app-title"));
+            }
+            else if (!hasUserMenu && !inLink) {
+                hasUserMenu = true;
+                replacement.appendChild(slotElement("user-menu"));
+            }
+        });
+        text.replaceWith(replacement);
+    }
+    const holder = document.createElement("div");
+    holder.appendChild(fragment);
+    const result = holder.innerHTML;
+    return result.trim() ? { html: result, hasUserMenu } : null;
+}
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+/**
+ * `parseBrandingHtml()` of `html`, done once the component is on the page (never while rendering: the server has no DOM to sanitize
+ * with, and rendering different HTML there than the hydrating client would leave the page without it). `null` when there is no HTML,
+ * or nothing is left of it; `undefined` while it has not been parsed yet - the frame reserves the header's place meanwhile.
+ */
+export function useBrandingHtml(html) {
+    const source = html?.trim() ? html : undefined;
+    const [parsed, setParsed] = useState(undefined);
+    useIsomorphicLayoutEffect(() => {
+        setParsed(source === undefined ? undefined : { source, value: parseBrandingHtml(source) });
+    }, [source]);
+    if (source === undefined) {
+        return null;
+    }
+    return parsed?.source === source ? parsed.value : undefined;
+}
+function BrandingHtml({ parsed, userMenu, hostMenu, appTitle, className }) {
+    const ref = useRef(null);
+    const [targets, setTargets] = useState({ menu: null, titles: [] });
+    const html = parsed?.html ?? "";
+    // The placeholders exist once React has set the HTML: find them here, before the browser paints, and portal into them.
+    useIsomorphicLayoutEffect(() => {
+        const root = ref.current;
+        setTargets({
+            menu: root?.querySelector(`[${SLOT_ATTRIBUTE}="user-menu"]`) ?? null,
+            titles: root ? Array.from(root.querySelectorAll(`[${SLOT_ATTRIBUTE}="app-title"]`)) : [],
+        });
+    }, [html]);
+    if (parsed === null) {
+        return null;
+    }
+    return (_jsxs(_Fragment, { children: [_jsx("div", { ref: ref, className: className, dangerouslySetInnerHTML: { __html: html } }), hostMenu && targets.menu && createPortal(userMenu, targets.menu), targets.titles.map((element, index) => createPortal(appTitle, element, `app-title-${index}`))] }));
+}
+/**
+ * The frame's version of the admin-configured `Branding.headerHtml` (see `useBranding()`), sanitized, in a `<header>` that stays at the top of the window as the
+ * page scrolls. When it is there the app has no title bar of its own (`AppChrome`): the header is the top of the app, and the account
+ * menu lives in it - where the HTML writes `{USER_MENU}`, else in a small cell at its right end. The webmail chrome (`AppShell`) shows
+ * it; the admin console has no custom header (its header is the console's own) and the escrow console renders no branding HTML at all.
+ */
+export function FrameBrandingHeader({ parsed, userMenu, fallbackMenu, appTitle }) {
+    // Publishes the header's height (`--rr-header-h`) for the pop-up stack, which sticks just below it.
+    const headerRef = useHeaderHeightRef();
+    if (parsed === null) {
         return null;
     }
-    return _jsx("div", { dangerouslySetInnerHTML: { __html: clean } });
+    return (_jsxs("header", { ref: headerRef, className: "sticky top-0 z-30 shrink-0 flex items-stretch bg-surface-alt", "data-branding-header": "", children: [_jsx(BrandingHtml, { parsed: parsed, userMenu: userMenu, hostMenu: parsed?.hasUserMenu, appTitle: appTitle, className: "flex-1 min-w-0" }), parsed && !parsed.hasUserMenu && fallbackMenu ? (_jsx("div", { className: "shrink-0 flex items-center px-3 bg-surface border-l border-border", "data-branding-menu-cell": "", children: fallbackMenu })) : null] }));
+}
+/** The frame's version of the admin-configured `Branding.footerHtml`, sanitized. Its variables work as in the header; a `{USER_MENU}` here only takes the menu when the header has none. */
+export function FrameBrandingFooter({ parsed, userMenu, appTitle }) {
+    return _jsx(BrandingHtml, { parsed: parsed, userMenu: userMenu, hostMenu: userMenu !== undefined, appTitle: appTitle });
 }
 /**
- * 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.
+ * The admin-configured `Branding.headerHtml`, sanitized, for pages that don't use a shell, such as public pages (the booking pages). There is no
+ * account menu there, so a `{USER_MENU}` in the HTML renders nothing. Renders nothing without branding or HTML.
  */
-export function BrandingHeader({ branding }) {
-    return _jsx(BrandingHtml, { html: branding?.headerHtml });
+export function BrandingHeader({ branding, appTitle }) {
+    return _jsx(BrandingHtml, { parsed: useBrandingHtml(branding?.headerHtml), appTitle: appTitle });
 }
-export function BrandingFooter({ branding }) {
-    return _jsx(BrandingHtml, { html: branding?.footerHtml });
+/** The admin-configured `Branding.footerHtml`, sanitized, for pages that don't use a shell - see `BrandingHeader`. */
+export function BrandingFooter({ branding, appTitle }) {
+    return _jsx(BrandingHtml, { parsed: useBrandingHtml(branding?.footerHtml), appTitle: appTitle });
 }

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

@@ -10,6 +10,7 @@ import Button from "@rapidmx/react-shared/components/buttons/Button.js";
 import FormField from "@rapidmx/react-shared/components/forms/FormField.js";
 import { enrollKey, getKeyVault, VaultAlreadyInitializedError } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
 import { UnopenableKeysNotice, unlockErrorMessage } from "./UnlockPromptProvider.js";
+import { FrameTakeover } from "../../navigation/frameContext.js";
 import { RecoveryFollowUpModal, UnlockModeToggle, startRecoveryUnlock } from "./RecoveryCodeUnlock.js";
 import { ENCRYPTION_PRIVATE_KEY_AAD_PURPOSE, getUnlockedKeys, unlockWithPassword, } from "@rapidmx/react-shared/crypto/keySession.js";
 import { buildAad, generateMasterKey, sealWithKey } from "@rapidmx/react-shared/crypto/masterKey.js";
@@ -170,22 +171,22 @@ export default function KeyEnrollmentGate({ mailboxUid, mailboxAddress, mailboxK
     }
     if ((status === "unlock" || status === "unlocking") && blocking) {
         const unlocking = status === "unlocking";
-        return (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Unlock your mailbox" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: unlockMode === "password"
-                            ? "Enter your encryption password to unlock signing and reading protected mail this session."
-                            : "Enter one of your recovery codes to unlock signing and reading protected mail this session. Each code works once." }), error && _jsx(Alert, { children: error }), _jsxs("form", { onSubmit: handleUnlock, children: [unlockMode === "password" ? (_jsx(FormField, { label: "Encryption password", htmlFor: "key-unlock-password", children: _jsx("input", { id: "key-unlock-password", type: "password", className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: password, onChange: (e) => setPassword(e.target.value), disabled: unlocking, autoComplete: "current-password" }) })) : (_jsx(FormField, { label: "Recovery code", htmlFor: "key-unlock-recovery-code", children: _jsx("input", { id: "key-unlock-recovery-code", type: "text", className: "w-full text-sm font-mono border border-border rounded-sm py-1.5 px-2 bg-surface", value: recoveryCode, onChange: (e) => setRecoveryCode(e.target.value), disabled: unlocking, autoComplete: "off", autoCapitalize: "characters", spellCheck: false }) })), _jsx(Button, { type: "submit", loading: unlocking, disabled: unlocking, children: "Unlock" })] }), _jsx("div", { className: "mt-3", children: _jsx(UnlockModeToggle, { mode: unlockMode, disabled: unlocking, onChange: (next) => {
-                                setUnlockMode(next);
-                                setError(null);
-                            } }) })] }) }));
+        return (_jsx(FrameTakeover, { children: _jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Unlock your mailbox" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: unlockMode === "password"
+                                ? "Enter your encryption password to unlock signing and reading protected mail this session."
+                                : "Enter one of your recovery codes to unlock signing and reading protected mail this session. Each code works once." }), error && _jsx(Alert, { children: error }), _jsxs("form", { onSubmit: handleUnlock, children: [unlockMode === "password" ? (_jsx(FormField, { label: "Encryption password", htmlFor: "key-unlock-password", children: _jsx("input", { id: "key-unlock-password", type: "password", className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: password, onChange: (e) => setPassword(e.target.value), disabled: unlocking, autoComplete: "current-password" }) })) : (_jsx(FormField, { label: "Recovery code", htmlFor: "key-unlock-recovery-code", children: _jsx("input", { id: "key-unlock-recovery-code", type: "text", className: "w-full text-sm font-mono border border-border rounded-sm py-1.5 px-2 bg-surface", value: recoveryCode, onChange: (e) => setRecoveryCode(e.target.value), disabled: unlocking, autoComplete: "off", autoCapitalize: "characters", spellCheck: false }) })), _jsx(Button, { type: "submit", loading: unlocking, disabled: unlocking, children: "Unlock" })] }), _jsx("div", { className: "mt-3", children: _jsx(UnlockModeToggle, { mode: unlockMode, disabled: unlocking, onChange: (next) => {
+                                    setUnlockMode(next);
+                                    setError(null);
+                                } }) })] }) }) }));
     }
     if (status === "setup_password" || status === "enrolling") {
         const enrolling = status === "enrolling";
-        return (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Protect your mailbox" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "Choose a password to protect your encryption keys. This is separate from your sign-in password and is never sent to the server." }), error && _jsx(Alert, { children: error }), _jsxs("form", { onSubmit: handleSetPassword, children: [_jsx(FormField, { label: "Encryption password", htmlFor: "key-enrollment-password", children: _jsx("input", { id: "key-enrollment-password", type: "password", className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: password, onChange: (e) => setPassword(e.target.value), disabled: enrolling, autoComplete: "new-password" }) }), _jsx(FormField, { label: "Confirm password", htmlFor: "key-enrollment-password-confirm", children: _jsx("input", { id: "key-enrollment-password-confirm", type: "password", className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: confirmPassword, onChange: (e) => setConfirmPassword(e.target.value), disabled: enrolling, autoComplete: "new-password" }) }), _jsx(Button, { type: "submit", loading: enrolling, disabled: enrolling, children: "Continue" })] })] }) }));
+        return (_jsx(FrameTakeover, { children: _jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Protect your mailbox" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "Choose a password to protect your encryption keys. This is separate from your sign-in password and is never sent to the server." }), error && _jsx(Alert, { children: error }), _jsxs("form", { onSubmit: handleSetPassword, children: [_jsx(FormField, { label: "Encryption password", htmlFor: "key-enrollment-password", children: _jsx("input", { id: "key-enrollment-password", type: "password", className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: password, onChange: (e) => setPassword(e.target.value), disabled: enrolling, autoComplete: "new-password" }) }), _jsx(FormField, { label: "Confirm password", htmlFor: "key-enrollment-password-confirm", children: _jsx("input", { id: "key-enrollment-password-confirm", type: "password", className: "w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface", value: confirmPassword, onChange: (e) => setConfirmPassword(e.target.value), disabled: enrolling, autoComplete: "new-password" }) }), _jsx(Button, { type: "submit", loading: enrolling, disabled: enrolling, children: "Continue" })] })] }) }) }));
     }
     if (status === "already_set_up") {
-        return (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Encryption is already set up" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "This mailbox\u2019s encryption was set up in another tab or on another device while this page was open, so nothing was changed here. Reload the page and unlock with the password chosen there." }), _jsx(Button, { type: "button", onClick: () => window.location.reload(), children: "Reload" })] }) }));
+        return (_jsx(FrameTakeover, { children: _jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Encryption is already set up" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "This mailbox\u2019s encryption was set up in another tab or on another device while this page was open, so nothing was changed here. Reload the page and unlock with the password chosen there." }), _jsx(Button, { type: "button", onClick: () => window.location.reload(), children: "Reload" })] }) }) }));
     }
     if (status === "show_recovery_codes") {
-        return (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Save your recovery codes" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "If you lose your password, these codes are the only way to recover your encrypted mail. Each code can be used once. Store them somewhere safe \u2014 they will not be shown again." }), _jsx("ul", { className: "grid grid-cols-2 gap-2 mb-3 font-mono text-sm", children: recoveryCodes.map((code) => (_jsx("li", { className: "bg-surface-alt rounded-sm py-1.5 px-2 text-center", children: code }, code))) }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto mb-5", onClick: handleCopyCodes, children: codesCopied ? "Copied" : "Copy codes to clipboard" }), _jsxs("label", { className: "flex items-center gap-2 text-sm mb-4", children: [_jsx("input", { type: "checkbox", checked: codesSaved, onChange: (e) => setCodesSaved(e.target.checked) }), "I have saved these recovery codes in a safe place."] }), _jsx(Button, { type: "button", disabled: !codesSaved, onClick: () => setStatus("ready"), children: "Continue" })] }) }));
+        return (_jsx(FrameTakeover, { children: _jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8", children: [_jsx("h1", { className: "text-lg font-bold mb-2", children: "Save your recovery codes" }), _jsx("p", { className: "text-sm text-text-muted mb-5", children: "If you lose your password, these codes are the only way to recover your encrypted mail. Each code can be used once. Store them somewhere safe \u2014 they will not be shown again." }), _jsx("ul", { className: "grid grid-cols-2 gap-2 mb-3 font-mono text-sm", children: recoveryCodes.map((code) => (_jsx("li", { className: "bg-surface-alt rounded-sm py-1.5 px-2 text-center", children: code }, code))) }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto mb-5", onClick: handleCopyCodes, children: codesCopied ? "Copied" : "Copy codes to clipboard" }), _jsxs("label", { className: "flex items-center gap-2 text-sm mb-4", children: [_jsx("input", { type: "checkbox", checked: codesSaved, onChange: (e) => setCodesSaved(e.target.checked) }), "I have saved these recovery codes in a safe place."] }), _jsx(Button, { type: "button", disabled: !codesSaved, onClick: () => setStatus("ready"), children: "Continue" })] }) }) }));
     }
     return (_jsxs(_Fragment, { children: [children, unopenableKeys && _jsx(UnopenableKeysNotice, { fingerprints: unopenableKeys, onDismiss: () => setUnopenableKeys(null) }), followUp && _jsx(RecoveryFollowUpModal, { followUp: followUp, onDone: () => setFollowUp(null) })] }));
 }

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

@@ -8,6 +8,7 @@ import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { autoProvisionMailbox } from "@rapidmx/react-shared/mail/mailApi.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import { FrameTakeover } from "../../navigation/frameContext.js";
 /** What the "Retry" screen says: the server couldn't read its provisioning policy (503) ... */
 const RETRY_POLICY_TEXT = "We couldn\u2019t check whether a mailbox can be set up for you. Please try again.";
 /** ... or couldn't reach the identity service (auth-server) it looks the caller's username up in (502). */
@@ -114,5 +115,6 @@ export default function MailboxProvisioning() {
     else {
         content = (_jsxs(_Fragment, { children: [_jsx("h1", { className: "text-lg font-bold uppercase tracking-wide", children: "No mailbox available" }), reason && _jsx("p", { className: "text-sm", children: reason }), _jsx("p", { className: "text-sm text-text-muted", children: "Ask an administrator to create one for you." })] }));
     }
-    return (_jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8 flex flex-col items-center gap-4 text-center", children: [_jsx("img", { src: "/images/wordmark.png", height: "128", alt: "" }), content] }) }));
+    // Inside the client-side router's persistent frame this hides the frame's rail and header, as replacing the whole shell used to.
+    return (_jsx(FrameTakeover, { children: _jsx("div", { className: "min-h-screen flex items-center justify-center p-8 bg-surface-alt", children: _jsxs("div", { className: "w-full max-w-md bg-surface border border-border rounded-md p-8 flex flex-col items-center gap-4 text-center", children: [_jsx("img", { src: "/images/wordmark.png", height: "128", alt: "" }), content] }) }) }));
 }

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

@@ -0,0 +1,21 @@
+import React from "react";
+/** The number of rows at the top of `size` x `size` RGBA pixel data that are empty - the icon's own margin above its first visible pixel. */
+export declare function emptyRowsAtTop(rgba: ArrayLike<number>, size: number): number;
+/** Whether this environment can decode an image and read it back - not a server, and not jsdom, where there is nothing to measure. */
+export declare function canMeasureImages(): boolean;
+/**
+ * How many pixels of empty margin an icon has above its first visible pixel when fitted (`object-fit: contain`) into a `SIZE` square.
+ * Drawn on a canvas and read back, so it works for any picture the browser can decode from the same origin (or with CORS); `0` where
+ * that isn't possible (no canvas, a picture that won't load, one from another origin that taints the canvas).
+ */
+export declare function measureTopMargin(src: string): Promise<number>;
+/**
+ * The deployment's icon at the top of an app rail (`AppShell`, `AdminShell`, `EscrowShell`): a block as wide as the rail and as tall as the
+ * title bar beside it (4rem), flush with the top and left edges of the window - no padding above it - with the bar's own bottom border
+ * continued under it, so the two read as one block. The picture is fitted inside the block, never cropped, and raised by whatever empty
+ * margin the file itself has above its artwork, so the first visible pixel is at the very top of the window (a logo exported with 6% of
+ * air around it would otherwise still leave a gap). The icon is shown once measured (a few milliseconds after it loads).
+ */
+export default function RailIcon({ src }: {
+    src: string;
+}): React.JSX.Element;

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

@@ -0,0 +1,85 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+/** The side, in CSS pixels, of the square the icon is fitted into and measured in: the rail is 4rem wide and the title bar 4rem tall, each less its 1px border. */
+const SIZE = 63;
+/** Pixels this transparent or less count as empty. */
+const EMPTY_ALPHA = 24;
+/** The number of rows at the top of `size` x `size` RGBA pixel data that are empty - the icon's own margin above its first visible pixel. */
+export function emptyRowsAtTop(rgba, size) {
+    for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; x++) {
+            if (rgba[(y * size + x) * 4 + 3] > EMPTY_ALPHA) {
+                return y;
+            }
+        }
+    }
+    return 0;
+}
+/** Whether this environment can decode an image and read it back - not a server, and not jsdom, where there is nothing to measure. */
+export function canMeasureImages() {
+    try {
+        return typeof new Image().decode === "function";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * How many pixels of empty margin an icon has above its first visible pixel when fitted (`object-fit: contain`) into a `SIZE` square.
+ * Drawn on a canvas and read back, so it works for any picture the browser can decode from the same origin (or with CORS); `0` where
+ * that isn't possible (no canvas, a picture that won't load, one from another origin that taints the canvas).
+ */
+export async function measureTopMargin(src) {
+    try {
+        const image = new Image();
+        image.src = src;
+        await image.decode();
+        const canvas = document.createElement("canvas");
+        canvas.width = SIZE;
+        canvas.height = SIZE;
+        const context = canvas.getContext("2d", { willReadFrequently: true });
+        if (!context || !image.naturalWidth || !image.naturalHeight) {
+            return 0;
+        }
+        const scale = Math.min(SIZE / image.naturalWidth, SIZE / image.naturalHeight);
+        const width = image.naturalWidth * scale;
+        const height = image.naturalHeight * scale;
+        context.drawImage(image, (SIZE - width) / 2, (SIZE - height) / 2, width, height);
+        return emptyRowsAtTop(context.getImageData(0, 0, SIZE, SIZE).data, SIZE);
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * The deployment's icon at the top of an app rail (`AppShell`, `AdminShell`, `EscrowShell`): a block as wide as the rail and as tall as the
+ * title bar beside it (4rem), flush with the top and left edges of the window - no padding above it - with the bar's own bottom border
+ * continued under it, so the two read as one block. The picture is fitted inside the block, never cropped, and raised by whatever empty
+ * margin the file itself has above its artwork, so the first visible pixel is at the very top of the window (a logo exported with 6% of
+ * air around it would otherwise still leave a gap). The icon is shown once measured (a few milliseconds after it loads).
+ */
+export default function RailIcon({ src }) {
+    const [margin, setMargin] = useState(null);
+    useEffect(() => {
+        let cancelled = false;
+        if (!canMeasureImages()) {
+            // Nothing to measure with: show the icon as it is (in the same effect pass, so nothing waits and nothing updates later).
+            setMargin(0);
+            return;
+        }
+        setMargin(null);
+        void measureTopMargin(src).then((measured) => {
+            if (!cancelled) {
+                setMargin(measured);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [src]);
+    return (_jsx("div", { className: "h-16 w-full shrink-0 overflow-hidden border-b border-border mb-2", "data-rail-icon": "", children: _jsx("img", { src: src, width: "64", height: "64", alt: "", className: "block h-full w-full object-contain", style: { transform: margin ? `translateY(-${margin}px)` : undefined, opacity: margin === null ? 0 : 1 } }) }));
+}

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

@@ -0,0 +1,55 @@
+import React, { ReactNode } from "react";
+import type { IconType } from "react-icons";
+/** One button of a `ResponsiveToolbar`. */
+export interface ToolbarAction {
+    id: string;
+    /** The visible caption while there is room, else the tooltip and the accessible name. */
+    label: string;
+    icon: IconType;
+    onClick: () => void;
+    disabled?: boolean;
+    /** A toggle: the button's pressed state. */
+    pressed?: boolean;
+    /** `title` and `aria-keyshortcuts` for a button with a shortcut - kept as given, whatever the layout. */
+    hint?: {
+        title: string;
+        "aria-keyshortcuts"?: string;
+    };
+    /** Actions with the same `group` sit together; a divider goes between groups. */
+    group: number;
+    /** Which goes into the "More" menu first when there is not room: the lowest number first. Never used for `essential`. */
+    rank: number;
+    /** Never moves into the "More" menu (the primary action). */
+    essential?: boolean;
+}
+/** Room (px) each kind of button takes, and what the bar spends on its padding, a divider and the "More" button - the layout is computed from them
+ * rather than measured, so the first paint on the client is already right and nothing jumps. */
+export declare const LABELLED_BUTTON_WIDTH = 64;
+export declare const ICON_BUTTON_WIDTH = 36;
+export interface ToolbarLayout {
+    /** Captions under the icons. */
+    labels: boolean;
+    /** The ids of the actions shown as buttons, in order. The rest are in the "More" menu. */
+    visible: string[];
+}
+/**
+ * Which buttons a bar of `width` px shows, and how: every one with its caption when that fits; else every one as an icon (the captions go first);
+ * else as many icons as fit, the least important (`rank`) going into a "More" menu one at a time - the essential ones stay whatever the width.
+ * Pure, so it is the same on the server and the client for a given width; `width === undefined` (not measured yet, no ResizeObserver) shows
+ * everything.
+ */
+export declare function layoutToolbar(actions: ToolbarAction[], width: number | undefined): ToolbarLayout;
+/** The width of `ref`'s element, kept current with a ResizeObserver; `undefined` until measured (and where there is no ResizeObserver). */
+export declare function useElementWidth(ref: React.RefObject<HTMLElement | null>): number | undefined;
+/**
+ * A toolbar that fits the column it is in - never wider, never over another pane. It measures its own width (`ResizeObserver`) and shows every
+ * action with a caption when there is room; when there is not, the captions go first (each button keeps its tooltip and accessible name), then the
+ * least important actions move into a "More" menu (`layoutToolbar()`). Arrow keys, Home and End move between the buttons; the menu is a real
+ * `role="menu"`. `children` (a hidden file input, say) are rendered inside the toolbar's element but take no room.
+ */
+export default function ResponsiveToolbar({ label, actions, leading, children }: {
+    label: string;
+    actions: ToolbarAction[];
+    leading?: ReactNode;
+    children?: ReactNode;
+}): React.JSX.Element;