1const IS_BROWSER = typeof window !== 'undefined';
2 
3// ─── Section 7: Browser UI (IS_BROWSER only) ────────────────────────────────
4 
5if (IS_BROWSER) {
6  // Detect extension mode via the script tag's data attribute or the document element fallback.
7  // currentScript is reliable for synchronously-executing scripts (which our IIFE is).
8  const _myScript = document.currentScript;
9  const EXTENSION_MODE = (_myScript && _myScript.dataset.impeccableExtension === 'true')
10    || document.documentElement.dataset.impeccableExtension === 'true';
11 
12  // Kinpaku gold — pinned to the site's brand token (see
13  // site/styles/kinpaku-tokens.css --ks-kinpaku). Keep this in sync with
14  // the picker's C.brand in skill/scripts/live-browser.js and the kit's
15  // picker section in site/styles/kinpaku-kit.css.
16  //
17  // One color across both light and dark host pages. The outline is a
18  // 2px gesture pointing at an element + a labeled tag — it's a marker,
19  // not body text, so it doesn't need WCAG AA against the page. The
20  // label text inside the gold tag is dark (LABEL_INK) which has ~16:1
21  // against the leaf gold, so reading the rule name is solid in both
22  // modes. Hover deepens the gold (preserves chroma — never drops it,
23  // dropping chroma washes the gold into a sand/olive tone).
24  const BRAND_COLOR = 'oklch(84% 0.19 80.46)';
25  const BRAND_COLOR_HOVER = 'oklch(74% 0.18 80)';
26  const LABEL_INK = 'oklch(4% 0.004 95)';
27  const LABEL_BG = BRAND_COLOR;
28  const OUTLINE_COLOR = BRAND_COLOR;
29 
30  // Inject hover styles via CSS (more reliable than JS event listeners)
31  const styleEl = document.createElement('style');
32  styleEl.textContent = `
33    @keyframes impeccable-reveal {
34      from { opacity: 0; }
35      to { opacity: 1; }
36    }
37    .impeccable-overlay:not(.impeccable-banner) {
38      pointer-events: none;
39      outline: 2px solid ${OUTLINE_COLOR};
40      border-radius: 4px;
41      transition: outline-color 0.15s ease;
42      animation: impeccable-reveal 0.4s cubic-bezier(0.16, 1, 0.3, 1) both;
43      animation-play-state: paused;
44      border-top-left-radius: 0;
45    }
46    .impeccable-overlay.impeccable-visible {
47      animation-play-state: running;
48    }
49    .impeccable-overlay.impeccable-hover {
50      outline-color: ${BRAND_COLOR_HOVER};
51      z-index: 100001 !important;
52    }
53    .impeccable-overlay.impeccable-hover .impeccable-label {
54      background: ${BRAND_COLOR_HOVER};
55    }
56    .impeccable-overlay.impeccable-spotlight {
57      z-index: 100002 !important;
58    }
59    .impeccable-overlay.impeccable-spotlight-dimmed {
60      opacity: 0.15 !important;
61      animation: none !important;
62      filter: blur(3px);
63    }
64    .impeccable-spotlight-backdrop {
65      position: fixed;
66      top: 0; left: 0; right: 0; bottom: 0;
67      backdrop-filter: blur(3px) brightness(0.6);
68      -webkit-backdrop-filter: blur(3px) brightness(0.6);
69      pointer-events: none;
70      z-index: 99998;
71      opacity: 0;
72      outline: none !important;
73      animation: none !important;
74    }
75    .impeccable-spotlight-backdrop.impeccable-visible {
76      opacity: 1;
77    }
78    .impeccable-hidden .impeccable-overlay${EXTENSION_MODE ? '' : ':not(.impeccable-banner)'} {
79      display: none !important;
80    }
81  `;
82  (document.head || document.documentElement).appendChild(styleEl);
83 
84  // Spotlight backdrop element (created lazily on first use)
85  let spotlightBackdrop = null;
86  let spotlightTarget = null;
87 
88  function getSpotlightBackdrop() {
89    if (!spotlightBackdrop) {
90      spotlightBackdrop = document.createElement('div');
91      spotlightBackdrop.className = 'impeccable-spotlight-backdrop';
92      document.body.appendChild(spotlightBackdrop);
93    }
94    return spotlightBackdrop;
95  }
96 
97  function updateSpotlightClipPath() {
98    if (!spotlightBackdrop || !spotlightTarget) return;
99    const r = spotlightTarget.getBoundingClientRect();
100    // Match the overlay's outer edge: element rect + 4px (2px overlay offset + 2px outline width)
101    const inset = 4;
102    const radius = 6; // outline border-radius (4) + outline width (2)
103    const x1 = r.left - inset;
104    const y1 = r.top - inset;
105    const x2 = r.right + inset;
106    const y2 = r.bottom + inset;
107    const vw = window.innerWidth;
108    const vh = window.innerHeight;
109    // Outer rect + rounded inner rect (evenodd creates a hole)
110    const path = `M0 0H${vw}V${vh}H0Z M${x1 + radius} ${y1}H${x2 - radius}A${radius} ${radius} 0 0 1 ${x2} ${y1 + radius}V${y2 - radius}A${radius} ${radius} 0 0 1 ${x2 - radius} ${y2}H${x1 + radius}A${radius} ${radius} 0 0 1 ${x1} ${y2 - radius}V${y1 + radius}A${radius} ${radius} 0 0 1 ${x1 + radius} ${y1}Z`;
111    spotlightBackdrop.style.clipPath = `path(evenodd, "${path}")`;
112  }
113 
114  function showSpotlight(target) {
115    if (!target || !target.getBoundingClientRect) return;
116    // Respect the spotlightBlur setting: if disabled, don't show the backdrop
117    if (window.__IMPECCABLE_CONFIG__?.spotlightBlur === false) {
118      spotlightTarget = target;
119      return;
120    }
121    spotlightTarget = target;
122    const bd = getSpotlightBackdrop();
123    updateSpotlightClipPath();
124    bd.classList.add('impeccable-visible');
125  }
126 
127  function hideSpotlight() {
128    spotlightTarget = null;
129    if (spotlightBackdrop) spotlightBackdrop.classList.remove('impeccable-visible');
130  }
131 
132  function isInViewport(el) {
133    const r = el.getBoundingClientRect();
134    return r.top >= 0 && r.left >= 0 && r.bottom <= window.innerHeight && r.right <= window.innerWidth;
135  }
136 
137  // Reposition spotlight on scroll/resize
138  window.addEventListener('scroll', () => {
139    if (spotlightTarget) updateSpotlightClipPath();
140  }, { passive: true });
141  window.addEventListener('resize', () => {
142    if (spotlightTarget) updateSpotlightClipPath();
143  });
144 
145  const overlays = [];
146  const TYPE_LABELS = {};
147  const RULE_CATEGORY = {};
148  for (const ap of ANTIPATTERNS) {
149    TYPE_LABELS[ap.id] = ap.name.toLowerCase();
150    RULE_CATEGORY[ap.id] = ap.category || 'quality';
151  }
152 
153  function isInFixedContext(el) {
154    let p = el;
155    while (p && p !== document.body) {
156      if (getComputedStyle(p).position === 'fixed') return true;
157      p = p.parentElement;
158    }
159    return false;
160  }
161 
162  function positionOverlay(overlay) {
163    const el = overlay._targetEl;
164    if (!el) return;
165    const rect = el.getBoundingClientRect();
166    if (overlay._isFixed) {
167      // Viewport-relative coords for fixed targets
168      overlay.style.top = `${rect.top - 2}px`;
169      overlay.style.left = `${rect.left - 2}px`;
170    } else {
171      // Document-relative coords for normal targets
172      overlay.style.top = `${rect.top + scrollY - 2}px`;
173      overlay.style.left = `${rect.left + scrollX - 2}px`;
174    }
175    overlay.style.width = `${rect.width + 4}px`;
176    overlay.style.height = `${rect.height + 4}px`;
177  }
178 
179  function repositionOverlays() {
180    for (const o of overlays) {
181      if (!o._targetEl || o.classList.contains('impeccable-banner')) continue;
182      // Skip overlays whose target is currently hidden (display: none on the overlay)
183      if (o.style.display === 'none') continue;
184      positionOverlay(o);
185    }
186  }
187 
188  let resizeRAF;
189  const onResize = () => {
190    cancelAnimationFrame(resizeRAF);
191    resizeRAF = requestAnimationFrame(repositionOverlays);
192  };
193  window.addEventListener('resize', onResize);
194  // Reposition on scroll too -- catches sticky/parallax shifts
195  window.addEventListener('scroll', onResize, { passive: true });
196  // Reposition when body resizes (lazy-loaded images, dynamic content, fonts loading)
197  if (typeof ResizeObserver !== 'undefined') {
198    const bodyResizeObserver = new ResizeObserver(onResize);
199    bodyResizeObserver.observe(document.body);
200  }
201 
202  // Track target element visibility via IntersectionObserver.
203  // Uses a huge rootMargin so all *rendered* elements count as intersecting,
204  // while display:none / closed <details> / hidden modals etc. do not.
205  // This is event-driven -- no polling needed.
206  let overlayIndex = 0;
207  const visibilityObserver = new IntersectionObserver((entries) => {
208    for (const entry of entries) {
209      const overlay = entry.target._impeccableOverlay;
210      if (!overlay) continue;
211      if (entry.isIntersecting) {
212        overlay.style.display = '';
213        positionOverlay(overlay);
214        if (!overlay._revealed) {
215          overlay._revealed = true;
216          if (firstScanDone) {
217            // Subsequent reveals (re-scans, scroll-into-view): instant, no animation
218            overlay.style.animation = 'none';
219          } else {
220            // Initial scan: staggered cascade reveal
221            overlay.style.animationDelay = `${Math.min((overlay._staggerIndex || 0) * 60, 600)}ms`;
222          }
223          requestAnimationFrame(() => {
224            overlay.classList.add('impeccable-visible');
225            if (overlay._checkLabel) overlay._checkLabel();
226          });
227        }
228      } else {
229        overlay.style.display = 'none';
230      }
231    }
232  }, { rootMargin: '99999px' });
233 
234  function detachOverlay(overlay) {
235    if (!overlay) return;
236    if (typeof overlay._cleanup === 'function') {
237      try { overlay._cleanup(); } catch { /* best effort overlay teardown */ }
238    }
239    if (overlay._targetEl && overlay._targetEl._impeccableOverlay === overlay) {
240      visibilityObserver.unobserve(overlay._targetEl);
241      delete overlay._targetEl._impeccableOverlay;
242    }
243    const idx = overlays.indexOf(overlay);
244    if (idx >= 0) overlays.splice(idx, 1);
245    overlay.remove();
246  }
247 
248  // Reposition overlays after CSS transitions end (e.g. reveal animations).
249  // Listens at document level so it catches transitions on ancestor elements
250  // (the transform may be on a parent, not the flagged element itself).
251  document.addEventListener('transitionend', (e) => {
252    if (e.propertyName !== 'transform') return;
253    for (const o of overlays) {
254      if (!o._targetEl || o.classList.contains('impeccable-banner') || o.style.display === 'none') continue;
255      if (e.target === o._targetEl || e.target.contains(o._targetEl)) {
256        positionOverlay(o);
257      }
258    }
259  });
260 
261  const highlight = function(el, findings) {
262    if (el._impeccableOverlay) detachOverlay(el._impeccableOverlay);
263    const hasSlop = findings.some(f => RULE_CATEGORY[f.type || f.id] === 'slop');
264 
265    const fixed = isInFixedContext(el);
266    const rect = el.getBoundingClientRect();
267    const outline = document.createElement('div');
268    outline.className = 'impeccable-overlay';
269    outline._targetEl = el;
270    outline._isFixed = fixed;
271    Object.assign(outline.style, {
272      position: fixed ? 'fixed' : 'absolute',
273      top: fixed ? `${rect.top - 2}px` : `${rect.top + scrollY - 2}px`,
274      left: fixed ? `${rect.left - 2}px` : `${rect.left + scrollX - 2}px`,
275      width: `${rect.width + 4}px`, height: `${rect.height + 4}px`,
276      zIndex: '99999', boxSizing: 'border-box',
277    });
278 
279    // Build per-finding label entries: ✦ prefix for slop
280    const entries = findings.map(f => {
281      const name = TYPE_LABELS[f.type || f.id] || f.type || f.id;
282      const prefix = RULE_CATEGORY[f.type || f.id] === 'slop' ? '\u2726 ' : '';
283      return { name: prefix + name, detail: f.detail || f.snippet };
284    });
285    const allText = entries.map(e => e.name).join(', ');
286 
287    const label = document.createElement('div');
288    label.className = 'impeccable-label';
289    Object.assign(label.style, {
290      position: 'absolute', bottom: '100%', left: '-2px',
291      display: 'flex', alignItems: 'center',
292      whiteSpace: 'nowrap',
293      fontSize: '11px', fontWeight: '600', letterSpacing: '0.02em',
294      color: LABEL_INK, lineHeight: '14px',
295      background: LABEL_BG,
296      fontFamily: 'system-ui, sans-serif',
297      borderRadius: '4px 4px 0 0',
298    });
299 
300    const textSpan = document.createElement('span');
301    textSpan.style.padding = '3px 8px';
302    textSpan.textContent = allText;
303    label.appendChild(textSpan);
304 
305    // State for cycling mode
306    let cycleMode = false;
307    let cycleIndex = 0;
308    let isHovered = false;
309    let prevBtn, nextBtn;
310 
311    function updateCycleText() {
312      const e = entries[cycleIndex];
313      textSpan.textContent = isHovered ? e.detail : e.name;
314    }
315 
316    function enableCycleMode() {
317      if (cycleMode || entries.length < 2) return;
318      cycleMode = true;
319 
320      const btnStyle = {
321        background: 'none', border: 'none', color: 'rgba(255,255,255,0.7)',
322        fontSize: '11px', cursor: 'pointer', padding: '3px 4px',
323        fontFamily: 'system-ui, sans-serif', lineHeight: '14px',
324        pointerEvents: 'auto',
325      };
326 
327      const navGroup = document.createElement('span');
328      Object.assign(navGroup.style, {
329        display: 'inline-flex', alignItems: 'center', flexShrink: '0',
330      });
331 
332      prevBtn = document.createElement('button');
333      prevBtn.textContent = '\u2039';
334      Object.assign(prevBtn.style, btnStyle);
335      prevBtn.style.paddingLeft = '6px';
336      prevBtn.addEventListener('click', (e) => {
337        e.stopPropagation();
338        cycleIndex = (cycleIndex - 1 + entries.length) % entries.length;
339        updateCycleText();
340      });
341 
342      nextBtn = document.createElement('button');
343      nextBtn.textContent = '\u203A';
344      Object.assign(nextBtn.style, btnStyle);
345      nextBtn.style.paddingRight = '2px';
346      nextBtn.addEventListener('click', (e) => {
347        e.stopPropagation();
348        cycleIndex = (cycleIndex + 1) % entries.length;
349        updateCycleText();
350      });
351 
352      navGroup.appendChild(prevBtn);
353      navGroup.appendChild(nextBtn);
354      label.insertBefore(navGroup, textSpan);
355      textSpan.style.padding = '3px 8px 3px 4px';
356      updateCycleText();
357    }
358 
359    outline.appendChild(label);
360 
361    // Start hidden; the IntersectionObserver will show it once the target is rendered
362    outline.style.display = 'none';
363    outline._staggerIndex = overlayIndex++;
364    el._impeccableOverlay = outline;
365    visibilityObserver.observe(el);
366 
367    // After first paint, check label width vs outline
368    outline._checkLabel = () => {
369      if (entries.length > 1 && label.offsetWidth > outline.offsetWidth) {
370        enableCycleMode();
371      }
372    };
373 
374    // Hover: show detail text, darken
375    const onMouseEnter = () => {
376      isHovered = true;
377      outline.classList.add('impeccable-hover');
378      outline.style.outlineColor = BRAND_COLOR_HOVER;
379      label.style.background = BRAND_COLOR_HOVER;
380      if (cycleMode) {
381        updateCycleText();
382      } else {
383        textSpan.textContent = entries.map(e => e.detail).join(' | ');
384      }
385    };
386    const onMouseLeave = () => {
387      isHovered = false;
388      outline.classList.remove('impeccable-hover');
389      outline.style.outlineColor = '';
390      label.style.background = LABEL_BG;
391      if (cycleMode) {
392        updateCycleText();
393      } else {
394        textSpan.textContent = allText;
395      }
396    };
397    el.addEventListener('mouseenter', onMouseEnter);
398    el.addEventListener('mouseleave', onMouseLeave);
399    outline._cleanup = () => {
400      el.removeEventListener('mouseenter', onMouseEnter);
401      el.removeEventListener('mouseleave', onMouseLeave);
402    };
403 
404    document.body.appendChild(outline);
405    overlays.push(outline);
406  };
407 
408  const showPageBanner = function(findings) {
409    if (!findings.length) return;
410    const banner = document.createElement('div');
411    banner.className = 'impeccable-overlay impeccable-banner';
412    Object.assign(banner.style, {
413      position: 'fixed', top: '0', left: '0', right: '0', zIndex: '100000',
414      background: LABEL_BG, color: LABEL_INK,
415      fontFamily: 'system-ui, sans-serif', fontSize: '13px',
416      display: 'flex', alignItems: 'center', pointerEvents: 'auto',
417      height: '36px', overflow: 'hidden', maxWidth: '100vw',
418      transform: 'translateY(-100%)',
419      transition: 'transform 0.4s cubic-bezier(0.16, 1, 0.3, 1)',
420    });
421    requestAnimationFrame(() => requestAnimationFrame(() => {
422      banner.style.transform = 'translateY(0)';
423    }));
424 
425    // Scrollable findings area
426    const scrollArea = document.createElement('div');
427    Object.assign(scrollArea.style, {
428      flex: '1', minWidth: '0', overflowX: 'auto', overflowY: 'hidden',
429      display: 'flex', gap: '8px', alignItems: 'center',
430      padding: '0 12px', scrollSnapType: 'x mandatory',
431      scrollbarWidth: 'none',
432    });
433    for (const f of findings) {
434      const prefix = RULE_CATEGORY[f.type] === 'slop' ? '\u2726 ' : '';
435      const tag = document.createElement('span');
436      tag.textContent = `${prefix}${TYPE_LABELS[f.type] || f.type}: ${f.detail}`;
437      Object.assign(tag.style, {
438        background: 'rgba(255,255,255,0.15)', padding: '2px 8px',
439        borderRadius: '3px', fontSize: '12px', fontFamily: 'ui-monospace, monospace',
440        whiteSpace: 'nowrap', flexShrink: '0', scrollSnapAlign: 'start',
441      });
442      scrollArea.appendChild(tag);
443    }
444    banner.appendChild(scrollArea);
445 
446    // Controls area (only in standalone mode, not extension)
447    if (!EXTENSION_MODE) {
448      const controls = document.createElement('div');
449      Object.assign(controls.style, {
450        display: 'flex', alignItems: 'center', gap: '2px',
451        padding: '0 8px', flexShrink: '0',
452      });
453 
454      // Toggle visibility button
455      const toggle = document.createElement('button');
456      toggle.textContent = '\u25C9'; // circle with dot (visible state)
457      toggle.title = 'Toggle overlay visibility';
458      Object.assign(toggle.style, {
459        background: 'none', border: 'none',
460        color: 'white', fontSize: '16px', cursor: 'pointer', padding: '0 4px',
461        opacity: '0.85', transition: 'opacity 0.15s',
462      });
463      let overlaysVisible = true;
464      toggle.addEventListener('click', () => {
465        overlaysVisible = !overlaysVisible;
466        document.body.classList.toggle('impeccable-hidden', !overlaysVisible);
467        toggle.textContent = overlaysVisible ? '\u25C9' : '\u25CB'; // filled vs empty circle
468        toggle.style.opacity = overlaysVisible ? '0.85' : '0.5';
469      });
470      controls.appendChild(toggle);
471 
472      // Close button
473      const close = document.createElement('button');
474      close.textContent = '\u00d7';
475      close.title = 'Dismiss banner';
476      Object.assign(close.style, {
477        background: 'none', border: 'none',
478        color: 'white', fontSize: '18px', cursor: 'pointer', padding: '0 4px',
479      });
480      close.addEventListener('click', () => banner.remove());
481      controls.appendChild(close);
482 
483      banner.appendChild(controls);
484    }
485    document.body.appendChild(banner);
486    overlays.push(banner);
487  };
488 
489  // Heuristic for skipping CSS-in-JS hashed class names like "css-1a2b3c" or "_2x4hG_".
490  // These change between builds and produce brittle, ugly selectors.
491  function isLikelyHashedClass(c) {
492    if (!c) return true;
493    if (/^(css|sc|emotion|jsx|module)-[\w-]{4,}$/i.test(c)) return true;
494    if (/^_[\w-]{5,}$/.test(c)) return true;
495    if (/^[a-z0-9]{6,}$/i.test(c) && /\d/.test(c)) return true;
496    return false;
497  }
498 
499  function buildSelectorSegment(el) {
500    const tag = el.tagName.toLowerCase();
501    let sel = tag;
502 
503    if (el.classList && el.classList.length > 0) {
504      const classes = [...el.classList]
505        .filter(c => !c.startsWith('impeccable-') && !isLikelyHashedClass(c))
506        .slice(0, 2);
507      if (classes.length > 0) {
508        sel += '.' + classes.map(c => CSS.escape(c)).join('.');
509      }
510    }
511 
512    // Disambiguate among siblings only if the parent has multiple matches
513    const parent = el.parentElement;
514    if (parent) {
515      try {
516        const matching = parent.querySelectorAll(':scope > ' + sel);
517        if (matching.length > 1) {
518          const sameType = [...parent.children].filter(c => c.tagName === el.tagName);
519          const idx = sameType.indexOf(el) + 1;
520          sel += `:nth-of-type(${idx})`;
521        }
522      } catch {
523        const idx = [...parent.children].indexOf(el) + 1;
524        sel = `${tag}:nth-child(${idx})`;
525      }
526    }
527    return sel;
528  }
529 
530  function generateSelector(el) {
531    if (el === document.body) return 'body';
532    if (el === document.documentElement) return 'html';
533    if (el.id) return '#' + CSS.escape(el.id);
534 
535    const parts = [];
536    let current = el;
537    let depth = 0;
538    const MAX_DEPTH = 10;
539 
540    while (current && current !== document.body && current !== document.documentElement && depth < MAX_DEPTH) {
541      parts.unshift(buildSelectorSegment(current));
542 
543      // Anchor on an ancestor's ID and stop walking up
544      if (current.id) {
545        parts[0] = '#' + CSS.escape(current.id);
546        break;
547      }
548 
549      // Stop as soon as the partial selector uniquely identifies the target
550      const trySelector = parts.join(' > ');
551      try {
552        const matches = document.querySelectorAll(trySelector);
553        if (matches.length === 1 && matches[0] === el) {
554          return trySelector;
555        }
556      } catch { /* invalid selector — keep walking */ }
557 
558      current = current.parentElement;
559      depth++;
560    }
561 
562    return parts.join(' > ');
563  }
564 
565  function getDirectText(el) {
566    return [...el.childNodes]
567      .filter(n => n.nodeType === 3)
568      .map(n => n.textContent || '')
569      .join('');
570  }
571 
572  function getDirectTextRect(el) {
573    const rects = [];
574    for (const node of el.childNodes) {
575      if (node.nodeType !== 3 || !(node.textContent || '').trim()) continue;
576      const range = document.createRange();
577      range.selectNodeContents(node);
578      for (const rect of range.getClientRects()) {
579        if (rect.width >= 1 && rect.height >= 1) rects.push(rect);
580      }
581      range.detach?.();
582    }
583    if (rects.length === 0) return null;
584    const left = Math.min(...rects.map(r => r.left));
585    const top = Math.min(...rects.map(r => r.top));
586    const right = Math.max(...rects.map(r => r.right));
587    const bottom = Math.max(...rects.map(r => r.bottom));
588    return {
589      left,
590      top,
591      right,
592      bottom,
593      width: right - left,
594      height: bottom - top,
595      x: left,
596      y: top,
597    };
598  }
599 
600  function collectVisualContrastReasons(el, style) {
601    const reasons = new Set();
602    const bgClip = style.webkitBackgroundClip || style.backgroundClip || '';
603    const ownBgImage = style.backgroundImage || '';
604    if (bgClip === 'text' && ownBgImage && ownBgImage !== 'none') {
605      reasons.add('background-clip text');
606    }
607    if (style.textShadow && style.textShadow !== 'none') reasons.add('text shadow');
608 
609    let current = el;
610    while (current && current.nodeType === 1) {
611      const tag = current.tagName?.toLowerCase();
612      const currentStyle = getComputedStyle(current);
613      const bgImage = currentStyle.backgroundImage || '';
614      const isDocumentSurface = tag === 'body' || tag === 'html';
615 
616      if (!isDocumentSurface && bgImage && bgImage !== 'none') {
617        if (/url\s*\(/i.test(bgImage)) reasons.add('image background');
618        if (/gradient/i.test(bgImage)) reasons.add('gradient background');
619      }
620      if (parseFloat(currentStyle.opacity) < 0.99) reasons.add('opacity stack');
621      if (currentStyle.mixBlendMode && currentStyle.mixBlendMode !== 'normal') reasons.add('blend mode');
622      if (currentStyle.filter && currentStyle.filter !== 'none') reasons.add('filter');
623      if (currentStyle.backdropFilter && currentStyle.backdropFilter !== 'none') reasons.add('backdrop filter');
624 
625      const solidBg = parseRgb(currentStyle.backgroundColor);
626      if (solidBg && solidBg.a >= 0.95 && (!bgImage || bgImage === 'none')) break;
627      current = current.parentElement;
628    }
629 
630    const sampleRect = getDirectTextRect(el) || el.getBoundingClientRect();
631    if (sampleRect && document.elementsFromPoint) {
632      const points = [
633        [sampleRect.left + sampleRect.width / 2, sampleRect.top + sampleRect.height / 2],
634        [sampleRect.left + Math.min(sampleRect.width - 1, Math.max(1, sampleRect.width * 0.25)), sampleRect.top + sampleRect.height / 2],
635        [sampleRect.left + Math.min(sampleRect.width - 1, Math.max(1, sampleRect.width * 0.75)), sampleRect.top + sampleRect.height / 2],
636      ];
637      for (const [x, y] of points) {
638        if (x < 0 || y < 0 || x > window.innerWidth || y > window.innerHeight) continue;
639        const stack = document.elementsFromPoint(x, y);
640        const selfIndex = stack.findIndex(node => node === el || el.contains(node) || node.contains?.(el));
641        if (selfIndex < 0) continue;
642        for (const node of stack.slice(selfIndex + 1)) {
643          const nodeTag = node.tagName?.toLowerCase();
644          if (nodeTag === 'img' || nodeTag === 'picture' || nodeTag === 'video' || nodeTag === 'canvas' || nodeTag === 'svg') {
645            reasons.add(`${nodeTag} underlay`);
646            break;
647          }
648        }
649      }
650    }
651 
652    return [...reasons];
653  }
654 
655  function collectVisualContrastCandidates(options = {}) {
656    const maxCandidates = Number.isFinite(options.maxCandidates) ? options.maxCandidates : 12;
657    const candidates = [];
658    for (const el of document.querySelectorAll('*')) {
659      if (candidates.length >= maxCandidates) break;
660      if (el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
661      if (el.closest('[id^="impeccable-live-"]')) continue;
662      if (el === document.body || el === document.documentElement) continue;
663      if (!isRenderedForBrowserRule(el)) continue;
664 
665      const tag = el.tagName.toLowerCase();
666      const style = getComputedStyle(el);
667      if (style.display === 'none' || style.visibility === 'hidden') continue;
668      const directText = getDirectText(el);
669      const hasDirectText = directText.trim().length > 0;
670      if (!hasDirectText || isEmojiOnlyText(directText)) continue;
671 
672      const bgColor = readOwnBackgroundColor(el, style);
673      const isStyledButton = (tag === 'a' || tag === 'button')
674        && bgColor && bgColor.a > 0.5;
675      if (SAFE_TAGS.has(tag) && !isStyledButton) continue;
676 
677      const rect = getDirectTextRect(el) || el.getBoundingClientRect();
678      if (!rect || rect.width < 4 || rect.height < 4) continue;
679 
680      const reasons = collectVisualContrastReasons(el, style);
681      if (reasons.length === 0) continue;
682 
683      const textColor = parseRgb(style.color);
684      const fontSize = parseFloat(style.fontSize) || 16;
685      const fontWeight = parseInt(style.fontWeight) || 400;
686      const isLargeText = fontSize >= WCAG_LARGE_TEXT_PX || (fontSize >= WCAG_LARGE_BOLD_TEXT_PX && fontWeight >= 700);
687      const threshold = isLargeText ? 3.0 : 4.5;
688      const clip = {
689        x: Math.max(0, Math.floor(rect.left + window.scrollX - 2)),
690        y: Math.max(0, Math.floor(rect.top + window.scrollY - 2)),
691        width: Math.max(1, Math.ceil(rect.width + 4)),
692        height: Math.max(1, Math.ceil(rect.height + 4)),
693      };
694 
695      candidates.push({
696        selector: generateSelector(el),
697        tagName: tag,
698        text: directText.trim().replace(/\s+/g, ' ').slice(0, 80),
699        threshold,
700        reasons,
701        clip,
702        textColor,
703        preferRenderedForeground: !textColor || textColor.a < 0.99 || reasons.some(reason =>
704          reason === 'opacity stack' ||
705          reason === 'blend mode' ||
706          reason === 'filter' ||
707          reason === 'backdrop filter' ||
708          reason === 'background-clip text'
709        ),
710        backgroundClipText: reasons.includes('background-clip text'),
711      });
712    }
713    return candidates;
714  }
715 
716  const visualContrastImageCache = new Map();
717  const visualContrastRasterCache = new WeakMap();
718 
719  function clampByte(value) {
720    return Math.max(0, Math.min(255, Math.round(value)));
721  }
722 
723  function blendRgba(fg, bg) {
724    if (!fg) return bg || null;
725    if (!bg || fg.a == null || fg.a >= 0.999) {
726      return { r: clampByte(fg.r), g: clampByte(fg.g), b: clampByte(fg.b), a: fg.a == null ? 1 : fg.a };
727    }
728    const alpha = Math.max(0, Math.min(1, fg.a));
729    return {
730      r: clampByte(fg.r * alpha + bg.r * (1 - alpha)),
731      g: clampByte(fg.g * alpha + bg.g * (1 - alpha)),
732      b: clampByte(fg.b * alpha + bg.b * (1 - alpha)),
733      a: 1,
734    };
735  }
736 
737  function pickWorstContrastColor(textColor, colors) {
738    const usable = (colors || []).filter(Boolean);
739    if (!usable.length) return null;
740    let worst = usable[0];
741    let worstRatio = contrastRatio(textColor, worst);
742    for (const color of usable.slice(1)) {
743      const ratio = contrastRatio(textColor, color);
744      if (ratio < worstRatio) {
745        worst = color;
746        worstRatio = ratio;
747      }
748    }
749    return worst;
750  }
751 
752  function firstCssUrl(value) {
753    const match = String(value || '').match(/url\((?:"([^"]+)"|'([^']+)'|([^)]*))\)/i);
754    if (!match) return '';
755    return (match[1] || match[2] || match[3] || '').trim();
756  }
757 
758  function getLayerValue(value, index = 0) {
759    return String(value || '').split(',')[index]?.trim() || '';
760  }
761 
762  function parsePositionToken(token, container, painted) {
763    if (!token || token === 'center') return (container - painted) / 2;
764    if (token === 'left' || token === 'top') return 0;
765    if (token === 'right' || token === 'bottom') return container - painted;
766    if (/%$/.test(token)) {
767      const pct = parseFloat(token) / 100;
768      return (container - painted) * pct;
769    }
770    if (/px$/.test(token)) return parseFloat(token) || 0;
771    return (container - painted) / 2;
772  }
773 
774  function parsePositionPair(positionValue) {
775    const tokens = String(positionValue || '50% 50%').trim().split(/\s+/).filter(Boolean);
776    const first = tokens[0] || '50%';
777    if (tokens.length < 2) {
778      if (first === 'top' || first === 'bottom') return ['50%', first];
779      return [first, '50%'];
780    }
781    return [first, tokens[1] || '50%'];
782  }
783 
784  function resolvePaintedImageRect(containerRect, image, sizeValue, positionValue) {
785    const intrinsicWidth = image.naturalWidth || image.videoWidth || image.width || 1;
786    const intrinsicHeight = image.naturalHeight || image.videoHeight || image.height || 1;
787    let paintedWidth = intrinsicWidth;
788    let paintedHeight = intrinsicHeight;
789    const size = String(sizeValue || 'auto').trim();
790 
791    if (size === 'cover' || size === 'contain') {
792      const scale = size === 'cover'
793        ? Math.max(containerRect.width / intrinsicWidth, containerRect.height / intrinsicHeight)
794        : Math.min(containerRect.width / intrinsicWidth, containerRect.height / intrinsicHeight);
795      paintedWidth = intrinsicWidth * scale;
796      paintedHeight = intrinsicHeight * scale;
797    } else if (size && size !== 'auto') {
798      const parts = size.split(/\s+/);
799      const widthToken = parts[0];
800      const heightToken = parts[1] || 'auto';
801      if (/%$/.test(widthToken)) paintedWidth = containerRect.width * (parseFloat(widthToken) / 100);
802      else if (/px$/.test(widthToken)) paintedWidth = parseFloat(widthToken) || paintedWidth;
803      if (heightToken === 'auto') paintedHeight = paintedWidth * (intrinsicHeight / intrinsicWidth);
804      else if (/%$/.test(heightToken)) paintedHeight = containerRect.height * (parseFloat(heightToken) / 100);
805      else if (/px$/.test(heightToken)) paintedHeight = parseFloat(heightToken) || paintedHeight;
806    }
807 
808    const [xToken, yToken] = parsePositionPair(positionValue);
809    const positionX = parsePositionToken(xToken, containerRect.width, paintedWidth);
810    const positionY = parsePositionToken(yToken, containerRect.height, paintedHeight);
811    return {
812      left: containerRect.left + positionX,
813      top: containerRect.top + positionY,
814      width: paintedWidth,
815      height: paintedHeight,
816      intrinsicWidth,
817      intrinsicHeight,
818    };
819  }
820 
821  function parseObjectPosition(positionValue) {
822    return parsePositionPair(positionValue);
823  }
824 
825  function resolveObjectImageRect(containerRect, image, style) {
826    const intrinsicWidth = image.naturalWidth || image.videoWidth || image.width || 1;
827    const intrinsicHeight = image.naturalHeight || image.videoHeight || image.height || 1;
828    const fit = style.objectFit || 'fill';
829    let paintedWidth = containerRect.width;
830    let paintedHeight = containerRect.height;
831    if (fit === 'contain' || fit === 'cover') {
832      const scale = fit === 'cover'
833        ? Math.max(containerRect.width / intrinsicWidth, containerRect.height / intrinsicHeight)
834        : Math.min(containerRect.width / intrinsicWidth, containerRect.height / intrinsicHeight);
835      paintedWidth = intrinsicWidth * scale;
836      paintedHeight = intrinsicHeight * scale;
837    } else if (fit === 'none') {
838      paintedWidth = intrinsicWidth;
839      paintedHeight = intrinsicHeight;
840    } else if (fit === 'scale-down') {
841      const containScale = Math.min(containerRect.width / intrinsicWidth, containerRect.height / intrinsicHeight, 1);
842      paintedWidth = intrinsicWidth * containScale;
843      paintedHeight = intrinsicHeight * containScale;
844    }
845    const [xToken, yToken] = parseObjectPosition(style.objectPosition);
846    return {
847      left: containerRect.left + parsePositionToken(xToken, containerRect.width, paintedWidth),
848      top: containerRect.top + parsePositionToken(yToken, containerRect.height, paintedHeight),
849      width: paintedWidth,
850      height: paintedHeight,
851      intrinsicWidth,
852      intrinsicHeight,
853    };
854  }
855 
856  function pointToImageSource(point, paintedRect) {
857    if (
858      point.x < paintedRect.left ||
859      point.y < paintedRect.top ||
860      point.x > paintedRect.left + paintedRect.width ||
861      point.y > paintedRect.top + paintedRect.height
862    ) {
863      return null;
864    }
865    return {
866      x: Math.max(0, Math.min(paintedRect.intrinsicWidth - 1, ((point.x - paintedRect.left) / paintedRect.width) * paintedRect.intrinsicWidth)),
867      y: Math.max(0, Math.min(paintedRect.intrinsicHeight - 1, ((point.y - paintedRect.top) / paintedRect.height) * paintedRect.intrinsicHeight)),
868    };
869  }
870 
871  async function loadVisualContrastImage(src) {
872    if (!src) return null;
873    if (visualContrastImageCache.has(src)) return visualContrastImageCache.get(src);
874    const promise = new Promise(resolve => {
875      const img = new Image();
876      let settled = false;
877      const finish = value => {
878        if (settled) return;
879        settled = true;
880        clearTimeout(timer);
881        resolve(value);
882      };
883      const timer = setTimeout(() => finish(null), 800);
884      try {
885        const absolute = new URL(src, location.href);
886        if (absolute.origin !== location.origin && absolute.protocol !== 'data:' && absolute.protocol !== 'blob:') {
887          img.crossOrigin = 'anonymous';
888        }
889      } catch {
890        // Let the browser resolve unusual URLs itself.
891      }
892      img.onload = () => finish(img);
893      img.onerror = () => finish(null);
894      img.src = src;
895    });
896    visualContrastImageCache.set(src, promise);
897    return promise;
898  }
899 
900  function sampleDrawablePixel(drawable, sourcePoint) {
901    if (visualContrastRasterCache.has(drawable)) {
902      const cached = visualContrastRasterCache.get(drawable);
903      if (!cached || !cached.ctx) return { status: 'unresolved', reason: cached?.reason || 'image sample failed' };
904      try {
905        const x = Math.max(0, Math.min(cached.width - 1, Math.floor(sourcePoint.x * cached.scaleX)));
906        const y = Math.max(0, Math.min(cached.height - 1, Math.floor(sourcePoint.y * cached.scaleY)));
907        const data = cached.ctx.getImageData(x, y, 1, 1).data;
908        return {
909          status: 'sampled',
910          color: { r: data[0], g: data[1], b: data[2], a: data[3] / 255 },
911        };
912      } catch (err) {
913        return {
914          status: 'unresolved',
915          reason: /taint|cross-origin|Security/i.test(err?.message || '') ? 'tainted image' : 'image sample failed',
916        };
917      }
918    }
919 
920    const canvas = document.createElement('canvas');
921    const intrinsicWidth = drawable.naturalWidth || drawable.videoWidth || drawable.width || 1;
922    const intrinsicHeight = drawable.naturalHeight || drawable.videoHeight || drawable.height || 1;
923    const maxRasterSide = 640;
924    const scale = Math.min(1, maxRasterSide / Math.max(intrinsicWidth, intrinsicHeight));
925    canvas.width = Math.max(1, Math.round(intrinsicWidth * scale));
926    canvas.height = Math.max(1, Math.round(intrinsicHeight * scale));
927    const ctx = canvas.getContext('2d', { willReadFrequently: true });
928    if (!ctx) return { status: 'unresolved', reason: 'canvas unavailable' };
929    try {
930      ctx.drawImage(drawable, 0, 0, canvas.width, canvas.height);
931      const cached = {
932        ctx,
933        width: canvas.width,
934        height: canvas.height,
935        scaleX: canvas.width / intrinsicWidth,
936        scaleY: canvas.height / intrinsicHeight,
937      };
938      visualContrastRasterCache.set(drawable, cached);
939      const x = Math.max(0, Math.min(cached.width - 1, Math.floor(sourcePoint.x * cached.scaleX)));
940      const y = Math.max(0, Math.min(cached.height - 1, Math.floor(sourcePoint.y * cached.scaleY)));
941      const data = ctx.getImageData(x, y, 1, 1).data;
942      return {
943        status: 'sampled',
944        color: { r: data[0], g: data[1], b: data[2], a: data[3] / 255 },
945      };
946    } catch (err) {
947      const reason = /taint|cross-origin|Security/i.test(err?.message || '') ? 'tainted image' : 'image sample failed';
948      visualContrastRasterCache.set(drawable, { ctx: null, reason });
949      return {
950        status: 'unresolved',
951        reason,
952      };
953    }
954  }
955 
956  async function sampleCssBackground(el, style, point, textColor) {
957    const rect = el.getBoundingClientRect();
958    const bgImage = style.backgroundImage || '';
959    if (bgImage && bgImage !== 'none') {
960      if (/gradient/i.test(bgImage)) {
961        const color = pickWorstContrastColor(textColor, parseGradientColors(bgImage));
962        if (color) return { status: 'sampled', color, method: 'analytic-gradient' };
963      }
964      if (/url\s*\(/i.test(bgImage)) {
965        const img = await loadVisualContrastImage(firstCssUrl(bgImage));
966        if (!img) return { status: 'unresolved', reason: 'image unavailable' };
967        const paintedRect = resolvePaintedImageRect(
968          rect,
969          img,
970          getLayerValue(style.backgroundSize) || 'auto',
971          getLayerValue(style.backgroundPosition) || '50% 50%',
972        );
973        const sourcePoint = pointToImageSource(point, paintedRect);
974        if (!sourcePoint) return { status: 'unresolved', reason: 'point outside background image' };
975        const sample = sampleDrawablePixel(img, sourcePoint);
976        if (sample.status === 'sampled') return { ...sample, method: 'canvas-background-image' };
977        return sample;
978      }
979    }
980    const bg = parseRgb(style.backgroundColor);
981    if (bg && bg.a > 0.05) return { status: 'sampled', color: bg, method: 'solid-background' };
982    return { status: 'unresolved', reason: 'no readable background' };
983  }
984 
985  async function sampleImageElement(img, point) {
986    const rect = img.getBoundingClientRect();
987    const style = getComputedStyle(img);
988    const paintedRect = resolveObjectImageRect(rect, img, style);
989    const sourcePoint = pointToImageSource(point, paintedRect);
990    if (!sourcePoint) return { status: 'unresolved', reason: 'point outside image' };
991    const sample = sampleDrawablePixel(img, sourcePoint);
992    if (sample.status === 'sampled') return { ...sample, method: 'canvas-img-underlay' };
993 
994    if (img.currentSrc || img.src) {
995      const loaded = await loadVisualContrastImage(img.currentSrc || img.src);
996      if (loaded) {
997        const loadedRect = { ...paintedRect, intrinsicWidth: loaded.naturalWidth || loaded.width || paintedRect.intrinsicWidth, intrinsicHeight: loaded.naturalHeight || loaded.height || paintedRect.intrinsicHeight };
998        const loadedPoint = pointToImageSource(point, loadedRect);
999        if (loadedPoint) {
1000          const loadedSample = sampleDrawablePixel(loaded, loadedPoint);
1001          if (loadedSample.status === 'sampled') return { ...loadedSample, method: 'canvas-img-underlay' };
1002        }
1003      }
1004    }
1005    return sample;
1006  }
1007 
1008  function textSamplePoints(rect) {
1009    const insetX = Math.min(12, Math.max(1, rect.width * 0.12));
1010    const insetY = Math.min(8, Math.max(1, rect.height * 0.22));
1011    const xs = rect.width < 28
1012      ? [rect.left + rect.width / 2]
1013      : [rect.left + insetX, rect.left + rect.width / 2, rect.right - insetX];
1014    const ys = rect.height < 22
1015      ? [rect.top + rect.height / 2]
1016      : [rect.top + insetY, rect.top + rect.height / 2, rect.bottom - insetY];
1017    const points = [];
1018    for (const y of ys) {
1019      for (const x of xs) {
1020        if (x >= 0 && y >= 0 && x <= window.innerWidth && y <= window.innerHeight) points.push({ x, y });
1021      }
1022    }
1023    return points;
1024  }
1025 
1026  async function sampleVisualBackgroundAtPoint(el, point, textColor, depth = 0) {
1027    if (depth > 8) {
1028      return { status: 'unresolved', reason: 'background stack too deep' };
1029    }
1030    const stack = typeof document.elementsFromPoint === 'function'
1031      ? document.elementsFromPoint(point.x, point.y)
1032      : [];
1033    const selfIndex = stack.findIndex(node => node === el || el.contains(node));
1034    const nodes = selfIndex >= 0 ? stack.slice(selfIndex) : [el, ...stack];
1035    const unresolved = [];
1036 
1037    for (const node of nodes) {
1038      if (!node || node.nodeType !== 1) continue;
1039      if (node.closest?.('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
1040      const tag = node.tagName?.toLowerCase();
1041      if (tag === 'img') {
1042        const sample = await sampleImageElement(node, point);
1043        if (sample.status === 'sampled') return sample;
1044        unresolved.push(sample.reason);
1045        continue;
1046      }
1047      if (tag === 'canvas' || tag === 'video') {
1048        const rect = node.getBoundingClientRect();
1049        const sourcePoint = pointToImageSource(point, {
1050          left: rect.left,
1051          top: rect.top,
1052          width: rect.width,
1053          height: rect.height,
1054          intrinsicWidth: node.width || node.videoWidth || rect.width,
1055          intrinsicHeight: node.height || node.videoHeight || rect.height,
1056        });
1057        if (sourcePoint) {
1058          const sample = sampleDrawablePixel(node, sourcePoint);
1059          if (sample.status === 'sampled') return { ...sample, method: `canvas-${tag}-underlay` };
1060          unresolved.push(sample.reason);
1061        }
1062        continue;
1063      }
1064      const style = getComputedStyle(node);
1065      const sample = await sampleCssBackground(node, style, point, textColor);
1066      if (sample.status === 'sampled') {
1067        if (!sample.color || sample.color.a == null || sample.color.a >= 0.95) return sample;
1068        const under = await sampleVisualBackgroundAtPoint(node.parentElement || document.body, point, textColor, depth + 1);
1069        if (under.status === 'sampled') {
1070          return {
1071            status: 'sampled',
1072            color: blendRgba(sample.color, under.color),
1073            method: `${sample.method}+alpha`,
1074          };
1075        }
1076        return sample;
1077      }
1078      unresolved.push(sample.reason);
1079    }
1080 
1081    return {
1082      status: 'unresolved',
1083      reason: [...new Set(unresolved.filter(Boolean))].slice(0, 3).join(', ') || 'no readable visual background',
1084    };
1085  }
1086 
1087  async function analyzeVisualContrastCandidate(candidate) {
1088    let el;
1089    try {
1090      el = document.querySelector(candidate.selector);
1091    } catch {
1092      return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'stale selector' };
1093    }
1094    if (!el) return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'missing element' };
1095    if (!isRenderedForBrowserRule(el)) return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'hidden element' };
1096 
1097    const blockingReason = (candidate.reasons || []).find(reason =>
1098      reason === 'background-clip text' ||
1099      reason === 'blend mode' ||
1100      reason === 'filter' ||
1101      reason === 'backdrop filter' ||
1102      reason === 'opacity stack' ||
1103      reason === 'text shadow'
1104    );
1105    if (blockingReason) {
1106      return { ...candidate, status: 'unresolved', confidence: 'none', reason: `${blockingReason} needs screenshot pixels` };
1107    }
1108 
1109    const style = getComputedStyle(el);
1110    const textColor = parseRgb(style.color) || candidate.textColor;
1111    if (!textColor) return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'unreadable text color' };
1112 
1113    const rect = getDirectTextRect(el) || el.getBoundingClientRect();
1114    if (!rect || rect.width < 4 || rect.height < 4) {
1115      return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'missing text rect' };
1116    }
1117 
1118    const points = textSamplePoints(rect);
1119    if (points.length === 0) {
1120      return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'text outside viewport' };
1121    }
1122 
1123    const ratios = [];
1124    const methods = new Set();
1125    const unresolved = [];
1126    for (const point of points) {
1127      const sample = await sampleVisualBackgroundAtPoint(el, point, textColor);
1128      if (sample.status !== 'sampled' || !sample.color) {
1129        unresolved.push(sample.reason);
1130        continue;
1131      }
1132      const fg = blendRgba(textColor, sample.color);
1133      ratios.push(contrastRatio(fg, sample.color));
1134      if (sample.method) methods.add(sample.method);
1135    }
1136 
1137    if (ratios.length < Math.min(3, points.length)) {
1138      return {
1139        ...candidate,
1140        status: 'unresolved',
1141        confidence: 'none',
1142        samples: ratios.length,
1143        reason: [...new Set(unresolved.filter(Boolean))].slice(0, 3).join(', ') || 'not enough readable samples',
1144      };
1145    }
1146 
1147    ratios.sort((a, b) => a - b);
1148    const pick = pct => ratios[Math.min(ratios.length - 1, Math.max(0, Math.floor((pct / 100) * ratios.length)))];
1149    const measuredRatio = pick(10);
1150    const medianRatio = pick(50);
1151    const status = measuredRatio < candidate.threshold ? 'fail' : 'pass';
1152    const method = [...methods].sort().join(', ') || 'browser-visual';
1153    const textLabel = candidate.text ? ` "${candidate.text}"` : '';
1154    const detail = `browser contrast ${measuredRatio.toFixed(1)}:1 median ${medianRatio.toFixed(1)}:1 (need ${candidate.threshold}:1) via ${method}${textLabel}`;
1155    return {
1156      ...candidate,
1157      status,
1158      confidence: method.includes('canvas-') ? 'high' : 'medium',
1159      method,
1160      ratio: measuredRatio,
1161      medianRatio,
1162      samples: ratios.length,
1163      finding: status === 'fail' ? { id: 'low-contrast', snippet: detail } : null,
1164    };
1165  }
1166 
1167  function waitForVisualPaint() {
1168    return new Promise(resolve => {
1169      requestAnimationFrame(() => requestAnimationFrame(resolve));
1170    });
1171  }
1172 
1173  async function analyzeVisualContrast(options = {}) {
1174    const candidates = collectVisualContrastCandidates(options);
1175    const results = [];
1176    const shouldScrollOffscreen = options.scrollOffscreen === true;
1177    const restoreScroll = { x: window.scrollX, y: window.scrollY };
1178    for (const candidate of candidates) {
1179      if (shouldScrollOffscreen && (window.scrollX !== restoreScroll.x || window.scrollY !== restoreScroll.y)) {
1180        window.scrollTo(restoreScroll.x, restoreScroll.y);
1181        await waitForVisualPaint();
1182      }
1183      let result = await analyzeVisualContrastCandidate(candidate);
1184      if (shouldScrollOffscreen && result.status === 'unresolved' && result.reason === 'text outside viewport') {
1185        let el = null;
1186        try {
1187          el = document.querySelector(candidate.selector);
1188        } catch {
1189          el = null;
1190        }
1191        if (el && typeof el.scrollIntoView === 'function') {
1192          el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'instant' });
1193          await waitForVisualPaint();
1194          result = await analyzeVisualContrastCandidate(candidate);
1195        }
1196      }
1197      results.push(result);
1198    }
1199    if (shouldScrollOffscreen && (window.scrollX !== restoreScroll.x || window.scrollY !== restoreScroll.y)) {
1200      window.scrollTo(restoreScroll.x, restoreScroll.y);
1201    }
1202    return results;
1203  }
1204 
1205  function isElementHidden(el) {
1206    if (!el || el === document.body || el === document.documentElement) return false;
1207    if (typeof el.checkVisibility === 'function') return !el.checkVisibility({ checkOpacity: false, checkVisibilityCSS: true });
1208    // Fallback: zero size or no offsetParent (covers display:none and detached subtrees)
1209    return el.offsetWidth === 0 && el.offsetHeight === 0;
1210  }
1211 
1212  function serializeFindings(allFindings) {
1213    return allFindings.map(({ el, findings }) => ({
1214      selector: generateSelector(el),
1215      tagName: el.tagName?.toLowerCase() || 'unknown',
1216      rect: (el !== document.body && el !== document.documentElement && el.getBoundingClientRect)
1217        ? el.getBoundingClientRect().toJSON() : null,
1218      isPageLevel: el === document.body || el === document.documentElement,
1219      isHidden: isElementHidden(el),
1220      findings: findings.map(f => {
1221        const ap = ANTIPATTERNS.find(a => a.id === (f.type || f.id));
1222        return {
1223          type: f.type || f.id,
1224          category: ap ? ap.category : 'quality',
1225          severity: ap?.severity || 'warning',
1226          detail: f.detail || f.snippet,
1227          ignoreValue: f.ignoreValue || f.value || '',
1228          name: ap ? ap.name : (f.type || f.id),
1229          description: ap ? ap.description : '',
1230        };
1231      }),
1232    }));
1233  }
1234 
1235  const printSummary = function(allFindings) {
1236    if (allFindings.length === 0) {
1237      console.log('%c[impeccable] No anti-patterns found.', 'color: #22c55e; font-weight: bold');
1238      return;
1239    }
1240    console.group(
1241      `%c[impeccable] ${allFindings.length} anti-pattern${allFindings.length === 1 ? '' : 's'} found`,
1242      'color: oklch(84% 0.19 80.46); font-weight: bold'
1243    );
1244    for (const { el, findings } of allFindings) {
1245      for (const f of findings) {
1246        console.log(`%c${f.type || f.id}%c ${f.detail || f.snippet}`,
1247          'color: oklch(84% 0.19 80.46); font-weight: bold', 'color: inherit', el);
1248      }
1249    }
1250    console.groupEnd();
1251  };
1252 
1253  function addBrowserFindings(groupMap, el, findings) {
1254    if (!findings || findings.length === 0) return;
1255    const existing = groupMap.get(el);
1256    if (existing) existing.push(...findings);
1257    else groupMap.set(el, [...findings]);
1258  }
1259 
1260  function browserFindingsFromMap(groupMap) {
1261    return [...groupMap.entries()].map(([el, findings]) => ({ el, findings }));
1262  }
1263 
1264  const DESIGN_COLOR_TOLERANCE = 6;
1265  const DESIGN_RADIUS_TOLERANCE_PX = 0.5;
1266  const DESIGN_SKIP_TAGS = new Set(['head', 'title', 'meta', 'link', 'style', 'script', 'noscript', 'template', 'source']);
1267 
1268  function normalizeBrowserFontName(value) {
1269    return String(value || '')
1270      .trim()
1271      .replace(/^["']|["']$/g, '')
1272      .replace(/\+/g, ' ')
1273      .replace(/\s+/g, ' ')
1274      .toLowerCase();
1275  }
1276 
1277  function browserPrimaryFont(stack) {
1278    if (!stack || /var\(/i.test(stack)) return '';
1279    return String(stack || '')
1280      .split(',')
1281      .map(normalizeBrowserFontName)
1282      .find(font => font && !GENERIC_FONTS.has(font)) || '';
1283  }
1284 
1285  function browserDesignSystemConfig() {
1286    const raw = window.__IMPECCABLE_CONFIG__?.designSystem;
1287    if (!raw?.present) return null;
1288    const allowedFonts = new Set((raw.allowedFonts || []).map(normalizeBrowserFontName).filter(Boolean));
1289    const allowedColors = (raw.allowedColors || [])
1290      .filter(color => color && Number.isFinite(color.r) && Number.isFinite(color.g) && Number.isFinite(color.b))
1291      .map(color => ({ r: color.r, g: color.g, b: color.b }));
1292    const allowedRadii = (raw.allowedRadii || [])
1293      .map(Number)
1294      .filter(px => Number.isFinite(px));
1295    return {
1296      present: true,
1297      hasFonts: raw.hasFonts === true && allowedFonts.size > 0,
1298      allowedFonts,
1299      hasColors: raw.hasColors === true && allowedColors.length > 0,
1300      allowedColors,
1301      hasRadii: raw.hasRadii === true && allowedRadii.length > 0,
1302      allowedRadii,
1303      hasPillRadius: raw.hasPillRadius === true,
1304    };
1305  }
1306 
1307  function browserColorsClose(a, b) {
1308    if (!a || !b) return false;
1309    return Math.max(
1310      Math.abs(a.r - b.r),
1311      Math.abs(a.g - b.g),
1312      Math.abs(a.b - b.b),
1313    ) <= DESIGN_COLOR_TOLERANCE;
1314  }
1315 
1316  function isBrowserDesignColorAllowed(raw, designSystem) {
1317    if (!designSystem?.hasColors) return true;
1318    const text = String(raw || '').trim().toLowerCase();
1319    if (!text || text === 'transparent' || text === 'currentcolor' || text === 'inherit' || text === 'initial') return true;
1320    if (text.includes('var(')) return true;
1321    const parsed = parseAnyColor(text);
1322    if (!parsed) return true;
1323    if ((parsed.a ?? 1) <= 0.05) return true;
1324    return designSystem.allowedColors.some(color => browserColorsClose(parsed, color));
1325  }
1326 
1327  function isBrowserTransparentCss(value) {
1328    const text = String(value || '').trim().toLowerCase();
1329    if (!text || text === 'transparent') return true;
1330    const parsed = parseAnyColor(text);
1331    return parsed ? (parsed.a ?? 1) <= 0.05 : false;
1332  }
1333 
1334  function isBrowserDesignRadiusAllowed(raw, designSystem) {
1335    if (!designSystem?.hasRadii) return true;
1336    const text = String(raw || '').trim().toLowerCase();
1337    if (!text || text === '0' || text === 'none' || text === 'initial' || text === 'inherit') return true;
1338    if (text.includes('var(') || text.includes('%')) return true;
1339    const px = resolveLengthPx(text, 16);
1340    if (px == null || !Number.isFinite(px) || px <= DESIGN_RADIUS_TOLERANCE_PX) return true;
1341    if (designSystem.hasPillRadius && px >= 99) return true;
1342    return designSystem.allowedRadii.some(allowed => Math.abs(allowed - px) <= DESIGN_RADIUS_TOLERANCE_PX);
1343  }
1344 
1345  function browserRadiusTokens(value) {
1346    return String(value || '')
1347      .replace(/\s*\/\s*/g, ' ')
1348      .split(/\s+/)
1349      .map(token => token.trim())
1350      .filter(Boolean);
1351  }
1352 
1353  function browserHasDirectText(el) {
1354    return [...(el.childNodes || [])].some(node => node.nodeType === 3 && node.textContent.trim().length > 0);
1355  }
1356 
1357  function browserSampleText(el) {
1358    const text = String(el.textContent || '').replace(/\s+/g, ' ').trim();
1359    return text ? ` "${text.slice(0, 40)}"` : '';
1360  }
1361 
1362  function shouldSkipDesignElement(el) {
1363    const tag = el.tagName?.toLowerCase?.() || '';
1364    return DESIGN_SKIP_TAGS.has(tag) || isElementHidden(el);
1365  }
1366 
1367  function checkElementDesignSystemDOM(el, designSystem, seen) {
1368    if (!designSystem?.present || shouldSkipDesignElement(el)) return [];
1369    const findings = [];
1370    const tag = el.tagName?.toLowerCase?.() || 'unknown';
1371    const style = getComputedStyle(el);
1372 
1373    if (designSystem.hasFonts && browserHasDirectText(el)) {
1374      const font = browserPrimaryFont(style.fontFamily || '');
1375      if (font && !designSystem.allowedFonts.has(font) && !seen.fonts.has(font)) {
1376        seen.fonts.add(font);
1377        findings.push({
1378          type: 'design-system-font',
1379          detail: `${tag}${browserSampleText(el)} uses ${font}; not declared in DESIGN.md typography`,
1380          ignoreValue: font,
1381        });
1382      }
1383    }
1384 
1385    if (designSystem.hasColors) {
1386      const colorChecks = [];
1387      if (browserHasDirectText(el)) colorChecks.push(['text color', style.color]);
1388      if (!isBrowserTransparentCss(style.backgroundColor)) colorChecks.push(['background', style.backgroundColor]);
1389      for (const side of ['Top', 'Right', 'Bottom', 'Left']) {
1390        if ((parseFloat(style[`border${side}Width`]) || 0) > 0) {
1391          colorChecks.push([`border-${side.toLowerCase()}`, style[`border${side}Color`]]);
1392        }
1393      }
1394      if ((parseFloat(style.outlineWidth) || 0) > 0) colorChecks.push(['outline', style.outlineColor]);
1395 
1396      for (const [kind, raw] of colorChecks) {
1397        const label = String(raw || '').trim().replace(/\s+/g, ' ');
1398        if (isBrowserDesignColorAllowed(label, designSystem)) continue;
1399        const key = `${kind}:${label}`;
1400        if (seen.colors.has(key)) continue;
1401        seen.colors.add(key);
1402        findings.push({
1403          type: 'design-system-color',
1404          detail: `${kind} ${label} on ${tag}${browserSampleText(el)} is outside DESIGN.md colors`,
1405          ignoreValue: label,
1406        });
1407      }
1408    }
1409 
1410    if (designSystem.hasRadii) {
1411      for (const token of browserRadiusTokens(style.borderRadius || '')) {
1412        if (isBrowserDesignRadiusAllowed(token, designSystem)) continue;
1413        if (seen.radii.has(token)) continue;
1414        seen.radii.add(token);
1415        findings.push({
1416          type: 'design-system-radius',
1417          detail: `border-radius ${token} on ${tag}${browserSampleText(el)} is outside the DESIGN.md rounded scale`,
1418          ignoreValue: token,
1419        });
1420      }
1421    }
1422 
1423    return findings;
1424  }
1425 
1426  function decodeBrowserGoogleFamily(value) {
1427    const family = String(value || '').split(':')[0].replace(/\+/g, ' ');
1428    try {
1429      return decodeURIComponent(family);
1430    } catch {
1431      return family;
1432    }
1433  }
1434 
1435  function checkBrowserDesignSystemSources(designSystem, seen) {
1436    if (!designSystem?.hasFonts) return [];
1437    const findings = [];
1438    for (const link of document.querySelectorAll('link[href*="fonts.googleapis.com/css"]')) {
1439      const href = link.getAttribute('href') || '';
1440      for (const match of href.matchAll(/[?&]family=([^&]+)/g)) {
1441        const display = decodeBrowserGoogleFamily(match[1]);
1442        const font = normalizeBrowserFontName(display);
1443        if (!font || designSystem.allowedFonts.has(font) || seen.fonts.has(font)) continue;
1444        seen.fonts.add(font);
1445        findings.push({
1446          type: 'design-system-font',
1447          detail: `Google Fonts: ${display} is not declared in DESIGN.md typography`,
1448          ignoreValue: display,
1449        });
1450      }
1451    }
1452    return findings;
1453  }
1454 
1455  function collectBrowserFindings() {
1456    const groupMap = new Map();
1457    const _disabled = EXTENSION_MODE ? (window.__IMPECCABLE_CONFIG__?.disabledRules || []) : [];
1458    const _ruleOk = (id) => !_disabled.length || !_disabled.includes(id);
1459    const designSystem = browserDesignSystemConfig();
1460    const designSeen = { fonts: new Set(), colors: new Set(), radii: new Set() };
1461    // Note: provider-gated rules (--gpt / --gemini) are NOT filtered here. In a
1462    // real browser env (detector page, live overlay, extension) running every
1463    // check is free, so we always surface them; the gating is purely a CLI
1464    // output concern, applied in the Node engines' detect* return paths.
1465 
1466    for (const el of document.querySelectorAll('*')) {
1467      // Skip impeccable's own elements and any descendants (overlays, labels, banner, nav buttons)
1468      if (el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
1469      // Skip browser extension elements (Claude, etc.)
1470      const elId = el.id || '';
1471      if (elId.startsWith('claude-') || elId.startsWith('cic-')) continue;
1472      // Skip the impeccable live-mode overlay (highlight, tooltip, bar, picker, toast).
1473      // These are inspector chrome, not part of the user's design.
1474      if (el.closest('[id^="impeccable-live-"]')) continue;
1475      // Skip html/body -- page-level findings go in the banner, not a full-page overlay
1476      if (el === document.body || el === document.documentElement) continue;
1477 
1478      const findings = [
1479        ...checkElementBordersDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1480        ...checkElementColorsDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1481        ...checkElementMotionDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1482        ...checkElementGlowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1483        ...checkElementAIPaletteDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1484        ...checkElementIconTileDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1485        ...checkElementItalicSerifDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1486        ...checkElementQualityDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1487        ...checkElementOversizedH1DOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1488        ...checkElementClippedOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1489        ...checkElementGptBorderShadowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1490        ...checkElementTextOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1491        ...checkElementDesignSystemDOM(el, designSystem, designSeen),
1492      ].filter(f => _ruleOk(f.type));
1493 
1494      addBrowserFindings(groupMap, el, findings);
1495 
1496      // Hero eyebrow: the offending element is the eyebrow above the heading,
1497      // not the heading itself — highlight the previous sibling instead.
1498      const eyebrowFindings = checkElementHeroEyebrowDOM(el)
1499        .map(f => ({ type: f.id, detail: f.snippet }))
1500        .filter(f => _ruleOk(f.type));
1501      if (eyebrowFindings.length > 0 && el.previousElementSibling) {
1502        addBrowserFindings(groupMap, el.previousElementSibling, eyebrowFindings);
1503      }
1504    }
1505 
1506    const pageLevelFindings = [];
1507 
1508    const designSourceFindings = checkBrowserDesignSystemSources(designSystem, designSeen)
1509      .filter(f => _ruleOk(f.type));
1510    if (designSourceFindings.length > 0) {
1511      pageLevelFindings.push(...designSourceFindings);
1512      addBrowserFindings(groupMap, document.body, designSourceFindings);
1513    }
1514 
1515    const typoFindings = checkTypography().filter(f => _ruleOk(f.type));
1516    if (typoFindings.length > 0) {
1517      pageLevelFindings.push(...typoFindings);
1518      addBrowserFindings(groupMap, document.body, typoFindings);
1519    }
1520 
1521    const sectionKickerFindings = checkRepeatedSectionKickersDOM()
1522      .map(f => ({ type: f.id, detail: f.snippet }))
1523      .filter(f => _ruleOk(f.type));
1524    if (sectionKickerFindings.length > 0) {
1525      pageLevelFindings.push(...sectionKickerFindings);
1526      addBrowserFindings(groupMap, document.body, sectionKickerFindings);
1527    }
1528 
1529    const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
1530    for (const f of layoutFindings) {
1531      const el = f.el || document.body;
1532      addBrowserFindings(groupMap, el, [{ type: f.type, detail: f.detail || f.snippet }]);
1533    }
1534 
1535    // Page-level quality checks (headings, etc.)
1536    const qualityFindings = checkPageQualityDOM().filter(f => _ruleOk(f.type));
1537    if (qualityFindings.length > 0) {
1538      pageLevelFindings.push(...qualityFindings);
1539      addBrowserFindings(groupMap, document.body, qualityFindings);
1540    }
1541 
1542    const creamFindings = checkCreamPalette(document)
1543      .map(f => ({ type: f.id, detail: f.snippet }))
1544      .filter(f => _ruleOk(f.type));
1545    if (creamFindings.length > 0) {
1546      pageLevelFindings.push(...creamFindings);
1547      addBrowserFindings(groupMap, document.body, creamFindings);
1548    }
1549 
1550    // Regex-on-HTML checks (shared with Node)
1551    // Clone the document and strip impeccable-live overlay nodes before the
1552    // regex scan, so the inspector's own inline styles (transitions on top/
1553    // left/width/height, etc.) don't register as page anti-patterns.
1554    const docClone = document.documentElement.cloneNode(true);
1555    for (const node of docClone.querySelectorAll('[id^="impeccable-live-"]')) {
1556      node.remove();
1557    }
1558    const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
1559    if (htmlPatternFindings.length > 0) {
1560      const mapped = htmlPatternFindings.map(f => ({ type: f.id, detail: f.snippet })).filter(f => _ruleOk(f.type));
1561      pageLevelFindings.push(...mapped);
1562      addBrowserFindings(groupMap, document.body, mapped);
1563    }
1564 
1565    return {
1566      groupMap,
1567      allFindings: browserFindingsFromMap(groupMap),
1568      pageLevelFindings,
1569    };
1570  }
1571 
1572  function shouldRunVisualContrast(options = {}) {
1573    return options.visualContrast === true || window.__IMPECCABLE_CONFIG__?.visualContrast === true;
1574  }
1575 
1576  function visualContrastOptions(options = {}) {
1577    const config = window.__IMPECCABLE_CONFIG__ || {};
1578    const scrollOffscreen = typeof options.scrollOffscreen === 'boolean'
1579      ? options.scrollOffscreen
1580      : typeof options.visualContrastScrollOffscreen === 'boolean'
1581        ? options.visualContrastScrollOffscreen
1582        : typeof config.visualContrastScrollOffscreen === 'boolean'
1583          ? config.visualContrastScrollOffscreen
1584          : false;
1585    return {
1586      ...options,
1587      maxCandidates: Number.isFinite(options.visualContrastMaxCandidates)
1588        ? options.visualContrastMaxCandidates
1589        : Number.isFinite(options.maxCandidates)
1590          ? options.maxCandidates
1591          : Number.isFinite(config.visualContrastMaxCandidates)
1592            ? config.visualContrastMaxCandidates
1593            : undefined,
1594      scrollOffscreen,
1595    };
1596  }
1597 
1598  let lastVisualContrastAnalyses = [];
1599  let lazyVisualContrastObserver = null;
1600  let lazyVisualContrastPending = new WeakMap();
1601  const lazyVisualContrastResolving = new WeakSet();
1602  let scanGeneration = 0;
1603 
1604  function rememberVisualContrastAnalysis(result) {
1605    if (!result?.selector) {
1606      lastVisualContrastAnalyses.push(result);
1607      return;
1608    }
1609    const idx = lastVisualContrastAnalyses.findIndex(item => item.selector === result.selector);
1610    if (idx >= 0) lastVisualContrastAnalyses[idx] = result;
1611    else lastVisualContrastAnalyses.push(result);
1612  }
1613 
1614  function disconnectLazyVisualContrastObserver() {
1615    if (lazyVisualContrastObserver) {
1616      lazyVisualContrastObserver.disconnect();
1617      lazyVisualContrastObserver = null;
1618    }
1619    lazyVisualContrastPending = new WeakMap();
1620  }
1621 
1622  function addVisualContrastResult(groupMap, result, options = {}) {
1623    if (result.status !== 'fail' || !result.finding || !result.selector) return false;
1624    let el = null;
1625    try {
1626      el = document.querySelector(result.selector);
1627    } catch {
1628      el = null;
1629    }
1630    if (!el) return false;
1631    const findingType = result.finding.type || result.finding.id || 'low-contrast';
1632    const existing = groupMap.get(el) || [];
1633    if (existing.some(f => (f.type || f.id) === findingType)) return false;
1634    addBrowserFindings(groupMap, el, [{
1635      type: findingType,
1636      detail: result.finding.detail || result.finding.snippet,
1637    }]);
1638    if (options.decorate && el !== document.body && el !== document.documentElement) {
1639      highlight(el, groupMap.get(el) || []);
1640    }
1641    return true;
1642  }
1643 
1644  function scanResultMeta(options = {}) {
1645    const scanId = options.scanId;
1646    if (typeof scanId !== 'string' && typeof scanId !== 'number') return {};
1647    return { scanId: String(scanId) };
1648  }
1649 
1650  function postSerializedFindings(groupMap, options = {}) {
1651    if (!EXTENSION_MODE) return;
1652    const allFindings = browserFindingsFromMap(groupMap);
1653    window.postMessage({
1654      source: 'impeccable-results',
1655      findings: serializeFindings(allFindings),
1656      count: allFindings.length,
1657      ...scanResultMeta(options),
1658    }, '*');
1659  }
1660 
1661  function postExtensionError(err) {
1662    if (!EXTENSION_MODE) return;
1663    window.postMessage({
1664      source: 'impeccable-error',
1665      message: err?.message || String(err),
1666    }, '*');
1667  }
1668 
1669  function reportVisualContrastError(err, detail = {}) {
1670    window.dispatchEvent(new CustomEvent('impeccable-visual-contrast-error', {
1671      detail: {
1672        ...detail,
1673        message: err?.message || String(err),
1674      },
1675    }));
1676    if (EXTENSION_MODE) {
1677      postExtensionError(err);
1678    } else {
1679      console.warn('[impeccable] visual contrast scan failed', err);
1680    }
1681  }
1682 
1683  function scheduleLazyVisualContrast(groupMap, analyses, options = {}, runtime = {}) {
1684    disconnectLazyVisualContrastObserver();
1685    if (options.visualContrastLazy === false || options.scrollOffscreen !== false) return;
1686    if (typeof IntersectionObserver === 'undefined') return;
1687    const unresolved = (analyses || []).filter(result =>
1688      result?.status === 'unresolved' &&
1689      result.reason === 'text outside viewport' &&
1690      result.selector
1691    );
1692    if (unresolved.length === 0) return;
1693    const generation = runtime.generation || scanGeneration;
1694 
1695    lazyVisualContrastObserver = new IntersectionObserver((entries) => {
1696      for (const entry of entries) {
1697        if (!entry.isIntersecting) continue;
1698        const el = entry.target;
1699        const candidate = lazyVisualContrastPending.get(el);
1700        if (!candidate || lazyVisualContrastResolving.has(el)) continue;
1701        lazyVisualContrastObserver?.unobserve(el);
1702        lazyVisualContrastPending.delete(el);
1703        lazyVisualContrastResolving.add(el);
1704        waitForVisualPaint()
1705          .then(() => analyzeVisualContrastCandidate(candidate))
1706          .then(result => {
1707            if (generation !== scanGeneration) return;
1708            rememberVisualContrastAnalysis(result);
1709            const added = addVisualContrastResult(groupMap, result, { decorate: true });
1710            if (added) {
1711              postSerializedFindings(groupMap, options);
1712              window.dispatchEvent(new CustomEvent('impeccable-visual-contrast-resolved', {
1713                detail: {
1714                  selector: result.selector,
1715                  status: result.status,
1716                  finding: result.finding || null,
1717                },
1718              }));
1719            }
1720          })
1721          .catch(err => {
1722            reportVisualContrastError(err, { selector: candidate.selector });
1723          })
1724          .finally(() => {
1725            lazyVisualContrastResolving.delete(el);
1726          });
1727      }
1728    }, { threshold: 0.5 });
1729 
1730    for (const candidate of unresolved) {
1731      let el = null;
1732      try {
1733        el = document.querySelector(candidate.selector);
1734      } catch {
1735        el = null;
1736      }
1737      if (!el) continue;
1738      lazyVisualContrastPending.set(el, candidate);
1739      lazyVisualContrastObserver.observe(el);
1740    }
1741  }
1742 
1743  async function addVisualContrastFindings(groupMap, options = {}, runtime = {}) {
1744    if (!shouldRunVisualContrast(options)) {
1745      lastVisualContrastAnalyses = [];
1746      disconnectLazyVisualContrastObserver();
1747      return [];
1748    }
1749    const resolvedOptions = visualContrastOptions(options);
1750    const analyses = await analyzeVisualContrast(resolvedOptions);
1751    if (runtime.generation && runtime.generation !== scanGeneration) return analyses;
1752    lastVisualContrastAnalyses = analyses;
1753    for (const result of analyses) {
1754      addVisualContrastResult(groupMap, result, { decorate: runtime.decorate });
1755    }
1756    if (runtime.decorate || runtime.scheduleLazy) scheduleLazyVisualContrast(groupMap, analyses, resolvedOptions, runtime);
1757    return analyses;
1758  }
1759 
1760  async function collectBrowserFindingsAsync(options = {}, runtime = {}) {
1761    const collected = collectBrowserFindings();
1762    await addVisualContrastFindings(collected.groupMap, options, runtime);
1763    return {
1764      ...collected,
1765      allFindings: browserFindingsFromMap(collected.groupMap),
1766      visualContrastAnalyses: lastVisualContrastAnalyses,
1767    };
1768  }
1769 
1770  function clearOverlays() {
1771    scanGeneration += 1;
1772    disconnectLazyVisualContrastObserver();
1773    for (const o of [...overlays]) detachOverlay(o);
1774    overlays.length = 0;
1775    visibilityObserver.disconnect();
1776    overlayIndex = 0;
1777  }
1778 
1779  function renderBrowserFindings(collected, options = {}) {
1780    const { allFindings, pageLevelFindings } = collected;
1781 
1782    for (const { el, findings } of allFindings) {
1783      if (el === document.body || el === document.documentElement) continue;
1784      highlight(el, findings);
1785    }
1786 
1787    if (pageLevelFindings.length > 0) {
1788      showPageBanner(pageLevelFindings);
1789    }
1790 
1791    if (!EXTENSION_MODE) printSummary(allFindings);
1792 
1793    // In extension mode, post serialized results for the DevTools panel
1794    if (EXTENSION_MODE) {
1795      window.postMessage({
1796        source: 'impeccable-results',
1797        findings: serializeFindings(allFindings),
1798        count: allFindings.length,
1799        ...scanResultMeta(options),
1800      }, '*');
1801    }
1802 
1803    // After this scan completes, all subsequent reveals are instant (no stagger, no animation)
1804    setTimeout(() => { firstScanDone = true; }, 1000);
1805 
1806    return allFindings;
1807  }
1808 
1809  let firstScanDone = false;
1810  const scan = function(options = {}) {
1811    clearOverlays();
1812    const generation = scanGeneration;
1813    const collected = collectBrowserFindings();
1814    const allFindings = renderBrowserFindings(collected, options);
1815    if (shouldRunVisualContrast(options)) {
1816      addVisualContrastFindings(collected.groupMap, options, { decorate: true, generation })
1817        .then(() => {
1818          if (generation === scanGeneration) postSerializedFindings(collected.groupMap, options);
1819        })
1820        .catch(err => {
1821          reportVisualContrastError(err);
1822        });
1823    }
1824    return allFindings;
1825  };
1826 
1827  const scanAsync = async function(options = {}) {
1828    clearOverlays();
1829    const generation = scanGeneration;
1830    if (shouldRunVisualContrast(options)) {
1831      const collected = await collectBrowserFindingsAsync(options, { generation, scheduleLazy: true });
1832      if (generation !== scanGeneration) return [];
1833      return renderBrowserFindings(collected, options);
1834    }
1835    lastVisualContrastAnalyses = [];
1836    return renderBrowserFindings(collectBrowserFindings(), options);
1837  };
1838 
1839  const detect = function(options = {}) {
1840    lastVisualContrastAnalyses = [];
1841    const { allFindings } = collectBrowserFindings();
1842    return options.serialize === false ? allFindings : serializeFindings(allFindings);
1843  };
1844 
1845  const detectAsync = async function(options = {}) {
1846    if (shouldRunVisualContrast(options)) {
1847      const { allFindings } = await collectBrowserFindingsAsync(options);
1848      return options.serialize === false ? allFindings : serializeFindings(allFindings);
1849    }
1850    lastVisualContrastAnalyses = [];
1851    const { allFindings } = collectBrowserFindings();
1852    return options.serialize === false ? allFindings : serializeFindings(allFindings);
1853  };
1854 
1855  if (EXTENSION_MODE) {
1856    // Extension mode: listen for commands, don't auto-scan
1857    window.addEventListener('message', (e) => {
1858      if (e.source !== window || !e.data || e.data.source !== 'impeccable-command') return;
1859      if (e.data.action === 'scan') {
1860        if (e.data.config) window.__IMPECCABLE_CONFIG__ = e.data.config;
1861        try {
1862          scan(e.data.config || {});
1863        } catch (err) {
1864          postExtensionError(err);
1865        }
1866      }
1867      if (e.data.action === 'toggle-overlays') {
1868        const visible = !document.body.classList.contains('impeccable-hidden');
1869        document.body.classList.toggle('impeccable-hidden', visible);
1870        window.postMessage({ source: 'impeccable-overlays-toggled', visible: !visible }, '*');
1871      }
1872      if (e.data.action === 'remove') {
1873        clearOverlays();
1874        styleEl.remove();
1875        if (spotlightBackdrop) { spotlightBackdrop.remove(); spotlightBackdrop = null; }
1876        document.body.classList.remove('impeccable-hidden');
1877      }
1878      if (e.data.action === 'highlight') {
1879        try {
1880          const target = e.data.selector ? document.querySelector(e.data.selector) : null;
1881          if (target) {
1882            // Scroll first so positionOverlay reads the post-scroll rect
1883            if (!isInViewport(target) && target.scrollIntoView) {
1884              target.scrollIntoView({ behavior: 'instant', block: 'center' });
1885            }
1886            for (const o of overlays) {
1887              if (o.classList.contains('impeccable-banner')) continue;
1888              const isMatch = o._targetEl === target;
1889              o.classList.toggle('impeccable-spotlight', isMatch);
1890              o.classList.toggle('impeccable-spotlight-dimmed', !isMatch);
1891              if (isMatch) {
1892                // Force the matching overlay visible immediately, don't wait for IntersectionObserver
1893                o.style.display = '';
1894                o.style.animation = 'none';
1895                o.classList.add('impeccable-visible');
1896                o._revealed = true;
1897                positionOverlay(o);
1898              }
1899            }
1900            showSpotlight(target);
1901          }
1902        } catch { /* invalid selector */ }
1903      }
1904      if (e.data.action === 'unhighlight') {
1905        hideSpotlight();
1906        for (const o of overlays) {
1907          o.classList.remove('impeccable-spotlight');
1908          o.classList.remove('impeccable-spotlight-dimmed');
1909        }
1910      }
1911    });
1912    window.postMessage({ source: 'impeccable-ready' }, '*');
1913  } else {
1914    if (window.__IMPECCABLE_CONFIG__?.autoScan !== false) {
1915      const runAutoScan = () => {
1916        try {
1917          scan();
1918        } catch (err) {
1919          console.warn('[impeccable] scan failed', err);
1920        }
1921      };
1922      if (document.readyState === 'loading') {
1923        document.addEventListener('DOMContentLoaded', () => setTimeout(runAutoScan, 100));
1924      } else {
1925        setTimeout(runAutoScan, 100);
1926      }
1927    }
1928  }
1929 
1930  window.impeccableDetect = detect;
1931  window.impeccableDetectAsync = detectAsync;
1932  window.impeccableScan = scan;
1933  window.impeccableScanAsync = scanAsync;
1934  window.impeccableCollectVisualContrastCandidates = collectVisualContrastCandidates;
1935  window.impeccableAnalyzeVisualContrast = analyzeVisualContrast;
1936  window.impeccableGetLastVisualContrastAnalyses = () => lastVisualContrastAnalyses.slice();
1937}
1938