@rapidmx/web-client 0.9.0 → 0.11.0

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;

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

@@ -0,0 +1,84 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiRequestError, apiUrl } from "@rapidmx/react-shared/util/api.js";
+import { attachmentContentUrl } from "@rapidmx/react-shared/mail/mailApi.js";
+/** 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();
+/** Forgets every remembered body (sign-out, and the tests). */
+export function clearBodyContentCache() {
+    cache.clear();
+}
+/** The remembered body for a message at a version, if any. */
+export function cachedBodyContent(uid, version) {
+    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, version, signal) {
+    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 = (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);
+    }
+    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 = 5000000;
+const INLINE_IMAGE_TYPES = /^image\/(?:png|jpe?g|gif|webp|avif|bmp|svg\+xml)$/;
+function base64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(binary);
+}
+/** 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) {
+    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() {
+    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, parts) {
+    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;
+    };
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Turning a message's HTML - which is hostile until proven otherwise - into the fragment that goes into its display frame.
+ *
+ * Four independent layers stand between a mail and script execution, and this file is two of them:
+ *
+ * 1. the server's own allow-list sanitizer (restapi's `ScanPipeline`), before the body is stored;
+ * 2. **this file**: DOMPurify (react-shared's `sanitizeMessageBodyHtml()` - scripts, `on*` handlers, `javascript:` URLs, and every
+ * remote resource reference removed) followed by a second, structural pass of our own that removes what DOMPurify's defaults
+ * allow but a mail body never needs (forms, frames, media, SVG's active elements, every non-`http(s)`/`mailto`/`tel` link);
+ * 3. the frame's Content-Security-Policy (`frameDocument.ts`): no script, no object, no frame, no form, nothing fetched;
+ * 4. the frame's `sandbox` attribute, which never has `allow-scripts`, so nothing executes even if all of the above failed.
+ *
+ * Nothing here parses into the app's own document: every parse is a `DOMParser` document, which has no browsing context, runs no
+ * script and fetches nothing.
+ */
+/** A body longer than this many characters is not sanitized or shown inline - DOMPurify on megabytes of markup would freeze the tab. */
+export declare const MAX_BODY_HTML_LENGTH = 1500000;
+/** A body with more elements than this is not shown inline either: it cannot be laid out and adapted in a reasonable time. */
+export declare const MAX_BODY_ELEMENTS = 20000;
+export interface PreparedBody {
+    /** `too_large` means `html` is empty and the caller should offer the message on its own page instead. */
+    status: "ok" | "too_large";
+    /** The sanitized fragment: one wrapper `div.rr-msg` holding the message's own `<style>` elements and body. */
+    html: string;
+    /** The mail carries its own dark styles: a `color-scheme` meta or property, or a `prefers-color-scheme: dark` block. */
+    declaresDarkSupport: boolean;
+    /** How many `<img>`s point at an inline part (`cid:`) - the frame's CSP only needs an image source for the attachments then. */
+    inlineImages: number;
+}
+export interface PrepareOptions {
+    /** The URL an inline image's `cid:` reference stands for, or `undefined` when there is no such part. Only `data:` URIs of an
+     * image type and `http(s)` URLs are accepted; anything else is treated as unresolved. */
+    resolveCid?: (contentId: string) => string | undefined;
+}
+/** CSS with the constructs above neutralised. */
+export declare function sanitizeCss(css: string): string;
+/**
+ * Whether a mail's own markup declares that it supports a dark scheme: `<meta name="color-scheme">` naming dark,
+ * a `color-scheme` property naming dark in a stylesheet or a `style` attribute, or an `@media (prefers-color-scheme: dark)` block. Such a mail
+ * brings its own dark styles, which the display honours instead of adapting the mail's colours.
+ */
+export declare function declaresDarkSupport(doc: Document): boolean;
+/**
+ * The display fragment for a message's HTML - see the file's header. `too_large` (and an empty `html`) for a body over
+ * `MAX_BODY_HTML_LENGTH` characters or `MAX_BODY_ELEMENTS` elements; an empty fragment where there is no DOM to parse with.
+ */
+export declare function prepareBodyHtml(raw: string, options?: PrepareOptions): PreparedBody;

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

