@rapidmx/web-client 0.10.0 → 0.12.0

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

@@ -0,0 +1,245 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** 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">;
+
+/** The handful of named colours a `bgcolor`/`text` attribute is realistically written with. Anything else is not guessed at. */
+const NAMED_COLOURS: Record<string, [number, number, number]> = {
+    white: [255, 255, 255],
+    black: [0, 0, 0],
+    red: [255, 0, 0],
+    green: [0, 128, 0],
+    blue: [0, 0, 255],
+    yellow: [255, 255, 0],
+    gray: [128, 128, 128],
+    grey: [128, 128, 128],
+    silver: [192, 192, 192],
+    navy: [0, 0, 128],
+    teal: [0, 128, 128],
+    maroon: [128, 0, 0],
+    purple: [128, 0, 128],
+    orange: [255, 165, 0],
+    lime: [0, 255, 0],
+    aqua: [0, 255, 255],
+    fuchsia: [255, 0, 255],
+    olive: [128, 128, 0],
+};
+
+function clamp(value: number, min: number, max: number): number {
+    return Math.min(max, Math.max(min, value));
+}
+
+/** One `rgb()` channel: a number 0-255, or a percentage of it. */
+function channel(token: string): number {
+    return token.endsWith("%") ? (parseFloat(token) / 100) * 255 : parseFloat(token);
+}
+
+/** An alpha: a number 0-1, or a percentage. */
+function alpha(token: string | undefined): number {
+    if (token === undefined) {
+        return 1;
+    }
+    return token.endsWith("%") ? parseFloat(token) / 100 : parseFloat(token);
+}
+
+/**
+ * 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 function parseColour(input: string | undefined | null): Rgba | undefined {
+    const text = (input ?? "").trim().toLowerCase();
+    if (text === "transparent") {
+        return { r: 0, g: 0, b: 0, a: 0 };
+    }
+    if (text in NAMED_COLOURS) {
+        const [r, g, b] = NAMED_COLOURS[text];
+        return { r, g, b, a: 1 };
+    }
+    const hex = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.exec(text)?.[1];
+    if (hex) {
+        const full = hex.length <= 4 ? [...hex].map((c) => c + c).join("") : hex;
+        const [r, g, b, a] = [0, 2, 4, 6].map((i) => (full.length > i ? parseInt(full.slice(i, i + 2), 16) : 255));
+        return { r, g, b, a: a / 255 };
+    }
+    const functional = /^(rgba?|color)\(\s*(?:srgb\s+)?([^)]*)\)$/.exec(text);
+    if (functional) {
+        const parts = functional[2].split(/[\s,/]+/).filter(Boolean);
+        if (parts.length < 3 || parts.length > 4 || parts.some((part) => !/^[-+]?(\d+\.?\d*|\.\d+)%?$/.test(part))) {
+            return undefined;
+        }
+        const scale = functional[1] === "color" ? 255 : 1;
+        const [r, g, b] = parts.slice(0, 3).map((part) => clamp(channel(part) * scale, 0, 255));
+        return { r, g, b, a: clamp(alpha(parts[3]), 0, 1) };
+    }
+    return undefined;
+}
+
+/** `rgb(r, g, b)` for an opaque colour, `rgba(...)` otherwise - what goes into a generated stylesheet. */
+export function formatColour(colour: Rgba | Rgb): string {
+    const { r, g, b } = colour;
+    const a = "a" in colour ? colour.a : 1;
+    const rgb = [r, g, b].map((value) => Math.round(clamp(value, 0, 255))).join(", ");
+    return a >= 1 ? `rgb(${rgb})` : `rgba(${rgb}, ${Math.round(a * 1000) / 1000})`;
+}
+
+/** `top` painted over `bottom`, as the opaque colour that results. */
+export function composite(top: Rgba, bottom: Rgb): Rgb {
+    return {
+        r: top.r * top.a + bottom.r * (1 - top.a),
+        g: top.g * top.a + bottom.g * (1 - top.a),
+        b: top.b * top.a + bottom.b * (1 - top.a),
+    };
+}
+
+function linear(value: number): number {
+    const c = value / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+/** WCAG relative luminance, 0 (black) to 1 (white). */
+export function luminance(colour: Rgb): number {
+    return 0.2126 * linear(colour.r) + 0.7152 * linear(colour.g) + 0.0722 * linear(colour.b);
+}
+
+/** WCAG contrast ratio between two opaque colours, 1 to 21. */
+export function contrastRatio(a: Rgb, b: Rgb): number {
+    const [lighter, darker] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+
+/** The lowest contrast ratio WCAG accepts for body text. */
+export const MIN_TEXT_CONTRAST = 4.5;
+
+export interface Hsl {
+    h: number;
+    s: number;
+    l: number;
+}
+
+export function rgbToHsl({ r, g, b }: Rgb): Hsl {
+    const [rn, gn, bn] = [r / 255, g / 255, b / 255];
+    const max = Math.max(rn, gn, bn);
+    const min = Math.min(rn, gn, bn);
+    const l = (max + min) / 2;
+    if (max === min) {
+        return { h: 0, s: 0, l };
+    }
+    const d = max - min;
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    const h = max === rn ? (gn - bn) / d + (gn < bn ? 6 : 0) : max === gn ? (bn - rn) / d + 2 : (rn - gn) / d + 4;
+    return { h: h * 60, s, l };
+}
+
+export function hslToRgb({ h, s, l }: Hsl): Rgb {
+    const a = s * Math.min(l, 1 - l);
+    const f = (n: number) => {
+        const k = (n + h / 30) % 12;
+        return 255 * (l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1)));
+    };
+    return { r: f(0), g: f(8), b: f(4) };
+}
+
+/** Whether two colours are the same to the eye's tolerance - what "unchanged" means when deciding to emit a rule. */
+export function sameColour(a: Rgb, b: Rgb): boolean {
+    return Math.abs(a.r - b.r) < 1 && Math.abs(a.g - b.g) < 1 && Math.abs(a.b - b.b) < 1;
+}
+
+/**
+ * `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 function ensureContrast(colour: Rgb, background: Rgb, min = MIN_TEXT_CONTRAST): Rgb {
+    // Judged as the whole-number colour it will be written as: a fractional colour that reads can round to one that does not.
+    const whole = roundColour(colour);
+    if (contrastRatio(whole, background) >= min) {
+        return whole;
+    }
+    const target = luminance(background) < 0.5 ? 1 : 0;
+    const hsl = rgbToHsl(colour);
+    if (contrastRatio(hslToRgb({ ...hsl, l: target }), background) < min) {
+        return blackOrWhite(background);
+    }
+    let [near, far] = [hsl.l, target];
+    for (let i = 0; i < 16; i++) {
+        const middle = (near + far) / 2;
+        if (contrastRatio(roundColour(hslToRgb({ ...hsl, l: middle })), background) >= min) {
+            far = middle;
+        } else {
+            near = middle;
+        }
+    }
+    return roundColour(hslToRgb({ ...hsl, l: far }));
+}
+
+function roundColour({ r, g, b }: Rgb): Rgb {
+    return { r: Math.round(r), g: Math.round(g), b: Math.round(b) };
+}
+
+/** How far from grey a colour may be and still count as a neutral (black, white, greys) rather than a colour with a hue to keep. */
+const NEUTRAL_SATURATION = 0.12;
+
+/** 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 function blackOrWhite(background: Rgb): Rgb {
+    const [white, black] = [
+        { r: 255, g: 255, b: 255 },
+        { r: 0, g: 0, b: 0 },
+    ];
+    return contrastRatio(white, background) >= contrastRatio(black, background) ? white : black;
+}
+
+/**
+ * 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 function adaptForeground(colour: Rgb, surface: ThemeSurface): Rgb {
+    if (contrastRatio(colour, surface.background) >= MIN_TEXT_CONTRAST) {
+        return colour;
+    }
+    const hsl = rgbToHsl(colour);
+    if (hsl.s >= NEUTRAL_SATURATION) {
+        return ensureContrast(colour, surface.background);
+    }
+    // The distance from the end of the scale that would have been readable: a dark theme wants light text, so it is how dark
+    // the colour is; a light theme, how light.
+    const t = surface.dark ? hsl.l : 1 - hsl.l;
+    const mixed = {
+        r: surface.text.r + (surface.background.r - surface.text.r) * t,
+        g: surface.text.g + (surface.background.g - surface.text.g) * t,
+        b: surface.text.b + (surface.background.b - surface.text.b) * t,
+    };
+    return ensureContrast(mixed, surface.background);
+}
+
+/**
+ * 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 function firstColourStop(backgroundImage: string): Rgba | undefined {
+    const match = /rgba?\([^)]*\)|#[0-9a-f]{3,8}\b/i.exec(backgroundImage);
+    return match ? parseColour(match[0]) : undefined;
+}

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");