@burdenoff/fe-libs 2026.825.1 → 2026.825.2

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@burdenoff/fe-libs",
-  "version": "2026.825.1",
+  "version": "2026.825.2",
   "description": "Burdenoff frontend primitives and domain libraries",
   "type": "module",
   "bin": {
-    "graphql-schema-drift": "./scripts/graphql-schema-drift/cli.ts"
+    "graphql-schema-drift": "./scripts/graphql-schema-drift/cli.ts",
+    "a11y-audit": "./scripts/a11y-audit/cli.ts"
   },
   "imports": {
     "#lib/*": "./src/lib/*",
@@ -283,6 +284,8 @@
     "src/vite/**/*",
     "scripts/graphql-schema-drift/*.ts",
     "scripts/graphql-schema-drift/README.md",
+    "scripts/a11y-audit/*.ts",
+    "scripts/a11y-audit/README.md",
     "README.md",
     "LICENSE"
   ],
@@ -293,7 +296,7 @@
     "lint:sanity": "if [ \"${CI:-}\" = \"true\" ]; then bun run lint; else bun run lint -- --cache --cache-location .eslintcache; fi",
     "format": "prettier --config shared/config/prettier.config.mjs --write \"src/**/*.{ts,tsx}\" \"!src/config/*.config.ts\"",
     "type:check": "bash scripts/build-limits.sh tsc --noEmit",
-    "test": "bun test scripts/graphql-schema-drift/__tests__ src/credentials src/storage src/shared/assistant src/shared/providers/AppShellProvider.test.ts src/shared/events/sinks/RybbitSink.test.ts src/shell-native src/shared/native src/chrome/__tests__ src/ui/__tests__",
+    "test": "bun test scripts/graphql-schema-drift/__tests__ scripts/a11y-audit/__tests__ src/credentials src/storage src/shared/assistant src/shared/providers/AppShellProvider.test.ts src/shared/events/sinks/RybbitSink.test.ts src/shell-native src/shared/native src/chrome/__tests__ src/ui/__tests__",
     "sanity": "bash scripts/build-limits.sh --gate bash -c 'bun run lint:sanity && bun run format && bun run type:check && bun run test && bun run build'",
     "switch:status": "bun scripts/deps-mode.ts status",
     "switch:remote": "bun scripts/deps-mode.ts remote",

package/scripts/a11y-audit/README.md