@@ -0,0 +1,267 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { sanitizeMessageBodyHtml } from "@rapidmx/react-shared/mail/messageBodySanitizer.js";
+import { parseColour } from "./color.js";
+/**
+ * Turning a message's HTML - which is hostile until proven otherwise - into the fragment that goes into its display frame.
+ *
+ * Four independent layers stand between a mail and script execution, and this file is two of them:
+ *
+ * 1. the server's own allow-list sanitizer (restapi's `ScanPipeline`), before the body is stored;
+ * 2. **this file**: DOMPurify (react-shared's `sanitizeMessageBodyHtml()` - scripts, `on*` handlers, `javascript:` URLs, and every
+ * remote resource reference removed) followed by a second, structural pass of our own that removes what DOMPurify's defaults
+ * allow but a mail body never needs (forms, frames, media, SVG's active elements, every non-`http(s)`/`mailto`/`tel` link);
+ * 3. the frame's Content-Security-Policy (`frameDocument.ts`): no script, no object, no frame, no form, nothing fetched;
+ * 4. the frame's `sandbox` attribute, which never has `allow-scripts`, so nothing executes even if all of the above failed.
+ *
+ * Nothing here parses into the app's own document: every parse is a `DOMParser` document, which has no browsing context, runs no
+ * script and fetches nothing.
+ */
+/** A body longer than this many characters is not sanitized or shown inline - DOMPurify on megabytes of markup would freeze the tab. */
+export const MAX_BODY_HTML_LENGTH = 1500000;
+/** A body with more elements than this is not shown inline either: it cannot be laid out and adapted in a reasonable time. */
+export const MAX_BODY_ELEMENTS = 20000;
+/** What a stylesheet or a `style` attribute may not contain, whatever the sanitizers before it did. */
+const STYLE_HAZARDS = [
+    // Fixed and sticky positioning could cover the frame (or, with a viewport-sized box, all of it) with a fake dialog.
+    [/position\s*:\s*(?:fixed|sticky)/gi, "position:relative"],
+    // A length in viewport-height units is the frame's own height, which is the message's height: `min-height: 100vh` would make the frame grow
+    // by what its content adds on every measurement. As plain pixels, nothing in the message depends on the size of the frame it is in.
+    [/(\d(?:\.\d+)?)\s*(?:[sld]?v(?:h|min|max|b))\b/gi, "$1px"],
+    [/expression\s*\(/gi, "none("],
+    [/-moz-binding\s*:/gi, "-x-binding:"],
+    [/behavior\s*:/gi, "x-behavior:"],
+    [/@import[^;]*;?/gi, ""],
+];
+/** CSS with the constructs above neutralised. */
+export function sanitizeCss(css) {
+    return STYLE_HAZARDS.reduce((text, [pattern, replacement]) => text.replace(pattern, replacement), css);
+}
+/** Elements removed together with everything inside them. */
+const REMOVED_ELEMENTS = new Set([
+    "script",
+    "noscript",
+    "object",
+    "embed",
+    "applet",
+    "iframe",
+    "frame",
+    "frameset",
+    "noembed",
+    "noframes",
+    "audio",
+    "video",
+    "source",
+    "track",
+    "canvas",
+    "dialog",
+    "template",
+    "slot",
+    "portal",
+    "bgsound",
+    "xml",
+    "base",
+    "meta",
+    "link",
+    "title",
+    "head",
+    "input",
+    "select",
+    "textarea",
+    "datalist",
+    "option",
+    "optgroup",
+    "math",
+    // SVG's active or reference-following elements: a script, a foreign document, a use of another element, and animation
+    // (which can set an `href` or an event handler's target).
+    "foreignobject",
+    "use",
+    "set",
+    "animate",
+    "animatemotion",
+    "animatetransform",
+]);
+/** Elements dropped but not their content: a message wrapped in an old ASP.NET `<form>` is still a message. */
+const UNWRAPPED_ELEMENTS = new Set(["form", "fieldset", "legend", "label", "button", "output", "marquee", "blink"]);
+/** Attributes no element of a mail may keep, on top of every `on*` handler. */
+const REMOVED_ATTRIBUTES = new Set([
+    "name",
+    "srcdoc",
+    "formaction",
+    "form",
+    "ping",
+    "nonce",
+    "is",
+    "slot",
+    "contenteditable",
+    "accesskey",
+    "tabindex",
+    "autofocus",
+    "draggable",
+    "srcset",
+    "crossorigin",
+    "integrity",
+    "referrerpolicy",
+    "http-equiv",
+    "xlink:href",
+]);
+/** The `href`s of a link a reader can follow: nothing that runs, nothing relative to this app, nothing that reads a local file. */
+const LINK_URL = /^(?:https?:\/\/|mailto:|tel:)/i;
+/** Inline images: raster types and SVG (an image context cannot run script or load anything), embedded as data. */
+const IMAGE_DATA_URI = /^data:image\/(?:png|jpe?g|gif|webp|avif|bmp|svg\+xml)[;,]/i;
+const CSS_ESCAPE = /\\([0-9a-f]{1,6})\s?|\\(.)/gi;
+/** Decodes CSS escapes, so a check for `color-scheme` cannot be dodged with `col\6fr-scheme`. */
+function unescapeCss(css) {
+    return css.replace(CSS_ESCAPE, (_match, hex, other) => hex ? String.fromCodePoint(Math.min(parseInt(hex, 16), 0x10ffff)) : other);
+}
+/**
+ * Whether a mail's own markup declares that it supports a dark scheme: `<meta name="color-scheme">` naming dark,
+ * a `color-scheme` property naming dark in a stylesheet or a `style` attribute, or an `@media (prefers-color-scheme: dark)` block. Such a mail
+ * brings its own dark styles, which the display honours instead of adapting the mail's colours.
+ */
+export function declaresDarkSupport(doc) {
+    const meta = doc.querySelector('meta[name="color-scheme" i]');
+    if (/\bdark\b/i.test(meta?.getAttribute("content") ?? "")) {
+        return true;
+    }
+    // An element's text is never null, and a `[style]` element always has the attribute.
+    const sheets = Array.from(doc.querySelectorAll("style"), (style) => style.textContent);
+    const inline = Array.from(doc.querySelectorAll("[style]"), (element) => element.getAttribute("style"));
+    return [...sheets, ...inline].some((css) => {
+        const text = unescapeCss(css);
+        return /color-scheme\s*:[^;}]*\bdark\b/i.test(text) || /prefers-color-scheme\s*:\s*dark/i.test(text);
+    });
+}
+/** A `bgcolor`/`text`/`link` attribute's value as an `rgb()` colour if we can read it - nothing else is ever copied into a style.
+ * `bgcolor="ffffff"` (no hash) is what old templates write and what a browser accepts. */
+function attributeColour(value) {
+    const text = (value ?? "").trim();
+    const colour = parseColour(/^[0-9a-f]{6}$/i.test(text) ? `#${text}` : text);
+    return colour && colour.a > 0 ? `rgb(${Math.round(colour.r)}, ${Math.round(colour.g)}, ${Math.round(colour.b)})` : undefined;
+}
+/** The wrapper `div.rr-msg`: the message's head `<style>`s first (DOMPurify drops a leading one as head content), then its body, with
+ * what a `<body bgcolor text link>` said carried over as the styles those attributes stand for. */
+function wrapMessage(doc) {
+    const wrapper = doc.createElement("div");
+    wrapper.className = "rr-msg";
+    for (const style of Array.from(doc.head.querySelectorAll("style"))) {
+        wrapper.appendChild(style.cloneNode(true));
+    }
+    const [background, text, link] = ["bgcolor", "text", "link"].map((name) => attributeColour(doc.body.getAttribute(name)));
+    // What the `<body>` said about itself moves to the wrapper, which stands in for it: its presentational colours first (a `style` beats
+    // them), then its own `style`, its classes (a template's stylesheet may select on them) and its direction.
+    const declarations = [background && `background-color:${background}`, text && `color:${text}`, doc.body.getAttribute("style")].filter(Boolean);
+    if (declarations.length > 0) {
+        wrapper.setAttribute("style", declarations.join(";"));
+    }
+    const bodyClass = doc.body.getAttribute("class");
+    if (bodyClass) {
+        wrapper.className += ` ${bodyClass}`;
+    }
+    const direction = doc.body.getAttribute("dir");
+    if (direction) {
+        wrapper.setAttribute("dir", direction);
+    }
+    if (link) {
+        const rule = doc.createElement("style");
+        rule.textContent = `:where(.rr-msg a:link){color:${link}}`;
+        wrapper.appendChild(rule);
+    }
+    wrapper.append(...Array.from(doc.body.childNodes));
+    return wrapper.outerHTML;
+}
+/** Replaces `element` with its children. */
+function unwrap(element) {
+    element.replaceWith(...Array.from(element.childNodes));
+}
+function hardenLink(element) {
+    const href = element.getAttribute("href")?.trim() ?? "";
+    if (LINK_URL.test(href)) {
+        element.setAttribute("href", href);
+        element.setAttribute("target", "_blank");
+        element.setAttribute("rel", "noopener noreferrer nofollow");
+    }
+    else {
+        // A link that goes nowhere a reader could safely follow stays as text, without the address it hid.
+        element.removeAttribute("href");
+        element.removeAttribute("target");
+    }
+}
+function hardenImage(element, options) {
+    const src = (element.getAttribute("src") ?? "").trim();
+    const inline = /^cid:/i.test(src);
+    const target = inline ? options.resolveCid?.(src.slice(4).replace(/^<|>$/g, "")) : src;
+    // Remote images are never fetched (they would tell the sender the message was read); an inline image resolves to an embedded
+    // image or to this server's own attachment URL, and one that doesn't resolve has nothing to show.
+    if (target !== undefined && (IMAGE_DATA_URI.test(target) || (inline && /^https?:\/\//i.test(target)))) {
+        element.setAttribute("src", target);
+    }
+    else {
+        element.removeAttribute("src");
+    }
+}
+/**
+ * The second, structural pass over already-sanitized markup: everything a mail body has no use for is removed or unwrapped, every
+ * link is forced to open in a new tab without an opener, and hazards in stylesheets are neutralised. Runs on a detached document.
+ */
+function harden(body, options) {
+    let inlineImages = 0;
+    const all = Array.from(body.querySelectorAll("*"));
+    for (const element of all) {
+        const tag = element.localName.toLowerCase();
+        if (REMOVED_ELEMENTS.has(tag)) {
+            element.remove();
+            continue;
+        }
+        if (UNWRAPPED_ELEMENTS.has(tag)) {
+            unwrap(element);
+            continue;
+        }
+        for (const attribute of Array.from(element.attributes)) {
+            const name = attribute.name.toLowerCase();
+            if (name.startsWith("on") || REMOVED_ATTRIBUTES.has(name)) {
+                element.removeAttribute(attribute.name);
+            }
+            else if (name === "style") {
+                element.setAttribute("style", sanitizeCss(attribute.value));
+            }
+        }
+        if (tag === "style") {
+            element.textContent = sanitizeCss(element.textContent);
+        }
+        else if (tag === "a" || tag === "area") {
+            hardenLink(element);
+        }
+        else if (tag === "img") {
+            if (/^cid:/i.test(element.getAttribute("src") ?? "")) {
+                inlineImages++;
+            }
+            hardenImage(element, options);
+        }
+    }
+    return { elements: all.length, inlineImages };
+}
+/**
+ * The display fragment for a message's HTML - see the file's header. `too_large` (and an empty `html`) for a body over
+ * `MAX_BODY_HTML_LENGTH` characters or `MAX_BODY_ELEMENTS` elements; an empty fragment where there is no DOM to parse with.
+ */
+export function prepareBodyHtml(raw, options = {}) {
+    const empty = { html: "", declaresDarkSupport: false, inlineImages: 0 };
+    if (raw.length > MAX_BODY_HTML_LENGTH) {
+        return { status: "too_large", ...empty };
+    }
+    if (typeof DOMParser === "undefined") {
+        return { status: "ok", ...empty };
+    }
+    const parsed = new DOMParser().parseFromString(raw, "text/html");
+    const darkSupport = declaresDarkSupport(parsed);
+    const sanitized = sanitizeMessageBodyHtml(wrapMessage(parsed));
+    const cleaned = new DOMParser().parseFromString(`<!doctype html><body>${sanitized}`, "text/html").body;
+    const { elements, inlineImages } = harden(cleaned, options);
+    if (elements > MAX_BODY_ELEMENTS) {
+        return { status: "too_large", ...empty };
+    }
+    return { status: "ok", html: cleaned.innerHTML, declaresDarkSupport: darkSupport, inlineImages };
+}

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

@@ -0,0 +1,63 @@
+/** A colour as the browser reports it: channels 0-255 and an alpha 0-1. */
+export interface Rgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** A colour with no transparency worth speaking of - what a contrast ratio is computed between. */
+export type Rgb = Pick<Rgba, "r" | "g" | "b">;
+/**
+ * Reads the colour notations a browser's computed style and an old-fashioned `bgcolor` attribute produce: `#rgb`, `#rgba`,
+ * `#rrggbb`, `#rrggbbaa`, `rgb()`/`rgba()` in the comma and the space syntax, `color(srgb ...)`, `transparent` and a few names.
+ * `undefined` for anything else (a gradient, `currentcolor`, `oklch()`), which callers treat as "unknown, leave it alone".
+ */
+export declare function parseColour(input: string | undefined | null): Rgba | undefined;
+/** `rgb(r, g, b)` for an opaque colour, `rgba(...)` otherwise - what goes into a generated stylesheet. */
+export declare function formatColour(colour: Rgba | Rgb): string;
+/** `top` painted over `bottom`, as the opaque colour that results. */
+export declare function composite(top: Rgba, bottom: Rgb): Rgb;
+/** WCAG relative luminance, 0 (black) to 1 (white). */
+export declare function luminance(colour: Rgb): number;
+/** WCAG contrast ratio between two opaque colours, 1 to 21. */
+export declare function contrastRatio(a: Rgb, b: Rgb): number;
+/** The lowest contrast ratio WCAG accepts for body text. */
+export declare const MIN_TEXT_CONTRAST = 4.5;
+export interface Hsl {
+    h: number;
+    s: number;
+    l: number;
+}
+export declare function rgbToHsl({ r, g, b }: Rgb): Hsl;
+export declare function hslToRgb({ h, s, l }: Hsl): Rgb;
+/** Whether two colours are the same to the eye's tolerance - what "unchanged" means when deciding to emit a rule. */
+export declare function sameColour(a: Rgb, b: Rgb): boolean;
+/**
+ * `colour` moved along its own hue and saturation - lighter over a dark background, darker over a light one - until it reaches
+ * `min` contrast against `background`. A colour that already has it is returned untouched; one that cannot get there (a mid-grey
+ * background) becomes whichever of white and black reads better.
+ */
+export declare function ensureContrast(colour: Rgb, background: Rgb, min?: number): Rgb;
+/** The theme a message is shown in: the opaque surface behind the body, its text and link colours, and whether it is a dark one. */
+export interface ThemeSurface {
+    background: Rgb;
+    text: Rgb;
+    link: Rgb;
+    dark: boolean;
+}
+/** Whichever of black and white reads better on `background`. */
+export declare function blackOrWhite(background: Rgb): Rgb;
+/**
+ * An authored text colour that cannot be read against the theme's background, adapted so it can. A neutral (black, white, a
+ * grey) is flipped to the other end of the scale - black becomes the theme's text colour, a dark grey a light one, and in a
+ * light theme white becomes dark text - by placing it between the theme's text and background colours according to how far it
+ * is from the one it must not be. Any other colour keeps its hue and saturation and only has its lightness moved, as little as
+ * it takes to reach 4.5:1 (`ensureContrast()`), so navy stays a navy and a brand red stays red. One that already reads is
+ * returned untouched.
+ */
+export declare function adaptForeground(colour: Rgb, surface: ThemeSurface): Rgb;
+/**
+ * The first colour in a computed `background-image` (a gradient's first stop): the best guess at what text over a gradient sits
+ * on. `undefined` for an image (`url(...)`) or anything with no colour in it.
+ */
+export declare function firstColourStop(backgroundImage: string): Rgba | undefined;