@wcag-audit/cli 1.0.0-alpha.11

package/src/audit.js

@@ -0,0 +1,199 @@
+// Top-level audit orchestrator. Launches a Playwright browser, navigates to
+// the page, and dispatches every checker in turn. Each checker returns a
+// Finding[] array which is normalized and merged. At the end the report
+// writer turns the merged findings + run metadata into an Excel workbook.
+
+import { chromium } from "playwright";
+import fs from "node:fs/promises";
+
+import { filterCriteriaForScope, buildAxeTags } from "./wcag-criteria.js";
+import { writeReport } from "./report.js";
+import { writeAiFixJson } from "./ai-fix-json.js";
+
+import { runAxe } from "./checkers/axe.js";
+import { runAiVision } from "./checkers/ai-vision.js";
+import { runKeyboard } from "./checkers/keyboard.js";
+import { runViewport } from "./checkers/viewport.js";
+import { runInteraction } from "./checkers/interaction.js";
+import { runMotion } from "./checkers/motion.js";
+import { runForms } from "./checkers/forms.js";
+import { runPointer } from "./checkers/pointer.js";
+import { runMedia } from "./checkers/media.js";
+import { runConsistency } from "./checkers/consistency.js";
+import { runAuth } from "./checkers/auth.js";
+import { runScreenReader } from "./checkers/screen-reader.js";
+
+// Each checker registers under a key matching the --skip option vocabulary.
+// `optIn: true` means the checker only runs when the request explicitly
+// includes its key (e.g. "screen-reader") in opts.include — they are slow
+// or platform-bound so we don't run them on every audit.
+const CHECKERS = [
+  { key: "axe", fn: runAxe, label: "axe-core" },
+  { key: "keyboard", fn: runKeyboard, label: "Keyboard / focus" },
+  { key: "viewport", fn: runViewport, label: "Viewport / reflow / text spacing" },
+  { key: "interaction", fn: runInteraction, label: "Hover & on-focus/on-input" },
+  { key: "motion", fn: runMotion, label: "Motion / autoplay / flashes" },
+  { key: "forms", fn: runForms, label: "Forms / error handling" },
+  { key: "pointer", fn: runPointer, label: "Pointer & gestures" },
+  { key: "media", fn: runMedia, label: "Audio / video presence" },
+  { key: "auth", fn: runAuth, label: "Accessible authentication" },
+  { key: "consistency", fn: runConsistency, label: "Multi-page consistency" },
+  { key: "ai", fn: runAiVision, label: "Claude AI vision review", requiresAi: true },
+  // Screen-reader walks the page and captures what each focusable element
+  // would announce. The walk + VoiceOver launch run with or without AI;
+  // AI is only used to grade the captured phrases for clarity. So we do
+  // NOT mark this requiresAi — the checker handles "no AI" gracefully.
+  { key: "screen-reader", fn: runScreenReader, label: "Real screen-reader walkthrough", optIn: true },
+];
+
+// Run a complete audit and return findings + metadata WITHOUT writing any
+// files. The HTTP server uses this directly so it can serialize the result
+// over the wire instead of producing a local xlsx. The CLI's runAudit()
+// wraps this and additionally writes the Excel report to disk.
+export async function runAuditCore(opts, hooks = {}) {
+  const startedAt = new Date();
+  await fs.mkdir(opts.screenshotsDir, { recursive: true });
+
+  // Screen-reader checker requires a VISIBLE browser window — VoiceOver /
+  // NVDA can only attach to GUI windows. Force headed mode whenever it's
+  // in the include list, even if the caller didn't pass --headed.
+  const wantsScreenReader = (opts.include || []).includes("screen-reader");
+  const headless = wantsScreenReader ? false : !opts.headed;
+  if (wantsScreenReader && !opts.headed) {
+    console.log("  ℹ screen-reader requested → forcing visible browser window");
+  }
+
+  const browser = await chromium.launch({
+    headless,
+    slowMo: opts.slowMo || 0,
+  });
+  const contextOpts = { viewport: { width: 1366, height: 900 } };
+  if (opts.authStorage) contextOpts.storageState = opts.authStorage;
+  const context = await browser.newContext(contextOpts);
+  const page = await context.newPage();
+
+  let findings = [];
+  let perCheckerTimings = {};
+  let perCheckerErrors = {};
+  let aiUsage = null;
+  const skip = new Set(opts.skip || []);
+
+  try {
+    await page.goto(opts.url, { waitUntil: "networkidle", timeout: 60_000 });
+    await page.waitForTimeout(500); // let JS settle
+
+    const ctx = {
+      page,
+      context,
+      browser,
+      url: opts.url,
+      title: await page.title(),
+      wcagVersion: opts.wcagVersion,
+      levels: opts.levels,
+      axeTags: buildAxeTags(opts.wcagVersion, opts.levels),
+      scopeCriteria: filterCriteriaForScope(opts.wcagVersion, opts.levels),
+      screenshotsDir: opts.screenshotsDir,
+      maxPages: opts.maxPages,
+      ai: {
+        enabled: !!opts.aiEnabled,
+        provider: opts.aiProvider || "anthropic",
+        // `anthropicApiKey` is the back-compat name kept by the CLI flag.
+        // For non-Anthropic providers the same field carries the OpenAI
+        // or Google key — the worker route normalizes it.
+        apiKey: opts.aiKey || opts.anthropicApiKey,
+        model: opts.aiModel,
+      },
+    };
+
+    const include = new Set(opts.include || []);
+    const enabledCheckers = CHECKERS.filter((c) => {
+      if (skip.has(c.key)) return false;
+      if (c.optIn && !include.has(c.key)) return false;
+      if (c.requiresAi && (!opts.aiEnabled || !opts.anthropicApiKey)) return false;
+      return true;
+    });
+    let checkerIdx = 0;
+    for (const c of enabledCheckers) {
+      checkerIdx++;
+      hooks.onProgress?.({
+        phase: "checker",
+        checker: c.key,
+        label: c.label,
+        index: checkerIdx,
+        total: enabledCheckers.length,
+      });
+      const t0 = Date.now();
+      try {
+        const out = await c.fn(ctx);
+        const checkerFindings = out?.findings || [];
+        findings = findings.concat(checkerFindings);
+        if (out?.usage) aiUsage = mergeUsage(aiUsage, out.usage);
+        if (out?.error) {
+          perCheckerErrors[c.key] = out.error;
+          process.stdout.write(`    ⚠ ${c.key}: ${out.error}\n`);
+        }
+        perCheckerTimings[c.key] = +((Date.now() - t0) / 1000).toFixed(1);
+      } catch (err) {
+        perCheckerErrors[c.key] = err.message;
+        process.stdout.write(`    ✗ ${c.key} threw: ${err.message}\n`);
+      }
+    }
+  } finally {
+    await context.close().catch(() => {});
+    await browser.close().catch(() => {});
+  }
+
+  findings.forEach((f, i) => { f.issueNumber = i + 1; });
+
+  const meta = {
+    url: opts.url,
+    wcagVersion: opts.wcagVersion,
+    levels: opts.levels,
+    startedAt: startedAt.toISOString(),
+    finishedAt: new Date().toISOString(),
+    totalFindings: findings.length,
+    perCheckerTimings,
+    perCheckerErrors,
+    aiEnabled: !!opts.aiEnabled,
+    aiModel: opts.aiModel,
+    aiUsage,
+    scopeCriteria: filterCriteriaForScope(opts.wcagVersion, opts.levels),
+  };
+
+  return { findings, meta };
+}
+
+// CLI wrapper: runs the core, writes the Excel file, prints progress.
+export async function runAudit(opts) {
+  console.log(`\n→ Auditing ${opts.url}`);
+  console.log(`  WCAG ${opts.wcagVersion}, levels ${opts.levels.join("/")}`);
+  console.log(`  Output: ${opts.outPath}\n`);
+
+  const { findings, meta } = await runAuditCore(opts, {
+    onProgress: (p) => {
+      if (p.phase === "checker") {
+        process.stdout.write(`  ▸ ${p.label} (${p.index}/${p.total})\n`);
+      }
+    },
+  });
+
+  await writeReport({ findings, meta, outPath: opts.outPath });
+
+  // Write AI fix JSON alongside the Excel report
+  const jsonPath = opts.outPath.replace(/\.xlsx$/i, ".ai-fix.json");
+  const aiFixJson = await writeAiFixJson({ findings, meta, outPath: jsonPath });
+  console.log(`\n✓ Done. ${findings.length} finding(s)`);
+  console.log(`  Excel  → ${opts.outPath}`);
+  console.log(`  AI fix → ${jsonPath}`);
+  if (meta.aiUsage) {
+    console.log(`  AI tokens: ${meta.aiUsage.input_tokens} in / ${meta.aiUsage.output_tokens} out`);
+  }
+}
+
+function mergeUsage(a, b) {
+  if (!a) return { ...b };
+  return {
+    input_tokens: (a.input_tokens || 0) + (b.input_tokens || 0),
+    output_tokens: (a.output_tokens || 0) + (b.output_tokens || 0),
+  };
+}

