@wcag-audit/cli 1.0.0-alpha.11

package/src/util/llm.js

@@ -0,0 +1,159 @@
+// Server-side mirror of the extension's llm-client.js. Same interface,
+// same provider catalogue, same call shape. Pure fetch — no SDKs — so
+// the same prompts work identically in browser and Node.
+//
+//   await callLlmJsonArray({
+//     provider, apiKey, model, prompt,
+//     images: [{ buffer, mimeType }], maxTokens
+//   })
+//   → { array, usage: { input_tokens, output_tokens }, raw }
+
+export const PROVIDERS = {
+  anthropic: {
+    label: "Anthropic Claude",
+    envKey: "ANTHROPIC_API_KEY",
+    defaultModel: "claude-sonnet-4-6",
+  },
+  openai: {
+    label: "OpenAI",
+    envKey: "OPENAI_API_KEY",
+    defaultModel: "gpt-4.1-mini",
+  },
+  google: {
+    label: "Google Gemini",
+    envKey: "GOOGLE_API_KEY",
+    defaultModel: "gemini-2.5-flash",
+  },
+};
+
+function toBase64(image) {
+  if (!image) return "";
+  if (typeof image.base64 === "string") return image.base64;
+  if (Buffer.isBuffer(image.buffer)) return image.buffer.toString("base64");
+  if (image.buffer) return Buffer.from(image.buffer).toString("base64");
+  return "";
+}
+
+// ─── Anthropic ──────────────────────────────────────────────────────────
+async function callAnthropic({ apiKey, model, prompt, images, maxTokens }) {
+  const content = [];
+  for (const img of images || []) {
+    content.push({
+      type: "image",
+      source: { type: "base64", media_type: img.mimeType || "image/png", data: toBase64(img) },
+    });
+  }
+  content.push({ type: "text", text: prompt });
+
+  const res = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: maxTokens || 4096,
+      messages: [{ role: "user", content }],
+    }),
+  });
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error(`Anthropic API ${res.status}: ${txt.slice(0, 400)}`);
+  }
+  const data = await res.json();
+  const text = (data.content || []).filter((c) => c.type === "text").map((c) => c.text).join("\n");
+  return {
+    text,
+    usage: { input_tokens: data.usage?.input_tokens || 0, output_tokens: data.usage?.output_tokens || 0 },
+  };
+}
+
+// ─── OpenAI ─────────────────────────────────────────────────────────────
+async function callOpenAi({ apiKey, model, prompt, images, maxTokens }) {
+  const content = [];
+  for (const img of images || []) {
+    const b64 = toBase64(img);
+    content.push({
+      type: "image_url",
+      image_url: { url: `data:${img.mimeType || "image/png"};base64,${b64}` },
+    });
+  }
+  content.push({ type: "text", text: prompt });
+
+  const res = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: "Bearer " + apiKey },
+    body: JSON.stringify({
+      model,
+      max_tokens: maxTokens || 4096,
+      messages: [{ role: "user", content }],
+    }),
+  });
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error(`OpenAI API ${res.status}: ${txt.slice(0, 400)}`);
+  }
+  const data = await res.json();
+  const text = data.choices?.[0]?.message?.content || "";
+  return {
+    text,
+    usage: { input_tokens: data.usage?.prompt_tokens || 0, output_tokens: data.usage?.completion_tokens || 0 },
+  };
+}
+
+// ─── Google Gemini ──────────────────────────────────────────────────────
+async function callGoogle({ apiKey, model, prompt, images, maxTokens }) {
+  const parts = [];
+  for (const img of images || []) {
+    parts.push({ inline_data: { mime_type: img.mimeType || "image/png", data: toBase64(img) } });
+  }
+  parts.push({ text: prompt });
+
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent?key=${encodeURIComponent(apiKey)}`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      contents: [{ role: "user", parts }],
+      generationConfig: { maxOutputTokens: maxTokens || 4096 },
+    }),
+  });
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error(`Google API ${res.status}: ${txt.slice(0, 400)}`);
+  }
+  const data = await res.json();
+  const text = (data.candidates?.[0]?.content?.parts || []).map((p) => p.text || "").join("\n");
+  return {
+    text,
+    usage: {
+      input_tokens: data.usageMetadata?.promptTokenCount || 0,
+      output_tokens: data.usageMetadata?.candidatesTokenCount || 0,
+    },
+  };
+}
+
+// ─── Dispatcher ─────────────────────────────────────────────────────────
+export async function callLlm(opts) {
+  const provider = (opts.provider || "anthropic").toLowerCase();
+  if (provider === "anthropic") return callAnthropic(opts);
+  if (provider === "openai") return callOpenAi(opts);
+  if (provider === "google") return callGoogle(opts);
+  throw new Error(`Unknown LLM provider: ${provider}`);
+}
+
+// JSON-array wrapper. Strips markdown fences and extracts the first
+// [...] block. Same contract as the extension's WCAG_LLM.callJsonArray.
+export async function callLlmJsonArray(opts) {
+  const { text, usage } = await callLlm(opts);
+  let t = (text || "").trim();
+  t = t.replace(/^```json\s*/i, "").replace(/^```\s*/i, "").replace(/```\s*$/i, "").trim();
+  const start = t.indexOf("[");
+  const end = t.lastIndexOf("]");
+  if (start === -1 || end === -1) {
+    throw new Error("LLM response did not contain a JSON array. Raw: " + (text || "").slice(0, 300));
+  }
+  return { array: JSON.parse(t.slice(start, end + 1)), usage, raw: text };
+}

