automatica11y 0.3.1 → 0.3.3

package/src/data/wcag-2.2.source.json

@@ -0,0 +1,6 @@
+{
+  "source": "https://www.w3.org/WAI/WCAG22/wcag.json",
+  "about": "https://github.com/w3c/wcag/blob/main/11ty/json/README.md",
+  "retrieved": "2026-10-08",
+  "sha256": "3a034865a879a7d874b60ff2aec7f430cf37bc1597a1e00985680fd80ef5cf75"
+}

package/src/globals.d.ts

@@ -1,6 +1,7 @@
 /** Properties our init scripts and helpers put on the page's window. They only exist inside the browser. */
 interface Window {
   __a11y: any;
+  __a11yMeasure: any;
   __vsr: any;
   __a11yClicks: number;
   __a11yLast: any;

package/src/harness/bundle.js

@@ -5,6 +5,20 @@ const ASSET_LOADERS = /** @type {Record<string, import("esbuild").Loader>} */ (O
   [".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".woff", ".woff2", ".ttf", ".eot"].map((ext) => [ext, "dataurl"]),
 ));
 
+/**
+ * The package names esbuild couldn't resolve, such as `@emotion/react`. A subpath import counts as its package.
+ * @param {{ text?: string }[]} errors
+ * @returns {string[]}
+ */
+export function unresolvedPackages(errors) {
+  const names = new Set();
+  for (const { text = "" } of errors) {
+    const match = /^Could not resolve "([^".\/][^"]*)"/.exec(text);
+    if (match) names.add(match[1].split("/").slice(0, match[1].startsWith("@") ? 2 : 1).join("/"));
+  }
+  return [...names];
+}
+
 /**
  * Bundle fixture entries into one folder of browser-ready ES modules, plus one HTML shell per entry.
  * esbuild loads here and only here. It doesn't type-check, and fixtures don't need it to.
@@ -33,7 +47,7 @@ export async function bundleEntries({ entries, outdir, workDir, react = false })
     });
   } catch (error) {
     const messages = (error.errors ?? []).slice(0, 3).map((e) => `${e.text}${e.location ? ` (${e.location.file}:${e.location.line})` : ""}`);
-    throw new Error(`Bundling failed: ${messages.join("; ") || error.message}`);
+    throw Object.assign(new Error(`Bundling failed: ${messages.join("; ") || error.message}`), { unresolved: unresolvedPackages(error.errors ?? []) });
   }
   /** @type {Record<string, string>} */
   const pages = {};
@@ -41,7 +55,7 @@ export async function bundleEntries({ entries, outdir, workDir, react = false })
     const css = existsSync(join(outdir, `${name}.css`)) ? `<link rel="stylesheet" href="./${name}.css">` : "";
     writeFileSync(
       join(outdir, `${name}.html`),
-      `<!doctype html>\n<html lang="en">\n<head><meta charset="utf-8"><title>${name}</title><link rel="icon" href="data:,">${css}</head>\n<body><div id="root"></div><script type="module" src="./${name}.js"></script></body>\n</html>\n`,
+      `<!doctype html>\n<html lang="en">\n<head><meta charset="utf-8"><title>${name}</title><link rel="icon" href="data:,">${css}</head>\n<body><main><div id="root"></div></main><script type="module" src="./${name}.js"></script></body>\n</html>\n`,
     );
     pages[name] = `/${name}.html`;
   }

package/src/harness/npm-install.js

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 const NPM_FLAGS = ["--ignore-scripts", "--no-audit", "--no-fund", "--prefer-offline", "--loglevel=error"];
@@ -19,6 +19,9 @@ export function runNpm(args, cwd, { timeoutMs = 300_000 } = {}) {
   });
 }
 
