@explainui/mcp 0.1.0-beta.1 → 0.1.3

package/dist/capture.js

@@ -8,29 +8,2006 @@
  *   - Auto-relaunches if browser disconnects
  *   - Clean shutdown on SIGINT/SIGTERM
  */
+import { execFileSync } from "child_process";
+import { createRequire } from "module";
 import { chromium } from "playwright";
-import { VIEWPORTS, ExplainUIError } from "./types.js";
+import { AxeBuilder } from "@axe-core/playwright";
+import { VIEWPORTS, ExplainUIError, } from "./types.js";
 let browser = null;
+/**
+ * Quick HTTP reachability check before Playwright tries to load the URL.
+ * Fails fast (<3s) with a clear message instead of waiting 15s for Playwright timeout.
+ */
+async function assertUrlReachable(url) {
+    let timedOut = false;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, 3_000);
+    try {
+        await fetch(url, { method: "HEAD", signal: controller.signal });
+    }
+    catch {
+        if (timedOut) {
+            throw new ExplainUIError("LOCAL_SERVER_NOT_RUNNING", `Cannot reach ${url} (no response within 3s).\n\n` +
+                `Make sure your dev server is running:\n` +
+                `  npm run dev    (or: yarn dev / pnpm dev)\n\n` +
+                `Then call explainui_analyze again.`);
+        }
+        // ECONNREFUSED or similar — server is definitely not running
+        throw new ExplainUIError("LOCAL_SERVER_NOT_RUNNING", `Cannot connect to ${url}.\n\n` +
+            `Your dev server is not running. Start it with:\n` +
+            `  npm run dev    (or: yarn dev / pnpm dev)\n\n` +
+            `Then call explainui_analyze again.`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 async function getBrowser() {
     if (!browser || !browser.isConnected()) {
-        browser = await chromium.launch({
-            headless: true,
-            args: [
-                "--no-sandbox",
-                "--disable-setuid-sandbox",
-                "--disable-dev-shm-usage",
-                "--disable-gpu",
-            ],
-        });
+        try {
+            browser = await chromium.launch({
+                headless: true,
+                args: [
+                    "--no-sandbox",
+                    "--disable-setuid-sandbox",
+                    "--disable-dev-shm-usage",
+                    "--disable-gpu",
+                ],
+            });
+        }
+        catch (err) {
+            const msg = err.message ?? "";
+            if (msg.includes("Executable doesn't exist") ||
+                msg.includes("Failed to launch") ||
+                msg.includes("chromium")) {
+                // Auto-install Chromium on first use using the bundled playwright-core CLI
+                try {
+                    const require = createRequire(import.meta.url);
+                    const cliPath = require.resolve("playwright-core/cli");
+                    execFileSync(process.execPath, [cliPath, "install", "chromium"], {
+                        stdio: "pipe",
+                        timeout: 120_000,
+                    });
+                }
+                catch {
+                    throw new ExplainUIError("BROWSER_INSTALL_FAILED", `Playwright Chromium is not installed and auto-install failed.\n\n` +
+                        `Run this manually to fix it:\n` +
+                        `  npx playwright install chromium\n\n` +
+                        `Then call explainui_analyze again.`);
+                }
+                // Retry launch after install
+                browser = await chromium.launch({
+                    headless: true,
+                    args: [
+                        "--no-sandbox",
+                        "--disable-setuid-sandbox",
+                        "--disable-dev-shm-usage",
+                        "--disable-gpu",
+                    ],
+                });
+                return browser;
+            }
+            throw err;
+        }
     }
     return browser;
 }
+/**
+ * Run deterministic DOM checks before any LLM call.
+ * These are objective measurements — not vision estimates.
+ * Fails gracefully: returns safe defaults if page.evaluate() throws.
+ */
+async function runDeterministicChecks(page) {
+    try {
+        return await page.evaluate(() => {
+            const body = document.body;
+            const bodyText = (body.innerText || "").trim();
+            const visibleEls = document.querySelectorAll("h1,h2,h3,h4,p,img,button,a,input,nav");
+            // content_readable: check font sizes on text elements
+            const textEls = document.querySelectorAll("p,span,li,td,th,label,a");
+            let minFontSize = 999;
+            const maxCheck = Math.min(textEls.length, 30);
+            for (let i = 0; i < maxCheck; i++) {
+                const el = textEls[i];
+                if (el.offsetWidth === 0 && el.offsetHeight === 0)
+                    continue;
+                const size = parseFloat(window.getComputedStyle(el).fontSize);
+                if (!isNaN(size) && size > 0 && size < minFontSize)
+                    minFontSize = size;
+            }
+            if (minFontSize === 999)
+                minFontSize = 16; // default if no text found
+            return {
+                page_renders: {
+                    pass: bodyText.length > 50 && visibleEls.length > 0,
+                    body_text_length: bodyText.length,
+                    visible_element_count: visibleEls.length,
+                },
+                layout_intact: {
+                    pass: document.body.scrollWidth <= window.innerWidth + 1,
+                    overflow_delta: Math.max(0, document.body.scrollWidth - window.innerWidth),
+                },
+                content_readable: {
+                    min_font_size: Math.round(minFontSize * 10) / 10,
+                    has_text_below_12px: minFontSize < 12,
+                },
+            };
+        });
+    }
+    catch {
+        // Graceful fallback — don't block capture if DOM query fails
+        return {
+            page_renders: { pass: true, body_text_length: -1, visible_element_count: -1 },
+            layout_intact: { pass: true, overflow_delta: 0 },
+            content_readable: { min_font_size: 16, has_text_below_12px: false },
+        };
+    }
+}
+/**
+ * Run accessibility checks via DOM inspection.
+ * These are deterministic — no LLM needed. Catches missing labels, alt text,
+ * lang attribute, outline:none, small touch targets, input type mismatches,
+ * and WCAG contrast ratio failures.
+ */
+async function runAccessibilityChecks(page) {
+    try {
+        return await page.evaluate(() => {
+            // ── Helper: parse CSS color to {r, g, b, a} ──
+            function parseColor(color) {
+                if (!color || color === "transparent" || color === "rgba(0, 0, 0, 0)")
+                    return null;
+                const m = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
+                if (m)
+                    return { r: +m[1], g: +m[2], b: +m[3], a: m[4] !== undefined ? +m[4] : 1 };
+                // hex
+                const hm = color.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+                if (hm)
+                    return { r: parseInt(hm[1], 16), g: parseInt(hm[2], 16), b: parseInt(hm[3], 16), a: 1 };
+                return null;
+            }
+            // ── Helper: linearize sRGB channel for luminance calc ──
+            function linearize(c) {
+                const s = c / 255;
+                return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+            }
+            // ── Helper: relative luminance ──
+            function luminance(r, g, b) {
+                return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+            }
+            // ── Helper: contrast ratio ──
+            function contrastRatio(fg, bg) {
+                const l1 = luminance(fg.r, fg.g, fg.b);
+                const l2 = luminance(bg.r, bg.g, bg.b);
+                const lighter = Math.max(l1, l2);
+                const darker = Math.min(l1, l2);
+                return (lighter + 0.05) / (darker + 0.05);
+            }
+            // ── Helper: get effective background color walking up ancestors ──
+            function getEffectiveBg(el) {
+                let current = el;
+                for (let depth = 0; current && depth < 10; depth++) {
+                    const style = window.getComputedStyle(current);
+                    const bgColor = parseColor(style.backgroundColor);
+                    if (bgColor && bgColor.a > 0.1) {
+                        // Blend with white if semi-transparent
+                        if (bgColor.a < 1) {
+                            return {
+                                r: Math.round(bgColor.r * bgColor.a + 255 * (1 - bgColor.a)),
+                                g: Math.round(bgColor.g * bgColor.a + 255 * (1 - bgColor.a)),
+                                b: Math.round(bgColor.b * bgColor.a + 255 * (1 - bgColor.a)),
+                            };
+                        }
+                        return bgColor;
+                    }
+                    current = current.parentElement;
+                }
+                return { r: 255, g: 255, b: 255 }; // default white
+            }
+            // ── Helper: simple CSS selector for an element ──
+            function getSelector(el) {
+                if (el.id)
+                    return `#${el.id}`;
+                const tag = el.tagName.toLowerCase();
+                const cls = el.className && typeof el.className === "string"
+                    ? "." + el.className.trim().split(/\s+/).slice(0, 2).join(".")
+                    : "";
+                return tag + cls;
+            }
+            const results = {
+                missing_labels: [],
+                missing_alt: [],
+                missing_lang: !document.documentElement.lang,
+                outline_none_focusable: [],
+                small_touch_targets: [],
+                input_type_mismatches: [],
+                contrast_failures: [],
+            };
+            // 1. Missing labels on form fields
+            const formFields = document.querySelectorAll("input:not([type='hidden']):not([type='submit']):not([type='button']), select, textarea");
+            for (let i = 0; i < Math.min(formFields.length, 30); i++) {
+                const el = formFields[i];
+                if (el.offsetWidth === 0 && el.offsetHeight === 0)
+                    continue;
+                const hasLabel = el.id && document.querySelector(`label[for="${el.id}"]`);
+                const hasAria = el.getAttribute("aria-label") || el.getAttribute("aria-labelledby");
+                const hasParentLabel = el.closest("label");
+                if (!hasLabel && !hasAria && !hasParentLabel) {
+                    results.missing_labels.push({
+                        selector: getSelector(el),
+                        tag: el.tagName.toLowerCase(),
+                        text: el.placeholder || el.name || el.type || "",
+                    });
+                }
+            }
+            // 2. Missing alt on images
+            const images = document.querySelectorAll("img");
+            for (let i = 0; i < Math.min(images.length, 30); i++) {
+                const img = images[i];
+                if (img.offsetWidth === 0 && img.offsetHeight === 0)
+                    continue;
+                const alt = img.getAttribute("alt");
+                if (alt === null || alt === "") {
+                    results.missing_alt.push({
+                        selector: getSelector(img),
+                        src: (img.src || "").slice(0, 100),
+                    });
+                }
+            }
+            // 3. outline:none on focusable elements (keyboard nav broken)
+            const focusable = document.querySelectorAll("a[href], button, input, select, textarea, [tabindex]");
+            for (let i = 0; i < Math.min(focusable.length, 30); i++) {
+                const el = focusable[i];
+                if (el.offsetWidth === 0 && el.offsetHeight === 0)
+                    continue;
+                const style = window.getComputedStyle(el);
+                const outlineNone = style.outlineStyle === "none" || style.outlineWidth === "0px";
+                // Check if there's a custom focus indicator (box-shadow or border might serve)
+                // Only flag if outline is removed AND there's no visible replacement
+                if (outlineNone) {
+                    // We can't trigger :focus in evaluate, so we check for global outline:none rules
+                    // by looking at the computed style — if outline is none at rest, it's likely none on focus too
+                    const hasGlobalOutlineNone = Array.from(document.styleSheets).some(sheet => {
+                        try {
+                            return Array.from(sheet.cssRules || []).some(rule => rule.cssText.includes(":focus") && rule.cssText.includes("outline") &&
+                                (rule.cssText.includes("none") || rule.cssText.includes("0")));
+                        }
+                        catch {
+                            return false;
+                        } // cross-origin sheets
+                    });
+                    if (hasGlobalOutlineNone) {
+                        results.outline_none_focusable.push({
+                            selector: getSelector(el),
+                            tag: el.tagName.toLowerCase(),
+                            text: (el.innerText || el.getAttribute("aria-label") || "").slice(0, 60),
+                        });
+                    }
+                }
+            }
+            // Deduplicate outline findings — if we found the global rule, just report once
+            if (results.outline_none_focusable.length > 5) {
+                results.outline_none_focusable = results.outline_none_focusable.slice(0, 3);
+                results.outline_none_focusable.push({
+                    selector: "*:focus",
+                    tag: "*",
+                    text: `Global *:focus{outline:none} detected — affects all ${focusable.length} focusable elements`,
+                });
+            }
+            // 4. Small touch targets (< 44px)
+            const clickable = document.querySelectorAll("a[href], button, input[type='submit'], input[type='button'], [role='button']");
+            for (let i = 0; i < Math.min(clickable.length, 30); i++) {
+                const el = clickable[i];
+                if (el.offsetWidth === 0 && el.offsetHeight === 0)
+                    continue;
+                const rect = el.getBoundingClientRect();
+                if (rect.width < 44 || rect.height < 44) {
+                    // Only flag if both dimensions are really small — it's not an issue if width=300 height=30
+                    if (rect.width < 44 && rect.height < 44) {
+                        results.small_touch_targets.push({
+                            selector: getSelector(el),
+                            tag: el.tagName.toLowerCase(),
+                            text: (el.innerText || el.getAttribute("aria-label") || "").slice(0, 60),
+                            width: Math.round(rect.width),
+                            height: Math.round(rect.height),
+                        });
+                    }
+                }
+            }
+            // 5. Input type mismatches (email-like fields with type="text")
+            const textInputs = document.querySelectorAll("input[type='text'], input:not([type])");
+            const emailPatterns = /email|e-mail/i;
+            const phonePatterns = /phone|tel|mobile/i;
+            const urlPatterns = /website|url|homepage/i;
+            for (let i = 0; i < Math.min(textInputs.length, 20); i++) {
+                const el = textInputs[i];
+                const label = el.placeholder || el.name || el.getAttribute("aria-label") || "";
+                const labelEl = el.id ? document.querySelector(`label[for="${el.id}"]`) : null;
+                const fullLabel = label + (labelEl ? " " + labelEl.textContent : "");
+                let suggested = "";
+                if (emailPatterns.test(fullLabel))
+                    suggested = "email";
+                else if (phonePatterns.test(fullLabel))
+                    suggested = "tel";
+                else if (urlPatterns.test(fullLabel))
+                    suggested = "url";
+                if (suggested) {
+                    results.input_type_mismatches.push({
+                        selector: getSelector(el),
+                        current_type: el.type || "text",
+                        suggested_type: suggested,
+                        label_text: fullLabel.slice(0, 80),
+                    });
+                }
+            }
+            // 6. WCAG contrast ratio failures
+            // Use TreeWalker to find ALL text nodes, not just hardcoded tags.
+            // This catches <div>, <section>, custom elements — anything with visible text.
+            const textNodes = [];
+            const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, {
+                acceptNode(node) {
+                    const text = (node.textContent || "").trim();
+                    if (text.length < 2)
+                        return NodeFilter.FILTER_REJECT;
+                    const parent = node.parentElement;
+                    if (!parent)
+                        return NodeFilter.FILTER_REJECT;
+                    if (parent.offsetWidth === 0 && parent.offsetHeight === 0)
+                        return NodeFilter.FILTER_REJECT;
+                    // Skip script/style/noscript
+                    const tag = parent.tagName.toLowerCase();
+                    if (tag === "script" || tag === "style" || tag === "noscript")
+                        return NodeFilter.FILTER_REJECT;
+                    return NodeFilter.FILTER_ACCEPT;
+                },
+            });
+            const seenEls = new Set();
+            while (walker.nextNode()) {
+                const parent = walker.currentNode.parentElement;
+                if (!seenEls.has(parent)) {
+                    seenEls.add(parent);
+                    textNodes.push(parent);
+                }
+                if (textNodes.length >= 100)
+                    break;
+            }
+            let checked = 0;
+            for (let i = 0; i < textNodes.length && checked < 80; i++) {
+                const el = textNodes[i];
+                const text = (el.innerText || "").trim();
+                if (text.length < 2)
+                    continue;
+                checked++;
+                const style = window.getComputedStyle(el);
+                const fg = parseColor(style.color);
+                const bg = getEffectiveBg(el);
+                if (!fg || !bg)
+                    continue;
+                // Handle semi-transparent foreground
+                let effectiveFg = fg;
+                if (fg.a < 1) {
+                    effectiveFg = {
+                        r: Math.round(fg.r * fg.a + bg.r * (1 - fg.a)),
+                        g: Math.round(fg.g * fg.a + bg.g * (1 - fg.a)),
+                        b: Math.round(fg.b * fg.a + bg.b * (1 - fg.a)),
+                        a: 1,
+                    };
+                }
+                const ratio = contrastRatio(effectiveFg, bg);
+                const fontSize = parseFloat(style.fontSize);
+                const isBold = parseInt(style.fontWeight) >= 700 || style.fontWeight === "bold";
+                const isLargeText = fontSize >= 18 || (fontSize >= 14 && isBold);
+                const requiredAA = isLargeText ? 3 : 4.5;
+                if (ratio < requiredAA) {
+                    results.contrast_failures.push({
+                        selector: getSelector(el),
+                        text: text.slice(0, 60),
+                        fg: style.color,
+                        bg: style.backgroundColor || "inherited",
+                        ratio: Math.round(ratio * 100) / 100,
+                        required: requiredAA,
+                        level: "AA",
+                        font_size: Math.round(fontSize * 10) / 10,
+                        is_bold: isBold,
+                    });
+                }
+            }
+            // Cap contrast failures to most severe
+            if (results.contrast_failures.length > 10) {
+                results.contrast_failures.sort((a, b) => a.ratio - b.ratio);
+                results.contrast_failures = results.contrast_failures.slice(0, 10);
+            }
+            return results;
+        });
+    }
+    catch {
+        return {
+            missing_labels: [],
+            missing_alt: [],
+            missing_lang: false,
+            outline_none_focusable: [],
+            small_touch_targets: [],
+            input_type_mismatches: [],
+            contrast_failures: [],
+        };
+    }
+}
+/**
+ * Detect dark UX patterns via DOM/JS inspection.
+ * Checks for: countdown timers, urgency/scarcity language, confirmshaming.
+ */
+async function runDarkPatternChecks(page) {
+    try {
+        return await page.evaluate(() => {
+            const findings = [];
+            function getSelector(el) {
+                if (el.id)
+                    return `#${el.id}`;
+                const tag = el.tagName.toLowerCase();
+                const cls = el.className && typeof el.className === "string"
+                    ? "." + el.className.trim().split(/\s+/).slice(0, 2).join(".")
+                    : "";
+                return tag + cls;
+            }
+            // 1. Countdown timers — elements with timer-like text patterns
+            const allEls = document.querySelectorAll("*");
+            const timerPattern = /\d{1,2}\s*:\s*\d{2}\s*:\s*\d{2}|\d{1,2}h\s*\d{1,2}m|\d+\s*hours?\s*\d+\s*min/i;
+            for (let i = 0; i < allEls.length; i++) {
+                const el = allEls[i];
+                if (el.children.length > 3)
+                    continue; // skip containers
+                const text = (el.innerText || "").trim();
+                if (text.length > 0 && text.length < 100 && timerPattern.test(text)) {
+                    findings.push({ type: "countdown_timer", text: text.slice(0, 80), selector: getSelector(el) });
+                }
+            }
+            // 2. Urgency/scarcity language
+            const urgencyPatterns = [
+                /only\s+\d+\s*(left|remaining|available)/i,
+                /offer\s*(expires?|ends?)\s*(in|soon|today|tonight)/i,
+                /limited\s*time\s*(offer|deal|only)/i,
+                /act\s*now/i,
+                /don'?t\s*(miss|get\s*left|wait)/i,
+                /hurry/i,
+                /\d+\s*people\s*(are\s*)?(viewing|watching|looking)/i,
+                /selling\s*fast/i,
+                /last\s*chance/i,
+                /today\s*only/i,
+            ];
+            const textEls = document.querySelectorAll("h1,h2,h3,h4,h5,h6,p,span,div,a,button,strong,em");
+            for (let i = 0; i < Math.min(textEls.length, 200); i++) {
+                const el = textEls[i];
+                if (el.children.length > 2)
+                    continue;
+                const text = (el.innerText || "").trim();
+                if (text.length < 5 || text.length > 200)
+                    continue;
+                for (const pattern of urgencyPatterns) {
+                    if (pattern.test(text)) {
+                        findings.push({ type: "urgency_language", text: text.slice(0, 80), selector: getSelector(el) });
+                        break;
+                    }
+                }
+            }
+            // 3. Confirmshaming — dismiss/decline buttons with guilt language
+            const shamingPatterns = [
+                /no,?\s*i\s*(don'?t|do\s*not)\s*want/i,
+                /i('?ll|\s*will)\s*(stay|remain)\s*(un|dis)/i,
+                /no\s*thanks?,?\s*i\s*(prefer|like|enjoy|want)\s*(to\s*)?(pay|lose|miss|be\s*(poor|broke|stupid))/i,
+                /i\s*don'?t\s*(care|need|like)\s*(about\s*)?(sav|money|deal|discount)/i,
+            ];
+            const buttons = document.querySelectorAll("a, button, [role='button']");
+            for (let i = 0; i < buttons.length; i++) {
+                const el = buttons[i];
+                const text = (el.innerText || "").trim();
+                if (text.length < 10 || text.length > 100)
+                    continue;
+                for (const pattern of shamingPatterns) {
+                    if (pattern.test(text)) {
+                        findings.push({ type: "confirmshaming", text: text.slice(0, 80), selector: getSelector(el) });
+                        break;
+                    }
+                }
+            }
+            // 4. Pre-checked opt-in checkboxes (dark pattern — GDPR/consent violation)
+            const checkboxes = document.querySelectorAll("input[type='checkbox']");
+            for (let i = 0; i < checkboxes.length; i++) {
+                const el = checkboxes[i];
+                if (!el.checked && !el.defaultChecked)
+                    continue;
+                const labelEl = el.id ? document.querySelector(`label[for="${el.id}"]`) : el.closest("label");
+                const labelText = (labelEl ? labelEl.textContent : el.getAttribute("aria-label") || "").trim();
+                const isConsent = /newsletter|marketing|offer|email|subscribe|opt.?in|promo|deal/i.test(labelText);
+                if (isConsent && labelText.length > 5) {
+                    findings.push({ type: "pre_checked_opt_in", text: labelText.slice(0, 80), selector: getSelector(el) });
+                }
+            }
+            // 5. Anchor pricing — crossed-out price with no evidence it was ever valid
+            const strikeTags = document.querySelectorAll("del, s, strike, [class*='original-price'], [class*='was-price'], [class*='old-price'], [class*='crossed']");
+            for (let i = 0; i < strikeTags.length; i++) {
+                const el = strikeTags[i];
+                if (el.offsetWidth === 0)
+                    continue;
+                const text = (el.innerText || "").trim();
+                if (/[$£€¥₹]?\s*\d+(?:[.,]\d+)?/.test(text) && text.length < 20) {
+                    findings.push({ type: "anchor_pricing", text: text.slice(0, 40), selector: getSelector(el) });
+                }
+            }
+            return findings;
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * WCAG 1.4.12 — Text Spacing violations.
+ * Checks line-height, word-spacing, letter-spacing for values that fail WCAG 1.4.12.
+ */
+async function runTextSpacingChecks(page) {
+    try {
+        return await page.evaluate(() => {
+            const violations = [];
+            function getSelector(el) {
+                if (el.id)
+                    return `#${el.id}`;
+                const tag = el.tagName.toLowerCase();
+                const cls = el.className && typeof el.className === "string"
+                    ? "." + el.className.trim().split(/\s+/).slice(0, 2).join(".") : "";
+                return tag + cls;
+            }
+            const textEls = document.querySelectorAll("p, li, td, th, label, span");
+            const seenSelectors = new Set();
+            for (let i = 0; i < Math.min(textEls.length, 80); i++) {
+                const el = textEls[i];
+                if (el.offsetWidth === 0 || el.offsetHeight === 0)
+                    continue;
+                if (el.children.length > 5)
+                    continue;
+                const text = (el.innerText || "").trim();
+                if (text.length < 20)
+                    continue;
+                const style = window.getComputedStyle(el);
+                const fontSize = parseFloat(style.fontSize);
+                const sel = getSelector(el);
+                if (seenSelectors.has(sel))
+                    continue;
+                seenSelectors.add(sel);
+                // line-height
+                const lh = style.lineHeight;
+                if (lh !== "normal" && !isNaN(parseFloat(lh))) {
+                    const ratio = parseFloat(lh) / fontSize;
+                    if (ratio < 1.2 && ratio > 0) {
+                        violations.push({ selector: sel, property: "line-height", value: lh,
+                            issue: `line-height ${lh} is ${ratio.toFixed(2)}× font-size (WCAG 1.4.12 requires users can override to ≥1.5×). Hard-coded px values below 1.2× block this.` });
+                    }
+                }
+                // word-spacing: negative values collapse words
+                const ws = style.wordSpacing;
+                if (ws && ws !== "normal" && ws !== "0px" && parseFloat(ws) / fontSize < -0.05) {
+                    violations.push({ selector: sel, property: "word-spacing", value: ws,
+                        issue: `word-spacing ${ws} (${(parseFloat(ws) / fontSize).toFixed(3)}em) is negative, collapsing word gaps. WCAG 1.4.12 requires no constraint preventing ≥0.16em spacing.` });
+                }
+                // letter-spacing: extreme negative values overlap characters
+                const ls = style.letterSpacing;
+                if (ls && ls !== "normal" && ls !== "0px" && parseFloat(ls) / fontSize < -0.05) {
+                    violations.push({ selector: sel, property: "letter-spacing", value: ls,
+                        issue: `letter-spacing ${ls} (${(parseFloat(ls) / fontSize).toFixed(3)}em) is negative, overlapping characters. WCAG 1.4.12 requires no constraint preventing ≥0.12em spacing.` });
+                }
+                if (violations.length >= 8)
+                    break;
+            }
+            // CSS rule scan: hard-coded line-height in px
+            try {
+                for (const sheet of Array.from(document.styleSheets)) {
+                    try {
+                        for (const rule of Array.from(sheet.cssRules || [])) {
+                            const css = rule.cssText || "";
+                            const m = css.match(/line-height\s*:\s*(\d+(?:\.\d+)?)px/);
+                            if (m && parseFloat(m[1]) < 18) {
+                                violations.push({ selector: rule.selectorText || "unknown",
+                                    property: "line-height (CSS rule)", value: `${m[1]}px`,
+                                    issue: `Hard-coded line-height: ${m[1]}px. Fails WCAG 1.4.12 — use unitless (e.g. 1.5) or em so it scales with user font-size preferences.` });
+                            }
+                            if (violations.length >= 8)
+                                break;
+                        }
+                    }
+                    catch { /* cross-origin */ }
+                }
+            }
+            catch { /* ignore */ }
+            return { violations: violations.slice(0, 8) };
+        });
+    }
+    catch {
+        return { violations: [] };
+    }
+}
+/**
+ * Deep form validation checks invisible to vision models.
+ * Catches: duplicate IDs, onpaste=false, wrong autocomplete, broken label[for],
+ * missing required attributes, radio groups without fieldset/legend.
+ */
+async function runFormDeepChecks(page) {
+    try {
+        return await page.evaluate(() => {
+            const findings = [];
+            function getSelector(el) {
+                if (el.id)
+                    return `#${el.id}`;
+                const tag = el.tagName.toLowerCase();
+                const cls = el.className && typeof el.className === "string"
+                    ? "." + el.className.trim().split(/\s+/).slice(0, 2).join(".") : "";
+                return tag + cls;
+            }
+            // 1. Duplicate IDs
+            const allIds = new Map();
+            document.querySelectorAll("[id]").forEach(el => { allIds.set(el.id, (allIds.get(el.id) || 0) + 1); });
+            allIds.forEach((count, id) => {
+                if (count > 1)
+                    findings.push({ type: "duplicate_id", selector: `#${id}`,
+                        detail: `id="${id}" appears ${count} times. Duplicate IDs break label associations, aria-labelledby, and getElementById. Each ID must be unique.` });
+            });
+            // 2. onpaste blocked (dark pattern + a11y)
+            document.querySelectorAll("input, textarea").forEach(elRaw => {
+                const el = elRaw;
+                const op = el.getAttribute("onpaste");
+                if (op && /return\s+false|preventDefault|false/.test(op)) {
+                    findings.push({ type: "onpaste_blocked", selector: getSelector(el),
+                        detail: `onpaste="return false" blocks paste on this field. This frustrates password-manager users and fails WCAG 2.1 SC 3.3.1. Remove the paste restriction.` });
+                }
+            });
+            // 3. Wrong autocomplete values
+            document.querySelectorAll("input[autocomplete], input[name], input[id]").forEach(elRaw => {
+                const el = elRaw;
+                const ac = el.getAttribute("autocomplete") || "";
+                const nameHint = (el.name || el.id || el.placeholder || "").toLowerCase();
+                if (ac === "off" && /name|email|phone|address/.test(nameHint)) {
+                    findings.push({ type: "wrong_autocomplete", selector: getSelector(el),
+                        detail: `autocomplete="off" on "${nameHint}" field prevents autofill. WCAG 1.3.5 requires correct autocomplete tokens. Use "name" / "email" / "tel" etc.` });
+                }
+                if (ac === "cc-name" && !/card|credit|payment|cc/.test(nameHint)) {
+                    findings.push({ type: "wrong_autocomplete", selector: getSelector(el),
+                        detail: `autocomplete="cc-name" on field "${nameHint}" is incorrect — browsers will fill credit card data into a non-payment field.` });
+                }
+            });
+            // 4. Broken label[for]↔input[id]
+            document.querySelectorAll("label[for]").forEach(elRaw => {
+                const label = elRaw;
+                const forAttr = label.getAttribute("for");
+                const target = document.getElementById(forAttr);
+                if (!target) {
+                    findings.push({ type: "broken_label_for", selector: `label[for="${forAttr}"]`,
+                        detail: `<label for="${forAttr}"> points to id="${forAttr}" but no element with that id exists. Screen readers cannot associate this label with any input.` });
+                }
+            });
+            // 5. Required fields with only visual asterisk, no required/aria-required
+            document.querySelectorAll("input:not([type='hidden']):not([type='submit']), select, textarea").forEach(elRaw => {
+                const el = elRaw;
+                if (el.offsetWidth === 0)
+                    return;
+                const hasRequired = el.hasAttribute("required") || el.getAttribute("aria-required") === "true";
+                const labelEl = el.id ? document.querySelector(`label[for="${el.id}"]`) : el.closest("label");
+                const labelText = labelEl ? (labelEl.textContent || "") : "";
+                if ((labelText.includes("*") || labelText.toLowerCase().includes("required")) && !hasRequired) {
+                    findings.push({ type: "missing_required", selector: getSelector(el),
+                        detail: `Field "${labelText.trim().slice(0, 60)}" has visual asterisk but no required or aria-required="true". Screen readers won't announce this as required.` });
+                }
+            });
+            // 6. Radio groups without fieldset/legend
+            const radioGroups = new Map();
+            document.querySelectorAll("input[type='radio']").forEach(elRaw => {
+                const el = elRaw;
+                const n = el.name || "__unnamed__";
+                if (!radioGroups.has(n))
+                    radioGroups.set(n, []);
+                radioGroups.get(n).push(el);
+            });
+            radioGroups.forEach((radios, groupName) => {
+                if (radios.length < 2)
+                    return;
+                const inFieldset = radios[0].closest("fieldset");
+                if (!inFieldset) {
+                    findings.push({ type: "radio_no_fieldset", selector: `input[name="${groupName}"]`,
+                        detail: `Radio group "${groupName}" (${radios.length} options) is not in a <fieldset>/<legend>. Screen readers cannot announce the group question. Wrap in <fieldset><legend>Question</legend>...</fieldset>.` });
+                }
+                else if (!inFieldset.querySelector("legend")?.textContent?.trim()) {
+                    findings.push({ type: "radio_no_fieldset", selector: `fieldset > input[name="${groupName}"]`,
+                        detail: `Radio group "${groupName}" has a <fieldset> but missing or empty <legend>. Screen readers need the legend to announce the group question.` });
+                }
+            });
+            // 7. Broken IDREF targets (aria-describedby, aria-labelledby, aria-controls pointing to non-existent IDs)
+            const idrefAttrs = ["aria-describedby", "aria-labelledby", "aria-controls", "aria-owns", "aria-flowto"];
+            for (const attr of idrefAttrs) {
+                document.querySelectorAll(`[${attr}]`).forEach(elRaw => {
+                    const el = elRaw;
+                    const ids = (el.getAttribute(attr) || "").split(/\s+/).filter(Boolean);
+                    for (const id of ids) {
+                        if (!document.getElementById(id)) {
+                            findings.push({ type: "broken_idref", selector: getSelector(el),
+                                detail: `${attr}="${id}" points to a non-existent element. Screen readers will silently ignore this reference. Either add an element with id="${id}" or remove the ${attr} attribute.` });
+                        }
+                    }
+                });
+            }
+            // 8. Empty critical attribute values (<meta charset="">, empty href, etc.)
+            const emptyChecks = [
+                { sel: "meta[charset]", attr: "charset", why: "Empty charset causes encoding issues — set to 'UTF-8'." },
+                { sel: "meta[name='viewport']", attr: "content", why: "Empty viewport content breaks mobile layout." },
+                { sel: "a[href='']", attr: "href", why: "Empty href reloads the page — use href='#' or a button instead." },
+                { sel: "img[alt]", attr: "alt", why: "Empty alt on a non-decorative image hides it from screen readers." },
+            ];
+            for (const { sel, attr, why } of emptyChecks) {
+                document.querySelectorAll(sel).forEach(elRaw => {
+                    const val = elRaw.getAttribute(attr);
+                    if (val !== null && val.trim() === "") {
+                        findings.push({ type: "empty_attribute", selector: getSelector(elRaw),
+                            detail: `${elRaw.tagName.toLowerCase()} has empty ${attr}="". ${why}` });
+                    }
+                });
+            }
+            // 9. select[onchange] auto-navigation (WCAG 3.2.2 — no context change on input)
+            document.querySelectorAll("select[onchange]").forEach(elRaw => {
+                const el = elRaw;
+                const onchange = el.getAttribute("onchange") || "";
+                if (/location|navigate|redirect|submit|window\.open/i.test(onchange)) {
+                    findings.push({ type: "select_onchange_nav", selector: getSelector(el),
+                        detail: `<select onchange="${onchange.slice(0, 60)}"> auto-navigates on selection. This violates WCAG 3.2.2 (no change of context on input). Users must be able to review their selection before the page changes. Add a separate "Go" button instead.` });
+                }
+            });
+            // 10. target="_blank" links without "(opens in new tab)" or external indicator
+            document.querySelectorAll("a[target='_blank']").forEach(elRaw => {
+                const el = elRaw;
+                if (el.offsetWidth === 0)
+                    return;
+                const text = (el.textContent || "").toLowerCase();
+                const ariaLabel = (el.getAttribute("aria-label") || "").toLowerCase();
+                const title = (el.getAttribute("title") || "").toLowerCase();
+                const combined = text + " " + ariaLabel + " " + title;
+                const hasWarning = /new (tab|window)|external|opens in/i.test(combined);
+                // Check for an external link icon (svg, icon class, or screen-reader-only text)
+                const hasSrText = el.querySelector(".sr-only, .visually-hidden, [class*='screen-reader']");
+                if (!hasWarning && !hasSrText) {
+                    findings.push({ type: "new_tab_no_warning", selector: getSelector(el),
+                        detail: `Link "${(el.textContent || "").trim().slice(0, 40)}" opens in a new tab (target="_blank") without warning the user. WCAG 3.2.5 requires users be informed of context changes. Add "(opens in new tab)" text, an external link icon, or visually-hidden helper text.` });
+                }
+            });
+            return { findings: findings.slice(0, 20) };
+        });
+    }
+    catch {
+        return { findings: [] };
+    }
+}
+/**
+ * CSS interaction bug detection.
+ * Catches: overflow:hidden clipping focus rings, z-index click intercepts,
+ * missing prefers-reduced-motion guard on CSS animations.
+ */
+async function runCssInteractionChecks(page) {
+    try {
+        return await page.evaluate(() => {
+            const findings = [];
+            function getSelector(el) {
+                if (el.id)
+                    return `#${el.id}`;
+                const tag = el.tagName.toLowerCase();
+                const cls = el.className && typeof el.className === "string"
+                    ? "." + el.className.trim().split(/\s+/).slice(0, 2).join(".") : "";
+                return tag + cls;
+            }
+            // 1. overflow:hidden on parent of focusable elements — clips focus rings
+            const focusable = document.querySelectorAll("a[href], button, input, select, textarea, [tabindex]");
+            const checkedParents = new Set();
+            for (let i = 0; i < Math.min(focusable.length, 40); i++) {
+                const el = focusable[i];
+                if (el.offsetWidth === 0)
+                    continue;
+                let parent = el.parentElement;
+                for (let d = 0; parent && d < 4; d++, parent = parent.parentElement) {
+                    if (checkedParents.has(parent))
+                        break;
+                    const style = window.getComputedStyle(parent);
+                    if (style.overflow === "hidden" || style.overflowX === "hidden" || style.overflowY === "hidden") {
+                        checkedParents.add(parent);
+                        findings.push({ type: "overflow_clips_focus", selector: getSelector(parent),
+                            detail: `overflow:hidden on ${getSelector(parent)} may clip the focus ring of child ${getSelector(el)}. Focus indicators extend outside element bounds and get cut off. Use padding + overflow:clip or outline-offset to preserve visible focus rings.` });
+                        break;
+                    }
+                }
+                if (findings.filter(f => f.type === "overflow_clips_focus").length >= 3)
+                    break;
+            }
+            // 2. Animated absolute/fixed elements with z-index > 1 and no pointer-events:none
+            const highZ = document.querySelectorAll("[style*='z-index'], [class*='overlay'], [class*='backdrop'], [class*='decoration']");
+            for (let i = 0; i < Math.min(highZ.length, 20); i++) {
+                const el = highZ[i];
+                if (el.offsetWidth === 0 || el.offsetHeight === 0)
+                    continue;
+                const style = window.getComputedStyle(el);
+                if (style.pointerEvents === "none")
+                    continue;
+                const zIndex = parseInt(style.zIndex);
+                if (isNaN(zIndex) || zIndex < 2)
+                    continue;
+                const pos = style.position;
+                if ((pos === "absolute" || pos === "fixed") &&
+                    style.animationName && style.animationName !== "none") {
+                    findings.push({ type: "z_index_intercept", selector: getSelector(el),
+                        detail: `Animated element (z-index:${zIndex}, position:${pos}) may intercept clicks on content below it. Add pointer-events:none if this is a decorative animation.` });
+                }
+                if (findings.filter(f => f.type === "z_index_intercept").length >= 3)
+                    break;
+            }
+            // 3. Missing / wrong prefers-reduced-motion guard
+            let hasAnimation = false;
+            let hasReducedMotionGuard = false;
+            let reducedMotionInPrintOnly = false;
+            try {
+                for (const sheet of Array.from(document.styleSheets)) {
+                    try {
+                        for (const rule of Array.from(sheet.cssRules || [])) {
+                            const css = rule.cssText || "";
+                            if (/@keyframes|animation\s*:|animation-name\s*:/.test(css))
+                                hasAnimation = true;
+                            // Valid guard: @media that includes prefers-reduced-motion but is NOT scoped to print only
+                            if (/@media[^{]*prefers-reduced-motion/.test(css)) {
+                                // Check if this is wrongly nested inside @media print
+                                const isPrintScoped = /^@media\s+print/.test(css.trim()) ||
+                                    /^@media[^{]*\bprint\b[^{]*prefers-reduced-motion/.test(css);
+                                if (!isPrintScoped) {
+                                    hasReducedMotionGuard = true;
+                                }
+                                else {
+                                    reducedMotionInPrintOnly = true;
+                                }
+                            }
+                        }
+                    }
+                    catch { /* cross-origin */ }
+                }
+            }
+            catch { /* ignore */ }
+            if (hasAnimation && !hasReducedMotionGuard) {
+                findings.push({ type: "missing_reduced_motion", selector: "@keyframes (global)",
+                    detail: "CSS animations are present but there is no @media (prefers-reduced-motion: reduce) guard. Users with vestibular disorders can experience nausea/seizures. Add: @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }" });
+            }
+            if (hasAnimation && reducedMotionInPrintOnly && !hasReducedMotionGuard) {
+                findings.push({ type: "reduced_motion_wrong_media", selector: "@media print (misplaced)",
+                    detail: "@media (prefers-reduced-motion) guard is nested inside @media print — it will never apply for screen users. Move it to a standalone @media (prefers-reduced-motion: reduce) block." });
+            }
+            // 4. transition: all on interactive elements — delays focus ring appearance
+            const interactive = document.querySelectorAll("a[href], button, input, select, textarea, [tabindex], [role='button']");
+            for (let i = 0; i < Math.min(interactive.length, 30); i++) {
+                const el = interactive[i];
+                if (el.offsetWidth === 0)
+                    continue;
+                const style = window.getComputedStyle(el);
+                const tp = style.transitionProperty || "";
+                const td = style.transitionDuration || "0s";
+                // Flag `transition: all` with duration >= 0.3s — the focus ring transition is invisible/delayed
+                if (/\ball\b/.test(tp)) {
+                    const durationMs = parseFloat(td) * (/ms/.test(td) ? 1 : 1000);
+                    if (durationMs >= 300) {
+                        findings.push({ type: "transition_all_focus", selector: getSelector(el),
+                            detail: `transition: all ${td} on interactive element ${getSelector(el)}. The "all" keyword includes outline/box-shadow, making the focus indicator fade in slowly instead of appearing instantly. Keyboard users may not see which element is focused. Use specific properties (e.g. transition: background-color 0.3s) instead of "all", or exclude outline: transition: all 0.3s, outline 0s.` });
+                    }
+                }
+                if (findings.filter(f => f.type === "transition_all_focus").length >= 3)
+                    break;
+            }
+            // 5. Focus indicator replaced with border-color only (WCAG 2.4.11 — focus not visible enough)
+            // Check CSS rules for :focus styles that only change border-color without outline
+            try {
+                for (const sheet of Array.from(document.styleSheets)) {
+                    try {
+                        for (const rule of Array.from(sheet.cssRules || [])) {
+                            const css = rule.cssText || "";
+                            if (/:focus/.test(css) && /border-color/.test(css) && /outline\s*:\s*(none|0)/.test(css)) {
+                                findings.push({ type: "focus_border_only", selector: rule.selectorText || ":focus rule",
+                                    detail: `CSS rule "${rule.selectorText || ":focus"}" replaces outline with border-color on focus. Border changes are often too subtle for keyboard users — WCAG 2.4.11 requires a visible focus indicator with at least 2px thickness and sufficient contrast. Keep the outline or add a visible box-shadow alongside the border change.` });
+                            }
+                            if (findings.filter(f => f.type === "focus_border_only").length >= 2)
+                                break;
+                        }
+                    }
+                    catch { /* cross-origin */ }
+                }
+            }
+            catch { /* ignore */ }
+            // 6. pointer-events:none on <label> — breaks click-to-focus affordance
+            const labels = document.querySelectorAll("label");
+            for (let i = 0; i < Math.min(labels.length, 20); i++) {
+                const lbl = labels[i];
+                if (lbl.offsetWidth === 0 || lbl.offsetHeight === 0)
+                    continue;
+                const cs = window.getComputedStyle(lbl);
+                if (cs.pointerEvents === "none") {
+                    findings.push({ type: "label_pointer_events_none", selector: getSelector(lbl),
+                        detail: `<label> has pointer-events:none — clicking the label will not focus or activate its associated input. Remove pointer-events:none from labels; if you need to prevent text selection use user-select:none instead.` });
+                }
+                if (findings.filter(f => f.type === "label_pointer_events_none").length >= 3)
+                    break;
+            }
+            // 7. user-select:none on interactive buttons/links — prevents text copy for AT and users
+            const interactiveEls = document.querySelectorAll("button, [role='button'], a[href]");
+            for (let i = 0; i < Math.min(interactiveEls.length, 30); i++) {
+                const el = interactiveEls[i];
+                if (el.offsetWidth === 0 || el.offsetHeight === 0)
+                    continue;
+                const cs = window.getComputedStyle(el);
+                if (cs.userSelect === "none" || cs.webkitUserSelect === "none") {
+                    // Only flag if the button has visible text (not icon-only)
+                    const text = (el.textContent || "").trim();
+                    if (text.length > 2) {
+                        findings.push({ type: "user_select_none_interactive", selector: getSelector(el),
+                            detail: `Interactive element "${text.slice(0, 40)}" has user-select:none. This prevents users (including those using zoom/magnification software) from selecting and copying button text. Remove user-select:none from interactive controls.` });
+                    }
+                }
+                if (findings.filter(f => f.type === "user_select_none_interactive").length >= 3)
+                    break;
+            }
+            return { findings: findings.slice(0, 18) };
+        });
+    }
+    catch {
+        return { findings: [] };
+    }
+}
+/**
+ * Color-only state detection and aria-hidden with focusable children.
+ * Catches: aria-hidden on ancestors of focusable elements, nav active state
+ * communicated only by color, success/error states with no role=status/alert.
+ */
+async function runColorOnlyStateChecks(page) {
+    try {
+        return await page.evaluate(() => {
+            const findings = [];
+            function getSelector(el) {
+                if (el.id)
+                    return `#${el.id}`;
+                const tag = el.tagName.toLowerCase();
+                const cls = el.className && typeof el.className === "string"
+                    ? "." + el.className.trim().split(/\s+/).slice(0, 2).join(".") : "";
+                return tag + cls;
+            }
+            // 1. aria-hidden="true" on ancestors of focusable elements — keyboard trap
+            const focusable = document.querySelectorAll("a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex='-1'])");
+            const flaggedHidden = new Set();
+            for (let i = 0; i < Math.min(focusable.length, 60); i++) {
+                const el = focusable[i];
+                if (el.offsetWidth === 0)
+                    continue;
+                let ancestor = el.parentElement;
+                while (ancestor) {
+                    if (flaggedHidden.has(ancestor))
+                        break;
+                    if (ancestor.getAttribute("aria-hidden") === "true") {
+                        flaggedHidden.add(ancestor);
+                        findings.push({ type: "aria_hidden_focusable", selector: getSelector(ancestor),
+                            detail: `aria-hidden="true" on ${getSelector(ancestor)} contains focusable ${getSelector(el)}. Critical a11y failure: keyboard users tab into content screen readers skip. Remove aria-hidden or add tabindex="-1" to all child interactive elements.` });
+                        break;
+                    }
+                    ancestor = ancestor.parentElement;
+                }
+                if (findings.filter(f => f.type === "aria_hidden_focusable").length >= 3)
+                    break;
+            }
+            // 2. Color-only active navigation state (no aria-current)
+            const navLinks = document.querySelectorAll("nav a, nav button, [role='navigation'] a, header nav a");
+            const activePat = /\bactive\b|\bcurrent\b|\bselected\b|is-active|nav-active/i;
+            for (let i = 0; i < Math.min(navLinks.length, 30); i++) {
+                const el = navLinks[i];
+                if (el.offsetWidth === 0)
+                    continue;
+                const cls = el.className || "";
+                if (activePat.test(cls) && !el.getAttribute("aria-current")) {
+                    findings.push({ type: "color_only_active_nav", selector: getSelector(el),
+                        detail: `Nav link "${(el.innerText || "").trim().slice(0, 40)}" uses CSS class "${cls.match(activePat)?.[0]}" for active state but has no aria-current="page". Color-only active indicators fail WCAG 1.4.1. Add aria-current="page" to the active nav link.` });
+                }
+                if (findings.filter(f => f.type === "color_only_active_nav").length >= 2)
+                    break;
+            }
+            // 3. Success/error states with no role=status/alert or aria-live
+            const statusEls = document.querySelectorAll("[class*='success'], [class*='error'], [class*='field-error'], [class*='alert'], [class*='toast'], [class*='feedback'], [class*='message']");
+            for (let i = 0; i < Math.min(statusEls.length, 15); i++) {
+                const el = statusEls[i];
+                if (el.offsetWidth === 0)
+                    continue;
+                const text = (el.innerText || "").trim();
+                if (text.length < 2)
+                    continue;
+                const role = el.getAttribute("role");
+                const ariaLive = el.getAttribute("aria-live");
+                if (role !== "status" && role !== "alert" && ariaLive !== "polite" && ariaLive !== "assertive") {
+                    const cls = (el.className || "").toLowerCase();
+                    const isError = /error|invalid|fail|danger/.test(cls);
+                    const isSuccess = /success|valid|confirm/.test(cls);
+                    if (isError || isSuccess) {
+                        findings.push({ type: isError ? "color_only_error" : "color_only_success", selector: getSelector(el),
+                            detail: `${isError ? "Error" : "Success"} state "${text.slice(0, 60)}" has no role="${isError ? "alert" : "status"}" or aria-live. Screen readers won't announce this change. Add role="${isError ? "alert" : "status"}" or aria-live="${isError ? "assertive" : "polite"}".` });
+                    }
+                }
+                if (findings.filter(f => ["color_only_error", "color_only_success"].includes(f.type)).length >= 3)
+                    break;
+            }
+            // 4. aria-live="assertive" on content present at page load (not dynamically inserted)
+            // assertive is for urgent live updates — on static content it's ARIA misuse
+            document.querySelectorAll("[aria-live='assertive']").forEach(elRaw => {
+                const el = elRaw;
+                if (el.offsetWidth === 0)
+                    return;
+                const text = (el.textContent || "").trim();
+                if (text.length < 5)
+                    return;
+                const role = el.getAttribute("role") || "";
+                if (role === "alert" || role === "log")
+                    return; // intentional live region
+                findings.push({ type: "aria_live_on_static", selector: getSelector(el),
+                    detail: `aria-live="assertive" on static content: "${text.slice(0, 50)}". Assertive live regions interrupt screen readers immediately — they should only be used for urgent updates (errors, warnings). Static content present at page load should not have aria-live="assertive". Remove it, or use aria-live="polite" if updates will be dynamic.` });
+            });
+            // 5. role="alert" on elements present in initial DOM (should only be injected dynamically)
+            document.querySelectorAll("[role='alert']").forEach(elRaw => {
+                const el = elRaw;
+                if (el.offsetWidth === 0)
+                    return;
+                const text = (el.textContent || "").trim();
+                if (text.length < 5)
+                    return;
+                // If this element has visible static text, it's likely misused
+                // Real alerts should be empty at load and populated by JS on error
+                findings.push({ type: "role_alert_on_static", selector: getSelector(el),
+                    detail: `role="alert" on element with static content: "${text.slice(0, 50)}". Alerts are announced immediately by screen readers when they appear in the DOM. If this content is present at page load, it will be announced disruptively every time the page loads. Move role="alert" to a container that starts empty and gets populated by JavaScript when an actual alert occurs.` });
+            });
+            // 6. Hover-only content (data-tooltip, title with critical info, CSS :hover-only visibility)
+            // data-tooltip attributes or [title] on elements that contain pricing/important info
+            const tooltipEls = document.querySelectorAll("[data-tooltip], [data-tip], [title]:not(svg):not(meta):not(link)");
+            for (let i = 0; i < Math.min(tooltipEls.length, 20); i++) {
+                const el = tooltipEls[i];
+                if (el.offsetWidth === 0)
+                    continue;
+                const tip = el.getAttribute("data-tooltip") || el.getAttribute("data-tip") || el.getAttribute("title") || "";
+                if (tip.length < 10)
+                    continue;
+                // Flag if tooltip contains critical information (pricing, billing, legal, requirements)
+                const isCritical = /pric|bill|charg|fee|cost|requir|important|must|legal|terms|cancel|refund|\$/i.test(tip);
+                if (isCritical) {
+                    findings.push({ type: "hover_only_content", selector: getSelector(el),
+                        detail: `Critical information hidden in hover-only tooltip: "${tip.slice(0, 60)}". Tooltip content is inaccessible to keyboard users, touch devices, and screen readers. Important information about pricing, billing, or requirements must be visible at all times — move it to visible page content or add it as an expandable/accessible element.` });
+                }
+                if (findings.filter(f => f.type === "hover_only_content").length >= 3)
+                    break;
+            }
+            return { findings: findings.slice(0, 18) };
+        });
+    }
+    catch {
+        return { findings: [] };
+    }
+}
+/**
+ * Document semantics and intent checks.
+ * Catches a11y/semantic blind spots often missed by visual-only analysis.
+ */
+async function runDocumentSemanticsChecks(page) {
+    try {
+        return await page.evaluate(() => {
+            const findings = [];
+            function getSelector(el) {
+                if (el.id)
+                    return `#${el.id}`;
+                const tag = el.tagName.toLowerCase();
+                const cls = el.className && typeof el.className === "string"
+                    ? "." + el.className.trim().split(/\s+/).slice(0, 2).join(".") : "";
+                return tag + cls;
+            }
+            const norm = (s) => s.toLowerCase().replace(/\s+/g, " ").trim();
+            function hasLangContext(el) {
+                let cur = el;
+                for (let i = 0; cur && i < 6; i++, cur = cur.parentElement) {
+                    const lang = (cur.getAttribute("lang") || "").trim();
+                    if (lang)
+                        return true;
+                }
+                return false;
+            }
+            function detectScript(text) {
+                if (/[\u4E00-\u9FFF\u3040-\u30FF\uAC00-\uD7AF]/.test(text))
+                    return "cjk";
+                if (/[\u0600-\u06FF]/.test(text))
+                    return "arabic";
+                if (/[\u0400-\u04FF]/.test(text))
+                    return "cyrillic";
+                if (/[\u0900-\u097F]/.test(text))
+                    return "devanagari";
+                return "latin";
+            }
+            // 1) aria-label contradicting visible text
+            const labeled = document.querySelectorAll("a, button, [role='button'], input[type='button'], input[type='submit']");
+            for (let i = 0; i < Math.min(labeled.length, 60); i++) {
+                const el = labeled[i];
+                if (el.offsetWidth === 0)
+                    continue;
+                const visible = norm((el.innerText || el.value || "").slice(0, 80));
+                const aria = norm((el.getAttribute("aria-label") || "").slice(0, 80));
+                if (visible.length < 2 || aria.length < 2)
+                    continue;
+                if (!visible.includes(aria) && !aria.includes(visible)) {
+                    findings.push({
+                        type: "aria_label_mismatch",
+                        selector: getSelector(el),
+                        detail: `aria-label "${aria}" does not match visible text "${visible}". Voice control and screen reader users may hear different control names than what sighted users see.`,
+                    });
+                }
+                if (findings.filter(f => f.type === "aria_label_mismatch").length >= 3)
+                    break;
+            }
+            // 2) data table without <th>
+            document.querySelectorAll("table").forEach((tableRaw) => {
+                const table = tableRaw;
+                if (table.offsetWidth === 0)
+                    return;
+                const rowCount = table.querySelectorAll("tr").length;
+                const tdCount = table.querySelectorAll("td").length;
+                const hasTh = table.querySelectorAll("th").length > 0;
+                if (rowCount >= 2 && tdCount >= 2 && !hasTh) {
+                    findings.push({
+                        type: "table_missing_th",
+                        selector: getSelector(table),
+                        detail: "Data table appears to have rows/columns but no <th> headers. Screen readers cannot announce column context when navigating cells.",
+                    });
+                }
+            });
+            // 3) SVG with no accessible title/name
+            document.querySelectorAll("svg").forEach((svgRaw) => {
+                const svg = svgRaw;
+                const hidden = svg.getAttribute("aria-hidden") === "true";
+                if (hidden)
+                    return;
+                const hasTitle = !!svg.querySelector("title");
+                const hasName = !!(svg.getAttribute("aria-label") || svg.getAttribute("aria-labelledby"));
+                if (!hasTitle && !hasName) {
+                    findings.push({
+                        type: "svg_missing_title",
+                        selector: getSelector(svg),
+                        detail: "SVG graphic has no <title> and no aria-label/aria-labelledby. Non-decorative SVGs need an accessible name.",
+                    });
+                }
+            });
+            // 4) <dialog> without aria-modal
+            document.querySelectorAll("dialog").forEach((dRaw) => {
+                const d = dRaw;
+                if (!d.hasAttribute("open"))
+                    return;
+                if (d.getAttribute("aria-modal") !== "true") {
+                    findings.push({
+                        type: "dialog_missing_aria_modal",
+                        selector: getSelector(d),
+                        detail: "Open <dialog> is missing aria-modal=\"true\". Assistive tech may not treat this as a modal context.",
+                    });
+                }
+            });
+            // 5) <iframe> without title — skip only truly invisible iframes (both dims zero or hidden)
+            document.querySelectorAll("iframe").forEach((fRaw) => {
+                const f = fRaw;
+                const s = window.getComputedStyle(f);
+                if (s.display === "none" || s.visibility === "hidden")
+                    return;
+                if (f.offsetWidth === 0 && f.offsetHeight === 0)
+                    return;
+                const title = (f.getAttribute("title") || "").trim();
+                if (!title) {
+                    findings.push({
+                        type: "iframe_missing_title",
+                        selector: getSelector(f),
+                        detail: "iframe is missing a title attribute. Screen readers announce iframes by title for context. Even 1×1 tracking iframes should have title=\"\" or role=\"presentation\".",
+                    });
+                }
+            });
+            // 6) Positive tabindex trap
+            document.querySelectorAll("[tabindex]").forEach((elRaw) => {
+                const el = elRaw;
+                const t = parseInt(el.getAttribute("tabindex") || "0", 10);
+                if (!Number.isNaN(t) && t > 0) {
+                    findings.push({
+                        type: "positive_tabindex",
+                        selector: getSelector(el),
+                        detail: `tabindex=\"${t}\" creates custom tab order and can break expected keyboard navigation flow.`,
+                    });
+                }
+            });
+            // 7) Figure without figcaption
+            document.querySelectorAll("figure").forEach((figRaw) => {
+                const fig = figRaw;
+                if (fig.offsetWidth === 0)
+                    return;
+                const hasMedia = !!fig.querySelector("img, svg, video, canvas");
+                const cap = fig.querySelector("figcaption");
+                const hasCap = !!cap && !!(cap.textContent || "").trim();
+                if (hasMedia && !hasCap) {
+                    findings.push({
+                        type: "figure_missing_figcaption",
+                        selector: getSelector(fig),
+                        detail: "Figure contains media but has no <figcaption>. Context/caption text improves semantics and accessibility.",
+                    });
+                }
+            });
+            // 8) <time> without datetime
+            document.querySelectorAll("time").forEach((tRaw) => {
+                const t = tRaw;
+                const dt = (t.getAttribute("datetime") || "").trim();
+                if (!dt) {
+                    findings.push({
+                        type: "time_missing_datetime",
+                        selector: getSelector(t),
+                        detail: "<time> element is missing datetime attribute. Machine-readable date/time is required for robust semantics.",
+                    });
+                }
+            });
+            // 9) Sensory-characteristic instructions
+            const bodyText = (document.body?.innerText || "").slice(0, 20000).toLowerCase();
+            const sensory = /(click|tap|press)\s+the\s+(blue|green|red|left|right|top|bottom)\s+(button|link|icon)/i;
+            const m = bodyText.match(sensory);
+            if (m) {
+                findings.push({
+                    type: "sensory_instruction",
+                    selector: "body",
+                    detail: `Instruction appears to rely on sensory cues only: "${m[0]}". Add non-sensory identifiers (name/label/position-independent instruction).`,
+                });
+            }
+            // 10) Mixed-language text without local lang annotation
+            const docLang = (document.documentElement.lang || "").toLowerCase();
+            const assumeLatinPrimary = /^(en|fr|de|es|pt|it|nl|sv|no|da|fi|pl)\b/.test(docLang) || docLang === "";
+            if (assumeLatinPrimary) {
+                const textEls = document.querySelectorAll("p, li, span, h1, h2, h3, h4, a, button");
+                for (let i = 0; i < Math.min(textEls.length, 120); i++) {
+                    const el = textEls[i];
+                    if (el.offsetWidth === 0)
+                        continue;
+                    const txt = (el.innerText || "").trim();
+                    if (txt.length < 10)
+                        continue;
+                    const script = detectScript(txt);
+                    if (script === "latin")
+                        continue;
+                    if (!hasLangContext(el)) {
+                        findings.push({
+                            type: "lang_mismatch_missing_lang",
+                            selector: getSelector(el),
+                            detail: `Text appears to use ${script} script under document lang="${docLang || "unspecified"}" but no local lang attribute is set on or above this element. Add lang on the mixed-language segment so screen readers switch pronunciation correctly.`,
+                        });
+                    }
+                    if (findings.filter(f => f.type === "lang_mismatch_missing_lang").length >= 3)
+                        break;
+                }
+            }
+            // 11) Open modal/dialog with no obvious escape/close control
+            const modalCandidates = document.querySelectorAll("dialog[open], [role='dialog'][aria-modal='true'], [role='alertdialog'][aria-modal='true']");
+            modalCandidates.forEach((mRaw) => {
+                const modal = mRaw;
+                if (modal.offsetWidth === 0 || modal.offsetHeight === 0)
+                    return;
+                const rect = modal.getBoundingClientRect();
+                const modalAreaRatio = Math.max(0, rect.width * rect.height) / Math.max(1, window.innerWidth * window.innerHeight);
+                const ariaModal = modal.getAttribute("aria-modal") === "true";
+                const bodyStyle = window.getComputedStyle(document.body);
+                const bodyLocked = /hidden|clip/.test(`${bodyStyle.overflow} ${bodyStyle.overflowX} ${bodyStyle.overflowY}`);
+                const isLikelyBlockingModal = ariaModal || modalAreaRatio >= 0.12;
+                const closeControl = modal.querySelector("button[aria-label*='close' i], button[title*='close' i], [data-dismiss], [data-close], [aria-controls][aria-label*='close' i], .close, .btn-close");
+                const hasCloseTextBtn = Array.from(modal.querySelectorAll("button, a, [role='button']"))
+                    .some((el) => /close|dismiss|cancel|×/i.test((el.textContent || "").trim()));
+                if (!closeControl && !hasCloseTextBtn) {
+                    findings.push({
+                        type: "modal_escape_missing",
+                        selector: getSelector(modal),
+                        detail: "Modal/dialog appears open but has no obvious close/dismiss control. Keyboard and assistive-technology users may be trapped if Escape handling is missing. Provide a visible close button and ensure Escape closes the modal.",
+                    });
+                }
+                const hasAccessibleName = !!((modal.getAttribute("aria-label") || "").trim()
+                    || (modal.getAttribute("aria-labelledby") || "").trim());
+                const hasHeading = !!modal.querySelector("h1, h2, h3, [role='heading']");
+                if (!hasAccessibleName && !hasHeading) {
+                    findings.push({
+                        type: "modal_missing_accessible_name",
+                        selector: getSelector(modal),
+                        detail: "Open modal/dialog has no aria-label/aria-labelledby and no visible heading. Screen reader users may not get context for what this dialog is about.",
+                    });
+                }
+                const outsideFocusable = (isLikelyBlockingModal && (ariaModal || bodyLocked))
+                    ? Array.from(document.querySelectorAll("a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex='-1'])")).filter((el) => {
+                        if (modal.contains(el))
+                            return false;
+                        const h = el;
+                        if (h.offsetWidth === 0 || h.offsetHeight === 0)
+                            return false;
+                        if (h.closest("[aria-hidden='true'], [inert]"))
+                            return false;
+                        if (h.matches("a.skip-link, .skip-link, [data-skip-link]"))
+                            return false;
+                        const href = (h.getAttribute("href") || "").trim();
+                        if (href === "#" || href.startsWith("#"))
+                            return false;
+                        return true;
+                    })
+                    : [];
+                if (outsideFocusable.length >= 3) {
+                    findings.push({
+                        type: "modal_background_focusable",
+                        selector: getSelector(modal),
+                        detail: `Open modal/dialog has ${outsideFocusable.length} potentially focusable elements outside the dialog that are not inert/aria-hidden. Keyboard focus may escape the modal instead of staying trapped.`,
+                    });
+                }
+            });
+            // 12) Critical above-the-fold image marked lazy
+            const viewportArea = Math.max(1, window.innerWidth * window.innerHeight);
+            document.querySelectorAll("img[loading='lazy']").forEach((imgRaw) => {
+                const img = imgRaw;
+                if (img.offsetWidth === 0 || img.offsetHeight === 0)
+                    return;
+                const rect = img.getBoundingClientRect();
+                if (rect.bottom <= 0 || rect.top >= window.innerHeight)
+                    return; // not above fold
+                const area = Math.max(0, rect.width * rect.height);
+                const areaRatio = area / viewportArea;
+                if (areaRatio >= 0.08) {
+                    findings.push({
+                        type: "above_fold_lazy_critical_image",
+                        selector: getSelector(img),
+                        detail: `Large above-the-fold image (${Math.round(areaRatio * 100)}% of viewport) uses loading="lazy". This can delay LCP and cause visible pop-in. Use eager loading for critical hero/media imagery.`,
+                    });
+                }
+            });
+            // 13) 320px reflow risk via fixed/min widths that cannot shrink
+            const widthLockedEls = document.querySelectorAll("body *");
+            for (let i = 0; i < Math.min(widthLockedEls.length, 220); i++) {
+                const el = widthLockedEls[i];
+                if (el.offsetWidth === 0 || el.offsetHeight === 0)
+                    continue;
+                if (el.closest("pre, code, kbd, samp, table, [role='table']"))
+                    continue;
+                const cs = window.getComputedStyle(el);
+                const display = cs.display || "";
+                if (display === "inline" || display === "contents")
+                    continue;
+                if (cs.overflowX === "auto" || cs.overflowX === "scroll")
+                    continue;
+                const minW = parseFloat(cs.minWidth || "0");
+                const declaredW = parseFloat(cs.width || "0");
+                const noShrink = cs.flexShrink === "0";
+                const nowrap = cs.whiteSpace === "nowrap";
+                const isContainerLike = el.children.length > 0 ||
+                    display.includes("block") ||
+                    display.includes("flex") ||
+                    display.includes("grid") ||
+                    display.includes("table");
+                if (!isContainerLike)
+                    continue;
+                if ((minW > 320 || (declaredW > 360 && noShrink) || (declaredW > 320 && nowrap))) {
+                    findings.push({
+                        type: "reflow_320_fixed_width",
+                        selector: getSelector(el),
+                        detail: `Element appears width-locked (min-width ${Math.round(minW)}px, width ${Math.round(declaredW)}px, flex-shrink ${cs.flexShrink}, white-space ${cs.whiteSpace}). This risks horizontal scrolling/failure at 320px viewport width (WCAG reflow).`,
+                    });
+                }
+                if (findings.filter(f => f.type === "reflow_320_fixed_width").length >= 3)
+                    break;
+            }
+            // 14) 320px reflow risk via unbreakable nowrap text
+            const textRiskEls = document.querySelectorAll("p, span, a, button, th, td, label");
+            for (let i = 0; i < Math.min(textRiskEls.length, 180); i++) {
+                const el = textRiskEls[i];
+                if (el.offsetWidth === 0 || el.offsetHeight === 0)
+                    continue;
+                const cs = window.getComputedStyle(el);
+                if (cs.whiteSpace !== "nowrap")
+                    continue;
+                if (el.closest("pre, code, kbd, samp, [role='code']"))
+                    continue;
+                const txt = (el.innerText || "").trim();
+                const tokenMatches = txt.match(/[A-Za-z0-9_-]{28,}/g) || [];
+                const longestTokenLen = tokenMatches.reduce((m, t) => Math.max(m, t.length), 0);
+                const hasVeryLongToken = longestTokenLen >= 36;
+                if (!hasVeryLongToken)
+                    continue;
+                const fontSize = parseFloat(cs.fontSize || "16") || 16;
+                const approxTokenWidth = longestTokenLen * fontSize * 0.56;
+                if (approxTokenWidth < 260 && el.scrollWidth <= 320)
+                    continue;
+                findings.push({
+                    type: "reflow_320_unbreakable_text",
+                    selector: getSelector(el),
+                    detail: "Element uses white-space: nowrap with a long unbroken text token. At 320px viewport width this can force horizontal scrolling or clipped content. Allow wrapping or add overflow-wrap/word-break.",
+                });
+                if (findings.filter(f => f.type === "reflow_320_unbreakable_text").length >= 3)
+                    break;
+            }
+            // 15) Wrong html[lang] locale — lang exists but doesn't match detected content
+            // Heuristic: if lang="en-*" but majority of text is non-Latin script, flag it
+            // Also catches lang="en-GB"/"en-AU" mismatches by validating against known locale tags
+            const htmlLang = (document.documentElement.lang || "").toLowerCase().trim();
+            if (htmlLang) {
+                // Check for empty lang="" on any element (invalid per WCAG — empty string is meaningless)
+                document.querySelectorAll("[lang]").forEach((elRaw) => {
+                    const el = elRaw;
+                    const langVal = (el.getAttribute("lang") || "").trim();
+                    if (langVal === "" && el !== document.documentElement) {
+                        findings.push({
+                            type: "empty_lang_attr",
+                            selector: getSelector(el),
+                            detail: `Element has lang="" (empty string). An empty lang attribute is invalid — it must be a valid BCP 47 language tag (e.g. lang="fr") or omitted entirely.`,
+                        });
+                    }
+                });
+                if (findings.filter(f => f.type === "empty_lang_attr").length === 0) {
+                    // Check for suspicious locale mismatches (e.g. lang="en-GB" on a clearly US-focused site)
+                    // Detect Cyrillic/CJK/Arabic/Hebrew/Greek majority text under a Latin lang
+                    const isLatinLang = /^(en|fr|de|es|pt|it|nl|sv|no|da|fi|pl|cs|sk|ro|hr|hu)\b/.test(htmlLang);
+                    if (isLatinLang) {
+                        const allText = (document.body?.innerText || "").slice(0, 2000);
+                        const nonLatinChars = (allText.match(/[\u0400-\u04FF\u4E00-\u9FFF\u0600-\u06FF\u0590-\u05FF\u0370-\u03FF]/g) || []).length;
+                        const ratio = nonLatinChars / Math.max(1, allText.replace(/\s/g, "").length);
+                        if (ratio > 0.3) {
+                            findings.push({
+                                type: "wrong_lang_locale",
+                                selector: "html",
+                                detail: `html[lang="${htmlLang}"] appears to be set to a Latin/English locale but the majority of visible text uses non-Latin characters. Update the lang attribute to match the actual content language for correct screen reader pronunciation.`,
+                            });
+                        }
+                    }
+                }
+            }
+            // 16) Fake div/section modal — fixed-position overlay with no role="dialog" or aria-modal
+            const fixedEls = document.querySelectorAll("div, section, aside");
+            let fakeModalCount = 0;
+            for (let i = 0; i < Math.min(fixedEls.length, 60) && fakeModalCount < 2; i++) {
+                const el = fixedEls[i];
+                if (el.offsetWidth === 0 || el.offsetHeight === 0)
+                    continue;
+                const cs = window.getComputedStyle(el);
+                if (cs.position !== "fixed" && cs.position !== "absolute")
+                    continue;
+                if (cs.zIndex === "auto" || parseInt(cs.zIndex || "0") < 10)
+                    continue;
+                // Must cover substantial portion of screen to be modal-like
+                const rect = el.getBoundingClientRect();
+                const coverageX = rect.width / Math.max(1, window.innerWidth);
+                const coverageY = rect.height / Math.max(1, window.innerHeight);
+                if (coverageX < 0.3 || coverageY < 0.2)
+                    continue;
+                // Skip elements that already have a valid dialog role
+                const role = (el.getAttribute("role") || "").toLowerCase();
+                if (role === "dialog" || role === "alertdialog")
+                    continue;
+                if (el.getAttribute("aria-modal"))
+                    continue;
+                if (el.tagName.toLowerCase() === "dialog")
+                    continue;
+                // Must be visible
+                if (cs.display === "none" || cs.visibility === "hidden" || parseFloat(cs.opacity || "1") < 0.1)
+                    continue;
+                findings.push({
+                    type: "fake_modal_div",
+                    selector: getSelector(el),
+                    detail: `Large fixed/absolute-positioned element (${Math.round(coverageX * 100)}% wide, ${Math.round(coverageY * 100)}% tall, z-index ${cs.zIndex}) appears to be a modal overlay but has no role="dialog", aria-modal="true", or focus trap. Screen reader users may not know a modal is open.`,
+                });
+                fakeModalCount++;
+            }
+            // 17) <a> with no href used as interactive CTA (onclick-only fake button)
+            document.querySelectorAll("a:not([href])").forEach((elRaw) => {
+                const el = elRaw;
+                if (el.offsetWidth === 0 || el.offsetHeight === 0)
+                    return;
+                const hasOnclick = el.hasAttribute("onclick") || el.getAttribute("role") === "button";
+                const text = (el.textContent || el.getAttribute("aria-label") || "").trim();
+                if (hasOnclick || text.length > 0) {
+                    findings.push({
+                        type: "anchor_no_href",
+                        selector: getSelector(el),
+                        detail: `<a> element "${text.slice(0, 50)}" has no href attribute. Without href, screen readers do not announce it as a link and keyboard users cannot Tab to it. Use <button> for actions, or add href for navigation. If JS-driven, add href="#" and handle keyboard events.`,
+                    });
+                }
+                if (findings.filter(f => f.type === "anchor_no_href").length >= 3)
+                    return;
+            });
+            // 18) <details>/<summary> misused as navigation widget
+            document.querySelectorAll("details").forEach((detRaw) => {
+                const det = detRaw;
+                const links = det.querySelectorAll("a[href]");
+                const nonSummaryLinks = Array.from(links).filter((l) => !det.querySelector("summary")?.contains(l));
+                if (nonSummaryLinks.length >= 2) {
+                    findings.push({
+                        type: "details_misused_as_nav",
+                        selector: getSelector(det),
+                        detail: `<details>/<summary> contains ${nonSummaryLinks.length} navigation links. This element has disclosure semantics (show/hide), not navigation semantics. Use <nav> with a visible list of links instead. Screen readers announce <details> as a disclosure widget, confusing users expecting a navigation menu.`,
+                    });
+                }
+            });
+            // 19) aria-label on price/value element announcing different value than visible text
+            const priceRe = /\$[\d,]+|\d+(?:\.\d+)?\s*(?:USD|EUR|GBP|\/mo|per month|\/year)/i;
+            document.querySelectorAll("[aria-label]").forEach((elRaw) => {
+                const el = elRaw;
+                if (el.offsetWidth === 0 || el.offsetHeight === 0)
+                    return;
+                const ariaLabel = (el.getAttribute("aria-label") || "").trim();
+                const visibleText = (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ");
+                if (!ariaLabel || !visibleText || ariaLabel.toLowerCase() === visibleText.toLowerCase())
+                    return;
+                // Only flag if both aria-label and visible text contain price-like values that differ
+                const ariaPrice = ariaLabel.match(priceRe)?.[0];
+                const visiblePrice = visibleText.match(priceRe)?.[0];
+                if (ariaPrice && visiblePrice && ariaPrice !== visiblePrice) {
+                    findings.push({
+                        type: "aria_label_price_mismatch",
+                        selector: getSelector(el),
+                        detail: `aria-label announces "${ariaLabel}" but visible text shows "${visibleText.slice(0, 80)}". The price/value differs between what screen readers hear and what sighted users see. This can be used to deceive AT users. Ensure aria-label matches visible content, or remove aria-label and rely on visible text.`,
+                    });
+                }
+            });
+            // 20) <progress> with no accessible name
+            document.querySelectorAll("progress").forEach((elRaw) => {
+                const el = elRaw;
+                if (el.offsetWidth === 0 || el.offsetHeight === 0)
+                    return;
+                const hasLabel = el.getAttribute("aria-label") ||
+                    el.getAttribute("aria-labelledby") ||
+                    el.getAttribute("title") ||
+                    el.id && document.querySelector(`label[for="${el.id}"]`);
+                if (!hasLabel) {
+                    findings.push({
+                        type: "progress_no_name",
+                        selector: getSelector(el),
+                        detail: `<progress> element has no accessible name (no aria-label, aria-labelledby, or associated <label>). Screen readers will announce "progress bar" with no context. Add aria-label="Loading..." or a visible <label> element.`,
+                    });
+                }
+            });
+            // 21) Error summary placed after submit button in DOM order
+            const forms = document.querySelectorAll("form");
+            forms.forEach((form) => {
+                const submitBtn = form.querySelector("button[type='submit'], input[type='submit'], button:not([type])");
+                if (!submitBtn)
+                    return;
+                const allEls = Array.from(form.querySelectorAll("*"));
+                const submitIdx = allEls.indexOf(submitBtn);
+                for (let i = submitIdx + 1; i < allEls.length; i++) {
+                    const el = allEls[i];
+                    const role = (el.getAttribute("role") || "").toLowerCase();
+                    const hasAriaLive = el.getAttribute("aria-live");
+                    if ((role === "alert" || role === "status" || hasAriaLive) && el.offsetWidth > 0) {
+                        findings.push({
+                            type: "error_summary_below_submit",
+                            selector: getSelector(el),
+                            detail: `Error/status container (role="${role || "aria-live"}" ) appears after the submit button in DOM order. When a form is submitted and errors appear, focus must be programmatically moved to the error summary — if it's below the submit button, users may miss it. Place the error summary above the first form field or move focus explicitly on submission.`,
+                        });
+                        break;
+                    }
+                }
+            });
+            // 22) aria-owns pointing to elements that are already DOM children (double-ownership)
+            document.querySelectorAll("[aria-owns]").forEach((elRaw) => {
+                const el = elRaw;
+                const ownsIds = (el.getAttribute("aria-owns") || "").split(/\s+/).filter(Boolean);
+                for (const id of ownsIds) {
+                    const owned = document.getElementById(id);
+                    if (owned && el.contains(owned)) {
+                        findings.push({
+                            type: "aria_owns_invalid",
+                            selector: getSelector(el),
+                            detail: `aria-owns="${id}" claims ownership of an element that is already a DOM child. aria-owns is only needed for elements outside the DOM subtree. Remove the redundant aria-owns attribute to avoid confusing AT about the element's location in the accessibility tree.`,
+                        });
+                        break;
+                    }
+                }
+                if (findings.filter(f => f.type === "aria_owns_invalid").length >= 3)
+                    return;
+            });
+            // 23) Skip link target missing tabindex="-1" (non-focusable destination)
+            const skipLinks = document.querySelectorAll("a[href^='#']");
+            for (let i = 0; i < Math.min(skipLinks.length, 10); i++) {
+                const link = skipLinks[i];
+                const text = (link.textContent || link.getAttribute("aria-label") || "").toLowerCase();
+                if (!/skip|jump|main content|content/i.test(text))
+                    continue;
+                const targetId = (link.getAttribute("href") || "").slice(1);
+                if (!targetId)
+                    continue;
+                const target = document.getElementById(targetId);
+                if (!target)
+                    continue;
+                // Natively focusable elements are fine; non-focusable ones need tabindex="-1"
+                const nativeFocusable = /^(a|button|input|select|textarea)$/i.test(target.tagName);
+                if (!nativeFocusable && target.getAttribute("tabindex") === null) {
+                    findings.push({
+                        type: "skip_link_target_no_tabindex",
+                        selector: getSelector(link),
+                        detail: `Skip link points to #${targetId} but that element (${target.tagName.toLowerCase()}) is not natively focusable and has no tabindex="-1". In some browsers, programmatic focus will fail silently. Add tabindex="-1" to the skip link target: <${target.tagName.toLowerCase()} id="${targetId}" tabindex="-1">.`,
+                    });
+                }
+                if (findings.filter(f => f.type === "skip_link_target_no_tabindex").length >= 2)
+                    break;
+            }
+            // 24) visibility:hidden on role="alert" or role="status" — in AT tree but invisible
+            document.querySelectorAll("[role='alert'], [role='status'], [aria-live]").forEach((elRaw) => {
+                const el = elRaw;
+                const cs = window.getComputedStyle(el);
+                if (cs.visibility === "hidden") {
+                    const role = el.getAttribute("role") || `aria-live="${el.getAttribute("aria-live")}"`;
+                    findings.push({
+                        type: "visibility_hidden_alert",
+                        selector: getSelector(el),
+                        detail: `Element with ${role} has visibility:hidden — it remains in the accessibility tree and screen readers may announce it, but it is visually invisible to sighted users. Use display:none to fully hide elements that should not be announced, or remove the ARIA role/live attribute when hiding.`,
+                    });
+                }
+                if (findings.filter(f => f.type === "visibility_hidden_alert").length >= 3)
+                    return;
+            });
+            // 25) Disabled input with adjacent visible error text — invisible to AT
+            const disabledInputs = document.querySelectorAll("input[disabled], textarea[disabled]");
+            for (let i = 0; i < Math.min(disabledInputs.length, 20); i++) {
+                const inp = disabledInputs[i];
+                // Look for a sibling or parent-child error message
+                const parent = inp.parentElement;
+                if (!parent)
+                    continue;
+                // Check siblings and nearby elements for error-like text
+                const siblings = Array.from(parent.children);
+                const errorSibling = siblings.find((sib) => {
+                    if (sib === inp)
+                        return false;
+                    const sibEl = sib;
+                    if (sibEl.offsetWidth === 0 || sibEl.offsetHeight === 0)
+                        return false;
+                    const text = (sibEl.textContent || "").toLowerCase().trim();
+                    return /\b(error|invalid|required|must|cannot|not allowed|please)\b/.test(text) && text.length > 5;
+                });
+                if (errorSibling) {
+                    findings.push({
+                        type: "disabled_input_adjacent_error",
+                        selector: getSelector(inp),
+                        detail: `Disabled input has an adjacent error/validation message ("${(errorSibling.textContent || "").trim().slice(0, 60)}") but the input is disabled — screen readers may not associate the error with a focusable element, leaving AT users without context. Avoid attaching errors to disabled inputs; show the reason inline instead.`,
+                    });
+                }
+            }
+            return { findings: findings.slice(0, 28) };
+        });
+    }
+    catch {
+        return { findings: [] };
+    }
+}
+/**
+ * Detect structural UX issues via DOM measurement.
+ * Catches: CTA competition, ghost buttons, spacing inconsistencies, heading hierarchy violations.
+ * These are issues that vision models struggle with but DOM measurements make definitive.
+ */
+async function runStructuralUXChecks(page) {
+    try {
+        return await page.evaluate(() => {
+            function getSelector(el) {
+                if (el.id)
+                    return `#${el.id}`;
+                const tag = el.tagName.toLowerCase();
+                const cls = el.className && typeof el.className === "string"
+                    ? "." + el.className.trim().split(/\s+/).slice(0, 2).join(".")
+                    : "";
+                return tag + cls;
+            }
+            function parseColor(color) {
+                if (!color || color === "transparent" || color === "rgba(0, 0, 0, 0)")
+                    return null;
+                const m = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
+                if (m)
+                    return { r: +m[1], g: +m[2], b: +m[3], a: m[4] !== undefined ? +m[4] : 1 };
+                const hm = color.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+                if (hm)
+                    return { r: parseInt(hm[1], 16), g: parseInt(hm[2], 16), b: parseInt(hm[3], 16), a: 1 };
+                return null;
+            }
+            function linearize(c) {
+                const s = c / 255;
+                return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+            }
+            function luminance(r, g, b) {
+                return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+            }
+            function contrastRatio(c1, c2) {
+                const l1 = luminance(c1.r, c1.g, c1.b);
+                const l2 = luminance(c2.r, c2.g, c2.b);
+                return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+            }
+            function getEffectiveBg(el) {
+                let current = el;
+                for (let depth = 0; current && depth < 10; depth++) {
+                    const bgColor = parseColor(window.getComputedStyle(current).backgroundColor);
+                    if (bgColor && bgColor.a > 0.1) {
+                        if (bgColor.a < 1) {
+                            return {
+                                r: Math.round(bgColor.r * bgColor.a + 255 * (1 - bgColor.a)),
+                                g: Math.round(bgColor.g * bgColor.a + 255 * (1 - bgColor.a)),
+                                b: Math.round(bgColor.b * bgColor.a + 255 * (1 - bgColor.a)),
+                            };
+                        }
+                        return bgColor;
+                    }
+                    current = current.parentElement;
+                }
+                return { r: 255, g: 255, b: 255 };
+            }
+            const results = {
+                cta_competition: [],
+                ghost_buttons: [],
+                spacing_inconsistencies: [],
+                heading_hierarchy_violations: [],
+            };
+            // ── 1. CTA Competition — multiple primary-styled buttons in one section ──
+            const sections = document.querySelectorAll("section, [role='region'], main > div, .section, .container");
+            for (let i = 0; i < Math.min(sections.length, 20); i++) {
+                const section = sections[i];
+                if (section.offsetWidth === 0 && section.offsetHeight === 0)
+                    continue;
+                const buttons = section.querySelectorAll("a, button, [role='button']");
+                const primaryCTAs = [];
+                for (let j = 0; j < buttons.length; j++) {
+                    const btn = buttons[j];
+                    const text = (btn.innerText || "").trim();
+                    if (text.length < 2 || text.length > 60)
+                        continue;
+                    const style = window.getComputedStyle(btn);
+                    const bg = parseColor(style.backgroundColor);
+                    const hasBg = bg && bg.a > 0.5 && !(bg.r > 240 && bg.g > 240 && bg.b > 240); // not white/transparent
+                    const fontSize = parseFloat(style.fontSize);
+                    const isBold = parseInt(style.fontWeight) >= 600;
+                    // A "primary" CTA: has non-white background, decent size, bold-ish
+                    if (hasBg && (fontSize >= 14 || isBold)) {
+                        primaryCTAs.push(text.slice(0, 40));
+                    }
+                }
+                if (primaryCTAs.length >= 3) {
+                    results.cta_competition.push({
+                        section_selector: getSelector(section),
+                        cta_count: primaryCTAs.length,
+                        cta_texts: primaryCTAs.slice(0, 5),
+                    });
+                }
+            }
+            // ── 2. Ghost Buttons — near-invisible buttons on their background ──
+            const allButtons = document.querySelectorAll("a, button, [role='button']");
+            for (let i = 0; i < Math.min(allButtons.length, 40); i++) {
+                const btn = allButtons[i];
+                if (btn.offsetWidth === 0 && btn.offsetHeight === 0)
+                    continue;
+                const text = (btn.innerText || "").trim();
+                if (text.length < 2)
+                    continue;
+                const style = window.getComputedStyle(btn);
+                const btnBg = parseColor(style.backgroundColor);
+                const btnColor = parseColor(style.color);
+                const btnBorder = parseColor(style.borderColor);
+                const parentBg = getEffectiveBg(btn.parentElement || btn);
+                // Ghost button pattern: transparent/no bg, relies on border/text color
+                const isGhost = !btnBg || btnBg.a < 0.3;
+                if (isGhost && parentBg) {
+                    // Check if button text/border contrasts enough with parent background
+                    const textContrast = btnColor ? contrastRatio(btnColor, parentBg) : 21;
+                    const borderContrast = btnBorder && btnBorder.a > 0.3 ? contrastRatio(btnBorder, parentBg) : 21;
+                    const effectiveContrast = Math.min(textContrast, borderContrast);
+                    if (effectiveContrast < 2.5) {
+                        results.ghost_buttons.push({
+                            selector: getSelector(btn),
+                            text: text.slice(0, 40),
+                            opacity: btnBg ? btnBg.a : 0,
+                            bg_contrast: Math.round(effectiveContrast * 100) / 100,
+                        });
+                    }
+                }
+            }
+            // ── 3. Spacing Inconsistencies — siblings with wildly different gaps ──
+            // Check flex/grid containers for children with inconsistent margin/padding
+            const containers = document.querySelectorAll("[class*='grid'], [class*='flex'], [class*='card'], [class*='feature']");
+            const checkedParents = new Set();
+            for (let i = 0; i < Math.min(containers.length, 30); i++) {
+                const container = containers[i];
+                const parent = container.parentElement;
+                if (!parent || checkedParents.has(parent))
+                    continue;
+                // Find siblings of the same type (cards, items, etc.)
+                const siblings = Array.from(parent.children).filter(child => {
+                    const ch = child;
+                    return ch.offsetWidth > 0 && ch.offsetHeight > 0 &&
+                        ch.tagName === container.tagName &&
+                        ch.className === container.className;
+                });
+                if (siblings.length < 3)
+                    continue;
+                checkedParents.add(parent);
+                // Check margin-bottom and padding-bottom consistency
+                for (const prop of ["marginBottom", "paddingBottom", "marginTop", "paddingTop"]) {
+                    const values = [];
+                    for (const sib of siblings) {
+                        values.push(parseFloat(window.getComputedStyle(sib)[prop]) || 0);
+                    }
+                    // Find if any value is an outlier (differs from median by >50% AND >10px)
+                    const sorted = [...values].sort((a, b) => a - b);
+                    const median = sorted[Math.floor(sorted.length / 2)];
+                    if (median < 8)
+                        continue; // skip trivial spacing
+                    for (let k = 0; k < values.length; k++) {
+                        const diff = Math.abs(values[k] - median);
+                        if (diff > median * 0.5 && diff > 10) {
+                            const cssProp = prop.replace(/([A-Z])/g, "-$1").toLowerCase();
+                            results.spacing_inconsistencies.push({
+                                parent_selector: getSelector(parent),
+                                property: cssProp,
+                                values_px: values.map(v => Math.round(v)),
+                                outlier_index: k,
+                                outlier_selector: getSelector(siblings[k]),
+                            });
+                            break; // one finding per property per container
+                        }
+                    }
+                }
+            }
+            // ── 4. Heading Hierarchy Violations — h2 smaller than h3, etc. ──
+            const headings = document.querySelectorAll("h1, h2, h3, h4, h5, h6");
+            for (let i = 0; i < headings.length - 1; i++) {
+                const current = headings[i];
+                const next = headings[i + 1];
+                if (current.offsetWidth === 0 || next.offsetWidth === 0)
+                    continue;
+                const currentLevel = parseInt(current.tagName[1]);
+                const nextLevel = parseInt(next.tagName[1]);
+                // Only check when next heading SHOULD be smaller (higher number = lower priority)
+                if (nextLevel <= currentLevel)
+                    continue;
+                const currentSize = parseFloat(window.getComputedStyle(current).fontSize);
+                const nextSize = parseFloat(window.getComputedStyle(next).fontSize);
+                // Violation: lower-priority heading is visually larger
+                if (nextSize > currentSize + 2) { // 2px tolerance
+                    results.heading_hierarchy_violations.push({
+                        larger_selector: getSelector(next),
+                        larger_tag: next.tagName.toLowerCase(),
+                        larger_size_px: Math.round(nextSize * 10) / 10,
+                        smaller_selector: getSelector(current),
+                        smaller_tag: current.tagName.toLowerCase(),
+                        smaller_size_px: Math.round(currentSize * 10) / 10,
+                    });
+                }
+            }
+            // Also check heading vs adjacent non-heading text that's visually larger
+            for (let i = 0; i < headings.length; i++) {
+                const heading = headings[i];
+                if (heading.offsetWidth === 0)
+                    continue;
+                const headingSize = parseFloat(window.getComputedStyle(heading).fontSize);
+                // Check next visible sibling
+                let nextSib = heading.nextElementSibling;
+                while (nextSib && nextSib.offsetWidth === 0) {
+                    nextSib = nextSib.nextElementSibling;
+                }
+                if (!nextSib || ["H1", "H2", "H3", "H4", "H5", "H6"].includes(nextSib.tagName))
+                    continue;
+                const sibSize = parseFloat(window.getComputedStyle(nextSib).fontSize);
+                if (sibSize > headingSize + 4) { // 4px tolerance for non-heading vs heading
+                    results.heading_hierarchy_violations.push({
+                        larger_selector: getSelector(nextSib),
+                        larger_tag: nextSib.tagName.toLowerCase(),
+                        larger_size_px: Math.round(sibSize * 10) / 10,
+                        smaller_selector: getSelector(heading),
+                        smaller_tag: heading.tagName.toLowerCase(),
+                        smaller_size_px: Math.round(headingSize * 10) / 10,
+                    });
+                }
+            }
+            // Cap results
+            if (results.cta_competition.length > 5)
+                results.cta_competition = results.cta_competition.slice(0, 5);
+            if (results.ghost_buttons.length > 5)
+                results.ghost_buttons = results.ghost_buttons.slice(0, 5);
+            if (results.spacing_inconsistencies.length > 5)
+                results.spacing_inconsistencies = results.spacing_inconsistencies.slice(0, 5);
+            if (results.heading_hierarchy_violations.length > 5)
+                results.heading_hierarchy_violations = results.heading_hierarchy_violations.slice(0, 5);
+            return results;
+        });
+    }
+    catch {
+        return {
+            cta_competition: [],
+            ghost_buttons: [],
+            spacing_inconsistencies: [],
+            heading_hierarchy_violations: [],
+        };
+    }
+}
+/**
+ * Extract visible DOM elements at the current scroll position.
+ * Returns elements with viewport-relative normalized bboxes.
+ * Cap at 50 elements per screenshot to control token cost.
+ */
+async function extractVisibleElements(page, vpWidth, vpHeight) {
+    try {
+        const raw = await page.evaluate(({ vw, vh }) => {
+            const selectors = "h1,h2,h3,h4,h5,h6,p,a,button,img,input,select,textarea," +
+                "nav,header,footer,section,main,[role='button'],[role='navigation']";
+            const els = document.querySelectorAll(selectors);
+            const results = [];
+            for (let i = 0; i < els.length && results.length < 50; i++) {
+                const el = els[i];
+                if (el.offsetWidth === 0 && el.offsetHeight === 0)
+                    continue;
+                const rect = el.getBoundingClientRect();
+                // Skip elements fully outside the viewport
+                if (rect.bottom < 0 || rect.top > vh || rect.right < 0 || rect.left > vw)
+                    continue;
+                const text = (el.innerText || el.getAttribute("alt") || el.getAttribute("aria-label") || "")
+                    .trim()
+                    .slice(0, 80);
+                results.push({
+                    tag: el.tagName.toLowerCase(),
+                    text,
+                    x: Math.max(0, rect.left) / vw,
+                    y: Math.max(0, rect.top) / vh,
+                    w: Math.min(rect.width, vw - Math.max(0, rect.left)) / vw,
+                    h: Math.min(rect.height, vh - Math.max(0, rect.top)) / vh,
+                });
+            }
+            return results;
+        }, { vw: vpWidth, vh: vpHeight });
+        // Assign sequential IDs and clamp bbox values
+        return raw.map((el, idx) => ({
+            id: `el_${idx + 1}`,
+            tag: el.tag,
+            text: el.text,
+            bbox: {
+                x: Math.round(Math.min(1, Math.max(0, el.x)) * 100) / 100,
+                y: Math.round(Math.min(1, Math.max(0, el.y)) * 100) / 100,
+                w: Math.round(Math.min(1, Math.max(0, el.w)) * 100) / 100,
+                h: Math.round(Math.min(1, Math.max(0, el.h)) * 100) / 100,
+            },
+        }));
+    }
+    catch {
+        return []; // Graceful fallback
+    }
+}
+/**
+ * Run axe-core accessibility audit on the page.
+ * Returns structured violations that complement our manual checks.
+ * Catches ARIA role issues, heading order, focus management, etc.
+ */
+async function runAxeChecks(page) {
+    try {
+        const results = await new AxeBuilder({ page })
+            .withTags(["wcag2a", "wcag2aa", "best-practice"])
+            .analyze();
+        return results.violations.map((v) => ({
+            id: v.id,
+            impact: v.impact || "moderate",
+            description: v.description,
+            help_url: v.helpUrl,
+            nodes: v.nodes.slice(0, 5).map((n) => ({
+                selector: Array.isArray(n.target) ? n.target.flat().join(" ") : String(n.target),
+                html: (n.html || "").slice(0, 200),
+                failure_summary: (n.failureSummary || "").slice(0, 200),
+            })),
+        }));
+    }
+    catch (err) {
+        // axe-core can fail on some pages — don't block capture
+        return [];
+    }
+}
 /**
  * Capture screenshots at all configured viewports for a given URL.
+ * Also runs deterministic DOM checks and extracts element maps.
  * Returns base64-encoded JPEG screenshots with labels.
  */
 export async function captureAllViewports(url) {
     const startTime = Date.now();
+    // Fast reachability check — fail in <3s instead of waiting 15s for Playwright
+    await assertUrlReachable(url);
     const b = await getBrowser();
     const context = await b.newContext({
         ignoreHTTPSErrors: true,
@@ -39,56 +2016,129 @@ export async function captureAllViewports(url) {
     });
     const page = await context.newPage();
     try {
-        await page.goto(url, { waitUntil: "networkidle", timeout: 15_000 });
+        await page.goto(url, { waitUntil: "networkidle", timeout: 20_000 });
+        // Extra wait for animations, lazy content, and JS rendering to settle
+        await page.waitForTimeout(2000);
+        // Run all deterministic checks in parallel (~100-500ms total)
+        const [baseChecks, a11yChecks, darkPatterns, axeViolations, structuralUX, textSpacing, formIssues, cssInteractions, colorOnlyStates, documentSemantics] = await Promise.all([
+            runDeterministicChecks(page),
+            runAccessibilityChecks(page),
+            runDarkPatternChecks(page),
+            runAxeChecks(page),
+            runStructuralUXChecks(page),
+            runTextSpacingChecks(page),
+            runFormDeepChecks(page),
+            runCssInteractionChecks(page),
+            runColorOnlyStateChecks(page),
+            runDocumentSemanticsChecks(page),
+        ]);
+        const deterministicChecks = {
+            ...baseChecks,
+            accessibility: a11yChecks,
+            dark_patterns: darkPatterns.length > 0 ? { findings: darkPatterns } : undefined,
+            structural_ux: structuralUX,
+            text_spacing: Array.isArray(textSpacing?.violations)
+                && textSpacing.violations.length > 0
+                ? textSpacing
+                : undefined,
+            form_issues: Array.isArray(formIssues?.findings)
+                && formIssues.findings.length > 0
+                ? formIssues
+                : undefined,
+            css_interactions: Array.isArray(cssInteractions?.findings)
+                && cssInteractions.findings.length > 0
+                ? cssInteractions
+                : undefined,
+            color_only_states: Array.isArray(colorOnlyStates?.findings)
+                && colorOnlyStates.findings.length > 0
+                ? colorOnlyStates
+                : undefined,
+            document_semantics: Array.isArray(documentSemantics?.findings)
+                && documentSemantics.findings.length > 0
+                ? documentSemantics
+                : undefined,
+        };
         const screenshots = [];
         for (const vp of VIEWPORTS) {
             await page.setViewportSize({ width: vp.width, height: vp.height });
-            await page.waitForTimeout(300); // let layout reflow settle
+            // Force scroll to absolute top FIRST — before anything else at this viewport
+            await page.evaluate(() => {
+                document.documentElement.style.scrollBehavior = "auto";
+                window.scrollTo({ top: 0, left: 0, behavior: "instant" });
+            });
+            await page.waitForTimeout(300);
+            // Trigger lazy-loaded content: scroll to bottom, then back to top
+            await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
+            await page.waitForTimeout(1000);
+            await page.evaluate(() => {
+                window.scrollTo({ top: 0, left: 0, behavior: "instant" });
+            });
+            await page.waitForTimeout(500);
             const pageHeight = await page.evaluate(() => document.body.scrollHeight);
             const scrollStep = vp.height;
-            const maxScrolls = Math.min(vp.scrolls, Math.ceil(pageHeight / scrollStep));
+            // How many viewport-height slices cover the page, capped by config
+            const maxScrolls = Math.min(vp.scrolls, Math.max(1, Math.ceil(pageHeight / scrollStep)));
             for (let i = 0; i < maxScrolls; i++) {
-                const scrollY = i * scrollStep;
-                await page.evaluate((y) => window.scrollTo(0, y), scrollY);
-                await page.waitForTimeout(150); // let lazy images load
+                // Scroll to exact position; snap last scroll to page bottom
+                const scrollY = (i === maxScrolls - 1 && i > 0)
+                    ? Math.max(0, pageHeight - vp.height)
+                    : i * scrollStep;
+                await page.evaluate((y) => {
+                    window.scrollTo({ top: y, left: 0, behavior: "instant" });
+                }, scrollY);
+                await page.waitForTimeout(500); // let lazy images + animations settle
+                // Verify we actually scrolled to the right position
+                const actualY = await page.evaluate(() => window.scrollY);
+                // Screenshot captures the visible viewport (no fullPage flag)
                 let bytes = await page.screenshot({
                     type: "jpeg",
-                    quality: 70,
-                    clip: { x: 0, y: 0, width: vp.width, height: vp.height },
+                    quality: 80,
                 });
                 // Size guard: if screenshot > 5MB, reduce quality
                 if (bytes.length > 5 * 1024 * 1024) {
                     bytes = await page.screenshot({
                         type: "jpeg",
-                        quality: 50,
-                        clip: { x: 0, y: 0, width: vp.width, height: vp.height },
+                        quality: 60,
                     });
                 }
+                // Extract visible DOM elements at this scroll position
+                const elements = await extractVisibleElements(page, vp.width, vp.height);
                 screenshots.push({
                     label: `${vp.label}_scroll_${i}`,
                     viewport: vp.label,
                     scroll_index: i,
                     data: bytes.toString("base64"),
+                    elements,
                 });
-                // Break if we've scrolled past the page content
-                const currentY = await page.evaluate(() => window.scrollY);
+                // Stop if we've reached the bottom of the page
                 const maxY = await page.evaluate(() => document.body.scrollHeight - window.innerHeight);
-                if (currentY >= maxY)
+                if (actualY >= maxY - 10)
                     break;
             }
         }
         return {
             screenshots,
             capture_duration_ms: Date.now() - startTime,
+            deterministic_checks: deterministicChecks,
+            axe_violations: axeViolations.length > 0 ? axeViolations : undefined,
         };
     }
     catch (err) {
-        const message = err.message || "";
+        // Re-throw ExplainUIErrors unchanged (already have good messages)
+        if (err instanceof ExplainUIError)
+            throw err;
+        const message = err.message ?? "";
         if (message.includes("ERR_CONNECTION_REFUSED")) {
-            throw new ExplainUIError("LOCAL_SERVER_NOT_RUNNING", `Could not connect to ${url}. Is your dev server running?`);
+            throw new ExplainUIError("LOCAL_SERVER_NOT_RUNNING", `Lost connection to ${url} during screenshot capture.\n` +
+                `Make sure your dev server stays running while ExplainUI is analyzing.`);
         }
-        if (message.includes("Timeout")) {
-            throw new ExplainUIError("CAPTURE_TIMEOUT", `Page at ${url} took too long to load (>15s).`);
+        if (message.toLowerCase().includes("timeout") || message.includes("TimeoutError")) {
+            throw new ExplainUIError("CAPTURE_TIMEOUT", `Page at ${url} took too long to render screenshots (>15s).\n\n` +
+                `This can happen with:\n` +
+                `  • Slow API calls blocking page render\n` +
+                `  • Large images or assets loading\n` +
+                `  • Infinite loading states\n\n` +
+                `Try calling analyze again. If it keeps timing out, check your page's network tab.`);
         }
         throw err;
     }