package/src/util/screenshot.js

@@ -0,0 +1,131 @@
+// Screenshot helpers for the CLI. Captures cropped, annotated PNGs of
+// problem elements and writes them to the configured screenshots dir so the
+// report writer can embed them and reference them.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+let counter = 0;
+
+export function nextScreenshotId() {
+  counter++;
+  return String(counter).padStart(4, "0");
+}
+
+export function safeFileSegment(s, max = 60) {
+  return (s || "")
+    .replace(/[^a-z0-9._-]+/gi, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, max) || "issue";
+}
+
+// Capture an annotated viewport screenshot of a single element. Mirrors
+// the extension: scroll the element to the centre of the viewport, draw a
+// bold red highlight overlay, capture the visible viewport (not clipped),
+// then remove the overlay. The popup re-renders this onto its standard
+// 1100x700 canvas so every embedded image in the report is identical.
+export async function captureElement(page, locator, opts = {}) {
+  const { label = "" } = opts;
+  try {
+    const handle = await locator.elementHandle({ timeout: 2000 });
+    if (!handle) return null;
+    await handle.evaluate((el) => {
+      try { el.scrollIntoView({ block: "center", inline: "center", behavior: "instant" }); } catch (_) {}
+    }).catch(() => {});
+    const box = await handle.boundingBox();
+    if (!box || box.width === 0 || box.height === 0) {
+      await handle.dispose();
+      return null;
+    }
+
+    // Bold red overlay matching the extension's content.js. Two layers of
+    // border + glow + a label with arrow so the highlight is unmissable
+    // even when the element fills most of the viewport.
+    await page.evaluate(
+      ({ x, y, w, h, label }) => {
+        const id = "__wcag_cli_overlay__";
+        const lid = "__wcag_cli_label__";
+        document.getElementById(id)?.remove();
+        document.getElementById(lid)?.remove();
+        const docX = x + window.scrollX;
+        const docY = y + window.scrollY;
+        const o = document.createElement("div");
+        o.id = id;
+        Object.assign(o.style, {
+          position: "absolute",
+          top: docY + "px",
+          left: docX + "px",
+          width: w + "px",
+          height: h + "px",
+          border: "5px solid #ff0033",
+          outline: "2px solid #ffffff",
+          boxShadow:
+            "0 0 0 4px rgba(255,255,255,0.95), " +
+            "0 0 0 8px rgba(255,0,51,0.6), " +
+            "0 0 24px 12px rgba(255,0,51,0.45)",
+          pointerEvents: "none",
+          zIndex: "2147483647",
+          boxSizing: "border-box",
+          borderRadius: "3px",
+        });
+        const t = document.createElement("div");
+        t.id = lid;
+        t.textContent = "▶ " + (label || "WCAG issue");
+        const labelTop = docY - 32;
+        const labelAbove = labelTop > 8;
+        Object.assign(t.style, {
+          position: "absolute",
+          top: (labelAbove ? labelTop : docY + h + 6) + "px",
+          left: docX + "px",
+          background: "#ff0033",
+          color: "#ffffff",
+          font: "bold 14px -apple-system, system-ui, sans-serif",
+          padding: "4px 10px",
+          borderRadius: "4px",
+          border: "2px solid #ffffff",
+          boxShadow: "0 2px 8px rgba(0,0,0,0.4)",
+          pointerEvents: "none",
+          zIndex: "2147483647",
+          whiteSpace: "nowrap",
+          maxWidth: "90vw",
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+        });
+        document.documentElement.appendChild(o);
+        document.documentElement.appendChild(t);
+      },
+      { x: box.x, y: box.y, w: box.width, h: box.height, label }
+    );
+
+    // Tiny pause for the overlay to paint and any sticky/fixed elements
+    // to settle after the scroll.
+    await page.waitForTimeout(150);
+
+    // Capture only the visible viewport. The element is already centred,
+    // so the highlight is in frame. The popup will normalize this through
+    // its fixed-size canvas, so we don't need to crop.
+    const buffer = await page.screenshot({ fullPage: false, type: "png" });
+
+    await page.evaluate(() => {
+      document.getElementById("__wcag_cli_overlay__")?.remove();
+      document.getElementById("__wcag_cli_label__")?.remove();
+    });
+    await handle.dispose();
+    return buffer;
+  } catch (e) {
+    return null;
+  }
+}
+
+export async function captureElementBySelector(page, selector, opts = {}) {
+  return captureElement(page, page.locator(selector).first(), opts);
+}
+
+export async function saveScreenshot(buffer, dir, ruleId) {
+  if (!buffer) return null;
+  await fs.mkdir(dir, { recursive: true });
+  const id = nextScreenshotId();
+  const file = path.join(dir, `${id}_${safeFileSegment(ruleId)}.png`);
+  await fs.writeFile(file, buffer);
+  return file;
+}

