automatica11y 0.3.2 → 0.4.0

package/src/tiers/computed/checks.js

@@ -0,0 +1,197 @@
+/**
+ * The computed checks. Each reads resolved styles (and, for one case, pixels) from a real browser and compares
+ * them with the numbers WCAG gives. A check returns pass, fail, undetermined, or not-applicable with a detail.
+ * `undetermined` means the page uses something a color can't be reduced to (a gradient, an image, transparency).
+ * It's a gap and never a pass.
+ * These are automatica11y's own measurements. They're reported on their own and never added to axe-core or IBM counts.
+ */
+import { num } from "../../text.js";
+import { criterionRef } from "../../wcag/index.js";
+import { contrastOver, contrastRatio, formatRatio, ringIsEnough, textThreshold } from "./color.js";
+
+const pass = (detail, extra = {}) => ({ result: "pass", detail, ...extra });
+const fail = (detail, extra = {}) => ({ result: "fail", detail, ...extra });
+const na = (detail) => ({ result: "not-applicable", detail });
+const undetermined = (detail, extra = {}) => ({ result: "undetermined", detail, ...extra });
+
+/** Time for CSS transitions to finish before a state is measured. */
+const SETTLE_MS = 400;
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const floor2 = (n) => Math.floor(n * 100) / 100;
+
+/** Move the pointer away and let any hover styles end. */
+async function parkPointer(ctx) {
+  await ctx.page.mouse.move(0, 0);
+  await ctx.settle(SETTLE_MS);
+}
+
+/** Text contrast in each state a person can put the control in. */
+const TEXT_CONTRAST = {
+  name: "text-contrast-by-state",
+  criteria: ["1.4.3"],
+  async run(ctx) {
+    /** @type {Array<{ state: string, parts: any[] }>} */
+    const states = [];
+    const measure = async (state) => states.push({ state, parts: (await ctx.page.evaluate(() => window.__a11yMeasure.text())) ?? [] });
+    await parkPointer(ctx);
+    await measure("rest");
+    if (states[0].parts.length === 0) return na("The trigger has no visible text, so its text contrast wasn't measured.");
+    await ctx.trigger.hover();
+    await ctx.settle(SETTLE_MS);
+    await measure("hover");
+    await parkPointer(ctx);
+    const reached = await ctx.tabToTrigger();
+    await ctx.settle(SETTLE_MS);
+    if (reached !== null) await measure("keyboard focus");
+    await ctx.page.evaluate(() => /** @type {HTMLElement} */ (document.activeElement)?.blur?.());
+    await ctx.trigger.hover();
+    await ctx.page.mouse.down();
+    await ctx.settle(SETTLE_MS);
+    await measure("pressed");
+    await ctx.page.mouse.up().catch(() => {});
+
+    const rows = [];
+    const unknown = [];
+    for (const { state, parts } of states) {
+      for (const part of parts) {
+        if (part.undetermined || !part.backdrop) {
+          unknown.push(`In ${state}, "${part.text}" can't be measured because ${part.undetermined ?? "its background couldn't be read"}.`);
+          continue;
+        }
+        rows.push({ state, text: part.text, ratio: contrastOver(part.color, part.backdrop), required: textThreshold(part.size, part.weight) });
+      }
+    }
+    const measurements = rows.map((r) => ({ state: r.state, text: r.text, ratio: floor2(r.ratio), required: r.required }));
+    const failed = rows.filter((r) => r.ratio < r.required).sort((a, b) => a.ratio / a.required - b.ratio / b.required);
+    const list = `Measured in ${states.map((s) => s.state).join(", ")}.`;
+    const skipped = reached === null ? " The trigger couldn't be reached with Tab, so keyboard focus wasn't measured." : "";
+    if (failed.length) {
+      const f = failed[0];
+      const more = failed.length > 1 ? ` ${num(failed.length - 1)} more measurement${failed.length > 2 ? "s are" : " is"} below its threshold.` : "";
+      return fail(`In ${f.state}, "${f.text}" has ${formatRatio(f.ratio)} against its background and needs ${f.required}:1.${more} ${list}${skipped}`, { measurements });
+    }
+    if (unknown.length || reached === null) {
+      const low = rows.length ? `The lowest measured is ${formatRatio(Math.min(...rows.map((r) => r.ratio)))}. ` : "";
+      return undetermined(`${low}${unknown[0] ?? ""} ${list}${skipped}`.replace(/\s+/g, " ").trim(), { measurements });
+    }
+    const lowest = rows.reduce((a, b) => (b.ratio / b.required < a.ratio / a.required ? b : a));
+    return pass(`The lowest is ${formatRatio(lowest.ratio)} in ${lowest.state} (needs ${lowest.required}:1). ${list}`, { measurements });
+  },
+};
+
+/** The edge, fill, or icon that tells a person where a control is. */
+const BOUNDARY_CONTRAST = {
+  name: "boundary-contrast",
+  criteria: ["1.4.11"],
+  async run(ctx) {
+    await parkPointer(ctx);
+    const b = await ctx.page.evaluate(() => window.__a11yMeasure.boundary());
+    if (!b) return na("There's no trigger to measure.");
+    if (b.undetermined || !b.outside) return undetermined(`The control's edge can't be measured because ${b.undetermined ?? "its surroundings couldn't be read"}.`);
+    const fill = b.parts.find((p) => p.kind === "fill")?.color ?? b.outside;
+    const marks = [
+      ...b.parts.map((p) => ({ label: p.kind, ratio: contrastRatio(p.color, b.outside) })),
+      ...b.graphics.map((g) => ({ label: `icon ${g.kind}`, ratio: contrastRatio(g.color, fill) })),
+    ];
+    if (marks.length === 0) return undetermined("No border, fill, or icon was found to measure.");
+    const best = marks.reduce((a, c) => (c.ratio > a.ratio ? c : a));
+    const measurements = marks.map((m) => ({ part: m.label, ratio: floor2(m.ratio) }));
+    const text = `The strongest mark is its ${best.label}, at ${formatRatio(best.ratio)} (needs 3:1).`;
+    if (b.inputLike) return best.ratio >= 3 ? pass(`${text} A field's edge identifies it.`, { measurements }) : fail(`${text} A field has no label inside it, so its edge is what identifies it.`, { measurements });
+    if (b.hasText) {
+      return best.ratio >= 3
+        ? pass(text, { measurements })
+        : { ...na(`${text} The control has visible text that identifies it, so ${criterionRef("1.4.11")} doesn't require its edge to reach 3:1. A person should confirm the text is enough.`), measurements };
+    }
+    return best.ratio >= 3 ? pass(`${text} The control has no text, so its icon or edge identifies it.`, { measurements }) : fail(`${text} The control has no text, so its icon or edge has to identify it.`, { measurements });
+  },
+};
+
+/** Does the focus indicator stand out from what's around it? */
+const FOCUS_CONTRAST = {
+  name: "focus-indicator-contrast",
+  criteria: ["1.4.11", "2.4.13"],
+  async run(ctx) {
+    await parkPointer(ctx);
+    const rest = await ctx.page.evaluate(() => window.__a11yMeasure.focusStyles(true));
+    if (!rest) return na("There's no trigger to measure.");
+    const clip = ctx.clipAround(rest.box, 12);
+    const shotRest = await ctx.page.screenshot({ clip });
+    if ((await ctx.tabToTrigger()) === null) return na("The trigger can't be reached with Tab, so its focus indicator wasn't measured.");
+    await ctx.settle(SETTLE_MS);
+    const now = await ctx.page.evaluate(() => window.__a11yMeasure.focusStyles(false));
+
+    // First choice: an outline, ring, or border on the control itself. Its colors and thickness are exact.
+    if (now && !now.undetermined && now.outside && now.inside) {
+      const found = [];
+      if (now.outline && !same(now.outline, rest.outline)) {
+        const against = now.outline.offset >= 0 ? now.outside : now.inside;
+        found.push({ label: "outline", ratio: contrastOver(now.outline.color, against), width: now.outline.width });
+      }
+      for (const shadow of now.shadows) {
+        if (shadow.inset || shadow.blur > 0 || !shadow.color || shadow.color[3] === 0 || (shadow.spread <= 0 && shadow.x === 0 && shadow.y === 0)) continue;
+        if (rest.shadows.some((r) => same(r, shadow))) continue;
+        found.push({ label: "box-shadow ring", ratio: contrastOver(shadow.color, now.outside), width: Math.max(shadow.spread, Math.abs(shadow.x), Math.abs(shadow.y)) });
+      }
+      if (now.border && !same(now.border, rest.border)) found.push({ label: "border", ratio: contrastOver(now.border.color, now.outside), width: now.border.width });
+      if (found.length) {
+        const best = found.reduce((a, c) => (c.ratio > a.ratio ? c : a));
+        const thin = best.width < 2 ? ` It's ${best.width}px thick, and ${criterionRef("2.4.13")} asks for at least 2px.` : "";
+        const detail = `The ${best.label} has ${formatRatio(best.ratio)} against what's next to it (needs 3:1).${thin}`;
+        const measurements = found.map((f) => ({ indicator: f.label, ratio: floor2(f.ratio), widthPx: f.width }));
+        return best.ratio >= 3 ? pass(detail, { method: "computed-style", measurements }) : fail(detail, { method: "computed-style", measurements });
+      }
+    }
+
+    // Otherwise the indicator is something styles can't summarize (a ripple, a background change, a blurred glow), so compare pixels.
+    const shotNow = await ctx.page.screenshot({ clip });
+    const url = (buffer) => `data:image/png;base64,${buffer.toString("base64")}`;
+    const px = await ctx.page.evaluate(([a, b]) => window.__a11yMeasure.compareShots(a, b), [url(shotRest), url(shotNow)]);
+    if (px.changed === 0) return na("Nothing visible changed on focus, so there's no indicator to measure. The interactions tier reports that as a failure.");
+    const perimeter = 2 * (rest.box.width + rest.box.height);
+    const measurements = [{ changedPixels: px.changed, pixelsAtLeast3to1: px.strong, strongestChange: floor2(px.max), perimeterPixels: Math.round(perimeter) }];
+    const detail = `${num(px.strong)} of ${num(px.changed)} changed pixels reach 3:1 against their unfocused color, and the strongest change is ${formatRatio(px.max)}. Enough to count is about half the control's perimeter, ${Math.round(perimeter / 2)}.`;
+    return ringIsEnough(px.strong, perimeter) ? pass(detail, { method: "pixels", measurements }) : fail(detail, { method: "pixels", measurements });
+  },
+};
+
+/**
+ * For a live region, the trigger is only a button that makes the message appear, so the message is what gets measured:
+ * the text that appears after the trigger is activated, in its resting state.
+ */
+const MESSAGE_TEXT_CONTRAST = {
+  name: "message-text-contrast",
+  criteria: ["1.4.3"],
+  async run(ctx) {
+    await parkPointer(ctx);
+    const before = (await ctx.page.evaluate(() => window.__a11yMeasure.text("page"))) ?? [];
+    await ctx.focus();
+    await ctx.press("Enter");
+    await ctx.settle(SETTLE_MS);
+    const after = (await ctx.page.evaluate(() => window.__a11yMeasure.text("page"))) ?? [];
+    const known = new Set(before.map((p) => p.key));
+    const fresh = after.filter((p) => !known.has(p.key));
+    if (fresh.length === 0) return na("No new visible text appeared when the trigger was activated, so there's no message text to measure.");
+    const rows = [];
+    const unknown = [];
+    for (const part of fresh) {
+      if (part.undetermined || !part.backdrop) unknown.push(`"${part.text}" can't be measured because ${part.undetermined ?? "its background couldn't be read"}.`);
+      else rows.push({ text: part.text, ratio: contrastOver(part.color, part.backdrop), required: textThreshold(part.size, part.weight) });
+    }
+    const measurements = rows.map((r) => ({ text: r.text, ratio: floor2(r.ratio), required: r.required }));
+    const failed = rows.filter((r) => r.ratio < r.required).sort((a, b) => a.ratio / a.required - b.ratio / b.required);
+    if (failed.length) return fail(`The message text "${failed[0].text}" has ${formatRatio(failed[0].ratio)} against its background and needs ${failed[0].required}:1.`, { measurements });
+    if (unknown.length) return undetermined(`${rows.length ? `The lowest measured is ${formatRatio(Math.min(...rows.map((r) => r.ratio)))}. ` : ""}${unknown[0]}`, { measurements });
+    const lowest = rows.reduce((a, b) => (b.ratio / b.required < a.ratio / a.required ? b : a));
+    return pass(`The message text "${lowest.text}" has ${formatRatio(lowest.ratio)} against its background (needs ${lowest.required}:1).`, { measurements });
+  },
+};
+
+/** The checks that apply to an archetype. */
+export function computedChecksFor(archetype) {
+  return archetype === "live-region" ? [MESSAGE_TEXT_CONTRAST] : [TEXT_CONTRAST, BOUNDARY_CONTRAST, FOCUS_CONTRAST];
+}
+
+/** Every computed check, for tests and docs. */
+export const COMPUTED_CHECKS = [TEXT_CONTRAST, BOUNDARY_CONTRAST, FOCUS_CONTRAST, MESSAGE_TEXT_CONTRAST];

