@rapidmx/web-client 0.10.0 → 0.12.0

package/dist/apps/shared/components/mail/compose/encryptionRequirement.d.ts

@@ -0,0 +1,49 @@
+import { RecipientEncryptionStatus } from "@rapidmx/react-shared/crypto/composeSecurity.js";
+import type { EncryptionPolicy } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
+/**
+ * Whether a message must be treated as encrypted - the one place that decides it, as a pure function of what is *known*.
+ *
+ * **The rule is fail open.** A message is plain, its draft is saved, and nothing about encryption is ever shown, unless encryption is
+ * actually in play. Encryption is in play only when
+ *
+ * 1. the user asked for it ("Encrypt this message", or a reply to encrypted mail, whose quote may carry decrypted text) - that is local
+ * knowledge and needs no request to have succeeded; or
+ * 2. the system's encryption policy **was loaded successfully**, this sender has an encryption key (enrolled on their mailbox, or unlocked
+ * in this tab), the message has recipients, **every** recipient's key lookup succeeded, and the policy auto-applies encryption to all
+ * of them (`decideMessageEncryption().autoEncrypt`: policy `automatic` for their tier, both sides preferring "mutual", a key found).
+ *
+ * Anything that failed to load, is still loading or is slow (the policy, the mailbox, a recipient's lookup) is **unknown**, and unknown
+ * counts as "not encrypted": that is what stops a gateway that flaps, a slow request, or a user who has never set encryption up from
+ * ever blocking a draft, blocking Close, blocking Send or showing an "encryption can't be checked" message. What was unknown is
+ * reported in `unknown`, so a caller that is about to send can give the loads a moment - and only a caller that finds out later that the
+ * message *does* need encryption acts on it (see `ComposeWindow`'s transition rules).
+ *
+ * Why this is safe enough: the requirement only ever protects *this client's* plaintext drafts and sends from being unencrypted when the
+ * server's policy says they should be; it is not the enforcement point (the keys are the user's, the server never sees them). A missing
+ * policy therefore does not mean "encrypt or refuse" - it means the client cannot tell, and the honest default is the one that works.
+ */
+export interface EncryptionFacts {
+    /** The user turned encryption on, or this compose is a reply to / forward of an encrypted message. */
+    encryptRequested: boolean;
+    /** The policy, once it has loaded; `undefined` while loading, failed or slow. */
+    policy: EncryptionPolicy | undefined;
+    /** The sender's mailbox has loaded (its enrolled keys are known). */
+    mailboxLoaded: boolean;
+    /** The sender has an encryption key to encrypt with: enrolled on the mailbox, unlocked in this tab, or offered earlier this session. */
+    hasEncryptionKey: boolean;
+    /** One entry per current recipient (To, Cc and Bcc): the resolved status, or `undefined` while that recipient's lookup is pending or failed. */
+    recipients: (RecipientEncryptionStatus | undefined)[];
+}
+export type EncryptionReason = "requested" | "policy";
+/** What was not known, and could still change the answer. */
+export type UnknownFact = "mailbox" | "policy" | "recipients";
+export interface EncryptionRequirement {
+    /** The message must be encrypted: it is never stored as a plaintext draft and never sent in the clear. */
+    required: boolean;
+    reason: EncryptionReason | null;
+    /** What was unknown (and so assumed "no encryption"). Empty when the answer cannot change with more loading. Never shown to the user. */
+    unknown: UnknownFact[];
+}
+/** Any tier of `policy` auto-encrypts - only then can what is still unknown about the recipients turn a message into an encrypted one. */
+export declare function policyCanAutoEncrypt(policy: EncryptionPolicy): boolean;
+export declare function evaluateEncryptionRequirement(facts: EncryptionFacts): EncryptionRequirement;

package/dist/apps/shared/components/mail/compose/encryptionRequirement.js

@@ -0,0 +1,35 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { decideMessageEncryption } from "@rapidmx/react-shared/crypto/composeSecurity.js";
+/** Any tier of `policy` auto-encrypts - only then can what is still unknown about the recipients turn a message into an encrypted one. */
+export function policyCanAutoEncrypt(policy) {
+    return [policy.encryptSameOrg, policy.encryptFederated, policy.encryptExternal].includes("automatic");
+}
+export function evaluateEncryptionRequirement(facts) {
+    if (facts.encryptRequested) {
+        return { required: true, reason: "requested", unknown: [] };
+    }
+    const unknown = [];
+    if (!facts.hasEncryptionKey) {
+        // Without a key nothing can be encrypted: a user who never set encryption up sees nothing at all. Whether the mailbox has one is
+        // only *unknown* while it has not loaded.
+        return { required: false, reason: null, unknown: facts.mailboxLoaded ? [] : ["mailbox"] };
+    }
+    if (!facts.policy) {
+        return { required: false, reason: null, unknown: ["policy"] };
+    }
+    if (!policyCanAutoEncrypt(facts.policy)) {
+        return { required: false, reason: null, unknown };
+    }
+    if (facts.recipients.length === 0) {
+        // Nobody to decide by yet: plain until a recipient is added.
+        return { required: false, reason: null, unknown };
+    }
+    const statuses = facts.recipients.filter((status) => !!status);
+    if (statuses.length < facts.recipients.length) {
+        return { required: false, reason: null, unknown: ["recipients"] };
+    }
+    return decideMessageEncryption(statuses).autoEncrypt ? { required: true, reason: "policy", unknown } : { required: false, reason: null, unknown };
+}

package/dist/apps/shared/components/mail/layout/MailShell.d.ts

