a11y-loop 0.1.0

package/src/lib/checks/reduced-motion.js

@@ -0,0 +1,139 @@
+/**
+ * Does `prefers-reduced-motion: reduce` actually do anything?
+ *
+ * Declaring a media query is not the same as honouring it. This samples
+ * computed animation state while the browser reports the reduce preference, and
+ * reports animations that are still running.
+ *
+ * Criterion mapping, chosen to stay honest about levels:
+ *  - An animation that loops forever, or runs for more than 5 seconds, and
+ *    starts on its own is SC 2.2.2 Pause, Stop, Hide (Level A) → violation.
+ *  - A short, finite animation is SC 2.3.3 Animation from Interactions
+ *    (Level AAA) → needs review, because AAA is not part of an AA target.
+ */
+
+import { makeFinding, SEVERITY } from '../finding.js';
+
+/** SC 2.2.2's threshold for "more than five seconds". */
+export const LONG_ANIMATION_SECONDS = 5;
+
+/** `"2s"` → 2, `"500ms"` → 0.5, `"0s"` → 0. Handles comma-separated lists. */
+export function parseSeconds(value) {
+  if (typeof value !== 'string') return 0;
+  const durations = value.split(',').map((part) => {
+    const text = part.trim();
+    const number = Number.parseFloat(text);
+    if (!Number.isFinite(number)) return 0;
+    return /ms$/.test(text) ? number / 1000 : number;
+  });
+  return Math.max(0, ...durations);
+}
+
+/** `"infinite"` or a finite count. */
+export function isInfinite(iterationCount) {
+  return String(iterationCount ?? '').split(',').some((part) => part.trim() === 'infinite');
+}
+
+/**
+ * @param {Array<{selector:string, html:string, animationName:string,
+ *   animationDuration:string, animationPlayState:string, animationIterationCount:string,
+ *   transitionDuration:string}>} samples
+ */
+export function findRunningAnimations(samples = []) {
+  const running = [];
+  for (const sample of samples) {
+    const names = (sample.animationName ?? 'none')
+      .split(',')
+      .map((n) => n.trim())
+      .filter((n) => n && n !== 'none');
+    if (names.length === 0) continue;
+
+    const duration = parseSeconds(sample.animationDuration);
+    if (duration === 0) continue;
+    const playState = String(sample.animationPlayState ?? 'running');
+    if (playState.split(',').every((s) => s.trim() === 'paused')) continue;
+
+    const infinite = isInfinite(sample.animationIterationCount);
+    running.push({
+      selector: sample.selector,
+      html: sample.html,
+      names,
+      duration,
+      infinite,
+      continuous: infinite || duration > LONG_ANIMATION_SECONDS,
+    });
+  }
+  return running;
+}
+
+/**
+ * @param {Array} samples
+ * @param {{passes:string[], state:string|null}} ctx
+ */
+export function reducedMotionFindings(samples, ctx) {
+  const { passes = [], state = null } = ctx ?? {};
+  return findRunningAnimations(samples).map((animation) => {
+    const lifetime = animation.infinite
+      ? 'loops forever'
+      : `runs for ${animation.duration}s`;
+    return makeFinding({
+      ruleId: 'reduced-motion-ignored',
+      source: 'a11y-loop',
+      severity: animation.continuous ? SEVERITY.VIOLATION : SEVERITY.NEEDS_REVIEW,
+      impact: animation.continuous ? 'serious' : 'moderate',
+      sc: animation.continuous ? '2.2.2' : '2.3.3',
+      selector: animation.selector,
+      html: animation.html,
+      message:
+        `Animation "${animation.names.join(', ')}" is still running while the browser reports ` +
+        `prefers-reduced-motion: reduce, and it ${lifetime}. Wrap the animation in ` +
+        '@media (prefers-reduced-motion: no-preference), or disable it under reduce.' +
+        (animation.continuous
+          ? ''
+          : ' Short, finite animations are Level AAA, so this is flagged for review rather ' +
+            'than as an AA failure.'),
+      passes,
+      state,
+      data: {
+        animationNames: animation.names,
+        durationSeconds: animation.duration,
+        infinite: animation.infinite,
+      },
+    });
+  });
+}
+
+/**
+ * Sample computed animation state. Only meaningful on the reduced-motion pass.
+ *
+ * Uses isRendered rather than isVisible deliberately: SC 2.2.2 is about
+ * motion a SIGHTED user can see, which has nothing to do with the
+ * accessibility tree. A moving element inside an aria-hidden container (a
+ * decorative marquee/ticker, say) is still a real vestibular hazard and still
+ * needs to stop under prefers-reduced-motion, even though it is correctly
+ * invisible to a screen reader.
+ *
+ * @param {import('playwright').Page} page
+ */
+export async function surveyAnimations(page) {
+  return page.evaluate(() => {
+    const helpers = window.__a11yLoop;
+    const samples = [];
+    for (const el of document.querySelectorAll('*')) {
+      if (!helpers.isRendered(el)) continue;
+      const style = getComputedStyle(el);
+      if (!style.animationName || style.animationName === 'none') continue;
+      samples.push({
+        selector: helpers.cssPath(el),
+        html: helpers.shortHtml(el),
+        animationName: style.animationName,
+        animationDuration: style.animationDuration,
+        animationPlayState: style.animationPlayState,
+        animationIterationCount: style.animationIterationCount,
+        transitionDuration: style.transitionDuration,
+      });
+      if (samples.length >= 30) break;
+    }
+    return samples;
+  });
+}

