@rapidmx/web-client 0.10.0 → 0.11.0

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

@@ -0,0 +1,86 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { RecipientEncryptionStatus, decideMessageEncryption } 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 function policyCanAutoEncrypt(policy: EncryptionPolicy): boolean {
+    return [policy.encryptSameOrg, policy.encryptFederated, policy.encryptExternal].includes("automatic");
+}
+
+export function evaluateEncryptionRequirement(facts: EncryptionFacts): EncryptionRequirement {
+    if (facts.encryptRequested) {
+        return { required: true, reason: "requested", unknown: [] };
+    }
+    const unknown: UnknownFact[] = [];
+    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 is RecipientEncryptionStatus => !!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/apps/shared/components/mail/layout/MailShell.tsx

@@ -15,7 +15,8 @@ import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 import { prefetchComposeWindow, useCompose } from "../compose/ComposeContext.js";
 import LocalIndexLifecycle from "../../../search/LocalIndexLifecycle.js";
 import { LiveUpdates, 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 {
     CountTracker,
     FolderBadge,
@@ -26,7 +27,8 @@ import {
     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";
@@ -79,6 +81,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
@@ -100,6 +104,7 @@ const MailShellContext = createContext<MailShellContextValue>({
     mailboxes: [],
     mailboxFolders: [],
     onFolderCreated: () => undefined,
+    noteFolderUids: () => undefined,
     live: NO_LIVE_UPDATES,
     trackMessageChange: () => NO_TRACKER,
 });
@@ -119,15 +124,6 @@ const FOLDER_LABELS: Record<string, string> = {
     deleted_items: "Deleted Items",
 };
 
-function folderSortKey(folder: Folder): number {
-    const idx = FOLDER_ORDER.indexOf(folder.type);
-    return idx === -1 ? FOLDER_ORDER.length : idx;
-}
-
-function sortedFoldersOf(folders: Folder[]): Folder[] {
-    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: MailboxFolders[], type: AggregateFolderType, counts: Record<string, FolderCount>): FolderBadge | undefined {
     const sum = mailboxFolders.reduce(
@@ -234,7 +230,9 @@ export default function MailShell({
     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<string | null>(null);
     const [requestedFolderUid, setRequestedFolderUid] = useState<string | null>(null);
     const [requestedAggregateType, setRequestedAggregateType] = useState<string | null>(null);
@@ -285,8 +283,8 @@ export default function MailShell({
     useUnreadTitle(inboxUnreadTotal(mailboxFolders, counts), { enabled: !hosted });
 
     const contextValue = useMemo<MailShellContextValue>(
-        () => ({ mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, live, trackMessageChange }),
-        [mailboxUid, folderUid, aggregateFolderType, mailboxes, mailboxFolders, onFolderCreated, live, trackMessageChange],
+        () => ({ 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
@@ -369,7 +367,23 @@ export default function MailShell({
                                     </div>
                                 )}
                                 <div className="flex flex-col gap-0.5">
-                                    {sortedFoldersOf(folders).map((folder) => {
+                                    {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 (
+                                                <div
+                                                    key={`placeholder-${row.type}`}
+                                                    data-folder-placeholder={row.type}
+                                                    className="flex items-center justify-between text-sm rounded-sm py-1.5 px-2.5 text-text-muted"
+                                                >
+                                                    <span>{FOLDER_LABELS[row.type]}</span>
+                                                    {row.type === "outbox" && <OutboxBadge total={sending} pendingHere={sending} />}
+                                                </div>
+                                            );
+                                        }
+                                        const folder = row.folder;
                                         const badge = badgeFor(folder.type, countOfFolder(folder, counts));
                                         return (
                                         <a
@@ -385,7 +399,16 @@ export default function MailShell({
                                             <span className={badge?.kind === "unread" ? "font-semibold" : undefined}>
                                                 {FOLDER_LABELS[folder.type] ?? folder.name}
                                             </span>
-                                            {badge && <FolderBadgeChip badge={badge} />}
+                                            {badge &&
+                                                (folder.type === "outbox" ? (
+                                                    <OutboxBadge
+                                                        total={badge.value}
+                                                        status={outboxStatuses[folder.uid]}
+                                                        pendingHere={pendingCountFor(mailbox.uid, pendingSends)}
+                                                    />
+                                                ) : (
+                                                    <FolderBadgeChip badge={badge} />
+                                                ))}
                                         </a>
                                         );
                                     })}
@@ -415,15 +438,6 @@ export default function MailShell({
                     </button>
                     <MailShellContext.Provider value={contextValue}>{children}</MailShellContext.Provider>
                 </main>
-                {!hosted && (
-                    <NewMailToasts
-                        toasts={notifications.toasts}
-                        onDismiss={notifications.dismiss}
-                        offerDesktop={notifications.offerDesktop}
-                        onEnableDesktop={() => void notifications.enableDesktop()}
-                        onDeclineDesktop={notifications.declineDesktop}
-                    />
-                )}
             </>
         );
     }

package/apps/shared/components/mail/reading/EncryptedBody.tsx

@@ -0,0 +1,65 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+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";
+
+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 = false }: EncryptedBodyProps) {
+    const theme = useResolvedTheme();
+    const surface = useThemeSurface(theme);
+    const Icon = locked ? HiOutlineLockClosed : HiOutlineExclamationTriangle;
+    return (
+        <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) }}
+        >
+            <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(" ")}
+            >
+                <Icon size={24} />
+            </span>
+            <p className="text-base font-semibold text-text">{locked ? "This message is encrypted" : "This message can’t be decrypted"}</p>
+            {locked ? (
+                <>
+                    <p className="text-sm text-text-muted">Unlock your keys to read it</p>
+                    <Button type="button" className="!w-auto mt-1" aria-label="Unlock to view this message" loading={unlocking} disabled={unlocking} onClick={onUnlock}>
+                        Unlock
+                    </Button>
+                </>
+            ) : (
+                reason && (
+                    <div className="mt-1 max-w-prose text-left">
+                        <Alert>{reason}</Alert>
+                    </div>
+                )
+            )}
+        </div>
+    );
+}

package/apps/shared/components/mail/reading/EncryptedPreview.tsx

@@ -0,0 +1,35 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+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 (
+        <span className="inline-flex items-center gap-1">
+            <HiOutlineLockClosed size={12} aria-hidden="true" className="shrink-0" />
+            Encrypted message
+        </span>
+    );
+}
+
+/**
+ * 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: { subject: string; latestPreview: string }): boolean {
+    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: string): string {
+    return subject === ENCRYPTED_SUBJECT_PLACEHOLDER ? "Encrypted message" : subject;
+}

package/apps/shared/components/mail/reading/MessageBody.tsx

@@ -0,0 +1,240 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { ApiRequestError, apiUrl } from "@rapidmx/react-shared/util/api.js";
+import type { Attachment } from "@rapidmx/react-shared/mail/mailApi.js";
+import type { MimeAttachment } from "@rapidmx/react-shared/crypto/mime.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 { BodyContent, 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, FrameMode, buildFrameDocument } from "./frameDocument.js";
+import { surfaceKey, useThemeSurface } from "./themeSurface.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;
+}
+
+type Remote = { status: "loading" } | { status: "ready"; content: BodyContent } | { status: "error"; message: string };
+
+/** 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 (
+        <div role="status" aria-busy="true" className="flex flex-col gap-2.5 py-1">
+            <span className="sr-only">Loading the message</span>
+            <Skeleton width="w-11/12" />
+            <Skeleton width="w-4/5" />
+            <Skeleton width="w-9/12" />
+            <Skeleton width="w-1/2" />
+        </div>
+    );
+}
+
+/** A short, stable fingerprint of a document's text (djb2), to tell one loaded document from the next. */
+function fingerprint(text: string): string {
+    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 }: MessageBodyProps) {
+    const [remote, setRemote] = useState<Remote>(() => {
+        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: Remote = content ? { status: "ready", content } : remote;
+    if (shown.status === "loading") {
+        return <BodySkeleton />;
+    }
+    if (shown.status === "error") {
+        return (
+            <div className="flex flex-col items-start gap-2">
+                <Alert>{shown.message}</Alert>
+                <Button type="button" variant="secondary" className="!w-auto" onClick={() => setAttempt((n) => n + 1)}>
+                    Try again
+                </Button>
+            </div>
+        );
+    }
+    if (shown.content.kind === "text") {
+        // Rendered as text - React escapes it - never as markup, in the theme's own colours.
+        return <pre aria-label={title} className="m-0 text-sm font-sans whitespace-pre-wrap break-words text-text">{shown.content.text}</pre>;
+    }
+    return (
+        <HtmlBody
+            key={messageUid}
+            messageUid={messageUid}
+            title={title}
+            html={shown.content.html}
+            remoteAvailable={!supplied}
+            attachments={attachments}
+            inlineParts={inlineParts}
+            original={original}
+            onAdaptable={onAdaptable}
+        />
+    );
+}
+
+function HtmlBody({
+    messageUid,
+    title,
+    html,
+    remoteAvailable,
+    attachments,
+    inlineParts,
+    original,
+    onAdaptable,
+}: {
+    messageUid: string;
+    title: string;
+    html: string;
+    /** The full message can be opened on its own from the server (it was not supplied by the caller). */
+    remoteAvailable: boolean;
+    attachments?: Attachment[];
+    inlineParts?: MimeAttachment[];
+    original: boolean;
+    onAdaptable?: (adaptable: boolean) => void;
+}) {
+    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 as { contentId?: string }).contentId ?? ""}`), inlineParts ? `parts:${inlineParts.length}` : ""].join("|");
+    const resolveCid = useMemo(() => makeCidResolver(attachments, inlineParts), [inlineKey]);
+    const prepared = useMemo(() => prepareBodyHtml(html, { resolveCid }), [html, resolveCid]);
+    const mode: FrameMode = 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<number | undefined>(undefined);
+    const [readyFor, setReadyFor] = useState<string | null>(null);
+    const [canvasAuthored, setCanvasAuthored] = useState(false);
+    const dispose = useRef<(() => void) | undefined>(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 (
+            <Alert>
+                This message is too large to show here.{" "}
+                {remoteAvailable && (
+                    <a href={apiUrl(`/mail/messages/${encodeURIComponent(messageUid)}/content`)} target="_blank" rel="noopener noreferrer" className="font-medium underline">
+                        Open it in its own tab
+                    </a>
+                )}
+            </Alert>
+        );
+    }
+
+    const ready = readyFor === frameKey;
+    const canvas = mode === "original" ? AUTHORED_CANVAS : surfaceCss;
+    const framed = mode !== "adapt" || canvasAuthored;
+    return (
+        <div className="relative rounded-md overflow-hidden" style={{ backgroundColor: canvas }}>
+            {!ready && <BodySkeleton />}
+            <iframe
+                key={frameKey}
+                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 }}
+            />
+        </div>
+    );
+}