@@ -0,0 +1,172 @@
+# a11y-audit — the fleet WCAG 2.1 AA gate
+
+A real axe-core run against a built app shell, microfrontend or website, wired to
+fail a build on `serious` **and** `critical` violations, with an explicit
+allowlist for the exceptions you have decided to live with.
+
+It exists because the thing it replaces did not work. Several repos had an
+`@axe-core/playwright` spec checked in, but:
+
+- no CI workflow ever executed it, and
+- where it did assert, it asserted `impact === 'critical'` only, through
+  `expect.soft(...)`, which records a failure and then lets the run pass.
+
+So the fleet's accessibility posture was "not assessed" while looking assessed.
+
+## What it does
+
+For every configured route × viewport:
+
+1. serves the built app (or points at a running one),
+2. navigates, waits for the DOM to stop changing, and refuses to audit a page
+   that never painted,
+3. runs axe-core with the WCAG 2.1 A + AA tag set,
+4. splits every failing DOM node into **blocking** / **allowlisted** /
+   **advisory**,
+5. writes a JSON report and a GitHub step summary,
+6. exits non-zero when anything blocking survives.
+
+Exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | no blocking violations |
+| `1` | blocking violations (or stale allowlist entries with `failOnStaleAllowlist`) |
+| `2` | the audit could not run — invalid config, app never came up, a route failed to load or never rendered |
+
+Exit `2` matters as much as exit `1`. An audit that could not look at a page is
+reported as a failure to audit, never as a pass.
+
+## Install in a repo
+
+```bash
+bun add -d @playwright/test @axe-core/playwright
+bunx playwright install --with-deps chromium
+```
+
+`@burdenoff/fe-libs` ships the runner as a package `bin`, so either of these works
+from the repo root:
+
+```bash
+a11y-audit
+bun run node_modules/@burdenoff/fe-libs/scripts/a11y-audit/cli.ts
+```
+
+Add the script to `package.json`:
+
+```json
+"a11y": "bun run node_modules/@burdenoff/fe-libs/scripts/a11y-audit/cli.ts"
+```
+
+Playwright and axe are imported dynamically, so fe-libs itself does not drag a
+browser automation stack into every consumer of the component library.
+
+## Config
+
+`a11y-audit.config.json` at the repo root (or pass a path as the first argument).
+
+```jsonc
+{
+  "name": "vibecontrols-app",
+  "serve": { "staticDir": "dist", "spa": true },
+  "routes": [
+    { "path": "/", "name": "landing" },
+    { "path": "/auth/login", "name": "auth-login" }
+  ],
+  "viewports": [
+    { "name": "desktop", "width": 1280, "height": 800 },
+    { "name": "mobile", "width": 390, "height": 844 }
+  ],
+  "settleMs": 1000,
+  "domQuietMs": 2000,
+  "allowlist": []
+}
+```
+
+### `serve` — exactly one mode
+
+| Mode | Use for | Example |
+| --- | --- | --- |
+| `staticDir` | app shells and websites, which build to a servable `dist/` | `{ "staticDir": "dist", "spa": true }` |
+| `command` + `port` | microfrontends, which build to a library and need their Vite harness to render | `{ "command": "bun run dev --port 4180", "port": 4180 }` |
+| `baseUrl` | an already-running target (preview deploy, alpha, prod) | `{ "baseUrl": "https://alphaapp.vibecontrols.com" }` |
+
+`spa: true` (the default) serves `index.html` for extension-less paths so
+client-routed URLs resolve. Missing *assets* still 404 — a broken bundle must not
+be laundered into a page load.
+
+`--base-url=URL` on the command line overrides whatever the config says, which is
+how you point the same config at alpha or prod.
+
+### Determinism knobs
+
+| Key | Default | Why |
+| --- | --- | --- |
+| `blockExternalRequests` | `true` | Aborts every request leaving the app's own origin. Without it, axe races backend latency: the same route audits a splash screen on one run and a rendered page on the next. Set `false` when auditing a live deployment where the backend is part of the subject. |
+| `settleMs` | `1500` | Fixed delay after `load` before quiescence polling starts. |
+| `domQuietMs` | `1500` | The DOM must stop changing (text length and element count) for this long before axe runs. |
+| `minTextLength` | `100` | A route that renders less than this much text is reported as **not audited** (exit 2), never as a pass. |
+| `navigationTimeoutMs` | `45000` | Per-navigation and per-quiescence ceiling. |
+
+Per route you can also set `waitForSelector` and a route-specific `settleMs`.
+
+### `failOn`
+
+Defaults to `["critical", "serious"]`. It may be **widened** (adding `moderate`),
+never narrowed — a config that drops `critical` or `serious` is rejected. That is
+the fleet floor and the gate refuses to run below it.
+
+## The allowlist
+
+There is deliberately **no** way to disable a rule. The only suppression
+mechanism is an allowlist entry, and every entry must say why.
+
+```jsonc
+{
+  "rule": "color-contrast",
+  "reason": "Stripe's hosted card iframe; contrast is fixed upstream and we cannot restyle it.",
+  "routes": ["/billing/*"],
+  "selectors": ["#stripe-card-frame"],
+  "expires": "2026-12-31",
+  "ticket": "BOFF-1234"
+}
+```
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `rule` | yes | one axe rule id. Wildcards (`*`, `**`, `.*`) are rejected. |
+| `reason` | yes | ≥ 20 characters of actual prose. `TODO`, `TBD`, `known issue`, `legacy`, `n/a` and "placeholder + nothing substantive" (`TODO: fix later`) are rejected. |
+| `routes` | no | exact path or `/prefix/*` subtree. A scope naming a route that is not audited fails the run as a typo. |
+| `selectors` | no | matches the node's own axe target, or an ancestor prefix of it on a combinator boundary. `#billing` does **not** match `#billing-panel`. |
+| `expires` | no | ISO `YYYY-MM-DD`. Past its end-of-day the entry suppresses nothing and the violations under it start failing again. |
+| `ticket` | no | Linear id, surfaced in the report. |
+
+Omitting both `routes` and `selectors` is allowed but it is a fleet-wide
+exemption for that rule, and the report labels it as unscoped so it is visible in
+review.
+
+Entries that matched nothing in a run are reported as **stale**. Set
+`failOnStaleAllowlist: true` once a repo's list is clean to keep it that way.
+
+## Output
+
+- console report (route by route, rule by rule, with the failing selectors),
+- `a11y-report.json` (path configurable via `reportPath` or `--json=`), which is
+  what you attach to a CI artifact,
+- a markdown table appended to `$GITHUB_STEP_SUMMARY` when running in Actions.
+
+## CLI flags
+
+```
+a11y-audit [configPath]
+           [--base-url=URL]   audit a running deployment instead of serving dist
+           [--json=PATH]      where to write the JSON report
+           [--route=/path]    repeatable; audit only these routes
+           [--quiet]          suppress the console report, keep the verdict
+```
+
+## Wiring it into CI
+
+Copy `a11y-check.yml.tmpl` from
+`~/products/dev/platform/context/cicd/templates/` into `.github/workflows/`.
+Rollout guide: `~/products/dev/platform/context/ui-simplification/HOW_TO_ADD_A11Y_CI.md`.

