impeccable 3.5.0 → 3.6.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.
@@ -11,14 +11,21 @@ import {
11
11
  isBrandFontOnOwnDomain,
12
12
  } from '../shared/constants.mjs';
13
13
  import {
14
+ CSS_NAMED_COLORS,
14
15
  colorToHex,
16
+ compositeColorOver,
15
17
  contrastRatio,
16
18
  getHue,
17
19
  hasChroma,
18
20
  isNeutralColor,
21
+ isNoPaintColorValue,
22
+ oklchToRgb,
23
+ parseAnyColor,
24
+ parseColorMix,
19
25
  parseGradientColors,
20
26
  parseRgb,
21
27
  relativeLuminance,
28
+ splitTopLevelCommas,
22
29
  } from '../shared/color.mjs';
23
30
  import { extractGoogleFontFamilies } from '../shared/fonts.mjs';
24
31
 
@@ -70,6 +77,34 @@ function checkBorders(tag, widths, colors, radius, opts = {}) {
70
77
  return findings;
71
78
  }
72
79
 
80
+ // ─── Scoped ignores: data-impeccable-ignore ─────────────────────────────────
81
+ //
82
+ // An element-scoped waiver that travels with the markup: any element carrying
83
+ // `data-impeccable-ignore="rule-a rule-b"` (or `*`, or an empty value, for
84
+ // every rule) suppresses matching findings from itself and its entire subtree,
85
+ // in every engine that walks elements — the browser overlay, the extension,
86
+ // and the static scan. This is the DOM twin of the line-based
87
+ // `impeccable-disable` comment directives, which the browser cannot apply (a
88
+ // live DOM has no line numbers), and the generalization of the one-off
89
+ // `data-impeccable-allow-kickers` opt-out.
90
+ //
91
+ // The intended use is curated exhibits: a page that documents anti-patterns by
92
+ // example, or renders a deliberate "before" specimen, marks the container once
93
+ // and every engine skips it while still scanning the page around it.
94
+ function scopedIgnoreActive(el, ruleId) {
95
+ const rule = String(ruleId || '').toLowerCase();
96
+ let cur = el;
97
+ while (cur && cur.nodeType === 1) {
98
+ const attr = typeof cur.getAttribute === 'function' ? cur.getAttribute('data-impeccable-ignore') : null;
99
+ if (attr != null) {
100
+ const rules = String(attr).trim().toLowerCase().split(/[\s,]+/).filter(Boolean);
101
+ if (rules.length === 0 || rules.includes('*') || rules.includes(rule)) return true;
102
+ }
103
+ cur = cur.parentElement;
104
+ }
105
+ return false;
106
+ }
107
+
73
108
  // Returns true if the given text is composed entirely of emoji characters
74
109
  // (plus whitespace / variation selectors). Emojis render as multicolor glyphs
75
110
  // regardless of CSS `color`, so contrast checks against the element's text
@@ -637,6 +672,26 @@ function cssTextHasDarkRootBg(content, customProps) {
637
672
  return false;
638
673
  }
639
674
 
675
+ // Best-effort extraction of the CSS selector whose declaration block contains
676
+ // the given index in raw CSS text. Lets CSS-text findings carry a live-DOM
677
+ // anchor, so the browser pass can resolve scoped ignores against the actual
678
+ // element and drop patterns that render nowhere on the page. Returns null for
679
+ // @-rule preludes, keyframe steps, nested blocks, and anything that does not
680
+ // read as a selector; those findings stay page-level.
681
+ function enclosingCssSelector(cssText, index) {
682
+ if (!cssText || !Number.isFinite(index)) return null;
683
+ const open = cssText.lastIndexOf('{', index);
684
+ if (open === -1) return null;
685
+ const prevClose = Math.max(cssText.lastIndexOf('}', open - 1), cssText.lastIndexOf(';', open - 1));
686
+ const raw = cssText.slice(prevClose + 1, open).trim().replace(/\s+/g, ' ');
687
+ if (!raw || raw.startsWith('@') || /^\d/.test(raw) || /[{}<]/.test(raw)) return null;
688
+ // Keyframe steps: percentage steps fail the digit test above, but `from`
689
+ // and `to` would read as (never-matching) type selectors and get a valid
690
+ // finding wrongly dropped by the zero-match rule downstream.
691
+ if (/^(?:from|to)(?:\s*,\s*(?:from|to))*$/i.test(raw)) return null;
692
+ return raw;
693
+ }
694
+
640
695
  function scanCssTextForGlow(content) {
641
696
  const customProps = collectCssCustomProps(content);
642
697
  const hasDarkBg = cssTextHasDarkRootBg(content, customProps);
@@ -948,6 +1003,7 @@ function scanCssTextForPseudoStripe(rawContent) {
948
1003
  id: 'side-tab',
949
1004
  snippet: `${selector} — absolute ${thicknessPx}px pseudo-element stripe (${edge}: 0)`,
950
1005
  index: selectorStart,
1006
+ selector,
951
1007
  });
952
1008
  }
953
1009
  return findings;
@@ -1010,6 +1066,7 @@ function scanCssTextForInsetStripe(content) {
1010
1066
  findings.push({
1011
1067
  id: 'side-tab',
1012
1068
  snippet: `${selector} — inset box-shadow ${ay === 0 ? ax : ay}px stripe (${edge})`,
1069
+ selector,
1013
1070
  });
1014
1071
  break;
1015
1072
  }
