@wcag-audit/cli 1.0.0-alpha.3

package/src/checkers/keyboard.js

@@ -0,0 +1,347 @@
+// Keyboard / focus checker. Covers (substantially):
+//
+//   2.1.1 Keyboard           — Tab through every focusable element
+//   2.1.2 No Keyboard Trap   — detect Tab cycles that never escape a region
+//   2.1.4 Character Key Shortcuts — detect global single-key listeners
+//   2.4.3 Focus Order        — Tab order vs visual reading order (top→bot, l→r)
+//   2.4.7 Focus Visible      — pixel-diff before/after focus per control
+//   2.4.11 Focus Not Obscured — focused rect vs sticky/fixed element rects
+//   2.4.12 Focus Not Obscured (Enhanced) — stricter version
+//
+// We also cap the walk at MAX_TAB_STOPS to keep large pages tractable.
+
+import { PNG } from "pngjs";
+import pixelmatch from "pixelmatch";
+import { saveScreenshot, captureElement } from "../util/screenshot.js";
+
+const MAX_TAB_STOPS = 200;
+const FOCUS_PIXEL_DIFF_THRESHOLD = 25; // changed pixels needed to call focus "visible"
+
+export async function runKeyboard(ctx) {
+  const { page } = ctx;
+  const findings = [];
+
+  // ── 2.1.4 Character key shortcuts ────────────────────────────────────
+  const singleKeyListeners = await page.evaluate(() => {
+    // Heuristic: look for window/document keydown listeners. We can't read
+    // installed listeners, but we can scan inline scripts for hotkey
+    // libraries (mousetrap, hotkeys-js, tinykeys) and bare event handlers.
+    const scripts = Array.from(document.scripts).map((s) => s.textContent || "").join("\n");
+    const hits = [];
+    const patterns = [
+      [/Mousetrap\.bind\(['"`]([a-z0-9])['"`]/gi, "Mousetrap.bind('$1')"],
+      [/hotkeys\(['"`]([a-z0-9])['"`]/gi, "hotkeys('$1')"],
+      [/tinykeys\([^,]+,\s*\{\s*['"`]([a-z0-9])['"`]/gi, "tinykeys {'$1'}"],
+      [/addEventListener\(['"`]keydown['"`][^)]*key\s*[=]==?\s*['"`]([a-z0-9])['"`]/gi, "keydown key=='$1'"],
+    ];
+    for (const [re, label] of patterns) {
+      let m;
+      while ((m = re.exec(scripts))) hits.push(`${label.replace("$1", m[1])}`);
+    }
+    return Array.from(new Set(hits)).slice(0, 20);
+  });
+  if (singleKeyListeners.length) {
+    findings.push({
+      source: "playwright",
+      ruleId: "kbd/single-key-shortcut",
+      criteria: "2.1.4",
+      level: "A",
+      impact: "moderate",
+      description: "Single-character keyboard shortcut(s) detected. WCAG 2.1.4 requires that such shortcuts be turn-off-able, remappable, or only active on focus.",
+      help: "Detected handlers: " + singleKeyListeners.join(", "),
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html",
+      selector: "",
+      evidence: singleKeyListeners.join("\n"),
+      failureSummary: "Confirm shortcuts can be disabled or are only active when component has focus.",
+      screenshotFile: null,
+    });
+  }
+
+  // ── Tab walk for 2.1.1 / 2.1.2 / 2.4.3 / 2.4.7 / 2.4.11 ─────────────
+  await page.evaluate(() => {
+    if (document.activeElement && document.activeElement !== document.body) {
+      document.activeElement.blur();
+    }
+    window.scrollTo(0, 0);
+  });
+  await page.waitForTimeout(100);
+
+  // Get initial reference screenshot of the empty-focus state for diffing.
+  const baselineShot = await page.screenshot({ fullPage: false, type: "png" });
+  const baselinePng = PNG.sync.read(baselineShot);
+
+  const stops = [];
+  let prevSelector = null;
+  let trapDetected = false;
+
+  for (let i = 0; i < MAX_TAB_STOPS; i++) {
+    await page.keyboard.press("Tab");
+    await page.waitForTimeout(30);
+
+    const info = await page.evaluate(() => {
+      const el = document.activeElement;
+      if (!el || el === document.body || el === document.documentElement) return null;
+      function cssPath(node) {
+        if (!(node instanceof Element)) return "";
+        const path = [];
+        while (node && node.nodeType === Node.ELEMENT_NODE && path.length < 6) {
+          let sel = node.nodeName.toLowerCase();
+          if (node.id) { sel += "#" + node.id; path.unshift(sel); break; }
+          let sib = node, nth = 1;
+          while ((sib = sib.previousElementSibling)) if (sib.nodeName === node.nodeName) nth++;
+          if (nth !== 1) sel += `:nth-of-type(${nth})`;
+          path.unshift(sel);
+          node = node.parentElement;
+        }
+        return path.join(" > ");
+      }
+      const r = el.getBoundingClientRect();
+      return {
+        tag: el.tagName.toLowerCase(),
+        text: (el.innerText || el.value || el.getAttribute("aria-label") || "").trim().slice(0, 80),
+        selector: cssPath(el),
+        rect: { x: r.x, y: r.y, w: r.width, h: r.height },
+        outerHTML: el.outerHTML.slice(0, 200),
+      };
+    });
+
+    if (!info) break;
+    if (info.selector === prevSelector) {
+      // Same element after a Tab — likely a trap or end of doc
+      trapDetected = true;
+      break;
+    }
+    stops.push(info);
+    prevSelector = info.selector;
+
+    // Check if we've cycled back to the first element (normal end of tab order)
+    if (stops.length > 1 && info.selector === stops[0].selector) {
+      stops.pop();
+      break;
+    }
+  }
+
+  // ── 2.1.2 Keyboard trap ─────────────────────────────────────────────
+  if (trapDetected) {
+    findings.push({
+      source: "playwright",
+      ruleId: "kbd/trap",
+      criteria: "2.1.2",
+      level: "A",
+      impact: "critical",
+      description: "Suspected keyboard trap: pressing Tab from a focused control did not advance focus.",
+      help: "Verify the user can leave this region using Tab/Shift+Tab. WCAG 2.1.2 forbids any region that requires non-standard keys to escape.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html",
+      selector: prevSelector || "",
+      evidence: prevSelector || "",
+      failureSummary: "Tab key did not move focus.",
+      screenshotFile: null,
+    });
+  }
+
+  // ── 2.1.1 Keyboard ─ if no Tab stops found, the page is unusable by kbd
+  if (stops.length === 0) {
+    findings.push({
+      source: "playwright",
+      ruleId: "kbd/no-focusable",
+      criteria: "2.1.1",
+      level: "A",
+      impact: "serious",
+      description: "No focusable elements were reached via the Tab key.",
+      help: "Either the page has no interactive content, or interactive controls are not keyboard reachable.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html",
+      selector: "",
+      evidence: "",
+      failureSummary: "Tab walk reached zero stops.",
+      screenshotFile: null,
+    });
+  }
+
+  // ── 2.4.3 Focus order vs visual order ───────────────────────────────
+  // Sort stops by visual position (top-to-bottom, left-to-right with row tolerance)
+  // and compare to actual Tab order. Mismatches → fail.
+  const visualOrder = [...stops]
+    .map((s, i) => ({ s, i }))
+    .sort((a, b) => {
+      const ay = a.s.rect.y, by = b.s.rect.y;
+      if (Math.abs(ay - by) > 20) return ay - by;
+      return a.s.rect.x - b.s.rect.x;
+    })
+    .map((x) => x.i);
+  const expected = stops.map((_, i) => i);
+  const mismatches = [];
+  for (let i = 0; i < expected.length; i++) {
+    if (visualOrder[i] !== expected[i]) {
+      mismatches.push({ tabPosition: i + 1, expectedSelector: stops[visualOrder[i]]?.selector, actualSelector: stops[i].selector });
+    }
+  }
+  // Only fail if there are several misorderings (a single one near a fixed-pos
+  // element is usually fine). Threshold: more than 15% of stops out of order.
+  if (mismatches.length > Math.max(3, stops.length * 0.15)) {
+    findings.push({
+      source: "playwright",
+      ruleId: "kbd/focus-order",
+      criteria: "2.4.3",
+      level: "A",
+      impact: "serious",
+      description: `Tab order does not match visual reading order at ${mismatches.length} of ${stops.length} stops.`,
+      help: "Tab order should follow the visible reading sequence. Reorder DOM or use tabindex carefully (avoid positive tabindex values).",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html",
+      selector: mismatches.slice(0, 5).map((m) => m.actualSelector).join(", "),
+      evidence: JSON.stringify(mismatches.slice(0, 10), null, 2),
+      failureSummary: `${mismatches.length} stops out of visual order`,
+      screenshotFile: null,
+    });
+  }
+
+  // ── 2.4.7 Focus Visible ─ pixel diff each focused stop against baseline
+  // Sample only the first ~30 stops to keep things fast.
+  const focusFails = [];
+  const sampled = stops.slice(0, 30);
+  for (let i = 0; i < sampled.length; i++) {
+    const stop = sampled[i];
+    // Re-focus by clicking via JS (avoid triggering navigation by using focus())
+    await page.evaluate((sel) => {
+      try { document.querySelector(sel)?.focus({ preventScroll: false }); } catch (_) {}
+    }, stop.selector);
+    await page.waitForTimeout(40);
+
+    const focusedShot = await page.screenshot({ fullPage: false, type: "png" });
+    const focusedPng = PNG.sync.read(focusedShot);
+    if (focusedPng.width !== baselinePng.width || focusedPng.height !== baselinePng.height) continue;
+    const diff = new PNG({ width: focusedPng.width, height: focusedPng.height });
+    const changed = pixelmatch(
+      baselinePng.data,
+      focusedPng.data,
+      diff.data,
+      focusedPng.width,
+      focusedPng.height,
+      { threshold: 0.25 }
+    );
+    if (changed < FOCUS_PIXEL_DIFF_THRESHOLD) {
+      focusFails.push(stop);
+    }
+  }
+  if (focusFails.length) {
+    for (const f of focusFails.slice(0, 10)) {
+      let screenshotFile = null;
+      try {
+        const buf = await captureElement(ctx.page, ctx.page.locator(f.selector).first(), {
+          label: "Focus invisible",
+        });
+        screenshotFile = await saveScreenshot(buf, ctx.screenshotsDir, "kbd_focus_visible");
+      } catch (_) {}
+      findings.push({
+        source: "playwright",
+        ruleId: "kbd/focus-visible",
+        criteria: "2.4.7",
+        level: "AA",
+        impact: "serious",
+        description: "No visible focus indicator detected when this control received keyboard focus.",
+        help: "Ensure :focus or :focus-visible styles produce a clearly visible outline / change. Default browser outline must not be removed without a replacement.",
+        helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html",
+        selector: f.selector,
+        evidence: f.outerHTML,
+        failureSummary: "Pixel diff between unfocused and focused state was below threshold.",
+        screenshotFile,
+      });
+    }
+  }
+
+  // ── 2.4.11 / 2.4.12 Focus Not Obscured ───────────────────────────────
+  // Find sticky/fixed-position elements and check whether the focused element
+  // intersects them while being below the sticky band.
+  //
+  // Skip cases that are NOT actually obscured:
+  //   1. The focused element is INSIDE the sticky element (e.g. nav links
+  //      inside a sticky nav) — they overlap geometrically but the user
+  //      can still see/interact with them.
+  //   2. The focused element is more than 95% covered AND the sticky is
+  //      small (< 10% of viewport) — likely a toast or banner that
+  //      should get its own fix, not a layout violation.
+  const stickyRects = await page.evaluate(() => {
+    const out = [];
+    document.querySelectorAll("*").forEach((el, idx) => {
+      const cs = getComputedStyle(el);
+      if ((cs.position === "fixed" || cs.position === "sticky") && cs.visibility !== "hidden" && cs.display !== "none") {
+        const r = el.getBoundingClientRect();
+        if (r.width > 0 && r.height > 0) {
+          // Tag the element so the containment check can find it again
+          const marker = `data-wcag-sticky-${idx}`;
+          el.setAttribute(marker, "1");
+          out.push({
+            x: r.x,
+            y: r.y,
+            w: r.width,
+            h: r.height,
+            tag: el.tagName.toLowerCase(),
+            marker,
+          });
+        }
+      }
+    });
+    return out.slice(0, 30);
+  });
+
+  const obscured = [];
+  for (const stop of sampled) {
+    for (const sr of stickyRects) {
+      const sx1 = sr.x, sy1 = sr.y, sx2 = sr.x + sr.w, sy2 = sr.y + sr.h;
+      const fx1 = stop.rect.x, fy1 = stop.rect.y, fx2 = stop.rect.x + stop.rect.w, fy2 = stop.rect.y + stop.rect.h;
+      const overlapX = Math.max(0, Math.min(sx2, fx2) - Math.max(sx1, fx1));
+      const overlapY = Math.max(0, Math.min(sy2, fy2) - Math.max(sy1, fy1));
+      const overlap = overlapX * overlapY;
+      const focusedArea = stop.rect.w * stop.rect.h;
+      // WCAG 2.4.11 says the focused element must not be ENTIRELY hidden.
+      // Allow up to 75% overlap before flagging — partial obscuring is
+      // acceptable per the spec.
+      if (focusedArea > 0 && overlap / focusedArea > 0.75) {
+        // Skip if the focused element is a descendant of the sticky
+        // element. Example: nav logo focused inside a sticky nav.
+        const isDescendant = await page.evaluate(
+          ({ sel, marker }) => {
+            try {
+              const sticky = document.querySelector(`[${marker}]`);
+              const focused = sel ? document.querySelector(sel) : null;
+              if (!sticky || !focused) return false;
+              return sticky.contains(focused);
+            } catch {
+              return false;
+            }
+          },
+          { sel: stop.selector, marker: sr.marker },
+        );
+        if (isDescendant) continue;
+        obscured.push({ stop, sticky: sr });
+        break;
+      }
+    }
+  }
+
+  // Clean up the marker attributes we added
+  await page.evaluate(() => {
+    document.querySelectorAll("[data-wcag-sticky-0],[data-wcag-sticky-1],[data-wcag-sticky-2],[data-wcag-sticky-3],[data-wcag-sticky-4],[data-wcag-sticky-5],[data-wcag-sticky-6],[data-wcag-sticky-7],[data-wcag-sticky-8],[data-wcag-sticky-9]").forEach((el) => {
+      [...el.attributes].forEach((a) => {
+        if (a.name.startsWith("data-wcag-sticky-")) el.removeAttribute(a.name);
+      });
+    });
+  }).catch(() => {});
+  for (const o of obscured.slice(0, 10)) {
+    findings.push({
+      source: "playwright",
+      ruleId: "kbd/focus-not-obscured",
+      criteria: "2.4.11",
+      level: "AA",
+      impact: "serious",
+      description: `Focused element is more than 50% obscured by a sticky/fixed element (${o.sticky.tag}).`,
+      help: "When a control receives keyboard focus, it must not be entirely hidden behind sticky headers, cookie banners, or other fixed UI.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html",
+      selector: o.stop.selector,
+      evidence: `Focused: ${JSON.stringify(o.stop.rect)} sticky: ${JSON.stringify(o.sticky)}`,
+      failureSummary: "Focused element overlapped sticky element by >50%.",
+      screenshotFile: null,
+    });
+  }
+
+  return { findings };
+}

package/src/checkers/media.js

@@ -0,0 +1,102 @@
+// Media presence checker. Covers (substantially):
+//
+//   1.2.1 Audio-only / Video-only — detects <audio>/<video>; transcript
+//                                   accuracy is human-only
+//   1.2.2 Captions (Prerecorded)  — checks <video> for <track kind=captions>
+//
+// We do NOT pretend to verify caption accuracy or audio description quality.
+// Those criteria are flagged as "needs human review" with a screenshot of
+// the media element so the human reviewer has a starting point.
+
+import { captureElement, saveScreenshot } from "../util/screenshot.js";
+
+export async function runMedia(ctx) {
+  const { page } = ctx;
+  const findings = [];
+
+  const media = await page.evaluate(() => {
+    const out = { videos: [], audios: [], iframes: [] };
+    document.querySelectorAll("video").forEach((v, i) => {
+      out.videos.push({
+        idx: i,
+        src: v.currentSrc || v.src || "",
+        hasCaptionTrack: !!v.querySelector("track[kind='captions']"),
+        hasSubtitleTrack: !!v.querySelector("track[kind='subtitles']"),
+        hasDescTrack: !!v.querySelector("track[kind='descriptions']"),
+        autoplay: v.autoplay,
+        muted: v.muted,
+      });
+    });
+    document.querySelectorAll("audio").forEach((a, i) => {
+      out.audios.push({
+        idx: i,
+        src: a.currentSrc || a.src || "",
+        autoplay: a.autoplay,
+      });
+    });
+    // Embedded YouTube/Vimeo iframes — we can't introspect their captions
+    // from outside the iframe, so we surface them for human review.
+    document.querySelectorAll("iframe[src*='youtube'],iframe[src*='vimeo'],iframe[src*='wistia']").forEach((f, i) => {
+      out.iframes.push({ idx: i, src: f.src });
+    });
+    return out;
+  });
+
+  for (let i = 0; i < media.videos.length; i++) {
+    const v = media.videos[i];
+    if (!v.hasCaptionTrack && !v.hasSubtitleTrack) {
+      const buf = await captureElement(page, page.locator("video").nth(i), { label: "Video w/o captions" });
+      const screenshotFile = await saveScreenshot(buf, ctx.screenshotsDir, "media_no_captions");
+      findings.push({
+        source: "playwright",
+        ruleId: "media/no-captions",
+        criteria: "1.2.2",
+        level: "A",
+        impact: "serious",
+        description: "Video element has no <track kind='captions'> or <track kind='subtitles'>.",
+        help: "Provide a captions track for any prerecorded video with audio. WCAG 1.2.2.",
+        helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/captions-prerecorded.html",
+        selector: `video:nth-of-type(${i + 1})`,
+        evidence: v.src || "(no src)",
+        failureSummary: "Missing captions track",
+        screenshotFile,
+      });
+    }
+    if (!v.hasDescTrack) {
+      findings.push({
+        source: "playwright",
+        ruleId: "media/no-audio-description",
+        criteria: "1.2.5",
+        level: "AA",
+        impact: "moderate",
+        description: "Video element has no <track kind='descriptions'> for audio description (and no human review confirms a media alternative is provided).",
+        help: "Provide audio description for video with significant visual content. WCAG 1.2.5. Mark as 'reviewed - not applicable' if a separate descriptive transcript or media alternative is offered.",
+        helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/audio-description-prerecorded.html",
+        selector: `video:nth-of-type(${i + 1})`,
+        evidence: v.src || "(no src)",
+        failureSummary: "No descriptions track — needs human review",
+        screenshotFile: null,
+      });
+    }
+  }
+
+  // Embedded video iframes: surface for human review.
+  for (const iframe of media.iframes) {
+    findings.push({
+      source: "playwright",
+      ruleId: "media/embedded-iframe",
+      criteria: "1.2.2",
+      level: "A",
+      impact: "moderate",
+      description: "Embedded media iframe (YouTube/Vimeo/Wistia). Caption presence cannot be verified from outside the iframe.",
+      help: "Confirm captions are enabled in the embedded player. Most providers support a captions track URL parameter (e.g. YouTube cc_load_policy=1).",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/captions-prerecorded.html",
+      selector: `iframe[src*='${iframe.src.split("/")[2] || ""}']`,
+      evidence: iframe.src,
+      failureSummary: "Embedded video — needs human review",
+      screenshotFile: null,
+    });
+  }
+
+  return { findings };
+}

package/src/checkers/motion.js

@@ -0,0 +1,155 @@
+// Motion / animation / autoplay checker. Covers:
+//
+//   2.2.2 Pause, Stop, Hide       — autoplay video, marquee, animations
+//   2.3.1 Three Flashes (or below) — pixel-diff a 5s screenshot timelapse
+//   2.3.3 Animation from Interactions — partial: detect prefers-reduced-motion handling
+//
+// Flash detection method: capture ~30 screenshots at 6 fps, compute the
+// fraction of pixels that changed between consecutive frames using
+// pixelmatch. A flash is a frame where >10% of pixels change. >3 flashes
+// in any 1-second window = fail.
+
+import { PNG } from "pngjs";
+import pixelmatch from "pixelmatch";
+import { saveScreenshot } from "../util/screenshot.js";
+
+const FRAMES = 30;
+const FRAME_INTERVAL_MS = 167; // ~6 fps → ~5s total
+const FLASH_PIXEL_FRACTION = 0.10; // 10% of pixels changed = 1 flash
+
+export async function runMotion(ctx) {
+  const { page } = ctx;
+  const findings = [];
+
+  // ── 2.2.2 Autoplay video / animations ───────────────────────────────
+  const motionInfo = await page.evaluate(() => {
+    const out = { autoplayVideos: [], marquee: [], blink: [], animatedSvg: 0, cssAnimations: 0 };
+    document.querySelectorAll("video[autoplay]").forEach((v) => {
+      if (v.paused === false || v.autoplay) {
+        out.autoplayVideos.push({ src: v.currentSrc || v.src, muted: v.muted, loop: v.loop });
+      }
+    });
+    document.querySelectorAll("marquee").forEach((m) => out.marquee.push(m.outerHTML.slice(0, 200)));
+    document.querySelectorAll("blink").forEach((b) => out.blink.push(b.outerHTML.slice(0, 200)));
+    document.querySelectorAll("svg animate, svg animateTransform, svg animateMotion").forEach(() => out.animatedSvg++);
+    document.querySelectorAll("*").forEach((el) => {
+      const cs = getComputedStyle(el);
+      if (cs.animationName && cs.animationName !== "none" && cs.animationDuration !== "0s") out.cssAnimations++;
+    });
+    return out;
+  });
+
+  if (motionInfo.autoplayVideos.length) {
+    findings.push({
+      source: "playwright",
+      ruleId: "motion/autoplay-video",
+      criteria: "2.2.2",
+      level: "A",
+      impact: "serious",
+      description: `${motionInfo.autoplayVideos.length} autoplay video element(s) detected.`,
+      help: "WCAG 2.2.2: any moving content that starts automatically and lasts more than 5 seconds must be pausable. Consider muted+looped decorative video only, with a pause control.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html",
+      selector: "video[autoplay]",
+      evidence: JSON.stringify(motionInfo.autoplayVideos.slice(0, 5), null, 2),
+      failureSummary: `${motionInfo.autoplayVideos.length} autoplay video(s)`,
+      screenshotFile: null,
+    });
+  }
+  if (motionInfo.marquee.length || motionInfo.blink.length) {
+    findings.push({
+      source: "playwright",
+      ruleId: "motion/deprecated-marquee-blink",
+      criteria: "2.2.2",
+      level: "A",
+      impact: "moderate",
+      description: `Deprecated <marquee>/<blink> elements detected. These cannot be paused via standard mechanisms.`,
+      help: "Replace with CSS or remove. WCAG 2.2.2.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html",
+      selector: motionInfo.marquee.length ? "marquee" : "blink",
+      evidence: [...motionInfo.marquee, ...motionInfo.blink].join("\n"),
+      failureSummary: "Deprecated motion element",
+      screenshotFile: null,
+    });
+  }
+
+  // ── 2.3.1 Flash detection via timelapse ─────────────────────────────
+  const frames = [];
+  for (let i = 0; i < FRAMES; i++) {
+    const buf = await page.screenshot({ fullPage: false, type: "png" });
+    frames.push(PNG.sync.read(buf));
+    await page.waitForTimeout(FRAME_INTERVAL_MS);
+  }
+
+  let totalFlashes = 0;
+  const flashTimestamps = [];
+  for (let i = 1; i < frames.length; i++) {
+    const a = frames[i - 1], b = frames[i];
+    if (a.width !== b.width || a.height !== b.height) continue;
+    const total = a.width * a.height;
+    const diff = new PNG({ width: a.width, height: a.height });
+    const changed = pixelmatch(a.data, b.data, diff.data, a.width, a.height, { threshold: 0.3 });
+    if (changed / total > FLASH_PIXEL_FRACTION) {
+      totalFlashes++;
+      flashTimestamps.push(i * FRAME_INTERVAL_MS);
+    }
+  }
+
+  // Look for any 1-second window with > 3 flashes
+  let maxIn1s = 0;
+  for (const t of flashTimestamps) {
+    const inWindow = flashTimestamps.filter((x) => x >= t && x < t + 1000).length;
+    if (inWindow > maxIn1s) maxIn1s = inWindow;
+  }
+
+  if (maxIn1s > 3) {
+    findings.push({
+      source: "playwright",
+      ruleId: "motion/flashing",
+      criteria: "2.3.1",
+      level: "A",
+      impact: "critical",
+      description: `Detected ${maxIn1s} large screen changes within a 1-second window during a 5-second observation. WCAG 2.3.1 forbids more than 3 flashes per second.`,
+      help: "Reduce flashing animations. Use prefers-reduced-motion to disable. Consider seizure-safety carefully.",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/three-flashes-or-below-threshold.html",
+      selector: "",
+      evidence: `Total large frame transitions: ${totalFlashes}; max in 1s window: ${maxIn1s}`,
+      failureSummary: "Possible photosensitive seizure risk",
+      screenshotFile: null,
+    });
+  }
+
+  // ── 2.3.3 Animation from interactions ─ partial check ───────────────
+  // Detect whether the site has any prefers-reduced-motion media query at
+  // all. If it has many CSS animations but no reduced-motion handling, flag.
+  const hasReducedMotionMQ = await page.evaluate(() => {
+    let found = false;
+    for (const sheet of Array.from(document.styleSheets)) {
+      try {
+        for (const rule of Array.from(sheet.cssRules || [])) {
+          if (rule.type === CSSRule.MEDIA_RULE && rule.conditionText.includes("prefers-reduced-motion")) {
+            found = true;
+          }
+        }
+      } catch (_) {}
+    }
+    return found;
+  });
+  if (motionInfo.cssAnimations > 5 && !hasReducedMotionMQ) {
+    findings.push({
+      source: "playwright",
+      ruleId: "motion/no-reduced-motion-mq",
+      criteria: "2.3.3",
+      level: "AAA",
+      impact: "moderate",
+      description: `${motionInfo.cssAnimations} CSS animations detected but no @media (prefers-reduced-motion) rule found in any stylesheet.`,
+      help: "Honor the user's reduced-motion preference. Wrap non-essential animations in @media (prefers-reduced-motion: no-preference) or set animation-duration: 0 inside (prefers-reduced-motion: reduce).",
+      helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html",
+      selector: "",
+      evidence: `CSS animations: ${motionInfo.cssAnimations}`,
+      failureSummary: "No reduced-motion media query",
+      screenshotFile: null,
+    });
+  }
+
+  return { findings };
+}