package/src/lib/checks/reflow.js

@@ -0,0 +1,101 @@
+/**
+ * Reflow (SC 1.4.10, Level AA) at 320×256.
+ *
+ * Playwright has no browser zoom API, but it does not need one: SC 1.4.10 says
+ * "320 CSS pixels is equivalent to a starting viewport width of 1280 CSS pixels
+ * wide at 400% zoom". Setting the viewport to 320×256 IS the 400% zoom test.
+ *
+ * The criterion excepts content that genuinely needs two-dimensional layout
+ * (data tables, maps, diagrams), which is why this reports named overflowing
+ * elements for review rather than failing the page outright.
+ */
+
+import { makeFinding, SEVERITY } from '../finding.js';
+
+export const REFLOW_VIEWPORT = { width: 320, height: 256 };
+
+/** Elements whose overflow SC 1.4.10 explicitly tolerates. */
+const TWO_DIMENSIONAL_TAGS = new Set(['TABLE', 'SVG', 'CANVAS', 'IFRAME', 'VIDEO', 'IMG', 'PRE']);
+
+/**
+ * @param {{horizontalScroll:boolean, scrollWidth:number, clientWidth:number, culprits:Array}} result
+ * @param {{passes:string[], state:string|null}} ctx
+ */
+export function reflowFindings(result, ctx) {
+  const { passes = [], state = null } = ctx ?? {};
+  if (!result?.horizontalScroll) return [];
+
+  const culprits = result.culprits ?? [];
+  const excepted = culprits.filter((c) => TWO_DIMENSIONAL_TAGS.has(c.tag));
+  const plain = culprits.filter((c) => !TWO_DIMENSIONAL_TAGS.has(c.tag));
+  const named = (plain.length ? plain : culprits).slice(0, 5);
+
+  const overflowBy = result.scrollWidth - result.clientWidth;
+  const list = named.length
+    ? named
+        .map((c) => `${c.selector ?? c.tag.toLowerCase()} (extends to ${c.right}px)`)
+        .join(', ')
+    : 'no single element could be identified';
+
+  const exceptionNote = excepted.length
+    ? ` ${excepted.length} of the overflowing element(s) are ` +
+      `${[...new Set(excepted.map((c) => c.tag.toLowerCase()))].join('/')}, which SC 1.4.10 ` +
+      'excepts when the content genuinely requires two-dimensional layout.'
+    : '';
+
+  return [
+    makeFinding({
+      ruleId: 'reflow-horizontal-scroll',
+      source: 'a11y-loop',
+      severity: plain.length ? SEVERITY.VIOLATION : SEVERITY.NEEDS_REVIEW,
+      impact: 'serious',
+      sc: '1.4.10',
+      selector: named[0]?.selector ?? 'html',
+      html: named[0]?.html ?? '',
+      message:
+        `At a ${REFLOW_VIEWPORT.width}×${REFLOW_VIEWPORT.height} viewport (equivalent to 400% ` +
+        `zoom at 1280px) the page scrolls horizontally by ${overflowBy}px. Overflowing: ` +
+        `${list}.${exceptionNote}`,
+      passes,
+      state,
+      data: {
+        viewport: REFLOW_VIEWPORT,
+        scrollWidth: result.scrollWidth,
+        clientWidth: result.clientWidth,
+        culprits: culprits.slice(0, 20),
+      },
+    }),
+  ];
+}
+
+/**
+ * Detect horizontal overflow and name the elements responsible.
+ * Assumes the viewport has already been set to 320×256.
+ *
+ * @param {import('playwright').Page} page
+ */
+export async function surveyReflow(page) {
+  return page.evaluate(() => {
+    const helpers = window.__a11yLoop;
+    const doc = document.documentElement;
+    const clientWidth = doc.clientWidth;
+    const horizontalScroll = doc.scrollWidth > clientWidth + 1;
+    const culprits = [];
+    if (horizontalScroll) {
+      for (const el of document.body.querySelectorAll('*')) {
+        const rect = el.getBoundingClientRect();
+        if (rect.right > clientWidth + 1 && rect.width > 0) {
+          culprits.push({
+            tag: el.tagName,
+            selector: helpers.cssPath(el),
+            html: helpers.shortHtml(el, 120),
+            right: Math.round(rect.right),
+            width: Math.round(rect.width),
+          });
+        }
+        if (culprits.length >= 20) break;
+      }
+    }
+    return { horizontalScroll, scrollWidth: doc.scrollWidth, clientWidth, culprits };
+  });
+}

