@icjia/contrastcap 0.1.0

package/src/engine/colorSuggest.js

@@ -0,0 +1,104 @@
+import {
+  relativeLuminance,
+  contrastRatio,
+  requiredRatio,
+  rgbToHex,
+} from './contrastCalc.js';
+
+// Hex ⇄ HSL helpers. L is 0-100.
+
+function hexToHsl(hex) {
+  let h = hex.startsWith('#') ? hex.slice(1) : hex;
+  if (h.length === 3) h = h.split('').map(c => c + c).join('');
+  const r = parseInt(h.slice(0, 2), 16) / 255;
+  const g = parseInt(h.slice(2, 4), 16) / 255;
+  const b = parseInt(h.slice(4, 6), 16) / 255;
+
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+
+  let s = 0;
+  let hue = 0;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case r: hue = (g - b) / d + (g < b ? 6 : 0); break;
+      case g: hue = (b - r) / d + 2; break;
+      case b: hue = (r - g) / d + 4; break;
+    }
+    hue *= 60;
+  }
+
+  return { h: hue, s: s * 100, l: l * 100 };
+}
+
+function hslToHex(h, s, l) {
+  const sNorm = Math.max(0, Math.min(100, s)) / 100;
+  const lNorm = Math.max(0, Math.min(100, l)) / 100;
+
+  const c = (1 - Math.abs(2 * lNorm - 1)) * sNorm;
+  const hp = ((h % 360) + 360) % 360 / 60;
+  const x = c * (1 - Math.abs((hp % 2) - 1));
+  let r = 0, g = 0, b = 0;
+  if (0 <= hp && hp < 1) [r, g, b] = [c, x, 0];
+  else if (hp < 2) [r, g, b] = [x, c, 0];
+  else if (hp < 3) [r, g, b] = [0, c, x];
+  else if (hp < 4) [r, g, b] = [0, x, c];
+  else if (hp < 5) [r, g, b] = [x, 0, c];
+  else             [r, g, b] = [c, 0, x];
+
+  const m = lNorm - c / 2;
+  return rgbToHex((r + m) * 255, (g + m) * 255, (b + m) * 255);
+}
+
+// Bisect in [loInit, hiInit] for an L that meets threshold.
+// preferHigher=true  → returns the MAX passing L in the range (used for darken: closer to original L)
+// preferHigher=false → returns the MIN passing L in the range (used for lighten: closer to original L)
+function findThresholdL(hsl, bgHex, loInit, hiInit, threshold, preferHigher) {
+  if (hiInit < loInit) return null;
+  const hiRatio = contrastRatio(hslToHex(hsl.h, hsl.s, hiInit), bgHex);
+  const loRatio = contrastRatio(hslToHex(hsl.h, hsl.s, loInit), bgHex);
+  if (hiRatio < threshold && loRatio < threshold) return null;
+
+  let lo = loInit, hi = hiInit;
+  for (let i = 0; i < 16; i++) {
+    const mid = (lo + hi) / 2;
+    const ratio = contrastRatio(hslToHex(hsl.h, hsl.s, mid), bgHex);
+    if (preferHigher) {
+      if (ratio >= threshold) lo = mid; else hi = mid;
+    } else {
+      if (ratio >= threshold) hi = mid; else lo = mid;
+    }
+  }
+  const finalL = preferHigher ? lo : hi;
+  // Sanity — confirm the final L actually meets the threshold.
+  const finalHex = hslToHex(hsl.h, hsl.s, finalL);
+  if (contrastRatio(finalHex, bgHex) < threshold) return null;
+  return { l: finalL, hex: finalHex };
+}
+
+/**
+ * Return the nearest hex color (by HSL lightness delta) to `fgHex`
+ * that meets the WCAG threshold against `bgHex`. Hue and saturation
+ * are preserved.
+ */
+export function suggestFix(fgHex, bgHex, isLargeText, level = 'AA') {
+  const threshold = requiredRatio(isLargeText, level);
+  const hsl = hexToHsl(fgHex);
+
+  const darken  = findThresholdL(hsl, bgHex, 0,     hsl.l, threshold, /* preferHigher */ true);
+  const lighten = findThresholdL(hsl, bgHex, hsl.l, 100,   threshold, /* preferHigher */ false);
+
+  if (darken && lighten) {
+    return Math.abs(darken.l - hsl.l) <= Math.abs(lighten.l - hsl.l) ? darken.hex : lighten.hex;
+  }
+  if (darken)  return darken.hex;
+  if (lighten) return lighten.hex;
+
+  // Fallback: no solution preserving hue/sat — e.g. white-on-white.
+  return relativeLuminance(bgHex) > 0.5 ? '#000000' : '#ffffff';
+}
+
+export const _test = { hexToHsl, hslToHex, findThresholdL };

