@rapidmx/web-client 0.10.0 → 0.11.0

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

@@ -14,11 +14,14 @@ import { useIdleKeyTimeout } from "@rapidmx/react-shared/crypto/useIdleKeyTimeou
 import ComposeProvider from "../mail/compose/ComposeContext.js";
 import { flushComposeDrafts, markSigningOut } from "../mail/compose/composeFlushRegistry.js";
 import BottomTabBar from "@rapidmx/react-shared/components/navigation/BottomTabBar.js";
-import { BrandingFooter, BrandingHeader } from "./BrandingChrome.js";
+import { FrameBrandingFooter, FrameBrandingHeader, useBrandingHtml } from "./BrandingChrome.js";
+import RailIcon from "./RailIcon.js";
+import AppearanceProvider from "../../appearance/AppearanceProvider.js";
+import { clearAppearanceCache } from "../../appearance/appearanceCache.js";
 import UserMenu from "./UserMenu.js";
 import { UnlockPromptProvider } from "./UnlockPromptProvider.js";
 import { SIGN_OUT_CHANNEL, destroyAllLocalIndexes } from "../../search/localIndexRpcClient.js";
-import { authApiFetch } from "@rapidmx/react-shared/util/api.js";
+import { authApiFetch, setApiUnauthorizedObserver } from "@rapidmx/react-shared/util/api.js";
 import { destroyUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
 import { clearPinnedSignerCache } from "../mail/pinnedSigners.js";
 import { mergePluginNavItems } from "../../plugins/pluginNav.js";
@@ -31,7 +34,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 = 3000;
 /**
@@ -77,12 +86,24 @@ export function appRailItems(pluginNav) {
  * 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 function AppChrome({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, routeKey, busy, hideChrome, children, }) {
+export function AppChrome({ active, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, branding: initialBranding, appearance, pluginNav, routeKey, busy, hideChrome, children, }) {
     const [stoppingImpersonation, setStoppingImpersonation] = useState(false);
     // The keyboard shortcuts dialog: opened by `?`/Ctrl+/ (`GlobalShortcuts`) and by the account menu's item.
     const [shortcutsOpen, setShortcutsOpen] = useState(false);
+    // The pop-up history ("Recent notifications" in the account menu). The pop-ups themselves are drawn by `NotificationCenter`, below.
+    const [historyOpen, setHistoryOpen] = useState(false);
+    // Only the count is read, so the whole frame does not render again for every pop-up that comes and goes.
+    const unseenErrors = useUnseenErrorCount();
+    // The title bar's height for the pop-up stack, which sticks just below the header (a branding header publishes its own - `FrameBrandingHeader`).
+    const headerRef = useHeaderHeightRef();
     const signingOutRef = useRef(false);
-    const { branding, iconSrc } = useBranding();
+    const { branding: fetchedBranding, iconSrc: fetchedIconSrc } = useBranding();
+    // The server's copy until the fetch answers, so the frame's shape (a custom header replaces the title bar) never changes after the first paint.
+    const branding = fetchedBranding ?? initialBranding ?? null;
+    const iconSrc = fetchedBranding ? fetchedIconSrc : initialBranding?.iconUrl || initialBranding?.logoUrl || fetchedIconSrc;
+    // The custom header and footer, sanitized and with their `{USER_MENU}` / `{APP_TITLE}` placeholders (`undefined` until parsed, `null` when there is none).
+    const header = useBrandingHtml(branding?.headerHtml);
+    const footer = useBrandingHtml(branding?.footerHtml);
     // The mailboxes, their folders and the one push connection live here, in the frame that stays mounted as the router swaps pages - so
     // new-mail pop-ups, the folder counters and the tab title's unread count work in Calendar, Contacts, Tasks and Settings too, and moving
     // between apps never opens a second socket (the server allows ten per user). `MailShell` reads them from `MailConnectionContext`. Outside
@@ -90,7 +111,19 @@ export function AppChrome({ active, userUid, authServerUrl, impersonating, imper
     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();
@@ -130,6 +163,7 @@ export function AppChrome({ active, userUid, authServerUrl, impersonating, imper
             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 ?? "/";
@@ -146,6 +180,7 @@ export function AppChrome({ active, userUid, authServerUrl, impersonating, imper
         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);
@@ -204,14 +239,25 @@ export function AppChrome({ active, userUid, authServerUrl, impersonating, imper
     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(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 }))] }) }));
+    // A custom header (`Branding.headerHtml`) replaces the app's own title bar and the icon at the top of the rail: it is the top of the app, and the
+    // account menu moves into it. While it is still being parsed it already counts, so the frame's shape doesn't change under the user.
+    const customHeader = header !== null;
+    // Where the one account menu lives: the header's `{USER_MENU}`, else the footer's, else a small cell at the header's right end - never lost.
+    const menuInHeader = !!header?.hasUserMenu;
+    const menuInFooter = customHeader && !!header && !menuInHeader && !!footer?.hasUserMenu;
+    const renderUserMenu = (placement) => (_jsx(UserMenu, { userUid: userUid, authServerUrl: authServerUrl, onSignOut: handleSignOut, 
+        // An impersonating administrator acts as the impersonated user, so the console link is hidden then.
+        showAdminLink: !!trusted && !impersonating, detectAdmin: !trusted && !impersonating, trustedRoles: trustedRoles, showSettingsLink: true, showNotificationSettings: true, onShowShortcuts: () => setShortcutsOpen(true), onShowNotifications: () => setHistoryOpen(true), unseenErrors: unseenErrors, placement: placement }));
+    return (_jsx(AppearanceProvider, { userUid: userUid, initial: appearance, lookUp: inFrame, children: _jsx(ShortcutProvider, { children: _jsxs(MailConnectionContext.Provider, { value: inFrame ? mail : null, children: [_jsx(GlobalShortcuts, { authServerUrl: authServerUrl, onToggleHelp: () => setShortcutsOpen((open) => !open) }), _jsx(ShortcutsDialog, { open: shortcutsOpen, onClose: () => setShortcutsOpen(false) }), _jsxs(UnlockPromptProvider, { children: [_jsx(UnlockBridge, {}), _jsx(ComposeProvider, { userUid: userUid, trusted: !!trusted && !impersonating, children: _jsxs("div", { className: "rr-frame-bg min-h-screen flex flex-col", children: [!hideChrome && customHeader && (_jsx(FrameBrandingHeader, { parsed: header, userMenu: menuInHeader ? renderUserMenu("down") : undefined, fallbackMenu: header && !menuInHeader && !menuInFooter ? renderUserMenu("down") : undefined, appTitle: activeLabel })), impersonating && !hideChrome && (_jsxs("div", { className: "h-10 shrink-0 bg-warning text-warning-contrast flex items-center justify-center gap-3 text-sm font-medium px-4", children: [_jsxs("span", { children: ["You are viewing as ", _jsx("strong", { children: userUid }), "."] }), _jsx("button", { type: "button", onClick: handleStopImpersonating, disabled: stoppingImpersonation, className: "underline hover:no-underline disabled:opacity-60", children: stoppingImpersonation ? "Returning to admin…" : "Return to admin" })] })), _jsxs("div", { className: "flex-1 flex min-h-0", children: [!hideChrome && (_jsxs("nav", { "aria-label": "Apps", className: [
+                                                        "hidden md:flex w-16 shrink-0 bg-surface border-r border-border flex-col items-center gap-1",
+                                                        // Under a custom header the rail starts with the app icons; without one its own icon is flush with the top of the window.
+                                                        customHeader ? "py-3" : "pb-3",
+                                                    ].join(" "), children: [!customHeader && (_jsx(RailIcon, { src: iconSrc })), apps.map(({ id, href, label, icon: Icon }) => (_jsx("a", { href: href, "aria-label": label, "aria-current": id === active ? "page" : undefined, title: label, className: [
+                                                                "w-10 h-10 flex items-center justify-center rounded-sm",
+                                                                id === active
+                                                                    ? "bg-primary/10 text-primary-dark"
+                                                                    : "text-text-muted hover:bg-surface-alt hover:text-text",
+                                                            ].join(" "), children: _jsx(Icon, { size: 20, "aria-hidden": "true" }) }, id)))] })), !hideChrome && _jsx(BottomTabBar, { apps: apps, active: active }), _jsxs("div", { className: "flex-1 flex flex-col min-w-0", children: [!hideChrome && !customHeader && (_jsxs("header", { ref: headerRef, className: "rr-solid sticky top-0 z-30 h-16 shrink-0 bg-surface border-b border-border flex items-center justify-between gap-4 px-6", children: [_jsx("span", { className: "font-display font-bold text-lg uppercase tracking-wide", children: activeLabel }), renderUserMenu("down")] })), _jsx(NotificationCenter, {}), _jsx("div", { ref: contentRef, id: "app-content", tabIndex: -1, "aria-busy": busy || undefined, className: ["flex-1 flex min-h-0 outline-none", hideChrome ? "" : "pb-14 md:pb-0"].join(" "), children: children })] })] }), routeKey !== undefined && (_jsx("div", { role: "status", "aria-live": "polite", className: "sr-only", children: announcement })), !hideChrome && _jsx(FrameBrandingFooter, { parsed: footer, userMenu: menuInFooter ? renderUserMenu("up") : undefined, appTitle: activeLabel })] }) })] }), _jsx(NotificationHistoryDialog, { open: historyOpen, onClose: () => setHistoryOpen(false) })] }) }) }));
 }
 /**
  * What a page's own shell (`MailShell`, `CalendarShell`, ...) renders around its content. Outside the client-side router it

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/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;