@@ -44,6 +44,8 @@ export interface MailShellContextValue {
      * A no-op on the default context value, which is only ever read outside a real shell.
      */
     onFolderCreated: (folder: Folder) => void;
+    /** Says which folders the messages on screen live in: one the sidebar does not know is looked for (see `MailConnection.noteFolderUids`). A no-op on the default context value. */
+    noteFolderUids: (folderUids: Iterable<string>) => void;
     /**
      * Bumped whenever new mail (or another change to a message) may have arrived - a push event, a reconnect or the safety-net
      * poll - so the list on screen can quietly refetch its first page. See `useMailLiveUpdates()`. Never changes on the default

package/dist/apps/shared/components/mail/layout/MailShell.js

@@ -15,10 +15,12 @@ import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 import { prefetchComposeWindow, useCompose } from "../compose/ComposeContext.js";
 import LocalIndexLifecycle from "../../../search/LocalIndexLifecycle.js";
 import { NO_LIVE_UPDATES } from "../../../mail/useMailLiveUpdates.js";
-import { FOLDER_ORDER, MAILBOX_LIST_LIMIT, MailConnectionContext, useMailConnection } from "../../../mail/useMailConnection.js";
+import { MAILBOX_LIST_LIMIT, MailConnectionContext, useMailConnection } from "../../../mail/useMailConnection.js";
+import { folderRows } from "../../../mail/folderTree.js";
 import { badgeFor, badgeLabel, countOfFolder, inboxUnreadTotal, } from "../../../mail/folderCounts.js";
 import { useUnreadTitle } from "../../../mail/useUnreadTitle.js";
-import NewMailToasts from "../NewMailToasts.js";
+import { pendingCountFor, usePendingSends } from "../../../mail/outbox/pendingSends.js";
+import OutboxBadge from "../OutboxBadge.js";
 import { ariaKeyShortcuts, withHint } from "../../../keyboard/format.js";
 import { SHORTCUTS } from "../../../keyboard/keymap.js";
 import { useKeyEnvironment } from "../../../keyboard/ShortcutProvider.js";
@@ -37,6 +39,7 @@ const MailShellContext = createContext({
     mailboxes: [],
     mailboxFolders: [],
     onFolderCreated: () => undefined,
+    noteFolderUids: () => undefined,
     live: NO_LIVE_UPDATES,
     trackMessageChange: () => NO_TRACKER,
 });
@@ -53,13 +56,6 @@ const FOLDER_LABELS = {
     archive: "Archive",
     deleted_items: "Deleted Items",
 };
-function folderSortKey(folder) {
-    const idx = FOLDER_ORDER.indexOf(folder.type);
-    return idx === -1 ? FOLDER_ORDER.length : idx;
-}
-function sortedFoldersOf(folders) {
-    return [...folders].sort((a, b) => folderSortKey(a) - folderSortKey(b) || a.name.localeCompare(b.name));
-}
 /** The badge an "All Mailboxes" entry shows: the folders of that type, summed across every mailbox, under the same rules as a single folder's. */
 function aggregateBadge(mailboxFolders, type, counts) {
     const sum = mailboxFolders.reduce((total, mf) => {
@@ -128,7 +124,9 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
     const navigate = useNavigate();
     const hosted = useContext(MailConnectionContext);
     const own = useMailConnection({ userUid, enabled: !hosted, open: navigate });
-    const { status, error, mailboxes, mailboxFolders, foldersLoading, onFolderCreated, live, folderCounts, notifications } = hosted ?? own;
+    const { status, error, mailboxes, mailboxFolders, foldersLoading, onFolderCreated, noteFolderUids, live, folderCounts, outbox: outboxStatuses } = hosted ?? own;
+    // The messages this tab is still handing to the server: the Outbox pill counts them at once.
+    const pendingSends = usePendingSends();
     const [requestedMailboxUid, setRequestedMailboxUid] = useState(null);
     const [requestedFolderUid, setRequestedFolderUid] = useState(null);
     const [requestedAggregateType, setRequestedAggregateType] = useState(null);
@@ -171,7 +169,7 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
     const trackMessageChange = folderCounts.track;
     // `(3) Acme: Mail` in the tab strip while there is unread mail in an Inbox - kept by the frame when there is one.
     useUnreadTitle(inboxUnreadTotal(mailboxFolders, counts), { enabled: !hosted });
-    const contextValue = useMemo(() => ({ mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, live, trackMessageChange }), [mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, live, trackMessageChange]);
+    const contextValue = useMemo(() => ({ mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, noteFolderUids, live, trackMessageChange }), [mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, noteFolderUids, live, trackMessageChange]);
     // A full-screen takeover, not nested inside the rest of the app's chrome — there's nothing else for a
     // mailbox-less caller to do here yet, so the icon rail/header/folder tree don't render at all. Checks
     // `mailboxes.length` directly (not `!mailboxUid`) since `mailboxUid` is legitimately undefined in
@@ -200,16 +198,24 @@ export default function MailShell({ userUid, authServerUrl, impersonating, imper
                                                     ? "bg-primary/10 text-primary-dark font-semibold"
                                                     : "text-text hover:bg-surface-alt",
                                             ].join(" "), children: [_jsx("span", { className: badge?.kind === "unread" ? "font-semibold" : undefined, children: FOLDER_LABELS[type] }), badge && _jsx(FolderBadgeChip, { badge: badge })] }, type));
-                                    }) })] })), mailboxFolders.map(({ mailbox, folders, error: mailboxError }) => (_jsxs("div", { children: [_jsxs("div", { className: "text-xs font-bold uppercase tracking-wide text-text-muted mb-1 px-2.5 truncate", children: [mailbox.displayName, mailbox.ownerUserUid ? "" : " (shared)"] }), mailboxError && (_jsx("div", { className: "px-2.5 pb-1", children: _jsx(Alert, { children: mailboxError }) })), _jsx("div", { className: "flex flex-col gap-0.5", children: sortedFoldersOf(folders).map((folder) => {
+                                    }) })] })), mailboxFolders.map(({ mailbox, folders, error: mailboxError }) => (_jsxs("div", { children: [_jsxs("div", { className: "text-xs font-bold uppercase tracking-wide text-text-muted mb-1 px-2.5 truncate", children: [mailbox.displayName, mailbox.ownerUserUid ? "" : " (shared)"] }), mailboxError && (_jsx("div", { className: "px-2.5 pb-1", children: _jsx(Alert, { children: mailboxError }) })), _jsx("div", { className: "flex flex-col gap-0.5", children: folderRows(folders, pendingCountFor(mailbox.uid, pendingSends)).map((row) => {
+                                        if (row.kind === "placeholder") {
+                                            // A folder the server has not made (or told us about) yet - the Outbox and Sent Items are made with the first message
+                                            // sent - shown the moment a message is on its way. Nothing to open; the real folder replaces it when it arrives.
+                                            const sending = pendingCountFor(mailbox.uid, pendingSends);
+                                            return (_jsxs("div", { "data-folder-placeholder": row.type, className: "flex items-center justify-between text-sm rounded-sm py-1.5 px-2.5 text-text-muted", children: [_jsx("span", { children: FOLDER_LABELS[row.type] }), row.type === "outbox" && _jsx(OutboxBadge, { total: sending, pendingHere: sending })] }, `placeholder-${row.type}`));
+                                        }
+                                        const folder = row.folder;
                                         const badge = badgeFor(folder.type, countOfFolder(folder, counts));
                                         return (_jsxs("a", { href: `/?mailboxUid=${encodeURIComponent(mailbox.uid)}&folderUid=${encodeURIComponent(folder.uid)}`, className: [
                                                 "flex items-center justify-between text-sm rounded-sm py-1.5 px-2.5",
                                                 folder.uid === folderUid
                                                     ? "bg-primary/10 text-primary-dark font-semibold"
                                                     : "text-text hover:bg-surface-alt",
-                                            ].join(" "), children: [_jsx("span", { className: badge?.kind === "unread" ? "font-semibold" : undefined, children: FOLDER_LABELS[folder.type] ?? folder.name }), badge && _jsx(FolderBadgeChip, { badge: badge })] }, folder.uid));
+                                            ].join(" "), children: [_jsx("span", { className: badge?.kind === "unread" ? "font-semibold" : undefined, children: FOLDER_LABELS[folder.type] ?? folder.name }), badge &&
+                                                    (folder.type === "outbox" ? (_jsx(OutboxBadge, { total: badge.value, status: outboxStatuses[folder.uid], pendingHere: pendingCountFor(mailbox.uid, pendingSends) })) : (_jsx(FolderBadgeChip, { badge: badge })))] }, folder.uid));
                                     }) })] }, mailbox.uid)))] }))] }));
