impeccable 2.3.1 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1544,11 +1544,16 @@ function parseAnyColor(s) {
1544
1544
  // OKLCH parser. Tailwind v4's CSS minifier squishes the space after
1545
1545
  // `%` ("21.5%.02 50"), so the separator between L and C may be absent.
1546
1546
  // Match L (with optional %), then C and H separated permissively.
1547
- m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?\s*\)/i);
1547
+ m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
1548
1548
  if (m) {
1549
1549
  const Lnum = parseFloat(m[1]);
1550
1550
  const L = m[2] === '%' ? Lnum / 100 : Lnum;
1551
- return oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]));
1551
+ const rgb = oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]));
1552
+ if (m[5] !== undefined) {
1553
+ const alpha = parseFloat(m[5]);
1554
+ rgb.a = m[6] === '%' ? alpha / 100 : alpha;
1555
+ }
1556
+ return rgb;
1552
1557
  }
1553
1558
  return null;
1554
1559
  }
@@ -1577,9 +1582,19 @@ const REPEATED_KICKER_SKIP_SELECTOR = [
1577
1582
  '[role="navigation"]',
1578
1583
  '[aria-label*="breadcrumb" i]',
1579
1584
  '[class*="breadcrumb" i]',
1585
+ '[aria-hidden="true"]',
1580
1586
  '[data-impeccable-allow-kickers]',
1581
1587
  ].join(',');
1582
1588
 