package/src/engine/contrastCalc.js

@@ -0,0 +1,63 @@
+// WCAG 2.1 relative luminance and contrast ratio math.
+
+function parseHex(hex) {
+  if (typeof hex !== 'string') throw new Error('Invalid hex color');
+  let h = hex.trim();
+  if (h.startsWith('#')) h = h.slice(1);
+  if (h.length === 3) h = h.split('').map(c => c + c).join('');
+  if (h.length !== 6 || !/^[0-9a-f]{6}$/i.test(h)) throw new Error('Invalid hex color');
+  return {
+    r: parseInt(h.slice(0, 2), 16),
+    g: parseInt(h.slice(2, 4), 16),
+    b: parseInt(h.slice(4, 6), 16),
+  };
+}
+
+function channelLum(c255) {
+  const c = c255 / 255;
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+export function relativeLuminance(hex) {
+  const { r, g, b } = parseHex(hex);
+  return 0.2126 * channelLum(r) + 0.7152 * channelLum(g) + 0.0722 * channelLum(b);
+}
+
+export function relativeLuminanceRgb(r, g, b) {
+  return 0.2126 * channelLum(r) + 0.7152 * channelLum(g) + 0.0722 * channelLum(b);
+}
+
+export function contrastRatio(hex1, hex2) {
+  const L1 = relativeLuminance(hex1);
+  const L2 = relativeLuminance(hex2);
+  const lighter = Math.max(L1, L2);
+  const darker  = Math.min(L1, L2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+export function requiredRatio(isLargeText, level = 'AA') {
+  if (level === 'AAA') return isLargeText ? 4.5 : 7;
+  return isLargeText ? 3 : 4.5; // AA
+}
+
+export function meetsThreshold(ratio, isLargeText, level = 'AA') {
+  return ratio >= requiredRatio(isLargeText, level);
+}
+
+// Parse CSS rgb()/rgba() → { r, g, b } with 0-255 channels.
+export function parseRgbString(str) {
+  if (typeof str !== 'string') throw new Error('Invalid rgb string');
+  const m = str.match(/rgba?\(\s*(\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?)/i);
+  if (!m) throw new Error('Invalid rgb string');
+  return {
+    r: Math.round(parseFloat(m[1])),
+    g: Math.round(parseFloat(m[2])),
+    b: Math.round(parseFloat(m[3])),
+  };
+}
+
+export function rgbToHex(r, g, b) {
+  const clamp = v => Math.max(0, Math.min(255, Math.round(v)));
+  const h = v => clamp(v).toString(16).padStart(2, '0');
+  return `#${h(r)}${h(g)}${h(b)}`;
+}

package/src/engine/pixelSampler.js

@@ -0,0 +1,94 @@
+import sharp from 'sharp';
+import {
+  parseRgbString,
+  relativeLuminanceRgb,
+  rgbToHex,
+} from './contrastCalc.js';
+import { CONFIG } from '../config.js';
+
+/**
+ * Sample the background color underneath an element by hiding its text
+ * and screenshotting the bounding-box region, then reading pixels with sharp.
+ *
+ * Returns: { hex, source, highVariance }
+ *   source: 'pixel-sample' | 'pixel-sample-over-image'
+ */
+export async function sampleBackgroundColor(page, elementHandle, box, fgColorCss) {
+  // Playwright screenshot can't clip to width/height < 1
+  const clip = {
+    x:      Math.max(0, Math.floor(box.x)),
+    y:      Math.max(0, Math.floor(box.y)),
+    width:  Math.max(1, Math.floor(box.width)),
+    height: Math.max(1, Math.floor(box.height)),
+  };
+
+  // Save the prior inline `style.color` so we restore exactly — clearing
+  // inline style would lose an author-set inline color.
+  await elementHandle.evaluate((el) => {
+    el.dataset._ccPrevInlineColor = el.style.color || '';
+    el.style.color = 'transparent';
+  });
+
+  let buffer;
+  try {
+    buffer = await page.screenshot({ clip, type: 'png', omitBackground: false });
+  } finally {
+    await elementHandle.evaluate((el) => {
+      el.style.color = el.dataset._ccPrevInlineColor || '';
+      delete el.dataset._ccPrevInlineColor;
+    }).catch(() => { /* element may have detached — acceptable */ });
+  }
+
+  const { data, info } = await sharp(buffer)
+    .removeAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+
+  const { width, height, channels } = info; // channels = 3 after removeAlpha
+  const cols = 5, rows = 3;
+  const samples = [];
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const px = Math.min(Math.floor((c + 0.5) * width  / cols), width  - 1);
+      const py = Math.min(Math.floor((r + 0.5) * height / rows), height - 1);
+      const idx = (py * width + px) * channels;
+      samples.push({ r: data[idx], g: data[idx + 1], b: data[idx + 2] });
+    }
+  }
+
+  const stddev = (k) => {
+    const vals = samples.map(s => s[k]);
+    const mean = vals.reduce((a, b) => a + b, 0) / vals.length;
+    const variance = vals.reduce((sum, v) => sum + (v - mean) ** 2, 0) / vals.length;
+    return Math.sqrt(variance);
+  };
+
+  const highVariance =
+    stddev('r') > CONFIG.VARIANCE_STDDEV ||
+    stddev('g') > CONFIG.VARIANCE_STDDEV ||
+    stddev('b') > CONFIG.VARIANCE_STDDEV;
+
+  let bgRgb;
+  if (highVariance) {
+    // Worst-case: pick the sample that gives the least contrast against fg.
+    // Light fg → use the lightest bg pixel; dark fg → use the darkest bg pixel.
+    const fg = parseRgbString(fgColorCss);
+    const fgLum = relativeLuminanceRgb(fg.r, fg.g, fg.b);
+    const sorted = [...samples].sort(
+      (a, b) => relativeLuminanceRgb(a.r, a.g, a.b) - relativeLuminanceRgb(b.r, b.g, b.b)
+    );
+    bgRgb = fgLum > 0.5 ? sorted[sorted.length - 1] : sorted[0];
+  } else {
+    const median = (k) => {
+      const sorted = samples.map(s => s[k]).sort((a, b) => a - b);
+      return sorted[Math.floor(sorted.length / 2)];
+    };
+    bgRgb = { r: median('r'), g: median('g'), b: median('b') };
+  }
+
+  return {
+    hex: rgbToHex(bgRgb.r, bgRgb.g, bgRgb.b),
+    source: highVariance ? 'pixel-sample-over-image' : 'pixel-sample',
+    highVariance,
+  };
+}

package/src/server.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'fs';
+import { execFile } from 'child_process';
+import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import * as z from 'zod/v4';
+
+import { CONFIG, log, setVerbosity } from './config.js';
+import { closeBrowser } from './browser.js';
+import { sanitizeError } from './utils/sanitizeError.js';
+import { checkPageContrast } from './tools/checkPageContrast.js';
+import { checkElementContrast } from './tools/checkElementContrast.js';
+import { getContrastSummary } from './tools/getContrastSummary.js';
+
+if (process.argv.includes('--verbose')) setVerbosity('verbose');
+if (process.argv.includes('--quiet')) setVerbosity('quiet');
+
+// ─── Version info ──────────────────────────────────────────────────
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url)));
+const serverVersion = pkg.version;
+
+let axeVersion = 'unknown';
+let playwrightVersion = 'unknown';
+try {
+  axeVersion = JSON.parse(readFileSync(new URL('../node_modules/axe-core/package.json', import.meta.url))).version;
+} catch { /* ignore */ }
+try {
+  playwrightVersion = JSON.parse(readFileSync(new URL('../node_modules/playwright/package.json', import.meta.url))).version;
+} catch { /* ignore */ }
+
+let _latestVersion = null;
+const _latestPromise = new Promise((resolve) => {
+  execFile('npm', ['view', '@icjia/contrastcap', 'version'], { timeout: 5000 }, (err, stdout) => {
+    const raw = err ? 'unknown' : stdout.trim();
+    _latestVersion = /^\d+\.\d+\.\d+/.test(raw) ? raw : 'unknown';
+    resolve(_latestVersion);
+  });
+});
+
+async function getLatestVersion() {
+  if (_latestVersion) return _latestVersion;
+  return _latestPromise;
+}
+
+log('info', `Server v${serverVersion} | axe-core v${axeVersion} | playwright v${playwrightVersion}`);
+
+// ─── Concurrency queue ─────────────────────────────────────────────
+
+let inFlight = 0;
+
+async function runQueued(fn) {
+  if (inFlight >= CONFIG.MAX_CONCURRENT) {
+    throw new Error('Audit queue full — try again shortly');
+  }
+  inFlight++;
+  try { return await fn(); }
+  finally { inFlight--; }
+}
+
+// ─── MCP Server ────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: 'contrastcap',
+  version: serverVersion,
+});
+
+function asJsonText(obj) {
+  return { content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }] };
+}
+
+function asErrorText(err) {
+  return { content: [{ type: 'text', text: `Error: ${sanitizeError(err)}` }] };
+}
+
+// ─── get_contrast_summary ──────────────────────────────────────────
+
+server.registerTool(
+  'get_contrast_summary',
+  {
+    description: 'Run a contrast audit against a URL and return only summary counts (pass / fail / warning / skipped). Minimal token cost — use this first before requesting full detail. Defaults to WCAG AA.',
+    inputSchema: z.object({
+      url:   z.string().max(CONFIG.MAX_URL_LENGTH).describe('HTTP or HTTPS URL to audit (localhost, staging, or prod)'),
+      level: z.enum(['AA', 'AAA']).default('AA').describe('WCAG conformance level. Defaults to AA. AAA must be explicitly requested.'),
+    }),
+  },
+  async (params) => {
+    try {
+      const result = await runQueued(() => getContrastSummary(params));
+      return asJsonText(result);
+    } catch (err) {
+      log('error', err.message);
+      return asErrorText(err);
+    }
+  }
+);
+
+// ─── check_page_contrast ───────────────────────────────────────────
+
+server.registerTool(
+  'check_page_contrast',
+  {
+    description: 'Run a full contrast audit against a URL. Returns detailed entries for failures and warnings (passes are counted but not itemized). Resolves axe-core "needs review" items via pixel sampling. Includes hex suggestions for failing foregrounds. Defaults to WCAG AA.',
+    inputSchema: z.object({
+      url:            z.string().max(CONFIG.MAX_URL_LENGTH).describe('HTTP or HTTPS URL to audit (localhost, staging, or prod)'),
+      level:          z.enum(['AA', 'AAA']).default('AA').describe('WCAG conformance level. Defaults to AA. AAA must be explicitly requested.'),
+      include_passes: z.boolean().default(false).describe('Reserved for future use — currently passing elements are always counted, never itemized, to keep token usage low.'),
+    }),
+  },
+  async (params) => {
+    try {
+      const result = await runQueued(() => checkPageContrast(params));
+      return asJsonText(result);
+    } catch (err) {
+      log('error', err.message);
+      return asErrorText(err);
+    }
+  }
+);
+
+// ─── check_element_contrast ────────────────────────────────────────
+
+server.registerTool(
+  'check_element_contrast',
+  {
+    description: 'Check contrast for a single element on a page, identified by CSS selector. Returns the computed ratio and a hex suggestion if failing. Useful for verifying a fix without re-running the whole page audit. Defaults to WCAG AA.',
+    inputSchema: z.object({
+      url:      z.string().max(CONFIG.MAX_URL_LENGTH).describe('HTTP or HTTPS URL to load'),
+      selector: z.string().max(CONFIG.SELECTOR_MAX_LEN).describe('CSS selector for the target element'),
+      level:    z.enum(['AA', 'AAA']).default('AA').describe('WCAG conformance level. Defaults to AA.'),
+    }),
+  },
+  async (params) => {
+    try {
+      const result = await runQueued(() => checkElementContrast(params));
+      return asJsonText(result);
+    } catch (err) {
+      log('error', err.message);
+      return asErrorText(err);
+    }
+  }
+);
+
+// ─── get_status ────────────────────────────────────────────────────
+
+server.registerTool(
+  'get_status',
+  {
+    description: 'Return contrastcap server version, installed axe-core and playwright versions, and whether a newer contrastcap is available on npm.',
+    inputSchema: z.object({}),
+  },
+  async () => {
+    try {
+      const latest = await getLatestVersion();
+      const updateNote = (latest === 'unknown' || latest === serverVersion)
+        ? '(latest)'
+        : `(latest: v${latest} — update available)`;
+
+      const text = [
+        'contrastcap status',
+        `  Server:     @icjia/contrastcap v${serverVersion} ${updateNote}`,
+        `  axe-core:   v${axeVersion}`,
+        `  playwright: v${playwrightVersion}`,
+        `  Node:       v${process.versions.node}`,
+        `  Platform:   ${process.platform} ${process.arch}`,
+        `  Default:    WCAG ${CONFIG.DEFAULT_LEVEL}`,
+      ].join('\n');
+
+      return { content: [{ type: 'text', text }] };
+    } catch (err) {
+      log('error', err.message);
+      return asErrorText(err);
+    }
+  }
+);
+
+// ─── Shutdown ──────────────────────────────────────────────────────
+
+async function shutdown() {
+  await closeBrowser();
+  process.exit(0);
+}
+process.on('SIGINT',  shutdown);
+process.on('SIGTERM', shutdown);
+
+// ─── Start ─────────────────────────────────────────────────────────
+
+console.error('[contrastcap] Server started — tools: get_contrast_summary, check_page_contrast, check_element_contrast, get_status');
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/tools/auditPage.js