package/src/cache/route-cache.js

@@ -0,0 +1,46 @@
+import { createHash } from "crypto";
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { join } from "path";
+
+export const CACHE_DIR = ".wcag-audit/cache";
+// 24h — enough to cover a full dev workday without rescanning, but
+// short enough that changes to the environment (deps, config) still
+// force a fresh audit at least once a day.
+export const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+export function hashContent(html, assetUrls = []) {
+  const h = createHash("sha256");
+  h.update(html || "");
+  // Sort assets so ordering doesn't invalidate the cache — Next.js
+  // sometimes reorders its chunks between dev-server restarts.
+  const sorted = [...assetUrls].sort();
+  h.update("\u0000");
+  h.update(sorted.join("\u0000"));
+  return h.digest("hex").slice(0, 16);
+}
+
+function cacheFileName(routePath) {
+  if (!routePath || routePath === "/") return "_root.json";
+  return "_" + routePath.replace(/^\//, "").replace(/[^a-zA-Z0-9]/g, "_") + ".json";
+}
+
+export async function readCacheEntry(projectDir, routePath, hash) {
+  const path = join(projectDir, CACHE_DIR, cacheFileName(routePath));
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.hash !== hash) return null;
+    if (!parsed.auditedAt || Date.now() - parsed.auditedAt > CACHE_TTL_MS) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeCacheEntry(projectDir, routePath, hash, { findings, auditedAt }) {
+  const dir = join(projectDir, CACHE_DIR);
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, cacheFileName(routePath));
+  const payload = { hash, auditedAt, findings };
+  await writeFile(path, JSON.stringify(payload, null, 2), "utf8");
+}

