@michaelmagan/dnumb 0.1.0

package/dist/snapshot/color.js

@@ -0,0 +1,1026 @@
+const clamp01 = (n) => Math.min(1, Math.max(0, n));
+const isPercent = (s) => s.trim().endsWith('%');
+const num = (s) => Number.parseFloat(s);
+function parseAlphaToken(s) {
+    if (s === undefined)
+        return 1;
+    const trimmed = s.trim();
+    if (trimmed === '' || trimmed.toLowerCase() === 'none')
+        return 1;
+    return isPercent(trimmed) ? clamp01(num(trimmed) / 100) : clamp01(num(trimmed));
+}
+/** Splits a CSS color function's parenthesized body into components + alpha,
+ * handling both the legacy comma syntax (`rgba(0, 0, 0, 0.5)`) and the
+ * modern space/slash syntax (`rgb(0 0 0 / 50%)`) -- `getComputedStyle`
+ * returns the former for `rgb()`/`hsl()` (verified,
+ * `docs/notes/03-color.md` §2) and the latter is cheap to also accept. */
+function splitComponents(inner) {
+    const slash = inner.indexOf('/');
+    const main = slash === -1 ? inner : inner.slice(0, slash);
+    let alpha = slash === -1 ? undefined : inner.slice(slash + 1).trim();
+    const parts = main.includes(',')
+        ? main.split(',').map((s) => s.trim())
+        : main.trim().split(/\s+/).filter(Boolean);
+    if (alpha === undefined && parts.length === 4)
+        alpha = parts.pop();
+    return { parts, alpha };
+}
+function channelFromToken(s) {
+    const v = isPercent(s) ? (num(s) / 100) * 255 : num(s);
+    return Math.round(clamp01(v / 255) * 255);
+}
+function parseRgbFn(inner) {
+    const { parts, alpha } = splitComponents(inner);
+    if (parts.length !== 3)
+        return null;
+    const [r, g, b] = parts;
+    return {
+        r: channelFromToken(r),
+        g: channelFromToken(g),
+        b: channelFromToken(b),
+        a: parseAlphaToken(alpha),
+    };
+}
+function hslToRgb(h, s, l) {
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const hp = (((h % 360) + 360) % 360) / 60;
+    const x = c * (1 - Math.abs((hp % 2) - 1));
+    let [r1, g1, b1] = [0, 0, 0];
+    if (hp < 1)
+        [r1, g1, b1] = [c, x, 0];
+    else if (hp < 2)
+        [r1, g1, b1] = [x, c, 0];
+    else if (hp < 3)
+        [r1, g1, b1] = [0, c, x];
+    else if (hp < 4)
+        [r1, g1, b1] = [0, x, c];
+    else if (hp < 5)
+        [r1, g1, b1] = [x, 0, c];
+    else
+        [r1, g1, b1] = [c, 0, x];
+    const m = l - c / 2;
+    return {
+        r: Math.round(clamp01(r1 + m) * 255),
+        g: Math.round(clamp01(g1 + m) * 255),
+        b: Math.round(clamp01(b1 + m) * 255),
+    };
+}
+function parseHslFn(inner) {
+    const { parts, alpha } = splitComponents(inner);
+    if (parts.length !== 3)
+        return null;
+    const [hs, ss, ls] = parts;
+    const h = num(hs.replace(/deg$/i, ''));
+    const s = isPercent(ss) ? num(ss) / 100 : num(ss);
+    const l = isPercent(ls) ? num(ls) / 100 : num(ls);
+    if (!Number.isFinite(h) || !Number.isFinite(s) || !Number.isFinite(l))
+        return null;
+    return { ...hslToRgb(h, s, l), a: parseAlphaToken(alpha) };
+}
+function parseHex(raw) {
+    const m = /^#([0-9a-f]{3,8})$/i.exec(raw.trim());
+    if (!m?.[1])
+        return null;
+    let h = m[1];
+    if (h.length === 3 || h.length === 4) {
+        h = h
+            .split('')
+            .map((c) => c + c)
+            .join('');
+    }
+    if (h.length !== 6 && h.length !== 8)
+        return null;
+    const r = Number.parseInt(h.slice(0, 2), 16);
+    const g = Number.parseInt(h.slice(2, 4), 16);
+    const b = Number.parseInt(h.slice(4, 6), 16);
+    const a = h.length === 8 ? Number.parseInt(h.slice(6, 8), 16) / 255 : 1;
+    return { r, g, b, a };
+}
+// ---- wide-gamut / perceptual functions -------------------------------------
+// Every matrix below is verified against real Chromium canvas readback in
+// `test/browser/color-space-conversion.test.ts`, not trusted from memory of
+// the spec text alone -- see that file and the probe this module's header
+// points to.
+/** Björn Ottosson's OKLab <-> linear sRGB matrices. */
+function oklabToLinearSrgb(L, a, b) {
+    const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+    const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+    const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+    const l = l_ ** 3;
+    const m = m_ ** 3;
+    const s = s_ ** 3;
+    return {
+        r: 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+        g: -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+        b: -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+    };
+}
+function linearToSrgbChannel(c) {
+    const abs = Math.abs(c);
+    return abs <= 0.0031308 ? c * 12.92 : Math.sign(c) * (1.055 * abs ** (1 / 2.4) - 0.055);
+}
+function srgbTransferToLinear(c) {
+    const abs = Math.abs(c);
+    return abs <= 0.04045 ? c / 12.92 : Math.sign(c) * ((abs + 0.055) / 1.055) ** 2.4;
+}
+/** Linear-light values (any gamut already mapped to linear sRGB primaries)
+ * -> 0-255 sRGB, clamping out-of-gamut channels rather than gamut-mapping
+ * perceptually -- the same simple per-channel clamp Chromium's own canvas
+ * rasterizer uses (verified: `color(display-p3 1 0 0)` reads back as pure
+ * `rgb(255,0,0)`, which only a hard clamp -- not perceptual remapping --
+ * produces). Disclosed as `clamped` so a caller can tell a lossy conversion
+ * from an exact one. */
+function linearToRgb255(lin, alpha) {
+    let clamped = false;
+    const chan = (c) => {
+        const s = linearToSrgbChannel(c);
+        const cl = clamp01(s);
+        if (Math.abs(cl - s) > 1e-9)
+            clamped = true;
+        return Math.round(cl * 255);
+    };
+    return { rgba: { r: chan(lin.r), g: chan(lin.g), b: chan(lin.b), a: clamp01(alpha) }, clamped };
+}
+function oklchComponents(L, C, H) {
+    const l = isPercent(L) ? num(L) / 100 : num(L);
+    const c = isPercent(C) ? (num(C) / 100) * 0.4 : num(C);
+    const h = ((num(H.replace(/deg$/i, '')) % 360) + 360) % 360;
+    return [l, c, h];
+}
+function oklabComponents(L, a, b) {
+    const l = isPercent(L) ? num(L) / 100 : num(L);
+    const ac = isPercent(a) ? (num(a) / 100) * 0.4 : num(a);
+    const bc = isPercent(b) ? (num(b) / 100) * 0.4 : num(b);
+    return [l, ac, bc];
+}
+function parseOklchFn(inner) {
+    const { parts, alpha } = splitComponents(inner);
+    if (parts.length !== 3)
+        return null;
+    const [Ls, Cs, Hs] = parts;
+    const [L, C, H] = oklchComponents(Ls, Cs, Hs);
+    if (!Number.isFinite(L) || !Number.isFinite(C) || !Number.isFinite(H))
+        return null;
+    const hRad = (H * Math.PI) / 180;
+    return linearToRgb255(oklabToLinearSrgb(L, C * Math.cos(hRad), C * Math.sin(hRad)), parseAlphaToken(alpha));
+}
+function parseOklabFn(inner) {
+    const { parts, alpha } = splitComponents(inner);
+    if (parts.length !== 3)
+        return null;
+    const [Ls, As, Bs] = parts;
+    const [L, a, b] = oklabComponents(Ls, As, Bs);
+    if (!Number.isFinite(L) || !Number.isFinite(a) || !Number.isFinite(b))
+        return null;
+    return linearToRgb255(oklabToLinearSrgb(L, a, b), parseAlphaToken(alpha));
+}
+/** CSS Color 4's Lab -> D50 XYZ, then a Bradford-adapted D50->linear-sRGB
+ * matrix combined into one step (verified against Chromium canvas readback:
+ * `lab(50 40 59.5)` -> `rgb(191,87,0)` exactly, out-of-gamut and clamped). */
+function labToXyzD50(L, a, b) {
+    const k = 24389 / 27;
+    const e = 216 / 24389;
+    const fy = (L + 16) / 116;
+    const fx = fy + a / 500;
+    const fz = fy - b / 200;
+    const fx3 = fx ** 3;
+    const fz3 = fz ** 3;
+    const xr = fx3 > e ? fx3 : (116 * fx - 16) / k;
+    const yr = L > k * e ? ((L + 16) / 116) ** 3 : L / k;
+    const zr = fz3 > e ? fz3 : (116 * fz - 16) / k;
+    const Xn = 0.3457 / 0.3585;
+    const Yn = 1;
+    const Zn = (1 - 0.3457 - 0.3585) / 0.3585;
+    return { X: xr * Xn, Y: yr * Yn, Z: zr * Zn };
+}
+function xyzD50ToLinearSrgb({ X, Y, Z }) {
+    return {
+        r: 3.1341359569 * X - 1.6172472247 * Y - 0.4906994307 * Z,
+        g: -0.9787684156 * X + 1.9161415014 * Y + 0.0334540657 * Z,
+        b: 0.0719453189 * X - 0.2289913338 * Y + 1.4052427493 * Z,
+    };
+}
+function labComponents(L, a, b) {
+    const l = num(L);
+    const ac = isPercent(a) ? (num(a) / 100) * 125 : num(a);
+    const bc = isPercent(b) ? (num(b) / 100) * 125 : num(b);
+    return [l, ac, bc];
+}
+function parseLabFn(inner) {
+    const { parts, alpha } = splitComponents(inner);
+    if (parts.length !== 3)
+        return null;
+    const [Ls, As, Bs] = parts;
+    const [L, a, b] = labComponents(Ls, As, Bs);
+    if (!Number.isFinite(L) || !Number.isFinite(a) || !Number.isFinite(b))
+        return null;
+    return linearToRgb255(xyzD50ToLinearSrgb(labToXyzD50(L, a, b)), parseAlphaToken(alpha));
+}
+function parseLchFn(inner) {
+    const { parts, alpha } = splitComponents(inner);
+    if (parts.length !== 3)
+        return null;
+    const [Ls, Cs, Hs] = parts;
+    const l = num(Ls);
+    const c = isPercent(Cs) ? (num(Cs) / 100) * 150 : num(Cs);
+    const h = num(Hs.replace(/deg$/i, ''));
+    if (!Number.isFinite(l) || !Number.isFinite(c) || !Number.isFinite(h))
+        return null;
+    const hRad = (h * Math.PI) / 180;
+    return linearToRgb255(xyzD50ToLinearSrgb(labToXyzD50(l, c * Math.cos(hRad), c * Math.sin(hRad))), parseAlphaToken(alpha));
+}
+/** linear-P3 -> linear-sRGB (CSS Color 4's matrix; verified against Chromium
+ * canvas readback -- see this file's header). */
+function p3LinearToSrgbLinear(r, g, b) {
+    return {
+        r: 1.2249401762 * r - 0.2249401762 * g + 0.0 * b,
+        g: -0.0420569547 * r + 1.0420569547 * g + 0.0 * b,
+        b: -0.0196375546 * r - 0.078636097 * g + 1.0982736516 * b,
+    };
+}
+function parseColorFn(space, inner) {
+    const { parts, alpha } = splitComponents(inner);
+    if (parts.length !== 3)
+        return null;
+    const chan = (s) => (isPercent(s) ? num(s) / 100 : num(s));
+    const [r, g, b] = parts.map(chan);
+    if (!Number.isFinite(r) || !Number.isFinite(g) || !Number.isFinite(b))
+        return null;
+    const a = parseAlphaToken(alpha);
+    switch (space) {
+        case 'srgb':
+            // `color(srgb r g b)` components are already gamma-encoded sRGB in the
+            // 0-1 range -- no transfer function, just clamp and scale to 8-bit.
+            return {
+                rgba: {
+                    r: Math.round(clamp01(r) * 255),
+                    g: Math.round(clamp01(g) * 255),
+                    b: Math.round(clamp01(b) * 255),
+                    a,
+                },
+                clamped: r < 0 || r > 1 || g < 0 || g > 1 || b < 0 || b > 1,
+            };
+        case 'srgb-linear':
+            return linearToRgb255({ r, g, b }, a);
+        case 'display-p3': {
+            const linear = p3LinearToSrgbLinear(srgbTransferToLinear(r), srgbTransferToLinear(g), srgbTransferToLinear(b));
+            return linearToRgb255(linear, a);
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Parse a computed-style color string to sRGB, or refuse honestly.
+ *
+ * Every space `docs/notes/03-color.md` §3 calls out as a real capture
+ * problem -- `oklch`, `oklab`, `lab`, `lch`, `color(srgb ...)`,
+ * `color(srgb-linear ...)`, `color(display-p3 ...)` -- converts. Anything
+ * else (a future space, a syntax this parser does not recognise) returns the
+ * raw string verbatim rather than guessing: rule 4 of the design note's §5
+ * applies to color parsing exactly as it does to the ratio itself.
+ */
+export function parseCssColor(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === '' || trimmed.toLowerCase() === 'transparent') {
+        return { kind: 'resolved', rgba: { r: 0, g: 0, b: 0, a: 0 } };
+    }
+    const hex = parseHex(trimmed);
+    if (hex)
+        return { kind: 'resolved', rgba: hex };
+    const fn = /^([a-z-]+)\(([^)]*)\)$/i.exec(trimmed);
+    if (fn?.[1] && fn[2] !== undefined) {
+        const name = fn[1].toLowerCase();
+        const inner = fn[2];
+        if (name === 'rgb' || name === 'rgba') {
+            const rgba = parseRgbFn(inner);
+            if (rgba)
+                return { kind: 'resolved', rgba };
+        }
+        else if (name === 'hsl' || name === 'hsla') {
+            const rgba = parseHslFn(inner);
+            if (rgba)
+                return { kind: 'resolved', rgba };
+        }
+        else if (name === 'oklch') {
+            const parsed = parseOklchFn(inner);
+            if (parsed)
+                return { kind: 'resolved', rgba: parsed.rgba };
+        }
+        else if (name === 'oklab') {
+            const parsed = parseOklabFn(inner);
+            if (parsed)
+                return { kind: 'resolved', rgba: parsed.rgba };
+        }
+        else if (name === 'lab') {
+            const parsed = parseLabFn(inner);
+            if (parsed)
+                return { kind: 'resolved', rgba: parsed.rgba };
+        }
+        else if (name === 'lch') {
+            const parsed = parseLchFn(inner);
+            if (parsed)
+                return { kind: 'resolved', rgba: parsed.rgba };
+        }
+        else if (name === 'color') {
+            const spaceMatch = /^\s*([a-z0-9-]+)\s+(.*)$/i.exec(inner);
+            if (spaceMatch?.[1] && spaceMatch[2] !== undefined) {
+                const parsed = parseColorFn(spaceMatch[1].toLowerCase(), spaceMatch[2]);
+                if (parsed)
+                    return { kind: 'resolved', rgba: parsed.rgba };
+            }
+        }
+    }
+    return { kind: 'verbatim', raw: trimmed };
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+function channelHex(n) {
+    return Math.max(0, Math.min(255, Math.round(n)))
+        .toString(16)
+        .padStart(2, '0');
+}
+/** `#rrggbb`, or `#rrggbbaa` when `alpha` is given and < 1. */
+export function toHex(rgb, alpha) {
+    const base = `#${channelHex(rgb.r)}${channelHex(rgb.g)}${channelHex(rgb.b)}`;
+    return alpha === undefined ? base : `${base}${channelHex(alpha * 255)}`;
+}
+/** A resolved color's display form: hex (with an alpha suffix below full
+ * opacity), or the raw CSS string verbatim when the space could not be
+ * converted -- "Colors print as lowercase hex ..., or verbatim when a color
+ * space could not be converted" (design note §4). */
+function displayColor(raw) {
+    const parsed = parseCssColor(raw);
+    if (parsed.kind === 'verbatim')
+        return parsed.raw;
+    return toHex(parsed.rgba, parsed.rgba.a < 0.999 ? parsed.rgba.a : undefined);
+}
+// ---------------------------------------------------------------------------
+// WCAG 2.x contrast
+// ---------------------------------------------------------------------------
+function srgbToLinearChannel(c8) {
+    const c = c8 / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+/** WCAG 2.x relative luminance. The name of a formula, never a threshold. */
+export function relativeLuminance(rgb) {
+    return (0.2126 * srgbToLinearChannel(rgb.r) +
+        0.7152 * srgbToLinearChannel(rgb.g) +
+        0.0722 * srgbToLinearChannel(rgb.b));
+}
+/** WCAG 2.x contrast ratio between two opaque sRGB colors. */
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const lighter = Math.max(la, lb);
+    const darker = Math.min(la, lb);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+function compositeOver(top, bottomOpaque) {
+    const a = clamp01(top.a);
+    return {
+        r: top.r * a + bottomOpaque.r * (1 - a),
+        g: top.g * a + bottomOpaque.g * (1 - a),
+        b: top.b * a + bottomOpaque.b * (1 - a),
+    };
+}
+// ---------------------------------------------------------------------------
+// `background-image`: the counter-fact that invalidates a backdrop
+// ---------------------------------------------------------------------------
+const COLOR_TOKEN_RE = /rgba?\([^)]*\)|hsla?\([^)]*\)|color\([^)]*\)|oklch\([^)]*\)|oklab\([^)]*\)|lch\([^)]*\)|lab\([^)]*\)|#[0-9a-fA-F]{3,8}\b/g;
+/**
+ * Refuse rather than let a missing field fail deep inside
+ * `parseBackgroundImageKind`/`firstShadowColor`/`parsePx` as an unreadable
+ * `TypeError: Cannot read properties of undefined (reading 'trim')` -- named
+ * after the field that is missing and what would have supplied it, the same
+ * quality of diagnosis `cli.ts#readBundle` gives for a malformed bundle file.
+ * A bundle read through `parseBundle` always satisfies this by construction
+ * (`bundle.ts#normalizeElement` backfills all four for a bundle written
+ * before they existed); this only ever fires for a record assembled by hand
+ * -- directly, or via `capture()`'s in-memory result mutated before use --
+ * that skipped one.
+ */
+function requireColorField(elementId, field, value, opts) {
+    // `null` is a legitimate, distinct third state on `backgroundImage` only
+    // (A3): "this specific capture never measured this field", not "the
+    // caller skipped a required field". `resolveBackdrop`/`hasPaint` are the
+    // code that actually acts on that `null`; this check only needs to let it
+    // through rather than treat it as the construction error `undefined` is.
+    if (value === null && opts?.allowNull)
+        return;
+    if (typeof value !== 'string') {
+        throw new Error(`dnumb: element "${elementId}" has no "${field}" (added for color capture -- every real ` +
+            'capture sets it, and parseBundle backfills it for a bundle written before this field ' +
+            'existed). A hand-built ElementRecord must include it -- see the type exported from ' +
+            '"@michaelmagan/dnumb/spec", or produce the record with capture()/parseBundle instead of by hand.');
+    }
+}
+/**
+ * `none`, a gradient (first and last color stop, `docs/notes/03-color.md`
+ * §2's "the stops are real, printable facts even though no ratio is"), or
+ * anything else that paints (`url()`, and any other CSS image function this
+ * parser does not specifically recognise, treated the same conservative
+ * way): all invalidate a resolved backdrop.
+ */
+function parseBackgroundImageKind(raw, elementId) {
+    requireColorField(elementId, 'backgroundImage', raw);
+    const trimmed = raw.trim();
+    if (trimmed === '' || trimmed.toLowerCase() === 'none')
+        return { kind: 'none' };
+    if (/-gradient\(/i.test(trimmed)) {
+        const tokens = [...trimmed.matchAll(COLOR_TOKEN_RE)].map((m) => m[0]);
+        const first = tokens[0];
+        const last = tokens[tokens.length - 1];
+        if (first && last) {
+            return { kind: 'gradient', from: displayColor(first), to: displayColor(last) };
+        }
+        // A gradient syntax this scan could not find a color token in (a bare
+        // keyword stop like `red`, or a syntax this regex missed) is still a
+        // gradient -- disclosed as an unresolvable one rather than silently
+        // treated as `none`, which would wrongly let compositing continue past it.
+        return { kind: 'gradient', from: 'unknown', to: 'unknown' };
+    }
+    return { kind: 'url' };
+}
+/**
+ * The browser's real default canvas fill, resolved from `<html>`'s own
+ * background-color and color-scheme -- or `null` when it genuinely cannot be
+ * determined from the page alone. Verified against real Chromium pixel
+ * readback (A2): `color-scheme: dark` with no background set anywhere reads
+ * back as `rgb(18, 18, 18)`, not white; an explicit opaque `<html>`
+ * background-color wins outright, regardless of color-scheme.
+ */
+function canvasBackdrop(canvas) {
+    const parsedBg = parseCssColor(canvas.backgroundColor);
+    if (parsedBg.kind === 'verbatim')
+        return null;
+    if (parsedBg.rgba.a >= OPAQUE_EPSILON)
+        return parsedBg.rgba;
+    const tokens = canvas.colorScheme.trim().toLowerCase().split(/\s+/).filter(Boolean);
+    const hasDark = tokens.includes('dark');
+    const hasLight = tokens.includes('light') || tokens.includes('normal') || tokens.length === 0;
+    // Both listed (`light dark`) genuinely depends on the reader's own OS
+    // preference, which this capture cannot see -- honestly unresolvable,
+    // not a coin flip. Anything this parser does not recognise gets the same
+    // "cannot say" treatment rather than a guess.
+    const uaDefault = hasDark && !hasLight
+        ? { r: 18, g: 18, b: 18 }
+        : hasLight && !hasDark
+            ? { r: 255, g: 255, b: 255 }
+            : null;
+    if (uaDefault === null)
+        return parsedBg.rgba.a > 0 ? null : null;
+    return parsedBg.rgba.a > 0 ? compositeOver(parsedBg.rgba, uaDefault) : uaDefault;
+}
+const OPAQUE_EPSILON = 0.999;
+/**
+ * Standard Porter-Duff "over": `top` (already-resolved, itself possibly
+ * translucent) painted over `bottom` (also possibly translucent), both in
+ * *straight* (non-premultiplied) alpha. Generalizes `compositeOver` above
+ * (which assumes an opaque bottom -- still used for the simpler alpha-chain
+ * case) to a bottom that is not yet fully resolved either, which is what
+ * folding CSS `opacity` into the walk needs (A5): an ancestor's own
+ * `background-color` is one input, that same ancestor's `opacity` is
+ * another, independent one, and both apply at the exact same position.
+ */
+function overStep(top, bottom) {
+    const a = clamp01(top.a + bottom.a * (1 - top.a));
+    if (a <= 0)
+        return { r: 0, g: 0, b: 0, a: 0 };
+    return {
+        r: (top.r * top.a + bottom.r * bottom.a * (1 - top.a)) / a,
+        g: (top.g * top.a + bottom.g * bottom.a * (1 - top.a)) / a,
+        b: (top.b * top.a + bottom.b * bottom.a * (1 - top.a)) / a,
+        a,
+    };
+}
+/**
+ * Walk up from `el` accumulating translucent `background-color` layers
+ * *and* CSS `opacity` until something fully opaque is reached, then report
+ * the composited result -- an incremental left-to-right fold rather than
+ * "collect layers, then composite once at the end", specifically so
+ * `opacity` folds in correctly (A5): unlike a plain `background-color`
+ * alpha, `opacity` scales *everything already composited so far* as one
+ * group at the exact point it is applied, so each ancestor's own
+ * contribution has to be resolved against what is beneath it before the
+ * next ancestor's `opacity` scales the combined result again. The pure
+ * `background-color`-only case (no `opacity < 1` anywhere in the chain)
+ * reduces to exactly the old flat-stack composite -- *verified* exact
+ * against Chromium's own `blendedBackgroundColors` on an alpha chain
+ * (`test/browser/color-backdrop.test.ts`) -- and the opacity-aware general
+ * case is verified against real Chromium canvas pixel readback for both a
+ * single opacity boundary and nested multi-level opacity (see this
+ * module's header and `test/browser/color-backdrop.test.ts`'s A5 cases).
+ *
+ * Aborts to a `gradient`/`image`/`not-captured` backdrop the instant any
+ * layer's own `backgroundImage` says so (A3), and to `canvas` when the walk
+ * runs off the top of `<body>` with no way to know the real default fill
+ * (A2, see `canvasBackdrop`). A non-ancestor overlay is checked by the
+ * caller before this ever runs (see `colorFactFor`), since an overlay makes
+ * the ancestor chain irrelevant regardless of what it would have found.
+ */
+export function resolveBackdrop(el, byId, canvas) {
+    const chain = [];
+    let cursor = el;
+    let lastId = el.id;
+    let isFirst = true;
+    let acc = { r: 0, g: 0, b: 0, a: 0 };
+    let layerCount = 0;
+    while (cursor) {
+        lastId = cursor.id;
+        if (cursor.backgroundImage === null) {
+            chain.push({ id: cursor.id, color: 'not-captured', alpha: 1 });
+            return { backdrop: { kind: 'not-captured', via: cursor.id }, rgb: null, chain };
+        }
+        const img = parseBackgroundImageKind(cursor.backgroundImage, cursor.id);
+        if (img.kind === 'gradient') {
+            chain.push({ id: cursor.id, color: `gradient(${img.from}→${img.to})`, alpha: 1 });
+            return {
+                backdrop: { kind: 'gradient', from: img.from, to: img.to, via: cursor.id },
+                rgb: null,
+                chain,
+            };
+        }
+        if (img.kind === 'url') {
+            chain.push({ id: cursor.id, color: 'image', alpha: 1 });
+            const coverage = {
+                boxWidth: Math.round(cursor.rect.width),
+                boxHeight: Math.round(cursor.rect.height),
+                ofWidth: Math.round(el.rect.width),
+                ofHeight: Math.round(el.rect.height),
+            };
+            return { backdrop: { kind: 'image', via: cursor.id, coverage }, rgb: null, chain };
+        }
+        const parsed = parseCssColor(cursor.backgroundColor);
+        if (parsed.kind === 'verbatim') {
+            // A color this parser cannot convert closes the walk right here: it
+            // might be opaque or translucent and there is no honest way to know
+            // which, so compositing cannot continue past it. Printed verbatim per
+            // §4 ("or verbatim when a color space could not be converted");
+            // `colorFactFor` reads `rgb === null` off this to force `ratio
+            // unmeasured (color-space)`.
+            chain.push({ id: cursor.id, color: parsed.raw, alpha: 1 });
+            return {
+                backdrop: {
+                    kind: 'opaque',
+                    color: parsed.raw,
+                    via: cursor.id,
+                    self: isFirst,
+                    layers: layerCount,
+                },
+                rgb: null,
+                chain,
+            };
+        }
+        const ownContributes = parsed.rgba.a > 0 || cursor.opacity < 1;
+        const combined = overStep(acc, parsed.rgba);
+        acc = { r: combined.r, g: combined.g, b: combined.b, a: clamp01(combined.a * cursor.opacity) };
+        if (acc.a >= OPAQUE_EPSILON) {
+            chain.push({ id: cursor.id, color: toHex(acc), alpha: acc.a });
+            return {
+                backdrop: {
+                    kind: 'opaque',
+                    color: toHex(acc),
+                    via: cursor.id,
+                    self: isFirst,
+                    layers: layerCount,
+                },
+                rgb: acc,
+                chain,
+            };
+        }
+        if (ownContributes) {
+            layerCount++;
+            chain.push({ id: cursor.id, color: toHex(acc), alpha: acc.a });
+        }
+        isFirst = false;
+        cursor = cursor.parentId ? byId.get(cursor.parentId) : undefined;
+    }
+    // The chain never met an opaque layer: what is really behind everything
+    // is the browser's own default canvas fill -- resolved from `<html>`'s
+    // own background-color/color-scheme when a caller supplied one (A2),
+    // never assumed to be white. `canvas` omitted (a caller not yet updated
+    // to pass one -- see this module's header) and `canvas` supplied but
+    // unresolvable (an unconvertible color, or an ambiguous `light dark`
+    // scheme) are both reported the same honest way: `unmeasured (canvas)`,
+    // never a guessed color.
+    const canvasRgb = canvas ? canvasBackdrop(canvas) : null;
+    if (canvasRgb === null) {
+        chain.push({ id: lastId, color: 'canvas (unresolved)', alpha: 1 });
+        return { backdrop: { kind: 'canvas' }, rgb: null, chain };
+    }
+    const final = overStep(acc, { ...canvasRgb, a: 1 });
+    chain.push({ id: lastId, color: `canvas ${toHex(canvasRgb)}`, alpha: 1 });
+    return {
+        backdrop: {
+            kind: 'opaque',
+            color: toHex(final),
+            via: 'canvas',
+            self: false,
+            layers: layerCount,
+        },
+        rgb: final,
+        chain,
+    };
+}
+/**
+ * Folds `startAcc` (the ink itself, or nothing) through `cursor`'s ancestors
+ * up to the resolved canvas, applying each level's own
+ * (`background-color`, `opacity`) exactly like `resolveBackdrop`'s main
+ * loop -- reused for the ink so it fades through the *same* opacity chain
+ * the backdrop does, toward the *same* outside reference, rather than a
+ * flat multiply against the backdrop's own already-resolved color, which
+ * `test/browser/color-backdrop.test.ts`'s nested-opacity case proves gives a
+ * different (wrong) answer (A5). Only ever called once `resolveBackdrop`
+ * has already proven this exact suffix of the chain -- starting at `el`'s
+ * parent, a subset of `el`'s own chain -- contains no gradient/image/
+ * not-captured/unconvertible-color abort, so none of those cases need
+ * handling here.
+ */
+function foldOverAncestors(startAcc, cursor, byId, canvasRgb) {
+    let acc = startAcc;
+    while (cursor) {
+        const parsed = parseCssColor(cursor.backgroundColor);
+        const bottom = parsed.kind === 'resolved' ? parsed.rgba : { r: 0, g: 0, b: 0, a: 0 };
+        const combined = overStep(acc, bottom);
+        acc = { r: combined.r, g: combined.g, b: combined.b, a: clamp01(combined.a * cursor.opacity) };
+        if (acc.a >= OPAQUE_EPSILON)
+            return acc;
+        cursor = cursor.parentId ? byId.get(cursor.parentId) : undefined;
+    }
+    const base = canvasRgb ?? { r: 255, g: 255, b: 255 };
+    return overStep(acc, { ...base, a: 1 });
+}
+// ---------------------------------------------------------------------------
+// The overlap check: a non-ancestor painted over or behind the text
+// ---------------------------------------------------------------------------
+function ancestorIdsOf(el, byId) {
+    const ids = new Set();
+    let cursor = el.parentId ? byId.get(el.parentId) : undefined;
+    while (cursor) {
+        ids.add(cursor.id);
+        cursor = cursor.parentId ? byId.get(cursor.parentId) : undefined;
+    }
+    return ids;
+}
+function isDescendantOf(candidate, ancestorId, byId) {
+    let cursor = candidate.parentId ? byId.get(candidate.parentId) : undefined;
+    while (cursor) {
+        if (cursor.id === ancestorId)
+            return true;
+        cursor = cursor.parentId ? byId.get(cursor.parentId) : undefined;
+    }
+    return false;
+}
+/** Whether an element paints anything a viewer could actually see covering
+ * what is behind it -- a non-transparent `background-color`, or any
+ * `background-image`. An unresolvable color is treated as "might paint": a
+ * false-positive overlay (an honest `unmeasured`) is the safe direction to
+ * err in, never a ratio that silently ignores something real. */
+function hasPaint(el) {
+    // `backgroundImage === null` (A3): this specific capture never measured
+    // it, so it might be a gradient or image painting over/behind the text --
+    // treated as "might paint", the same safe direction this function's own
+    // doc comment already takes for an unresolvable color.
+    if (el.backgroundImage === null)
+        return true;
+    if (parseBackgroundImageKind(el.backgroundImage, el.id).kind !== 'none')
+        return true;
+    const parsed = parseCssColor(el.backgroundColor);
+    return parsed.kind === 'verbatim' || parsed.rgba.a > 0;
+}
+function rectsIntersect(a, b) {
+    return a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
+}
+/**
+ * A non-ancestor element painted `under` (in front of, obscuring the text
+ * itself) or `behind` (between the text and where the ancestor walk would
+ * have looked) this one -- the two `incompleteData` cases
+ * `blendedBackgroundColors` gets silently wrong (design note §3): a
+ * `rgba(255,0,0,0.8)` sibling scrim painted directly over text reads back as
+ * `rgb(255,255,255)`, the page background, as if the overlay were not there.
+ *
+ * Two independent input signals, one per capture path (design note §7):
+ * `el.hitStackIds` (the `walk` path's `elementsFromPoint` result, already
+ * ordered front-to-back) when present, else `paintOrder` plus rect
+ * intersection (the `cdp` path, Node-side, whole-rect rather than
+ * centre-point). Neither present -- a hand-built fixture, a bundle written
+ * before this capability existed -- reports no overlay rather than guessing:
+ * rule 4 of the design note's §5 (refuse rather than fabricate) applies here
+ * exactly as it does to the ratio itself.
+ */
+export function detectOverlay(el, byId, elements) {
+    const ancestors = ancestorIdsOf(el, byId);
+    // `Array.isArray`/`typeof ... === 'number'`, not `!== null`: a bundle
+    // written before these two fields existed has them simply absent from its
+    // JSON (`undefined`, not the explicit `null` a current capture writes for
+    // "not computed") -- `test/fixtures/real-sites/*.json` are real examples.
+    // `undefined !== null` is true, so a bare null-check would have walked
+    // straight into `undefined.indexOf`, treating a bundle with NO signal at
+    // all as if it carried an empty-but-present one.
+    if (Array.isArray(el.hitStackIds)) {
+        const stack = el.hitStackIds;
+        const elIdx = stack.indexOf(el.id);
+        const ancIdx = stack.findIndex((id) => ancestors.has(id));
+        // Anything at or past the first ancestor in the stack is behind the wall
+        // our composite walk would stop at anyway -- irrelevant to check.
+        const boundary = ancIdx === -1 ? stack.length : ancIdx;
+        for (let i = 0; i < boundary; i++) {
+            const id = stack[i];
+            if (id === undefined || id === el.id)
+                continue;
+            const candidate = byId.get(id);
+            if (!candidate?.visible)
+                continue;
+            if (isDescendantOf(candidate, el.id, byId))
+                continue;
+            if (!hasPaint(candidate))
+                continue;
+            // Before `el` in the front-to-back stack: painted on top of, obscuring,
+            // the text pixel itself. After `el` (or `el` not found at all, which
+            // should not happen for a visible text element but is handled the same
+            // conservative way): sits behind the text but ahead of where the
+            // ancestor wall is.
+            return { reason: elIdx !== -1 && i < elIdx ? 'under' : 'behind', via: candidate.id };
+        }
+        return null;
+    }
+    if (typeof el.paintOrder === 'number') {
+        let ancestorMax = Number.NEGATIVE_INFINITY;
+        for (const id of ancestors) {
+            const po = byId.get(id)?.paintOrder;
+            if (typeof po === 'number')
+                ancestorMax = Math.max(ancestorMax, po);
+        }
+        const candidates = elements
+            .filter((c) => c.id !== el.id &&
+            c.visible &&
+            typeof c.paintOrder === 'number' &&
+            !ancestors.has(c.id) &&
+            !isDescendantOf(c, el.id, byId) &&
+            rectsIntersect(c.rect, el.rect) &&
+            hasPaint(c))
+            .sort((a, b) => (b.paintOrder ?? 0) - (a.paintOrder ?? 0));
+        for (const candidate of candidates) {
+            const po = candidate.paintOrder ?? Number.NEGATIVE_INFINITY;
+            if (po > (el.paintOrder ?? Number.POSITIVE_INFINITY))
+                return { reason: 'under', via: candidate.id };
+            if (po > ancestorMax)
+                return { reason: 'behind', via: candidate.id };
+        }
+        return null;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Effective opacity: the CSS `opacity` property compounding through ancestors
+// ---------------------------------------------------------------------------
+/** `opacity` on an ancestor scales everything painted inside it, and it
+ * compounds -- two nested `opacity: 0.5` elements render at an effective
+ * 0.25. Computed Node-side over the existing `opacity` field every element
+ * already carries; no new capture is needed for this one (design note §7's
+ * "the walk multiplies ancestor opacities itself" happens here instead, over
+ * records, matching this module's whole architecture). */
+function effectiveOpacity(el, byId) {
+    let opacity = el.opacity;
+    let cursor = el.parentId ? byId.get(el.parentId) : undefined;
+    while (cursor) {
+        opacity *= cursor.opacity;
+        cursor = cursor.parentId ? byId.get(cursor.parentId) : undefined;
+    }
+    return opacity;
+}
+// ---------------------------------------------------------------------------
+// Counter-facts: text-shadow, text-stroke
+// ---------------------------------------------------------------------------
+/** The first shadow's color, or `null` when there is no shadow. Chromium
+ * serializes the color first in each comma-separated shadow (*verified*:
+ * `text-shadow: 2px 2px 4px rgba(0,0,0,0.8)` computes to
+ * `"rgba(0, 0, 0, 0.8) 2px 2px 4px"`), so the first color-shaped token in the
+ * first comma segment is the shadow's own color -- dnumb cannot measure what
+ * a shadow does perceptually, so this discloses that one exists and in what
+ * color, nothing more (design note §2). */
+function firstShadowColor(raw, elementId) {
+    requireColorField(elementId, 'textShadow', raw);
+    const trimmed = raw.trim();
+    if (trimmed === '' || trimmed.toLowerCase() === 'none')
+        return null;
+    const firstSegment = trimmed.split(',')[0] ?? trimmed;
+    const token = COLOR_TOKEN_RE.exec(firstSegment)?.[0];
+    COLOR_TOKEN_RE.lastIndex = 0;
+    return token ? displayColor(token) : null;
+}
+function parsePx(raw) {
+    if (raw === undefined)
+        return null;
+    const n = Number.parseFloat(raw);
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * The color fact for one element, or `null` when the measurement gate does
+ * not apply: "every visible element with its own text" (design note §4) --
+ * no text, no ink-on-backdrop question to answer.
+ *
+ * A6 note: a closed `<sl-dialog>` (`opacity: 0` on an ancestor) still gets a
+ * fact here for each visible-by-its-own-styling descendant -- `el.visible`
+ * only reflects the element's *own* opacity/display/visibility/size, not an
+ * ancestor's. That fact's `ratio` genuinely does come out `1.00` (ink
+ * composited to exactly equal its own backdrop at zero *effective* opacity)
+ * -- mathematically correct, not fabricated, and never suppressed here:
+ * "facts, with counter-facts, never adjudicate" means this module does not
+ * get to decide the fact is uninteresting and drop it. `effectiveOpacity`
+ * below is the counter-fact that explains it (`opacity ×0`, kept on
+ * `ColorFact` and, via `ColorPair.effectiveOpacity`, on `q color`'s grouped
+ * rows too -- see that field's doc comment) so a reader sees *why* the
+ * ratio is round, rather than the fact disappearing and the explanation
+ * disappearing with it.
+ */
+export function colorFactFor(el, byId, elements, canvas) {
+    if (!el.visible || !el.text)
+        return null;
+    const opacity = effectiveOpacity(el, byId);
+    // Fail fast, once, naming the first missing field -- rather than let it
+    // surface later as a `TypeError` inside `resolveBackdrop`/`firstShadowColor`/
+    // `parsePx`. See `requireColorField`'s doc comment. `backgroundImage` alone
+    // allows `null` -- see `requireColorField` and `ElementRecord.backgroundImage`.
+    requireColorField(el.id, 'backgroundImage', el.backgroundImage, { allowNull: true });
+    requireColorField(el.id, 'textShadow', el.textShadow);
+    requireColorField(el.id, 'textStrokeWidth', el.textStrokeWidth);
+    requireColorField(el.id, 'textStrokeColor', el.textStrokeColor);
+    const fgParsed = parseCssColor(el.color);
+    const overlay = detectOverlay(el, byId, elements);
+    let backdrop;
+    let bgRgb;
+    if (overlay) {
+        backdrop = { kind: 'overlay', reason: overlay.reason, via: overlay.via };
+        bgRgb = null;
+    }
+    else {
+        const resolved = resolveBackdrop(el, byId, canvas);
+        backdrop = resolved.backdrop;
+        bgRgb = resolved.rgb;
+    }
+    let ratioReason = null;
+    if (backdrop.kind === 'gradient')
+        ratioReason = 'gradient';
+    else if (backdrop.kind === 'image')
+        ratioReason = 'image';
+    else if (backdrop.kind === 'overlay')
+        ratioReason = backdrop.reason;
+    else if (backdrop.kind === 'not-captured')
+        ratioReason = 'not-captured';
+    else if (backdrop.kind === 'canvas')
+        ratioReason = 'canvas';
+    else if (bgRgb === null || fgParsed.kind !== 'resolved')
+        ratioReason = 'color-space';
+    let fg;
+    let ratio = null;
+    if (fgParsed.kind === 'verbatim') {
+        fg = fgParsed.raw;
+    }
+    else if (ratioReason === null && bgRgb) {
+        // The backdrop fully resolved: fold the ink through the *same*
+        // ancestor opacity chain the backdrop itself was resolved through,
+        // toward the *same* outside reference, rather than a flat multiply
+        // against the backdrop's own already-resolved color (A5) -- see
+        // `foldOverAncestors`'s doc comment for why the two give different
+        // answers whenever more than one opacity boundary is involved, and
+        // this module's header for the real-Chromium verification. The result
+        // is the ink's true rendered color -- opaque, no alpha suffix, because
+        // it no longer represents "this element's own raw CSS color" but "what
+        // is actually painted at this pixel", the same register `bgRgb` itself
+        // is already in.
+        const startAcc = {
+            ...fgParsed.rgba,
+            a: clamp01(fgParsed.rgba.a * el.opacity),
+        };
+        const parentEl = el.parentId ? byId.get(el.parentId) : undefined;
+        const canvasRgb = canvas ? canvasBackdrop(canvas) : null;
+        const foldedInk = foldOverAncestors(startAcc, parentEl, byId, canvasRgb);
+        fg = toHex(foldedInk);
+        ratio = Math.round(contrastRatio(foldedInk, bgRgb) * 100) / 100;
+    }
+    else {
+        const effAlpha = clamp01(fgParsed.rgba.a * opacity);
+        fg = toHex(fgParsed.rgba, effAlpha < 0.999 ? effAlpha : undefined);
+    }
+    const fontSizePx = parsePx(el.fontSize) ?? 0;
+    const strokeWidthPx = parsePx(el.textStrokeWidth);
+    const hasStroke = strokeWidthPx !== null && strokeWidthPx > 0;
+    return {
+        elementId: el.id,
+        fg,
+        backdrop,
+        ratio,
+        ratioReason,
+        fontSizePx,
+        fontWeight: el.fontWeight,
+        effectiveOpacity: opacity < 0.999 ? opacity : null,
+        shadowColor: firstShadowColor(el.textShadow, el.id),
+        strokeWidthPx: hasStroke ? strokeWidthPx : null,
+        strokeColor: hasStroke ? displayColor(el.textStrokeColor) : null,
+    };
+}
+/** Every color fact the capture supports, in document order -- the gate from
+ * `colorFactFor` applied once per element. */
+export function colorFactsForAll(elements, canvas) {
+    const byId = new Map(elements.map((el) => [el.id, el]));
+    const out = [];
+    for (const el of elements) {
+        const fact = colorFactFor(el, byId, elements, canvas);
+        if (fact)
+            out.push(fact);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Rendering: the §4 grammar
+// ---------------------------------------------------------------------------
+const px = (n) => Number.isInteger(n) ? String(n) : n.toFixed(1).replace(/\.0$/, '');
+const twoDp = (n) => n.toFixed(2);
+const trimmedDecimal = (n) => String(Math.round(n * 100) / 100);
+/** Just the `<bg>` half of the grammar -- reused by `q color`'s pair table
+ * and the digest header's `lowest` clause, which both need it without the
+ * rest of the line. */
+export function backdropLabel(backdrop) {
+    switch (backdrop.kind) {
+        case 'opaque':
+            return backdrop.self
+                ? `${backdrop.color} self`
+                : `${backdrop.color} via ${backdrop.via}${backdrop.layers > 0 ? ` (α×${backdrop.layers})` : ''}`;
+        case 'gradient':
+            return `gradient(${backdrop.from}→${backdrop.to}) ${backdrop.via}`;
+        case 'image': {
+            const c = backdrop.coverage;
+            return `image ${backdrop.via} (${c.boxWidth}x${c.boxHeight} of ${c.ofWidth}x${c.ofHeight})`;
+        }
+        case 'overlay':
+            return `unknown (${backdrop.reason} ${backdrop.via})`;
+        case 'not-captured':
+            return `unknown (not captured ${backdrop.via})`;
+        case 'canvas':
+            return 'unknown (canvas)';
+    }
+}
+const RATIO_UNMEASURED_LABEL = {
+    'color-space': 'unmeasured (color-space)',
+    'not-captured': 'unmeasured (not-captured)',
+    canvas: 'unmeasured (canvas)',
+};
+function ratioLabel(fact) {
+    if (fact.ratio !== null)
+        return twoDp(fact.ratio);
+    if (fact.ratioReason && RATIO_UNMEASURED_LABEL[fact.ratioReason]) {
+        return RATIO_UNMEASURED_LABEL[fact.ratioReason];
+    }
+    return 'unmeasured';
+}
+/**
+ * `color <fg> on <bg>; ratio <r>; <size>px/<weight>[; opacity ×<o>][; shadow
+ * <color>][; stroke <w>px <color>]` -- `docs/notes/03-color.md` §4, exactly.
+ */
+export function renderColorFact(fact) {
+    const head = `color ${fact.fg} on ${backdropLabel(fact.backdrop)}; ratio ${ratioLabel(fact)}; ${px(fact.fontSizePx)}px/${fact.fontWeight}`;
+    const tail = [];
+    if (fact.effectiveOpacity !== null)
+        tail.push(`opacity ×${trimmedDecimal(fact.effectiveOpacity)}`);
+    if (fact.shadowColor !== null)
+        tail.push(`shadow ${fact.shadowColor}`);
+    if (fact.strokeWidthPx !== null && fact.strokeColor !== null) {
+        tail.push(`stroke ${px(fact.strokeWidthPx)}px ${fact.strokeColor}`);
+    }
+    return tail.length > 0 ? `${head}; ${tail.join('; ')}` : head;
+}
+/**
+ * One row per (ink, backdrop) pair, not per element -- "thousands of
+ * elements compress to dozens of rows" (design note §6). `fg` and the
+ * rendered `<bg>` form together are the grouping key: two elements with the
+ * same ink over the same backdrop are, by construction, the same measured
+ * ratio.
+ */
+export function groupColorFacts(facts) {
+    const groups = new Map();
+    for (const fact of facts) {
+        const bgLabel = backdropLabel(fact.backdrop);
+        const key = `${fact.fg}\u0000${bgLabel}`;
+        let group = groups.get(key);
+        if (!group) {
+            group = {
+                fg: fact.fg,
+                bgLabel,
+                ratio: fact.ratio,
+                ratioReason: fact.ratioReason,
+                elementIds: [],
+                fontSizesPx: [],
+                weights: [],
+                effectiveOpacity: fact.effectiveOpacity,
+            };
+            groups.set(key, group);
+        }
+        group.elementIds.push(fact.elementId);
+        group.fontSizesPx.push(fact.fontSizePx);
+        group.weights.push(fact.fontWeight);
+    }
+    return [...groups.values()];
+}