package/src/lib/checks/target-size.js

@@ -0,0 +1,128 @@
+/**
+ * Target size (SC 2.5.8, Level AA, new in WCAG 2.2).
+ *
+ * Our own geometric check rather than axe's `target-size`, which is disabled by
+ * default and has a documented false-positive trail. We measure the rect and
+ * apply the Spacing exception explicitly, so the report explains itself:
+ * "18×18 CSS px, and the 24 px spacing circle overlaps <other element>".
+ *
+ * Everything here is needs-review, never a hard failure. Of the criterion's
+ * five exceptions, only Spacing is measurable: Equivalent, Inline, User agent
+ * control and Essential all require knowing the author's intent.
+ */
+
+import { makeFinding, SEVERITY } from '../finding.js';
+
+export const MIN_TARGET_PX = 24;
+
+const centerOf = (rect) => ({ x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 });
+
+/**
+ * Does a 24 px-diameter circle centred on this target stay clear of every other
+ * target's circle? Two circles of radius 12 clear each other when their centres
+ * are at least 24 px apart.
+ */
+export function meetsSpacingException(target, allTargets) {
+  const c = centerOf(target.rect);
+  for (const other of allTargets) {
+    if (other === target || other.selector === target.selector) continue;
+    const o = centerOf(other.rect);
+    const distance = Math.hypot(c.x - o.x, c.y - o.y);
+    if (distance < MIN_TARGET_PX) return { met: false, conflictsWith: other.selector, distance };
+  }
+  return { met: true };
+}
+
+/**
+ * @param {Array<{selector:string, html:string, rect:{x:number,y:number,width:number,height:number}, inline?:boolean}>} targets
+ * @returns {Array<{selector:string, html:string, width:number, height:number, spacing:object, inline:boolean}>}
+ */
+export function evaluateTargets(targets = []) {
+  const undersized = targets.filter(
+    (t) => t.rect.width < MIN_TARGET_PX || t.rect.height < MIN_TARGET_PX,
+  );
+  return undersized.map((t) => ({
+    selector: t.selector,
+    html: t.html,
+    width: Math.round(t.rect.width * 10) / 10,
+    height: Math.round(t.rect.height * 10) / 10,
+    inline: Boolean(t.inline),
+    spacing: meetsSpacingException(t, targets),
+  }));
+}
+
+/**
+ * @param {Array} targets
+ * @param {{passes:string[], state:string|null}} ctx
+ */
+export function targetSizeFindings(targets, ctx) {
+  const { passes = [], state = null } = ctx ?? {};
+  return evaluateTargets(targets).map((t) => {
+    const size = `${t.width}×${t.height} CSS px`;
+    const detail = t.spacing.met
+      ? 'No other target sits within 24 px, so the Spacing exception may apply.'
+      : `The 24 px spacing circle overlaps ${t.spacing.conflictsWith} ` +
+        `(centres ${Math.round(t.spacing.distance)} px apart), so the Spacing exception does not apply.`;
+    const inlineNote = t.inline
+      ? ' This target is inside a sentence, so the Inline exception may also apply.'
+      : '';
+
+    return makeFinding({
+      ruleId: 'target-size-min',
+      source: 'a11y-loop',
+      severity: SEVERITY.NEEDS_REVIEW,
+      impact: 'moderate',
+      sc: '2.5.8',
+      selector: t.selector,
+      html: t.html,
+      message:
+        `Target is ${size}, smaller than the 24×24 minimum. ${detail}${inlineNote} ` +
+        'The Equivalent, User agent control and Essential exceptions cannot be judged ' +
+        'automatically — confirm one applies, or enlarge the target.',
+      passes,
+      state,
+      data: {
+        width: t.width,
+        height: t.height,
+        minimum: MIN_TARGET_PX,
+        spacingExceptionMet: t.spacing.met,
+        conflictsWith: t.spacing.conflictsWith ?? null,
+      },
+    });
+  });
+}
+
+/**
+ * Measure every interactive element's rect.
+ * @param {import('playwright').Page} page
+ */
+export async function surveyTargets(page) {
+  return page.evaluate(() => {
+    const helpers = window.__a11yLoop;
+    return helpers.interactiveElements().map((el) => {
+      const rect = el.getBoundingClientRect();
+      // SC 2.5.8's Inline exception covers targets in a sentence or block of
+      // text, so compare against the nearest text-bearing block rather than the
+      // immediate parent — a link wrapped in a <span> would otherwise look
+      // standalone.
+      const block = el.closest('p, li, td, th, dd, blockquote, figcaption, h1, h2, h3, h4, h5, h6');
+      const blockText = (block?.textContent ?? '').trim();
+      const ownText = (el.textContent ?? '').trim();
+      const inline =
+        getComputedStyle(el).display === 'inline' &&
+        Boolean(block) &&
+        blockText.length > ownText.length + 10;
+      return {
+        selector: helpers.cssPath(el),
+        html: helpers.shortHtml(el),
+        inline,
+        rect: {
+          x: rect.x,
+          y: rect.y,
+          width: rect.width,
+          height: rect.height,
+        },
+      };
+    });
+  });
+}

