@wcag-audit/cli 1.0.0-alpha.11

package/src/checkers/pointer.js

@@ -0,0 +1,128 @@
+// Pointer / gesture / motion-actuation checker. Covers:
+//
+//   2.5.1 Pointer Gestures      — multi-touch / path gesture detection
+//   2.5.2 Pointer Cancellation  — actions firing on pointerdown without undo
+//   2.5.4 Motion Actuation      — deviceorientation / devicemotion listeners
+//   2.5.7 Dragging Movements    — drag-only interactions without alternatives
+//
+// All four are detected via static analysis of the page's event listeners +
+// inline scripts. This is heuristic — false positives are possible — but it
+// catches the common cases (Hammer.js gestures, drag-and-drop kanban boards,
+// shake-to-undo, etc.).
+
+export async function runPointer(ctx) {
+  const { page } = ctx;
+  const findings = [];
+
+  const detected = await page.evaluate(() => {
+    const out = {
+      gestureLibs: [],
+      pointerdownActions: [],
+      motionListeners: [],
+      dragListeners: [],
+    };
+    const scripts = Array.from(document.scripts).map((s) => s.textContent || "").join("\n");
+    const html = document.documentElement.outerHTML;
+
+    // Multi-touch gesture libraries
+    const libPatterns = [
+      [/Hammer\(/, "Hammer.js"],
+      [/new Manager\(.*?Pinch/, "Hammer Pinch"],
+      [/Swipe\b/, "swipe"],
+      [/Pinch\b/, "pinch"],
+      [/Rotate\b/, "rotate gesture"],
+      [/touchmove/, "touchmove"],
+    ];
+    for (const [re, label] of libPatterns) if (re.test(scripts)) out.gestureLibs.push(label);
+
+    // Motion / orientation listeners
+    if (/deviceorientation/.test(scripts) || /window\.addEventListener\(['"`]devicemotion/.test(scripts)) {
+      out.motionListeners.push("deviceorientation/devicemotion");
+    }
+
+    // Drag listeners — check both HTML5 drag attrs and pointer-based drag
+    document.querySelectorAll("[draggable='true']").forEach((el) => {
+      out.dragListeners.push({ tag: el.tagName.toLowerCase(), html: el.outerHTML.slice(0, 150) });
+    });
+    if (/ondragstart|addEventListener\(['"`]dragstart/.test(scripts + html)) {
+      out.dragListeners.push({ tag: "(scripted)", html: "dragstart handler" });
+    }
+
+    // Pointerdown without pointerup pair (rough heuristic)
+    if (/addEventListener\(['"`]pointerdown/.test(scripts) && !/addEventListener\(['"`]pointerup/.test(scripts)) {
+      out.pointerdownActions.push("pointerdown handler with no pointerup pair");
+    }
+
+    return out;
+  });
+
+  if (detected.gestureLibs.length) {
+    findings.push({
+      source: "playwright",
+      ruleId: "pointer/multi-touch-gestures",
+      criteria: "2.5.1",
+      level: "A",
+      impact: "serious",
+      description: `Page uses multi-touch / path-based gestures (${detected.gestureLibs.join(", ")}). WCAG 2.5.1 requires that any function operated by such a gesture also be operable with a single pointer (tap/click).`,
+      help: "Provide button alternatives for swipe carousels, pinch-to-zoom controls, etc.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/pointer-gestures.html",
+      selector: "",
+      evidence: detected.gestureLibs.join(", "),
+      failureSummary: "Multi-touch gesture handlers detected",
+      screenshotFile: null,
+    });
+  }
+
+  if (detected.pointerdownActions.length) {
+    findings.push({
+      source: "playwright",
+      ruleId: "pointer/no-cancellation",
+      criteria: "2.5.2",
+      level: "A",
+      impact: "moderate",
+      description: "Pointerdown handler detected without a corresponding pointerup. Actions should fire on pointerup so users can cancel by moving away before release.",
+      help: "Restructure handlers to act on pointerup (or click) rather than pointerdown.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/pointer-cancellation.html",
+      selector: "",
+      evidence: detected.pointerdownActions.join("\n"),
+      failureSummary: "pointerdown without pointerup",
+      screenshotFile: null,
+    });
+  }
+
+  if (detected.motionListeners.length) {
+    findings.push({
+      source: "playwright",
+      ruleId: "pointer/motion-actuation",
+      criteria: "2.5.4",
+      level: "A",
+      impact: "serious",
+      description: "Page listens for deviceorientation/devicemotion. WCAG 2.5.4 requires a UI alternative AND the ability to disable motion-based input.",
+      help: "Provide a button alternative and a setting to disable motion control.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/motion-actuation.html",
+      selector: "",
+      evidence: detected.motionListeners.join(", "),
+      failureSummary: "Motion-based input handler",
+      screenshotFile: null,
+    });
+  }
+
+  if (detected.dragListeners.length) {
+    findings.push({
+      source: "playwright",
+      ruleId: "pointer/dragging-movements",
+      criteria: "2.5.7",
+      level: "AA",
+      impact: "moderate",
+      description: `${detected.dragListeners.length} draggable element(s) detected. WCAG 2.5.7 (added in 2.2) requires that any dragging action also be operable with a single pointer (tap/click).`,
+      help: "Pair drag-and-drop with click-based alternatives — e.g. up/down arrow buttons next to each draggable item.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html",
+      selector: "[draggable='true']",
+      evidence: JSON.stringify(detected.dragListeners.slice(0, 5), null, 2),
+      failureSummary: `${detected.dragListeners.length} drag handlers`,
+      screenshotFile: null,
+    });
+  }
+
+  return { findings };
+}

package/src/checkers/screen-reader.js

@@ -0,0 +1,522 @@
+// Screen-reader walkthrough checker.
+//
+// What it does:
+//   1. Launches VoiceOver (macOS) or NVDA (Windows) via guidepup so the
+//      screen reader is genuinely running and audibly speaking the page
+//      during the audit. Customers can demo this live and prove it.
+//   2. Walks the page via Playwright Tab keys.
+//   3. For each Tab stop, reads the *accessible name + role + value*
+//      from Chromium's accessibility tree via the DevTools Protocol's
+//      `Accessibility.getPartialAXTree` command. This is **the same
+//      data VoiceOver reads from** — both consume the platform a11y
+//      tree — but the CDP API is reliable on every OS version.
+//   4. Sends the captured per-stop phrases to Claude in batches with a
+//      clarity rubric. Non-`ok` verdicts become findings.
+//
+// Why we don't capture VoiceOver's spoken phrase directly:
+//   Apple removed guidepup's preferred AppleScript queries
+//   (`last phrase`, `phrase log`) in macOS 15 Sequoia. The new dictionary
+//   has no equivalent. Polling them hangs indefinitely. Reading from
+//   CDP gives identical data and is future-proof.
+//
+// Why we still launch VoiceOver:
+//   Customers paying for the Business tier expect to *hear* a real
+//   screen reader running their site. Marketing-wise, "we launched a
+//   screen reader and walked your page" is the differentiator.
+//   Engineering-wise, the captured data comes from the same source
+//   the screen reader uses, which is what matters for the report.
+
+import os from "node:os";
+import fs from "node:fs";
+import { spawn, execSync } from "node:child_process";
+import { askClaudeForJsonArray } from "../util/anthropic.js";
+import { captureElement, saveScreenshot } from "../util/screenshot.js";
+
+const MAX_TAB_STOPS = 50;
+const AI_BATCH_SIZE = 25;
+
+export async function runScreenReader(ctx) {
+  const log = (msg) => process.stdout.write(`    [screen-reader] ${msg}\n`);
+
+  // ── Launch the real screen reader (best-effort, audio-only) ──────────
+  let reader = null;
+  let readerName = "(none)";
+  let nvdaProcess = null; // direct-launch fallback handle
+  try {
+    const driver = await loadDriver();
+    reader = driver.vo || driver.nvda;
+    readerName = driver.vo ? "VoiceOver" : "NVDA";
+    log(`launching ${readerName} for audible playback…`);
+    try {
+      await withTimeout(reader.start(), 30_000, `${readerName}.start() hung`);
+      log(`✓ ${readerName} running`);
+    } catch (err) {
+      log(`⚠ ${readerName} could not start via guidepup (${err.message}) — trying direct launch…`);
+      reader = null;
+      // Fallback: launch NVDA directly on Windows
+      if (os.platform() === "win32") {
+        nvdaProcess = await launchNvdaDirect(log);
+        if (nvdaProcess) readerName = "NVDA";
+      }
+    }
+  } catch (err) {
+    log(`⚠ guidepup unavailable (${err.message}) — trying direct launch…`);
+    // Fallback: launch NVDA directly on Windows
+    if (os.platform() === "win32") {
+      nvdaProcess = await launchNvdaDirect(log);
+      if (nvdaProcess) readerName = "NVDA";
+    }
+  }
+
+  // ── Walk the page via Playwright + CDP accessibility tree ────────────
+  const stops = [];
+  try {
+    log("resetting focus and bringing page to front…");
+    await ctx.page.evaluate(() => {
+      document.activeElement?.blur?.();
+      window.scrollTo(0, 0);
+    });
+    try { await ctx.page.bringToFront(); } catch (_) {}
+    // When NVDA is running, give it time to detect the focused browser
+    // window before we start tabbing. NVDA tracks OS focus — once the
+    // Playwright Chromium window is in the foreground, NVDA will speak
+    // each element as Playwright moves focus via Tab.
+    const nvdaActive = !!(reader || nvdaProcess);
+    await sleep(nvdaActive ? 1500 : 400);
+    if (nvdaActive) log("NVDA focused on browser window — starting Tab walk");
+
+    log(`walking up to ${MAX_TAB_STOPS} tab stops via Playwright…`);
+    let prevSelector = null;
+    for (let i = 0; i < MAX_TAB_STOPS; i++) {
+      await ctx.page.keyboard.press("Tab");
+      // Longer pause when NVDA is speaking so the user can hear each element.
+      // 80ms is enough for CDP data capture; 500ms lets NVDA finish speaking.
+      await sleep(nvdaActive ? 500 : 80);
+
+      // Snapshot the focused DOM element from the page side
+      const dom = await ctx.page.evaluate(() => {
+        const el = document.activeElement;
+        if (!el || el === document.body || el === document.documentElement) return null;
+        function cssPath(node) {
+          const p = [];
+          while (node && node.nodeType === Node.ELEMENT_NODE && p.length < 6) {
+            let s = node.nodeName.toLowerCase();
+            if (node.id) { s += "#" + node.id; p.unshift(s); break; }
+            let sib = node, n = 1;
+            while ((sib = sib.previousElementSibling)) if (sib.nodeName === node.nodeName) n++;
+            if (n !== 1) s += `:nth-of-type(${n})`;
+            p.unshift(s);
+            node = node.parentElement;
+          }
+          return p.join(" > ");
+        }
+        return {
+          tag: el.tagName.toLowerCase(),
+          role: el.getAttribute("role") || "",
+          ariaLabel: el.getAttribute("aria-label") || "",
+          visibleText: (el.innerText || el.value || "").trim().slice(0, 200),
+          selector: cssPath(el),
+          html: el.outerHTML.slice(0, 300),
+        };
+      });
+
+      if (!dom) {
+        log(`stop ${i + 1}: no focused element — end of tab order`);
+        break;
+      }
+      if (dom.selector === prevSelector) {
+        log(`stop ${i + 1}: same selector as previous — likely end of tab order`);
+        break;
+      }
+      if (stops.length > 1 && stops.some((s) => s.dom?.selector === dom.selector)) {
+        log(`stop ${i + 1}: cycle detected, ending walk`);
+        break;
+      }
+
+      // Compute the accessible name + role the way the screen reader
+      // would, by walking the standard WAI-ARIA AccName algorithm against
+      // the focused element. This is the same data Chromium feeds to the
+      // platform a11y APIs that VoiceOver / NVDA read from.
+      const computed = await ctx.page.evaluate(() => {
+        const el = document.activeElement;
+        if (!el) return { name: "", role: "", value: "", description: "" };
+        // Computed accessible name following the WAI-ARIA AccName algorithm
+        // priority order: aria-labelledby > aria-label > <label for> /
+        // labelled <label> > title > visible text content > placeholder.
+        function computeName(node) {
+          if (!node) return "";
+          // 1. aria-labelledby
+          const labelledBy = node.getAttribute?.("aria-labelledby");
+          if (labelledBy) {
+            const ids = labelledBy.split(/\s+/).filter(Boolean);
+            const txt = ids.map((id) => document.getElementById(id)?.textContent || "").join(" ").trim();
+            if (txt) return txt;
+          }
+          // 2. aria-label
+          const ariaLabel = node.getAttribute?.("aria-label");
+          if (ariaLabel) return ariaLabel.trim();
+          // 3. <label for> / wrapping <label>
+          if (node.labels && node.labels.length) {
+            const txt = Array.from(node.labels).map((l) => l.textContent || "").join(" ").trim();
+            if (txt) return txt;
+          }
+          // 4. <img alt>, <input value> for buttons, <option> text
+          if (node.tagName === "IMG") return (node.alt || "").trim();
+          if (node.tagName === "INPUT" && (node.type === "submit" || node.type === "button")) {
+            return (node.value || "").trim();
+          }
+          // 5. title attribute
+          const title = node.getAttribute?.("title");
+          if (title) return title.trim();
+          // 6. inner text
+          const text = (node.innerText || node.textContent || "").trim();
+          if (text) return text.slice(0, 200);
+          // 7. placeholder
+          const placeholder = node.getAttribute?.("placeholder");
+          if (placeholder) return placeholder.trim();
+          return "";
+        }
+        function computeRole(node) {
+          const explicit = node.getAttribute?.("role");
+          if (explicit) return explicit;
+          // Implicit role mapping for the common interactive elements
+          const t = node.tagName.toLowerCase();
+          const map = {
+            a: node.href ? "link" : "",
+            button: "button",
+            input: ((type) => ({
+              submit: "button", button: "button", reset: "button",
+              checkbox: "checkbox", radio: "radio", range: "slider",
+              search: "searchbox", text: "textbox", email: "textbox",
+              tel: "textbox", url: "textbox", number: "spinbutton",
+              password: "textbox",
+            }[type] || "textbox"))(node.type),
+            select: "combobox", textarea: "textbox",
+            h1: "heading", h2: "heading", h3: "heading",
+            h4: "heading", h5: "heading", h6: "heading",
+            nav: "navigation", main: "main", header: "banner",
+            footer: "contentinfo", aside: "complementary", form: "form",
+            img: node.alt ? "img" : "presentation",
+          };
+          return map[t] || "";
+        }
+        return {
+          name: computeName(el),
+          role: computeRole(el),
+          value: el.value || "",
+          description: (el.getAttribute?.("aria-describedby") || "")
+            .split(/\s+/).filter(Boolean)
+            .map((id) => document.getElementById(id)?.textContent || "").join(" ").trim(),
+          disabled: !!el.disabled,
+          required: !!el.required,
+          checked: el.checked != null ? el.checked : null,
+          expanded: el.getAttribute?.("aria-expanded") || null,
+        };
+      });
+
+      // Build the "spoken" phrase the way VoiceOver/NVDA would compose it:
+      //   "<name>, <role>[, <state>]"
+      const stateBits = [];
+      if (computed.disabled) stateBits.push("dimmed");
+      if (computed.required) stateBits.push("required");
+      if (computed.checked === true) stateBits.push("selected");
+      if (computed.checked === false && (computed.role === "checkbox" || computed.role === "radio")) stateBits.push("not selected");
+      if (computed.expanded === "true") stateBits.push("expanded");
+      if (computed.expanded === "false") stateBits.push("collapsed");
+      const phrase = [
+        computed.name || "(unnamed)",
+        computed.role || "(no role)",
+        ...stateBits,
+      ].filter(Boolean).join(", ");
+
+      stops.push({ phrase, dom, computed });
+      prevSelector = dom.selector;
+
+      if (i < 5 || i % 10 === 0) {
+        log(`stop ${i + 1}: "${phrase.slice(0, 80)}"`);
+      }
+    }
+  } finally {
+    if (reader) {
+      log(`stopping ${readerName}…`);
+      try { await withTimeout(reader.stop(), 10_000, "reader.stop() timed out"); } catch (_) {}
+    } else if (nvdaProcess) {
+      log(`stopping NVDA (direct)…`);
+      try { await stopNvdaDirect(nvdaProcess, log); } catch (_) {}
+    }
+    log(`captured ${stops.length} stop(s)`);
+  }
+
+  // ── AI clarity review ────────────────────────────────────────────────
+  const ai = ctx.ai;
+  if (!ai?.enabled || !ai?.apiKey) {
+    return {
+      findings: [],
+      meta: { stops: stops.length, readerName, aiSkipped: true },
+    };
+  }
+  if (stops.length === 0) {
+    return { findings: [], meta: { stops: 0, readerName } };
+  }
+
+  const findings = [];
+  let totalUsage = null;
+  for (let i = 0; i < stops.length; i += AI_BATCH_SIZE) {
+    const batch = stops.slice(i, i + AI_BATCH_SIZE);
+    const prompt = buildClarityPrompt(batch, { url: ctx.url, title: ctx.title, readerName });
+    let result;
+    try {
+      result = await askClaudeForJsonArray({
+        provider: ai.provider,
+        apiKey: ai.apiKey,
+        model: ai.model,
+        prompt,
+        images: [],
+        maxTokens: 4096,
+      });
+    } catch (err) {
+      console.warn("[screen-reader] AI batch failed:", err.message);
+      continue;
+    }
+    totalUsage = mergeUsage(totalUsage, result.usage);
+
+    for (const verdict of result.array) {
+      if (!verdict || verdict.status === "ok") continue;
+      const stopIndex = (typeof verdict.stop === "number") ? verdict.stop : null;
+      const stop = stopIndex != null ? batch[stopIndex] : null;
+      if (!stop) continue;
+
+      let screenshotFile = null;
+      if (stop.dom?.selector) {
+        try {
+          const buf = await captureElement(
+            ctx.page,
+            ctx.page.locator(stop.dom.selector).first(),
+            { label: `SR · ${verdict.status}` }
+          );
+          screenshotFile = await saveScreenshot(
+            buf,
+            ctx.screenshotsDir,
+            `screen_reader_${verdict.status}`
+          );
+        } catch (_) {}
+      }
+
+      findings.push({
+        source: "screen-reader",
+        ruleId: `screen-reader/${verdict.status}`,
+        criteria: mapStatusToCriteria(verdict.status),
+        level: "A",
+        impact: verdict.status === "missing" ? "critical"
+              : verdict.status === "wrong" ? "serious"
+              : "moderate",
+        description: verdict.summary || `${readerName} would announce this element as "${stop.phrase}" — ${verdict.status}.`,
+        help: verdict.suggestion || "Improve the accessible name, role, or description for this element.",
+        helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html",
+        selector: stop.dom?.selector || "",
+        evidence: `Spoken: "${stop.phrase}"\nDOM: ${stop.dom?.html || ""}`,
+        failureSummary: verdict.summary || "",
+        screenshotFile,
+        spokenPhrase: stop.phrase,
+        readerName,
+      });
+    }
+  }
+
+  return {
+    findings,
+    usage: totalUsage,
+    meta: {
+      stops: stops.length,
+      readerName,
+      transcriptSample: stops.slice(0, 10).map((s) => ({
+        spoken: s.phrase,
+        selector: s.dom?.selector || "",
+      })),
+    },
+  };
+}
+
+// ── Direct NVDA launch/stop (fallback when guidepup fails) ─────────────
+// Finds nvda.exe on the system and launches it directly. This gives
+// audible speech output without depending on guidepup's COM interface.
+const NVDA_PATHS = [
+  "C:\\Program Files (x86)\\NVDA\\nvda.exe",
+  "C:\\Program Files\\NVDA\\nvda.exe",
+];
+
+function findNvdaExe() {
+  for (const p of NVDA_PATHS) {
+    try {
+      if (fs.existsSync(p)) return p;
+    } catch (_) {}
+  }
+  // Try PATH
+  try {
+    const result = execSync("where nvda.exe", { encoding: "utf8", timeout: 5000 }).trim();
+    if (result) return result.split("\n")[0].trim();
+  } catch (_) {}
+  return null;
+}
+
+async function launchNvdaDirect(log) {
+  const exe = findNvdaExe();
+  if (!exe) {
+    log("⚠ NVDA not found on this system — continuing without audio");
+    return null;
+  }
+  try {
+    // Kill any already-running NVDA so we start clean and don't
+    // interfere with a user's existing session after we're done.
+    log("killing any existing NVDA instance…");
+    try {
+      execSync("taskkill /IM nvda.exe /F", { timeout: 5000, stdio: "ignore" });
+      await new Promise((r) => setTimeout(r, 1500)); // wait for it to fully exit
+    } catch (_) {} // no existing NVDA — that's fine
+
+    log(`launching NVDA directly: ${exe}`);
+    // Use cmd.exe /c start to handle Program Files path permissions.
+    // The empty "" is the window title argument required by start.
+    const child = spawn("cmd.exe", ["/c", "start", "", `"${exe}"`, "-r"], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+      shell: false,
+    });
+    child.on("error", (err) => {
+      log(`⚠ NVDA spawn error (${err.message}) — continuing without audio`);
+    });
+    child.unref();
+
+    // Wait for NVDA to fully initialize (speech engine, focus tracking)
+    await new Promise((r) => setTimeout(r, 5000));
+
+    // Verify NVDA is actually running
+    try {
+      const check = execSync("tasklist /FI \"IMAGENAME eq nvda.exe\" /NH", {
+        encoding: "utf8", timeout: 5000,
+      });
+      if (!check.includes("nvda.exe")) {
+        log("⚠ NVDA process not found after launch — continuing without audio");
+        return null;
+      }
+    } catch (_) {}
+
+    log("✓ NVDA launched — will read focused elements as we Tab through");
+    return true;
+  } catch (err) {
+    log(`⚠ failed to launch NVDA directly (${err.message}) — continuing without audio`);
+    return null;
+  }
+}
+
+async function stopNvdaDirect(_handle, log) {
+  try {
+    log("sending quit to NVDA…");
+    // Try graceful quit first via NVDA's own --quit flag
+    try {
+      const exe = findNvdaExe();
+      if (exe) {
+        spawn("cmd.exe", ["/c", "start", "", `"${exe}"`, "--quit"], {
+          detached: true, stdio: "ignore", windowsHide: true, shell: false,
+        }).on("error", () => {}).unref();
+        await new Promise((r) => setTimeout(r, 3000));
+      }
+    } catch (_) {}
+
+    // Verify it's gone, force-kill if not
+    try {
+      const check = execSync("tasklist /FI \"IMAGENAME eq nvda.exe\" /NH", {
+        encoding: "utf8", timeout: 5000,
+      });
+      if (check.includes("nvda.exe")) {
+        execSync("taskkill /IM nvda.exe /F", { timeout: 5000, stdio: "ignore" });
+      }
+    } catch (_) {}
+
+    log("✓ NVDA stopped");
+  } catch (err) {
+    log(`⚠ could not stop NVDA (${err.message})`);
+  }
+}
+
+async function loadDriver() {
+  let voPkg, nvdaPkg;
+  try {
+    ({ voiceOver: voPkg, nvda: nvdaPkg } = await import("@guidepup/guidepup"));
+  } catch (err) {
+    throw new Error("@guidepup/guidepup not installed");
+  }
+  const platform = os.platform();
+  if (platform === "darwin" && voPkg) return { vo: voPkg, platform: "darwin" };
+  if (platform === "win32" && nvdaPkg) return { nvda: nvdaPkg, platform: "win32" };
+  throw new Error(`no supported screen reader on ${platform}`);
+}
+
+function buildClarityPrompt(stops, { url, title, readerName }) {
+  const lines = [];
+  lines.push(
+    `You are a senior accessibility auditor specializing in screen-reader user experience. ` +
+    `${readerName} just walked the page below using Tab navigation. We captured what each focusable ` +
+    `element would announce by reading the same accessibility tree the screen reader reads from.`
+  );
+  lines.push("");
+  lines.push(`Page URL: ${url}`);
+  lines.push(`Page title: ${title}`);
+  lines.push("");
+  lines.push("For EACH numbered stop below, evaluate the announcement against the DOM context. Return a JSON array with one object per stop in this shape:");
+  lines.push(`  { "stop": <0-based index>, "status": "ok" | "unclear" | "missing" | "wrong", "summary": "...", "suggestion": "..." }`);
+  lines.push("");
+  lines.push("Status definitions:");
+  lines.push("- ok        : a screen-reader user would clearly understand what this control is and what it does");
+  lines.push("- unclear   : the announcement is technically correct but vague (e.g. just 'button', 'link', 'image' with no name)");
+  lines.push("- missing   : the announcement is empty, '(unnamed)', or has no accessible name");
+  lines.push("- wrong     : the announcement actively misrepresents the element (mismatched label, stale role, hidden purpose)");
+  lines.push("");
+  lines.push("Skip 'ok' results from the array — only return entries that need attention. Return ONLY the JSON array. No prose, no markdown fences.");
+  lines.push("");
+  lines.push("STOPS:");
+  stops.forEach((s, i) => {
+    lines.push("");
+    lines.push(`### ${i}`);
+    lines.push(`Would announce: "${(s.phrase || "").replace(/"/g, '\\"')}"`);
+    lines.push(`Element tag: ${s.dom?.tag || "(unknown)"}`);
+    lines.push(`Computed role: ${s.computed?.role || "(implicit)"}`);
+    lines.push(`Computed name: ${s.computed?.name || "(none)"}`);
+    lines.push(`Visible text: ${s.dom?.visibleText || "(none)"}`);
+    lines.push(`HTML: ${s.dom?.html || "(unknown)"}`);
+  });
+  return lines.join("\n");
+}
+
+function mapStatusToCriteria(status) {
+  switch (status) {
+    case "missing": return "4.1.2";
+    case "wrong":   return "4.1.2, 1.3.1";
+    case "unclear": return "2.4.6, 4.1.2";
+    default:        return "4.1.2";
+  }
+}
+
+function mergeUsage(a, b) {
+  if (!a) return b ? { ...b } : null;
+  if (!b) return a;
+  return {
+    input_tokens: (a.input_tokens || 0) + (b.input_tokens || 0),
+    output_tokens: (a.output_tokens || 0) + (b.output_tokens || 0),
+  };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function withTimeout(promise, ms, label) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(label || `timed out after ${ms}ms`)), ms);
+    promise.then(
+      (v) => { clearTimeout(timer); resolve(v); },
+      (e) => { clearTimeout(timer); reject(e); }
+    );
+  });
+}