@@ -0,0 +1,238 @@
+import { CONFIG, log } from '../config.js';
+import { validateUrl } from '../utils/urlValidate.js';
+import { withPage } from '../browser.js';
+import { runContrastAudit, selectorFromNode, axeColors } from '../engine/axeRunner.js';
+import { sampleBackgroundColor } from '../engine/pixelSampler.js';
+import {
+  contrastRatio,
+  requiredRatio,
+  parseRgbString,
+  rgbToHex,
+} from '../engine/contrastCalc.js';
+import { suggestFix } from '../engine/colorSuggest.js';
+import { isLargeText } from '../utils/largeText.js';
+
+function rgbStringToHex(rgbStr) {
+  const { r, g, b } = parseRgbString(rgbStr);
+  return rgbToHex(r, g, b);
+}
+
+function withinMarginalDelta(ratio, required) {
+  return ratio < required + CONFIG.MARGINAL_DELTA && ratio >= required;
+}
+
+async function elementMeta(element) {
+  return element.evaluate((el) => {
+    const cs = getComputedStyle(el);
+    return {
+      color:      cs.color,
+      fontSize:   cs.fontSize,   // always resolved to "NNpx"
+      fontWeight: cs.fontWeight,
+      text:       (el.textContent || '').trim(),
+    };
+  });
+}
+
+/**
+ * Resolve a single axe `incomplete` node via pixel sampling.
+ * Returns one of: { kind: 'pass' | 'fail' | 'warning' | 'skipped', entry? }
+ */
+async function resolveIncomplete(page, node, level) {
+  const selector = selectorFromNode(node);
+  if (!selector || Array.isArray(node.target[0])) {
+    // Nested context (shadow DOM or iframe) — we can't reach it via page.$()
+    return { kind: 'skipped', reason: 'unreachable selector (shadow DOM or iframe)' };
+  }
+
+  let element;
+  try { element = await page.$(selector); } catch { element = null; }
+  if (!element) return { kind: 'skipped', reason: 'element not found' };
+
+  try {
+    await element.scrollIntoViewIfNeeded({ timeout: 1500 }).catch(() => { /* ignore */ });
+
+    const box = await element.boundingBox();
+    if (!box || box.width * box.height < 4) {
+      return { kind: 'skipped', reason: 'zero-size element' };
+    }
+
+    const meta = await elementMeta(element);
+    const fgPx = parseFloat(meta.fontSize);
+    const large = isLargeText(fgPx, meta.fontWeight);
+    const required = requiredRatio(large, level);
+
+    const fgHex = rgbStringToHex(meta.color);
+
+    const bg = await sampleBackgroundColor(page, element, box, meta.color);
+    const ratio = contrastRatio(fgHex, bg.hex);
+
+    const passes = ratio >= required;
+    const marginal = !passes ? false : withinMarginalDelta(ratio, required);
+
+    const base = {
+      selector,
+      text:         meta.text,
+      ratio,
+      required,
+      level,
+      fontSize:     meta.fontSize,
+      fontWeight:   meta.fontWeight,
+      isLargeText:  large,
+      foreground:   fgHex,
+      background:   bg.hex,
+      backgroundSource: bg.source,
+    };
+
+    if (!passes) {
+      base.suggestion = suggestFix(fgHex, bg.hex, large, level);
+      return { kind: 'fail', entry: base };
+    }
+
+    // Passes — but mark warning if marginal or over high-variance background.
+    if (marginal || bg.highVariance) {
+      const notes = [];
+      if (marginal) notes.push(`Ratio within ${CONFIG.MARGINAL_DELTA} of threshold — marginal.`);
+      if (bg.highVariance) notes.push('Background sampled from gradient or image — may vary at other positions.');
+      base.note = notes.join(' ');
+      return { kind: 'warning', entry: base };
+    }
+    return { kind: 'pass' };
+  } finally {
+    await element.dispose().catch(() => {});
+  }
+}
+
+function buildFailureFromViolation(node, level) {
+  const selector = selectorFromNode(node);
+  if (!selector) return null;
+  const colors = axeColors(node);
+  if (!colors || !colors.fgColor || !colors.bgColor) return null;
+
+  const fgHex = rgbStringToHex(colors.fgColor);
+  const bgHex = rgbStringToHex(colors.bgColor);
+
+  const fgPx = parseFloat(colors.fontSize || '16');
+  const fontWeight = colors.fontWeight || '400';
+  const large = isLargeText(fgPx, fontWeight);
+  const required = typeof colors.expectedContrastRatio === 'number'
+    ? colors.expectedContrastRatio
+    : requiredRatio(large, level);
+  const ratio = typeof colors.contrastRatio === 'number'
+    ? colors.contrastRatio
+    : contrastRatio(fgHex, bgHex);
+
+  return {
+    selector,
+    text: '',
+    ratio,
+    required,
+    level,
+    fontSize:   colors.fontSize,
+    fontWeight: fontWeight,
+    isLargeText: large,
+    foreground: fgHex,
+    background: bgHex,
+    backgroundSource: 'computed',
+    suggestion: suggestFix(fgHex, bgHex, large, level),
+  };
+}
+
+/**
+ * Run the full page-level audit pipeline and return aggregate counts + entries.
+ *
+ * @param {string} url
+ * @param {'AA'|'AAA'} level
+ * @returns {Promise<{ finalUrl, axePassCount, resolvedPassCount, failures, warnings, skippedCount }>}
+ */
+export async function auditPage(url, level) {
+  const validated = await validateUrl(url);
+
+  return withPage(async (page) => {
+    await page.goto(validated, {
+      timeout: CONFIG.NAV_TIMEOUT,
+      waitUntil: 'networkidle',
+    }).catch(async (err) => {
+      // networkidle can be flaky on long-polling pages — fall back to 'load'
+      if (/Timeout/i.test(err.message || '')) {
+        await page.goto(validated, { timeout: CONFIG.NAV_TIMEOUT, waitUntil: 'load' });
+      } else {
+        throw err;
+      }
+    });
+
+    // Post-redirect SSRF guard.
+    await validateUrl(page.url());
+
+    const { violations, incomplete, passes } = await runContrastAudit(page);
+
+    // Fill in text snippets for violations so failure entries are readable.
+    const failures = [];
+    for (const node of violations) {
+      const entry = buildFailureFromViolation(node, level);
+      if (!entry) continue;
+      try {
+        const el = await page.$(entry.selector);
+        if (el) {
+          const txt = await el.evaluate((e) => (e.textContent || '').trim());
+          entry.text = txt;
+          await el.dispose().catch(() => {});
+        }
+      } catch { /* ignore */ }
+      failures.push(entry);
+    }
+
+    const warnings = [];
+    let resolvedPassCount = 0;
+    let skippedCount = 0;
+    let processed = 0;
+
+    for (const node of incomplete) {
+      if (processed >= CONFIG.MAX_ELEMENTS) {
+        skippedCount++;
+        continue;
+      }
+      processed++;
+
+      let result;
+      try {
+        result = await Promise.race([
+          resolveIncomplete(page, node, level),
+          new Promise((_, rej) => setTimeout(
+            () => rej(new Error('element timeout')),
+            CONFIG.ELEMENT_TIMEOUT,
+          )),
+        ]);
+      } catch (err) {
+        log('debug', `element timeout/error: ${err.message}`);
+        skippedCount++;
+        continue;
+      }
+
+      if (result.kind === 'pass') resolvedPassCount++;
+      else if (result.kind === 'fail') failures.push(result.entry);
+      else if (result.kind === 'warning') warnings.push(result.entry);
+      else skippedCount++;
+    }
+
+    return {
+      finalUrl: page.url(),
+      axePassCount: passes.length,
+      resolvedPassCount,
+      failures,
+      warnings,
+      skippedCount,
+    };
+  });
+}
+
+// ─── Audit timeout wrapper ────────────────────────────────────────
+
+export function withAuditTimeout(promise, label = 'Audit') {
+  return Promise.race([
+    promise,
+    new Promise((_, rej) => setTimeout(
+      () => rej(new Error(`${label} timed out`)),
+      CONFIG.AUDIT_TIMEOUT,
+    )),
+  ]);
+}