package/src/cache/route-cache.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, readFile, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { hashContent, readCacheEntry, writeCacheEntry, CACHE_DIR, CACHE_TTL_MS } from "./route-cache.js";
+
+let projDir;
+
+beforeEach(async () => {
+  projDir = await mkdtemp(join(tmpdir(), "wcagcache-"));
+});
+
+afterEach(async () => {
+  await rm(projDir, { recursive: true, force: true });
+});
+
+describe("hashContent", () => {
+  it("produces stable hex digest for identical inputs", () => {
+    const a = hashContent("<html>hi</html>", ["a.css", "b.js"]);
+    const b = hashContent("<html>hi</html>", ["a.css", "b.js"]);
+    expect(a).toBe(b);
+    expect(a).toMatch(/^[a-f0-9]{16}$/);
+  });
+
+  it("changes when HTML changes", () => {
+    const a = hashContent("<html>hi</html>", []);
+    const b = hashContent("<html>bye</html>", []);
+    expect(a).not.toBe(b);
+  });
+
+  it("changes when asset list changes", () => {
+    const a = hashContent("<html/>", ["a.css"]);
+    const b = hashContent("<html/>", ["a.css", "b.css"]);
+    expect(a).not.toBe(b);
+  });
+
+  it("ignores asset order", () => {
+    const a = hashContent("<html/>", ["a.css", "b.css"]);
+    const b = hashContent("<html/>", ["b.css", "a.css"]);
+    expect(a).toBe(b);
+  });
+});
+
+describe("readCacheEntry / writeCacheEntry", () => {
+  it("returns null when no entry exists", async () => {
+    const entry = await readCacheEntry(projDir, "/", "abc123");
+    expect(entry).toBeNull();
+  });
+
+  it("returns the written entry on match", async () => {
+    await writeCacheEntry(projDir, "/", "abc123", {
+      findings: [{ ruleId: "image-alt", impact: "critical" }],
+      auditedAt: Date.now(),
+    });
+    const entry = await readCacheEntry(projDir, "/", "abc123");
+    expect(entry).not.toBeNull();
+    expect(entry.findings).toHaveLength(1);
+    expect(entry.findings[0].ruleId).toBe("image-alt");
+  });
+
+  it("returns null when hash does not match", async () => {
+    await writeCacheEntry(projDir, "/", "abc123", { findings: [], auditedAt: Date.now() });
+    const entry = await readCacheEntry(projDir, "/", "different-hash");
+    expect(entry).toBeNull();
+  });
+
+  it("returns null when entry is older than TTL", async () => {
+    await writeCacheEntry(projDir, "/", "abc123", {
+      findings: [],
+      auditedAt: Date.now() - CACHE_TTL_MS - 1000,
+    });
+    const entry = await readCacheEntry(projDir, "/", "abc123");
+    expect(entry).toBeNull();
+  });
+
+  it("writes cache to the expected directory", async () => {
+    await writeCacheEntry(projDir, "/about", "abc", { findings: [], auditedAt: Date.now() });
+    const raw = await readFile(join(projDir, CACHE_DIR, "_about.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    expect(parsed.hash).toBe("abc");
+  });
+
+  it("handles root path `/` by naming the file `_root.json`", async () => {
+    await writeCacheEntry(projDir, "/", "abc", { findings: [], auditedAt: Date.now() });
+    const raw = await readFile(join(projDir, CACHE_DIR, "_root.json"), "utf8");
+    expect(JSON.parse(raw).hash).toBe("abc");
+  });
+
+  it("survives corrupt JSON by returning null", async () => {
+    const { mkdir } = await import("fs/promises");
+    await mkdir(join(projDir, CACHE_DIR), { recursive: true });
+    await writeFile(join(projDir, CACHE_DIR, "_root.json"), "{ not json", "utf8");
+    const entry = await readCacheEntry(projDir, "/", "abc");
+    expect(entry).toBeNull();
+  });
+});

package/src/checkers/ai-vision.js

@@ -0,0 +1,102 @@
+// AI vision pass — same prompts as the extension, ported to Node + the
+// official Anthropic SDK. Reviews the visual-judgment criteria that no
+// static rule engine can check (sensory characteristics, images of text,
+// non-text contrast, etc.).
+
+import { askClaudeForJsonArray } from "../util/anthropic.js";
+import { captureElementBySelector, saveScreenshot } from "../util/screenshot.js";
+
+const PROMPTS = {
+  "1.3.3": `Look for instructions in visible content that rely SOLELY on sensory characteristics — shape ("square button"), size, color ("the green link"), location ("on the right"), orientation, or sound ("after the beep"). Each must also be conveyed in a non-sensory way. Fail if any lacks a non-sensory alternative.`,
+  "1.4.5": `Look at the screenshot for IMAGES that contain text content. Logos, brand wordmarks, and decorative typography are exempt. Common offenders: hero banners with text overlays, infographics, navigation rendered as image sprites, buttons rendered as PNGs.`,
+  "1.4.8": `Inspect text blocks for: line length over ~80 characters, fully justified text, line spacing under 1.5x within paragraphs, paragraph spacing under 2x line height, horizontal scrolling at default width.`,
+  "1.4.9": `Stricter than 1.4.5 (AAA): NO images of text are allowed except logotypes or where presentation is essential.`,
+  "1.4.11": `Examine UI components (buttons, form inputs, focus indicators, tabs, links) and meaningful graphics in the screenshot. Boundaries / strokes need 3:1 contrast against the adjacent background. Flag specific components.`,
+  "1.4.12": `Inspect HTML/CSS for rules preventing user override of text spacing: line-height, letter-spacing, word-spacing or paragraph spacing set with !important, fixed-pixel heights on text containers, overflow:hidden on text blocks.`,
+  "2.4.5": `Check whether the page provides MORE THAN ONE way to find content: search box, sitemap link, table of contents, primary navigation, A-Z index. Fail if only one method exists (and the page isn't a step in a process).`,
+  "2.4.6": `Read every heading and visible form label. Mark any that are vague or non-descriptive ("More", "Click here", "Section 1", "Untitled"). Quote them.`,
+  "2.4.8": `Check if the page tells the user where they are within the site: breadcrumbs, "you are here" indicator, current item highlighted in nav. Fail if none.`,
+  "2.4.10": `Review the heading structure. Are large content sections missing headings? Are heading levels skipped (h1 → h3)?`,
+  "3.1.3": `Identify jargon, idioms, technical terms or unusual words in visible text whose meaning isn't obvious from context. AAA requires a glossary/definition mechanism.`,
+  "3.1.4": `Identify abbreviations and acronyms in visible text. WCAG requires the expanded form OR meaning to be available (e.g. <abbr title>). Quote them.`,
+  "3.1.5": `Estimate the reading level of the main content. AAA requires lower secondary (~9 years schooling) OR a simpler version. Fail with justification if significantly above.`,
+};
+
+function buildPrompt(criteria, pageMeta, html) {
+  const lines = [];
+  lines.push("You are a senior WCAG 2.2 accessibility auditor. Evaluate the screenshot and HTML against the listed criteria.");
+  lines.push("");
+  lines.push(`Page URL: ${pageMeta.url}`);
+  lines.push(`Page title: ${pageMeta.title}`);
+  lines.push("");
+  lines.push("Return a JSON array. For each criterion ONE object: { criterion, status (pass|fail|needs-review), summary, findings: [{ issue, evidence, selector, severity (minor|moderate|serious|critical) }] }");
+  lines.push("- 'fail' only with concrete evidence quoted from the screenshot or HTML.");
+  lines.push("- 'needs-review' when interaction/audio/video/multi-page context is needed. Do not guess.");
+  lines.push("- 'pass' only when affirmatively confirmed.");
+  lines.push("- selector: a CSS selector if you can identify it from the HTML, otherwise empty string.");
+  lines.push("- Return ONLY the JSON array, no prose, no markdown fences.");
+  lines.push("");
+  lines.push("CRITERIA:");
+  for (const c of criteria) {
+    lines.push("");
+    lines.push(`### ${c.id} ${c.title} (Level ${c.level})`);
+    lines.push(PROMPTS[c.id] || "");
+  }
+  lines.push("");
+  lines.push("--- PAGE HTML (truncated) ---");
+  lines.push((html || "").slice(0, 80000));
+  return lines.join("\n");
+}
+
+export async function runAiVision(ctx) {
+  const { page, ai } = ctx;
+  const reviewable = ctx.scopeCriteria.filter((c) => c.aiReviewable);
+  if (!reviewable.length) return { findings: [] };
+
+  const screenshot = await page.screenshot({ fullPage: true, type: "png" });
+  const html = await page.content();
+
+  const prompt = buildPrompt(reviewable, { url: ctx.url, title: ctx.title }, html);
+  const { array, usage } = await askClaudeForJsonArray({
+    provider: ai.provider,
+    apiKey: ai.apiKey,
+    model: ai.model,
+    prompt,
+    images: [{ buffer: screenshot, mimeType: "image/png" }],
+  });
+
+  const findings = [];
+  for (const r of array) {
+    if (r.status !== "fail" || !Array.isArray(r.findings)) continue;
+    const critEntry = reviewable.find((c) => c.id === r.criterion);
+    for (const f of r.findings) {
+      let screenshotFile = null;
+      if (f.selector) {
+        try {
+          const buf = await captureElementBySelector(page, f.selector, {
+            label: `AI · ${r.criterion}`,
+          });
+          screenshotFile = await saveScreenshot(buf, ctx.screenshotsDir, `ai_${r.criterion}`);
+        } catch (_) {}
+      }
+      findings.push({
+        source: "ai",
+        ruleId: `ai/${r.criterion}`,
+        criteria: r.criterion,
+        level: critEntry?.level || "",
+        impact: f.severity || "moderate",
+        description: f.issue || r.summary || "",
+        help: r.summary || "",
+        helpUrl: critEntry
+          ? `https://www.w3.org/WAI/WCAG22/Understanding/${critEntry.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}.html`
+          : "",
+        selector: f.selector || "",
+        evidence: f.evidence || "",
+        failureSummary: f.evidence || "",
+        screenshotFile,
+        aiVerdict: r,
+      });
+    }
+  }
+  return { findings, usage };
+}

package/src/checkers/auth.js

@@ -0,0 +1,111 @@
+// Accessible authentication checker. Covers (substantially):
+//
+//   3.3.8 Accessible Authentication (Minimum) — added in WCAG 2.2
+//   3.3.9 Accessible Authentication (Enhanced)
+//
+// We detect cognitive function tests by looking for common CAPTCHA scripts,
+// math/text puzzles, and image-selection challenges. The criterion permits
+// these only if there's an alternative method (e.g. WebAuthn) or a
+// mechanism to assist (e.g. password manager support, copy-paste allowed).
+
+export async function runAuth(ctx) {
+  const { page } = ctx;
+  const findings = [];
+
+  const detection = await page.evaluate(() => {
+    const out = { captchas: [], pasteBlocked: [], cognitivePuzzles: [] };
+
+    // Only flag 3.3.8 when BOTH a visible captcha widget AND an auth form
+    // are present on the page. Matching script strings alone is too noisy.
+    const hasAuthForm = !!(
+      document.querySelector("input[type='password']") ||
+      document.querySelector("form [type='email'],form [name*='email' i]") ||
+      document.querySelector(".cl-rootBox, .cl-signIn-root, .auth-form, [data-clerk-form]")
+    );
+    const captchaSelectors = [
+      [".g-recaptcha, iframe[src*='recaptcha']", "Google reCAPTCHA"],
+      [".h-captcha, iframe[src*='hcaptcha']", "hCaptcha"],
+      [".cf-turnstile, iframe[src*='challenges.cloudflare']", "Cloudflare Turnstile"],
+      ["iframe[src*='funcaptcha'], iframe[src*='arkoselabs']", "FunCaptcha"],
+    ];
+    if (hasAuthForm) {
+      for (const [sel, label] of captchaSelectors) {
+        const el = document.querySelector(sel);
+        if (el) {
+          const r = el.getBoundingClientRect();
+          if (r.width > 0 && r.height > 0) out.captchas.push(label);
+        }
+      }
+    }
+
+    // Inputs with onpaste="return false" or paste blocking
+    document.querySelectorAll("input").forEach((el) => {
+      const op = el.getAttribute("onpaste") || "";
+      if (/return false|preventDefault/i.test(op)) {
+        out.pasteBlocked.push({ name: el.name || el.id, type: el.type });
+      }
+    });
+
+    // Heuristic for math/text puzzles in labels
+    const labels = Array.from(document.querySelectorAll("label")).map((l) => l.innerText || "");
+    for (const text of labels) {
+      if (/what is\s+\d+\s*[+\-*x]\s*\d+/i.test(text) || /type the (word|text|number)/i.test(text)) {
+        out.cognitivePuzzles.push(text.trim().slice(0, 100));
+      }
+    }
+    return out;
+  });
+
+  if (detection.captchas.length) {
+    findings.push({
+      source: "playwright",
+      ruleId: "auth/captcha-detected",
+      criteria: "3.3.8",
+      level: "AA",
+      impact: "serious",
+      description: `CAPTCHA detected (${detection.captchas.join(", ")}). WCAG 3.3.8 (added in 2.2) forbids cognitive function tests for authentication unless an alternative or mechanism to assist is provided.`,
+      help: "Provide WebAuthn / passkey authentication, OR ensure the user can use a password manager and the captcha provides an audio / accessible alternative. Cloudflare Turnstile and hCaptcha can be configured to use device-bound puzzles which are 3.3.8-compliant.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html",
+      selector: "",
+      evidence: detection.captchas.join(", "),
+      failureSummary: "CAPTCHA on authentication flow",
+      screenshotFile: null,
+    });
+  }
+
+  if (detection.pasteBlocked.length) {
+    findings.push({
+      source: "playwright",
+      ruleId: "auth/paste-blocked",
+      criteria: "3.3.8",
+      level: "AA",
+      impact: "serious",
+      description: `${detection.pasteBlocked.length} input field(s) block pasting. This breaks password managers and is a 3.3.8 failure.`,
+      help: "Remove onpaste handlers from password and username fields.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html",
+      selector: detection.pasteBlocked.map((p) => `input[name='${p.name}']`).join(", "),
+      evidence: JSON.stringify(detection.pasteBlocked),
+      failureSummary: "Paste blocked on input",
+      screenshotFile: null,
+    });
+  }
+
+  if (detection.cognitivePuzzles.length) {
+    findings.push({
+      source: "playwright",
+      ruleId: "auth/cognitive-puzzle",
+      criteria: "3.3.8",
+      level: "AA",
+      impact: "serious",
+      description: `Cognitive function puzzle(s) detected in form labels: ${detection.cognitivePuzzles.join("; ")}`,
+      help: "Replace math/text puzzles with WebAuthn or other accessible authentication.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html",
+      selector: "label",
+      evidence: detection.cognitivePuzzles.join("\n"),
+      failureSummary: "Math/text puzzle in form",
+      screenshotFile: null,
+    });
+  }
+
+  return { findings };
+}

package/src/checkers/axe.js

@@ -0,0 +1,65 @@
+// axe-core via @axe-core/playwright. Same engine as the extension; this
+// gives us the ~30 fully-automated WCAG criteria as the baseline.
+
+import { AxeBuilder } from "@axe-core/playwright";
+import { captureElement, saveScreenshot } from "../util/screenshot.js";
+
+export async function runAxe(ctx) {
+  const { page } = ctx;
+  const builder = new AxeBuilder({ page }).withTags(ctx.axeTags);
+  const result = await builder.analyze();
+
+  const findings = [];
+  for (const violation of result.violations) {
+    for (const node of violation.nodes) {
+      const criteria = extractCriteria(violation.tags);
+      const level = extractLevels(violation.tags).join(",");
+      const targetStr = Array.isArray(node.target)
+        ? node.target.map((t) => (Array.isArray(t) ? t.join(" >> ") : t)).join(", ")
+        : String(node.target || "");
+
+      // Capture annotated screenshot
+      let screenshotFile = null;
+      try {
+        const buffer = await captureElement(page, page.locator(targetStr).first(), {
+          label: `axe · ${violation.id}`,
+        });
+        screenshotFile = await saveScreenshot(buffer, ctx.screenshotsDir, `axe_${violation.id}`);
+      } catch (_) {}
+
+      findings.push({
+        source: "axe",
+        ruleId: violation.id,
+        criteria: criteria.join(", "),
+        level,
+        impact: node.impact || violation.impact || "moderate",
+        description: violation.description || "",
+        help: violation.help || "",
+        helpUrl: violation.helpUrl || "",
+        selector: targetStr,
+        evidence: (node.html || "").slice(0, 500),
+        failureSummary: node.failureSummary || "",
+        screenshotFile,
+      });
+    }
+  }
+  return { findings };
+}
+
+function extractCriteria(tags) {
+  const out = [];
+  for (const t of tags || []) {
+    const m = /^wcag(\d)(\d)(\d+)$/i.exec(t);
+    if (m) out.push(`${m[1]}.${m[2]}.${m[3]}`);
+  }
+  return Array.from(new Set(out));
+}
+
+function extractLevels(tags) {
+  const levels = new Set();
+  for (const t of tags || []) {
+    const m = /^wcag2[12]?(a{1,3})$/i.exec(t);
+    if (m) levels.add(m[1].toUpperCase());
+  }
+  return Array.from(levels);
+}