wcag-scanner 1.2.65 → 1.2.67

package/dist/react/WcagDevOverlay.js

@@ -4,117 +4,264 @@ exports.WcagDevOverlay = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const browserScanner_1 = require("./browserScanner");
-// ─── Impact theme ──────────────────────────────────────────────────────────────
+const gemini_1 = require("./gemini");
+// ─── Impact colours ───────────────────────────────────────────────────────────
 const IMPACT = {
     critical: { color: '#dc2626', bg: '#fef2f2', border: '#fca5a5' },
     serious: { color: '#ea580c', bg: '#fff7ed', border: '#fdba74' },
     moderate: { color: '#ca8a04', bg: '#fefce8', border: '#fde047' },
     minor: { color: '#2563eb', bg: '#eff6ff', border: '#93c5fd' },
 };
-const impactTheme = (impact) => { var _a; return (_a = IMPACT[impact]) !== null && _a !== void 0 ? _a : { color: '#6b7280', bg: '#f9fafb', border: '#e5e7eb' }; };
+const theme = (impact) => { var _a; return (_a = IMPACT[impact]) !== null && _a !== void 0 ? _a : { color: '#6b7280', bg: '#f9fafb', border: '#e5e7eb' }; };
 // ─── Highlight helpers ─────────────────────────────────────────────────────────
+const HIGHLIGHT_ID = 'wcag-dev-highlight';
+function getHighlightLayer() {
+    let layer = document.getElementById(HIGHLIGHT_ID);
+    if (layer)
+        return layer;
+    layer = document.createElement('div');
+    layer.id = HIGHLIGHT_ID;
+    layer.setAttribute('aria-hidden', 'true');
+    Object.assign(layer.style, {
+        position: 'fixed',
+        top: '0',
+        left: '0',
+        width: '0',
+        height: '0',
+        display: 'none',
+        pointerEvents: 'none',
+        zIndex: '2147483646',
+        borderRadius: '10px',
+        boxSizing: 'border-box',
+        transition: 'opacity 80ms ease-out, transform 80ms ease-out',
+        transform: 'translateZ(0)',
+    });
+    const label = document.createElement('div');
+    label.setAttribute('data-wcag-highlight-label', 'true');
+    Object.assign(label.style, {
+        position: 'absolute',
+        top: '-30px',
+        left: '0',
+        padding: '4px 8px',
+        borderRadius: '999px',
+        color: '#fff',
+        fontSize: '11px',
+        fontWeight: '700',
+        letterSpacing: '0.03em',
+        boxShadow: '0 6px 18px rgba(15,23,42,0.22)',
+        whiteSpace: 'nowrap',
+        maxWidth: '280px',
+        overflow: 'hidden',
+        textOverflow: 'ellipsis',
+    });
+    layer.appendChild(label);
+    document.body.appendChild(layer);
+    return layer;
+}
 let _hovered = null;
 let _pinned = null;
