@rapidmx/web-client 0.9.0 → 0.11.0

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>
+    );
+}

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

@@ -0,0 +1,174 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import ContactAvatar from "@rapidmx/react-shared/components/avatar/ContactAvatar.js";
+import Skeleton from "@rapidmx/react-shared/components/feedback/Skeleton.js";
+import type { MailAddressLike } from "@rapidmx/react-shared/mail/mailAddress.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,
+}: {
+    subject: string;
+    /** A line under the subject, such as "3 messages". */
+    meta?: React.ReactNode;
+    children?: React.ReactNode;
+}) {
+    return (
+        <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">
+            <h1 className="text-base sm:text-lg font-bold tracking-tight line-clamp-2 break-words">{subject}</h1>
+            {meta && <p className="text-xs sm:text-sm text-text-muted mt-0.5">{meta}</p>}
+            {children}
+        </header>
+    );
+}
+
+/** 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,
+}: {
+    unread?: boolean;
+    className?: string;
+    children: React.ReactNode;
+}) {
+    return (
+        <div className={["relative rounded-lg border border-border bg-surface backdrop-blur-sm shadow-sm overflow-hidden", className].join(" ")}>
+            <UnreadBar unread={unread} />
+            {children}
+        </div>
+    );
+}
+
+/**
+ * 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: React.CSSProperties = { 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 }: { from: MailAddressLike }) {
+    return <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,
+}: {
+    from: MailAddressLike;
+    date: string;
+    preview: React.ReactNode;
+    unread: boolean;
+    buttonProps: React.ButtonHTMLAttributes<HTMLButtonElement>;
+    buttonRef: (node: HTMLButtonElement | null) => void;
+    senderClassName: string;
+    dateClassName: string;
+}) {
+    return (
+        <CardShell unread={unread}>
+            <h2 style={BODY_FONT_STYLE}>
+                <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(" ")}
+                >
+                    <UnreadLabel unread={unread} />
+                    <SenderAvatar from={from} />
+                    <span className="flex-1 min-w-0">
+                        {/* On a phone the date drops under the sender rather than squeezing the name to nothing. */}
+                        <span className="flex flex-wrap items-baseline justify-between gap-x-2 text-sm">
+                            <MailAddress recipient={from} className={`${senderClassName} min-w-[13rem]! flex-1`} />
+                            <span className={["text-xs shrink-0", dateClassName].join(" ")}>{date}</span>
+                        </span>
+                        <span className="block text-xs text-text-muted truncate font-normal">{preview}</span>
+                    </span>
+                </button>
+            </h2>
+        </CardShell>
+    );
+}
+
+/** 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 (
+        <div aria-hidden="true" className="rounded-lg border border-border bg-surface shadow-sm overflow-hidden">
+            <div className="flex items-center gap-3 px-4 py-3">
+                <Skeleton width="w-10" height="h-10" className="rounded-full shrink-0" />
+                <div className="flex-1 flex flex-col gap-2">
+                    <Skeleton width="w-1/3" />
+                    <Skeleton width="w-1/2" height="h-3" />
+                </div>
+                <Skeleton width="w-16" height="h-3" />
+            </div>
+            <div className="flex flex-col gap-2.5 px-4 pb-4">
+                <Skeleton width="w-11/12" />
+                <Skeleton width="w-4/5" />
+                <Skeleton width="w-9/12" />
+            </div>
+        </div>
+    );
+}
+
+/**
+ * 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 }: { subject?: string; messageCount?: number }) {
+    return (
+        <div className="flex-1 min-w-0 min-h-0 flex flex-col">
+            {subject !== undefined ? (
+                <SubjectCard subject={subject || "(no subject)"} meta={messageCount > 1 ? `${messageCount} messages` : undefined} />
+            ) : (
+                <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">
+                    <Skeleton width="w-2/3" height="h-6" />
+                </div>
+            )}
+            <SkeletonCards messageCount={messageCount} />
+        </div>
+    );
+}
+
+/**
+ * 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 }: { messageCount?: number }) {
+    return (
+        <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">
+            <span className="sr-only">Loading the message</span>
+            {Array.from({ length: Math.min(3, Math.max(1, messageCount)) }, (_, index) => (
+                <CardSkeleton key={index} />
+            ))}
+        </div>
+    );
+}

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

@@ -0,0 +1,100 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiRequestError, apiUrl } from "@rapidmx/react-shared/util/api.js";
+import { Attachment, attachmentContentUrl } 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 };
+
+/** How many bodies are remembered for the session - a thread that is expanded, collapsed and expanded again does not ask the server twice. */
+const CACHE_LIMIT = 40;
+/** What the pane asks `/content` for. */
+export const ACCEPT = "text/html, text/plain;q=0.8";
+const cache = new Map<string, BodyContent>();
+
+/** Forgets every remembered body (sign-out, and the tests). */
+export function clearBodyContentCache(): void {
+    cache.clear();
+}
+
+/** The remembered body for a message at a version, if any. */
+export function cachedBodyContent(uid: string, version: number): BodyContent | undefined {
+    return cache.get(`${uid}:${version}`);
+}
+
+/**
+ * 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 async function fetchBodyContent(uid: string, version: number, signal?: AbortSignal): Promise<BodyContent> {
+    const cached = cachedBodyContent(uid, version);
+    if (cached) {
+        return cached;
+    }
+    // Says what it can show, as a document request would: the server answers with the sanitized HTML, or its plain-text fallback.
+    const res = await fetch(apiUrl(`/mail/messages/${encodeURIComponent(uid)}/content`), {
+        credentials: "include",
+        headers: { Accept: ACCEPT },
+        signal,
+    });
+    if (!res.ok) {
+        const contentType = res.headers.get("content-type") ?? "";
+        const body = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
+        throw new ApiRequestError((body && (body.message || body.error)) || res.statusText || "Could not load this message.", res.status, body?.code, body);
+    }
+    const text = await res.text();
+    const content: BodyContent = (res.headers.get("content-type") ?? "").toLowerCase().includes("text/html")
+        ? { kind: "html", html: text }
+        : { kind: "text", text };
+    if (cache.size >= CACHE_LIMIT) {
+        cache.delete(cache.keys().next().value as string);
+    }
+    cache.set(`${uid}:${version}`, content);
+    return content;
+}
+
+/** The largest inline image embedded into a body from a signed or encrypted message. */
+export const MAX_INLINE_IMAGE_BYTES = 5_000_000;
+const INLINE_IMAGE_TYPES = /^image\/(?:png|jpe?g|gif|webp|avif|bmp|svg\+xml)$/;
+
+function base64(bytes: Uint8Array): string {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(binary);
+}
+
+/** 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 function absoluteAttachmentUrl(uid: string): string {
+    return new URL(attachmentContentUrl(uid), window.location.href).href;
+}
+
+/** The CSP source that allows exactly this server's attachment URLs and nothing else. */
+export function attachmentSource(): string {
+    return new URL(apiUrl("/mail/attachments/"), window.location.href).href;
+}
+
+/**
+ * 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 function makeCidResolver(attachments: InlineCapable[] | undefined, parts: MimeAttachment[] | undefined): (contentId: string) => string | undefined {
+    return (contentId) => {
+        if (parts) {
+            const part = parts.find((candidate) => candidate.contentId === contentId);
+            const bytes = part && INLINE_IMAGE_TYPES.test(part.contentType) ? part.decode() : undefined;
+            return part && bytes && bytes.length <= MAX_INLINE_IMAGE_BYTES ? `data:${part.contentType};base64,${base64(bytes)}` : undefined;
+        }
+        const attachment = attachments?.find((candidate) => candidate.contentId === contentId);
+        return attachment ? absoluteAttachmentUrl(attachment.uid) : undefined;
+    };
+}