@rapidmx/web-client 0.9.0 → 0.11.0

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

@@ -0,0 +1,298 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 = 1_500_000;
+/** 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 = 20_000;
+
+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;
+}
+
+/** What a stylesheet or a `style` attribute may not contain, whatever the sanitizers before it did. */
+const STYLE_HAZARDS: [RegExp, string][] = [
+    // 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: string): string {
+    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: string): string {
+    return css.replace(CSS_ESCAPE, (_match, hex: string | undefined, other: string | undefined) =>
+        hex ? String.fromCodePoint(Math.min(parseInt(hex, 16), 0x10ffff)) : (other as 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 function declaresDarkSupport(doc: Document): boolean {
+    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: string | null): string | undefined {
+    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: Document): string {
+    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): void {
+    element.replaceWith(...Array.from(element.childNodes));
+}
+
+function hardenLink(element: Element): void {
+    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: Element, options: PrepareOptions): void {
+    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: HTMLElement, options: PrepareOptions): { elements: number; inlineImages: number } {
+    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: string, options: PrepareOptions = {}): PreparedBody {
+    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/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;
+}