1589
+ const REPEATED_KICKER_CARD_CONTEXT_SELECTOR = [
1590
+ 'article',
1591
+ 'button',
1592
+ 'a',
1593
+ 'li',
1594
+ '[role="listitem"]',
1595
+ '[role="option"]',
1596
+ ].join(',');
1597
+
1583
1598
  function cleanInlineText(el) {
1584
1599
  return [...el.childNodes]
1585
1600
  .filter(n => n.nodeType === 3)
@@ -1589,6 +1604,11 @@ function cleanInlineText(el) {
1589
1604
  .trim();
1590
1605
  }
1591
1606
 
1607
+ function isRepeatedKickerCardContext(heading, kicker) {
1608
+ const item = heading.closest?.(REPEATED_KICKER_CARD_CONTEXT_SELECTOR);
1609
+ return Boolean(item && (!item.contains || item.contains(kicker)));
1610
+ }
1611
+
1592
1612
  function isRepeatedKickerCandidate(opts) {
1593
1613
  const {
1594
1614
  headingTag,
@@ -1602,6 +1622,7 @@ function isRepeatedKickerCandidate(opts) {
1602
1622
  } = opts;
1603
1623
  if (!['h2', 'h3', 'h4'].includes(headingTag)) return false;
1604
1624
  if (!headingText || headingText.length < 3) return false;
1625
+ if (/^\/[\w-]+/i.test(headingText.replace(/^"|"$/g, '').trim())) return false;
1605
1626
  if (!(headingFontSize >= 20)) return false;
1606
1627
  if (!kickerTag || HEADING_TAGS.has(kickerTag)) return false;
1607
1628
  if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false;
@@ -1623,6 +1644,7 @@ function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpac
1623
1644
  if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
1624
1645
  const kicker = heading.previousElementSibling;
1625
1646
  if (!kicker || kicker.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
1647
+ if (isRepeatedKickerCardContext(heading, kicker)) continue;
1626
1648
 
1627
1649
  const headingStyle = getStyle(heading);
1628
1650
  const kickerStyle = getStyle(kicker);
@@ -1805,6 +1827,84 @@ function resolveLengthPx(value, fontSizePx) {
1805
1827
  return num * fontSizePx;
1806
1828
  }
1807
1829
 
1830
+ function cssColorIsTransparent(value) {
1831
+ if (!value) return true;
1832
+ const str = String(value).trim().toLowerCase();
1833
+ if (!str || str === 'transparent' || str === 'rgba(0, 0, 0, 0)') return true;
1834
+ const parsed = parseAnyColor(str);
1835
+ if (parsed) return (parsed.a ?? 1) <= 0.05;
1836
+ return /^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*0(?:\.0+)?\s*\)$/.test(str);
1837
+ }
1838
+
1839
+ function colorsNearlyMatch(a, b) {
1840
+ const ca = parseAnyColor(a);
1841
+ const cb = parseAnyColor(b);
1842
+ if (!ca || !cb) return false;
1843
+ const alphaDelta = Math.abs((ca.a ?? 1) - (cb.a ?? 1));
1844
+ const channelDelta = Math.max(
1845
+ Math.abs(ca.r - cb.r),
1846
+ Math.abs(ca.g - cb.g),
1847
+ Math.abs(ca.b - cb.b),
1848
+ );
1849
+ return alphaDelta <= 0.03 && channelDelta <= 3;
1850
+ }
1851
+
1852
+ function getComputedStyleFor(win, el) {
1853
+ if (win && typeof win.getComputedStyle === 'function') {
1854
+ try { return win.getComputedStyle(el); } catch {}
1855
+ }
1856
+ if (typeof getComputedStyle === 'function') {
1857
+ try { return getComputedStyle(el); } catch {}
1858
+ }
1859
+ return null;
1860
+ }
1861
+
1862
+ function hasVisibleBackgroundBoundary(style, el, win) {
1863
+ const bg = style?.backgroundColor || '';
1864
+ if (cssColorIsTransparent(bg)) return false;
1865
+
1866
+ let parent = el?.parentElement || null;
1867
+ while (parent) {
1868
+ const parentStyle = getComputedStyleFor(win, parent);
1869
+ const parentBg = parentStyle?.backgroundColor || '';
1870
+ if (!cssColorIsTransparent(parentBg)) {
1871
+ return !colorsNearlyMatch(bg, parentBg);
1872
+ }
1873
+ parent = parent.parentElement;
1874
+ }
1875
+
1876
+ return true;
1877
+ }
1878
+
1879
+ const TEXT_EDGE_TAGS = new Set(['A', 'BUTTON', 'CODE', 'DD', 'DT', 'FIGCAPTION', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'LI', 'P', 'PRE', 'SPAN', 'TD', 'TH']);
1880
+
1881
+ function hasMeaningfulDirectText(node) {
1882
+ if (!node?.childNodes) return false;
1883
+ for (const child of node.childNodes) {
1884
+ if (child.nodeType === 3 && child.textContent.trim().length > 4) return true;
1885
+ }
1886
+ return false;
1887
+ }
1888
+
1889
+ function textDescendantsFlushSides(el, rect) {
1890
+ const flush = { top: false, right: false, bottom: false, left: false };
1891
+ if (!rect || !el?.querySelectorAll) return flush;
1892
+ const TEXT_EDGE_THRESHOLD = 4;
1893
+ const candidates = el.querySelectorAll('a, button, code, dd, dt, figcaption, h1, h2, h3, h4, h5, h6, li, p, pre, span, td, th');
1894
+ for (const node of candidates) {
1895
+ if (!TEXT_EDGE_TAGS.has(node.tagName) || !hasMeaningfulDirectText(node)) continue;
1896
+ let nodeRect = null;
1897
+ try { nodeRect = node.getBoundingClientRect(); } catch {}
1898
+ if (!nodeRect || nodeRect.width <= 0 || nodeRect.height <= 0) continue;
1899
+ if (nodeRect.bottom < rect.top || nodeRect.top > rect.bottom || nodeRect.right < rect.left || nodeRect.left > rect.right) continue;
1900
+ if (nodeRect.top - rect.top <= TEXT_EDGE_THRESHOLD) flush.top = true;
1901
+ if (rect.right - nodeRect.right <= TEXT_EDGE_THRESHOLD) flush.right = true;
1902
+ if (rect.bottom - nodeRect.bottom <= TEXT_EDGE_THRESHOLD) flush.bottom = true;
1903
+ if (nodeRect.left - rect.left <= TEXT_EDGE_THRESHOLD) flush.left = true;
1904
+ }
1905
+ return flush;
1906
+ }
1907
+
1808
1908
  // Pure quality checks. Most run on computed CSS and DOM-only inputs (work in
1809
1909
  // jsdom and the browser). Two checks (line-length, cramped-padding) gate on
1810
1910
  // element rect dimensions, which jsdom can't compute — pass `rect: null` from
@@ -1834,7 +1934,8 @@ function checkQuality(opts) {
1834
1934
  // font-size — bigger text demands proportionally more padding.
1835
1935
  // vertical: max(4px, fontSize × 0.3)
1836
1936
  // horizontal: max(8px, fontSize × 0.5)
1837
- if (rect && hasDirectText && textLen > 20 && rect.width > 100 && rect.height > 30) {
1937
+ const isInlineCode = tag === 'code' && !(el.closest && el.closest('pre'));
1938
+ if (!isInlineCode && rect && hasDirectText && textLen > 20 && rect.width > 100 && rect.height > 30) {
1838
1939
  const borders = {
1839
1940
  top: parseFloat(style.borderTopWidth) || 0,
1840
1941
  right: parseFloat(style.borderRightWidth) || 0,
@@ -1842,7 +1943,7 @@ function checkQuality(opts) {
1842
1943
  left: parseFloat(style.borderLeftWidth) || 0,
1843
1944
  };
1844
1945
  const borderCount = Object.values(borders).filter(w => w > 0).length;
1845
- const hasBg = style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)';
1946
+ const hasBg = hasVisibleBackgroundBoundary(style, el, win);
1846
1947
  if (borderCount >= 2 || hasBg) {
1847
1948
  const vPads = [], hPads = [];
1848
1949
  if (hasBg || borders.top > 0) vPads.push(parseFloat(style.paddingTop) || 0);
@@ -1890,10 +1991,6 @@ function checkQuality(opts) {
1890
1991
  !['fixed', 'absolute'].includes(elPosition) &&
1891
1992
  el.children && el.children.length > 0
1892
1993
  ) {
1893
- const isTransparent = (c) =>
1894
- !c || c === 'transparent' || c === 'rgba(0, 0, 0, 0)' ||
1895
- /^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*0(?:\.0+)?\s*\)$/.test(c);
1896
-
1897
1994
  const borderW = {
1898
1995
  top: parseFloat(style.borderTopWidth) || 0,
1899
1996
  right: parseFloat(style.borderRightWidth) || 0,
@@ -1901,10 +1998,10 @@ function checkQuality(opts) {
1901
1998
  left: parseFloat(style.borderLeftWidth) || 0,
1902
1999
  };
1903
2000
  const borderVisible = {
1904
- top: borderW.top > 0 && !isTransparent(style.borderTopColor),
1905
- right: borderW.right > 0 && !isTransparent(style.borderRightColor),
1906
- bottom: borderW.bottom > 0 && !isTransparent(style.borderBottomColor),
1907
- left: borderW.left > 0 && !isTransparent(style.borderLeftColor),
2001
+ top: borderW.top > 0 && !cssColorIsTransparent(style.borderTopColor),
2002
+ right: borderW.right > 0 && !cssColorIsTransparent(style.borderRightColor),
2003
+ bottom: borderW.bottom > 0 && !cssColorIsTransparent(style.borderBottomColor),
2004
+ left: borderW.left > 0 && !cssColorIsTransparent(style.borderLeftColor),
1908
2005
  };
1909
2006
  // Outline detection. jsdom decomposes `border` shorthand into
1910
2007
  // border{Top,…}Width/Color but does NOT decompose `outline` —
@@ -1924,8 +2021,8 @@ function checkQuality(opts) {
1924
2021
  if (cMatch) outlineColorVal = cMatch[1];
1925
2022
  }
1926
2023
  }
1927
- const outlineVisible = outlineW > 0 && !isTransparent(outlineColorVal) && outlineStyleVal && outlineStyleVal !== 'none';
1928
- const bgVisible = !isTransparent(style.backgroundColor);
2024
+ const outlineVisible = outlineW > 0 && !cssColorIsTransparent(outlineColorVal) && outlineStyleVal && outlineStyleVal !== 'none';
2025
+ const bgVisible = hasVisibleBackgroundBoundary(style, el, win);
1929
2026
 
1930
2027
  const anyVisible = borderVisible.top || borderVisible.right || borderVisible.bottom || borderVisible.left || outlineVisible || bgVisible;
1931
2028
  if (anyVisible) {
@@ -1953,13 +2050,7 @@ function checkQuality(opts) {
1953
2050
  const CHILD_INSULATE_THRESHOLD = 4;
1954
2051
  const childrenInsulate = { top: false, right: false, bottom: false, left: false };
1955
2052
  for (const child of el.children) {
1956
- let childStyle = null;
1957
- if (win && typeof win.getComputedStyle === 'function') {
1958
- try { childStyle = win.getComputedStyle(child); } catch {}
1959
- }
1960
- if (!childStyle && typeof getComputedStyle === 'function') {
1961
- try { childStyle = getComputedStyle(child); } catch {}
1962
- }
2053
+ let childStyle = getComputedStyleFor(win, child);
1963
2054
  if (!childStyle) continue;
1964
2055
  const childPad = {
1965
2056
  top: resolveLengthPx(childStyle.paddingTop, fontSize) ?? 0,
@@ -1967,15 +2058,37 @@ function checkQuality(opts) {
1967
2058
  bottom: resolveLengthPx(childStyle.paddingBottom, fontSize) ?? 0,
1968
2059
  left: resolveLengthPx(childStyle.paddingLeft, fontSize) ?? 0,
1969
2060
  };
2061
+ const childMargin = {
2062
+ top: resolveLengthPx(childStyle.marginTop, fontSize) ?? 0,
2063
+ right: resolveLengthPx(childStyle.marginRight, fontSize) ?? 0,
2064
+ bottom: resolveLengthPx(childStyle.marginBottom, fontSize) ?? 0,
2065
+ left: resolveLengthPx(childStyle.marginLeft, fontSize) ?? 0,
2066
+ };
2067
+ if (rect && typeof child.getBoundingClientRect === 'function') {
2068
+ try {
2069
+ const childRect = child.getBoundingClientRect();
2070
+ if (childRect && childRect.width > 0 && childRect.height > 0) {
2071
+ if (childRect.top - rect.top >= CHILD_INSULATE_THRESHOLD) childrenInsulate.top = true;
2072
+ if (rect.right - childRect.right >= CHILD_INSULATE_THRESHOLD) childrenInsulate.right = true;
2073
+ if (rect.bottom - childRect.bottom >= CHILD_INSULATE_THRESHOLD) childrenInsulate.bottom = true;
2074
+ if (childRect.left - rect.left >= CHILD_INSULATE_THRESHOLD) childrenInsulate.left = true;
2075
+ }
2076
+ } catch {}
2077
+ }
1970
2078
  for (const s of ['top', 'right', 'bottom', 'left']) {
1971
- if (childPad[s] >= CHILD_INSULATE_THRESHOLD) childrenInsulate[s] = true;
2079
+ if (childPad[s] >= CHILD_INSULATE_THRESHOLD || childMargin[s] >= CHILD_INSULATE_THRESHOLD) {
2080
+ childrenInsulate[s] = true;
2081
+ }
1972
2082
  }
1973
2083
  }
1974
2084
 
2085
+ const textFlush = rect ? textDescendantsFlushSides(el, rect) : null;
2086
+ const fullBleedBgBand = rect && viewportWidth > 0 && rect.width >= viewportWidth * 0.94 && bgVisible && !outlineVisible;
1975
2087
  const flushSides = [];
1976
2088
  for (const side of ['top', 'right', 'bottom', 'left']) {
1977
- const sideBounded = borderVisible[side] || outlineVisible || bgVisible;
1978
- if (sideBounded && pad[side] <= PAD_THRESHOLD && !childrenInsulate[side]) {
2089
+ const bgBoundsSide = bgVisible && !(fullBleedBgBand && (side === 'left' || side === 'right'));
2090
+ const sideBounded = borderVisible[side] || outlineVisible || bgBoundsSide;
2091
+ if (sideBounded && pad[side] <= PAD_THRESHOLD && !childrenInsulate[side] && (!textFlush || textFlush[side])) {
1979
2092
  flushSides.push(side);
1980
2093
  }
1981
2094
  }
@@ -2069,7 +2182,7 @@ function checkQuality(opts) {
2069
2182
  // Only flag actual body content, not UI labels (buttons, tabs, badges, captions, footer text, etc.)
2070
2183
  if (hasDirectText && textLen > 20 && fontSize < 12) {
2071
2184
  const skipTags = ['sub', 'sup', 'code', 'kbd', 'samp', 'var', 'caption', 'figcaption'];
2072
- const inUIContext = el.closest && el.closest('button, a, label, summary, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="option"], nav, footer, [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="label" i], [class*="caption" i]');
2185
+ const inUIContext = el.closest && el.closest('button, a, label, summary, pre, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="option"], nav, footer, [aria-hidden="true"], [class*="badge" i], [class*="caption" i], [class*="chip" i], [class*="code" i], [class*="console" i], [class*="diff" i], [class*="label" i], [class*="meta" i], [class*="mock" i], [class*="pill" i], [class*="preview" i], [class*="tag" i], [class*="terminal" i], [class*="writes" i]');
2073
2186
  const isUppercase = style.textTransform === 'uppercase';
2074
2187
  if (!skipTags.includes(tag) && !inUIContext && !isUppercase) {
2075
2188
  findings.push({ id: 'tiny-text', snippet: `${fontSize}px body text` });
@@ -2677,17 +2790,28 @@ function checkCreamPalette(doc, win) {
2677
2790
  }
2678
2791
 
2679
2792
  // ─── Oversized hero headline ────────────────────────────────────────────────
2680
- // Fires when a *long* headline is set at display size, so a full sentence ends
2681
- // up dominating the viewport. A punchy one- or two-word headline at the same
2682
- // size is a legitimate stylistic choice and must pass — length, not size
2683
- // alone, is the tell.
2793
+ // Fires when a *long* headline is set at display size and actually dominates
2794
+ // the viewport. A punchy one- or two-word headline at the same size is a
2795
+ // legitimate stylistic choice, and a large-but-contained two-line hero should
2796
+ // pass too — length and viewport share together are the tell.
2684
2797
  const OVERSIZED_H1_FONT_PX = 72;
2685
2798
  const OVERSIZED_H1_MIN_CHARS = 40;
2686
- function checkOversizedH1({ tag, fontSize, headingText }) {
2799
+ const OVERSIZED_H1_MIN_VIEWPORT_HEIGHT_RATIO = 0.28;
2800
+ const OVERSIZED_H1_MIN_VIEWPORT_AREA_RATIO = 0.25;
2801
+ function checkOversizedH1({ tag, fontSize, headingText, rect = null, viewportWidth = 0, viewportHeight = 0 }) {
2687
2802
  if (tag !== 'h1') return [];
2688
2803
  const textLen = headingText.length;
2689
2804
  if (fontSize >= OVERSIZED_H1_FONT_PX && textLen >= OVERSIZED_H1_MIN_CHARS) {
2690
- return [{ id: 'oversized-h1', snippet: `${Math.round(fontSize)}px h1, ${textLen} chars "${headingText.slice(0, 60)}"` }];
2805
+ let viewportDetail = '';
2806
+ if (rect && viewportWidth > 0 && viewportHeight > 0) {
2807
+ const heightRatio = rect.height / viewportHeight;
2808
+ const areaRatio = (rect.width * rect.height) / (viewportWidth * viewportHeight);
2809
+ const dominatesViewport = heightRatio >= OVERSIZED_H1_MIN_VIEWPORT_HEIGHT_RATIO
2810
+ || areaRatio >= OVERSIZED_H1_MIN_VIEWPORT_AREA_RATIO;
2811
+ if (!dominatesViewport) return [];
2812
+ viewportDetail = `, ${Math.round(heightRatio * 100)}vh`;
2813
+ }
2814
+ return [{ id: 'oversized-h1', snippet: `${Math.round(fontSize)}px h1, ${textLen} chars${viewportDetail} "${headingText.slice(0, 60)}"` }];
2691
2815
  }
2692
2816
  return [];
2693
2817
  }
@@ -2705,31 +2829,54 @@ function checkElementOversizedH1DOM(el) {
2705
2829
  const style = getComputedStyle(el);
2706
2830
  const fontSize = parseFloat(style.fontSize) || 0;
2707
2831
  const headingText = (el.textContent || '').trim().replace(/\s+/g, ' ');
2708
- return checkOversizedH1({ tag, fontSize, headingText });
2832
+ const rect = el.getBoundingClientRect();
2833
+ const viewportWidth = (typeof window !== 'undefined' ? window.innerWidth : 0) || 0;
2834
+ const viewportHeight = (typeof window !== 'undefined' ? window.innerHeight : 0) || 0;
2835
+ return checkOversizedH1({ tag, fontSize, headingText, rect, viewportWidth, viewportHeight });
2709
2836
  }
2710
2837
 
2711
2838
  // ─── GPT tell: hairline border + wide diffuse shadow (gated --gpt) ────────────
2712
- function shadowMaxBlurPx(boxShadow) {
2839
+ const CSS_COLOR_TOKEN_RE = /(?:rgba?|hsla?|oklch|oklab|lab|lch|color)\([^)]*\)|#[0-9a-fA-F]{3,8}\b|\b(?:black|white|transparent|currentcolor)\b/gi;
2840
+
2841
+ function shadowLayerAlpha(layer) {
2842
+ CSS_COLOR_TOKEN_RE.lastIndex = 0;
2843
+ const match = CSS_COLOR_TOKEN_RE.exec(layer);
2844
+ if (!match) return 1;
2845
+ if (match[0].toLowerCase() === 'transparent') return 0;
2846
+ const parsed = parseAnyColor(match[0]);
2847
+ return parsed ? (parsed.a ?? 1) : 1;
2848
+ }
2849
+
2850
+ function shadowMaxBlurPx(boxShadow, { minAlpha = 0 } = {}) {
2713
2851
  if (!boxShadow || boxShadow === 'none') return 0;
2714
2852
  let maxBlur = 0;
2715
2853
  // Split into layers on commas not inside parentheses (rgba(...) etc.).
2716
2854
  for (const layer of boxShadow.split(/,(?![^()]*\))/)) {
2855
+ if (shadowLayerAlpha(layer) < minAlpha) continue;
2717
2856
  // Strip colors and keywords (rgba()/hsl()/hex/named/inset/px), leaving the
2718
2857
  // ordered length tokens: offsetX offsetY blur [spread]. Static jsdom keeps
2719
2858
  // unitless zeros ("0 0 24px"); browsers normalize to px ("0px 0px 24px") —
2720
2859
  // both reduce to the same numbers here.
2721
- const cleaned = layer.replace(/rgba?\([^)]*\)|hsla?\([^)]*\)|#[0-9a-f]+|\b[a-z]+\b/gi, ' ');
2860
+ const cleaned = layer.replace(CSS_COLOR_TOKEN_RE, ' ').replace(/\b[a-z]+\b/gi, ' ');
2722
2861
  const nums = [...cleaned.matchAll(/-?\d*\.?\d+/g)].map(m => parseFloat(m[0]));
2723
2862
  if (nums.length >= 3) maxBlur = Math.max(maxBlur, nums[2]);
2724
2863
  }
2725
2864
  return maxBlur;
2726
2865
  }
2727
2866
 
2728
- function checkGptThinBorderWideShadow({ borderWidths, boxShadow }) {
2729
- const maxBorder = Math.max(0, ...borderWidths);
2730
- const hasThinBorder = maxBorder > 0 && maxBorder <= 1.5;
2731
- const blur = shadowMaxBlurPx(boxShadow);
2732
- if (hasThinBorder && blur >= 16) {
2867
+ function cssColorAlpha(value) {
2868
+ if (cssColorIsTransparent(value)) return 0;
2869
+ const parsed = parseAnyColor(value);
2870
+ return parsed ? (parsed.a ?? 1) : 1;
2871
+ }
2872
+
2873
+ function checkGptThinBorderWideShadow({ borderWidths, borderColors, boxShadow }) {
2874
+ const visibleThinBorders = borderWidths
2875
+ .map((width, index) => ({ width, alpha: cssColorAlpha(borderColors?.[index] || '') }))
2876
+ .filter(({ width, alpha }) => width > 0 && width <= 1.5 && alpha >= 0.28);
2877
+ const maxBorder = Math.max(0, ...visibleThinBorders.map(({ width }) => width));
2878
+ const blur = shadowMaxBlurPx(boxShadow, { minAlpha: 0.12 });
2879
+ if (visibleThinBorders.length >= 2 && blur >= 16) {
2733
2880
  return [{ id: 'gpt-thin-border-wide-shadow', snippet: `${maxBorder}px border + ${Math.round(blur)}px shadow blur` }];
2734
2881
  }
2735
2882
  return [];
@@ -2744,13 +2891,22 @@ function borderWidthsFromStyle(style) {
2744
2891
  ];
2745
2892
  }
2746
2893
 
2894
+ function borderColorsFromStyle(style) {
2895
+ return [
2896
+ style.borderTopColor || '',
2897
+ style.borderRightColor || '',
2898
+ style.borderBottomColor || '',
2899
+ style.borderLeftColor || '',
2900
+ ];
2901
+ }
2902
+
2747
2903
  function checkElementGptBorderShadow(el, style) {
2748
- return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), boxShadow: style.boxShadow || '' });
2904
+ return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), borderColors: borderColorsFromStyle(style), boxShadow: style.boxShadow || '' });
2749
2905
  }
2750
2906
 
2751
2907
  function checkElementGptBorderShadowDOM(el) {
2752
2908
  const style = getComputedStyle(el);
2753
- return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), boxShadow: style.boxShadow || '' });
2909
+ return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), borderColors: borderColorsFromStyle(style), boxShadow: style.boxShadow || '' });
2754
2910
  }
2755
2911
 
2756
2912
  // ─── Clipped overflow container ───────────────────────────────────────────────
@@ -2763,17 +2919,131 @@ function classSelector(el) {
2763
2919
  return tokens.length ? `${tag}.${tokens.join('.')}` : tag;
2764
2920
  }
2765
2921
 
2922
+ function positionedChildIsDecorative(child) {
2923
+ if (!child || typeof child.getAttribute !== 'function') return false;
2924
+ if (child.closest?.('[aria-hidden="true"]')) return true;
2925
+ const role = (child.getAttribute('role') || '').toLowerCase();
2926
+ if (role === 'none' || role === 'presentation') return true;
2927
+ const tag = child.tagName ? child.tagName.toLowerCase() : '';
2928
+ if (['img', 'svg', 'canvas', 'video'].includes(tag)) return true;
2929
+ const ident = `${child.getAttribute('class') || ''} ${child.getAttribute('id') || ''}`;
2930
+ if (
2931
+ /\b(art|bg|background|badge|blob|crop|decor|dot|glow|grain|image|mask|ornament|overlay|photo|scrim|shadow|shine|texture)\b/i.test(ident) &&
2932
+ !positionedChildHasSubstantiveContent(child)
2933
+ ) {
2934
+ return true;
2935
+ }
2936
+ return false;
2937
+ }
2938
+
2939
+ const POSITIONED_CHILD_INTERACTIVE_SELECTOR = [
2940
+ 'a[href]',
2941
+ 'button',
2942
+ 'input',
2943
+ 'select',
2944
+ 'summary',
2945
+ 'textarea',
2946
+ '[tabindex]:not([tabindex="-1"])',
2947
+ '[role="button"]',
2948
+ '[role="dialog"]',
2949
+ '[role="link"]',
2950
+ '[role="listbox"]',
2951
+ '[role="menu"]',
2952
+ '[role="menuitem"]',
2953
+ '[role="option"]',
2954
+ '[role="tooltip"]',
2955
+ ].join(',');
2956
+
2957
+ function positionedChildHasSubstantiveContent(child) {
2958
+ const text = (child.textContent || '').replace(/\s+/g, ' ').trim();
2959
+ if (text.length > 0) return true;
2960
+ if (typeof child.matches === 'function') {
2961
+ try {
2962
+ if (child.matches(POSITIONED_CHILD_INTERACTIVE_SELECTOR)) return true;
2963
+ } catch {}
2964
+ }
2965
+ if (typeof child.querySelector === 'function') {
2966
+ try {
2967
+ if (child.querySelector(POSITIONED_CHILD_INTERACTIVE_SELECTOR)) return true;
2968
+ } catch {}
2969
+ }
2970
+ return false;
2971
+ }
2972
+
2973
+ function clippingContainerIsIntentionalViewport(el) {
2974
+ if (!el || typeof el.getAttribute !== 'function') return false;
2975
+ const roleDescription = (el.getAttribute('aria-roledescription') || '').toLowerCase();
2976
+ if (/\b(carousel|slider)\b/.test(roleDescription)) return true;
2977
+ const ident = `${el.getAttribute('class') || ''} ${el.getAttribute('id') || ''}`.toLowerCase();
2978
+ return /\b(carousel|comparison|compare|fisheye|marquee|preview|scroller|slider|slideshow|split|viewport)\b/.test(ident) ||
2979
+ /\b(demo-area|demo-stage|demo-viewport)\b/.test(ident);
2980
+ }
2981
+
2982
+ function elementRect(el) {
2983
+ if (!el || typeof el.getBoundingClientRect !== 'function') return null;
2984
+ try {
2985
+ const rect = el.getBoundingClientRect();
2986
+ if (!rect) return null;
2987
+ const values = [rect.top, rect.right, rect.bottom, rect.left, rect.width, rect.height];
2988
+ if (!values.every(Number.isFinite)) return null;
2989
+ if (rect.width <= 0 && rect.height <= 0) return null;
2990
+ return rect;
2991
+ } catch {
2992
+ return null;
2993
+ }
2994
+ }
2995
+
2996
+ function positionedStyleImpliesEscape(style) {
2997
+ const values = [
2998
+ style.top,
2999
+ style.right,
3000
+ style.bottom,
3001
+ style.left,
3002
+ style.inset,
3003
+ style.insetBlock,
3004
+ style.insetInline,
3005
+ style.insetBlockStart,
3006
+ style.insetBlockEnd,
3007
+ style.insetInlineStart,
3008
+ style.insetInlineEnd,
3009
+ ].filter(Boolean).map(value => String(value).trim().toLowerCase());
3010
+ for (const value of values) {
3011
+ if (/(^|[\s(])-+(?:\d|\.)/.test(value)) return true;
3012
+ if (/(^|[\s(])100(?:\.0+)?%/.test(value)) return true;
3013
+ }
3014
+ return false;
3015
+ }
3016
+
3017
+ function positionedChildEscapesClip(el, child, clipX, clipY) {
3018
+ const parentRect = elementRect(el);
3019
+ const childRect = elementRect(child);
3020
+ if (!parentRect || !childRect) return null;
3021
+ const threshold = 2;
3022
+ return Boolean(
3023
+ (clipX && (childRect.left < parentRect.left - threshold || childRect.right > parentRect.right + threshold)) ||
3024
+ (clipY && (childRect.top < parentRect.top - threshold || childRect.bottom > parentRect.bottom + threshold))
3025
+ );
3026
+ }
3027
+
2766
3028
  function checkClippedOverflow(el, style, getStyle) {
2767
3029
  const clips = (v) => v === 'hidden' || v === 'clip';
2768
3030
  const scrolls = (v) => v === 'auto' || v === 'scroll';
2769
3031
  const ox = style.overflowX || '', oy = style.overflowY || '', ov = style.overflow || '';
2770
- const anyClip = clips(ox) || clips(oy) || clips(ov);
3032
+ const clipX = clips(ox) || clips(ov);
3033
+ const clipY = clips(oy) || clips(ov);
3034
+ const anyClip = clipX || clipY;
2771
3035
  const anyScroll = scrolls(ox) || scrolls(oy) || scrolls(ov);
2772
3036
  if (!anyClip || anyScroll) return [];
3037
+ if (clippingContainerIsIntentionalViewport(el)) return [];
2773
3038
  if (!el.querySelectorAll) return [];
2774
3039
  for (const child of el.querySelectorAll('*')) {
2775
- const pos = (getStyle(child).position) || '';
3040
+ const childStyle = getStyle(child);
3041
+ const pos = childStyle.position || '';
2776
3042
  if (pos === 'absolute' || pos === 'fixed') {
3043
+ if (positionedChildIsDecorative(child)) continue;
3044
+ const escapes = positionedChildEscapesClip(el, child, clipX, clipY);
3045
+ if (escapes === false) continue;
3046
+ if (escapes === null && !positionedStyleImpliesEscape(childStyle)) continue;
2777
3047
  return [{ id: 'clipped-overflow-container', snippet: `${classSelector(el)} clips a positioned child` }];
2778
3048
  }
2779
3049
  }
@@ -2792,14 +3062,94 @@ function checkElementClippedOverflowDOM(el) {
2792
3062
  // ─── Text overflow (browser-only: needs scrollWidth/clientWidth) ──────────────
2793
3063
  const TEXT_OVERFLOW_SKIP_TAGS = new Set(['pre', 'code', 'textarea', 'svg', 'canvas', 'select', 'option', 'marquee']);
2794
3064
 
3065
+ function metricLengthPx(value, fontSizePx = 16) {
3066
+ if (typeof value === 'number' && Number.isFinite(value)) return value;
3067
+ if (typeof value !== 'string') return null;
3068
+ return resolveLengthPx(value, fontSizePx);
3069
+ }
3070
+
3071
+ function firstMetricLengthPx(fontSizePx, ...values) {
3072
+ for (const value of values) {
3073
+ const parsed = metricLengthPx(value, fontSizePx);
3074
+ if (parsed !== null) return parsed;
3075
+ }
3076
+ return null;
3077
+ }
3078
+
3079
+ function expandBoxShorthand(parts) {
3080
+ if (parts.length === 1) return [parts[0], parts[0], parts[0], parts[0]];
3081
+ if (parts.length === 2) return [parts[0], parts[1], parts[0], parts[1]];
3082
+ if (parts.length === 3) return [parts[0], parts[1], parts[2], parts[1]];
3083
+ return [parts[0], parts[1], parts[2], parts[3]];
3084
+ }
3085
+
3086
+ function clippedByInset(clipPath) {
3087
+ const match = String(clipPath || '').trim().toLowerCase().match(/^inset\s*\(([^)]*)\)$/);
3088
+ if (!match) return false;
3089
+ const beforeRound = match[1].split(/\s+round\s+/)[0].trim();
3090
+ if (!beforeRound) return false;
3091
+ const values = expandBoxShorthand(beforeRound.split(/\s+/).slice(0, 4));
3092
+ const percents = values.map(value => String(value).trim().match(/^(-?\d+(?:\.\d+)?)%$/));
3093
+ if (percents.some(match => !match)) return false;
3094
+ const [top, right, bottom, left] = percents.map(match => parseFloat(match[1]));
3095
+ return top + bottom >= 100 || left + right >= 100;
3096
+ }
3097
+
3098
+ function clippedByRect(clip) {
3099
+ const match = String(clip || '').trim().toLowerCase().match(/^rect\s*\(([^)]*)\)$/);
3100
+ if (!match) return false;
3101
+ const values = match[1].split(/[,\s]+/).map(value => value.trim()).filter(Boolean);
3102
+ if (values.length !== 4) return false;
3103
+ const [top, right, bottom, left] = values.map(value => metricLengthPx(value, 16));
3104
+ if ([top, right, bottom, left].some(value => value === null)) return false;
3105
+ return bottom <= top || right <= left;
3106
+ }
3107
+
3108
+ function isScreenReaderOnlyTextStyle(style, metrics = {}) {
3109
+ if (!style) return false;
3110
+ const overflowValues = [style.overflow, style.overflowX, style.overflowY]
3111
+ .map(value => String(value || '').toLowerCase());
3112
+ const clipsOverflow = overflowValues.some(value => value === 'hidden' || value === 'clip');
3113
+
3114
+ const fontSize = metricLengthPx(style.fontSize, 16) || 16;
3115
+ const width = firstMetricLengthPx(fontSize, metrics.width, metrics.clientWidth, style.width, style.inlineSize);
3116
+ const height = firstMetricLengthPx(fontSize, metrics.height, metrics.clientHeight, style.height, style.blockSize);
3117
+ const isTiny = width !== null && height !== null && width <= 2 && height <= 2;
3118
+ const isAbsolutelyHidden = String(style.position || '').toLowerCase() === 'absolute' && isTiny && clipsOverflow;
3119
+
3120
+ const clipPath = String(style.clipPath || style.webkitClipPath || '').trim();
3121
+ const clip = String(style.clip || '').trim();
3122
+ return isAbsolutelyHidden || clippedByInset(clipPath) || clippedByRect(clip);
3123
+ }
3124
+
3125
+ function isRenderedForBrowserRule(el) {
3126
+ for (let cur = el; cur && cur.nodeType === 1; cur = cur.parentElement) {
3127
+ if (cur.getAttribute?.('aria-hidden') === 'true') return false;
3128
+ const style = getComputedStyle(cur);
3129
+ const visibility = String(style.visibility || '').toLowerCase();
3130
+ if (style.display === 'none' || visibility === 'hidden' || visibility === 'collapse') return false;
3131
+ if ((parseFloat(style.opacity) || 0) <= 0.01) return false;
3132
+ if (String(style.contentVisibility || '').toLowerCase() === 'hidden') return false;
3133
+ }
3134
+ return true;
3135
+ }
3136
+
2795
3137
  function checkElementTextOverflowDOM(el) {
2796
3138
  const tag = el.tagName.toLowerCase();
2797
3139
  if (TEXT_OVERFLOW_SKIP_TAGS.has(tag)) return [];
3140
+ if (!isRenderedForBrowserRule(el)) return [];
2798
3141
  // Only the element that actually owns overflowing text — not its ancestors,
2799
3142
  // which inherit a wider scrollWidth from the spilling descendant.
2800
3143
  const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 0);
2801
3144
  if (!hasDirectText) return [];
2802
3145
  const style = getComputedStyle(el);
3146
+ const rect = el.getBoundingClientRect ? el.getBoundingClientRect() : null;
3147
+ if (isScreenReaderOnlyTextStyle(style, {
3148
+ width: rect?.width,
3149
+ height: rect?.height,
3150
+ clientWidth: el.clientWidth,
3151
+ clientHeight: el.clientHeight,
3152
+ })) return [];
2803
3153
  const isScrollRegion = (s) => /(auto|scroll)/.test(s.overflowX || '') || /(auto|scroll)/.test(s.overflow || '');
2804
3154
  if (isScrollRegion(style)) return [];
2805
3155
  // A scrollable ancestor means this overflow is intentional and scrollable.
@@ -3476,6 +3826,7 @@ if (IS_BROWSER) {
3476
3826
  if (el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
3477
3827
  if (el.closest('[id^="impeccable-live-"]')) continue;
3478
3828
  if (el === document.body || el === document.documentElement) continue;
3829
+ if (!isRenderedForBrowserRule(el)) continue;
3479
3830
 
3480
3831
  const tag = el.tagName.toLowerCase();
3481
3832
  const style = getComputedStyle(el);
@@ -3907,6 +4258,7 @@ if (IS_BROWSER) {
3907
4258
  return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'stale selector' };
3908
4259
  }
3909
4260
  if (!el) return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'missing element' };
4261
+ if (!isRenderedForBrowserRule(el)) return { ...candidate, status: 'unresolved', confidence: 'none', reason: 'hidden element' };
3910
4262
 
3911
4263
  const blockingReason = (candidate.reasons || []).find(reason =>
3912
4264
  reason === 'background-clip text' ||
@@ -4253,13 +4605,20 @@ if (IS_BROWSER) {
4253
4605
  return true;
4254
4606
  }
4255
4607
 
4256
- function postSerializedFindings(groupMap) {
4608
+ function scanResultMeta(options = {}) {
4609
+ const scanId = options.scanId;
4610
+ if (typeof scanId !== 'string' && typeof scanId !== 'number') return {};
4611
+ return { scanId: String(scanId) };
4612
+ }
4613
+
4614
+ function postSerializedFindings(groupMap, options = {}) {
4257
4615
  if (!EXTENSION_MODE) return;
4258
4616
  const allFindings = browserFindingsFromMap(groupMap);
4259
4617
  window.postMessage({
4260
4618
  source: 'impeccable-results',
4261
4619
  findings: serializeFindings(allFindings),
4262
4620
  count: allFindings.length,
4621
+ ...scanResultMeta(options),
4263
4622
  }, '*');
4264
4623
  }
4265
4624
 
@@ -4313,7 +4672,7 @@ if (IS_BROWSER) {
4313
4672
  rememberVisualContrastAnalysis(result);
4314
4673
  const added = addVisualContrastResult(groupMap, result, { decorate: true });
4315
4674
  if (added) {
4316
- postSerializedFindings(groupMap);
4675
+ postSerializedFindings(groupMap, options);
4317
4676
  window.dispatchEvent(new CustomEvent('impeccable-visual-contrast-resolved', {
4318
4677
  detail: {
4319
4678
  selector: result.selector,
@@ -4381,7 +4740,7 @@ if (IS_BROWSER) {
4381
4740
  overlayIndex = 0;
4382
4741
  }
4383
4742
 
4384
- function renderBrowserFindings(collected) {
4743
+ function renderBrowserFindings(collected, options = {}) {
4385
4744
  const { allFindings, pageLevelFindings } = collected;
4386
4745
 
4387
4746
  for (const { el, findings } of allFindings) {
@@ -4401,6 +4760,7 @@ if (IS_BROWSER) {
4401
4760
  source: 'impeccable-results',
4402
4761
  findings: serializeFindings(allFindings),
4403
4762
  count: allFindings.length,
4763
+ ...scanResultMeta(options),
4404
4764
  }, '*');
4405
4765
  }
4406
4766
 
@@ -4415,11 +4775,11 @@ if (IS_BROWSER) {
4415
4775
  clearOverlays();
4416
4776
  const generation = scanGeneration;
4417
4777
  const collected = collectBrowserFindings();
4418
- const allFindings = renderBrowserFindings(collected);
4778
+ const allFindings = renderBrowserFindings(collected, options);
4419
4779
  if (shouldRunVisualContrast(options)) {
4420
4780
  addVisualContrastFindings(collected.groupMap, options, { decorate: true, generation })
4421
4781
  .then(() => {
4422
- if (generation === scanGeneration) postSerializedFindings(collected.groupMap);
4782
+ if (generation === scanGeneration) postSerializedFindings(collected.groupMap, options);
4423
4783
  })
4424
4784
  .catch(err => {
4425
4785
  reportVisualContrastError(err);
@@ -4434,10 +4794,10 @@ if (IS_BROWSER) {
4434
4794
  if (shouldRunVisualContrast(options)) {
4435
4795
  const collected = await collectBrowserFindingsAsync(options, { generation, scheduleLazy: true });
4436
4796
  if (generation !== scanGeneration) return [];
4437
- return renderBrowserFindings(collected);
4797
+ return renderBrowserFindings(collected, options);
4438
4798
  }
4439
4799
  lastVisualContrastAnalyses = [];
4440
- return renderBrowserFindings(collectBrowserFindings());
4800
+ return renderBrowserFindings(collectBrowserFindings(), options);
4441
4801
  };
4442
4802
 
4443
4803
  const detect = function(options = {}) {