+/** npm's local copy of a package list can lag behind the registry, so a version that exists looks missing. */
+const STALE_CACHE = /ETARGET|notarget|No matching version/i;
+
 /** The version of an installed package, or null. */
 export function installedVersion(dir, name) {
   try {
@@ -39,11 +42,23 @@ export async function installPackage({ dir, name, version, flavor, run = runNpm
   if (!existsSync(join(dir, "package.json"))) writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "automatica11y-target", private: true }));
   /** @type {string[]} */
   const warnings = [];
+  let refreshed = false;
+  /** Run npm. If it says a version doesn't exist, ask once more with fresh package data, since the version came from the registry. */
+  const npm = async (args) => {
+    try {
+      return await run(args, dir);
+    } catch (error) {
+      if (!STALE_CACHE.test(String(error.message)) || !args.includes("--prefer-offline")) throw error;
+      if (!refreshed) warnings.push(`npm's local list of ${name} versions was out of date, so the install refreshed it and tried again.`);
+      refreshed = true;
+      return run(args.map((arg) => (arg === "--prefer-offline" ? "--prefer-online" : arg)), dir);
+    }
+  };
   try {
-    await run(["install", `${name}@${version}`, ...NPM_FLAGS], dir);
+    await npm(["install", `${name}@${version}`, ...NPM_FLAGS]);
   } catch (error) {
     if (!/ERESOLVE|peer dep/i.test(String(error.message))) throw new Error(`npm couldn't install ${name}@${version}: ${firstLine(error.message)}`);
-    await run(["install", `${name}@${version}`, "--legacy-peer-deps", ...NPM_FLAGS], dir).catch((retry) => {
+    await npm(["install", `${name}@${version}`, "--legacy-peer-deps", ...NPM_FLAGS]).catch((retry) => {
       throw new Error(`npm couldn't install ${name}@${version}: ${firstLine(retry.message)}`);
     });
     warnings.push(`npm couldn't satisfy ${name}'s peer dependencies, so it installed them loosely (--legacy-peer-deps). Results may not match a supported setup.`);
@@ -51,15 +66,64 @@ export async function installPackage({ dir, name, version, flavor, run = runNpm
   if (flavor === "react") {
     const react = installedVersion(dir, "react");
     if (!react) {
-      await run(["install", "react", "react-dom", ...NPM_FLAGS, "--legacy-peer-deps"], dir);
+      await npm(["install", "react", "react-dom", ...NPM_FLAGS, "--legacy-peer-deps"]);
       warnings.push(`${name} didn't bring in react, so the latest react and react-dom were added.`);
     } else if (!installedVersion(dir, "react-dom")) {
-      await run(["install", `react-dom@${react}`, ...NPM_FLAGS, "--legacy-peer-deps"], dir);
+      await npm(["install", `react-dom@${react}`, ...NPM_FLAGS, "--legacy-peer-deps"]);
     }
   }
   return { dir, warnings, react: installedVersion(dir, "react"), reactDom: installedVersion(dir, "react-dom"), version: installedVersion(dir, name) };
 }
 
+/**
+ * Find the optional peer dependencies that installed packages declare, with the range each asks for.
+ * npm leaves these out, but a library's default setup can still need one (MUI needs an Emotion package).
+ * @param {string} dir The install folder.
+ * @returns {Map<string, string>} Package name to range.
+ */
+export function declaredOptionalPeers(dir) {
+  const root = join(dir, "node_modules");
+  const found = new Map();
+  const names = [];
+  for (const entry of existsSync(root) ? readdirSync(root) : []) {
+    if (entry.startsWith(".")) continue;
+    if (entry.startsWith("@")) for (const inner of readdirSync(join(root, entry))) names.push(`${entry}/${inner}`);
+    else names.push(entry);
+  }
+  for (const name of names) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(root, name, "package.json"), "utf8"));
+      for (const [peer, meta] of Object.entries(pkg.peerDependenciesMeta ?? {})) {
+        if (meta?.optional && pkg.peerDependencies?.[peer] && !found.has(peer)) found.set(peer, pkg.peerDependencies[peer]);
+      }
+    } catch {
+      // A folder without a readable package.json isn't a package.
+    }
+  }
+  return found;
+}
+
+/**
+ * Install the optional peer dependencies a failed bundle was missing. Only packages that an installed library
+ * declares as optional peers are added, so a typo in a fixture can't pull in an arbitrary package.
+ * @param {{ dir: string, unresolved: string[], run?: typeof runNpm }} options
+ * @returns {Promise<{ installed: string[], warnings: string[] }>}
+ */
+export async function installOptionalPeers({ dir, unresolved, run = runNpm }) {
+  const declared = declaredOptionalPeers(dir);
+  const wanted = unresolved.filter((name) => declared.has(name) && !installedVersion(dir, name));
+  if (wanted.length === 0) return { installed: [], warnings: [] };
+  // A loose install prunes packages that only arrived as peers, so name React again to keep it.
+  const keep = ["react", "react-dom"].flatMap((name) => (installedVersion(dir, name) ? [`${name}@${installedVersion(dir, name)}`] : []));
+  const specs = [...wanted.map((name) => `${name}@${declared.get(name)}`), ...keep];
+  try {
+    await run(["install", ...specs, "--legacy-peer-deps", ...NPM_FLAGS], dir);
+  } catch (error) {
+    throw new Error(`npm couldn't install the optional peer dependencies ${wanted.join(", ")}: ${firstLine(error.message)}`);
+  }
+  return { installed: wanted, warnings: [`The library lists ${wanted.join(", ")} as optional peer dependencies and its code needs them to load, so they were installed.`] };
+}
+
 function firstLine(text) {
   return String(text).split("\n").find((line) => line.trim())?.replace(/^npm (error|ERR!)\s*/i, "").trim() ?? "unknown error";
 }

package/src/plan/mapping.js

@@ -58,7 +58,8 @@ export function candidateMapping({ flavor, exports = [], tags = [] }) {
     const info = exports.find((e) => e.name === best);
     const parts = info?.parts ?? [];
     // Flat compound libraries (DialogRoot, DialogTrigger, DialogContent) have sibling exports that share a prefix.
-    const siblings = flavor === "react" ? names.filter((n) => n !== best && n.startsWith(best) && n.length > best.length) : [];
+    // A button or link usually sits beside ButtonBase, ButtonGroup, and the like, which aren't its parts, so only real parts (Button.Root) count there.
+    const siblings = flavor === "react" && !TEMPLATED.has(archetype) ? names.filter((n) => n !== best && n.startsWith(best) && n.length > best.length) : [];
     const compound = parts.length > 0 || siblings.length >= 2;
     const templated = TEMPLATED.has(archetype) && !compound;
     mapping[archetype] = {

package/src/plan/resolve-npm.js

@@ -53,7 +53,8 @@ export function detectFlavor(meta) {
   const peers = meta.peerDependencies ?? {};
   const deps = meta.dependencies ?? {};
   if ("react" in peers || "react-dom" in peers || "react" in deps) {
-    return { kind: "npm-react", framework: "React", reason: "The package lists react as a dependency." };
+    const how = "react" in peers || "react-dom" in peers ? "peer dependency" : "dependency";
+    return { kind: "npm-react", framework: "React", reason: `The package lists react as a ${how}.` };
   }
   if (meta.customElements) return { kind: "npm-wc", framework: "Web components", reason: "The package has a customElements manifest." };
   for (const [name, label] of Object.entries(OTHER_FRAMEWORKS)) {

package/src/report/comparison.js

@@ -15,7 +15,7 @@ import {
   targetSection,
 } from "./parts.js";
 
-const TIER_ORDER = ["rules", "interactions", "vsr"];
+const TIER_ORDER = ["rules", "interactions", "computed", "vsr"];
 
 /** The archetype rows: component archetypes in a fixed order, then whole pages, then Storybook stories. */
 function archetypeKeys(results) {
@@ -104,6 +104,16 @@ function interactionsCell(configs) {
   return parts.filter(Boolean).join("; ");
 }
 
+function computedCell(configs) {
+  const checks = configs.flatMap((c) => c.tiers.computed?.checks ?? []);
+  if (checks.length === 0) return configs.map((c) => c.tiers.computed?.status).find(Boolean) ?? "-";
+  const failed = checks.filter((c) => c.result === "fail").map((c) => code(c.name));
+  const unknown = checks.filter((c) => c.result === "undetermined").length;
+  const errors = checks.filter((c) => c.result === "error").length;
+  const parts = [failed.length ? `failed: ${failed.slice(0, 3).join(", ")}${failed.length > 3 ? `, and ${num(failed.length - 3)} more` : ""}` : "no failures", unknown ? `${num(unknown)} undetermined` : null, errors ? plural(errors, "error") : null];
+  return parts.filter(Boolean).join("; ");
+}
+
 function vsrCell(configs) {
   const walks = configs.map((c) => c.tiers.vsr).filter((v) => v?.status === "ran");
   if (walks.length === 0) return configs.map((c) => c.tiers.vsr?.status).find(Boolean) ?? "-";
@@ -113,17 +123,17 @@ function vsrCell(configs) {
 }
 
 function findingsTable(plan, results, key) {
-  const head = ["Target", "Configuration", ENGINE_NAMES.axe, ENGINE_NAMES.ibm, "Interactions", "Virtual screen reader (simulated)"];
+  const head = ["Target", "Configuration", ENGINE_NAMES.axe, ENGINE_NAMES.ibm, "Interactions", "Computed checks", "Virtual screen reader (simulated)"];
   const lines = [`| ${head.join(" | ")} |`, `| ${head.map(() => "---").join(" | ")} |`];
   for (const target of results.targets) {
     const planTarget = plan.targets.find((t) => t.id === target.id);
     for (const row of rowsFor(planTarget, target, key)) {
       if (row.note) {
-        lines.push(`| ${cell(target.id)} | ${cell(row.label)} | ${cell(row.note)} | | | |`);
+        lines.push(`| ${cell(target.id)} | ${cell(row.label)} | ${cell(row.note)} | | | | |`);
         continue;
       }
       const c = row.configs;
-      lines.push(`| ${cell(target.id)} | ${cell(row.label)} | ${cell(ruleCell(c, "axe"))} | ${cell(ruleCell(c, "ibm"))} | ${cell(interactionsCell(c))} | ${cell(vsrCell(c))} |`);
+      lines.push(`| ${cell(target.id)} | ${cell(row.label)} | ${cell(ruleCell(c, "axe"))} | ${cell(ruleCell(c, "ibm"))} | ${cell(interactionsCell(c))} | ${cell(computedCell(c))} | ${cell(vsrCell(c))} |`);
     }
   }
   return lines;

package/src/report/parts.js

@@ -1,3 +1,4 @@
+import { criterion, criterionName, wcagAttribution } from "../wcag/index.js";
 import { cap, num, plural } from "../text.js";
 
 /** Markdown helpers. */
@@ -8,7 +9,7 @@ export const sentence = (text) => String(text).replace(/\.+$/, "");
 /** Escape angle brackets so rule text like <input> doesn't turn into HTML. */
 export const esc = (text) => String(text ?? "").replace(/</g, "\\<");
 export const ENGINE_NAMES = { axe: "axe-core", ibm: "IBM Equal Access" };
-export const TIER_NAMES = { rules: "Rules", interactions: "Interactions", vsr: "Virtual screen reader" };
+export const TIER_NAMES = { rules: "Rules", interactions: "Interactions", computed: "Computed checks", vsr: "Virtual screen reader" };
 
 export function toolLines(tools) {
   return Object.entries(tools)
@@ -27,6 +28,11 @@ export function engineCell(summary, engine) {
 export function tierCell(target, tier) {
   const counts = target.summary?.interactions;
   const vsr = target.summary?.vsr;
+  const measured = target.summary?.computed;
+  if (tier === "computed" && measured) {
+    const parts = [measured.fail && `${num(measured.fail)} failed`, measured.undetermined && `${num(measured.undetermined)} undetermined`, measured.error && plural(measured.error, "error"), measured.pass && `${num(measured.pass)} passed`, measured.notApplicable && `${num(measured.notApplicable)} not applicable`].filter(Boolean);
+    return `ran, ${parts.join(", ")}`;
+  }
   if (tier === "vsr" && vsr) return `ran (simulated), ${vsr.flagged ? `${num(vsr.flagged)} flagged` : "none flagged"}`;
   if (tier === "interactions" && counts) {
     const parts = [counts.fail && plural(counts.fail, "failed", "failed"), counts.error && plural(counts.error, "error"), counts.pass && `${num(counts.pass)} passed`, counts.notApplicable && `${num(counts.notApplicable)} not applicable`].filter(Boolean);
@@ -58,7 +64,7 @@ export function findingBlock(finding, { showImpact, showToolkit }) {
     showImpact && finding.impact ? `impact: ${finding.impact}` : null,
     showToolkit && finding.toolkitLevel != null ? `IBM Toolkit level ${finding.toolkitLevel}` : null,
     finding.kind ? `kind: ${finding.kind}` : null,
-    finding.wcag.length ? `WCAG ${finding.wcag.join(", ")}` : null,
+    finding.wcag.length ? `WCAG ${finding.wcag.map(criterionName).join(", ")}` : null,
     plural(finding.nodeCount, "element"),
   ].filter(Boolean);
   const lines = [`- ${code(finding.ruleId)} (${meta.join("; ")}). ${esc(finding.help)} [Rule help](${finding.helpUrl})`];
@@ -200,7 +206,25 @@ export function interactionsSection(result, nested) {
   const lines = [`${nested ? "#####" : "####"} Interactions.`, "", "Each check ran on a fresh page, using only the trigger and root hooks and ARIA roles. A check that couldn't finish is an error, which counts as a gap and never as a pass.", ""];
   lines.push("| Check | Result | WCAG | Detail |", "| --- | --- | --- | --- |");
   for (const check of result.checks) {
-    lines.push(`| ${code(check.name)} | ${check.result} | ${cell((check.criteria ?? []).join(", ") || "-")} | ${cell(check.detail)}${check.method ? cell(` (method: ${check.method})`) : ""} |`);
+    lines.push(`| ${code(check.name)} | ${check.result} | ${cell(criteriaCell(check.criteria))} | ${cell(check.detail)}${check.method ? cell(` (method: ${check.method})`) : ""} |`);
+  }
+  return lines.join("\n");
+}
+
+/** Criterion numbers as links to the W3C text, with the W3C's name for each. Unknown numbers stay plain. */
+export function criteriaCell(list) {
+  if (!list || list.length === 0) return "-";
+  return list.map((num) => {
+    const c = criterion(num);
+    return c ? `[${c.num} ${c.handle}](${c.url})` : num;
+  }).join(", ");
+}
+
+export function computedSection(result, nested) {
+  const lines = [`${nested ? "#####" : "####"} Computed checks.`, "", "automatica11y's own measurements from resolved styles in the browser, with the numbers WCAG gives. They're reported on their own and never added to the axe-core or IBM Equal Access counts. A check that can't reduce the page to colors (a gradient, an image, transparency) is undetermined, which counts as a gap and never as a pass.", ""];
+  lines.push("| Check | Result | WCAG | Detail |", "| --- | --- | --- | --- |");
+  for (const check of result.checks) {
+    lines.push(`| ${code(check.name)} | ${check.result} | ${cell(criteriaCell(check.criteria))} | ${cell(check.detail)}${check.method ? cell(` (method: ${check.method})`) : ""} |`);
   }
   return lines.join("\n");
 }
@@ -250,6 +274,8 @@ export function targetSection(planTarget, target) {
           lines.push(vsrSection(result, name !== "page"), "");
         } else if (tier === "interactions" && result.status === "ran") {
           lines.push(interactionsSection(result, name !== "page"), "");
+        } else if (tier === "computed" && result.status === "ran") {
+          lines.push(computedSection(result, name !== "page"), "");
         } else if (result.status !== "ran") {
           skipped.add(`${TIER_NAMES[tier] ?? tier}: ${sentence(result.reason ?? result.status)}.`);
         }
@@ -326,6 +352,8 @@ export function reportFooter(results) {
     "",
     "Contrast results depend on how the browser rendered the page, so the browser version is recorded above.",
     "",
+    `**WCAG data.** ${wcagAttribution()}`,
+    "",
   );
   return lines;
 }

package/src/run/audit-npm.js

@@ -2,7 +2,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { bundleEntries } from "../harness/bundle.js";
-import { installPackage } from "../harness/npm-install.js";
+import { installOptionalPeers, installPackage } from "../harness/npm-install.js";
 import * as react from "../harness/npm-react.js";
 import * as wc from "../harness/npm-wc.js";
 import { closedShadowHosts, notTestableEntries } from "../harness/shadow.js";
@@ -10,6 +10,7 @@ import { serveStatic } from "../harness/static-serve.js";
 import { openPage } from "../harness/url.js";
 import { candidateMapping, findAuthoredFixture } from "../plan/mapping.js";
 import { ARCHETYPES } from "../schema.js";
+import { runComputed } from "../tiers/computed/index.js";
 import { runInteractions } from "../tiers/interactions/index.js";
 import { runRules } from "../tiers/rules/index.js";
 import { failedVsr, runVsr } from "../tiers/vsr.js";
@@ -40,12 +41,28 @@ function watchErrors(errors) {
   };
 }
 
+/**
+ * Bundle, and if the library needs an optional peer dependency that npm left out, install it and bundle once more.
+ * @param {Parameters<typeof bundleEntries>[0]} options
+ * @param {string[]} warnings Gets a note when peers were installed.
+ */
+async function bundleWithPeers(options, warnings) {
+  try {
+    return await bundleEntries(options);
+  } catch (error) {
+    const added = await installOptionalPeers({ dir: options.workDir, unresolved: error.unresolved ?? [] });
+    if (added.installed.length === 0) throw error;
+    warnings.push(...added.warnings);
+    return bundleEntries(options);
+  }
+}
+
 /** Load the whole package in a page to list its exports and the custom elements it defines. */
-async function discover({ browser, workDir, flavor, pkg, buildDir }) {
+async function discover({ browser, workDir, flavor, pkg, buildDir, warnings }) {
   const helper = flavor === "react" ? react : wc;
   const entryFile = join(workDir, "discover.js");
   writeFileSync(entryFile, helper.discoverEntry(pkg));
-  await bundleEntries({ entries: { discover: entryFile }, outdir: buildDir, workDir, react: flavor === "react" });
+  await bundleWithPeers({ entries: { discover: entryFile }, outdir: buildDir, workDir, react: flavor === "react" }, warnings);
   const server = await serveStatic(buildDir);
   const errors = [];
   try {
@@ -104,7 +121,7 @@ async function auditFixturePage({ browser, url, archetype, plan, libA11y }) {
       /** @type {Record<string, any>} */
       const tiers = {};
       for (const tier of plan.options.tiers) {
-        if (tier === "interactions") continue;
+        if (tier === "interactions" || tier === "computed") continue;
         if (tier === "vsr") tiers.vsr = failure ? { status: "skipped", simulated: true, reason: failure } : await runVsr(opened.page, { scope: "body", state }).catch(failedVsr);
         else if (failure) tiers.rules = { status: "failed", reason: failure, engines: Object.fromEntries(plan.options.engines.map((e) => [e, { status: "failed", reason: failure }])) };
         else {
@@ -117,6 +134,7 @@ async function auditFixturePage({ browser, url, archetype, plan, libA11y }) {
     const hidden = notTestableEntries(await closedShadowHosts(opened.page));
     // The checks open their own fresh pages, so run them after this page's rules results are in.
     if (plan.options.tiers.includes("interactions")) configs[0].tiers.interactions = await runInteractions(browser, libA11y === "n/a" ? url : `${url}?libA11y=${libA11y}`, archetype);
+    if (plan.options.tiers.includes("computed")) configs[0].tiers.computed = await runComputed(browser, libA11y === "n/a" ? url : `${url}?libA11y=${libA11y}`, archetype);
     return { configs, hidden };
   } finally {
     await opened.close();
@@ -164,7 +182,7 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
     const installed = await install({ dir: workDir, name: resolved.name, version: resolved.version, flavor });
     const warnings = [...installed.warnings];
 
-    const found = await discover({ browser, workDir, flavor: flavor === "react" ? "react" : "wc", pkg: resolved.name, buildDir });
+    const found = await discover({ browser, workDir, flavor: flavor === "react" ? "react" : "wc", pkg: resolved.name, buildDir, warnings });
     if (flavor === "unknown") {
       if (found.tags.length > 0) flavor = "wc";
       else if (installed.react && found.exports.some((e) => /^[A-Z]/.test(e.name))) flavor = "react";
@@ -219,7 +237,7 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
       mkdirSync(join(tmp, "entries"), { recursive: true });
       writeFileSync(entryFile, helper.entry(fixture, resolved.name));
       try {
-        await bundleEntries({ entries: { [archetype]: entryFile }, outdir: buildDir, workDir, react: flavor === "react" });
+        await bundleWithPeers({ entries: { [archetype]: entryFile }, outdir: buildDir, workDir, react: flavor === "react" }, warnings);
         runnable[archetype] = `/${archetype}.html`;
       } catch (error) {
         archetypes[archetype] = { status: "gap", reason: `The fixture didn't bundle. ${firstLine(error)}`, configs: [] };

package/src/run/run-plan.js

@@ -6,6 +6,7 @@ import { launchBrowser } from "../harness/browser.js";
 import { serveStatic } from "../harness/static-serve.js";
 import { listStories, readIndex, selectStories, storyUrl, waitForStory } from "../harness/storybook.js";
 import { closedShadowHosts, notTestableEntries } from "../harness/shadow.js";
+import { COMPUTED_NOT_APPLICABLE_FOR_PAGES } from "../tiers/computed/index.js";
 import { NOT_APPLICABLE_FOR_PAGES } from "../tiers/interactions/index.js";
 import { failedVsr, runVsr } from "../tiers/vsr.js";
 import { openPage } from "../harness/url.js";
@@ -37,6 +38,8 @@ async function auditPage(browser, url, planTarget, plan, extraWarnings) {
         tiers.rules = await runRules(opened.page, { engines: plan.options.engines, wcag: plan.options.wcag, level: plan.options.level });
       } else if (tier === "interactions") {
         tiers.interactions = NOT_APPLICABLE_FOR_PAGES;
+      } else if (tier === "computed") {
+        tiers.computed = COMPUTED_NOT_APPLICABLE_FOR_PAGES;
       } else {
         tiers.vsr = await runVsr(opened.page, { scope: "body" }).catch(failedVsr);
       }
@@ -71,7 +74,9 @@ async function auditStory(browser, base, story, plan) {
           ? await runRules(opened.page, { engines: plan.options.engines, wcag: plan.options.wcag, level: plan.options.level, scope: "#storybook-root" })
           : tier === "interactions"
             ? NOT_APPLICABLE_FOR_PAGES
-            : await runVsr(opened.page, { scope: "#storybook-root" }).catch(failedVsr);
+            : tier === "computed"
+              ? COMPUTED_NOT_APPLICABLE_FOR_PAGES
+              : await runVsr(opened.page, { scope: "#storybook-root" }).catch(failedVsr);
     }
     const hidden = notTestableEntries(await closedShadowHosts(opened.page));
     return { id: story.id, ok: true, archetype: { status: "ran", configs: [{ libA11y: "n/a", tiers }] }, hidden };

package/src/run/summary.js

@@ -32,6 +32,11 @@ export function summarize(archetypes, engines, gaps = []) {
     summary.interactions = { pass: 0, fail: 0, notApplicable: 0, error: 0 };
     for (const check of checks) summary.interactions[check.result === "not-applicable" ? "notApplicable" : check.result] += 1;
   }
+  const measured = Object.values(archetypes).flatMap((a) => a.configs.flatMap((c) => c.tiers.computed?.checks ?? []));
+  if (measured.length) {
+    summary.computed = { pass: 0, fail: 0, undetermined: 0, notApplicable: 0, error: 0 };
+    for (const check of measured) summary.computed[check.result === "not-applicable" ? "notApplicable" : check.result] += 1;
+  }
   const walks = Object.entries(archetypes).flatMap(([name, a]) => a.configs.map((c) => ({ name, vsr: c.tiers.vsr })).filter((x) => x.vsr?.status === "ran"));
   if (walks.length) {
     summary.vsr = { walks: walks.length, flagged: walks.reduce((n, w) => n + w.vsr.flags.length, 0) };

package/src/schema.js

@@ -2,7 +2,7 @@ import * as v from "valibot";
 
 export const WCAG_VERSIONS = ["2.0", "2.1", "2.2"];
 export const LEVELS = ["A", "AA", "AAA"];
-export const TIERS = ["rules", "interactions", "vsr"];
+export const TIERS = ["rules", "interactions", "computed", "vsr"];
 export const ENGINES = ["axe", "ibm"];
 export const LIB_A11Y = ["on", "off"];
 export const IMPACTS = ["minor", "moderate", "serious", "critical"];
@@ -136,10 +136,12 @@ const TierResultSchema = v.object({
       v.object({
         name: v.string(),
         criteria: v.optional(v.array(v.string())),
-        result: v.picklist(["pass", "fail", "not-applicable", "error"]),
+        result: v.picklist(["pass", "fail", "undetermined", "not-applicable", "error"]),
         detail: v.string(),
         /** How the focus indicator was detected: computed-style or screenshot. */
         method: v.optional(v.string()),
+        /** The numbers behind a computed check, for example contrast ratios by state. */
+        measurements: v.optional(v.array(v.record(v.string(), v.unknown()))),
       }),
     ),
   ),
@@ -218,6 +220,7 @@ export const TargetResultSchema = v.object({
     gaps: v.array(v.string()),
     notTestable: v.array(v.string()),
     interactions: v.optional(v.object({ pass: v.number(), fail: v.number(), notApplicable: v.number(), error: v.number() })),
+    computed: v.optional(v.object({ pass: v.number(), fail: v.number(), undetermined: v.number(), notApplicable: v.number(), error: v.number() })),
     vsr: v.optional(v.object({ walks: v.number(), flagged: v.number() })),
   }),
   warnings: v.array(v.string()),

package/src/tiers/computed/checks.js

@@ -0,0 +1,158 @@
+/**
+ * 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 { criterionRef } from "../../wcag/index.js";
+import { contrastOver, contrastRatio, formatRatio, 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 ? ` ${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 = `${px.strong} of ${px.changed} changed pixels reach 3:1 against their unfocused color, and the strongest change is ${formatRatio(px.max)}. A ring around this control needs about ${Math.round(perimeter)}.`;
+    return px.strong >= perimeter ? pass(detail, { method: "pixels", measurements }) : fail(detail, { method: "pixels", measurements });
+  },
+};
+
+export const COMPUTED_CHECKS = [TEXT_CONTRAST, BOUNDARY_CONTRAST, FOCUS_CONTRAST];