package/src/wcag-criteria.js

@@ -0,0 +1,256 @@
+// Catalogue of WCAG success criteria (2.0 / 2.1 / 2.2) with the automation
+// status of each one against this CLI's three engines:
+//
+//   automation:        what axe-core can detect statically
+//                      "automated" | "partial" | "manual"
+//   aiReviewable:      what Claude vision can judge from a still snapshot
+//   playwrightCheckable: what we can verify by driving the browser (keyboard,
+//                      viewport, hover, form submit, motion timelapse, etc.)
+//
+// `addedIn` is the WCAG version that introduced the criterion. `removedIn`
+// marks criteria dropped in a later version (4.1.1 in 2.2).
+
+export const WCAG_CRITERIA = [
+  // ─────────────────────────── 1. Perceivable ───────────────────────────
+  { id: "1.1.1", title: "Non-text Content", level: "A", addedIn: "2.0",
+    automation: "automated",
+    axeRules: ["image-alt", "input-image-alt", "area-alt", "role-img-alt", "svg-img-alt", "object-alt", "input-button-name"] },
+
+  { id: "1.2.1", title: "Audio-only and Video-only (Prerecorded)", level: "A", addedIn: "2.0",
+    automation: "partial", axeRules: ["audio-caption", "video-caption"],
+    playwrightCheckable: true,
+    notes: "CLI detects <audio>/<video> presence; transcript accuracy is human-only." },
+  { id: "1.2.2", title: "Captions (Prerecorded)", level: "A", addedIn: "2.0",
+    automation: "partial", axeRules: ["video-caption"],
+    playwrightCheckable: true,
+    notes: "CLI checks for <track kind=captions>; caption correctness is human." },
+  { id: "1.2.3", title: "Audio Description or Media Alternative (Prerecorded)", level: "A", addedIn: "2.0",
+    automation: "manual",
+    notes: "Quality of description is human-only." },
+  { id: "1.2.4", title: "Captions (Live)", level: "AA", addedIn: "2.0",
+    automation: "manual" },
+  { id: "1.2.5", title: "Audio Description (Prerecorded)", level: "AA", addedIn: "2.0",
+    automation: "manual" },
+  { id: "1.2.6", title: "Sign Language (Prerecorded)", level: "AAA", addedIn: "2.0",
+    automation: "manual" },
+  { id: "1.2.7", title: "Extended Audio Description (Prerecorded)", level: "AAA", addedIn: "2.0",
+    automation: "manual" },
+  { id: "1.2.8", title: "Media Alternative (Prerecorded)", level: "AAA", addedIn: "2.0",
+    automation: "manual" },
+  { id: "1.2.9", title: "Audio-only (Live)", level: "AAA", addedIn: "2.0",
+    automation: "manual" },
+
+  { id: "1.3.1", title: "Info and Relationships", level: "A", addedIn: "2.0",
+    automation: "automated",
+    axeRules: ["definition-list", "dlitem", "list", "listitem", "table-fake-caption", "td-headers-attr", "th-has-data-cells", "scope-attr-valid", "aria-required-parent", "aria-required-children", "label", "form-field-multiple-labels", "p-as-heading"] },
+  { id: "1.3.2", title: "Meaningful Sequence", level: "A", addedIn: "2.0",
+    automation: "partial", axeRules: ["tabindex"], playwrightCheckable: true,
+    notes: "CLI compares DOM order to visual order via bounding boxes." },
+  { id: "1.3.3", title: "Sensory Characteristics", level: "A", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "1.3.4", title: "Orientation", level: "AA", addedIn: "2.1",
+    automation: "automated", axeRules: ["css-orientation-lock"] },
+  { id: "1.3.5", title: "Identify Input Purpose", level: "AA", addedIn: "2.1",
+    automation: "automated", axeRules: ["autocomplete-valid"] },
+  { id: "1.3.6", title: "Identify Purpose", level: "AAA", addedIn: "2.1",
+    automation: "manual" },
+
+  { id: "1.4.1", title: "Use of Color", level: "A", addedIn: "2.0",
+    automation: "partial", axeRules: ["link-in-text-block"], aiReviewable: true },
+  { id: "1.4.2", title: "Audio Control", level: "A", addedIn: "2.0",
+    automation: "automated", axeRules: ["no-autoplay-audio"], playwrightCheckable: true },
+  { id: "1.4.3", title: "Contrast (Minimum)", level: "AA", addedIn: "2.0",
+    automation: "automated", axeRules: ["color-contrast"] },
+  { id: "1.4.4", title: "Resize Text", level: "AA", addedIn: "2.0",
+    automation: "partial", axeRules: ["meta-viewport"], playwrightCheckable: true,
+    notes: "CLI zooms to 200% and checks for content loss / overflow." },
+  { id: "1.4.5", title: "Images of Text", level: "AA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "1.4.6", title: "Contrast (Enhanced)", level: "AAA", addedIn: "2.0",
+    automation: "automated", axeRules: ["color-contrast-enhanced"] },
+  { id: "1.4.7", title: "Low or No Background Audio", level: "AAA", addedIn: "2.0",
+    automation: "manual" },
+  { id: "1.4.8", title: "Visual Presentation", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "1.4.9", title: "Images of Text (No Exception)", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "1.4.10", title: "Reflow", level: "AA", addedIn: "2.1",
+    automation: "partial", axeRules: ["meta-viewport"], playwrightCheckable: true,
+    notes: "CLI shrinks viewport to 320 CSS px and checks for horizontal scroll." },
+  { id: "1.4.11", title: "Non-text Contrast", level: "AA", addedIn: "2.1",
+    automation: "manual", aiReviewable: true },
+  { id: "1.4.12", title: "Text Spacing", level: "AA", addedIn: "2.1",
+    automation: "manual", aiReviewable: true, playwrightCheckable: true,
+    notes: "CLI injects WCAG-required spacing CSS and checks for clipped text." },
+  { id: "1.4.13", title: "Content on Hover or Focus", level: "AA", addedIn: "2.1",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI hovers tooltip triggers and verifies dismissible/persistent/hoverable." },
+
+  // ─────────────────────────── 2. Operable ───────────────────────────
+  { id: "2.1.1", title: "Keyboard", level: "A", addedIn: "2.0",
+    automation: "partial",
+    axeRules: ["frame-focusable-content", "scrollable-region-focusable", "nested-interactive"],
+    playwrightCheckable: true,
+    notes: "CLI tabs through every interactive element." },
+  { id: "2.1.2", title: "No Keyboard Trap", level: "A", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI detects Tab cycles where focus never leaves a region." },
+  { id: "2.1.3", title: "Keyboard (No Exception)", level: "AAA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true },
+  { id: "2.1.4", title: "Character Key Shortcuts", level: "A", addedIn: "2.1",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI scans for global single-key keydown listeners." },
+
+  { id: "2.2.1", title: "Timing Adjustable", level: "A", addedIn: "2.0",
+    automation: "manual", axeRules: ["meta-refresh"], playwrightCheckable: true },
+  { id: "2.2.2", title: "Pause, Stop, Hide", level: "A", addedIn: "2.0",
+    automation: "partial", axeRules: ["blink", "marquee", "no-autoplay-audio"],
+    playwrightCheckable: true,
+    notes: "CLI records a timelapse and detects auto-updating content / autoplay." },
+  { id: "2.2.3", title: "No Timing", level: "AAA", addedIn: "2.0", automation: "manual" },
+  { id: "2.2.4", title: "Interruptions", level: "AAA", addedIn: "2.0", automation: "manual" },
+  { id: "2.2.5", title: "Re-authenticating", level: "AAA", addedIn: "2.0", automation: "manual" },
+  { id: "2.2.6", title: "Timeouts", level: "AAA", addedIn: "2.1", automation: "manual" },
+
+  { id: "2.3.1", title: "Three Flashes or Below Threshold", level: "A", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI captures a 10s timelapse and counts large frame-to-frame deltas." },
+  { id: "2.3.2", title: "Three Flashes", level: "AAA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true },
+  { id: "2.3.3", title: "Animation from Interactions", level: "AAA", addedIn: "2.1",
+    automation: "manual", playwrightCheckable: true },
+
+  { id: "2.4.1", title: "Bypass Blocks", level: "A", addedIn: "2.0",
+    automation: "automated", axeRules: ["bypass", "region", "landmark-one-main", "skip-link"] },
+  { id: "2.4.2", title: "Page Titled", level: "A", addedIn: "2.0",
+    automation: "automated", axeRules: ["document-title"] },
+  { id: "2.4.3", title: "Focus Order", level: "A", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI compares Tab order to visual reading order." },
+  { id: "2.4.4", title: "Link Purpose (In Context)", level: "A", addedIn: "2.0",
+    automation: "automated", axeRules: ["link-name"] },
+  { id: "2.4.5", title: "Multiple Ways", level: "AA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true, playwrightCheckable: true },
+  { id: "2.4.6", title: "Headings and Labels", level: "AA", addedIn: "2.0",
+    automation: "partial", axeRules: ["empty-heading", "heading-order", "empty-table-header"], aiReviewable: true },
+  { id: "2.4.7", title: "Focus Visible", level: "AA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI captures before/after focus state and pixel-diffs each control." },
+  { id: "2.4.8", title: "Location", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "2.4.9", title: "Link Purpose (Link Only)", level: "AAA", addedIn: "2.0",
+    automation: "automated", axeRules: ["link-name"] },
+  { id: "2.4.10", title: "Section Headings", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "2.4.11", title: "Focus Not Obscured (Minimum)", level: "AA", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI checks focused element rect vs sticky/fixed element rects." },
+  { id: "2.4.12", title: "Focus Not Obscured (Enhanced)", level: "AAA", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true },
+  { id: "2.4.13", title: "Focus Appearance", level: "AAA", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true },
+
+  { id: "2.5.1", title: "Pointer Gestures", level: "A", addedIn: "2.1",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI scans for multi-touch / path gesture event listeners." },
+  { id: "2.5.2", title: "Pointer Cancellation", level: "A", addedIn: "2.1",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI detects elements that act on pointerdown without an undo path." },
+  { id: "2.5.3", title: "Label in Name", level: "A", addedIn: "2.1",
+    automation: "automated", axeRules: ["label-content-name-mismatch"] },
+  { id: "2.5.4", title: "Motion Actuation", level: "A", addedIn: "2.1",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI scans for deviceorientation/devicemotion listeners." },
+  { id: "2.5.5", title: "Target Size (Enhanced)", level: "AAA", addedIn: "2.1",
+    automation: "automated", axeRules: ["target-size"] },
+  { id: "2.5.6", title: "Concurrent Input Mechanisms", level: "AAA", addedIn: "2.1",
+    automation: "manual" },
+  { id: "2.5.7", title: "Dragging Movements", level: "AA", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true },
+  { id: "2.5.8", title: "Target Size (Minimum)", level: "AA", addedIn: "2.2",
+    automation: "automated", axeRules: ["target-size"] },
+
+  // ─────────────────────────── 3. Understandable ───────────────────────────
+  { id: "3.1.1", title: "Language of Page", level: "A", addedIn: "2.0",
+    automation: "automated", axeRules: ["html-has-lang", "html-lang-valid", "html-xml-lang-mismatch"] },
+  { id: "3.1.2", title: "Language of Parts", level: "AA", addedIn: "2.0",
+    automation: "automated", axeRules: ["valid-lang"] },
+  { id: "3.1.3", title: "Unusual Words", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "3.1.4", title: "Abbreviations", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "3.1.5", title: "Reading Level", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "3.1.6", title: "Pronunciation", level: "AAA", addedIn: "2.0", automation: "manual" },
+
+  { id: "3.2.1", title: "On Focus", level: "A", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI focuses each control and watches for navigation / context change." },
+  { id: "3.2.2", title: "On Input", level: "A", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI types into each input and watches for navigation / context change." },
+  { id: "3.2.3", title: "Consistent Navigation", level: "AA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI crawls multiple pages and compares navigation structure." },
+  { id: "3.2.4", title: "Consistent Identification", level: "AA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true },
+  { id: "3.2.5", title: "Change on Request", level: "AAA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true },
+  { id: "3.2.6", title: "Consistent Help", level: "A", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI looks for a help mechanism in the same location across pages." },
+
+  { id: "3.3.1", title: "Error Identification", level: "A", addedIn: "2.0",
+    automation: "manual", axeRules: ["aria-required-attr"], playwrightCheckable: true,
+    notes: "CLI submits forms invalid and checks errors are announced." },
+  { id: "3.3.2", title: "Labels or Instructions", level: "A", addedIn: "2.0",
+    automation: "automated",
+    axeRules: ["label", "form-field-multiple-labels", "select-name", "input-button-name"] },
+  { id: "3.3.3", title: "Error Suggestion", level: "AA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI submits forms invalid and asks AI whether the error provides a fix." },
+  { id: "3.3.4", title: "Error Prevention (Legal, Financial, Data)", level: "AA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true },
+  { id: "3.3.5", title: "Help", level: "AAA", addedIn: "2.0", automation: "manual" },
+  { id: "3.3.6", title: "Error Prevention (All)", level: "AAA", addedIn: "2.0", automation: "manual" },
+  { id: "3.3.7", title: "Redundant Entry", level: "A", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI walks multi-step forms and detects duplicate fields." },
+  { id: "3.3.8", title: "Accessible Authentication (Minimum)", level: "AA", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI detects CAPTCHAs and other cognitive function tests." },
+  { id: "3.3.9", title: "Accessible Authentication (Enhanced)", level: "AAA", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true },
+
+  // ─────────────────────────── 4. Robust ───────────────────────────
+  { id: "4.1.1", title: "Parsing", level: "A", addedIn: "2.0", removedIn: "2.2",
+    automation: "automated", axeRules: ["duplicate-id", "duplicate-id-active", "duplicate-id-aria"] },
+  { id: "4.1.2", title: "Name, Role, Value", level: "A", addedIn: "2.0",
+    automation: "automated",
+    axeRules: ["aria-allowed-attr", "aria-allowed-role", "aria-command-name", "aria-hidden-body", "aria-hidden-focus", "aria-input-field-name", "aria-meter-name", "aria-progressbar-name", "aria-required-attr", "aria-required-children", "aria-required-parent", "aria-roles", "aria-toggle-field-name", "aria-tooltip-name", "aria-valid-attr", "aria-valid-attr-value", "button-name", "link-name", "select-name", "summary-name"] },
+  { id: "4.1.3", title: "Status Messages", level: "AA", addedIn: "2.1",
+    automation: "partial", axeRules: ["aria-allowed-role", "aria-valid-attr-value"] },
+];
+
+export function filterCriteriaForScope(version, levels) {
+  const upper = new Set(levels.map((l) => l.toUpperCase()));
+  return WCAG_CRITERIA.filter((c) => {
+    if (!upper.has(c.level)) return false;
+    if (version === "2.1" && c.addedIn === "2.2") return false;
+    if (version === "2.2" && c.removedIn === "2.2") return false;
+    return true;
+  });
+}
+
+export function buildAxeTags(version, levels, includeBP = false) {
+  const versions = version === "2.2" ? ["wcag2", "wcag21", "wcag22"] : ["wcag2", "wcag21"];
+  const tags = [];
+  for (const v of versions) {
+    for (const lvl of levels) {
+      const suffix = v === "wcag2" ? "" : v.slice(4);
+      tags.push(`wcag${suffix}${lvl.toLowerCase()}`);
+    }
+  }
+  if (includeBP) tags.push("best-practice");
+  return tags;
+}