-function restoreEl(saved) {
-    saved.el.style.outline = saved.outline;
-    saved.el.style.boxShadow = saved.shadow;
-}
-function applyHighlight(el, color) {
-    el.style.outline = `2px solid ${color}`;
-    el.style.boxShadow = `0 0 0 4px ${color}28`;
+let _highlightRaf = 0;
+let _highlightCleanup = null;
+function labelForElement(el) {
+    const htmlEl = el;
+    const parts = [el.tagName.toLowerCase()];
+    if (htmlEl.id)
+        parts.push(`#${htmlEl.id}`);
+    const classes = typeof htmlEl.className === 'string'
+        ? htmlEl.className.trim().split(/\s+/).filter(Boolean).slice(0, 2)
+        : [];
+    if (classes.length)
+        parts.push(`.${classes.join('.')}`);
+    return parts.join('');
 }
-function hoverEl(el) {
-    if (_hovered) {
-        restoreEl(_hovered);
-        _hovered = null;
+function renderHighlight(el, mode) {
+    const rect = el.getBoundingClientRect();
+    const layer = getHighlightLayer();
+    const label = layer.querySelector('[data-wcag-highlight-label="true"]');
+    if (rect.width <= 0 || rect.height <= 0) {
+        layer.style.display = 'none';
+        return;
+    }
+    const color = mode === 'pinned' ? '#7c3aed' : '#0ea5e9';
+    const glow = mode === 'pinned' ? 'rgba(124,58,237,0.35)' : 'rgba(14,165,233,0.28)';
+    Object.assign(layer.style, {
+        display: 'block',
+        top: `${Math.max(rect.top - 4, 0)}px`,
+        left: `${Math.max(rect.left - 4, 0)}px`,
+        width: `${Math.max(rect.width + 8, 12)}px`,
+        height: `${Math.max(rect.height + 8, 12)}px`,
+        border: `3px solid ${color}`,
+        background: `${color}0d`,
+        boxShadow: `0 0 0 4px ${glow}, 0 14px 34px rgba(15,23,42,0.16)`,
+        opacity: '1',
+    });
+    if (label) {
+        label.textContent = mode === 'pinned' ? `Pinned ${labelForElement(el)}` : `Inspecting ${labelForElement(el)}`;
+        label.style.background = color;
+        label.style.top = rect.top < 48 ? `${rect.height + 10}px` : '-30px';
     }
-    if (!el || (_pinned === null || _pinned === void 0 ? void 0 : _pinned.el) === el)
+}
+function syncHighlightPosition() {
+    cancelAnimationFrame(_highlightRaf);
+    _highlightRaf = requestAnimationFrame(() => {
+        if (_pinned) {
+            renderHighlight(_pinned, 'pinned');
+            return;
+        }
+        if (_hovered) {
+            renderHighlight(_hovered, 'hover');
+            return;
+        }
+        const layer = document.getElementById(HIGHLIGHT_ID);
+        if (layer)
+            layer.style.display = 'none';
+    });
+}
+function ensureHighlightTracking() {
+    if (_highlightCleanup)
         return;
-    const h = el;
-    _hovered = { el: h, outline: h.style.outline, shadow: h.style.boxShadow };
-    applyHighlight(h, '#0ea5e9');
-    h.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+    const update = () => syncHighlightPosition();
+    window.addEventListener('scroll', update, true);
+    window.addEventListener('resize', update);
+    _highlightCleanup = () => {
+        window.removeEventListener('scroll', update, true);
+        window.removeEventListener('resize', update);
+        _highlightCleanup = null;
+    };
+}
+function maybeStopHighlightTracking() {
+    if (_hovered || _pinned || !_highlightCleanup)
+        return;
+    _highlightCleanup();
+}
+function hoverEl(el) {
+    _hovered = !el || _pinned === el ? null : el;
+    ensureHighlightTracking();
+    syncHighlightPosition();
 }
 function clearHover() {
-    if (_hovered) {
-        restoreEl(_hovered);
-        _hovered = null;
-    }
+    _hovered = null;
+    syncHighlightPosition();
+    maybeStopHighlightTracking();
 }
-function pinEl(el) {
-    if ((_pinned === null || _pinned === void 0 ? void 0 : _pinned.el) === el) {
-        restoreEl(_pinned);
+/** Returns true if now pinned, false if unpinned */
+function togglePin(el) {
+    if (_pinned === el) {
         _pinned = null;
+        syncHighlightPosition();
+        maybeStopHighlightTracking();
         return false;
     }
-    if (_pinned)
-        restoreEl(_pinned);
-    if ((_hovered === null || _hovered === void 0 ? void 0 : _hovered.el) === el) {
-        restoreEl(_hovered);
-        _hovered = null;
-    }
-    const h = el;
-    _pinned = { el: h, outline: h.style.outline, shadow: h.style.boxShadow };
-    applyHighlight(h, '#7c3aed');
-    h.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+    _hovered = null;
+    _pinned = el;
+    ensureHighlightTracking();
+    syncHighlightPosition();
+    el.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'nearest' });
     return true;
 }
 function clearAllHighlights() {
-    if (_hovered) {
-        restoreEl(_hovered);
-        _hovered = null;
-    }
-    if (_pinned) {
-        restoreEl(_pinned);
-        _pinned = null;
-    }
+    cancelAnimationFrame(_highlightRaf);
+    _hovered = null;
+    _pinned = null;
+    const layer = document.getElementById(HIGHLIGHT_ID);
+    if (layer)
+        layer.style.display = 'none';
+    maybeStopHighlightTracking();
 }
-const ViolationCard = ({ item, pinned, onPin }) => {
+const ViolationCard = ({ item, pinned, onPin, apiKey }) => {
     const [expanded, setExpanded] = (0, react_1.useState)(false);
-    const { color, bg, border } = impactTheme(item.impact);
-    const clickable = !!item.domElement;
+    const [aiState, setAiState] = (0, react_1.useState)('idle');
+    const [suggestion, setSuggestion] = (0, react_1.useState)(null);
+    const [aiError, setAiError] = (0, react_1.useState)('');
+    const { color, bg, border } = theme(item.impact);
+    const fetchAi = async () => {
+        if (!apiKey || aiState === 'loading')
+            return;
+        setAiState('loading');
+        setAiError('');
+        try {
+            const s = await (0, gemini_1.getAiSuggestion)(apiKey, item);
+            setSuggestion(s);
+            setAiState('done');
+        }
+        catch (e) {
+            setAiError(e instanceof Error ? e.message : 'Unknown error');
+            setAiState('error');
+        }
+    };
     return ((0, jsx_runtime_1.jsxs)("div", { style: {
-            background: bg,
-            borderRadius: 8,
-            marginBottom: 6,
-            overflow: 'hidden',
+            background: bg, borderRadius: 8, marginBottom: 6, overflow: 'hidden',
             outline: pinned ? `2px solid ${color}` : `1px solid ${border}`,
             outlineOffset: pinned ? 1 : 0,
             borderLeft: `3px solid ${color}`,
-        }, children: [(0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', alignItems: 'flex-start', gap: 8, padding: '9px 10px', cursor: clickable ? 'pointer' : 'default' }, onMouseEnter: () => hoverEl(item.domElement), onMouseLeave: () => clearHover(), onClick: () => item.domElement && onPin(item.domElement), children: [(0, jsx_runtime_1.jsx)("span", { style: {
+        }, children: [(0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', alignItems: 'flex-start', gap: 8, padding: '9px 10px', cursor: item.domElement ? 'pointer' : 'default' }, onMouseEnter: () => hoverEl(item.domElement), onMouseLeave: () => clearHover(), onClick: () => item.domElement && onPin(item.domElement), title: item.domElement ? (pinned ? 'Click to unpin' : 'Click to pin element') : undefined, children: [(0, jsx_runtime_1.jsx)("span", { style: {
                             fontSize: 9, fontWeight: 700, letterSpacing: '0.06em', textTransform: 'uppercase',
                             background: color, color: '#fff', borderRadius: 4, padding: '2px 5px', flexShrink: 0, marginTop: 2,
                         }, children: item.impact }), (0, jsx_runtime_1.jsxs)("span", { style: { fontSize: 12, fontWeight: 500, color: '#1e293b', lineHeight: 1.5, flex: 1 }, children: [item.description, pinned && (0, jsx_runtime_1.jsx)("span", { style: { marginLeft: 5, fontSize: 10 }, children: "\uD83D\uDCCD" })] }), (0, jsx_runtime_1.jsx)("button", { style: { background: 'none', border: 'none', cursor: 'pointer', color: '#94a3b8', fontSize: 11, padding: '1px 4px', flexShrink: 0 }, onClick: e => { e.stopPropagation(); setExpanded(x => !x); }, title: expanded ? 'Collapse' : 'Show details', children: expanded ? '▲' : '▼' })] }), expanded && ((0, jsx_runtime_1.jsxs)("div", { style: { padding: '0 10px 10px', borderTop: `1px solid ${border}` }, children: [item.elementPath && ((0, jsx_runtime_1.jsx)("code", { style: {
                             display: 'block', marginTop: 8, fontSize: 10, color: '#475569',
                             background: '#f1f5f9', border: '1px solid #e2e8f0', borderRadius: 4,
-                            padding: '3px 7px', fontFamily: 'monospace', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
-                        }, children: item.elementPath })), item.snippet && ((0, jsx_runtime_1.jsx)("code", { style: {
+                            padding: '3px 7px', fontFamily: 'monospace', overflow: 'hidden',
+                            textOverflow: 'ellipsis', whiteSpace: 'nowrap',
+                        }, title: item.elementSelector, children: item.elementPath })), item.snippet && ((0, jsx_runtime_1.jsx)("code", { style: {
                             display: 'block', marginTop: 6, fontSize: 10,
                             background: '#0f172a', color: '#e2e8f0', borderRadius: 5,
-                            padding: '5px 8px', fontFamily: 'monospace', whiteSpace: 'pre-wrap', wordBreak: 'break-all',
-                            maxHeight: 72, overflow: 'auto',
+                            padding: '5px 8px', fontFamily: 'monospace', whiteSpace: 'pre-wrap',
+                            wordBreak: 'break-all', maxHeight: 72, overflow: 'auto',
                         }, children: item.snippet })), item.help && ((0, jsx_runtime_1.jsx)("p", { style: { margin: '7px 0 0', fontSize: 11, color: '#475569', fontStyle: 'italic', lineHeight: 1.5 }, children: item.help })), item.wcag && item.wcag.length > 0 && ((0, jsx_runtime_1.jsx)("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 4, marginTop: 7 }, children: item.wcag.map(w => ((0, jsx_runtime_1.jsxs)("span", { style: {
                                 fontSize: 10, fontWeight: 600, color: '#7c3aed',
                                 background: '#f5f3ff', border: '1px solid #ddd6fe', borderRadius: 4, padding: '1px 6px',
-                            }, children: ["WCAG ", w] }, w))) }))] }))] }));
+                            }, children: ["WCAG ", w] }, w))) })), apiKey && ((0, jsx_runtime_1.jsxs)("div", { style: { marginTop: 10, borderTop: `1px solid ${border}`, paddingTop: 8 }, children: [aiState === 'idle' && ((0, jsx_runtime_1.jsx)("button", { onClick: fetchAi, style: {
+                                    fontSize: 10, fontWeight: 600, color: '#7c3aed',
+                                    background: '#f5f3ff', border: '1px solid #ddd6fe', borderRadius: 5,
+                                    padding: '3px 9px', cursor: 'pointer',
+                                }, children: "\u2728 Get AI fix" })), aiState === 'loading' && ((0, jsx_runtime_1.jsx)("span", { style: { fontSize: 10, color: '#94a3b8' }, children: "\u23F3 Asking Gemini\u2026" })), aiState === 'error' && ((0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsxs)("span", { style: { fontSize: 10, color: '#dc2626' }, children: ["\u26A0 ", aiError] }), (0, jsx_runtime_1.jsx)("button", { onClick: fetchAi, style: { marginLeft: 8, fontSize: 10, color: '#7c3aed', background: 'none', border: 'none', cursor: 'pointer' }, children: "Retry" })] })), aiState === 'done' && suggestion && ((0, jsx_runtime_1.jsxs)("div", { children: [suggestion.code && ((0, jsx_runtime_1.jsx)("code", { style: {
+                                            display: 'block', fontSize: 10, background: '#0f172a', color: '#86efac',
+                                            borderRadius: 5, padding: '5px 8px', fontFamily: 'monospace',
+                                            whiteSpace: 'pre-wrap', wordBreak: 'break-all', maxHeight: 100, overflow: 'auto',
+                                        }, children: suggestion.code })), suggestion.explanation && ((0, jsx_runtime_1.jsx)("p", { style: { margin: '5px 0 0', fontSize: 11, color: '#16a34a', fontStyle: 'italic' }, children: suggestion.explanation })), (0, jsx_runtime_1.jsx)("button", { onClick: () => { setSuggestion(null); setAiState('idle'); }, style: { marginTop: 4, fontSize: 10, color: '#94a3b8', background: 'none', border: 'none', cursor: 'pointer' }, children: "Clear" })] }))] }))] }))] }));
+};
+const SettingsPanel = ({ apiKey, preset, onSave, onPresetChange }) => {
+    const [draft, setDraft] = (0, react_1.useState)(apiKey);
+    const [saved, setSaved] = (0, react_1.useState)(false);
+    const save = () => {
+        (0, gemini_1.setStoredApiKey)(draft);
+        onSave(draft);
+        setSaved(true);
+        setTimeout(() => setSaved(false), 2000);
+    };
+    return ((0, jsx_runtime_1.jsxs)("div", { style: { padding: '16px 14px', flex: 1, overflowY: 'auto' }, children: [(0, jsx_runtime_1.jsxs)("p", { style: { margin: '0 0 12px', fontSize: 12, color: '#475569', lineHeight: 1.6 }, children: ["Enter your ", (0, jsx_runtime_1.jsx)("strong", { children: "Google Gemini API key" }), " to get AI-powered fix suggestions for each violation. The key is stored in ", (0, jsx_runtime_1.jsx)("code", { style: { fontSize: 11, background: '#f1f5f9', padding: '1px 4px', borderRadius: 3 }, children: "localStorage" }), " and never leaves your browser."] }), (0, jsx_runtime_1.jsx)("label", { style: { display: 'block', fontSize: 11, fontWeight: 600, color: '#374151', marginBottom: 4 }, children: "Gemini API Key" }), (0, jsx_runtime_1.jsx)("input", { type: "password", value: draft, onChange: e => setDraft(e.target.value), placeholder: "AIza\u2026", style: {
+                    width: '100%', boxSizing: 'border-box', fontSize: 12,
+                    border: '1px solid #d1d5db', borderRadius: 6, padding: '7px 10px',
+                    outline: 'none', fontFamily: 'monospace',
+                    background: '#f9fafb',
+                }, onKeyDown: e => { if (e.key === 'Enter')
+                    save(); } }), (0, jsx_runtime_1.jsxs)("div", { style: { marginTop: 10, display: 'flex', gap: 8, alignItems: 'center' }, children: [(0, jsx_runtime_1.jsx)("button", { onClick: save, style: {
+                            background: '#7c3aed', color: '#fff', border: 'none', borderRadius: 6,
+                            padding: '6px 14px', fontSize: 12, fontWeight: 600, cursor: 'pointer',
+                        }, children: saved ? '✓ Saved' : 'Save key' }), draft && ((0, jsx_runtime_1.jsx)("button", { onClick: () => { setDraft(''); (0, gemini_1.setStoredApiKey)(''); onSave(''); }, style: { fontSize: 11, color: '#94a3b8', background: 'none', border: 'none', cursor: 'pointer' }, children: "Clear" }))] }), (0, jsx_runtime_1.jsxs)("p", { style: { marginTop: 16, fontSize: 10, color: '#9ca3af', lineHeight: 1.6 }, children: ["Get a free key at", ' ', (0, jsx_runtime_1.jsx)("span", { style: { color: '#7c3aed', fontWeight: 600 }, children: "aistudio.google.com" }), ' ', "\u2192 Get API key. The free tier is sufficient for development use."] }), (0, jsx_runtime_1.jsxs)("div", { style: { marginTop: 18, paddingTop: 14, borderTop: '1px solid #e2e8f0' }, children: [(0, jsx_runtime_1.jsx)("label", { style: { display: 'block', fontSize: 11, fontWeight: 600, color: '#374151', marginBottom: 4 }, children: "Scan Preset" }), (0, jsx_runtime_1.jsxs)("select", { value: preset, onChange: e => onPresetChange(e.target.value), style: {
+                            width: '100%', boxSizing: 'border-box', fontSize: 12,
+                            border: '1px solid #d1d5db', borderRadius: 6, padding: '7px 10px',
+                            outline: 'none', background: '#f9fafb', color: '#111827',
+                        }, children: [(0, jsx_runtime_1.jsx)("option", { value: "fast", children: "Fast" }), (0, jsx_runtime_1.jsx)("option", { value: "full", children: "Full" })] }), (0, jsx_runtime_1.jsx)("p", { style: { margin: '8px 0 0', fontSize: 10, color: '#64748b', lineHeight: 1.6 }, children: "`fast` runs the default rule set. `full` also includes heavier checks like `backgroundImages`." })] })] }));
 };
 // ─── Main Overlay ──────────────────────────────────────────────────────────────
