@rapidmx/web-client 0.9.0 → 0.11.0

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

@@ -0,0 +1,142 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { ThemeSurface } from "./color.js";
+import { bodyOf, documentElementOf, viewOf } from "./safeDocument.js";
+import { AdaptationResult, adaptDocument } from "./themeAdaptation.js";
+
+/**
+ * The parent's side of a message's display frame: once its document has loaded, adapt its colours to the theme, then follow its height
+ * for as long as it lives. This is where the frame is read, which works because the frame is same-origin and has no script; every read
+ * is made through the DOM's own accessors on the frame's document (never by a name the document could have clobbered).
+ */
+
+/** The tallest a message frame is allowed to grow, in CSS pixels: a hostile `height: 100000000px` must not build a layer the browser cannot paint. */
+export const MAX_FRAME_HEIGHT = 200_000;
+/** How many size changes one loaded document may report before the frame stops listening - a stylesheet that resizes itself in response to
+ * its own size (`height: 200vh`) would otherwise grow the frame on every observation, up to the cap. */
+export const MAX_RESIZE_REPORTS = 200;
+
+export interface FrameHandlers {
+    /** The document's content height in CSS pixels, whenever it changes (also once at load). */
+    onHeight: (height: number) => void;
+    /** The document is ready to show. `adaptation` is present when it was adapted to a theme. */
+    onReady: (adaptation?: AdaptationResult) => void;
+    /** Adapt to this surface before showing; absent for a document shown as it is. */
+    surface?: ThemeSurface;
+}
+
+function pixels(value: string): number {
+    const parsed = parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+
+/**
+ * The height of what the document displays: the bottom of its wrapper plus the body's own trailing margin, padding and border. Not
+ * `scrollHeight`, which is never less than the frame's own height, so a message could never shrink.
+ */
+export function measureFrameHeight(doc: Document): number {
+    const view = viewOf(doc);
+    const body = bodyOf(doc);
+    const wrapper = body?.firstElementChild;
+    if (!view || !body || !wrapper) {
+        return 0;
+    }
+    const style = view.getComputedStyle(body);
+    const trailing = pixels(style.marginBottom) + pixels(style.paddingBottom) + pixels(style.borderBottomWidth);
+    const bottom = wrapper.getBoundingClientRect().bottom + view.scrollY + trailing;
+    return Math.min(MAX_FRAME_HEIGHT, Math.max(0, Math.ceil(bottom)));
+}
+
+/** Re-sends a key pressed inside the frame to the app's own document, so the app's keyboard shortcuts work with focus in a message body
+ * (a frame keeps its own key events); if the app handled it, the frame's default action is prevented too. */
+export function forwardKeyDown(event: KeyboardEvent, target: Document): void {
+    const copy = new KeyboardEvent("keydown", {
+        key: event.key,
+        code: event.code,
+        ctrlKey: event.ctrlKey,
+        shiftKey: event.shiftKey,
+        altKey: event.altKey,
+        metaKey: event.metaKey,
+        repeat: event.repeat,
+        bubbles: true,
+        cancelable: true,
+    });
+    if (!target.dispatchEvent(copy)) {
+        event.preventDefault();
+    }
+}
+
+/**
+ * Starts controlling `iframe`'s freshly loaded document. Returns a function that stops everything (observers, listeners, an adaptation
+ * still in progress); call it before the frame reloads and when it goes away. Returns a no-op for a frame with no readable document.
+ */
+export function controlFrame(iframe: HTMLIFrameElement, handlers: FrameHandlers): () => void {
+    const doc = iframe.contentDocument;
+    const view = doc ? viewOf(doc) : null;
+    const body = doc ? bodyOf(doc) : null;
+    const wrapper = body?.firstElementChild;
+    if (!doc || !view || !body || !wrapper) {
+        return () => undefined;
+    }
+    let disposed = false;
+    let reports = 0;
+    const measure = () => {
+        if (!disposed) {
+            handlers.onHeight(measureFrameHeight(doc));
+        }
+    };
+    const onKeyDown = (event: KeyboardEvent) => forwardKeyDown(event, iframe.ownerDocument);
+    doc.addEventListener("keydown", onKeyDown);
+
+    measure();
+    // The frame's own ResizeObserver where it has one (the observations then run in its own rendering steps), else this window's.
+    const Observer: typeof ResizeObserver | undefined = view.ResizeObserver ?? (typeof ResizeObserver === "undefined" ? undefined : ResizeObserver);
+    let observer: ResizeObserver | undefined;
+    const onWindowResize = () => measure();
+    if (Observer) {
+        observer = new Observer(() => {
+            if (++reports > MAX_RESIZE_REPORTS) {
+                observer?.disconnect();
+                return;
+            }
+            measure();
+        });
+        for (const element of [wrapper, body, documentElementOf(doc)]) {
+            observer.observe(element);
+        }
+    } else {
+        window.addEventListener("resize", onWindowResize);
+    }
+
+    // Paper is not a dark surface: while the page is being printed the message goes back to the colours it was written with, and is adapted
+    // again afterwards.
+    let revert: (() => void) | undefined;
+    let reapply: (() => void) | undefined;
+    const onBeforePrint = () => revert?.();
+    const onAfterPrint = () => reapply?.();
+    window.addEventListener("beforeprint", onBeforePrint);
+    window.addEventListener("afterprint", onAfterPrint);
+
+    if (handlers.surface) {
+        void adaptDocument(doc, handlers.surface, { isCancelled: () => disposed }).then((result) => {
+            if (!disposed) {
+                ({ revert, reapply } = result);
+                measure();
+                handlers.onReady(result);
+            }
+        });
+    } else {
+        handlers.onReady();
+    }
+
+    return () => {
+        disposed = true;
+        window.removeEventListener("beforeprint", onBeforePrint);
+        window.removeEventListener("afterprint", onAfterPrint);
+        observer?.disconnect();
+        window.removeEventListener("resize", onWindowResize);
+        doc.removeEventListener("keydown", onKeyDown);
+    };
+}

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

@@ -0,0 +1,123 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * The document a message's body is displayed in: the `srcdoc` of a sandboxed iframe.
+ *
+ * **Why an iframe, and why `allow-same-origin`.** The body is untrusted HTML. It must never be inserted into the app's own DOM
+ * (a sanitizer bug there is script in the app's origin, next to the unlocked mail keys), so it lives in a frame. A frame with
+ * `sandbox=""` has an opaque origin and cannot be measured from outside, which is what made every message a full-height scrolling
+ * box. `allow-same-origin` (and nothing else that runs code - never `allow-scripts`) lets the *app* read the document's height and
+ * adapt its colours, and is safe because a document with no script can neither use the origin nor reach the app: there is no code in
+ * the frame to do it. That claim rests on four layers, each enough to stop a script on its own (server sanitizer, `bodyHtml.ts`,
+ * the CSP below, the missing `allow-scripts`), and is proven against a corpus of hostile mail in a real browser
+ * (`.claude/NOTES.md`, 2026-09-21).
+ *
+ * The rest of the sandbox: `allow-popups` and `allow-popups-to-escape-sandbox` only so a link the reader clicks can open in a new tab
+ * (every link is `target=_blank rel="noopener noreferrer nofollow"`, and no script can open one uninvited); no `allow-forms`,
+ * `allow-top-navigation`, `allow-modals`, `allow-downloads`, `allow-pointer-lock` or `allow-presentation`.
+ */
+export const FRAME_SANDBOX = "allow-same-origin allow-popups allow-popups-to-escape-sandbox";
+
+/**
+ * The frame's Content-Security-Policy. Nothing is loaded from anywhere: images are `data:` URIs and, for a message's inline parts,
+ * this server's own attachment URLs (`attachmentSource`); remote images, fonts, stylesheets, frames and every other fetch are
+ * refused, as they are today by the server's own header for `/content` (`default-src 'none'; img-src data: cid:; style-src
+ * 'unsafe-inline'; sandbox`). Inline styles are allowed because mail is styled that way; nothing else inline is (no script at all).
+ */
+export function frameCsp(attachmentSource?: string): string {
+    // A source is a URL prefix (`https://host/api/mail/attachments/`); anything that is not one is left out rather than trusted, as this
+    // string is written into an attribute.
+    const source = attachmentSource && /^https?:\/\/[\w.:@-]+(?:\/[\w./%~-]*)?$/.test(attachmentSource) ? attachmentSource : undefined;
+    return [
+        "default-src 'none'",
+        "script-src 'none'",
+        "object-src 'none'",
+        "frame-src 'none'",
+        "form-action 'none'",
+        "base-uri 'none'",
+        "style-src 'unsafe-inline'",
+        `img-src data:${source ? ` ${source}` : ""}`,
+        "font-src data:",
+    ].join("; ");
+}
+
+/** How a message is being shown: as the theme dictates (`adapt`), as its author wrote it (`original`), or - a message that carries its
+ * own dark styles - as those styles say (`native`). */
+export type FrameMode = "adapt" | "original" | "native";
+
+export interface FrameOptions {
+    mode: FrameMode;
+    /** The app's scheme: what `prefers-color-scheme` means inside the frame (it would otherwise be the operating system's). */
+    scheme: "light" | "dark";
+    /** The theme's opaque body surface and text colour, as `rgb()` - the defaults a native-dark message starts from. */
+    surface: string;
+    text: string;
+    /** The CSP `img-src` source for this server's attachment URLs, when the message has inline images that point there. */
+    attachmentSource?: string;
+}
+
+/** The colour the adaptation pass reads to tell text nobody coloured from text somebody did (`themeAdaptation.ts`). */
+export const TEXT_SENTINEL = "rgb(1, 2, 3)";
+/** The same for a link nobody coloured. */
+export const LINK_SENTINEL = "rgb(1, 2, 4)";
+
+const ALWAYS_TRUE = "(min-width: 0px)";
+const ALWAYS_FALSE = "(max-width: -1px)";
+
+/**
+ * Makes `prefers-color-scheme` mean the app's scheme inside a message's stylesheets. A browser answers it with the operating
+ * system's preference, which is not what the reader chose in Appearance; each occurrence becomes a media condition that is always
+ * true or always false. Only `<style>` contents are rewritten.
+ */
+export function rewriteColourSchemeQueries(html: string, scheme: "light" | "dark"): string {
+    return html.replace(/(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi, (_match, open: string, css: string, close: string) => {
+        const rewritten = css.replace(/\(\s*prefers-color-scheme\s*:\s*(dark|light)\s*\)/gi, (_condition, wanted: string) =>
+            wanted.toLowerCase() === scheme ? ALWAYS_TRUE : ALWAYS_FALSE,
+        );
+        return open + rewritten + close;
+    });
+}
+
+/** Layout rules every mode shares: the document is exactly as tall as its content, never scrolls itself, and a wide table scrolls
+ * inside the message instead of widening the pane. */
+const LAYOUT_CSS = `
+html{height:auto!important;min-height:0!important;overflow:hidden!important;font:14px/1.5 system-ui,-apple-system,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif}
+body{height:auto!important;min-height:0!important}
+#rr-body{box-sizing:border-box;position:relative;overflow-x:auto;overflow-y:hidden;overflow-wrap:break-word}
+#rr-body img{max-width:100%;height:auto}
+#rr-body pre{white-space:pre-wrap}
+@media print{html{overflow:visible!important}}
+`;
+
+function modeCss(options: FrameOptions): string {
+    const { mode, scheme, surface, text } = options;
+    if (mode === "adapt") {
+        // The sentinels are what the adaptation pass reads to tell what a message's author coloured from what it inherited; the pass
+        // then replaces them, so they never show. Zero specificity: any rule of the message beats them.
+        return `:where(html){color-scheme:${scheme}}:where(body){margin:0}:where(:root){color:${TEXT_SENTINEL}}:where(a:link,a:visited){color:${LINK_SENTINEL}}`;
+    }
+    if (mode === "native") {
+        return `:where(html){color-scheme:${scheme};background-color:${surface};color:${text}}:where(body){margin:0}`;
+    }
+    // As its author wrote it: a light document, as a browser in a light scheme shows it - with the browser's own 8px page margin. Zero
+    // specificity, so the message's own rules win.
+    return ":where(html){color-scheme:light}:where(body){margin:8px}";
+}
+
+/**
+ * The complete document for a message: the CSP as the very first element of the head, the layout rules, the mode's defaults and the
+ * sanitized fragment inside `#rr-body`. `fragment` must come out of `prepareBodyHtml()`.
+ */
+export function buildFrameDocument(fragment: string, options: FrameOptions): string {
+    const body = rewriteColourSchemeQueries(fragment, options.mode === "original" ? "light" : options.scheme);
+    return [
+        "<!doctype html>",
+        '<html lang="en"><head><meta charset="utf-8">',
+        `<meta http-equiv="Content-Security-Policy" content="${frameCsp(options.attachmentSource)}">`,
+        `<style>${LAYOUT_CSS}${modeCss(options)}</style></head>`,
+        `<body><div id="rr-body">${body}</div></body></html>`,
+    ].join("");
+}

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

@@ -0,0 +1,24 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Reads off a message's display document that a hostile message cannot redirect. On a `Document` the named properties of `<img name=...>`,
+ * `<form name=...>` and friends *override* the built-in ones (`<img name="body">` makes `document.body` that image), so anything reading
+ * `doc.body` from the app would be handed the message's element. Every such element and attribute is stripped before display
+ * (`bodyHtml.ts`), and these accessors - the platform's own getters, taken from this window's `Document.prototype` and applied to the
+ * frame's document - are the second guard: they answer with the real thing whatever the document contains.
+ */
+type DocumentGetter = "documentElement" | "body" | "defaultView";
+
+const getters: Partial<Record<DocumentGetter, () => unknown>> = {};
+
+function read<T>(doc: Document, name: DocumentGetter): T {
+    getters[name] ??= Object.getOwnPropertyDescriptor(Document.prototype, name)!.get as () => unknown;
+    return getters[name].call(doc) as T;
+}
+
+export const documentElementOf = (doc: Document): HTMLElement => read<HTMLElement>(doc, "documentElement");
+export const bodyOf = (doc: Document): HTMLElement | null => read<HTMLElement | null>(doc, "body");
+export const viewOf = (doc: Document): (Window & typeof globalThis) | null => read<(Window & typeof globalThis) | null>(doc, "defaultView");

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

@@ -0,0 +1,221 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import {
+    MIN_TEXT_CONTRAST,
+    Rgb,
+    ThemeSurface,
+    adaptForeground,
+    blackOrWhite,
+    composite,
+    contrastRatio,
+    ensureContrast,
+    firstColourStop,
+    formatColour,
+    luminance,
+    parseColour,
+    sameColour,
+} from "./color.js";
+import { LINK_SENTINEL, TEXT_SENTINEL } from "./frameDocument.js";
+import { documentElementOf, viewOf } from "./safeDocument.js";
+
+/**
+ * Makes a message take the app's theme wherever its author left the colours to the reader, and leaves it as authored wherever the
+ * author chose them. Runs in the parent against the display frame's document (which is same-origin only because no script can run
+ * there - see `frameDocument.ts`); reads with `getComputedStyle` and writes nothing but `color` on individual elements, as inline
+ * `!important` declarations built from numbers, never from text of the message.
+ *
+ * **Authored or inherited, without parsing CSS.** The frame's base stylesheet gives the root a sentinel text colour, and unvisited/visited
+ * links another, at zero specificity, so any rule of the message beats them. An element whose computed `color` still equals the sentinel
+ * was never coloured by the message (its text is *unauthored*); any other value - black included - was chosen by somebody. A background
+ * is authored when its computed colour is not transparent or its image is not `none`.
+ *
+ * **What each text becomes**, from its effective background (the nearest authored background up the tree, composited over what is beneath
+ * it, else the theme's surface):
+ * - unauthored text on the theme surface: the theme's text colour; an unauthored link: the theme's link colour;
+ * - authored text on the theme surface: kept if it reads (4.5:1), else adapted (`adaptForeground()`: black becomes white, navy a lighter
+ * navy) - the symmetric case in a light theme included;
+ * - anything on an authored, opaque background (a white cell, a dark banner, a gradient): that region is shown as authored - its own text
+ * colours untouched - except unauthored text, which must not inherit the theme's colour (white on white) and gets black or white by
+ * contrast with that background (black when the background is a picture or a gradient with no first colour to judge by);
+ * - a semi-transparent authored background is composited over what is under it and treated like the theme surface, since how it looks
+ * depends on the theme.
+ *
+ * Every element ends with exactly its target colour: an element is written to only when inheritance would not give it that (which includes
+ * one that may carry a declaration of its own). Images, SVG and everything else that is not text are untouched.
+ */
+
+export interface AdaptationResult {
+    /** Elements examined. */
+    elements: number;
+    /** Elements given an inline colour. */
+    written: number;
+    /** Whether adapting makes a visible difference from the message as authored: a text colour changed a lot, or the canvas is the theme's
+     * dark surface rather than the white a message is authored on. False for e.g. a bare message in a light theme. */
+    material: boolean;
+    /** `<html>` or `<body>` carries an authored background: the whole frame takes it. */
+    authoredCanvas: boolean;
+    /** Stopped because `isCancelled()` said the frame was gone. */
+    cancelled: boolean;
+    /** Puts every colour back as the message had it (paper is not a dark surface: the frame does this for printing). */
+    revert: () => void;
+    /** Puts the adapted colours back after `revert()`. */
+    reapply: () => void;
+}
+
+export interface AdaptOptions {
+    /** How long one slice of work may take before the pass gives the browser a turn. */
+    sliceMs?: number;
+    isCancelled?: () => boolean;
+    /** For tests. */
+    now?: () => number;
+    yieldToBrowser?: () => Promise<void>;
+}
+
+/** Not examined, nor are their children. `head` and its contents never render; `svg` is left as drawn. */
+const SKIPPED = new Set(["head", "script", "style", "title", "meta", "link", "template", "svg", "img"]);
+
+/** What travels down the tree: the effective background, whether it is an authored opaque one, and the colour the parent ends up with. */
+interface Context {
+    background: Rgb;
+    authored: boolean;
+    unknown: boolean;
+    parentColour: Rgb;
+}
+
+/** Classic link blue - what an unauthored link looks like in an authored region, before contrast. */
+const DEFAULT_LINK: Rgb = { r: 0, g: 0, b: 238 };
+/** How much lighter or darker (in luminance) an adapted text colour must be than the original for the difference to be worth an opt-out. */
+const MATERIAL_LUMINANCE_SHIFT = 0.3;
+/** A surface at least this luminous is close enough to the white a message is authored on that it is not, by itself, an adaptation. */
+const LIGHT_SURFACE = 0.85;
+
+/** The elements whose background is the message's canvas: `<html>`, `<body>`, and the wrapper that stands in for the message's own `<body>`. */
+function standsForCanvas(element: HTMLElement, root: HTMLElement): boolean {
+    return element === root || element.localName === "body" || element.parentElement?.id === "rr-body";
+}
+
+function noop(): void {
+    // Nothing was written, so there is nothing to put back.
+}
+
+function nextTurn(): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+/** The colour a `color` value comes to over a background: opaque, alpha composited. */
+function opaque(css: string, over: Rgb): Rgb | undefined {
+    const colour = parseColour(css);
+    return colour ? composite(colour, over) : undefined;
+}
+
+/**
+ * Adapts `doc` to `surface` - see the file's header. Time-sliced (`sliceMs`, then a turn for the browser) so a very large message never
+ * blocks the page; the frame stays hidden until this resolves, so nothing unreadable is ever shown.
+ */
+export async function adaptDocument(doc: Document, surface: ThemeSurface, options: AdaptOptions = {}): Promise<AdaptationResult> {
+    const { sliceMs = 12, isCancelled = () => false, now = () => performance.now(), yieldToBrowser = nextTurn } = options;
+    const view = viewOf(doc);
+    const result: AdaptationResult = { elements: 0, written: 0, material: false, authoredCanvas: false, cancelled: false, revert: noop, reapply: noop };
+    if (!view) {
+        return result;
+    }
+    const root = documentElementOf(doc);
+    // Every read happens before the first write: a write changes what its descendants inherit, which would make every child of an element
+    // we coloured look authored.
+    const writes: { element: HTMLElement; colour: string }[] = [];
+    const stack: { element: HTMLElement; context: Context }[] = [
+        { element: root, context: { background: surface.background, authored: false, unknown: false, parentColour: surface.text } },
+    ];
+    let sliceStart = now();
+    while (stack.length > 0) {
+        if (now() - sliceStart > sliceMs) {
+            await yieldToBrowser();
+            if (isCancelled()) {
+                result.cancelled = true;
+                return result;
+            }
+            sliceStart = now();
+        }
+        const { element, context } = stack.pop()!;
+        if (SKIPPED.has(element.localName.toLowerCase())) {
+            continue;
+        }
+        result.elements++;
+        const style = view.getComputedStyle(element);
+        let { background, authored, unknown } = context;
+        const own = parseColour(style.backgroundColor);
+        const image = style.backgroundImage;
+        if (image && image !== "none") {
+            const stop = firstColourStop(image) ?? (own && own.a > 0 ? own : undefined);
+            authored = true;
+            unknown = !stop;
+            background = stop ? composite(stop, background) : background;
+            result.authoredCanvas ||= standsForCanvas(element, root);
+        } else if (own && own.a >= 0.98) {
+            authored = true;
+            unknown = false;
+            background = composite(own, background);
+            result.authoredCanvas ||= standsForCanvas(element, root);
+        } else if (own && own.a > 0) {
+            background = composite(own, background);
+        }
+
+        const declared = style.color;
+        const original = opaque(declared, background);
+        let target: { rgb: Rgb; css: string } | undefined;
+        if (declared === TEXT_SENTINEL) {
+            const rgb = authored ? (unknown ? { r: 0, g: 0, b: 0 } : blackOrWhite(background)) : ensureContrast(surface.text, background);
+            target = { rgb, css: formatColour(rgb) };
+        } else if (declared === LINK_SENTINEL) {
+            const rgb = authored ? (unknown ? DEFAULT_LINK : ensureContrast(DEFAULT_LINK, background)) : ensureContrast(surface.link, background);
+            target = { rgb, css: formatColour(rgb) };
+        } else if (original && !authored) {
+            // Authored text on the theme's surface: it stays if it reads, else it is adapted.
+            const readable = contrastRatio(original, background) >= MIN_TEXT_CONTRAST;
+            const rgb = readable ? original : adaptForeground(original, { ...surface, background });
+            target = { rgb, css: readable ? declared : formatColour(rgb) };
+        } else if (original) {
+            // Authored text on an authored background: as its author had it.
+            target = { rgb: original, css: declared };
+        }
+        let parentColour = context.parentColour;
+        if (target) {
+            // An element is written to unless inheritance already gives it its target: the parent must end with that colour, and an element
+            // that may carry a declaration of its own (an authored colour, a link - the sentinel is a rule on it - and the root) must not
+            // be declaring a different one. Text nobody coloured inherits and has nothing of its own to override.
+            const ownDeclaration = declared !== TEXT_SENTINEL || element === root;
+            if (!sameColour(target.rgb, context.parentColour) || (ownDeclaration && !sameColour(target.rgb, original ?? target.rgb))) {
+                writes.push({ element, colour: target.css });
+            }
+            if (original && Math.abs(luminance(target.rgb) - luminance(original)) > MATERIAL_LUMINANCE_SHIFT) {
+                result.material = true;
+            }
+            parentColour = target.rgb;
+        }
+        for (const child of Array.from(element.children).reverse()) {
+            stack.push({ element: child as HTMLElement, context: { background, authored, unknown, parentColour } });
+        }
+    }
+    // What each element had inline before, so the writes can be taken back (a message may carry its own inline colour).
+    const before = writes.map(({ element }) => ({ value: element.style.getPropertyValue("color"), priority: element.style.getPropertyPriority("color") }));
+    result.reapply = () => {
+        for (const { element, colour } of writes) {
+            element.style.setProperty("color", colour, "important");
+        }
+    };
+    result.revert = () => {
+        writes.forEach(({ element }, index) => {
+            if (before[index].value) {
+                element.style.setProperty("color", before[index].value, before[index].priority);
+            } else {
+                element.style.removeProperty("color");
+            }
+        });
+    };
+    result.reapply();
+    result.written = writes.length;
+    result.material ||= !result.authoredCanvas && luminance(surface.background) < LIGHT_SURFACE;
+    return result;
+}

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

@@ -0,0 +1,90 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import type { ResolvedTheme } from "../../../appearance/resolvedTheme.js";
+import { Rgb, Rgba, ThemeSurface, composite, formatColour, parseColour } from "./color.js";
+
+/** The palette used where the page's own tokens cannot be read (no DOM, or a stylesheet without them): the app's built-in schemes. */
+export const DEFAULT_SURFACES: Record<ResolvedTheme, ThemeSurface> = {
+    light: { background: { r: 255, g: 255, b: 255 }, text: { r: 28, g: 37, b: 38 }, link: { r: 20, g: 138, b: 128 }, dark: false },
+    dark: { background: { r: 27, g: 32, b: 34 }, text: { r: 238, g: 242, b: 243 }, link: { r: 45, g: 212, b: 191 }, dark: true },
+};
+
+/** The page's own CSS variables a message is adapted to. Read from the document, so a branding palette or a user's own Appearance colours are followed. */
+const TOKENS = {
+    surface: "--rr-color-surface",
+    page: "--rr-color-bg",
+    text: "--rr-color-text",
+    link: "--rr-color-primary-dark",
+} as const;
+
+/** The colour a CSS custom property resolves to, by asking the browser what a probe element painted with it comes to (which also
+ * resolves `var()` chains and colour functions); `undefined` when it isn't defined or isn't a colour. */
+function resolveToken(probe: HTMLElement, name: string): Rgba | undefined {
+    probe.style.color = `var(${name}, transparent)`;
+    const colour = parseColour(getComputedStyle(probe).color);
+    return colour && colour.a > 0 ? colour : undefined;
+}
+
+/**
+ * The theme a message is shown in, read from the page's own tokens: the surface behind the body composited to an opaque colour (a
+ * translucent surface over a photo would make text unreadable, so the body area is always painted with this opaque one), the text
+ * colour and the link colour. Falls back to the built-in scheme for anything the page doesn't define.
+ */
+export function readThemeSurface(theme: ResolvedTheme): ThemeSurface {
+    const fallback = DEFAULT_SURFACES[theme];
+    if (typeof document === "undefined" || !document.body) {
+        return fallback;
+    }
+    const probe = document.createElement("span");
+    probe.style.display = "none";
+    document.body.appendChild(probe);
+    try {
+        const page = resolveToken(probe, TOKENS.page);
+        const surface = resolveToken(probe, TOKENS.surface);
+        const underlay: Rgb = page ? composite(page, fallback.background) : fallback.background;
+        const text = resolveToken(probe, TOKENS.text);
+        const link = resolveToken(probe, TOKENS.link);
+        return {
+            dark: fallback.dark,
+            background: surface ? composite(surface, underlay) : underlay,
+            text: text ? composite(text, underlay) : fallback.text,
+            link: link ? composite(link, underlay) : fallback.link,
+        };
+    } finally {
+        probe.remove();
+    }
+}
+
+/** A string that changes exactly when the surface does - what a frame is keyed on. */
+export function surfaceKey(surface: ThemeSurface): string {
+    return [surface.background, surface.text, surface.link].map(formatColour).join("|") + (surface.dark ? "|dark" : "|light");
+}
+
+/**
+ * The theme surface for `theme`, kept current: re-read when the scheme changes and when the page's own colours are changed at runtime
+ * (Appearance sets `data-theme` on `<html>` and writes the user's colours into a `<style>` in the head). The identity only changes when a colour does.
+ */
+export function useThemeSurface(theme: ResolvedTheme): ThemeSurface {
+    const [surface, setSurface] = useState(() => readThemeSurface(theme));
+    useEffect(() => {
+        const update = () =>
+            setSurface((previous) => {
+                const next = readThemeSurface(theme);
+                return surfaceKey(previous) === surfaceKey(next) ? previous : next;
+            });
+        update();
+        if (typeof MutationObserver === "undefined") {
+            return;
+        }
+        const observer = new MutationObserver(update);
+        observer.observe(document.documentElement, { attributes: true, attributeFilter: ["style", "class", "data-theme"] });
+        // The Appearance provider writes the user's own colours into a `<style>` element in the head, whose text is replaced when they change.
+        observer.observe(document.head, { childList: true, subtree: true, characterData: true, attributes: true });
+        return () => observer.disconnect();
+    }, [theme]);
+    // The render that first sees a new scheme must not use the previous one's colours (the effect above corrects the state after it).
+    return surface.dark === (theme === "dark") ? surface : readThemeSurface(theme);
+}

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

@@ -0,0 +1,38 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useState } from "react";
+
+/** Messages the reader chose to see exactly as authored rather than adapted to the theme, for the life of the tab. */
+const original = new Set<string>();
+
+/** Whether the reader asked to see `uid` as authored. */
+export function isViewedOriginal(uid: string): boolean {
+    return original.has(uid);
+}
+
+/** Forgets every choice (the tests). */
+export function clearViewedOriginal(): void {
+    original.clear();
+}
+
+/**
+ * The per-message "View original" choice: `false` (follow the theme) until the reader flips it, then remembered for the session so
+ * collapsing and expanding a message, or coming back to it, keeps the choice.
+ */
+export function useViewOriginal(uid: string): [boolean, (value: boolean) => void] {
+    const [value, setValue] = useState(() => isViewedOriginal(uid));
+    const update = useCallback(
+        (next: boolean) => {
+            if (next) {
+                original.add(uid);
+            } else {
+                original.delete(uid);
+            }
+            setValue(next);
+        },
+        [uid],
+    );
+    return [value, update];
+}