-        inner = (_jsxs(_Fragment, { children: [_jsx(MailShortcuts, { mailboxUid: defaultMailboxUid }), _jsx("aside", { className: "hidden md:flex w-64 shrink-0 bg-surface border-r border-border flex-col", children: sidebarContent() }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Folders", children: _jsx("div", { className: "flex flex-col", children: sidebarContent() }) }), _jsxs("main", { className: "flex-1 min-w-0 overflow-y-auto", children: [_jsx("button", { type: "button", className: "md:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open folders", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) }), _jsx(MailShellContext.Provider, { value: contextValue, children: children })] }), !hosted && (_jsx(NewMailToasts, { toasts: notifications.toasts, onDismiss: notifications.dismiss, offerDesktop: notifications.offerDesktop, onEnableDesktop: () => void notifications.enableDesktop(), onDeclineDesktop: notifications.declineDesktop }))] }));
+        inner = (_jsxs(_Fragment, { children: [_jsx(MailShortcuts, { mailboxUid: defaultMailboxUid }), _jsx("aside", { className: "hidden md:flex w-64 shrink-0 bg-surface border-r border-border flex-col", children: sidebarContent() }), _jsx(Drawer, { open: drawerOpen, onClose: () => setDrawerOpen(false), title: "Folders", children: _jsx("div", { className: "flex flex-col", children: sidebarContent() }) }), _jsxs("main", { className: "flex-1 min-w-0 overflow-y-auto", children: [_jsx("button", { type: "button", className: "md:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text", "aria-label": "Open folders", onClick: () => setDrawerOpen(true), children: _jsx(HiOutlineBars3, { size: 20, "aria-hidden": "true" }) }), _jsx(MailShellContext.Provider, { value: contextValue, children: children })] })] }));
     }
     // Wraps AppShell unconditionally, at a stable tree position regardless of whether mailboxUid has
     // resolved yet - KeyEnrollmentGate itself passes `children` through untouched until a real

package/dist/apps/shared/components/mail/reading/EncryptedBody.d.ts

@@ -0,0 +1,21 @@
+import React from "react";
+export interface EncryptedBodyProps {
+    /** This device has no unlocked key session for the message's mailbox: unlocking could help. */
+    locked: boolean;
+    /** Why the message couldn't be decrypted when the keys were available (shown for the failed state). */
+    reason?: string;
+    /** Opens the app's unlock prompt (`useUnlockPrompt().requestUnlock`). Only used - and only offered - when `locked`. */
+    onUnlock: () => void;
+    /** An unlock is being asked for: the button waits. */
+    unlocking?: boolean;
+}
+/**
+ * What an encrypted message's body is until (and unless) it can be read, drawn as card content in the app's own tokens: on the theme's opaque surface, so
+ * it stays legible over a translucent card and a background photo.
+ *
+ * **Locked** - the keys are not unlocked: a lock, "This message is encrypted", a hint and a primary Unlock button, which opens the same prompt compose's
+ * "Unlock to sign or encrypt" does. When it succeeds the pane decrypts and shows the message in place.
+ * **Cannot be decrypted** - the keys are unlocked and it still can't be opened (no key for this mailbox, not a recipient, damaged, unsupported): the reason,
+ * and no button - unlocking again wouldn't change it.
+ */
+export default function EncryptedBody({ locked, reason, onUnlock, unlocking }: EncryptedBodyProps): React.JSX.Element;

package/dist/apps/shared/components/mail/reading/EncryptedBody.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { HiOutlineExclamationTriangle, HiOutlineLockClosed } from "react-icons/hi2";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import { useResolvedTheme } from "../../../appearance/resolvedTheme.js";
+import { formatColour } from "./color.js";
+import { useThemeSurface } from "./themeSurface.js";
+/**
+ * What an encrypted message's body is until (and unless) it can be read, drawn as card content in the app's own tokens: on the theme's opaque surface, so
+ * it stays legible over a translucent card and a background photo.
+ *
+ * **Locked** - the keys are not unlocked: a lock, "This message is encrypted", a hint and a primary Unlock button, which opens the same prompt compose's
+ * "Unlock to sign or encrypt" does. When it succeeds the pane decrypts and shows the message in place.
+ * **Cannot be decrypted** - the keys are unlocked and it still can't be opened (no key for this mailbox, not a recipient, damaged, unsupported): the reason,
+ * and no button - unlocking again wouldn't change it.
+ */
+export default function EncryptedBody({ locked, reason, onUnlock, unlocking = false }) {
+    const theme = useResolvedTheme();
+    const surface = useThemeSurface(theme);
+    const Icon = locked ? HiOutlineLockClosed : HiOutlineExclamationTriangle;
+    return (_jsxs("div", { className: "flex flex-col items-center gap-2 rounded-md border border-border px-4 py-8 text-center", style: { backgroundColor: formatColour(surface.background) }, children: [_jsx("span", { "aria-hidden": "true", className: ["inline-flex h-12 w-12 items-center justify-center rounded-full", locked ? "bg-primary/10 text-primary-dark" : "bg-warning/15 text-text"].join(" "), children: _jsx(Icon, { size: 24 }) }), _jsx("p", { className: "text-base font-semibold text-text", children: locked ? "This message is encrypted" : "This message can’t be decrypted" }), locked ? (_jsxs(_Fragment, { children: [_jsx("p", { className: "text-sm text-text-muted", children: "Unlock your keys to read it" }), _jsx(Button, { type: "button", className: "!w-auto mt-1", "aria-label": "Unlock to view this message", loading: unlocking, disabled: unlocking, onClick: onUnlock, children: "Unlock" })] })) : (reason && (_jsx("div", { className: "mt-1 max-w-prose text-left", children: _jsx(Alert, { children: reason }) })))] }));
+}

package/dist/apps/shared/components/mail/reading/EncryptedPreview.d.ts

@@ -0,0 +1,18 @@
+import React from "react";
+/** The subject an encrypted message carries on the server (RFC 9788's placeholder): the real one is inside the ciphertext. */
+export declare const ENCRYPTED_SUBJECT_PLACEHOLDER = "[...]";
+/**
+ * What a list row's preview line says for an encrypted message nothing has been decrypted of yet: a small lock and "Encrypted message". The server never
+ * derives a preview for encrypted mail (it has no plaintext), so the line would otherwise be empty.
+ */
+export declare function EncryptedPreview(): React.JSX.Element;
+/**
+ * Whether a conversation row stands for an encrypted latest message. A conversation summary carries no flag for it, but an encrypted message has no preview
+ * and the placeholder subject - which a plaintext message with an empty body does not.
+ */
+export declare function conversationLooksEncrypted(conversation: {
+    subject: string;
+    latestPreview: string;
+}): boolean;
+/** The subject to show for a message's own: what an encrypted message says is the placeholder, which nobody should have to read as a title. */
+export declare function displaySubject(subject: string): string;

package/dist/apps/shared/components/mail/reading/EncryptedPreview.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { HiOutlineLockClosed } from "react-icons/hi2";
+/** The subject an encrypted message carries on the server (RFC 9788's placeholder): the real one is inside the ciphertext. */
+export const ENCRYPTED_SUBJECT_PLACEHOLDER = "[...]";
+/**
+ * What a list row's preview line says for an encrypted message nothing has been decrypted of yet: a small lock and "Encrypted message". The server never
+ * derives a preview for encrypted mail (it has no plaintext), so the line would otherwise be empty.
+ */
+export function EncryptedPreview() {
+    return (_jsxs("span", { className: "inline-flex items-center gap-1", children: [_jsx(HiOutlineLockClosed, { size: 12, "aria-hidden": "true", className: "shrink-0" }), "Encrypted message"] }));
+}
+/**
+ * Whether a conversation row stands for an encrypted latest message. A conversation summary carries no flag for it, but an encrypted message has no preview
+ * and the placeholder subject - which a plaintext message with an empty body does not.
+ */
+export function conversationLooksEncrypted(conversation) {
+    return conversation.latestPreview === "" && conversation.subject === ENCRYPTED_SUBJECT_PLACEHOLDER;
+}
+/** The subject to show for a message's own: what an encrypted message says is the placeholder, which nobody should have to read as a title. */
+export function displaySubject(subject) {
+    return subject === ENCRYPTED_SUBJECT_PLACEHOLDER ? "Encrypted message" : subject;
+}

package/dist/apps/shared/components/mail/reading/MessageBody.d.ts

@@ -0,0 +1,32 @@
+import React from "react";
+import type { Attachment } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { MimeAttachment } from "@rapidmx/react-shared/crypto/mime.js";
+import { BodyContent } from "./bodyContent.js";
+export interface MessageBodyProps {
+    messageUid: string;
+    /** Part of what a remembered body is keyed on, so an edited message is fetched again. */
+    messageVersion: number;
+    /** The accessible name of the body. */
+    title: string;
+    /** A body the caller already has - decrypted or verified content. Shown instead of asking the server. */
+    content?: BodyContent;
+    /** The message's server-side attachments, for resolving its inline `cid:` images. */
+    attachments?: Attachment[];
+    /** The parts inside a signed or encrypted message, for resolving its inline images from the decrypted content. */
+    inlineParts?: MimeAttachment[];
+    /** Show the message as its author wrote it: nothing adapted to the theme. */
+    original?: boolean;
+    /** Says whether "view original" would change anything, once that is known: never for plain text, a message with its own dark styles, or a
+     * message the theme leaves as it is. */
+    onAdaptable?: (adaptable: boolean) => void;
+}
+/** Placeholder lines shown where the body will be, in the body's own place, until it has arrived and been laid out. */
+export declare function BodySkeleton(): React.JSX.Element;
+/**
+ * The body of one message, in the card's own place: the sanitized HTML in a frame that is exactly as tall as its content (following it as
+ * images load and the width changes), or plain text. See `frameDocument.ts` for the isolation and `themeAdaptation.ts` for how a message
+ * takes the app's theme.
+ *
+ * Nothing waits on the network to lay out: the skeleton is here at once, and the frame's height is only ever the height of what is in it.
+ */
+export default function MessageBody({ messageUid, messageVersion, title, content, attachments, inlineParts, original, onAdaptable }: MessageBodyProps): React.JSX.Element;

package/dist/apps/shared/components/mail/reading/MessageBody.js

@@ -0,0 +1,136 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useMemo, useRef, useState } from "react";
+import { ApiRequestError, apiUrl } from "@rapidmx/react-shared/util/api.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import Skeleton from "@rapidmx/react-shared/components/feedback/Skeleton.js";
+import { useResolvedTheme } from "../../../appearance/resolvedTheme.js";
+import { attachmentSource, cachedBodyContent, fetchBodyContent, makeCidResolver } from "./bodyContent.js";
+import { prepareBodyHtml } from "./bodyHtml.js";
+import { formatColour } from "./color.js";
+import { controlFrame } from "./frameControl.js";
+import { FRAME_SANDBOX, buildFrameDocument } from "./frameDocument.js";
+import { surfaceKey, useThemeSurface } from "./themeSurface.js";
+/** Placeholder lines shown where the body will be, in the body's own place, until it has arrived and been laid out. */
+export function BodySkeleton() {
+    return (_jsxs("div", { role: "status", "aria-busy": "true", className: "flex flex-col gap-2.5 py-1", children: [_jsx("span", { className: "sr-only", children: "Loading the message" }), _jsx(Skeleton, { width: "w-11/12" }), _jsx(Skeleton, { width: "w-4/5" }), _jsx(Skeleton, { width: "w-9/12" }), _jsx(Skeleton, { width: "w-1/2" })] }));
+}
+/** A short, stable fingerprint of a document's text (djb2), to tell one loaded document from the next. */
+function fingerprint(text) {
+    let hash = 5381;
+    for (let i = 0; i < text.length; i++) {
+        hash = ((hash << 5) + hash + text.charCodeAt(i)) | 0;
+    }
+    return (hash >>> 0).toString(36);
+}
+/** The background of a message shown as authored: white, the canvas an HTML message is written for. */
+const AUTHORED_CANVAS = "rgb(255, 255, 255)";
+/**
+ * The body of one message, in the card's own place: the sanitized HTML in a frame that is exactly as tall as its content (following it as
+ * images load and the width changes), or plain text. See `frameDocument.ts` for the isolation and `themeAdaptation.ts` for how a message
+ * takes the app's theme.
+ *
+ * Nothing waits on the network to lay out: the skeleton is here at once, and the frame's height is only ever the height of what is in it.
+ */
+export default function MessageBody({ messageUid, messageVersion, title, content, attachments, inlineParts, original = false, onAdaptable }) {
+    const [remote, setRemote] = useState(() => {
+        const cached = cachedBodyContent(messageUid, messageVersion);
+        return cached ? { status: "ready", content: cached } : { status: "loading" };
+    });
+    const [attempt, setAttempt] = useState(0);
+    const supplied = content !== undefined;
+    useEffect(() => {
+        if (supplied) {
+            return;
+        }
+        const cached = cachedBodyContent(messageUid, messageVersion);
+        if (cached) {
+            setRemote({ status: "ready", content: cached });
+            return;
+        }
+        const controller = new AbortController();
+        setRemote({ status: "loading" });
+        fetchBodyContent(messageUid, messageVersion, controller.signal).then((loaded) => setRemote({ status: "ready", content: loaded }), (err) => {
+            if (!controller.signal.aborted) {
+                setRemote({ status: "error", message: err instanceof ApiRequestError ? err.message : "Could not load this message." });
+            }
+        });
+        return () => controller.abort();
+    }, [messageUid, messageVersion, supplied, attempt]);
+    const shown = content ? { status: "ready", content } : remote;
+    if (shown.status === "loading") {
+        return _jsx(BodySkeleton, {});
+    }
+    if (shown.status === "error") {
+        return (_jsxs("div", { className: "flex flex-col items-start gap-2", children: [_jsx(Alert, { children: shown.message }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: () => setAttempt((n) => n + 1), children: "Try again" })] }));
+    }
+    if (shown.content.kind === "text") {
+        // Rendered as text - React escapes it - never as markup, in the theme's own colours.
+        return _jsx("pre", { "aria-label": title, className: "m-0 text-sm font-sans whitespace-pre-wrap break-words text-text", children: shown.content.text });
+    }
+    return (_jsx(HtmlBody, { messageUid: messageUid, title: title, html: shown.content.html, remoteAvailable: !supplied, attachments: attachments, inlineParts: inlineParts, original: original, onAdaptable: onAdaptable }, messageUid));
+}
+function HtmlBody({ messageUid, title, html, remoteAvailable, attachments, inlineParts, original, onAdaptable, }) {
+    const theme = useResolvedTheme();
+    const surface = useThemeSurface(theme);
+    // Keyed on what the resolver reads rather than on the arrays, which a caller may rebuild on every render.
+    const inlineKey = [...(attachments ?? []).map((a) => `${a.uid}:${a.contentId ?? ""}`), inlineParts ? `parts:${inlineParts.length}` : ""].join("|");
+    const resolveCid = useMemo(() => makeCidResolver(attachments, inlineParts), [inlineKey]);
+    const prepared = useMemo(() => prepareBodyHtml(html, { resolveCid }), [html, resolveCid]);
+    const mode = prepared.declaresDarkSupport ? "native" : original ? "original" : "adapt";
+    const surfaceCss = formatColour(surface.background);
+    const srcDoc = useMemo(() => {
+        // The frame may load images from this server's attachment URLs only when an inline image was actually resolved to one.
+        const source = prepared.inlineImages > 0 ? attachmentSource() : undefined;
+        return buildFrameDocument(prepared.html, {
+            mode,
+            scheme: theme,
+            surface: surfaceCss,
+            text: formatColour(surface.text),
+            attachmentSource: source && prepared.html.includes(source) ? source : undefined,
+        });
+    }, [prepared, mode, theme, surfaceCss, surface.text]);
+    // A different body, surface or mode is a different document: the adaptation pass edits the document it ran on, so it is run on a fresh
+    // one, and the old one's readiness is not the new one's.
+    const frameKey = useMemo(() => `${mode}:${surfaceKey(surface)}:${fingerprint(srcDoc)}`, [mode, surface, srcDoc]);
+    const [height, setHeight] = useState(undefined);
+    const [readyFor, setReadyFor] = useState(null);
+    const [canvasAuthored, setCanvasAuthored] = useState(false);
+    const dispose = useRef(undefined);
+    useEffect(() => () => dispose.current?.(), []);
+    const reportAdaptable = useRef(onAdaptable);
+    reportAdaptable.current = onAdaptable;
+    useEffect(() => {
+        if (mode === "native") {
+            reportAdaptable.current?.(false);
+        }
+    }, [mode]);
+    if (prepared.status === "too_large") {
+        return (_jsxs(Alert, { children: ["This message is too large to show here.", " ", remoteAvailable && (_jsx("a", { href: apiUrl(`/mail/messages/${encodeURIComponent(messageUid)}/content`), target: "_blank", rel: "noopener noreferrer", className: "font-medium underline", children: "Open it in its own tab" }))] }));
+    }
+    const ready = readyFor === frameKey;
+    const canvas = mode === "original" ? AUTHORED_CANVAS : surfaceCss;
+    const framed = mode !== "adapt" || canvasAuthored;
+    return (_jsxs("div", { className: "relative rounded-md overflow-hidden", style: { backgroundColor: canvas }, children: [!ready && _jsx(BodySkeleton, {}), _jsx("iframe", { title: title, srcDoc: srcDoc, sandbox: FRAME_SANDBOX, scrolling: "no", onLoad: (event) => {
+                    dispose.current?.();
+                    dispose.current = controlFrame(event.currentTarget, {
+                        surface: mode === "adapt" ? surface : undefined,
+                        onHeight: setHeight,
+                        onReady: (adaptation) => {
+                            setReadyFor(frameKey);
+                            if (adaptation) {
+                                setCanvasAuthored(adaptation.authoredCanvas);
+                                reportAdaptable.current?.(adaptation.material);
+                            }
+                        },
+                    });
+                }, className: [
+                    "block w-full border-0 rounded-md",
+                    ready ? "" : "absolute inset-x-0 top-0 invisible",
+                    framed && ready ? "ring-1 ring-border" : "",
+                ].join(" "), style: { height: height ?? 0 } }, frameKey)] }));
+}

package/dist/apps/shared/components/mail/reading/MessageCard.d.ts

@@ -0,0 +1,62 @@
+import React from "react";
+import type { MailAddressLike } from "@rapidmx/react-shared/mail/mailAddress.js";
+/**
+ * The pieces the reading pane is drawn from: a header card that carries the subject, and one card per message. Built from the app's own
+ * tokens only (`bg-surface`, `text-text`, `border-border`), so they follow the theme, a branding palette and the Appearance colours; the
+ * body area inside a card paints its own opaque surface (`MessageBody`), so a translucent card over a background photo stays legible.
+ */
+/** The header-style card at the top of the pane: the conversation's (or message's) subject, and what goes with it. */
+export declare function SubjectCard({ subject, meta, children, }: {
+    subject: string;
+    /** A line under the subject, such as "3 messages". */
+    meta?: React.ReactNode;
+    children?: React.ReactNode;
+}): React.JSX.Element;
+/** One message's card: rounded, bordered, lifted a little, its content clipped to the corners. The accent bar of an unread message runs down its left edge. */
+export declare function CardShell({ unread, className, children, }: {
+    unread?: boolean;
+    className?: string;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * Headings carry the display typeface globally (`app.css`, unlayered - so no utility class can beat it); a sender line that happens to be a
+ * heading is body text and keeps the body's, by inline style.
+ */
+export declare const BODY_FONT_STYLE: React.CSSProperties;
+/** A sender's avatar in the card header. There are no photos in the data, so this is the initials disc every contact gets. */
+export declare function SenderAvatar({ from }: {
+    from: MailAddressLike;
+}): React.JSX.Element;
+/**
+ * A collapsed message: its card with the sender, the date and the first line of the body, all of it the one button that expands it.
+ * Shares the header's look with an expanded card, so expanding does not change how the message begins.
+ */
+export declare function CollapsedCard({ from, date, preview, unread, buttonProps, buttonRef, senderClassName, dateClassName, }: {
+    from: MailAddressLike;
+    date: string;
+    preview: React.ReactNode;
+    unread: boolean;
+    buttonProps: React.ButtonHTMLAttributes<HTMLButtonElement>;
+    buttonRef: (node: HTMLButtonElement | null) => void;
+    senderClassName: string;
+    dateClassName: string;
+}): React.JSX.Element;
+/** The card's place-holder while its message is still loading: an avatar, two header lines and a few lines of body. */
+export declare function CardSkeleton(): React.JSX.Element;
+/**
+ * What the pane shows while it is getting ready - its code loading, a conversation's messages arriving: the subject card as soon as the
+ * subject is known (`subject` is `undefined` when it is not, as on the mobile page before its message arrived) and a skeleton card per
+ * message, so the frame of the pane is on screen at once and the messages only fill in. One live region for the whole thing.
+ */
+export declare function ReadingPaneSkeleton({ subject, messageCount }: {
+    subject?: string;
+    messageCount?: number;
+}): React.JSX.Element;
+/**
+ * The skeleton cards themselves - up to three, one live region ("Loading the message") for all of them - in the place the message cards take,
+ * so a pane that already shows its subject card (a thread whose messages are still coming) swaps them for the real ones without the header
+ * card being drawn again.
+ */
+export declare function SkeletonCards({ messageCount }: {
+    messageCount?: number;
+}): React.JSX.Element;

package/dist/apps/shared/components/mail/reading/MessageCard.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import ContactAvatar from "@rapidmx/react-shared/components/avatar/ContactAvatar.js";
+import Skeleton from "@rapidmx/react-shared/components/feedback/Skeleton.js";
+import MailAddress from "../MailAddress.js";
+import { UnreadBar, UnreadLabel } from "../unreadStyle.js";
+/**
+ * The pieces the reading pane is drawn from: a header card that carries the subject, and one card per message. Built from the app's own
+ * tokens only (`bg-surface`, `text-text`, `border-border`), so they follow the theme, a branding palette and the Appearance colours; the
+ * body area inside a card paints its own opaque surface (`MessageBody`), so a translucent card over a background photo stays legible.
+ */
+/** The header-style card at the top of the pane: the conversation's (or message's) subject, and what goes with it. */
+export function SubjectCard({ subject, meta, children, }) {
+    return (_jsxs("header", { className: "shrink-0 mx-2 mt-2 sm:mx-3 sm:mt-3 rounded-lg border border-border bg-surface backdrop-blur-sm shadow-sm px-4 py-2.5", children: [_jsx("h1", { className: "text-base sm:text-lg font-bold tracking-tight line-clamp-2 break-words", children: subject }), meta && _jsx("p", { className: "text-xs sm:text-sm text-text-muted mt-0.5", children: meta }), children] }));
+}
+/** One message's card: rounded, bordered, lifted a little, its content clipped to the corners. The accent bar of an unread message runs down its left edge. */
+export function CardShell({ unread = false, className = "", children, }) {
+    return (_jsxs("div", { className: ["relative rounded-lg border border-border bg-surface backdrop-blur-sm shadow-sm overflow-hidden", className].join(" "), children: [_jsx(UnreadBar, { unread: unread }), children] }));
+}
+/**
+ * Headings carry the display typeface globally (`app.css`, unlayered - so no utility class can beat it); a sender line that happens to be a
+ * heading is body text and keeps the body's, by inline style.
+ */
+export const BODY_FONT_STYLE = { fontFamily: "var(--rr-font-family)" };
+/** A sender's avatar in the card header. There are no photos in the data, so this is the initials disc every contact gets. */
+export function SenderAvatar({ from }) {
+    return _jsx(ContactAvatar, { displayName: from.displayName || from.name || from.address, size: 40 });
+}
+/**
+ * A collapsed message: its card with the sender, the date and the first line of the body, all of it the one button that expands it.
+ * Shares the header's look with an expanded card, so expanding does not change how the message begins.
+ */
+export function CollapsedCard({ from, date, preview, unread, buttonProps, buttonRef, senderClassName, dateClassName, }) {
+    return (_jsx(CardShell, { unread: unread, children: _jsx("h2", { style: BODY_FONT_STYLE, children: _jsxs("button", { type: "button", ref: buttonRef, ...buttonProps, className: [
+                    "w-full text-left flex items-center gap-3 px-4 py-3",
+                    unread ? "bg-primary/[0.07] hover:bg-primary/10" : "hover:bg-surface-alt",
+                    "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-primary",
+                ].join(" "), children: [_jsx(UnreadLabel, { unread: unread }), _jsx(SenderAvatar, { from: from }), _jsxs("span", { className: "flex-1 min-w-0", children: [_jsxs("span", { className: "flex flex-wrap items-baseline justify-between gap-x-2 text-sm", children: [_jsx(MailAddress, { recipient: from, className: `${senderClassName} min-w-[13rem]! flex-1` }), _jsx("span", { className: ["text-xs shrink-0", dateClassName].join(" "), children: date })] }), _jsx("span", { className: "block text-xs text-text-muted truncate font-normal", children: preview })] })] }) }) }));
+}
+/** The card's place-holder while its message is still loading: an avatar, two header lines and a few lines of body. */
+export function CardSkeleton() {
+    return (_jsxs("div", { "aria-hidden": "true", className: "rounded-lg border border-border bg-surface shadow-sm overflow-hidden", children: [_jsxs("div", { className: "flex items-center gap-3 px-4 py-3", children: [_jsx(Skeleton, { width: "w-10", height: "h-10", className: "rounded-full shrink-0" }), _jsxs("div", { className: "flex-1 flex flex-col gap-2", children: [_jsx(Skeleton, { width: "w-1/3" }), _jsx(Skeleton, { width: "w-1/2", height: "h-3" })] }), _jsx(Skeleton, { width: "w-16", height: "h-3" })] }), _jsxs("div", { className: "flex flex-col gap-2.5 px-4 pb-4", children: [_jsx(Skeleton, { width: "w-11/12" }), _jsx(Skeleton, { width: "w-4/5" }), _jsx(Skeleton, { width: "w-9/12" })] })] }));
+}
+/**
+ * What the pane shows while it is getting ready - its code loading, a conversation's messages arriving: the subject card as soon as the
+ * subject is known (`subject` is `undefined` when it is not, as on the mobile page before its message arrived) and a skeleton card per
+ * message, so the frame of the pane is on screen at once and the messages only fill in. One live region for the whole thing.
+ */
+export function ReadingPaneSkeleton({ subject, messageCount = 1 }) {
+    return (_jsxs("div", { className: "flex-1 min-w-0 min-h-0 flex flex-col", children: [subject !== undefined ? (_jsx(SubjectCard, { subject: subject || "(no subject)", meta: messageCount > 1 ? `${messageCount} messages` : undefined })) : (_jsx("div", { "aria-hidden": "true", className: "shrink-0 mx-2 mt-2 sm:mx-3 sm:mt-3 rounded-lg border border-border bg-surface shadow-sm px-4 py-3", children: _jsx(Skeleton, { width: "w-2/3", height: "h-6" }) })), _jsx(SkeletonCards, { messageCount: messageCount })] }));
+}
+/**
+ * The skeleton cards themselves - up to three, one live region ("Loading the message") for all of them - in the place the message cards take,
+ * so a pane that already shows its subject card (a thread whose messages are still coming) swaps them for the real ones without the header
+ * card being drawn again.
+ */
+export function SkeletonCards({ messageCount = 1 }) {
+    return (_jsxs("div", { role: "status", "aria-busy": "true", className: "flex-1 min-h-0 overflow-y-auto p-2 sm:p-3 flex flex-col gap-3", children: [_jsx("span", { className: "sr-only", children: "Loading the message" }), Array.from({ length: Math.min(3, Math.max(1, messageCount)) }, (_, index) => (_jsx(CardSkeleton, {}, index)))] }));
+}

package/dist/apps/shared/components/mail/reading/bodyContent.d.ts

@@ -0,0 +1,38 @@
+import { Attachment } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { MimeAttachment } from "@rapidmx/react-shared/crypto/mime.js";
+/** What a message's body is: server-sanitized HTML, or plain text (a message with no HTML part, or the server's plain-text fallback). */
+export type BodyContent = {
+    kind: "html";
+    html: string;
+} | {
+    kind: "text";
+    text: string;
+};
+/** What the pane asks `/content` for. */
+export declare const ACCEPT = "text/html, text/plain;q=0.8";
+/** Forgets every remembered body (sign-out, and the tests). */
+export declare function clearBodyContentCache(): void;
+/** The remembered body for a message at a version, if any. */
+export declare function cachedBodyContent(uid: string, version: number): BodyContent | undefined;
+/**
+ * The message's body from the server's `GET /mail/messages/:id/content`: the HTML the server sanitized when it ingested the message
+ * (`sanitizedHtmlBlobKey`), or - for a message with none - the plain-text preview. A request that fails throws an `ApiRequestError`.
+ * Successful answers are remembered per uid and version.
+ */
+export declare function fetchBodyContent(uid: string, version: number, signal?: AbortSignal): Promise<BodyContent>;
+/** The largest inline image embedded into a body from a signed or encrypted message. */
+export declare const MAX_INLINE_IMAGE_BYTES = 5000000;
+/** A server attachment record as it may really arrive: the model carries the part's `Content-ID`, though the client type doesn't list it. */
+export type InlineCapable = Attachment & {
+    contentId?: string;
+};
+/** The absolute URL of an attachment - the frame is a document of its own, where a relative URL would not mean what it does here. */
+export declare function absoluteAttachmentUrl(uid: string): string;
+/** The CSP source that allows exactly this server's attachment URLs and nothing else. */
+export declare function attachmentSource(): string;
+/**
+ * How an inline `cid:` image is resolved to something the frame may load: for a message shown from the server, the attachment whose
+ * `Content-ID` matches (its URL on this server); for a decrypted or verified one, the part inside the signed/encrypted entity, embedded
+ * as a `data:` URI (raster and SVG images up to `MAX_INLINE_IMAGE_BYTES`). Anything else has no source, so the image is not shown.
+ */
+export declare function makeCidResolver(attachments: InlineCapable[] | undefined, parts: MimeAttachment[] | undefined): (contentId: string) => string | undefined;