-const WcagDevOverlay = ({ level = 'AA', rules, position = 'bottom-right', debounce = 750, }) => {
+const WcagDevOverlay = ({ level = 'AA', preset = 'fast', rules, position = 'bottom-right', debounce = 750, }) => {
     var _a, _b, _c;
-    const [open, setOpen] = (0, react_1.useState)(() => {
-        try {
-            return sessionStorage.getItem('wcag-open') === '1';
-        }
-        catch (_a) {
-            return false;
-        }
-    });
+    const [open, setOpen] = (0, react_1.useState)(() => { try {
+        return sessionStorage.getItem('wcag-open') === '1';
+    }
+    catch (_a) {
+        return false;
+    } });
+    const [view, setView] = (0, react_1.useState)('list');
     const [tab, setTab] = (0, react_1.useState)('violations');
     const [filter, setFilter] = (0, react_1.useState)('all');
     const [scanning, setScanning] = (0, react_1.useState)(false);
     const [results, setResults] = (0, react_1.useState)(null);
     const [lastScan, setLastScan] = (0, react_1.useState)(null);
     const [pinnedEl, setPinnedEl] = (0, react_1.useState)(null);
+    const [apiKey, setApiKey] = (0, react_1.useState)(() => (0, gemini_1.getStoredApiKey)());
+    const [activePreset, setActivePreset] = (0, react_1.useState)(preset);
     // Drag
     const [pos, setPos] = (0, react_1.useState)(null);
     const dragging = (0, react_1.useRef)(false);
@@ -124,6 +271,8 @@ const WcagDevOverlay = ({ level = 'AA', rules, position = 'bottom-right', deboun
     const overlayRef = (0, react_1.useRef)(null);
     const scanningRef = (0, react_1.useRef)(false);
     const cooldownRef = (0, react_1.useRef)(false);
+    const pendingScanRef = (0, react_1.useRef)(false);
+    const scanTokenRef = (0, react_1.useRef)(0);
     // ── Persist open state ────────────────────────────────────────────────────
     (0, react_1.useEffect)(() => {
         try {
@@ -135,42 +284,55 @@ const WcagDevOverlay = ({ level = 'AA', rules, position = 'bottom-right', deboun
     }, [open]);
     // ── Scan ──────────────────────────────────────────────────────────────────
     const scan = (0, react_1.useCallback)(async () => {
-        if (scanningRef.current)
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        if (scanningRef.current) {
+            pendingScanRef.current = true;
             return;
+        }
+        const token = ++scanTokenRef.current;
+        // Set cooldown BEFORE clearing scanningRef to close the observer gap
+        cooldownRef.current = true;
         scanningRef.current = true;
         setScanning(true);
         try {
-            const res = await (0, browserScanner_1.scanBrowserPage)({ level, rules });
-            setResults(res);
-            setLastScan(new Date());
+            const res = await (0, browserScanner_1.scanBrowserPage)({ level, preset: activePreset, rules });
+            if (token === scanTokenRef.current) {
+                setResults(res);
+                setLastScan(new Date());
+            }
         }
         finally {
             scanningRef.current = false;
             setScanning(false);
-            // Cooldown prevents the observer from immediately re-triggering after scan
-            cooldownRef.current = true;
-            setTimeout(() => { cooldownRef.current = false; }, 1200);
+            window.setTimeout(() => {
+                cooldownRef.current = false;
+                if (pendingScanRef.current) {
+                    pendingScanRef.current = false;
+                    void scan();
+                }
+            }, 300);
         }
-    }, [level, rules]);
+    }, [activePreset, level, rules]);
     (0, react_1.useEffect)(() => { scan(); }, [scan]);
     // ── MutationObserver ──────────────────────────────────────────────────────
     (0, react_1.useEffect)(() => {
         observerRef.current = new MutationObserver((mutations) => {
             if (scanningRef.current || cooldownRef.current)
                 return;
-            if (overlayRef.current &&
-                mutations.every(m => overlayRef.current.contains(m.target)))
+            if (overlayRef.current && mutations.every(m => overlayRef.current.contains(m.target)))
                 return;
             if (timerRef.current)
                 clearTimeout(timerRef.current);
-            timerRef.current = setTimeout(scan, debounce);
+            timerRef.current = setTimeout(() => {
+                timerRef.current = null;
+                void scan();
+            }, debounce);
         });
         observerRef.current.observe(document.body, {
-            childList: true,
-            subtree: true,
-            attributes: true,
-            // 'style' excluded — our highlight helper modifies inline styles on
-            // page elements which would otherwise cause an infinite rescan loop
+            childList: true, subtree: true, attributes: true,
             attributeFilter: ['class', 'hidden', 'aria-hidden', 'role', 'alt', 'src', 'href'],
         });
         return () => {
@@ -181,33 +343,30 @@ const WcagDevOverlay = ({ level = 'AA', rules, position = 'bottom-right', deboun
             clearAllHighlights();
         };
     }, [scan, debounce]);
-    // ── Keyboard shortcut Alt+Shift+W ─────────────────────────────────────────
+    // ── Keyboard Alt+Shift+W ──────────────────────────────────────────────────
     (0, react_1.useEffect)(() => {
-        const handler = (e) => {
-            if (e.altKey && e.shiftKey && e.key === 'W')
-                setOpen(o => !o);
-        };
-        window.addEventListener('keydown', handler);
-        return () => window.removeEventListener('keydown', handler);
+        const h = (e) => { if (e.altKey && e.shiftKey && e.key === 'W')
+            setOpen(o => !o); };
+        window.addEventListener('keydown', h);
+        return () => window.removeEventListener('keydown', h);
     }, []);
-    // ── Pin handler ───────────────────────────────────────────────────────────
+    // ── Pin ───────────────────────────────────────────────────────────────────
     const handlePin = (0, react_1.useCallback)((el) => {
-        const nowPinned = pinEl(el);
+        const nowPinned = togglePin(el);
         setPinnedEl(nowPinned ? el : null);
     }, []);
     // ── Drag ──────────────────────────────────────────────────────────────────
     const onDragStart = (e) => {
         var _a, _b, _c;
         dragging.current = true;
-        const rect = (_a = overlayRef.current) === null || _a === void 0 ? void 0 : _a.getBoundingClientRect();
-        dragOffset.current = { x: e.clientX - ((_b = rect === null || rect === void 0 ? void 0 : rect.left) !== null && _b !== void 0 ? _b : 0), y: e.clientY - ((_c = rect === null || rect === void 0 ? void 0 : rect.top) !== null && _c !== void 0 ? _c : 0) };
+        const r = (_a = overlayRef.current) === null || _a === void 0 ? void 0 : _a.getBoundingClientRect();
+        dragOffset.current = { x: e.clientX - ((_b = r === null || r === void 0 ? void 0 : r.left) !== null && _b !== void 0 ? _b : 0), y: e.clientY - ((_c = r === null || r === void 0 ? void 0 : r.top) !== null && _c !== void 0 ? _c : 0) };
         e.preventDefault();
     };
     (0, react_1.useEffect)(() => {
         const onMove = (e) => {
-            if (!dragging.current)
-                return;
-            setPos({ x: e.clientX - dragOffset.current.x, y: e.clientY - dragOffset.current.y });
+            if (dragging.current)
+                setPos({ x: e.clientX - dragOffset.current.x, y: e.clientY - dragOffset.current.y });
         };
         const onUp = () => { dragging.current = false; };
         window.addEventListener('mousemove', onMove);
@@ -230,58 +389,10 @@ const WcagDevOverlay = ({ level = 'AA', rules, position = 'bottom-right', deboun
     const anchorStyle = pos
         ? { position: 'fixed', top: pos.y, left: pos.x, zIndex: 2147483647, fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif' }
         : { position: 'fixed', bottom: 20, [isLeft ? 'left' : 'right']: 20, zIndex: 2147483647, fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif' };
-    const btnColor = scanning ? '#64748b' : vCount > 0 ? '#7c3aed' : '#16a34a';
-    const s = {
-        toggle: {
-            display: 'flex', alignItems: 'center', gap: 6,
-            background: btnColor, color: '#fff', border: 'none', borderRadius: 22,
-            padding: '8px 14px', fontSize: 12, fontWeight: 600, cursor: 'pointer',
-            boxShadow: '0 2px 12px rgba(0,0,0,0.2)', userSelect: 'none',
-        },
-        badge: {
-            background: 'rgba(255,255,255,0.22)', borderRadius: 9,
-            padding: '1px 6px', fontSize: 11, fontWeight: 700,
-        },
-        panel: {
-            position: 'absolute',
-            bottom: pos ? undefined : 48,
-            top: pos ? 48 : undefined,
-            [isLeft ? 'left' : 'right']: 0,
-            width: 400,
-            maxHeight: '74vh',
-            background: '#ffffff',
-            borderRadius: 10,
-            boxShadow: '0 8px 40px rgba(0,0,0,0.16), 0 0 0 1px rgba(0,0,0,0.07)',
-            display: 'flex',
-            flexDirection: 'column',
-            overflow: 'hidden',
-        },
-        header: {
-            display: 'flex', alignItems: 'center', gap: 8,
-            padding: '10px 12px', background: '#0f172a',
-            cursor: 'grab', userSelect: 'none', flexShrink: 0,
-        },
-        headerBtn: {
-            background: 'none', border: 'none', cursor: 'pointer',
-            color: '#64748b', fontSize: 14, padding: '2px 5px', lineHeight: 1, borderRadius: 4,
-        },
-        summary: {
-            display: 'flex', gap: 6, padding: '8px 12px',
-            borderBottom: '1px solid #f1f5f9', background: '#f8fafc', flexShrink: 0,
-        },
-        toolbar: {
-            display: 'flex', alignItems: 'center',
-            borderBottom: '1px solid #f1f5f9', padding: '0 12px',
-            gap: 2, flexShrink: 0,
-        },
-        list: {
-            flex: 1, overflowY: 'auto', padding: '10px 10px',
-        },
-        footer: {
-            display: 'flex', alignItems: 'center', justifyContent: 'space-between',
-            padding: '7px 12px', borderTop: '1px solid #f1f5f9',
-            background: '#f8fafc', fontSize: 10, color: '#94a3b8', flexShrink: 0,
-        },
+    const btnBg = scanning ? '#64748b' : vCount > 0 ? '#7c3aed' : '#16a34a';
+    const iconBtnStyle = {
+        background: 'none', border: 'none', cursor: 'pointer',
+        color: '#64748b', fontSize: 14, padding: '2px 5px', lineHeight: 1, borderRadius: 4,
     };
     const chip = (color, count) => ({
         display: 'flex', alignItems: 'center', gap: 3, fontSize: 11, fontWeight: 600,
@@ -302,17 +413,34 @@ const WcagDevOverlay = ({ level = 'AA', rules, position = 'bottom-right', deboun
         padding: '4px 10px', fontSize: 10, fontWeight: 600,
         cursor: scanning ? 'wait' : 'pointer', opacity: scanning ? 0.55 : 1,
     };
-    return ((0, jsx_runtime_1.jsxs)("div", { ref: overlayRef, style: anchorStyle, "data-wcag-overlay": "true", children: [open && ((0, jsx_runtime_1.jsxs)("div", { style: s.panel, role: "dialog", "aria-label": "WCAG Dev Inspector", children: [(0, jsx_runtime_1.jsxs)("div", { style: s.header, onMouseDown: onDragStart, children: [(0, jsx_runtime_1.jsx)("span", { style: { fontSize: 14 }, children: "\u267F" }), (0, jsx_runtime_1.jsx)("span", { style: { fontWeight: 700, fontSize: 13, flex: 1, color: '#f1f5f9' }, children: "WCAG Inspector" }), (0, jsx_runtime_1.jsx)("span", { style: {
+    const viewActive = (v) => ({
+        ...iconBtnStyle,
+        color: view === v ? '#7c3aed' : '#64748b',
+        background: view === v ? '#f5f3ff' : 'none',
+    });
+    return ((0, jsx_runtime_1.jsxs)("div", { ref: overlayRef, style: anchorStyle, "data-wcag-overlay": "true", children: [open && ((0, jsx_runtime_1.jsxs)("div", { style: {
+                    position: 'absolute', bottom: pos ? undefined : 48, top: pos ? 48 : undefined,
+                    [isLeft ? 'left' : 'right']: 0, width: 410, maxHeight: '75vh',
+                    background: '#fff', borderRadius: 10,
+                    boxShadow: '0 8px 40px rgba(0,0,0,0.16), 0 0 0 1px rgba(0,0,0,0.07)',
+                    display: 'flex', flexDirection: 'column', overflow: 'hidden',
+                }, role: "dialog", "aria-label": "WCAG Dev Inspector", children: [(0, jsx_runtime_1.jsxs)("div", { style: {
+                            display: 'flex', alignItems: 'center', gap: 8,
+                            padding: '10px 12px', background: '#0f172a',
+                            cursor: 'grab', userSelect: 'none', flexShrink: 0,
+                        }, onMouseDown: onDragStart, children: [(0, jsx_runtime_1.jsx)("span", { style: { fontSize: 14 }, children: "\u267F" }), (0, jsx_runtime_1.jsx)("span", { style: { fontWeight: 700, fontSize: 13, flex: 1, color: '#f1f5f9' }, children: "WCAG Inspector" }), (0, jsx_runtime_1.jsx)("span", { style: {
                                     fontSize: 9, fontWeight: 700, color: '#a78bfa',
                                     background: '#4c1d95', borderRadius: 4, padding: '2px 6px', letterSpacing: '0.05em',
-                                }, children: level }), (0, jsx_runtime_1.jsx)("button", { onClick: scan, disabled: scanning, title: "Rescan", style: s.headerBtn, children: scanning ? '⏳' : '↻' }), (0, jsx_runtime_1.jsx)("button", { onClick: () => setOpen(false), title: "Close (Alt+Shift+W)", style: s.headerBtn, children: "\u2715" })] }), (0, jsx_runtime_1.jsxs)("div", { style: s.summary, children: [(0, jsx_runtime_1.jsxs)("span", { style: chip('#dc2626', vCount), children: ["\u2717 ", vCount, " violation", vCount !== 1 ? 's' : ''] }), (0, jsx_runtime_1.jsxs)("span", { style: chip('#ea580c', wCount), children: ["\u26A0 ", wCount, " warning", wCount !== 1 ? 's' : ''] }), (0, jsx_runtime_1.jsxs)("span", { style: chip('#16a34a', pCount), children: ["\u2713 ", pCount, " pass", pCount !== 1 ? 'es' : ''] })] }), (0, jsx_runtime_1.jsxs)("div", { style: s.toolbar, children: [(0, jsx_runtime_1.jsxs)("button", { style: tabBtn(tab === 'violations'), onClick: () => setTab('violations'), children: ["Violations (", vCount, ")"] }), (0, jsx_runtime_1.jsxs)("button", { style: tabBtn(tab === 'warnings'), onClick: () => setTab('warnings'), children: ["Warnings (", wCount, ")"] }), (0, jsx_runtime_1.jsxs)("select", { style: {
-                                    marginLeft: 'auto', fontSize: 10, border: '1px solid #e2e8f0',
-                                    borderRadius: 5, padding: '3px 6px', color: '#475569', background: '#fff', cursor: 'pointer', outline: 'none',
-                                }, value: filter, onChange: e => setFilter(e.target.value), children: [(0, jsx_runtime_1.jsx)("option", { value: "all", children: "All" }), (0, jsx_runtime_1.jsx)("option", { value: "critical", children: "Critical" }), (0, jsx_runtime_1.jsx)("option", { value: "serious", children: "Serious" }), (0, jsx_runtime_1.jsx)("option", { value: "moderate", children: "Moderate" }), (0, jsx_runtime_1.jsx)("option", { value: "minor", children: "Minor" })] })] }), (0, jsx_runtime_1.jsxs)("div", { style: s.list, children: [scanning && !results && ((0, jsx_runtime_1.jsxs)("div", { style: { textAlign: 'center', color: '#94a3b8', padding: '28px 0', fontSize: 12 }, children: [(0, jsx_runtime_1.jsx)("div", { style: { fontSize: 22, marginBottom: 8 }, children: "\u23F3" }), "Scanning\u2026"] })), !scanning && isEmpty && ((0, jsx_runtime_1.jsxs)("div", { style: { textAlign: 'center', padding: '28px 0' }, children: [(0, jsx_runtime_1.jsx)("div", { style: { fontSize: 28, marginBottom: 8 }, children: tab === 'violations' ? '✅' : '🔕' }), (0, jsx_runtime_1.jsxs)("div", { style: { color: '#64748b', fontSize: 12, fontWeight: 500 }, children: ["No ", tab, " found"] }), filter !== 'all' && ((0, jsx_runtime_1.jsx)("button", { style: { marginTop: 6, fontSize: 11, color: '#7c3aed', background: 'none', border: 'none', cursor: 'pointer' }, onClick: () => setFilter('all'), children: "Clear filter" }))] })), items === null || items === void 0 ? void 0 : items.map((item, i) => ((0, jsx_runtime_1.jsx)(ViolationCard, { item: item, pinned: pinnedEl === item.domElement && item.domElement != null, onPin: handlePin }, `${item.rule}-${i}`)))] }), (0, jsx_runtime_1.jsxs)("div", { style: s.footer, children: [(0, jsx_runtime_1.jsxs)("span", { children: [pinnedEl ? '📍 pinned · ' : '', "Scanned ", elapsed, results ? ` · ${results.duration}ms` : ''] }), (0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', gap: 6, alignItems: 'center' }, children: [pinnedEl && ((0, jsx_runtime_1.jsx)("button", { style: { ...rescanBtn, background: '#64748b' }, onClick: () => { clearAllHighlights(); setPinnedEl(null); }, children: "Unpin" })), (0, jsx_runtime_1.jsx)("button", { style: rescanBtn, onClick: scan, disabled: scanning, children: scanning ? 'Scanning…' : 'Rescan' })] })] })] })), (0, jsx_runtime_1.jsxs)("button", { style: s.toggle, onClick: () => setOpen(o => !o), title: "Toggle WCAG Inspector (Alt+Shift+W)", "aria-expanded": open, children: [(0, jsx_runtime_1.jsx)("span", { style: { fontSize: 14 }, children: "\u267F" }), scanning
+                                }, children: level }), (0, jsx_runtime_1.jsx)("button", { onClick: () => setView(v => v === 'settings' ? 'list' : 'settings'), style: viewActive('settings'), title: "Settings", children: "\u2699" }), (0, jsx_runtime_1.jsx)("button", { onClick: scan, disabled: scanning, title: "Rescan", style: iconBtnStyle, children: scanning ? '⏳' : '↻' }), (0, jsx_runtime_1.jsx)("button", { onClick: () => setOpen(false), title: "Close (Alt+Shift+W)", style: iconBtnStyle, children: "\u2715" })] }), view === 'settings' ? ((0, jsx_runtime_1.jsx)(SettingsPanel, { apiKey: apiKey, preset: activePreset, onSave: k => setApiKey(k), onPresetChange: setActivePreset })) : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', gap: 6, padding: '8px 12px', borderBottom: '1px solid #f1f5f9', background: '#f8fafc', flexShrink: 0 }, children: [(0, jsx_runtime_1.jsxs)("span", { style: chip('#dc2626', vCount), children: ["\u2717 ", vCount, " violation", vCount !== 1 ? 's' : ''] }), (0, jsx_runtime_1.jsxs)("span", { style: chip('#ea580c', wCount), children: ["\u26A0 ", wCount, " warning", wCount !== 1 ? 's' : ''] }), (0, jsx_runtime_1.jsxs)("span", { style: chip('#16a34a', pCount), children: ["\u2713 ", pCount, " pass", pCount !== 1 ? 'es' : ''] }), apiKey && (0, jsx_runtime_1.jsx)("span", { style: { ...chip('#7c3aed', 1), marginLeft: 'auto' }, title: "AI suggestions enabled", children: "\u2728 AI" })] }), (0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', alignItems: 'center', borderBottom: '1px solid #f1f5f9', padding: '0 12px', gap: 2, flexShrink: 0 }, children: [(0, jsx_runtime_1.jsxs)("button", { style: tabBtn(tab === 'violations'), onClick: () => setTab('violations'), children: ["Violations (", vCount, ")"] }), (0, jsx_runtime_1.jsxs)("button", { style: tabBtn(tab === 'warnings'), onClick: () => setTab('warnings'), children: ["Warnings (", wCount, ")"] }), (0, jsx_runtime_1.jsxs)("select", { style: { marginLeft: 'auto', fontSize: 10, border: '1px solid #e2e8f0', borderRadius: 5, padding: '3px 6px', color: '#475569', background: '#fff', cursor: 'pointer', outline: 'none' }, value: filter, onChange: e => setFilter(e.target.value), children: [(0, jsx_runtime_1.jsx)("option", { value: "all", children: "All" }), (0, jsx_runtime_1.jsx)("option", { value: "critical", children: "Critical" }), (0, jsx_runtime_1.jsx)("option", { value: "serious", children: "Serious" }), (0, jsx_runtime_1.jsx)("option", { value: "moderate", children: "Moderate" }), (0, jsx_runtime_1.jsx)("option", { value: "minor", children: "Minor" })] })] }), (0, jsx_runtime_1.jsxs)("div", { style: { flex: 1, overflowY: 'auto', padding: '10px' }, children: [scanning && !results && ((0, jsx_runtime_1.jsxs)("div", { style: { textAlign: 'center', color: '#94a3b8', padding: '28px 0', fontSize: 12 }, children: [(0, jsx_runtime_1.jsx)("div", { style: { fontSize: 22, marginBottom: 8 }, children: "\u23F3" }), "Scanning\u2026"] })), !scanning && isEmpty && ((0, jsx_runtime_1.jsxs)("div", { style: { textAlign: 'center', padding: '28px 0' }, children: [(0, jsx_runtime_1.jsx)("div", { style: { fontSize: 28, marginBottom: 8 }, children: tab === 'violations' ? '✅' : '🔕' }), (0, jsx_runtime_1.jsxs)("div", { style: { color: '#64748b', fontSize: 12, fontWeight: 500 }, children: ["No ", tab, " found"] }), filter !== 'all' && ((0, jsx_runtime_1.jsx)("button", { style: { marginTop: 6, fontSize: 11, color: '#7c3aed', background: 'none', border: 'none', cursor: 'pointer' }, onClick: () => setFilter('all'), children: "Clear filter" }))] })), items === null || items === void 0 ? void 0 : items.map((item, i) => ((0, jsx_runtime_1.jsx)(ViolationCard, { item: item, pinned: pinnedEl === item.domElement && item.domElement != null, onPin: handlePin, apiKey: apiKey }, `${item.rule}-${i}`)))] }), (0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '7px 12px', borderTop: '1px solid #f1f5f9', background: '#f8fafc', fontSize: 10, color: '#94a3b8', flexShrink: 0 }, children: [(0, jsx_runtime_1.jsxs)("span", { children: [pinnedEl ? '📍 pinned · ' : '', "Scanned ", elapsed, results ? ` · ${results.duration}ms` : ''] }), (0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', gap: 6, alignItems: 'center' }, children: [pinnedEl && ((0, jsx_runtime_1.jsx)("button", { style: { ...rescanBtn, background: '#64748b' }, onClick: () => { clearAllHighlights(); setPinnedEl(null); }, children: "Unpin" })), (0, jsx_runtime_1.jsx)("button", { style: rescanBtn, onClick: scan, disabled: scanning, children: scanning ? 'Scanning…' : 'Rescan' })] })] })] }))] })), (0, jsx_runtime_1.jsxs)("button", { style: {
+                    display: 'flex', alignItems: 'center', gap: 6,
+                    background: btnBg, color: '#fff', border: 'none', borderRadius: 22,
+                    padding: '8px 14px', fontSize: 12, fontWeight: 600, cursor: 'pointer',
+                    boxShadow: '0 2px 12px rgba(0,0,0,0.2)', userSelect: 'none',
+                }, onClick: () => setOpen(o => !o), title: "Toggle WCAG Inspector (Alt+Shift+W)", "aria-expanded": open, children: [(0, jsx_runtime_1.jsx)("span", { style: { fontSize: 14 }, children: "\u267F" }), scanning
                         ? (0, jsx_runtime_1.jsx)("span", { style: { opacity: 0.8, fontSize: 11 }, children: "scanning\u2026" })
                         : vCount > 0
-                            ? (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("span", { style: s.badge, children: vCount }), (0, jsx_runtime_1.jsx)("span", { style: { fontSize: 11 }, children: "issues" })] })
-                            : (0, jsx_runtime_1.jsx)("span", { style: s.badge, children: "\u2713" })] })] }));
+                            ? (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("span", { style: { background: 'rgba(255,255,255,0.22)', borderRadius: 9, padding: '1px 6px', fontSize: 11, fontWeight: 700 }, children: vCount }), (0, jsx_runtime_1.jsx)("span", { style: { fontSize: 11 }, children: " issues" })] })
+                            : (0, jsx_runtime_1.jsx)("span", { style: { background: 'rgba(255,255,255,0.22)', borderRadius: 9, padding: '1px 6px', fontSize: 11, fontWeight: 700 }, children: "\u2713" })] })] }));
 };
 exports.WcagDevOverlay = WcagDevOverlay;
 exports.default = exports.WcagDevOverlay;

package/dist/react/browserScanner.d.ts

@@ -2,10 +2,13 @@ import { ScannerOptions, Violation, Warning, Pass } from '../types';
 export interface AnnotatedViolation extends Violation {
     domElement?: Element;
     elementPath?: string;
+    /** Precise nth-child CSS selector — use for querySelector to find element */
+    elementSelector?: string;
 }
 export interface AnnotatedWarning extends Warning {
     domElement?: Element;
     elementPath?: string;
+    elementSelector?: string;
 }
 export interface BrowserScanResults {
     violations: AnnotatedViolation[];
@@ -14,5 +17,12 @@ export interface BrowserScanResults {
     duration: number;
 }
 export declare function scanBrowserPage(options?: ScannerOptions): Promise<BrowserScanResults>;
-/** Build a readable CSS-selector-style breadcrumb for an element. */
+/**
+ * Build a precise nth-child CSS selector path for an element.
+ * This is unambiguous and always finds the exact element.
+ */
+export declare function getNthChildSelector(el: Element): string;
+/** Build a human-readable breadcrumb label for an element. */
 export declare function getElementPath(el: Element): string;
+export declare function findElement(item: Violation | Warning, doc: Document): Element | null;
+export declare function findBySnippet(snippet: string, doc: Document): Element | null;