package/src/tiers/computed/color.js

@@ -0,0 +1,48 @@
+/**
+ * Color math for the computed tier. Colors are `[r, g, b, a]` with r, g, and b from 0 to 255 and a from 0 to 1.
+ * The page turns every CSS color into this form (see measure-kit.js), so this file never parses CSS.
+ */
+
+/** Relative luminance of an opaque color, as WCAG defines it. */
+export function luminance([r, g, b]) {
+  const lin = (c) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** Lay `top` over an opaque `under` color. The result is opaque. */
+export function composite(top, under) {
+  const a = top[3];
+  return [0, 1, 2].map((i) => top[i] * a + under[i] * (1 - a)).concat(1);
+}
+
+/** WCAG contrast ratio between two opaque colors, from 1 to 21. */
+export function contrastRatio(a, b) {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Contrast of a possibly translucent foreground over an opaque background. */
+export function contrastOver(fg, bg) {
+  return contrastRatio(composite(fg, bg), bg);
+}
+
+/** The ratio text needs: 3 for large text (24px, or 18.66px and bold), and 4.5 for the rest. */
+export function textThreshold(sizePx, weight) {
+  return sizePx >= 24 || (sizePx >= 18.66 && Number(weight) >= 700) ? 3 : 4.5;
+}
+
+/**
+ * Is a focus change big enough to count as an indicator? Pixels that change by 3:1 or more have to cover at least half the
+ * control's perimeter: a ring or underline a person can't miss, even with anti-aliased edges and rounded corners.
+ */
+export function ringIsEnough(strongPixels, perimeter) {
+  return strongPixels >= perimeter / 2;
+}
+
+/** "4.52:1". The ratio is cut down, never rounded up, so 2.999 never reads as 3. */
+export function formatRatio(ratio) {
+  return `${(Math.floor(ratio * 100) / 100).toFixed(2).replace(/\.?0+$/, "")}:1`;
+}

package/src/tiers/computed/index.js

@@ -0,0 +1,25 @@
+import { installHelpers } from "../interactions/helpers.js";
+import { runCheck } from "../interactions/index.js";
+import { computedChecksFor } from "./checks.js";
+import { installMeasure } from "./measure-kit.js";
+
+/**
+ * Run the computed checks for one archetype against its fixture page. Each check gets a fresh page.
+ * A check that can't finish reports `error`, and one that can't reduce the page to colors reports `undetermined`.
+ * Neither counts as a pass.
+ * @param {import("playwright-core").Browser} browser
+ * @param {string} url
+ * @param {string} archetype
+ */
+export async function runComputed(browser, url, archetype) {
+  if (archetype === "chart") return { status: "not-applicable", reason: "The chart archetype has no trigger to measure." };
+  const results = [];
+  for (const check of computedChecksFor(archetype)) results.push(await runCheck(browser, url, check, { kits: [installHelpers, installMeasure] }));
+  return { status: "ran", checks: results };
+}
+
+/** What a page or Storybook target says about this tier. */
+export const COMPUTED_NOT_APPLICABLE_FOR_PAGES = {
+  status: "not-applicable",
+  reason: "Computed checks need an archetype fixture with a trigger hook. Page and Storybook targets don't have one.",
+};

package/src/tiers/computed/measure-kit.js

@@ -0,0 +1,225 @@
+/**
+ * Runs inside the page before any page script. It sets `window.__a11yMeasure`, which reads resolved styles
+ * (getComputedStyle) and turns them into plain numbers: colors as [r, g, b, a], sizes in pixels.
+ * It never decides pass or fail. The checks in checks.js do that.
+ * This function is serialized and sent to the browser, so it can't use anything from outside itself.
+ */
+export function installMeasure() {
+  const canvas = document.createElement("canvas");
+  canvas.width = 1;
+  canvas.height = 1;
+  const context = canvas.getContext("2d", { willReadFrequently: true });
+
+  /** Any CSS color to [r, g, b, a] in sRGB, or null. The canvas does the conversion, so modern color spaces work. */
+  const rgba = (css) => {
+    if (!css || !context) return null;
+    context.clearRect(0, 0, 1, 1);
+    context.fillStyle = "#000";
+    context.fillStyle = css;
+    context.fillRect(0, 0, 1, 1);
+    const [r, g, b, a] = context.getImageData(0, 0, 1, 1).data;
+    // The canvas stores premultiplied values, so a translucent color loses a little precision. That's fine for contrast.
+    return a === 0 ? [0, 0, 0, 0] : [r, g, b, a / 255];
+  };
+  const over = (top, under) => [0, 1, 2].map((i) => top[i] * top[3] + under[i] * (1 - top[3])).concat(1);
+  const parentOf = (el) => el.assignedSlot || el.parentElement || (el.getRootNode() instanceof ShadowRoot ? el.getRootNode().host : null);
+
+  /**
+   * The opaque color behind an element: its ancestors' backgrounds laid over each other, ending at white.
+   * `includeSelf` adds the element's own background. Gradients, images, and transparency can't be reduced to one color,
+   * so those return a reason instead of a guess.
+   */
+  const backdrop = (el, includeSelf) => {
+    const layers = [];
+    let node = includeSelf ? el : parentOf(el);
+    for (let hops = 0; node && hops < 60; hops += 1) {
+      const style = getComputedStyle(node);
+      if (style.backgroundImage !== "none") return { reason: "a background image or gradient sits behind it" };
+      if (Number(style.opacity) < 1) return { reason: "an element behind it is partly transparent" };
+      if (style.mixBlendMode !== "normal") return { reason: "a blend mode is applied behind it" };
+      const color = rgba(style.backgroundColor);
+      if (color && color[3] > 0) {
+        layers.push(color);
+        if (color[3] === 1) break;
+      }
+      node = parentOf(node);
+    }
+    let result = [255, 255, 255, 1];
+    for (const layer of layers.reverse()) result = over(layer, result);
+    return { color: result };
+  };
+
+  const visibleBox = (el) => {
+    const box = el.getBoundingClientRect();
+    return box.width > 0 && box.height > 0;
+  };
+  const deepActive = () => {
+    let active = document.activeElement;
+    while (active && active.shadowRoot && active.shadowRoot.activeElement) active = active.shadowRoot.activeElement;
+    return active;
+  };
+  const trigger = () => {
+    const find = (root) => {
+      const hit = root.querySelector("[data-a11y-trigger]");
+      if (hit) return hit;
+      for (const el of root.querySelectorAll("*")) if (el.shadowRoot) { const inner = find(el.shadowRoot); if (inner) return inner; }
+      return null;
+    };
+    return find(document);
+  };
+
+  /** Split a computed box-shadow list at its top-level commas. */
+  const splitShadows = (value) => {
+    const out = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < value.length; i += 1) {
+      if (value[i] === "(") depth += 1;
+      else if (value[i] === ")") depth -= 1;
+      else if (value[i] === "," && depth === 0) { out.push(value.slice(start, i).trim()); start = i + 1; }
+    }
+    out.push(value.slice(start).trim());
+    return out.filter(Boolean);
+  };
+  const parseShadow = (text) => {
+    const color = /(rgba?\([^)]*\)|color\([^)]*\)|oklab\([^)]*\)|oklch\([^)]*\)|lab\([^)]*\)|lch\([^)]*\)|hsla?\([^)]*\)|#[0-9a-f]{3,8}|\b[a-z]+\b(?=\s|$))/i.exec(text.replace(/\binset\b/, ""));
+    const rest = text.replace(/\binset\b/, "").replace(color ? color[0] : "", "");
+    const [x, y, blur, spread] = (rest.match(/-?[\d.]+px/g) ?? []).map(parseFloat);
+    return { inset: /\binset\b/.test(text), x: x ?? 0, y: y ?? 0, blur: blur ?? 0, spread: spread ?? 0, color: color ? rgba(color[0]) : null };
+  };
+
+  const keys = new WeakMap();
+  let keyCounter = 0;
+
+  window.__a11yMeasure = {
+    rgba,
+    /**
+     * The text inside the trigger (or, with "page", anywhere on the page except the trigger): each piece of text with its
+     * color, size, and backdrop. Slotted text takes its style from the slot's parent in the flattened tree, and text that is
+     * visually hidden (a one-pixel screen reader copy) is left out. `key` lets a later call tell which text is new.
+     */
+    text(scope) {
+      const wholePage = scope === "page" || scope === "all";
+      const el = trigger();
+      if (!el && !wholePage) return null;
+      const parts = [];
+      const seen = new Set();
+      const consider = (textNode, label, own) => {
+        const host = own ?? textNode.parentElement;
+        const node = own ?? textNode.assignedSlot ?? host;
+        if (!host || !node || seen.has(textNode) || !visibleBox(host)) return;
+        const box = host.getBoundingClientRect();
+        if (box.width <= 1 && box.height <= 1) return;
+        seen.add(textNode);
+        const style = getComputedStyle(node);
+        if (style.visibility === "hidden") return;
+        if (!keys.has(textNode)) keys.set(textNode, (keyCounter += 1));
+        const behind = backdrop(node, true);
+        const color = rgba(style.color);
+        parts.push({
+          key: keys.get(textNode),
+          text: label.replace(/\s+/g, " ").trim().slice(0, 40),
+          color,
+          size: parseFloat(style.fontSize),
+          weight: style.fontWeight,
+          backdrop: behind.color ?? null,
+          undetermined: behind.reason ?? (color ? null : "its color couldn't be read"),
+        });
+      };
+      const walk = (root) => {
+        const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, wholePage ? { acceptNode: (n) => (n.parentElement?.closest(scope === "all" ? "script, style, noscript" : "script, style, noscript, [data-a11y-trigger]") ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT) } : undefined);
+        for (let node = walker.nextNode(); node && parts.length < (scope === "all" ? 300 : 30); node = walker.nextNode()) {
+          if (node.nodeValue && node.nodeValue.trim() && node.parentElement) consider(node, node.nodeValue);
+        }
+        if (wholePage) for (const host of root.querySelectorAll("*")) if (host.shadowRoot) walk(host.shadowRoot);
+      };
+      walk(wholePage ? document.body : el);
+      if (!wholePage && el.matches("input, textarea, select") && "value" in el && String(el.value).trim()) {
+        consider(el, String(el.value), el);
+      }
+      return parts;
+    },
+    /** What the control looks like from outside: label, input, or icon, and the colors that mark its edge. */
+    boundary() {
+      const el = trigger();
+      if (!el) return null;
+      const style = getComputedStyle(el);
+      const outside = backdrop(el, false);
+      const inside = backdrop(el, true);
+      const parts = [];
+      if (outside.color && inside.color) {
+        parts.push({ kind: "fill", color: inside.color });
+        for (const side of ["Top", "Right", "Bottom", "Left"]) {
+          const border = parseFloat(style[`border${side}Width`]) > 0 && style[`border${side}Style`] !== "none" ? rgba(style[`border${side}Color`]) : null;
+          if (border && border[3] > 0) parts.push({ kind: `${side.toLowerCase()} border`, color: over(border, inside.color), width: parseFloat(style[`border${side}Width`]) });
+        }
+      }
+      const graphics = [];
+      for (const shape of el.querySelectorAll("svg path, svg circle, svg ellipse, svg rect, svg line, svg polyline, svg polygon")) {
+        const s = getComputedStyle(shape);
+        for (const [kind, value] of [["fill", s.fill], ["stroke", s.stroke]]) {
+          const color = value && value !== "none" ? rgba(value) : null;
+          if (color && color[3] > 0 && visibleBox(shape) && inside.color) graphics.push({ kind, color: over(color, inside.color) });
+        }
+      }
+      return {
+        outside: outside.color ?? null,
+        undetermined: outside.reason ?? inside.reason ?? null,
+        parts,
+        graphics: graphics.slice(0, 12),
+        hasText: (el.innerText ?? el.textContent ?? "").trim().length > 0 || (el.matches("input, textarea, select") && "value" in el && String(el.value).trim().length > 0),
+        inputLike: el.matches("input:not([type=button]):not([type=submit]):not([type=reset]):not([type=checkbox]):not([type=radio]), textarea, select") || ["textbox", "combobox", "searchbox", "listbox"].includes(el.getAttribute("role") ?? ""),
+        box: (() => { const b = el.getBoundingClientRect(); return { x: b.x, y: b.y, width: b.width, height: b.height }; })(),
+      };
+    },
+    /** The styles that draw a focus indicator on the focused element itself, with the colors they sit against. */
+    focusStyles(atRest) {
+      const el = atRest ? trigger() : deepActive();
+      if (!el) return null;
+      const style = getComputedStyle(el);
+      const outside = backdrop(el, false);
+      const inside = backdrop(el, true);
+      const side = ["Top", "Right", "Bottom", "Left"].find((name) => parseFloat(style[`border${name}Width`]) > 0 && style[`border${name}Style`] !== "none");
+      const border = side ? rgba(style[`border${side}Color`]) : null;
+      return {
+        outside: outside.color ?? null,
+        inside: inside.color ?? null,
+        undetermined: outside.reason ?? inside.reason ?? null,
+        outline: style.outlineStyle !== "none" && parseFloat(style.outlineWidth) > 0 ? { width: parseFloat(style.outlineWidth), offset: parseFloat(style.outlineOffset) || 0, color: rgba(style.outlineColor) } : null,
+        shadows: style.boxShadow === "none" ? [] : splitShadows(style.boxShadow).map(parseShadow),
+        border: border ? { width: parseFloat(style[`border${side}Width`]), color: border } : null,
+        box: (() => { const b = el.getBoundingClientRect(); return { x: b.x, y: b.y, width: b.width, height: b.height }; })(),
+      };
+    },
+    /**
+     * Compare two screenshots (as data URLs) pixel by pixel. For each pixel that changed, find the contrast between
+     * its two colors. Used when a focus indicator isn't a plain outline or ring, such as a ripple or a background change.
+     */
+    async compareShots(before, after) {
+      const load = async (url) => {
+        const bitmap = await createImageBitmap(await (await fetch(url)).blob());
+        const c = document.createElement("canvas");
+        c.width = bitmap.width;
+        c.height = bitmap.height;
+        const ctx = c.getContext("2d", { willReadFrequently: true });
+        ctx.drawImage(bitmap, 0, 0);
+        return ctx.getImageData(0, 0, c.width, c.height);
+      };
+      const [a, b] = [await load(before), await load(after)];
+      const lin = (v) => { const s = v / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; };
+      const lum = (d, i) => 0.2126 * lin(d[i]) + 0.7152 * lin(d[i + 1]) + 0.0722 * lin(d[i + 2]);
+      let changed = 0;
+      let strong = 0;
+      let max = 1;
+      for (let i = 0; i < a.data.length; i += 4) {
+        if (a.data[i] === b.data[i] && a.data[i + 1] === b.data[i + 1] && a.data[i + 2] === b.data[i + 2]) continue;
+        changed += 1;
+        const [hi, lo] = [lum(a.data, i), lum(b.data, i)].sort((x, y) => y - x);
+        const ratio = (hi + 0.05) / (lo + 0.05);
+        if (ratio > max) max = ratio;
+        if (ratio >= 3) strong += 1;
+      }
+      return { changed, strong, max, width: a.width, height: a.height };
+    },
+  };
+}