impeccable 2.3.2 → 3.0.1

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