package/scripts/a11y-audit/allowlist.ts

@@ -0,0 +1,178 @@
+/**
+ * Allowlist matching and violation partitioning.
+ *
+ * Pure functions only — this is the part of the gate that decides what is
+ * allowed to not fail a build, so it is unit-tested directly rather than
+ * inferred from a green CI run.
+ */
+
+import type { AllowedNode, AllowlistEntry, FlatNode, ImpactLevel, RouteSpec } from './types';
+
+/** axe targets nest one level for iframes; flatten to plain selector strings. */
+export function flattenTarget(target: unknown): string[] {
+  if (typeof target === 'string') return [target];
+  if (!Array.isArray(target)) return [];
+  return target.flatMap((t) => flattenTarget(t));
+}
+
+function normalizeSelector(selector: string): string {
+  return selector.trim().replace(/\s+/g, ' ');
+}
+
+/**
+ * A configured selector matches an axe target when it is the target itself or
+ * an ancestor prefix of it. `#billing-panel` therefore covers
+ * `#billing-panel > table > tr:nth-child(2) > td`, but `#billing` does not —
+ * the boundary must fall on a combinator, so prefixes never match by accident.
+ */
+export function selectorMatches(allowSelector: string, target: string): boolean {
+  const allow = normalizeSelector(allowSelector);
+  const actual = normalizeSelector(target);
+  if (allow.length === 0) return false;
+  if (allow === actual) return true;
+  if (!actual.startsWith(allow)) return false;
+  const boundary = actual.charAt(allow.length);
+  return boundary === ' ' || boundary === '>' || boundary === '+' || boundary === '~';
+}
+
+/**
+ * A configured route matches either exactly, or as a `/prefix/*` subtree.
+ * `/settings/*` covers `/settings/profile` and `/settings` itself.
+ */
+export function routeMatches(allowRoute: string, routePath: string): boolean {
+  const allow = allowRoute.trim();
+  const actual = routePath.trim();
+  if (allow === actual) return true;
+  if (!allow.endsWith('/*')) return false;
+  const prefix = allow.slice(0, -2);
+  if (prefix.length === 0) return false;
+  return actual === prefix || actual.startsWith(`${prefix}/`);
+}
+
+/** An entry with an `expires` date in the past suppresses nothing. */
+export function isExpired(entry: AllowlistEntry, now: Date): boolean {
+  if (!entry.expires) return false;
+  const expiryEnd = new Date(`${entry.expires}T23:59:59.999Z`).getTime();
+  return now.getTime() > expiryEnd;
+}
+
+/** Does this entry cover this specific failing node? */
+export function entryCovers(entry: AllowlistEntry, node: FlatNode, now: Date): boolean {
+  if (entry.rule !== node.rule) return false;
+  if (isExpired(entry, now)) return false;
+  if (entry.routes && !entry.routes.some((r) => routeMatches(r, node.route))) return false;
+  if (
+    entry.selectors &&
+    !entry.selectors.some((s) => node.target.some((t) => selectorMatches(s, t)))
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/** Shape of the subset of an axe violation this module reads. */
+export interface AxeViolationLike {
+  id: string;
+  impact?: string | null;
+  help?: string;
+  helpUrl?: string;
+  tags?: string[];
+  nodes: Array<{
+    target: unknown;
+    html?: string;
+    impact?: string | null;
+    failureSummary?: string;
+  }>;
+}
+
+/** Flatten axe violations into one record per failing DOM node. */
+export function flattenViolations(
+  violations: AxeViolationLike[],
+  context: { route: string; routeName: string; viewport: string }
+): FlatNode[] {
+  const flat: FlatNode[] = [];
+  for (const violation of violations) {
+    for (const node of violation.nodes) {
+      flat.push({
+        rule: violation.id,
+        impact: (node.impact ?? violation.impact ?? 'minor') as ImpactLevel,
+        help: violation.help ?? '',
+        helpUrl: violation.helpUrl ?? '',
+        tags: violation.tags ?? [],
+        route: context.route,
+        routeName: context.routeName,
+        viewport: context.viewport,
+        target: flattenTarget(node.target),
+        html: (node.html ?? '').slice(0, 400),
+        failureSummary: node.failureSummary ?? '',
+      });
+    }
+  }
+  return flat;
+}
+
+export interface PartitionResult {
+  blocking: FlatNode[];
+  allowed: AllowedNode[];
+  advisory: FlatNode[];
+  /** Indexes into the allowlist that actually suppressed something. */
+  usedEntries: Set<number>;
+}
+
+/**
+ * Split flattened nodes into build-failing, explicitly-allowed and advisory
+ * (below the failure threshold, reported but not blocking).
+ *
+ * When several entries cover the same node the first one wins, so the report
+ * attributes it to a single, nameable reason.
+ */
+export function partitionNodes(
+  nodes: FlatNode[],
+  allowlist: AllowlistEntry[],
+  failOn: ImpactLevel[],
+  now: Date
+): PartitionResult {
+  const blocking: FlatNode[] = [];
+  const allowed: AllowedNode[] = [];
+  const advisory: FlatNode[] = [];
+  const usedEntries = new Set<number>();
+
+  for (const node of nodes) {
+    const index = allowlist.findIndex((entry) => entryCovers(entry, node, now));
+    if (index >= 0) {
+      usedEntries.add(index);
+      const entry = allowlist[index];
+      allowed.push({
+        ...node,
+        allowlistIndex: index,
+        allowlistReason: entry.reason,
+        allowlistTicket: entry.ticket,
+      });
+      continue;
+    }
+    if (failOn.includes(node.impact)) blocking.push(node);
+    else advisory.push(node);
+  }
+
+  return { blocking, allowed, advisory, usedEntries };
+}
+
+/**
+ * Entries whose `routes` name a path that is not in the audited route list.
+ * Almost always a typo, and a typo here silently widens or voids the scope.
+ */
+export function findUnreachableRouteScopes(
+  allowlist: AllowlistEntry[],
+  routes: RouteSpec[]
+): Array<{ index: number; route: string }> {
+  const unreachable: Array<{ index: number; route: string }> = [];
+  allowlist.forEach((entry, index) => {
+    if (!entry.routes) return;
+    for (const scope of entry.routes) {
+      if (!routes.some((route) => routeMatches(scope, route.path))) {
+        unreachable.push({ index, route: scope });
+      }
+    }
+  });
+  return unreachable;
+}

package/scripts/a11y-audit/audit.ts

@@ -0,0 +1,306 @@
+/**
+ * Browser driving: navigate each configured route at each configured viewport
+ * and run a real axe-core pass against the rendered DOM.
+ *
+ * `playwright-core` and `@axe-core/playwright` are imported dynamically so the
+ * shared runner can live in fe-libs without dragging a browser automation
+ * dependency into every consumer of the component library. Consuming repos
+ * declare them as devDependencies; a missing one is a loud, actionable error.
+ */
+
+import { partitionNodes, flattenViolations } from './allowlist';
+import type { AxeViolationLike } from './allowlist';
+import type { RunningApp } from './server';
+import type { AuditReport, ResolvedConfig, RouteResult } from './types';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- dynamically imported
+   third-party modules have no static types available inside this script. */
+type AnyRecord = Record<string, any>;
+
+const MISSING_DEP_HINT =
+  'Add them to the repo devDependencies:\n' +
+  '    bun add -d @playwright/test @axe-core/playwright\n' +
+  '    bunx playwright install --with-deps chromium';
+
+async function loadPlaywright(): Promise<AnyRecord> {
+  for (const specifier of ['playwright', 'playwright-core', '@playwright/test']) {
+    try {
+      const mod = (await import(specifier)) as AnyRecord;
+      if (mod?.chromium) return mod.chromium as AnyRecord;
+    } catch {
+      /* try the next specifier */
+    }
+  }
+  throw new Error(`[a11y-audit] Cannot resolve Playwright.\n  ${MISSING_DEP_HINT}`);
+}
+
+type AxeBuilderCtor = new (options: { page: AnyRecord }) => {
+  withTags: (tags: string[]) => { analyze: () => Promise<AnyRecord> };
+};
+
+async function loadAxeBuilder(): Promise<AxeBuilderCtor> {
+  try {
+    const mod = (await import('@axe-core/playwright')) as AnyRecord;
+    return (mod.default ?? mod) as AxeBuilderCtor;
+  } catch (error) {
+    throw new Error(
+      `[a11y-audit] Cannot resolve @axe-core/playwright (${(error as Error).message}).\n  ` +
+        MISSING_DEP_HINT,
+      { cause: error }
+    );
+  }
+}
+
+async function loadAxeVersion(): Promise<string> {
+  try {
+    const mod = (await import('axe-core')) as AnyRecord;
+    return (mod.default?.version ?? mod.version ?? 'unknown') as string;
+  } catch {
+    return 'unknown';
+  }
+}
+
+interface DomSnapshot {
+  textLength: number;
+  elementCount: number;
+}
+
+async function snapshotDom(page: AnyRecord): Promise<DomSnapshot> {
+  return (await page.evaluate(() => ({
+    textLength: (document.body?.innerText ?? '').trim().length,
+    elementCount: document.querySelectorAll('*').length,
+  }))) as DomSnapshot;
+}
+
+/**
+ * Poll until the rendered DOM stops changing for `quietMs`, or `timeoutMs`
+ * elapses. Returns the final snapshot and whether it actually went quiet.
+ *
+ * This is what makes the gate reproducible on a shell that paints a splash
+ * before it paints the page.
+ */
+async function waitForStableDom(
+  page: AnyRecord,
+  quietMs: number,
+  timeoutMs: number
+): Promise<{ snapshot: DomSnapshot; settled: boolean }> {
+  const pollMs = 250;
+  const deadline = Date.now() + timeoutMs;
+  let previous = await snapshotDom(page);
+  let quietSince = Date.now();
+
+  while (Date.now() < deadline) {
+    await page.waitForTimeout(pollMs);
+    const current = await snapshotDom(page);
+    if (
+      current.textLength !== previous.textLength ||
+      current.elementCount !== previous.elementCount
+    ) {
+      previous = current;
+      quietSince = Date.now();
+      continue;
+    }
+    previous = current;
+    if (Date.now() - quietSince >= quietMs) return { snapshot: current, settled: true };
+  }
+  return { snapshot: previous, settled: false };
+}
+
+/** Run the full audit. Throws on navigation failure — never silently skips a route. */
+export async function runAudit(
+  config: ResolvedConfig,
+  app: Pick<RunningApp, 'baseUrl' | 'resolveAsset'>,
+  now: Date = new Date()
+): Promise<AuditReport> {
+  const { baseUrl, resolveAsset } = app;
+  const chromium = await loadPlaywright();
+  const AxeBuilder = await loadAxeBuilder();
+  const axeVersion = await loadAxeVersion();
+
+  const browser = await chromium.launch({
+    args: ['--no-sandbox', '--disable-dev-shm-usage', '--disable-gpu'],
+  });
+  const results: RouteResult[] = [];
+  const usedEntries = new Set<number>();
+  const navigationErrors: string[] = [];
+
+  /** Fresh page with request routing applied — used for the first try and every retry. */
+  const openPage = async (context: AnyRecord): Promise<AnyRecord> => {
+    const page = await context.newPage();
+    if (config.blockExternalRequests || resolveAsset) {
+      await page.route('**/*', (route: AnyRecord) => {
+        const requestUrl: string = route.request().url();
+        const isOwnOrigin = requestUrl.startsWith(baseUrl);
+
+        // Serve the build's own files straight from disk. Chromium never opens
+        // a socket for them, so a spurious network-change notification cannot
+        // cancel a hundred in-flight chunk loads and leave the shell blank.
+        if (isOwnOrigin && resolveAsset) {
+          const asset = resolveAsset(new URL(requestUrl).pathname);
+          if (asset) {
+            void route.fulfill({
+              status: 200,
+              contentType: asset.contentType,
+              headers: { 'cache-control': 'no-store' },
+              body: asset.body,
+            });
+            return;
+          }
+          void route.fulfill({ status: 404, contentType: 'text/plain', body: 'Not found' });
+          return;
+        }
+
+        // Deterministic DOM: nothing the audit sees depends on a live backend,
+        // a CDN or the runner's network latency.
+        if (isOwnOrigin || requestUrl.startsWith('data:') || !config.blockExternalRequests) {
+          void route.continue();
+          return;
+        }
+        void route.abort();
+      });
+    }
+    return page;
+  };
+
+  try {
+    for (const viewport of config.viewports) {
+      const context = await browser.newContext({
+        viewport: { width: viewport.width, height: viewport.height },
+        // Deterministic rendering: no OS locale/timezone drift between the dev
+        // machine and the CI runner changing what axe sees.
+        locale: 'en-US',
+        timezoneId: 'UTC',
+        reducedMotion: 'reduce',
+        // A service worker caching the shell across routes would make the audit
+        // depend on which route ran first.
+        serviceWorkers: 'block',
+      });
+
+      for (const route of config.routes) {
+        const url = `${baseUrl}${route.path}`;
+        const attemptFailures: string[] = [];
+        let result: RouteResult | null = null;
+
+        for (let attempt = 1; attempt <= config.routeAttempts && result === null; attempt += 1) {
+          const page = await openPage(context);
+          try {
+            const response = await page.goto(url, {
+              waitUntil: 'load',
+              timeout: config.navigationTimeoutMs,
+            });
+            if (response && response.status() >= 400) {
+              throw new Error(`HTTP ${response.status()}`);
+            }
+            if (route.waitForSelector) {
+              await page.waitForSelector(route.waitForSelector, {
+                timeout: config.navigationTimeoutMs,
+              });
+            }
+            await page.waitForTimeout(route.settleMs ?? config.settleMs);
+
+            const stability = await waitForStableDom(
+              page,
+              config.domQuietMs,
+              config.navigationTimeoutMs
+            );
+            const floor = route.minTextLength ?? config.minTextLength;
+            if (stability.snapshot.textLength < floor) {
+              throw new Error(
+                `rendered only ${stability.snapshot.textLength} characters of text (floor is ` +
+                  `${floor}) — the page never finished painting, so a clean axe result here ` +
+                  'would be meaningless'
+              );
+            }
+
+            const axeResults = (await new AxeBuilder({ page })
+              .withTags(config.standard)
+              .analyze()) as AnyRecord;
+
+            const nodes = flattenViolations(axeResults.violations as AxeViolationLike[], {
+              route: route.path,
+              routeName: route.name,
+              viewport: viewport.name,
+            });
+            const partition = partitionNodes(nodes, config.allowlist, config.failOn, now);
+            partition.usedEntries.forEach((index) => usedEntries.add(index));
+
+            result = {
+              route: route.path,
+              routeName: route.name,
+              viewport: viewport.name,
+              finalUrl: page.url(),
+              blocking: partition.blocking,
+              allowed: partition.allowed,
+              advisory: partition.advisory,
+              passCount: (axeResults.passes as unknown[]).length,
+              incompleteCount: (axeResults.incomplete as unknown[]).length,
+              renderedTextLength: stability.snapshot.textLength,
+              domSettled: stability.settled,
+              attempts: attempt,
+            };
+          } catch (error) {
+            attemptFailures.push(`attempt ${attempt}: ${(error as Error).message}`);
+          } finally {
+            await page.close();
+          }
+        }
+
+        if (result === null) {
+          navigationErrors.push(
+            `${route.name} @ ${viewport.name} (${url}):\n      ${attemptFailures.join('\n      ')}`
+          );
+          continue;
+        }
+        if (result.attempts > 1) {
+          console.warn(
+            `[a11y-audit] ${route.name} @ ${viewport.name} needed ${result.attempts} attempts ` +
+              `(${attemptFailures.join('; ')})`
+          );
+        }
+        results.push(result);
+      }
+
+      await context.close();
+    }
+  } finally {
+    await browser.close();
+  }
+
+  if (navigationErrors.length > 0) {
+    throw new Error(
+      `[a11y-audit] ${navigationErrors.length} route(s) could not be loaded, so the audit is ` +
+        'incomplete and cannot be treated as a pass:\n  - ' +
+        navigationErrors.join('\n  - ')
+    );
+  }
+
+  const staleAllowlistEntries = config.allowlist
+    .map((entry, index) => ({ index, rule: entry.rule, reason: entry.reason }))
+    .filter((entry) => !usedEntries.has(entry.index));
+
+  const expiredAllowlistEntries = config.allowlist
+    .map((entry, index) => ({ index, rule: entry.rule, expires: entry.expires ?? '' }))
+    .filter((entry) => {
+      if (!entry.expires) return false;
+      return now.getTime() > new Date(`${entry.expires}T23:59:59.999Z`).getTime();
+    });
+
+  return {
+    name: config.name,
+    generatedAt: now.toISOString(),
+    baseUrl,
+    standard: config.standard,
+    failOn: config.failOn,
+    axeVersion,
+    blockExternalRequests: config.blockExternalRequests,
+    routes: results,
+    staleAllowlistEntries,
+    expiredAllowlistEntries,
+    totals: {
+      blocking: results.reduce((sum, r) => sum + r.blocking.length, 0),
+      allowed: results.reduce((sum, r) => sum + r.allowed.length, 0),
+      advisory: results.reduce((sum, r) => sum + r.advisory.length, 0),
+      routesAudited: results.length,
+    },
+  };
+}