@@ -1067,7 +1124,7 @@ function collectMarqueeKeyframes(content) {
1067
1124
  function scanCssTextForMarquee(content, markup = content) {
1068
1125
  const findings = [];
1069
1126
  if (/<marquee\b/i.test(markup)) {
1070
- findings.push({ id: 'marquee', snippet: '<marquee> element' });
1127
+ findings.push({ id: 'marquee', snippet: '<marquee> element', selector: 'marquee' });
1071
1128
  }
1072
1129
  const marqueeKeyframes = collectMarqueeKeyframes(content);
1073
1130
  if (marqueeKeyframes.size === 0) return findings;
@@ -1082,7 +1139,7 @@ function scanCssTextForMarquee(content, markup = content) {
1082
1139
  const key = `${selector} ${name}`;
1083
1140
  if (seen.has(key)) continue;
1084
1141
  seen.add(key);
1085
- findings.push({ id: 'marquee', snippet: `${selector} — infinite horizontal loop animation "${name}"` });
1142
+ findings.push({ id: 'marquee', snippet: `${selector} — infinite horizontal loop animation "${name}"`, selector });
1086
1143
  }
1087
1144
  }
1088
1145
  return findings;
@@ -1453,8 +1510,10 @@ function checkHtmlPatterns(html, corpora) {
1453
1510
  const purpleHexRe = /#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9|6366f1|764ba2|667eea)\b/gi;
1454
1511
  if (purpleHexRe.test(styleText)) {
1455
1512
  const purpleTextRe = /(?:(?:^|;)\s*color\s*:\s*(?:.*?)(?:#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9))|gradient.*?#(?:7c3aed|8b5cf6|a855f7|764ba2|667eea))/gi;
1456
- if (purpleTextRe.test(styleText)) {
1457
- findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet accent colors detected' });
1513
+ purpleTextRe.lastIndex = 0;
1514
+ const purpleMatch = purpleTextRe.exec(styleText);
1515
+ if (purpleMatch) {
1516
+ findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet accent colors detected', selector: enclosingCssSelector(styleText, purpleMatch.index + 1) || undefined });
1458
1517
  }
1459
1518
  }
1460
1519
 
@@ -1465,7 +1524,7 @@ function checkHtmlPatterns(html, corpora) {
1465
1524
  const start = Math.max(0, gm.index - 200);
1466
1525
  const context = styleText.substring(start, gm.index + gm[0].length + 200);
1467
1526
  if (/gradient/i.test(context)) {
1468
- findings.push({ id: 'gradient-text', snippet: 'background-clip: text + gradient' });
1527
+ findings.push({ id: 'gradient-text', snippet: 'background-clip: text + gradient', selector: enclosingCssSelector(styleText, gm.index) || undefined });
1469
1528
  break;
1470
1529
  }
1471
1530
  }
@@ -1531,7 +1590,7 @@ function checkHtmlPatterns(html, corpora) {
1531
1590
  const animationToken = bounceMatch[1]
1532
1591
  .split(/[,\s]+/)
1533
1592
  .find((part) => /bounce|elastic|wobble|jiggle|spring/i.test(part));
1534
- findings.push({ id: 'bounce-easing', snippet: `animation: ${animationToken || bounceMatch[1].trim()}` });
1593
+ findings.push({ id: 'bounce-easing', snippet: `animation: ${animationToken || bounceMatch[1].trim()}`, selector: enclosingCssSelector(styleText, bounceMatch.index) || undefined });
1535
1594
  }
1536
1595
 
1537
1596
  // Overshoot cubic-bezier
@@ -1540,7 +1599,7 @@ function checkHtmlPatterns(html, corpora) {
1540
1599
  while ((bm = bezierRe.exec(styleText)) !== null) {
1541
1600
  const y1 = parseFloat(bm[2]), y2 = parseFloat(bm[4]);
1542
1601
  if (y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1) {
1543
- findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${bm[1]}, ${bm[2]}, ${bm[3]}, ${bm[4]})` });
1602
+ findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${bm[1]}, ${bm[2]}, ${bm[3]}, ${bm[4]})`, selector: enclosingCssSelector(styleText, bm.index) || undefined });
1544
1603
  break;
1545
1604
  }
1546
1605
  }
@@ -1573,18 +1632,21 @@ function checkHtmlPatterns(html, corpora) {
1573
1632
 
1574
1633
  const glowHits = scanCssTextForGlow(styleText);
1575
1634
  if (glowHits.length > 0) {
1576
- findings.push({ id: 'dark-glow', snippet: glowHits[0].snippet });
1635
+ findings.push({ id: 'dark-glow', snippet: glowHits[0].snippet, selector: enclosingCssSelector(styleText, glowHits[0].index) || undefined });
1577
1636
  }
1578
1637
 
1579
1638
  // Radial-gradient background halo (gradient-drawn sibling of dark-glow)
1580
1639
  const haloHits = scanCssTextForRadialHalo(styleText);
1581
1640
  if (haloHits.length > 0) {
1582
- findings.push({ id: 'radial-halo', snippet: haloHits[0].snippet });
1641
+ findings.push({ id: 'radial-halo', snippet: haloHits[0].snippet, selector: enclosingCssSelector(styleText, haloHits[0].index) || undefined });
1583
1642
  }
1584
1643
 
1585
1644
  // --- Generated-UI tells: repeating-gradient stripes ---
1586
- if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(styleText)) {
1587
- findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
1645
+ {
1646
+ const stripesMatch = /repeating-(?:linear|radial|conic)-gradient\s*\(/i.exec(styleText);
1647
+ if (stripesMatch) {
1648
+ findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes', selector: enclosingCssSelector(styleText, stripesMatch.index) || undefined });
1649
+ }
1588
1650
  }
1589
1651
 
1590
1652
  // --- Generated-UI tells: two-axis grid-line background ---
@@ -1602,7 +1664,7 @@ function checkHtmlPatterns(html, corpora) {
1602
1664
  // whole gradient layers.
1603
1665
  const gridHits = scanCssTextForGridBackground(styleText);
1604
1666
  if (gridHits.length > 0) {
1605
- findings.push({ id: 'codex-grid-background', snippet: gridHits[0].snippet });
1667
+ findings.push({ id: 'codex-grid-background', snippet: gridHits[0].snippet, selector: enclosingCssSelector(styleText, gridHits[0].index) || undefined });
1606
1668
  }
1607
1669
 
1608
1670
  // --- Generated-copy tells: "X theater" framing copy ---
@@ -1622,8 +1684,11 @@ function checkHtmlPatterns(html, corpora) {
1622
1684
  // hover:rotate / hover:translate utility on an <img>. Each distinct
1623
1685
  // mechanism is its own finding.
1624
1686
  const imgHoverCss = /\bimg\b[^,{}]*:hover\b[^{}]*\{[^}]*\btransform\s*:\s*(?:scale|rotate|translate|matrix|skew)/i;
1625
- if (imgHoverCss.test(styleText)) {
1626
- findings.push({ id: 'image-hover-transform', snippet: 'img:hover { transform } rule' });
1687
+ {
1688
+ const imgHoverMatch = imgHoverCss.exec(styleText);
1689
+ if (imgHoverMatch) {
1690
+ findings.push({ id: 'image-hover-transform', snippet: 'img:hover { transform } rule', selector: enclosingCssSelector(styleText, imgHoverMatch.index + imgHoverMatch[0].indexOf('{') + 1) || undefined });
1691
+ }
1627
1692
  }
1628
1693
  const imgTagRe = /<img\b[^>]*\bclass\s*=\s*"([^"]*)"/gi;
1629
1694
  let im;
@@ -1670,7 +1735,46 @@ function readOwnBackgroundColor(el, computedStyle) {
1670
1735
  return bg;
1671
1736
  }
1672
1737
 
1673
- function resolveBackground(el, win, customPropMap) {
1738
+ // One element's background-color as the cascade walk sees it: computed style
1739
+ // first (with the modern-color fallback), then, in static mode only,
1740
+ // custom-prop resolution and the inline-shorthand peek. Shared by
1741
+ // resolveBackgroundInfo and resolveGradientStops so both walks read the same
1742
+ // surfaces.
1743
+ function readCascadeBackgroundColor(current, style, customPropMap) {
1744
+ let bg = parseRgb(style.backgroundColor) || parseAnyColor(style.backgroundColor);
1745
+ if (!DETECTOR_IS_BROWSER && (!bg || bg.a < 0.1)) {
1746
+ // The static engine can return literal "var(--X)" / "oklch(...)" strings.
1747
+ // Resolve through customPropMap so Tailwind v4 color tokens become RGB.
1748
+ if (customPropMap) {
1749
+ bg = parseColorResolved(style.backgroundColor, customPropMap);
1750
+ }
1751
+ if (!bg || bg.a < 0.1) {
1752
+ // Inline-style fallback for colors the static cascade did not surface
1753
+ // on backgroundColor.
1754
+ const rawStyle = current.getAttribute?.('style') || '';
1755
+ const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
1756
+ const inlineBg = bgMatch ? bgMatch[1].trim() : '';
1757
+ if (inlineBg && !/gradient/i.test(inlineBg) && !/url\s*\(/i.test(inlineBg)) {
1758
+ bg = parseColorResolved(inlineBg, customPropMap) || parseAnyColor(inlineBg);
1759
+ }
1760
+ }
1761
+ }
1762
+ return bg;
1763
+ }
1764
+
1765
+ // Walk up for the surface the element's text is painted on.
1766
+ //
1767
+ // Returns { color, unresolved }:
1768
+ // • color set — the effective surface, overlays composited in.
1769
+ // • unresolved: true — a layer on the way up paints a color this parser
1770
+ // cannot read, so the surface is unknown. Callers
1771
+ // must SKIP their contrast checks. Guessing white
1772
+ // here is what flooded dark themes with false
1773
+ // "on #ffffff" findings: one abstention costs a
1774
+ // single finding, one wrong guess costs a hundred.
1775
+ // • both null/false — no solid color, but a gradient or image is in
1776
+ // play; callers fall back to its color stops.
1777
+ function resolveBackgroundInfo(el, win, customPropMap) {
1674
1778
  let current = el;
1675
1779
  // Translucent layers (0.1 < a < 1) found on the way down to an opaque
1676
1780
  // base. A browser composites these over the base; the old behavior
@@ -1698,67 +1802,114 @@ function resolveBackground(el, win, customPropMap) {
1698
1802
  // body backgrounds.
1699
1803
  // Real browsers serialize wide-gamut computed values as oklab()/oklch()
1700
1804
  // (e.g. any color-mix() result), which plain parseRgb misses.
1701
- let bg = parseRgb(style.backgroundColor) || parseAnyColor(style.backgroundColor);
1702
- if (!DETECTOR_IS_BROWSER && (!bg || bg.a < 0.1)) {
1703
- // jsdom returns literal "var(--X)" / "oklch(...)" strings. Resolve
1704
- // through customPropMap so Tailwind v4 color tokens become RGB.
1705
- if (customPropMap) {
1706
- bg = parseColorResolved(style.backgroundColor, customPropMap);
1707
- }
1708
- if (!bg || bg.a < 0.1) {
1709
- // Inline-style fallback. jsdom doesn't decompose background
1710
- // shorthand, so colors set via inline style are otherwise invisible.
1711
- const rawStyle = current.getAttribute?.('style') || '';
1712
- const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
1713
- const inlineBg = bgMatch ? bgMatch[1].trim() : '';
1714
- if (inlineBg && !/gradient/i.test(inlineBg) && !/url\s*\(/i.test(inlineBg)) {
1715
- bg = parseColorResolved(inlineBg, customPropMap) || parseAnyColor(inlineBg);
1716
- }
1717
- }
1805
+ let bg = readCascadeBackgroundColor(current, style, customPropMap);
1806
+
1807
+ // `background-color: currentcolor` paints with the element's own text
1808
+ // color — real paint whose value we know. Real browsers resolve the
1809
+ // keyword before getComputedStyle output; jsdom hands it through
1810
+ // verbatim, and without this substitution the layer would read as
1811
+ // unparseable and force a needless abstention.
1812
+ if ((!bg || bg.a < 0.1) && /^currentcolor$/i.test(String(style.backgroundColor || '').trim())) {
1813
+ // The static cascade resolves var() text tokens before checks run, so
1814
+ // style.color is normally already an rgb string here; parseColorResolved
1815
+ // is defense in depth for any future caller that passes a live
1816
+ // customPropMap (it matches the text-color path in checkElementColors
1817
+ // and reduces to parseAnyColor when the map is null or absent).
1818
+ bg = parseRgb(style.color) || parseColorResolved(style.color, customPropMap);
1718
1819
  }
1719
1820
 
1720
1821
  if (bg && bg.a > 0.1) {
1721
- if (bg.a >= 0.99) return flatten(bg);
1822
+ if (bg.a >= 0.99) return { color: flatten(bg), unresolved: false };
1722
1823
  overlays.push(bg);
1824
+ } else if (!bg && !isNoPaintColorValue(style.backgroundColor)) {
1825
+ // This layer names a color we could not parse (a color space we do not
1826
+ // model, an unresolved var(), a syntax newer than the parser). It may
1827
+ // well be opaque, which would make every ancestor below it invisible —
1828
+ // so the surface is unknown and the walk stops here rather than
1829
+ // reporting an ancestor the visitor never sees.
1830
+ return { color: null, unresolved: true };
1723
1831
  }
1724
- // No solid bg-color at this level. If THIS level has a gradient/url
1725
- // with no underlying solid color we can read:
1726
- // • on body/html: assume white. Body-level gradients are almost
1727
- // always decorative texture (paper grain, noise) on top of a
1728
- // solid bg-color the page set via `background: var(--paper)`
1729
- // shorthand — which jsdom can't decompose into bg-color. The
1730
- // downstream gradient-stops fallback path produces catastrophic
1731
- // false positives in this case (gradient noise stops have
1732
- // accidental browns/blacks that look like card backgrounds).
1733
- // • on other elements: bail to null and let the caller fall back
1734
- // to gradient stops (gradient buttons / hero sections are real
1735
- // bgs worth checking against).
1832
+ // No solid bg-color at this level, but this level paints an image. CSS
1833
+ // stacks background-image layers first-on-top, so which layer leads
1834
+ // decides what the visitor sees:
1835
+ // • gradient on top — the gradient is the surface. Hand the caller a
1836
+ // null color so it falls back to the gradient's own stops (body
1837
+ // grounds, gradient buttons, hero sections).
1838
+ // • url() on top — the surface is an image whose pixels this engine
1839
+ // cannot read, and it may fully cover every layer and ancestor
1840
+ // beneath it. Same contract as an unparseable color: abstain, so
1841
+ // the gradient-stop fallback never measures a gradient the image
1842
+ // hides (the shipped miss: `url(photo), linear-gradient(...)`
1843
+ // reported low-contrast against the invisible gradient's stops).
1736
1844
  if (hasGradientOrUrl) {
1737
- if (current.tagName === 'BODY' || current.tagName === 'HTML') {
1738
- return flatten({ r: 255, g: 255, b: 255, a: 1 });
1845
+ const layers = splitTopLevelCommas(bgImage);
1846
+ const topPaintLayer = layers.find(
1847
+ (layer) => /gradient\s*\(/i.test(layer) || /url\s*\(/i.test(layer),
1848
+ );
1849
+ const gradientOnTop = !!topPaintLayer
1850
+ && /gradient\s*\(/i.test(topPaintLayer)
1851
+ && !/^\s*url\s*\(/i.test(topPaintLayer);
1852
+ if (!gradientOnTop) return { color: null, unresolved: true };
1853
+ // Gradient on top of a url() layer: the image shows through wherever
1854
+ // the gradient is not fully opaque, so a translucent wash like
1855
+ // `linear-gradient(rgba(0,0,0,.2), rgba(0,0,0,.2)), url(photo)` paints
1856
+ // a blend with pixels this engine cannot read. Only a gradient whose
1857
+ // every readable stop is opaque provably covers the image; otherwise
1858
+ // the surface is unknown — abstain rather than hand callers gradient
1859
+ // stops (or a stop average) the visitor never sees unmixed.
1860
+ const urlBeneath = layers.some(
1861
+ (layer) => layer !== topPaintLayer && /url\s*\(/i.test(layer),
1862
+ );
1863
+ if (urlBeneath) {
1864
+ const topStops = parseGradientColors(topPaintLayer);
1865
+ const provablyOpaque = topStops.length > 0 && topStops.every((s) => (s.a ?? 1) >= 0.99);
1866
+ if (!provablyOpaque) return { color: null, unresolved: true };
1739
1867
  }
1740
- return null;
1868
+ return { color: null, unresolved: false };
1741
1869
  }
1742
1870
  current = current.parentElement;
1743
1871
  }
1744
- return flatten({ r: 255, g: 255, b: 255, a: 1 });
1872
+ // Every layer up to the document root was genuinely see-through, so the
1873
+ // browser paints its default canvas. This is the ONLY case that earns the
1874
+ // white assumption.
1875
+ return { color: flatten({ r: 255, g: 255, b: 255, a: 1 }), unresolved: false };
1876
+ }
1877
+
1878
+ function resolveBackground(el, win, customPropMap) {
1879
+ return resolveBackgroundInfo(el, win, customPropMap).color;
1745
1880
  }
1746
1881
 
1747
1882
  // Walk parents looking for a gradient background and return its color stops.
1748
1883
  // Used as a fallback when resolveBackground() returns null because the
1749
1884
  // effective background is a gradient (no single solid color to compare against).
1885
+ // Translucent solid layers found between the element and the gradient (frosted
1886
+ // panels, glass washes) are composited over every stop, the same way
1887
+ // resolveBackground flattens them over a solid base — raw stops alone would
1888
+ // false-flag dark text on a light frosted wash over a dark gradient, and miss
1889
+ // the inverse.
1750
1890
  function resolveGradientStops(el, win, customPropMap) {
1751
1891
  let current = el;
1892
+ const overlays = [];
1752
1893
  while (current && current.nodeType === 1) {
1753
1894
  const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
1754
1895
  const bgImage = style.backgroundImage || '';
1896
+ // A url() layer anywhere in the stack — alone, or alongside a gradient in
1897
+ // the same declaration (a translucent wash over a texture photo) — paints
1898
+ // pixels the analytic walk cannot know. Measuring the gradient stops over
1899
+ // the wrong base flagged dark ink sitting on a bright gold-leaf image at
1900
+ // 2.6:1; skipping beats a wrong ratio, and the screenshot subsystem owns
1901
+ // image-backed text.
1902
+ if (bgImage && bgImage !== 'none' && /url\s*\(/i.test(bgImage)) return null;
1755
1903
  let stops = null;
1756
1904
  if (bgImage && bgImage !== 'none' && /gradient/i.test(bgImage)) {
1905
+ // parseGradientColors (shared) reads modern-space stops too — oklch,
1906
+ // color-mix and friends via balanced-paren token capture — so browser
1907
+ // computed values that keep the authored syntax stay measurable.
1757
1908
  const parsed = parseGradientColors(bgImage);
1758
1909
  if (parsed.length > 0) stops = parsed;
1759
1910
  }
1760
1911
  if (!stops && !DETECTOR_IS_BROWSER) {
1761
- // jsdom doesn't decompose `background:` shorthand — peek at the raw inline style
1912
+ // Static mode: peek at the raw inline style for gradients the cascade did not surface
1762
1913
  const rawStyle = current.getAttribute?.('style') || '';
1763
1914
  const bgMatch = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
1764
1915
  if (bgMatch && /gradient/i.test(bgMatch[1])) {
@@ -1766,7 +1917,23 @@ function resolveGradientStops(el, win, customPropMap) {
1766
1917
  if (parsed.length > 0) stops = parsed;
1767
1918
  }
1768
1919
  }
1769
- if (stops) return compositeGradientStops(stops, current, win, customPropMap);
1920
+ if (stops) {
1921
+ const composited = compositeGradientStops(stops, current, win, customPropMap);
1922
+ if (!composited || overlays.length === 0) return composited;
1923
+ return composited.map(stop => {
1924
+ let acc = stop;
1925
+ for (let i = overlays.length - 1; i >= 0; i--) acc = compositeColorOver(overlays[i], acc);
1926
+ return acc;
1927
+ });
1928
+ }
1929
+ const bg = readCascadeBackgroundColor(current, style, customPropMap);
1930
+ if (bg && bg.a > 0.1) {
1931
+ // An opaque surface above the gradient means the gradient never shows
1932
+ // through here; resolveBackground would have returned it, so reaching
1933
+ // this is defensive — bail rather than measure the wrong layer.
1934
+ if (bg.a >= 0.99) return null;
1935
+ overlays.push(bg);
1936
+ }
1770
1937
  current = current.parentElement;
1771
1938
  }
1772
1939
  return null;
@@ -1986,15 +2153,25 @@ function checkElementColorsDOM(el) {
1986
2153
  const rect = el.getBoundingClientRect();
1987
2154
  if (rect.width < 10 || rect.height < 10) return [];
1988
2155
  const style = getComputedStyle(el);
2156
+ // Invisible at rest: hidden scene variants (opacity-0 carousels, swap
2157
+ // decks) are not user-visible, and measuring their inherited colors against
2158
+ // whatever surface happens to sit behind the stack is noise, not audit.
2159
+ if (style.visibility === 'hidden' || effectiveOpacityDOM(el) <= 0.02) return [];
1989
2160
  const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
1990
2161
  const hasDirectText = directText.trim().length > 0;
1991
- let effectiveBg = resolveBackground(el);
2162
+ const bgInfo = resolveBackgroundInfo(el);
2163
+ let effectiveBg = bgInfo.color;
2164
+ // An unreadable surface anywhere up the chain: skip the gradient-stop
2165
+ // fallback too, so nothing downstream measures against a ground we never
2166
+ // resolved.
2167
+ let surfaceUnresolved = bgInfo.unresolved;
1992
2168
  let ownBg = readOwnBackgroundColor(el, style);
1993
2169
  if (!ownBg || (ownBg.a ?? 1) <= 0.5) {
1994
2170
  const pseudoSurface = readPseudoSurfaceDOM(el, rect);
1995
2171
  if (pseudoSurface) {
1996
2172
  ownBg = pseudoSurface;
1997
2173
  effectiveBg = pseudoSurface;
2174
+ surfaceUnresolved = false;
1998
2175
  }
1999
2176
  }
2000
2177
  return checkColors({
@@ -2006,8 +2183,8 @@ function checkElementColorsDOM(el) {
2006
2183
  // an oklch token near its own oklch background).
2007
2184
  textColor: parseRgb(style.color) || parseAnyColor(style.color),
2008
2185
  bgColor: ownBg,
2009
- effectiveBg,
2010
- effectiveBgStops: effectiveBg ? null : resolveGradientStops(el),
2186
+ effectiveBg: surfaceUnresolved ? null : effectiveBg,
2187
+ effectiveBgStops: surfaceUnresolved || effectiveBg ? null : resolveGradientStops(el),
2011
2188
  fontSize: parseFloat(style.fontSize) || 16,
2012
2189
  fontWeight: parseInt(style.fontWeight) || 400,
2013
2190
  hasDirectText,
@@ -2157,283 +2334,6 @@ function resolveVarRefs(raw, customPropMap, depth = 0) {
2157
2334
  });
2158
2335
  }
2159
2336
 
2160
- // OKLCH → sRGB conversion (Björn Ottosson's matrices). L in 0..1 (or %),
2161
- // C in 0..~0.4 typical, H in degrees. Returns clamped {r,g,b,a:1} in 0..255.
2162
- // Needed because jsdom doesn't compute oklch() values — getComputedStyle
2163
- // returns the literal "oklch(...)" string. Without this, the entire
2164
- // Tailwind v4 color palette (which is OKLCH-based) is invisible to the
2165
- // detector's contrast / color checks.
2166
- function oklchToRgb(L, C, H) {
2167
- const hRad = (H * Math.PI) / 180;
2168
- return oklabToRgb(L, C * Math.cos(hRad), C * Math.sin(hRad));
2169
- }
2170
-
2171
- function oklabToRgb(L, a, b) {
2172
- const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
2173
- const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
2174
- const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
2175
- const lc = l_ * l_ * l_, mc = m_ * m_ * m_, sc = s_ * s_ * s_;
2176
- const rLin = 4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc;
2177
- const gLin = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc;
2178
- const bLin = -0.0041960863 * lc - 0.7034186147 * mc + 1.7076147010 * sc;
2179
- const enc = (x) => {
2180
- const c = Math.max(0, Math.min(1, x));
2181
- return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
2182
- };
2183
- return {
2184
- r: Math.round(enc(rLin) * 255),
2185
- g: Math.round(enc(gLin) * 255),
2186
- b: Math.round(enc(bLin) * 255),
2187
- a: 1,
2188
- };
2189
- }
2190
-
2191
- function hslToRgb(h, s, l) {
2192
- h = ((h % 360) + 360) % 360;
2193
- const c = (1 - Math.abs(2 * l - 1)) * s;
2194
- const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
2195
- const m0 = l - c / 2;
2196
- const [r, g, b] =
2197
- h < 60 ? [c, x, 0] :
2198
- h < 120 ? [x, c, 0] :
2199
- h < 180 ? [0, c, x] :
2200
- h < 240 ? [0, x, c] :
2201
- h < 300 ? [x, 0, c] : [c, 0, x];
2202
- return {
2203
- r: Math.round((r + m0) * 255),
2204
- g: Math.round((g + m0) * 255),
2205
- b: Math.round((b + m0) * 255),
2206
- a: 1,
2207
- };
2208
- }
2209
-
2210
- function hwbToRgb(h, w, bl) {
2211
- if (w + bl >= 1) {
2212
- const g = Math.round((w / (w + bl)) * 255);
2213
- return { r: g, g, b: g, a: 1 };
2214
- }
2215
- const base = hslToRgb(h, 1, 0.5);
2216
- const mix = (c) => Math.round(((c / 255) * (1 - w - bl) + w) * 255);
2217
- return { r: mix(base.r), g: mix(base.g), b: mix(base.b), a: 1 };
2218
- }
2219
-
2220
- // Common CSS named colors — the handful that actually show up in generated
2221
- // UIs, not the full 148-name spec list. Includes the achromatic names so a
2222
- // named gray parses (and correctly reads as no-chroma) instead of being
2223
- // treated as an unknown color.
2224
- const CSS_NAMED_COLORS = {
2225
- black: { r: 0, g: 0, b: 0 },
2226
- white: { r: 255, g: 255, b: 255 },
2227
- gray: { r: 128, g: 128, b: 128 },
2228
- grey: { r: 128, g: 128, b: 128 },
2229
- silver: { r: 192, g: 192, b: 192 },
2230
- dimgray: { r: 105, g: 105, b: 105 },
2231
- darkgray: { r: 169, g: 169, b: 169 },
2232
- lightgray: { r: 211, g: 211, b: 211 },
2233
- gainsboro: { r: 220, g: 220, b: 220 },
2234
- whitesmoke: { r: 245, g: 245, b: 245 },
2235
- red: { r: 255, g: 0, b: 0 },
2236
- crimson: { r: 220, g: 20, b: 60 },
2237
- tomato: { r: 255, g: 99, b: 71 },
2238
- coral: { r: 255, g: 127, b: 80 },
2239
- salmon: { r: 250, g: 128, b: 114 },
2240
- orange: { r: 255, g: 165, b: 0 },
2241
- gold: { r: 255, g: 215, b: 0 },
2242
- yellow: { r: 255, g: 255, b: 0 },
2243
- olive: { r: 128, g: 128, b: 0 },
2244
- lime: { r: 0, g: 255, b: 0 },
2245
- green: { r: 0, g: 128, b: 0 },
2246
- teal: { r: 0, g: 128, b: 128 },
2247
- turquoise: { r: 64, g: 224, b: 208 },
2248
- cyan: { r: 0, g: 255, b: 255 },
2249
- aqua: { r: 0, g: 255, b: 255 },
2250
- skyblue: { r: 135, g: 206, b: 235 },
2251
- dodgerblue: { r: 30, g: 144, b: 255 },
2252
- blue: { r: 0, g: 0, b: 255 },
2253
- navy: { r: 0, g: 0, b: 128 },
2254
- indigo: { r: 75, g: 0, b: 130 },
2255
- rebeccapurple: { r: 102, g: 51, b: 153 },
2256
- purple: { r: 128, g: 0, b: 128 },
2257
- violet: { r: 238, g: 130, b: 238 },
2258
- orchid: { r: 218, g: 112, b: 214 },
2259
- magenta: { r: 255, g: 0, b: 255 },
2260
- fuchsia: { r: 255, g: 0, b: 255 },
2261
- hotpink: { r: 255, g: 105, b: 180 },
2262
- pink: { r: 255, g: 192, b: 203 },
2263
- maroon: { r: 128, g: 0, b: 0 },
2264
- };
2265
-
2266
- // Split a string on top-level commas (ignoring commas nested in parens).
2267
- function splitTopLevelCommas(str) {
2268
- const parts = [];
2269
- let depth = 0, start = 0;
2270
- for (let i = 0; i < str.length; i++) {
2271
- const ch = str[i];
2272
- if (ch === '(') depth++;
2273
- else if (ch === ')') depth = Math.max(0, depth - 1);
2274
- else if (ch === ',' && depth === 0) {
2275
- parts.push(str.slice(start, i).trim());
2276
- start = i + 1;
2277
- }
2278
- }
2279
- const tail = str.slice(start).trim();
2280
- if (tail) parts.push(tail);
2281
- return parts;
2282
- }
2283
-
2284
- // Evaluate a CSS color-mix() expression to {r,g,b,a}. Returns null when
2285
- // the expression can't be resolved (unresolved var(), unknown colors).
2286
- //
2287
- // Mixing is done with premultiplied alpha in sRGB regardless of the
2288
- // declared interpolation space. That is exact for the dominant generated-UI
2289
- // pattern — `color-mix(in oklab, <color> N%, transparent)` — where the
2290
- // result is simply <color> at alpha N% in ANY rectangular space, and a
2291
- // close-enough approximation for opaque-opaque mixes (the detector only
2292
- // consumes these values for contrast/chroma thresholds, not for display).
2293
- function parseColorMix(str) {
2294
- const m = String(str).trim().match(/^color-mix\(/i);
2295
- if (!m) return null;
2296
- // Balanced-paren capture of the arguments.
2297
- let depth = 0, end = -1;
2298
- const open = str.indexOf('(');
2299
- for (let i = open; i < str.length; i++) {
2300
- if (str[i] === '(') depth++;
2301
- else if (str[i] === ')') { depth--; if (depth === 0) { end = i; break; } }
2302
- }
2303
- if (end < 0) return null;
2304
- const args = splitTopLevelCommas(str.slice(open + 1, end));
2305
- if (args.length !== 3 || !/^in\s/i.test(args[0])) return null;
2306
-
2307
- const parseComponent = (component) => {
2308
- // Percentage may lead or trail the color per spec.
2309
- let pct = null;
2310
- let colorStr = component;
2311
- const trail = component.match(/\s+([\d.]+)%$/);
2312
- const lead = component.match(/^([\d.]+)%\s+/);
2313
- if (trail) { pct = parseFloat(trail[1]); colorStr = component.slice(0, trail.index).trim(); }
2314
- else if (lead) { pct = parseFloat(lead[1]); colorStr = component.slice(lead[0].length).trim(); }
2315
- let color;
2316
- if (/^transparent$/i.test(colorStr)) color = { r: 0, g: 0, b: 0, a: 0 };
2317
- else color = parseAnyColor(colorStr);
2318
- if (!color) return null;
2319
- return { color, pct };
2320
- };
2321
-
2322
- const c1 = parseComponent(args[1]);
2323
- const c2 = parseComponent(args[2]);
2324
- if (!c1 || !c2) return null;
2325
- let p1 = c1.pct, p2 = c2.pct;
2326
- if (p1 == null && p2 == null) { p1 = 50; p2 = 50; }
2327
- else if (p1 == null) p1 = 100 - p2;
2328
- else if (p2 == null) p2 = 100 - p1;
2329
- const sum = p1 + p2;
2330
- if (sum <= 0) return null;
2331
- // Per spec: weights normalize to sum; when sum < 100 the result alpha is
2332
- // additionally scaled by sum/100.
2333
- const w1 = p1 / sum, w2 = p2 / sum;
2334
- const alphaScale = sum < 100 ? sum / 100 : 1;
2335
- const a1 = c1.color.a ?? 1, a2 = c2.color.a ?? 1;
2336
- const a = (a1 * w1 + a2 * w2) * alphaScale;
2337
- if (a <= 0) return { r: 0, g: 0, b: 0, a: 0 };
2338
- const mix = (ch) => Math.round((c1.color[ch] * a1 * w1 + c2.color[ch] * a2 * w2) / (a1 * w1 + a2 * w2));
2339
- return { r: mix('r'), g: mix('g'), b: mix('b'), a: Math.min(1, a) };
2340
- }
2341
-
2342
- // Composite a translucent color over an opaque(ish) base (simple
2343
- // source-over in sRGB). Returns an opaque {r,g,b,a:1}.
2344
- function compositeColorOver(top, base) {
2345
- const a = top.a ?? 1;
2346
- return {
2347
- r: Math.round(top.r * a + base.r * (1 - a)),
2348
- g: Math.round(top.g * a + base.g * (1 - a)),
2349
- b: Math.round(top.b * a + base.b * (1 - a)),
2350
- a: 1,
2351
- };
2352
- }
2353
-
2354
- // Extended color parser: rgb/rgba/hex/oklch/oklab/hsl/hwb/color-mix/common
2355
- // named colors. Returns null on no match. Use this when the input might be
2356
- // any CSS color form; use plain parseRgb when you only expect computed rgb()
2357
- // values from real browsers.
2358
- function parseAnyColor(s) {
2359
- if (!s || typeof s !== 'string') return null;
2360
- const str = s.trim();
2361
- if (str === 'transparent' || str === 'currentcolor' || str === 'inherit') return null;
2362
- if (/^color-mix\(/i.test(str)) return parseColorMix(str);
2363
- let m;
2364
- m = str.match(/rgba?\(\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)(?:\s*[,/]\s*([\d.]+))?\s*\)/);
2365
- if (m) return { r: Math.round(+m[1]), g: Math.round(+m[2]), b: Math.round(+m[3]), a: m[4] !== undefined ? +m[4] : 1 };
2366
- m = str.match(/^#([0-9a-f]{3,8})$/i);
2367
- if (m) {
2368
- const h = m[1];
2369
- if (h.length === 3 || h.length === 4) {
2370
- return {
2371
- r: parseInt(h[0] + h[0], 16),
2372
- g: parseInt(h[1] + h[1], 16),
2373
- b: parseInt(h[2] + h[2], 16),
2374
- a: h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1,
2375
- };
2376
- }
2377
- if (h.length === 6 || h.length === 8) {
2378
- return {
2379
- r: parseInt(h.slice(0, 2), 16),
2380
- g: parseInt(h.slice(2, 4), 16),
2381
- b: parseInt(h.slice(4, 6), 16),
2382
- a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
2383
- };
2384
- }
2385
- }
2386
- // OKLCH parser. Tailwind v4's CSS minifier squishes the space after
2387
- // `%` ("21.5%.02 50"), so the separator between L and C may be absent.
2388
- // Match L (with optional %), then C and H separated permissively.
2389
- m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
2390
- if (m) {
2391
- const Lnum = parseFloat(m[1]);
2392
- const L = m[2] === '%' ? Lnum / 100 : Lnum;
2393
- const rgb = oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]));
2394
- if (m[5] !== undefined) {
2395
- const alpha = parseFloat(m[5]);
2396
- rgb.a = m[6] === '%' ? alpha / 100 : alpha;
2397
- }
2398
- return rgb;
2399
- }
2400
- // OKLAB — a/b are signed axes; percentages map 100% → 0.4.
2401
- m = str.match(/oklab\(\s*([\d.]+)(%?)\s+(-?[\d.]+)(%?)\s+(-?[\d.]+)(%?)(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
2402
- if (m) {
2403
- const L = m[2] === '%' ? parseFloat(m[1]) / 100 : parseFloat(m[1]);
2404
- const a = m[4] === '%' ? parseFloat(m[3]) * 0.004 : parseFloat(m[3]);
2405
- const b = m[6] === '%' ? parseFloat(m[5]) * 0.004 : parseFloat(m[5]);
2406
- const rgb = oklabToRgb(L, a, b);
2407
- if (m[7] !== undefined) {
2408
- const alpha = parseFloat(m[7]);
2409
- rgb.a = m[8] === '%' ? alpha / 100 : alpha;
2410
- }
2411
- return rgb;
2412
- }
2413
- // HSL/HSLA — comma or space syntax, optional deg on hue.
2414
- m = str.match(/hsla?\(\s*(-?[\d.]+)(?:deg)?\s*[,\s]\s*([\d.]+)%\s*[,\s]\s*([\d.]+)%(?:\s*[,/]\s*([\d.]+)(%)?)?\s*\)/i);
2415
- if (m) {
2416
- const rgb = hslToRgb(parseFloat(m[1]), parseFloat(m[2]) / 100, parseFloat(m[3]) / 100);
2417
- if (m[4] !== undefined) {
2418
- const alpha = parseFloat(m[4]);
2419
- rgb.a = m[5] === '%' ? alpha / 100 : alpha;
2420
- }
2421
- return rgb;
2422
- }
2423
- // HWB — hue whiteness% blackness%.
2424
- m = str.match(/hwb\(\s*(-?[\d.]+)(?:deg)?\s+([\d.]+)%\s+([\d.]+)%(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
2425
- if (m) {
2426
- const rgb = hwbToRgb(parseFloat(m[1]), parseFloat(m[2]) / 100, parseFloat(m[3]) / 100);
2427
- if (m[4] !== undefined) {
2428
- const alpha = parseFloat(m[4]);
2429
- rgb.a = m[5] === '%' ? alpha / 100 : alpha;
2430
- }
2431
- return rgb;
2432
- }
2433
- const named = CSS_NAMED_COLORS[str.toLowerCase()];
2434
- if (named) return { ...named, a: 1 };
2435
- return null;
2436
- }
2437
2337
 
2438
2338
  // Resolve var() refs in a color string (via customPropMap), then parse.
2439
2339
  // Returns null on any failure. Used in jsdom-mode paths where
@@ -2796,9 +2696,20 @@ function checkElementGlowDOM(el) {
2796
2696
  if (!boxShadow && !textShadow) return [];
2797
2697
  // Use parent's background — glow radiates outward, so the surrounding context matters
2798
2698
  // If resolveBackground returns null (gradient), try to infer from the gradient colors
2799
- let parentBg = el.parentElement ? resolveBackground(el.parentElement) : resolveBackground(el);
2800
- if (!parentBg) {
2801
- // Gradient background — sample its colors to determine if it's dark
2699
+ const parentBgInfo = resolveBackgroundInfo(el.parentElement || el);
2700
+ // Unknown surface (an unreadable layer on the way up): skip only the
2701
+ // gradient hunt below, which would walk PAST that layer and score the
2702
+ // glow against a background the visitor never sees. checkGlow still runs
2703
+ // with a null surface: the zero-offset chromatic halo tell holds on ANY
2704
+ // background, and the static loop already passes the unresolved walk's
2705
+ // null color straight through (detect-html.mjs uses resolveBackground).
2706
+ let parentBg = parentBgInfo.color;
2707
+ if (!parentBg && !parentBgInfo.unresolved) {
2708
+ // Gradient background — sample its colors to determine if it's dark.
2709
+ // Modern-syntax parsing matters here: body-level gradients now reach this
2710
+ // fallback in browser mode, and their stops usually serialize as oklch —
2711
+ // which the shared parseGradientColors reads via its color-function
2712
+ // token capture.
2802
2713
  let cur = el.parentElement;
2803
2714
  while (cur && cur.nodeType === 1) {
2804
2715
  const bgImage = getComputedStyle(cur).backgroundImage || '';
@@ -2846,10 +2757,13 @@ function checkElementAIPaletteDOM(el) {
2846
2757
  const hue = getHue(textColor);
2847
2758
  const isAIPalette = (hue >= 160 && hue <= 200) || (hue >= 260 && hue <= 310);
2848
2759
  if (isAIPalette) {
2849
- const parentBg = el.parentElement ? resolveBackground(el.parentElement) : null;
2850
- // Also check gradient parents
2851
- let effectiveBg = parentBg;
2852
- if (!effectiveBg) {
2760
+ const parentBgInfo = el.parentElement
2761
+ ? resolveBackgroundInfo(el.parentElement)
2762
+ : { color: null, unresolved: false };
2763
+ // Unknown surface: leave effectiveBg null (no finding) rather than
2764
+ // hunting gradient ancestors past a layer we could not read.
2765
+ let effectiveBg = parentBgInfo.color;
2766
+ if (!effectiveBg && !parentBgInfo.unresolved) {
2853
2767
  let cur = el.parentElement;
2854
2768
  while (cur && cur.nodeType === 1) {
2855
2769
  const gi = getComputedStyle(cur).backgroundImage || '';
@@ -3644,10 +3558,19 @@ function checkElementBorders(tag, style, overrides, resolvedRadius, el = null) {
3644
3558
  }
3645
3559
 
3646
3560
  function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInheritRule) {
3561
+ // Invisible at rest, static twin of the browser walk's skip: opacity does
3562
+ // not inherit, so walk ancestors multiplying declared opacity down.
3563
+ if (style.visibility === 'hidden') return [];
3564
+ let effOpacity = 1;
3565
+ for (let cur = el; cur && cur.nodeType === 1 && effOpacity > 0.02; cur = cur.parentElement) {
3566
+ effOpacity *= parseFloat(window.getComputedStyle(cur).opacity || '1');
3567
+ }
3568
+ if (effOpacity <= 0.02) return [];
3647
3569
  const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
3648
3570
  const hasDirectText = directText.trim().length > 0;
3649
3571
 
3650
- const effectiveBg = resolveBackground(el, window, customPropMap);
3572
+ const bgInfo = resolveBackgroundInfo(el, window, customPropMap);
3573
+ const effectiveBg = bgInfo.color;
3651
3574
  // jsdom returns literal "var(--X)" / "oklch(...)" for color, so plain
3652
3575
  // parseRgb misses Tailwind-tokenized text colors. Resolve through the
3653
3576
  // customPropMap first; fall back to parseRgb for vanilla rgb() pages.
@@ -3693,11 +3616,13 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
3693
3616
  // element itself has no usable own background, that pseudo is the real
3694
3617
  // surface for contrast purposes.
3695
3618
  let finalEffectiveBg = effectiveBg;
3619
+ let surfaceUnresolved = bgInfo.unresolved;
3696
3620
  if ((!ownBg || (ownBg.a ?? 1) <= 0.5) && typeof window.getPseudoSurface === 'function') {
3697
3621
  const pseudoSurface = window.getPseudoSurface(el);
3698
3622
  if (pseudoSurface) {
3699
3623
  ownBg = pseudoSurface;
3700
3624
  finalEffectiveBg = pseudoSurface;
3625
+ surfaceUnresolved = false;
3701
3626
  }
3702
3627
  }
3703
3628
 
@@ -3705,8 +3630,9 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
3705
3630
  tag,
3706
3631
  textColor,
3707
3632
  bgColor: ownBg,
3708
- effectiveBg: finalEffectiveBg,
3709
- effectiveBgStops: finalEffectiveBg ? null : resolveGradientStops(el, window, customPropMap),
3633
+ // Unknown surface: hand the checks nothing rather than a guess.
3634
+ effectiveBg: surfaceUnresolved ? null : finalEffectiveBg,
3635
+ effectiveBgStops: surfaceUnresolved || finalEffectiveBg ? null : resolveGradientStops(el, window, customPropMap),
3710
3636
  fontSize: parseFloat(style.fontSize) || 16,
3711
3637
  fontWeight: parseInt(style.fontWeight) || 400,
3712
3638
  hasDirectText,
@@ -4802,6 +4728,11 @@ function isRenderedForBrowserRule(el) {
4802
4728
  function checkElementTextOverflowDOM(el) {
4803
4729
  const tag = el.tagName.toLowerCase();
4804
4730
  if (TEXT_OVERFLOW_SKIP_TAGS.has(tag)) return [];
4731
+ // scrollWidth/clientWidth are CSS box-model metrics; on SVG content Chrome
4732
+ // returns arbitrary non-zero values for both (a <text> reported 78/48 while
4733
+ // its rendered length sat comfortably inside its box), so the delta is
4734
+ // noise, not overflow. SVG clips to its own viewport anyway.
4735
+ if (el.namespaceURI === 'http://www.w3.org/2000/svg') return [];
4805
4736
  if (!isRenderedForBrowserRule(el)) return [];
4806
4737
  // Only the element that actually owns overflowing text — not its ancestors,
4807
4738
  // which inherit a wider scrollWidth from the spilling descendant.
@@ -5186,6 +5117,22 @@ function isPaintedForOcclusion(el) {
5186
5117
  // path is pure geometry and runs anywhere on the page.
5187
5118
  const OCCLUSION_TEXT_SKIP_TAGS = new Set(['script', 'style', 'noscript', 'template', 'title']);
5188
5119
 
5120
+ // An element whose effective opacity multiplies out to ~0 paints nothing at
5121
+ // rest: it is not user-visible, so visual findings on it (contrast, occlusion)
5122
+ // measure a state nobody sees. Browser-only — the walk needs live computed
5123
+ // styles. Cycling scenes that fade such elements in later are the screenshot
5124
+ // subsystem's territory, not the analytic walk's.
5125
+ function effectiveOpacityDOM(el) {
5126
+ let o = 1;
5127
+ // Walk all the way through body and html: `body { opacity: 0 }` page-fade
5128
+ // wrappers hide every descendant just as thoroughly as a local wrapper.
5129
+ for (let cur = el; cur && cur.nodeType === 1; cur = cur.parentElement) {
5130
+ o *= parseFloat(getComputedStyle(cur).opacity || '1');
5131
+ if (o <= 0.02) return 0;
5132
+ }
5133
+ return o;
5134
+ }
5135
+
5189
5136
  function checkTextOcclusionDOM() {
5190
5137
  const findings = [];
5191
5138
  const seenVictims = new Set();
@@ -5213,6 +5160,11 @@ function checkTextOcclusionDOM() {
5213
5160
  }
5214
5161
  return false;
5215
5162
  };
5163
+ // The classic occluder shape this rules out is an opacity-0 interaction
5164
+ // layer — a range scrubber stretched over a before/after comparison — which
5165
+ // elementFromPoint still returns and whose UA background-color otherwise
5166
+ // reads as an opaque box.
5167
+ const effectiveOpacity = effectiveOpacityDOM;
5216
5168
 
5217
5169
  // Collect renderable text owners in / near the first viewport for the
5218
5170
  // elementFromPoint probe. SVG <text> counts too.
@@ -5225,6 +5177,7 @@ function checkTextOcclusionDOM() {
5225
5177
  const text = inSvg ? (el.textContent || '').trim() : elementDirectText(el);
5226
5178
  if (text.length < 2) continue;
5227
5179
  if (!isPaintedForOcclusion(el)) continue;
5180
+ if (effectiveOpacity(el) <= 0.02) continue;
5228
5181
  let rect; try { rect = el.getBoundingClientRect(); } catch { continue; }
5229
5182
  if (rect.width < 6 || rect.height < 6) continue;
5230
5183
  // Viewport-bound probe: keep text whose box overlaps the live viewport.
@@ -5258,6 +5211,7 @@ function checkTextOcclusionDOM() {
5258
5211
  if (top === el || el.contains(top) || top.contains(el)) continue;
5259
5212
  const topCs = getComputedStyle(top);
5260
5213
  if (isFloated(topCs) || isMarqueeish(top, topCs) || isPinnedOverlay(top)) continue;
5214
+ if (effectiveOpacity(top) <= 0.02) continue;
5261
5215
  const topTag = top.tagName.toLowerCase();
5262
5216
  // Text sitting under a raw image/video is contrast territory (deduped
5263
5217
  // against the pixel low-contrast rule); leave those alone here.
@@ -5468,6 +5422,7 @@ export {
5468
5422
  CSS_NAMED_COLORS,
5469
5423
  checkBorders,
5470
5424
  isEmojiOnlyText,
5425
+ scopedIgnoreActive,
5471
5426
  checkColors,
5472
5427
  checkHoverContrast,
5473
5428
  checkElementHoverContrast,
@@ -5497,6 +5452,7 @@ export {
5497
5452
  checkHtmlPatterns,
5498
5453
  readOwnBackgroundColor,
5499
5454
  resolveBackground,
5455
+ resolveBackgroundInfo,
5500
5456
  resolveGradientStops,
5501
5457
  parseRadiusToPx,
5502
5458
  resolveBorderRadiusPx,