package/src/lib/contrast-math.js

@@ -0,0 +1,189 @@
+/**
+ * WCAG 2.x contrast math — own implementation.
+ *
+ * Reference (WCAG 2.2, Understanding SC 1.4.3):
+ *   c_srgb = c_8bit / 255
+ *   c      = c_srgb <= 0.04045 ? c_srgb / 12.92 : ((c_srgb + 0.055) / 1.055) ** 2.4
+ *   L      = 0.2126 * R + 0.7152 * G + 0.0722 * B
+ *   ratio  = (L_lighter + 0.05) / (L_darker + 0.05)
+ *
+ * Deliberate choices, for reproducibility against the WebAIM Contrast Checker
+ * (the de facto reference implementation practitioners compare against):
+ *  - Channels are quantised to 8 bits on parse, because that is what a browser
+ *    actually renders and what WebAIM operates on.
+ *  - Alpha is composited in NON-LINEAR sRGB (the same thing browsers and
+ *    axe-core do) before linearisation.
+ *  - The displayed ratio is TRUNCATED to 2 decimals, never rounded up. This is
+ *    what axe-core does (`Math.floor(contrast * 100) / 100` in
+ *    color-contrast-evaluate) and it is why the canonical figure for red on
+ *    white is 3.99:1 and not 4.00:1. The pass/fail verdict uses the full
+ *    precision ratio, so a pair can never reach a threshold by rounding.
+ */
+
+import { parse, converter } from 'culori';
+
+const toRgb = converter('rgb');
+
+export class ColorParseError extends Error {
+  constructor(input) {
+    super(`Could not parse color: ${JSON.stringify(input)}`);
+    this.name = 'ColorParseError';
+    this.input = input;
+  }
+}
+
+/** WCAG threshold table. `nonText` is SC 1.4.11 (UI components / graphical objects). */
+export const THRESHOLDS = {
+  normal: { AA: 4.5, AAA: 7 },
+  large: { AA: 3, AAA: 4.5 },
+  nonText: { AA: 3 },
+};
+
+/** SC that governs each context. */
+export const CONTEXT_SC = {
+  normal: { AA: '1.4.3', AAA: '1.4.6' },
+  large: { AA: '1.4.3', AAA: '1.4.6' },
+  'non-text': { AA: '1.4.11' },
+};
+
+const to8bit = (v) => Math.round(Math.min(1, Math.max(0, v)) * 255);
+
+/**
+ * Parse any CSS color string into 8-bit sRGB channels plus alpha.
+ * @param {string} input
+ * @returns {{r:number,g:number,b:number,alpha:number,hex:string}}
+ */
+export function parseColor(input) {
+  if (typeof input !== 'string' || input.trim() === '') throw new ColorParseError(input);
+  let raw = input.trim();
+  // Bare hex digits are a very common agent/user input ("777777").
+  if (/^[0-9a-f]{3}$|^[0-9a-f]{4}$|^[0-9a-f]{6}$|^[0-9a-f]{8}$/i.test(raw)) raw = `#${raw}`;
+  const parsed = parse(raw);
+  if (!parsed) throw new ColorParseError(input);
+  const rgb = toRgb(parsed);
+  if (!rgb) throw new ColorParseError(input);
+  const r = to8bit(rgb.r);
+  const g = to8bit(rgb.g);
+  const b = to8bit(rgb.b);
+  const alpha = rgb.alpha === undefined ? 1 : Math.min(1, Math.max(0, rgb.alpha));
+  return { r, g, b, alpha, hex: toHex({ r, g, b }) };
+}
+
+/** @returns {string} lowercase `#rrggbb` */
+export function toHex({ r, g, b }) {
+  const h = (v) => Math.round(v).toString(16).padStart(2, '0');
+  return `#${h(r)}${h(g)}${h(b)}`;
+}
+
+/**
+ * Composite `fg` over `bg` in non-linear sRGB (what browsers do).
+ * @returns {{r:number,g:number,b:number,alpha:number,hex:string}}
+ */
+export function composite(fg, bg) {
+  const a = fg.alpha ?? 1;
+  if (a >= 1) return { ...fg, alpha: 1 };
+  const mix = (f, b) => Math.round(f * a + b * (1 - a));
+  const out = { r: mix(fg.r, bg.r), g: mix(fg.g, bg.g), b: mix(fg.b, bg.b), alpha: 1 };
+  return { ...out, hex: toHex(out) };
+}
+
+/** Relative luminance of an opaque 8-bit sRGB color. */
+export function relativeLuminance({ r, g, b }) {
+  const lin = (v8) => {
+    const c = v8 / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** Contrast ratio between two opaque colors. Order-independent. */
+export function contrastRatio(a, b) {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  const lighter = Math.max(la, lb);
+  const darker = Math.min(la, lb);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Truncate to 2 decimals for display — never for the verdict, and never
+ * upward. Matches axe-core's `Math.floor(contrast * 100) / 100`.
+ */
+export function truncateRatio(ratio) {
+  return Math.floor(ratio * 100) / 100;
+}
+
+/** `4.47828` → `"4.47"`, `21` → `"21"`. */
+export function formatRatio(ratio) {
+  const r = truncateRatio(ratio);
+  return Number.isInteger(r) ? String(r) : r.toFixed(2);
+}
+
+/**
+ * WCAG "large scale" text: 18pt regular / 14pt bold, i.e. >=24px / >=18.5px bold
+ * (1pt = 4/3 px). This boundary is the most common source of disagreement
+ * between contrast tools; 18.5 rather than 18.66 matches axe-core.
+ */
+export function isLargeText(fontSizePx, bold = false) {
+  const px = Number(fontSizePx);
+  if (!Number.isFinite(px)) return false;
+  return bold ? px >= 18.5 : px >= 24;
+}
+
+/** Is a CSS font-weight value bold for the purposes of SC 1.4.3? */
+export function isBoldWeight(weight) {
+  if (weight === 'bold' || weight === 'bolder') return true;
+  const n = Number(weight);
+  return Number.isFinite(n) && n >= 700;
+}
+
+/**
+ * Full contrast verdict for a foreground/background pair.
+ *
+ * @param {string|object} fgInput  CSS color string or parsed color
+ * @param {string|object} bgInput
+ * @param {{large?:boolean, ui?:boolean, pageBackground?:string}} [opts]
+ */
+export function checkContrast(fgInput, bgInput, opts = {}) {
+  const { large = false, ui = false, pageBackground = '#ffffff' } = opts;
+  const fgRaw = typeof fgInput === 'string' ? parseColor(fgInput) : fgInput;
+  const bgRaw = typeof bgInput === 'string' ? parseColor(bgInput) : bgInput;
+  const page = typeof pageBackground === 'string' ? parseColor(pageBackground) : pageBackground;
+
+  // A translucent background composites over the page behind it first.
+  const bg = composite(bgRaw, page);
+  const fg = composite(fgRaw, bg);
+
+  const context = ui ? 'non-text' : large ? 'large' : 'normal';
+  const thresholds = ui ? THRESHOLDS.nonText : large ? THRESHOLDS.large : THRESHOLDS.normal;
+  const ratio = contrastRatio(fg, bg);
+
+  const passes = {};
+  for (const [level, min] of Object.entries(thresholds)) passes[level] = ratio >= min;
+
+  return {
+    fg: {
+      input: typeof fgInput === 'string' ? fgInput : fgRaw.hex,
+      hex: fgRaw.hex,
+      alpha: fgRaw.alpha ?? 1,
+      composited: fg.hex,
+      rgb: [fg.r, fg.g, fg.b],
+    },
+    bg: {
+      input: typeof bgInput === 'string' ? bgInput : bgRaw.hex,
+      hex: bgRaw.hex,
+      alpha: bgRaw.alpha ?? 1,
+      composited: bg.hex,
+      rgb: [bg.r, bg.g, bg.b],
+    },
+    context,
+    ratio,
+    ratioDisplay: formatRatio(ratio),
+    ratioTruncated: truncateRatio(ratio),
+    thresholds,
+    passes,
+    sc: CONTEXT_SC[context],
+    /** The threshold that has to be met for the requested context at Level AA. */
+    required: thresholds.AA,
+  };
+}

package/src/lib/diff.js

@@ -0,0 +1,118 @@
+/**
+ * Cross-iteration diff — the convergence and oscillation detector.
+ *
+ * Matching is by fingerprint, which is why fingerprints exist. Without it a loop
+ * cannot tell "fixed" from "moved", cannot detect a regression, and cannot see
+ * the classic oscillation: fix A, break B, fix B, break A, forever.
+ *
+ * NEW violations are a regression and fail the command, even when the total
+ * count went down. A run that fixes six things and breaks one has broken one.
+ */
+
+const byFingerprint = (findings = []) => new Map(findings.map((f) => [f.fingerprint, f]));
+
+function diffBucket(before = [], after = []) {
+  const beforeMap = byFingerprint(before);
+  const afterMap = byFingerprint(after);
+  return {
+    fixed: [...beforeMap.values()].filter((f) => !afterMap.has(f.fingerprint)),
+    new: [...afterMap.values()].filter((f) => !beforeMap.has(f.fingerprint)),
+    remaining: [...afterMap.values()].filter((f) => beforeMap.has(f.fingerprint)),
+  };
+}
+
+/**
+ * @param {object} before an a11y-loop JSON report
+ * @param {object} after
+ * @returns {{
+ *   fixed:Array, new:Array, remaining:Array,
+ *   needsReview:{fixed:Array,new:Array,remaining:Array},
+ *   summary:{fixed:number,new:number,remaining:number,regression:boolean,converged:boolean,verdict:string}
+ * }}
+ */
+export function diffReports(before, after) {
+  const violations = diffBucket(before?.findings?.violations, after?.findings?.violations);
+  const needsReview = diffBucket(before?.findings?.needsReview, after?.findings?.needsReview);
+
+  const regression = violations.new.length > 0;
+  const converged = !regression && violations.remaining.length === 0;
+
+  let verdict;
+  if (regression) {
+    verdict =
+      `REGRESSION: ${violations.new.length} new violation${violations.new.length === 1 ? '' : 's'} ` +
+      `introduced (${violations.fixed.length} fixed, ${violations.remaining.length} still present)`;
+  } else if (converged) {
+    verdict =
+      violations.fixed.length > 0
+        ? `Converged: all ${violations.fixed.length} violation${violations.fixed.length === 1 ? '' : 's'} fixed, none introduced`
+        : 'No violations in either report';
+  } else {
+    verdict =
+      `Progress: ${violations.fixed.length} fixed, ${violations.remaining.length} still present, ` +
+      'none introduced';
+  }
+
+  return {
+    ...violations,
+    needsReview,
+    summary: {
+      fixed: violations.fixed.length,
+      new: violations.new.length,
+      remaining: violations.remaining.length,
+      needsReviewFixed: needsReview.fixed.length,
+      needsReviewNew: needsReview.new.length,
+      regression,
+      converged,
+      verdict,
+    },
+  };
+}
+
+const label = (finding) => {
+  const sc = finding.wcag?.sc ? `SC ${finding.wcag.sc}` : '—';
+  return { sc, rule: finding.ruleId, selector: finding.selector || '(document)' };
+};
+
+/** Compact fixed-width table plus the one-line verdict. */
+export function formatDiffHuman(diff, { beforePath, afterPath } = {}) {
+  const lines = [];
+  lines.push(`a11y-loop diff · before: ${beforePath ?? 'before'} · after: ${afterPath ?? 'after'}`);
+
+  const rows = [
+    ...diff.fixed.map((f) => ({ status: 'FIXED', ...label(f) })),
+    ...diff.new.map((f) => ({ status: 'NEW', ...label(f) })),
+    ...diff.remaining.map((f) => ({ status: 'REMAINING', ...label(f) })),
+  ];
+
+  if (rows.length === 0) {
+    lines.push('', 'No violations in either report.');
+  } else {
+    const width = (key, min) => Math.max(min, ...rows.map((r) => r[key].length));
+    const statusWidth = width('status', 9);
+    const scWidth = width('sc', 8);
+    const ruleWidth = Math.min(28, width('rule', 4));
+    lines.push('');
+    for (const row of rows) {
+      lines.push(
+        [
+          row.status.padEnd(statusWidth),
+          row.sc.padEnd(scWidth),
+          row.rule.slice(0, ruleWidth).padEnd(ruleWidth),
+          row.selector,
+        ].join('  '),
+      );
+    }
+  }
+
+  if (diff.summary.needsReviewNew > 0) {
+    lines.push(
+      '',
+      `${diff.summary.needsReviewNew} new needs-review finding(s) — not blocking, but new.`,
+    );
+  }
+
+  lines.push('', diff.summary.verdict);
+  lines.push('');
+  return lines.join('\n');
+}