@rapidmx/web-client 0.10.0 → 0.12.0

package/apps/shared/components/escrow/layout/EscrowShell.tsx

@@ -12,6 +12,8 @@ import { getBranding } from "@rapidmx/react-shared/branding/brandingApi.js";
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import BottomTabBar, { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
 import UserMenu from "../../layout/UserMenu.js";
+import RailIcon from "../../layout/RailIcon.js";
+import AppearanceProvider from "../../../appearance/AppearanceProvider.js";
 import { signOutOfConsole } from "../../admin/signOut.js";
 
 export type EscrowSection = "matters" | "auditLog";
@@ -104,13 +106,13 @@ export default function EscrowShell({ active, userUid, authServerUrl, children }
     } else {
         const activeItem = NAV_ITEMS.find((item) => item.id === active);
         content = (
-            <div className="min-h-screen flex flex-col bg-surface-alt">
+            <div className="rr-frame-bg min-h-screen flex flex-col">
                 <div className="flex-1 flex min-h-0">
                     <nav
                         aria-label="Escrow sections"
-                        className="hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center py-3 gap-1"
+                        className="hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center pb-3 gap-1"
                     >
-                        <img src={iconSrc} width="96" height="96" alt="" className="mb-3" />
+                        <RailIcon src={iconSrc} />
                         {NAV_ITEMS.map(({ id, href, label, icon: Icon }) => (
                             <a
                                 key={id}
@@ -131,11 +133,11 @@ export default function EscrowShell({ active, userUid, authServerUrl, children }
                     </nav>
                     <BottomTabBar apps={NAV_ITEMS} active={active} />
                     <div className="flex-1 flex flex-col min-w-0">
-                        <header className="h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6">
+                        <header className="rr-solid sticky top-0 z-30 h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6">
                             <span className="font-display font-bold text-lg uppercase tracking-wide">{activeItem?.label}</span>
                             <UserMenu userUid={userUid} authServerUrl={authServerUrl} onSignOut={handleSignOut} />
                         </header>
-                        <div className="flex-1 pb-14 md:pb-0">
+                        <div id="app-content" className="flex-1 pb-14 md:pb-0">
                             <main className="max-w-6xl mx-auto px-6 py-8">{children}</main>
                         </div>
                     </div>
@@ -144,5 +146,10 @@ export default function EscrowShell({ active, userUid, authServerUrl, children }
         );
     }
 
-    return <>{content}</>;
+    // The user's own colours and background (`AppearanceProvider`), from what the last webmail page cached in this browser: the console never asks the server.
+    return (
+        <AppearanceProvider userUid={userUid} lookUp={false}>
+            {content}
+        </AppearanceProvider>
+    );
 }

package/apps/shared/components/layout/AppShell.tsx

@@ -20,11 +20,15 @@ import { useIdleKeyTimeout } from "@rapidmx/react-shared/crypto/useIdleKeyTimeou
 import ComposeProvider from "../mail/compose/ComposeContext.js";
 import { flushComposeDrafts, markSigningOut } from "../mail/compose/composeFlushRegistry.js";
 import BottomTabBar, { NavItem } from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
-import { BrandingFooter, BrandingHeader } from "./BrandingChrome.js";
+import { FrameBrandingFooter, FrameBrandingHeader, useBrandingHtml } from "./BrandingChrome.js";
+import RailIcon from "./RailIcon.js";
+import AppearanceProvider from "../../appearance/AppearanceProvider.js";
+import { clearAppearanceCache } from "../../appearance/appearanceCache.js";
+import type { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
 import UserMenu from "./UserMenu.js";
 import { UnlockPromptProvider } from "./UnlockPromptProvider.js";
 import { SIGN_OUT_CHANNEL, destroyAllLocalIndexes } from "../../search/localIndexRpcClient.js";
-import { authApiFetch } from "@rapidmx/react-shared/util/api.js";
+import { authApiFetch, setApiUnauthorizedObserver } from "@rapidmx/react-shared/util/api.js";
 import { destroyUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
 import { clearPinnedSignerCache } from "../mail/pinnedSigners.js";
 import { mergePluginNavItems, PluginNav, PluginNavProps } from "../../plugins/pluginNav.js";
@@ -37,7 +41,13 @@ 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";
+import UnlockBridge from "../../mail/outbox/UnlockBridge.js";
+import NotificationCenter from "../../notifications/NotificationCenter.js";
+import { useHeaderHeightRef } from "../../notifications/headerOffset.js";
+import NotificationHistoryDialog from "../../notifications/NotificationHistoryDialog.js";
+import { notifySessionExpired, setSignInUrl } from "../../notifications/apiErrors.js";
+import { useUnseenErrorCount } from "../../notifications/useNotifications.js";
+import { useSigningEnrollmentWatcher } from "../../signing/useSigningEnrollmentWatcher.js";
 
 /** How long sign-out waits for auth-server's logout before navigating anyway. */
 export const LOGOUT_TIMEOUT_MS = 3_000;
@@ -93,6 +103,10 @@ export interface AppShellProps extends PluginNavProps {
     /** The role names the server treats as trusted (its `trusted_roles` config, injected via the route's `fetchProps`) -
      * what that lookup looks for. Absent means the server's own default, `["admin"]`. */
     trustedRoles?: string[];
+    /** The deployment's branding as the server rendered the page (its `branding` prop). Used until the frame's own fetch answers, so a custom header is there from the first paint - and the frame knows to drop its own title bar - instead of appearing (and moving everything) once the request returns. */
+    branding?: Branding;
+    /** The signed-in user's stored appearance preferences as the server rendered the page (its `appearance` prop), so the first paint already wears the theme and background - see `AppearanceProvider`. */
+    appearance?: unknown;
 }
 
 export interface AppDef {
@@ -152,6 +166,8 @@ export function AppChrome({
     impersonationBaseUrl,
     trusted,
     trustedRoles,
+    branding: initialBranding,
+    appearance,
     pluginNav,
     routeKey,
     busy,
@@ -161,8 +177,20 @@ export function AppChrome({
     const [stoppingImpersonation, setStoppingImpersonation] = useState(false);
     // The keyboard shortcuts dialog: opened by `?`/Ctrl+/ (`GlobalShortcuts`) and by the account menu's item.
     const [shortcutsOpen, setShortcutsOpen] = useState(false);
+    // The pop-up history ("Recent notifications" in the account menu). The pop-ups themselves are drawn by `NotificationCenter`, below.
+    const [historyOpen, setHistoryOpen] = useState(false);
+    // Only the count is read, so the whole frame does not render again for every pop-up that comes and goes.
+    const unseenErrors = useUnseenErrorCount();
+    // The title bar's height for the pop-up stack, which sticks just below the header (a branding header publishes its own - `FrameBrandingHeader`).
+    const headerRef = useHeaderHeightRef();
     const signingOutRef = useRef(false);
-    const { branding, iconSrc } = useBranding();
+    const { branding: fetchedBranding, iconSrc: fetchedIconSrc } = useBranding();
+    // The server's copy until the fetch answers, so the frame's shape (a custom header replaces the title bar) never changes after the first paint.
+    const branding = fetchedBranding ?? initialBranding ?? null;
+    const iconSrc = fetchedBranding ? fetchedIconSrc : initialBranding?.iconUrl || initialBranding?.logoUrl || fetchedIconSrc;
+    // The custom header and footer, sanitized and with their `{USER_MENU}` / `{APP_TITLE}` placeholders (`undefined` until parsed, `null` when there is none).
+    const header = useBrandingHtml(branding?.headerHtml);
+    const footer = useBrandingHtml(branding?.footerHtml);
     // The mailboxes, their folders and the one push connection live here, in the frame that stays mounted as the router swaps pages - so
     // new-mail pop-ups, the folder counters and the tab title's unread count work in Calendar, Contacts, Tasks and Settings too, and moving
     // between apps never opens a second socket (the server allows ten per user). `MailShell` reads them from `MailConnectionContext`. Outside
@@ -170,8 +198,20 @@ export function AppChrome({
     const inFrame = useInAppFrame();
     const navigate = useNavigate();
     const mail = useMailConnection({ userUid, enabled: inFrame, open: navigate });
+    // A signing certificate the user asked for is announced when it is issued (or fails), on whichever page they are - see the hook.
+    useSigningEnrollmentWatcher({ userUid, mailboxes: mail.mailboxes, enabled: inFrame });
 
     useRedirectIfUnauthenticated(userUid, authServerUrl);
+    // Any request this app makes that the server answers with a 401 - the session ended - raises one "Your session expired" pop-up with a
+    // Sign in action (see `notifySessionExpired()`), whichever request noticed first, a background refresh included.
+    useEffect(() => {
+        setSignInUrl(authServerUrl);
+        if (!userUid) {
+            return;
+        }
+        setApiUnauthorizedObserver(() => void notifySessionExpired());
+        return () => setApiUnauthorizedObserver(undefined);
+    }, [userUid, authServerUrl]);
     // Mounted here, not scoped to Mail/Settings (the only shells that actually read unlocked keys),
     // specifically so activity in *any* app resets the idle clock - see that hook's own doc comment.
     useIdleKeyTimeout();
@@ -213,6 +253,7 @@ export function AppChrome({
             markSigningOut();
             destroyUnlockedKeys();
             clearPinnedSignerCache();
+            clearAppearanceCache();
             // Bounded by its own timeout and never rejects - awaited so navigating doesn't kill the Worker mid-delete.
             void destroyAllLocalIndexes().then(() => {
                 window.location.href = authServerUrl ?? "/";
@@ -230,6 +271,7 @@ export function AppChrome({
         destroyUnlockedKeys();
         // Trusted signer pins read from contacts don't outlive the session either.
         clearPinnedSignerCache();
+        clearAppearanceCache();
         // Open compose windows save edits still waiting on their autosave debounce while the session is still
         // valid - logout invalidates it. Bounded the same way as logout itself, and never rejects.
         await flushComposeDrafts(LOGOUT_TIMEOUT_MS);
@@ -290,21 +332,55 @@ export function AppChrome({
     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;
+    // A custom header (`Branding.headerHtml`) replaces the app's own title bar and the icon at the top of the rail: it is the top of the app, and the
+    // account menu moves into it. While it is still being parsed it already counts, so the frame's shape doesn't change under the user.
+    const customHeader = header !== null;
+    // Where the one account menu lives: the header's `{USER_MENU}`, else the footer's, else a small cell at the header's right end - never lost.
+    const menuInHeader = !!header?.hasUserMenu;
+    const menuInFooter = customHeader && !!header && !menuInHeader && !!footer?.hasUserMenu;
+    const renderUserMenu = (placement: "down" | "up") => (
+        <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
+            showNotificationSettings
+            onShowShortcuts={() => setShortcutsOpen(true)}
+            onShowNotifications={() => setHistoryOpen(true)}
+            unseenErrors={unseenErrors}
+            placement={placement}
+        />
+    );
 
     return (
         // Mounted here, not scoped to Mail/Settings, for the same reason as useIdleKeyTimeout() above -
         // ComposeWindow's sign/encrypt toggles and MessageDetailPane's encrypted-message view (both Mail)
         // are today's only useUnlockPrompt() callers, but this needs to be available to any app shell.
+        // Asks the server for the user's appearance only in the persistent frame (every core page); a page that renders its own chrome (a plugin's) uses the
+        // `appearance` it was given and what this browser cached.
+        <AppearanceProvider userUid={userUid} initial={appearance} lookUp={inFrame}>
         <ShortcutProvider>
         <MailConnectionContext.Provider value={inFrame ? mail : null}>
         <GlobalShortcuts authServerUrl={authServerUrl} onToggleHelp={() => setShortcutsOpen((open) => !open)} />
         <ShortcutsDialog open={shortcutsOpen} onClose={() => setShortcutsOpen(false)} />
         <UnlockPromptProvider>
+            <UnlockBridge />
             {/* An impersonating admin acts with the impersonated user's access, so their own trusted role
                 mustn't skip the per-mailbox checks. */}
             <ComposeProvider userUid={userUid} trusted={!!trusted && !impersonating}>
-            <div className="min-h-screen flex flex-col bg-surface-alt">
-                {!hideChrome && <BrandingHeader branding={branding} />}
+            <div className="rr-frame-bg min-h-screen flex flex-col">
+                {!hideChrome && customHeader && (
+                    <FrameBrandingHeader
+                        parsed={header}
+                        userMenu={menuInHeader ? renderUserMenu("down") : undefined}
+                        fallbackMenu={header && !menuInHeader && !menuInFooter ? renderUserMenu("down") : undefined}
+                        appTitle={activeLabel}
+                    />
+                )}
                 {impersonating && !hideChrome && (
                     <div className="h-10 shrink-0 bg-warning text-warning-contrast flex items-center justify-center gap-3 text-sm font-medium px-4">
                         <span>
@@ -324,9 +400,15 @@ export function AppChrome({
                     {!hideChrome && (
                     <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"
+                        className={[
+                            "hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center gap-1",
+                            // Under a custom header the rail starts with the app icons; without one its own icon is flush with the top of the window.
+                            customHeader ? "py-3" : "pb-3",
+                        ].join(" ")}
                     >
-                        <img src={iconSrc} width="96" height="96" alt="" className="mb-3" />
+                        {!customHeader && (
+                            <RailIcon src={iconSrc} />
+                        )}
                         {apps.map(({ id, href, label, icon: Icon }) => (
                             <a
                                 key={id}
@@ -348,23 +430,14 @@ export function AppChrome({
                     )}
                     {!hideChrome && <BottomTabBar apps={apps} active={active} />}
                     <div className="flex-1 flex flex-col min-w-0">
-                        {!hideChrome && (
-                        <header className="h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6">
+                        {!hideChrome && !customHeader && (
+                        <header ref={headerRef} className="rr-solid sticky top-0 z-30 h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6">
                             <span className="font-display font-bold text-lg uppercase tracking-wide">{activeLabel}</span>
-                            <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
-                                showNotificationSettings
-                                onShowShortcuts={() => setShortcutsOpen(true)}
-                            />
+                            {renderUserMenu("down")}
                         </header>
                         )}
+                        {/* The one pop-up stack for the whole app: right under the header row, so it never covers the account menu. */}
+                        <NotificationCenter />
                         <div
                             ref={contentRef}
                             id="app-content"
@@ -381,21 +454,14 @@ export function AppChrome({
                         {announcement}
                     </div>
                 )}
-                {!hideChrome && <BrandingFooter branding={branding} />}
+                {!hideChrome && <FrameBrandingFooter parsed={footer} userMenu={menuInFooter ? renderUserMenu("up") : undefined} appTitle={activeLabel} />}
             </div>
             </ComposeProvider>
         </UnlockPromptProvider>
-        {inFrame && (
-            <NewMailToasts
-                toasts={mail.notifications.toasts}
-                onDismiss={mail.notifications.dismiss}
-                offerDesktop={mail.notifications.offerDesktop}
-                onEnableDesktop={() => void mail.notifications.enableDesktop()}
-                onDeclineDesktop={mail.notifications.declineDesktop}
-            />
-        )}
+        <NotificationHistoryDialog open={historyOpen} onClose={() => setHistoryOpen(false)} />
         </MailConnectionContext.Provider>
         </ShortcutProvider>
+        </AppearanceProvider>
     );
 }
 

package/apps/shared/components/layout/BrandingChrome.tsx

@@ -2,9 +2,11 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import React from "react";
+import React, { ReactNode, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
 import DOMPurify from "dompurify";
-import { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+import type { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+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). */
@@ -30,6 +32,19 @@ const FORBIDDEN_TAGS = [
 ];
 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
@@ -42,23 +57,195 @@ export function sanitizeBrandingHtml(html: string): string {
     return DOMPurify.sanitize(html, { FORBID_TAGS: FORBIDDEN_TAGS, FORBID_ATTR: FORBIDDEN_ATTRS });
 }
 
-function BrandingHtml({ html }: { html: string | undefined }) {
-    const clean = html ? sanitizeBrandingHtml(html) : "";
-    if (!clean) {
+/** 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;
+}
+
+function slotElement(name: "user-menu" | "app-title"): HTMLSpanElement {
+    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: string): ParsedBrandingHtml | null {
+    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: Text[] = [];
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+        texts.push(node as Text);
+    }
+    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: string | undefined): ParsedBrandingHtml | null | undefined {
+    const source = html?.trim() ? html : undefined;
+    const [parsed, setParsed] = useState<{ source: string; value: ParsedBrandingHtml | null } | undefined>(undefined);
+    useIsomorphicLayoutEffect(() => {
+        setParsed(source === undefined ? undefined : { source, value: parseBrandingHtml(source) });
+    }, [source]);
+    if (source === undefined) {
+        return null;
+    }
+    return parsed?.source === source ? parsed.value : undefined;
+}
+
+interface BrandingHtmlProps {
+    parsed: ParsedBrandingHtml | null | undefined;
+    /** Rendered into the `{USER_MENU}` slot - only where `hostMenu` says this HTML is where the menu lives. */
+    userMenu?: ReactNode;
+    hostMenu?: boolean;
+    /** The current app's name, rendered into every `{APP_TITLE}` slot. */
+    appTitle?: string;
+    className?: string;
+}
+
+function BrandingHtml({ parsed, userMenu, hostMenu, appTitle, className }: BrandingHtmlProps) {
+    const ref = useRef<HTMLDivElement>(null);
+    const [targets, setTargets] = useState<{ menu: Element | null; titles: Element[] }>({ 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 (
+        <>
+            <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}`))}
+        </>
+    );
+}
+
+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 function FrameBrandingHeader({ parsed, userMenu, fallbackMenu, appTitle }: FrameBrandingHeaderProps) {
+    // 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 <div dangerouslySetInnerHTML={{ __html: clean }} />;
+    return (
+        <header ref={headerRef} className="sticky top-0 z-30 shrink-0 flex items-stretch bg-surface-alt" data-branding-header="">
+            <BrandingHtml parsed={parsed} userMenu={userMenu} hostMenu={parsed?.hasUserMenu} appTitle={appTitle} className="flex-1 min-w-0" />
+            {parsed && !parsed.hasUserMenu && fallbackMenu ? (
+                <div className="shrink-0 flex items-center px-3 bg-surface border-l border-border" data-branding-menu-cell="">
+                    {fallbackMenu}
+                </div>
+            ) : null}
+        </header>
+    );
+}
+
+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 function FrameBrandingFooter({ parsed, userMenu, appTitle }: FrameBrandingFooterProps) {
+    return <BrandingHtml parsed={parsed} userMenu={userMenu} hostMenu={userMenu !== undefined} appTitle={appTitle} />;
+}
+
+export interface BrandingChromeProps {
+    branding: Branding | null;
+    /** What `{APP_TITLE}` is replaced with - the page's own name. Nothing when absent. */
+    appTitle?: string;
 }
 
 /**
- * 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 }: { branding: Branding | null }) {
-    return <BrandingHtml html={branding?.headerHtml} />;
+export function BrandingHeader({ branding, appTitle }: BrandingChromeProps) {
+    return <BrandingHtml parsed={useBrandingHtml(branding?.headerHtml)} appTitle={appTitle} />;
 }
 
-export function BrandingFooter({ branding }: { branding: Branding | null }) {
-    return <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 }: BrandingChromeProps) {
+    return <BrandingHtml parsed={useBrandingHtml(branding?.footerHtml)} appTitle={appTitle} />;
 }

package/apps/shared/components/layout/RailIcon.tsx

@@ -0,0 +1,100 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { 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: ArrayLike<number>, size: number): number {
+    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(): boolean {
+    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: string): Promise<number> {
+    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 }: { src: string }) {
+    const [margin, setMargin] = useState<number | null>(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 (
+        <div className="h-16 w-full shrink-0 overflow-hidden border-b border-border mb-2" data-rail-icon="">
+            <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 }}
+            />
+        </div>
+    );
+}