impeccable 3.4.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
  }
@@ -1062,10 +1119,12 @@ function collectMarqueeKeyframes(content) {
1062
1119
  // bound to a keyframe loop that travels a large horizontal distance.
1063
1120
  // Rotation/opacity animations never qualify (no X travel); JS-driven
1064
1121
  // carousels with user controls have no infinite CSS X-loop to match.
1065
- function scanCssTextForMarquee(content) {
1122
+ // `content` is CSS-bearing text; `markup` (defaulting to the same string
1123
+ // for single-corpus callers) is where the <marquee> tag itself lives.
1124
+ function scanCssTextForMarquee(content, markup = content) {
1066
1125
  const findings = [];
1067
- if (/<marquee\b/i.test(content)) {
1068
- findings.push({ id: 'marquee', snippet: '<marquee> element' });
1126
+ if (/<marquee\b/i.test(markup)) {
1127
+ findings.push({ id: 'marquee', snippet: '<marquee> element', selector: 'marquee' });
1069
1128
  }
1070
1129
  const marqueeKeyframes = collectMarqueeKeyframes(content);
1071
1130
  if (marqueeKeyframes.size === 0) return findings;
@@ -1080,7 +1139,7 @@ function scanCssTextForMarquee(content) {
1080
1139
  const key = `${selector} ${name}`;
1081
1140
  if (seen.has(key)) continue;
1082
1141
  seen.add(key);
1083
- findings.push({ id: 'marquee', snippet: `${selector} — infinite horizontal loop animation "${name}"` });
1142
+ findings.push({ id: 'marquee', snippet: `${selector} — infinite horizontal loop animation "${name}"`, selector });
1084
1143
  }
1085
1144
  }
1086
1145
  return findings;
@@ -1243,10 +1302,14 @@ function selectorHitsLandmark(content, selector, ranges) {
1243
1302
  // element sits inside a header/nav landmark is the hero liveness cliché
1244
1303
  // and is promoted to error severity; occurrences elsewhere keep the
1245
1304
  // registry default severity.
1246
- function scanCssTextForPulsingDot(content) {
1305
+ //
1306
+ // `content` is CSS-bearing text (rules and keyframes); `markup` — defaulting
1307
+ // to the same string for single-corpus callers like the regex source
1308
+ // engine — is where landmark ranges and Tailwind class attributes live.
1309
+ function scanCssTextForPulsingDot(content, markup = content) {
1247
1310
  const customProps = collectCssCustomProps(content);
1248
1311
  const keyframes = collectPulseKeyframes(content);
1249
- const heroRanges = landmarkSourceRanges(content);
1312
+ const heroRanges = landmarkSourceRanges(markup);
1250
1313
  const findings = [];
1251
1314
  const seen = new Set();
1252
1315
 
@@ -1295,7 +1358,7 @@ function scanCssTextForPulsingDot(content) {
1295
1358
 
1296
1359
  if (seen.has(selector)) continue;
1297
1360
  seen.add(selector);
1298
- const inLandmark = selectorHitsLandmark(content, selector, heroRanges);
1361
+ const inLandmark = selectorHitsLandmark(markup, selector, heroRanges);
1299
1362
  findings.push({
1300
1363
  id: 'pulsing-dot',
1301
1364
  snippet: `${selector} — ${w}x${h}px dot with infinite "${pulseName}" animation${inLandmark ? ' in header/nav' : ''}`,
@@ -1305,10 +1368,11 @@ function scanCssTextForPulsingDot(content) {
1305
1368
  }
1306
1369
 
1307
1370
  // Tailwind utilities: animate-ping / animate-pulse on a tiny rounded-full
1308
- // element declared entirely in the class attribute.
1371
+ // element declared entirely in the class attribute. Scanned in the markup
1372
+ // corpus so the match index lines up with the landmark ranges.
1309
1373
  const classRe = /class\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
1310
1374
  let cm;
1311
- while ((cm = classRe.exec(content)) !== null) {
1375
+ while ((cm = classRe.exec(markup)) !== null) {
1312
1376
  const cls = cm[1] || cm[2] || '';
1313
1377
  const anim = cls.match(/\banimate-(ping|pulse)\b/);
1314
1378
  if (!anim) continue;
@@ -1389,36 +1453,82 @@ function scanHtmlForShapeAssembledIllustration(html) {
1389
1453
  return findings;
1390
1454
  }
1391
1455
 
1456
+ // Scoped scan corpora for the page-level pattern checks. CSS-property
1457
+ // regexes run over the whole source string fire on documentation ABOUT
1458
+ // css — `<code>background-clip: text</code>` prose, <pre> samples, HTML
1459
+ // comments — so the checks scan only the strings that actually style the
1460
+ // page:
1461
+ // styleText — <style> block contents plus style="…" attribute values.
1462
+ // Attribute values keep their `style="…"` form so block-scoped
1463
+ // scanners (grid background) keep treating each attribute as one
1464
+ // declaration block, exactly as they did against raw source. Engines
1465
+ // that already read more CSS (linked stylesheets) prepend it.
1466
+ // classText — class attribute values, for utility-class scans.
1467
+ // Markup-shaped checks (inline <svg> scenes, <img> tags, <marquee>,
1468
+ // landmark ranges) and rendered-text checks (theater phrases) keep the
1469
+ // full source. This extraction serves callers without a parsed document
1470
+ // (the browser bundle scanning outerHTML); attribute reads are tag-scoped
1471
+ // so escaped code samples (&lt;div style="…"&gt;) never contribute. The
1472
+ // static engine passes richer corpora built from its parsed document.
1473
+ // Bare CSS input (no markup at all) is its own style text, which keeps
1474
+ // direct checkHtmlPatterns(css) callers behaving as before.
1475
+ function buildHtmlPatternCorpora(html) {
1476
+ const source = String(html || '');
1477
+ if (!/<[a-zA-Z!/]/.test(source)) {
1478
+ return { styleText: source, classText: source };
1479
+ }
1480
+ const styleParts = [];
1481
+ const classParts = [];
1482
+ const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
1483
+ let m;
1484
+ while ((m = styleBlockRe.exec(source)) !== null) styleParts.push(m[1]);
1485
+ const tagRe = /<[a-zA-Z][^>]*>/g;
1486
+ while ((m = tagRe.exec(source)) !== null) {
1487
+ const tag = m[0];
1488
+ const sm = tag.match(/\bstyle\s*=\s*("[^"]*"|'[^']*')/i);
1489
+ if (sm) styleParts.push(`style=${sm[1]}`);
1490
+ const cm = tag.match(/\bclass\s*=\s*(?:"([^"]*)"|'([^']*)')/i);
1491
+ if (cm) classParts.push(cm[1] ?? cm[2] ?? '');
1492
+ }
1493
+ return { styleText: styleParts.join('\n'), classText: classParts.join('\n') };
1494
+ }
1495
+
1392
1496
  /**
1393
1497
  * Regex-on-HTML checks shared between browser and Node page-level detection.
1394
- * These don't need DOM access, just the raw HTML string.
1498
+ * These don't need DOM access, just the raw HTML string. CSS-property and
1499
+ * utility-class patterns scan the scoped corpora (styleText / classText —
1500
+ * see buildHtmlPatternCorpora) so prose about css never flags; only the
1501
+ * markup-shaped and rendered-text checks read the full source.
1395
1502
  */
1396
- function checkHtmlPatterns(html) {
1503
+ function checkHtmlPatterns(html, corpora) {
1504
+ const { styleText, classText } = corpora || buildHtmlPatternCorpora(html);
1397
1505
  const findings = [];
1398
1506
 
1399
1507
  // --- Color ---
1400
1508
 
1401
1509
  // AI color palette: purple/violet
1402
1510
  const purpleHexRe = /#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9|6366f1|764ba2|667eea)\b/gi;
1403
- if (purpleHexRe.test(html)) {
1511
+ if (purpleHexRe.test(styleText)) {
1404
1512
  const purpleTextRe = /(?:(?:^|;)\s*color\s*:\s*(?:.*?)(?:#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9))|gradient.*?#(?:7c3aed|8b5cf6|a855f7|764ba2|667eea))/gi;
1405
- if (purpleTextRe.test(html)) {
1406
- 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 });
1407
1517
  }
1408
1518
  }
1409
1519
 
1410
1520
  // Gradient text (background-clip: text + gradient)
1411
1521
  const gradientRe = /(?:-webkit-)?background-clip\s*:\s*text/gi;
1412
1522
  let gm;
1413
- while ((gm = gradientRe.exec(html)) !== null) {
1523
+ while ((gm = gradientRe.exec(styleText)) !== null) {
1414
1524
  const start = Math.max(0, gm.index - 200);
1415
- const context = html.substring(start, gm.index + gm[0].length + 200);
1525
+ const context = styleText.substring(start, gm.index + gm[0].length + 200);
1416
1526
  if (/gradient/i.test(context)) {
1417
- 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 });
1418
1528
  break;
1419
1529
  }
1420
1530
  }
1421
- if (/\bbg-clip-text\b/.test(html) && /\bbg-gradient-to-/.test(html)) {
1531
+ if (/\bbg-clip-text\b/.test(classText) && /\bbg-gradient-to-/.test(classText)) {
1422
1532
  findings.push({ id: 'gradient-text', snippet: 'bg-clip-text + bg-gradient (Tailwind)' });
1423
1533
  }
1424
1534
 
@@ -1427,10 +1537,10 @@ function checkHtmlPatterns(html) {
1427
1537
  // Side-tab accent stripe drawn as an absolutely-positioned pseudo-element
1428
1538
  // (no border property involved, so the element-level border checks and
1429
1539
  // the border-left regexes never see it).
1430
- findings.push(...scanCssTextForPseudoStripe(html));
1540
+ findings.push(...scanCssTextForPseudoStripe(styleText));
1431
1541
 
1432
1542
  // Side-tab accent stripe drawn as a single-edge inset box-shadow.
1433
- findings.push(...scanCssTextForInsetStripe(html));
1543
+ findings.push(...scanCssTextForInsetStripe(styleText));
1434
1544
 
1435
1545
  // --- Layout ---
1436
1546
 
@@ -1438,20 +1548,20 @@ function checkHtmlPatterns(html) {
1438
1548
  const spacingValues = [];
1439
1549
  const spacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*(\d+)px/gi;
1440
1550
  let sm;
1441
- while ((sm = spacingRe.exec(html)) !== null) {
1551
+ while ((sm = spacingRe.exec(styleText)) !== null) {
1442
1552
  const v = parseInt(sm[1], 10);
1443
1553
  if (v > 0 && v < 200) spacingValues.push(v);
1444
1554
  }
1445
1555
  const gapRe = /gap\s*:\s*(\d+)px/gi;
1446
- while ((sm = gapRe.exec(html)) !== null) {
1556
+ while ((sm = gapRe.exec(styleText)) !== null) {
1447
1557
  spacingValues.push(parseInt(sm[1], 10));
1448
1558
  }
1449
1559
  const twSpaceRe = /\b(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-(\d+)\b/g;
1450
- while ((sm = twSpaceRe.exec(html)) !== null) {
1560
+ while ((sm = twSpaceRe.exec(classText)) !== null) {
1451
1561
  spacingValues.push(parseInt(sm[1], 10) * 4);
1452
1562
  }
1453
1563
  const remSpacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*([\d.]+)rem/gi;
1454
- while ((sm = remSpacingRe.exec(html)) !== null) {
1564
+ while ((sm = remSpacingRe.exec(styleText)) !== null) {
1455
1565
  const v = Math.round(parseFloat(sm[1]) * 16);
1456
1566
  if (v > 0 && v < 200) spacingValues.push(v);
1457
1567
  }
@@ -1475,21 +1585,21 @@ function checkHtmlPatterns(html) {
1475
1585
 
1476
1586
  // Bounce/elastic animation names
1477
1587
  const bounceRe = /animation(?:-name)?\s*:\s*([^;{}]*(?:bounce|elastic|wobble|jiggle|spring)[^;{}]*)/gi;
1478
- const bounceMatch = bounceRe.exec(html);
1588
+ const bounceMatch = bounceRe.exec(styleText);
1479
1589
  if (bounceMatch) {
1480
1590
  const animationToken = bounceMatch[1]
1481
1591
  .split(/[,\s]+/)
1482
1592
  .find((part) => /bounce|elastic|wobble|jiggle|spring/i.test(part));
1483
- 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 });
1484
1594
  }
1485
1595
 
1486
1596
  // Overshoot cubic-bezier
1487
1597
  const bezierRe = /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g;
1488
1598
  let bm;
1489
- while ((bm = bezierRe.exec(html)) !== null) {
1599
+ while ((bm = bezierRe.exec(styleText)) !== null) {
1490
1600
  const y1 = parseFloat(bm[2]), y2 = parseFloat(bm[4]);
1491
1601
  if (y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1) {
1492
- 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 });
1493
1603
  break;
1494
1604
  }
1495
1605
  }
@@ -1497,7 +1607,7 @@ function checkHtmlPatterns(html) {
1497
1607
  // Layout property transitions
1498
1608
  const transRe = /transition(?:-property)?\s*:\s*([^;{}]+)/gi;
1499
1609
  let tm;
1500
- while ((tm = transRe.exec(html)) !== null) {
1610
+ while ((tm = transRe.exec(styleText)) !== null) {
1501
1611
  const val = tm[1].toLowerCase();
1502
1612
  if (/\ball\b/.test(val)) continue;
1503
1613
  const found = val.match(/\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding(?:-(?:top|right|bottom|left))?\b|\bmargin(?:-(?:top|right|bottom|left))?\b/gi);
@@ -1507,31 +1617,36 @@ function checkHtmlPatterns(html) {
1507
1617
  }
1508
1618
  }
1509
1619
 
1510
- // Pulsing status dots (tiny circular elements on infinite pulse animations)
1511
- findings.push(...scanCssTextForPulsingDot(html));
1620
+ // Pulsing status dots (tiny circular elements on infinite pulse animations).
1621
+ // The CSS rules come from styleText; the markup carries the landmark
1622
+ // ranges and Tailwind class attributes.
1623
+ findings.push(...scanCssTextForPulsingDot(styleText, html));
1512
1624
 
1513
1625
  // Shape-assembled illustrations (large pictorial SVGs built from primitives)
1514
1626
  findings.push(...scanHtmlForShapeAssembledIllustration(html));
1515
1627
 
1516
1628
  // Auto-scrolling marquees (<marquee> or infinite horizontal loop animations)
1517
- findings.push(...scanCssTextForMarquee(html));
1629
+ findings.push(...scanCssTextForMarquee(styleText, html));
1518
1630
 
1519
1631
  // --- Dark glow / chromatic halo shadows ---
1520
1632
 
1521
- const glowHits = scanCssTextForGlow(html);
1633
+ const glowHits = scanCssTextForGlow(styleText);
1522
1634
  if (glowHits.length > 0) {
1523
- 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 });
1524
1636
  }
1525
1637
 
1526
1638
  // Radial-gradient background halo (gradient-drawn sibling of dark-glow)
1527
- const haloHits = scanCssTextForRadialHalo(html);
1639
+ const haloHits = scanCssTextForRadialHalo(styleText);
1528
1640
  if (haloHits.length > 0) {
1529
- 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 });
1530
1642
  }
1531
1643
 
1532
1644
  // --- Generated-UI tells: repeating-gradient stripes ---
1533
- if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(html)) {
1534
- 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
+ }
1535
1650
  }
1536
1651
 
1537
1652
  // --- Generated-UI tells: two-axis grid-line background ---
@@ -1547,9 +1662,9 @@ function checkHtmlPatterns(html) {
1547
1662
  // in for the second axis. Colors like `oklch(96% 0.012 82 / 0.055)` carry
1548
1663
  // nested parens, so match the hairline stop directly rather than parsing
1549
1664
  // whole gradient layers.
1550
- const gridHits = scanCssTextForGridBackground(html);
1665
+ const gridHits = scanCssTextForGridBackground(styleText);
1551
1666
  if (gridHits.length > 0) {
1552
- 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 });
1553
1668
  }
1554
1669
 
1555
1670
  // --- Generated-copy tells: "X theater" framing copy ---
@@ -1569,8 +1684,11 @@ function checkHtmlPatterns(html) {
1569
1684
  // hover:rotate / hover:translate utility on an <img>. Each distinct
1570
1685
  // mechanism is its own finding.
1571
1686
  const imgHoverCss = /\bimg\b[^,{}]*:hover\b[^{}]*\{[^}]*\btransform\s*:\s*(?:scale|rotate|translate|matrix|skew)/i;
1572
- if (imgHoverCss.test(html)) {
1573
- 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
+ }
1574
1692
  }
1575
1693
  const imgTagRe = /<img\b[^>]*\bclass\s*=\s*"([^"]*)"/gi;
1576
1694
  let im;
@@ -1617,7 +1735,46 @@ function readOwnBackgroundColor(el, computedStyle) {
1617
1735
  return bg;
1618
1736
  }
1619
1737
 
1620
- 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) {
1621
1778
  let current = el;
1622
1779
  // Translucent layers (0.1 < a < 1) found on the way down to an opaque
1623
1780
  // base. A browser composites these over the base; the old behavior
@@ -1645,67 +1802,114 @@ function resolveBackground(el, win, customPropMap) {
1645
1802
  // body backgrounds.
1646
1803
  // Real browsers serialize wide-gamut computed values as oklab()/oklch()
1647
1804
  // (e.g. any color-mix() result), which plain parseRgb misses.
1648
- let bg = parseRgb(style.backgroundColor) || parseAnyColor(style.backgroundColor);
1649
- if (!DETECTOR_IS_BROWSER && (!bg || bg.a < 0.1)) {
1650
- // jsdom returns literal "var(--X)" / "oklch(...)" strings. Resolve
1651
- // through customPropMap so Tailwind v4 color tokens become RGB.
1652
- if (customPropMap) {
1653
- bg = parseColorResolved(style.backgroundColor, customPropMap);
1654
- }
1655
- if (!bg || bg.a < 0.1) {
1656
- // Inline-style fallback. jsdom doesn't decompose background
1657
- // shorthand, so colors set via inline style are otherwise invisible.
1658
- const rawStyle = current.getAttribute?.('style') || '';
1659
- const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
1660
- const inlineBg = bgMatch ? bgMatch[1].trim() : '';
1661
- if (inlineBg && !/gradient/i.test(inlineBg) && !/url\s*\(/i.test(inlineBg)) {
1662
- bg = parseColorResolved(inlineBg, customPropMap) || parseAnyColor(inlineBg);
1663
- }
1664
- }
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);
1665
1819
  }
1666
1820
 
1667
1821
  if (bg && bg.a > 0.1) {
1668
- if (bg.a >= 0.99) return flatten(bg);
1822
+ if (bg.a >= 0.99) return { color: flatten(bg), unresolved: false };
1669
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 };
1670
1831
  }
1671
- // No solid bg-color at this level. If THIS level has a gradient/url
1672
- // with no underlying solid color we can read:
1673
- // • on body/html: assume white. Body-level gradients are almost
1674
- // always decorative texture (paper grain, noise) on top of a
1675
- // solid bg-color the page set via `background: var(--paper)`
1676
- // shorthand — which jsdom can't decompose into bg-color. The
1677
- // downstream gradient-stops fallback path produces catastrophic
1678
- // false positives in this case (gradient noise stops have
1679
- // accidental browns/blacks that look like card backgrounds).
1680
- // • on other elements: bail to null and let the caller fall back
1681
- // to gradient stops (gradient buttons / hero sections are real
1682
- // 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).
1683
1844
  if (hasGradientOrUrl) {
1684
- if (current.tagName === 'BODY' || current.tagName === 'HTML') {
1685
- 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 };
1686
1867
  }
1687
- return null;
1868
+ return { color: null, unresolved: false };
1688
1869
  }
1689
1870
  current = current.parentElement;
1690
1871
  }
1691
- 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;
1692
1880
  }
1693
1881
 
1694
1882
  // Walk parents looking for a gradient background and return its color stops.
1695
1883
  // Used as a fallback when resolveBackground() returns null because the
1696
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.
1697
1890
  function resolveGradientStops(el, win, customPropMap) {
1698
1891
  let current = el;
1892
+ const overlays = [];
1699
1893
  while (current && current.nodeType === 1) {
1700
1894
  const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
1701
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;
1702
1903
  let stops = null;
1703
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.
1704
1908
  const parsed = parseGradientColors(bgImage);
1705
1909
  if (parsed.length > 0) stops = parsed;
1706
1910
  }
1707
1911
  if (!stops && !DETECTOR_IS_BROWSER) {
1708
- // 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
1709
1913
  const rawStyle = current.getAttribute?.('style') || '';
1710
1914
  const bgMatch = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
1711
1915
  if (bgMatch && /gradient/i.test(bgMatch[1])) {
@@ -1713,7 +1917,23 @@ function resolveGradientStops(el, win, customPropMap) {
1713
1917
  if (parsed.length > 0) stops = parsed;
1714
1918
  }
1715
1919
  }
1716
- 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
+ }
1717
1937
  current = current.parentElement;
1718
1938
  }
1719
1939
  return null;
@@ -1933,15 +2153,25 @@ function checkElementColorsDOM(el) {
1933
2153
  const rect = el.getBoundingClientRect();
1934
2154
  if (rect.width < 10 || rect.height < 10) return [];
1935
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 [];
1936
2160
  const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
1937
2161
  const hasDirectText = directText.trim().length > 0;
1938
- 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;
1939
2168
  let ownBg = readOwnBackgroundColor(el, style);
1940
2169
  if (!ownBg || (ownBg.a ?? 1) <= 0.5) {
1941
2170
  const pseudoSurface = readPseudoSurfaceDOM(el, rect);
1942
2171
  if (pseudoSurface) {
1943
2172
  ownBg = pseudoSurface;
1944
2173
  effectiveBg = pseudoSurface;
2174
+ surfaceUnresolved = false;
1945
2175
  }
1946
2176
  }
1947
2177
  return checkColors({
@@ -1953,8 +2183,8 @@ function checkElementColorsDOM(el) {
1953
2183
  // an oklch token near its own oklch background).
1954
2184
  textColor: parseRgb(style.color) || parseAnyColor(style.color),
1955
2185
  bgColor: ownBg,
1956
- effectiveBg,
1957
- effectiveBgStops: effectiveBg ? null : resolveGradientStops(el),
2186
+ effectiveBg: surfaceUnresolved ? null : effectiveBg,
2187
+ effectiveBgStops: surfaceUnresolved || effectiveBg ? null : resolveGradientStops(el),
1958
2188
  fontSize: parseFloat(style.fontSize) || 16,
1959
2189
  fontWeight: parseInt(style.fontWeight) || 400,
1960
2190
  hasDirectText,
@@ -2104,283 +2334,6 @@ function resolveVarRefs(raw, customPropMap, depth = 0) {
2104
2334
  });
2105
2335
  }
2106
2336
 
2107
- // OKLCH → sRGB conversion (Björn Ottosson's matrices). L in 0..1 (or %),
2108
- // C in 0..~0.4 typical, H in degrees. Returns clamped {r,g,b,a:1} in 0..255.
2109
- // Needed because jsdom doesn't compute oklch() values — getComputedStyle
2110
- // returns the literal "oklch(...)" string. Without this, the entire
2111
- // Tailwind v4 color palette (which is OKLCH-based) is invisible to the
2112
- // detector's contrast / color checks.
2113
- function oklchToRgb(L, C, H) {
2114
- const hRad = (H * Math.PI) / 180;
2115
- return oklabToRgb(L, C * Math.cos(hRad), C * Math.sin(hRad));
2116
- }
2117
-
2118
- function oklabToRgb(L, a, b) {
2119
- const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
2120
- const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
2121
- const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
2122
- const lc = l_ * l_ * l_, mc = m_ * m_ * m_, sc = s_ * s_ * s_;
2123
- const rLin = 4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc;
2124
- const gLin = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc;
2125
- const bLin = -0.0041960863 * lc - 0.7034186147 * mc + 1.7076147010 * sc;
2126
- const enc = (x) => {
2127
- const c = Math.max(0, Math.min(1, x));
2128
- return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
2129
- };
2130
- return {
2131
- r: Math.round(enc(rLin) * 255),
2132
- g: Math.round(enc(gLin) * 255),
2133
- b: Math.round(enc(bLin) * 255),
2134
- a: 1,
2135
- };
2136
- }
2137
-
2138
- function hslToRgb(h, s, l) {
2139
- h = ((h % 360) + 360) % 360;
2140
- const c = (1 - Math.abs(2 * l - 1)) * s;
2141
- const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
2142
- const m0 = l - c / 2;
2143
- const [r, g, b] =
2144
- h < 60 ? [c, x, 0] :
2145
- h < 120 ? [x, c, 0] :
2146
- h < 180 ? [0, c, x] :
2147
- h < 240 ? [0, x, c] :
2148
- h < 300 ? [x, 0, c] : [c, 0, x];
2149
- return {
2150
- r: Math.round((r + m0) * 255),
2151
- g: Math.round((g + m0) * 255),
2152
- b: Math.round((b + m0) * 255),
2153
- a: 1,
2154
- };
2155
- }
2156
-
2157
- function hwbToRgb(h, w, bl) {
2158
- if (w + bl >= 1) {
2159
- const g = Math.round((w / (w + bl)) * 255);
2160
- return { r: g, g, b: g, a: 1 };
2161
- }
2162
- const base = hslToRgb(h, 1, 0.5);
2163
- const mix = (c) => Math.round(((c / 255) * (1 - w - bl) + w) * 255);
2164
- return { r: mix(base.r), g: mix(base.g), b: mix(base.b), a: 1 };
2165
- }
2166
-
2167
- // Common CSS named colors — the handful that actually show up in generated
2168
- // UIs, not the full 148-name spec list. Includes the achromatic names so a
2169
- // named gray parses (and correctly reads as no-chroma) instead of being
2170
- // treated as an unknown color.
2171
- const CSS_NAMED_COLORS = {
2172
- black: { r: 0, g: 0, b: 0 },
2173
- white: { r: 255, g: 255, b: 255 },
2174
- gray: { r: 128, g: 128, b: 128 },
2175
- grey: { r: 128, g: 128, b: 128 },
2176
- silver: { r: 192, g: 192, b: 192 },
2177
- dimgray: { r: 105, g: 105, b: 105 },
2178
- darkgray: { r: 169, g: 169, b: 169 },
2179
- lightgray: { r: 211, g: 211, b: 211 },
2180
- gainsboro: { r: 220, g: 220, b: 220 },
2181
- whitesmoke: { r: 245, g: 245, b: 245 },
2182
- red: { r: 255, g: 0, b: 0 },
2183
- crimson: { r: 220, g: 20, b: 60 },
2184
- tomato: { r: 255, g: 99, b: 71 },
2185
- coral: { r: 255, g: 127, b: 80 },
2186
- salmon: { r: 250, g: 128, b: 114 },
2187
- orange: { r: 255, g: 165, b: 0 },
2188
- gold: { r: 255, g: 215, b: 0 },
2189
- yellow: { r: 255, g: 255, b: 0 },
2190
- olive: { r: 128, g: 128, b: 0 },
2191
- lime: { r: 0, g: 255, b: 0 },
2192
- green: { r: 0, g: 128, b: 0 },
2193
- teal: { r: 0, g: 128, b: 128 },
2194
- turquoise: { r: 64, g: 224, b: 208 },
2195
- cyan: { r: 0, g: 255, b: 255 },
2196
- aqua: { r: 0, g: 255, b: 255 },
2197
- skyblue: { r: 135, g: 206, b: 235 },
2198
- dodgerblue: { r: 30, g: 144, b: 255 },
2199
- blue: { r: 0, g: 0, b: 255 },
2200
- navy: { r: 0, g: 0, b: 128 },
2201
- indigo: { r: 75, g: 0, b: 130 },
2202
- rebeccapurple: { r: 102, g: 51, b: 153 },
2203
- purple: { r: 128, g: 0, b: 128 },
2204
- violet: { r: 238, g: 130, b: 238 },
2205
- orchid: { r: 218, g: 112, b: 214 },
2206
- magenta: { r: 255, g: 0, b: 255 },
2207
- fuchsia: { r: 255, g: 0, b: 255 },
2208
- hotpink: { r: 255, g: 105, b: 180 },
2209
- pink: { r: 255, g: 192, b: 203 },
2210
- maroon: { r: 128, g: 0, b: 0 },
2211
- };
2212
-
2213
- // Split a string on top-level commas (ignoring commas nested in parens).
2214
- function splitTopLevelCommas(str) {
2215
- const parts = [];
2216
- let depth = 0, start = 0;
2217
- for (let i = 0; i < str.length; i++) {
2218
- const ch = str[i];
2219
- if (ch === '(') depth++;
2220
- else if (ch === ')') depth = Math.max(0, depth - 1);
2221
- else if (ch === ',' && depth === 0) {
2222
- parts.push(str.slice(start, i).trim());
2223
- start = i + 1;
2224
- }
2225
- }
2226
- const tail = str.slice(start).trim();
2227
- if (tail) parts.push(tail);
2228
- return parts;
2229
- }
2230
-
2231
- // Evaluate a CSS color-mix() expression to {r,g,b,a}. Returns null when
2232
- // the expression can't be resolved (unresolved var(), unknown colors).
2233
- //
2234
- // Mixing is done with premultiplied alpha in sRGB regardless of the
2235
- // declared interpolation space. That is exact for the dominant generated-UI
2236
- // pattern — `color-mix(in oklab, <color> N%, transparent)` — where the
2237
- // result is simply <color> at alpha N% in ANY rectangular space, and a
2238
- // close-enough approximation for opaque-opaque mixes (the detector only
2239
- // consumes these values for contrast/chroma thresholds, not for display).
2240
- function parseColorMix(str) {
2241
- const m = String(str).trim().match(/^color-mix\(/i);
2242
- if (!m) return null;
2243
- // Balanced-paren capture of the arguments.
2244
- let depth = 0, end = -1;
2245
- const open = str.indexOf('(');
2246
- for (let i = open; i < str.length; i++) {
2247
- if (str[i] === '(') depth++;
2248
- else if (str[i] === ')') { depth--; if (depth === 0) { end = i; break; } }
2249
- }
2250
- if (end < 0) return null;
2251
- const args = splitTopLevelCommas(str.slice(open + 1, end));
2252
- if (args.length !== 3 || !/^in\s/i.test(args[0])) return null;
2253
-
2254
- const parseComponent = (component) => {
2255
- // Percentage may lead or trail the color per spec.
2256
- let pct = null;
2257
- let colorStr = component;
2258
- const trail = component.match(/\s+([\d.]+)%$/);
2259
- const lead = component.match(/^([\d.]+)%\s+/);
2260
- if (trail) { pct = parseFloat(trail[1]); colorStr = component.slice(0, trail.index).trim(); }
2261
- else if (lead) { pct = parseFloat(lead[1]); colorStr = component.slice(lead[0].length).trim(); }
2262
- let color;
2263
- if (/^transparent$/i.test(colorStr)) color = { r: 0, g: 0, b: 0, a: 0 };
2264
- else color = parseAnyColor(colorStr);
2265
- if (!color) return null;
2266
- return { color, pct };
2267
- };
2268
-
2269
- const c1 = parseComponent(args[1]);
2270
- const c2 = parseComponent(args[2]);
2271
- if (!c1 || !c2) return null;
2272
- let p1 = c1.pct, p2 = c2.pct;
2273
- if (p1 == null && p2 == null) { p1 = 50; p2 = 50; }
2274
- else if (p1 == null) p1 = 100 - p2;
2275
- else if (p2 == null) p2 = 100 - p1;
2276
- const sum = p1 + p2;
2277
- if (sum <= 0) return null;
2278
- // Per spec: weights normalize to sum; when sum < 100 the result alpha is
2279
- // additionally scaled by sum/100.
2280
- const w1 = p1 / sum, w2 = p2 / sum;
2281
- const alphaScale = sum < 100 ? sum / 100 : 1;
2282
- const a1 = c1.color.a ?? 1, a2 = c2.color.a ?? 1;
2283
- const a = (a1 * w1 + a2 * w2) * alphaScale;
2284
- if (a <= 0) return { r: 0, g: 0, b: 0, a: 0 };
2285
- const mix = (ch) => Math.round((c1.color[ch] * a1 * w1 + c2.color[ch] * a2 * w2) / (a1 * w1 + a2 * w2));
2286
- return { r: mix('r'), g: mix('g'), b: mix('b'), a: Math.min(1, a) };
2287
- }
2288
-
2289
- // Composite a translucent color over an opaque(ish) base (simple
2290
- // source-over in sRGB). Returns an opaque {r,g,b,a:1}.
2291
- function compositeColorOver(top, base) {
2292
- const a = top.a ?? 1;
2293
- return {
2294
- r: Math.round(top.r * a + base.r * (1 - a)),
2295
- g: Math.round(top.g * a + base.g * (1 - a)),
2296
- b: Math.round(top.b * a + base.b * (1 - a)),
2297
- a: 1,
2298
- };
2299
- }
2300
-
2301
- // Extended color parser: rgb/rgba/hex/oklch/oklab/hsl/hwb/color-mix/common
2302
- // named colors. Returns null on no match. Use this when the input might be
2303
- // any CSS color form; use plain parseRgb when you only expect computed rgb()
2304
- // values from real browsers.
2305
- function parseAnyColor(s) {
2306
- if (!s || typeof s !== 'string') return null;
2307
- const str = s.trim();
2308
- if (str === 'transparent' || str === 'currentcolor' || str === 'inherit') return null;
2309
- if (/^color-mix\(/i.test(str)) return parseColorMix(str);
2310
- let m;
2311
- m = str.match(/rgba?\(\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)(?:\s*[,/]\s*([\d.]+))?\s*\)/);
2312
- 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 };
2313
- m = str.match(/^#([0-9a-f]{3,8})$/i);
2314
- if (m) {
2315
- const h = m[1];
2316
- if (h.length === 3 || h.length === 4) {
2317
- return {
2318
- r: parseInt(h[0] + h[0], 16),
2319
- g: parseInt(h[1] + h[1], 16),
2320
- b: parseInt(h[2] + h[2], 16),
2321
- a: h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1,
2322
- };
2323
- }
2324
- if (h.length === 6 || h.length === 8) {
2325
- return {
2326
- r: parseInt(h.slice(0, 2), 16),
2327
- g: parseInt(h.slice(2, 4), 16),
2328
- b: parseInt(h.slice(4, 6), 16),
2329
- a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
2330
- };
2331
- }
2332
- }
2333
- // OKLCH parser. Tailwind v4's CSS minifier squishes the space after
2334
- // `%` ("21.5%.02 50"), so the separator between L and C may be absent.
2335
- // Match L (with optional %), then C and H separated permissively.
2336
- m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
2337
- if (m) {
2338
- const Lnum = parseFloat(m[1]);
2339
- const L = m[2] === '%' ? Lnum / 100 : Lnum;
2340
- const rgb = oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]));
2341
- if (m[5] !== undefined) {
2342
- const alpha = parseFloat(m[5]);
2343
- rgb.a = m[6] === '%' ? alpha / 100 : alpha;
2344
- }
2345
- return rgb;
2346
- }
2347
- // OKLAB — a/b are signed axes; percentages map 100% → 0.4.
2348
- m = str.match(/oklab\(\s*([\d.]+)(%?)\s+(-?[\d.]+)(%?)\s+(-?[\d.]+)(%?)(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
2349
- if (m) {
2350
- const L = m[2] === '%' ? parseFloat(m[1]) / 100 : parseFloat(m[1]);
2351
- const a = m[4] === '%' ? parseFloat(m[3]) * 0.004 : parseFloat(m[3]);
2352
- const b = m[6] === '%' ? parseFloat(m[5]) * 0.004 : parseFloat(m[5]);
2353
- const rgb = oklabToRgb(L, a, b);
2354
- if (m[7] !== undefined) {
2355
- const alpha = parseFloat(m[7]);
2356
- rgb.a = m[8] === '%' ? alpha / 100 : alpha;
2357
- }
2358
- return rgb;
2359
- }
2360
- // HSL/HSLA — comma or space syntax, optional deg on hue.
2361
- m = str.match(/hsla?\(\s*(-?[\d.]+)(?:deg)?\s*[,\s]\s*([\d.]+)%\s*[,\s]\s*([\d.]+)%(?:\s*[,/]\s*([\d.]+)(%)?)?\s*\)/i);
2362
- if (m) {
2363
- const rgb = hslToRgb(parseFloat(m[1]), parseFloat(m[2]) / 100, parseFloat(m[3]) / 100);
2364
- if (m[4] !== undefined) {
2365
- const alpha = parseFloat(m[4]);
2366
- rgb.a = m[5] === '%' ? alpha / 100 : alpha;
2367
- }
2368
- return rgb;
2369
- }
2370
- // HWB — hue whiteness% blackness%.
2371
- m = str.match(/hwb\(\s*(-?[\d.]+)(?:deg)?\s+([\d.]+)%\s+([\d.]+)%(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
2372
- if (m) {
2373
- const rgb = hwbToRgb(parseFloat(m[1]), parseFloat(m[2]) / 100, parseFloat(m[3]) / 100);
2374
- if (m[4] !== undefined) {
2375
- const alpha = parseFloat(m[4]);
2376
- rgb.a = m[5] === '%' ? alpha / 100 : alpha;
2377
- }
2378
- return rgb;
2379
- }
2380
- const named = CSS_NAMED_COLORS[str.toLowerCase()];
2381
- if (named) return { ...named, a: 1 };
2382
- return null;
2383
- }
2384
2337
 
2385
2338
  // Resolve var() refs in a color string (via customPropMap), then parse.
2386
2339
  // Returns null on any failure. Used in jsdom-mode paths where
@@ -2470,7 +2423,11 @@ function isKickerCandidate(opts) {
2470
2423
  || isSmallCaps;
2471
2424
  if (!isUppercased) return false;
2472
2425
  if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false;
2473
- const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08);
2426
+ // Proportional only, no absolute floor: the wild's most common recipe is
2427
+ // 0.08em at a sub-13px size, which computes to under 1px and sailed past
2428
+ // the old Math.max(1, ...) floor (observed live: a page whose kickers were
2429
+ // literally class="kicker" produced zero findings).
2430
+ const minTrackedSpacing = kickerFontSize * 0.06;
2474
2431
  if (!(kickerLetterSpacing >= minTrackedSpacing)) return false;
2475
2432
  return true;
2476
2433
  }
@@ -2739,9 +2696,20 @@ function checkElementGlowDOM(el) {
2739
2696
  if (!boxShadow && !textShadow) return [];
2740
2697
  // Use parent's background — glow radiates outward, so the surrounding context matters
2741
2698
  // If resolveBackground returns null (gradient), try to infer from the gradient colors
2742
- let parentBg = el.parentElement ? resolveBackground(el.parentElement) : resolveBackground(el);
2743
- if (!parentBg) {
2744
- // 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.
2745
2713
  let cur = el.parentElement;
2746
2714
  while (cur && cur.nodeType === 1) {
2747
2715
  const bgImage = getComputedStyle(cur).backgroundImage || '';
@@ -2789,10 +2757,13 @@ function checkElementAIPaletteDOM(el) {
2789
2757
  const hue = getHue(textColor);
2790
2758
  const isAIPalette = (hue >= 160 && hue <= 200) || (hue >= 260 && hue <= 310);
2791
2759
  if (isAIPalette) {
2792
- const parentBg = el.parentElement ? resolveBackground(el.parentElement) : null;
2793
- // Also check gradient parents
2794
- let effectiveBg = parentBg;
2795
- 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) {
2796
2767
  let cur = el.parentElement;
2797
2768
  while (cur && cur.nodeType === 1) {
2798
2769
  const gi = getComputedStyle(cur).backgroundImage || '';
@@ -3587,10 +3558,19 @@ function checkElementBorders(tag, style, overrides, resolvedRadius, el = null) {
3587
3558
  }
3588
3559
 
3589
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 [];
3590
3569
  const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
3591
3570
  const hasDirectText = directText.trim().length > 0;
3592
3571
 
3593
- const effectiveBg = resolveBackground(el, window, customPropMap);
3572
+ const bgInfo = resolveBackgroundInfo(el, window, customPropMap);
3573
+ const effectiveBg = bgInfo.color;
3594
3574
  // jsdom returns literal "var(--X)" / "oklch(...)" for color, so plain
3595
3575
  // parseRgb misses Tailwind-tokenized text colors. Resolve through the
3596
3576
  // customPropMap first; fall back to parseRgb for vanilla rgb() pages.
@@ -3636,11 +3616,13 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
3636
3616
  // element itself has no usable own background, that pseudo is the real
3637
3617
  // surface for contrast purposes.
3638
3618
  let finalEffectiveBg = effectiveBg;
3619
+ let surfaceUnresolved = bgInfo.unresolved;
3639
3620
  if ((!ownBg || (ownBg.a ?? 1) <= 0.5) && typeof window.getPseudoSurface === 'function') {
3640
3621
  const pseudoSurface = window.getPseudoSurface(el);
3641
3622
  if (pseudoSurface) {
3642
3623
  ownBg = pseudoSurface;
3643
3624
  finalEffectiveBg = pseudoSurface;
3625
+ surfaceUnresolved = false;
3644
3626
  }
3645
3627
  }
3646
3628
 
@@ -3648,8 +3630,9 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
3648
3630
  tag,
3649
3631
  textColor,
3650
3632
  bgColor: ownBg,
3651
- effectiveBg: finalEffectiveBg,
3652
- 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),
3653
3636
  fontSize: parseFloat(style.fontSize) || 16,
3654
3637
  fontWeight: parseInt(style.fontWeight) || 400,
3655
3638
  hasDirectText,
@@ -3854,12 +3837,6 @@ function checkTypography() {
3854
3837
  if (isBrandFontOnOwnDomain(font)) continue;
3855
3838
  findings.push({ type: 'overused-font', detail: `Primary font: ${font} (${Math.round(share * 100)}% of text)` });
3856
3839
  }
3857
-
3858
- // Single-font check: only one distinct primary font across all text
3859
- if (fontUsage.size === 1) {
3860
- const only = [...fontUsage.keys()][0];
3861
- findings.push({ type: 'single-font', detail: `only font used is ${only}` });
3862
- }
3863
3840
  }
3864
3841
 
3865
3842
  const sizes = new Set();
@@ -4121,14 +4098,6 @@ function checkPageTypography(doc, win) {
4121
4098
  findings.push({ id: 'overused-font', snippet: `Primary font: ${font}` });
4122
4099
  }
4123
4100
 
4124
- // Single font
4125
- if (fonts.size === 1) {
4126
- const els = doc.querySelectorAll('*');
4127
- if (els.length >= 20) {
4128
- findings.push({ id: 'single-font', snippet: `only font used is ${[...fonts][0]}` });
4129
- }
4130
- }
4131
-
4132
4101
  // Flat type hierarchy
4133
4102
  const sizes = new Set();
4134
4103
  const textEls = doc.querySelectorAll('h1, h2, h3, h4, h5, h6, p, span, a, li, td, th, label, button, div');
@@ -4759,6 +4728,11 @@ function isRenderedForBrowserRule(el) {
4759
4728
  function checkElementTextOverflowDOM(el) {
4760
4729
  const tag = el.tagName.toLowerCase();
4761
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 [];
4762
4736
  if (!isRenderedForBrowserRule(el)) return [];
4763
4737
  // Only the element that actually owns overflowing text — not its ancestors,
4764
4738
  // which inherit a wider scrollWidth from the spilling descendant.
@@ -5143,6 +5117,22 @@ function isPaintedForOcclusion(el) {
5143
5117
  // path is pure geometry and runs anywhere on the page.
5144
5118
  const OCCLUSION_TEXT_SKIP_TAGS = new Set(['script', 'style', 'noscript', 'template', 'title']);
5145
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
+
5146
5136
  function checkTextOcclusionDOM() {
5147
5137
  const findings = [];
5148
5138
  const seenVictims = new Set();
@@ -5170,6 +5160,11 @@ function checkTextOcclusionDOM() {
5170
5160
  }
5171
5161
  return false;
5172
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;
5173
5168
 
5174
5169
  // Collect renderable text owners in / near the first viewport for the
5175
5170
  // elementFromPoint probe. SVG <text> counts too.
@@ -5182,6 +5177,7 @@ function checkTextOcclusionDOM() {
5182
5177
  const text = inSvg ? (el.textContent || '').trim() : elementDirectText(el);
5183
5178
  if (text.length < 2) continue;
5184
5179
  if (!isPaintedForOcclusion(el)) continue;
5180
+ if (effectiveOpacity(el) <= 0.02) continue;
5185
5181
  let rect; try { rect = el.getBoundingClientRect(); } catch { continue; }
5186
5182
  if (rect.width < 6 || rect.height < 6) continue;
5187
5183
  // Viewport-bound probe: keep text whose box overlaps the live viewport.
@@ -5215,6 +5211,7 @@ function checkTextOcclusionDOM() {
5215
5211
  if (top === el || el.contains(top) || top.contains(el)) continue;
5216
5212
  const topCs = getComputedStyle(top);
5217
5213
  if (isFloated(topCs) || isMarqueeish(top, topCs) || isPinnedOverlay(top)) continue;
5214
+ if (effectiveOpacity(top) <= 0.02) continue;
5218
5215
  const topTag = top.tagName.toLowerCase();
5219
5216
  // Text sitting under a raw image/video is contrast territory (deduped
5220
5217
  // against the pixel low-contrast rule); leave those alone here.
@@ -5425,6 +5422,7 @@ export {
5425
5422
  CSS_NAMED_COLORS,
5426
5423
  checkBorders,
5427
5424
  isEmojiOnlyText,
5425
+ scopedIgnoreActive,
5428
5426
  checkColors,
5429
5427
  checkHoverContrast,
5430
5428
  checkElementHoverContrast,
@@ -5450,9 +5448,11 @@ export {
5450
5448
  cssLengthToPx,
5451
5449
  scanCssTextForPulsingDot,
5452
5450
  scanHtmlForShapeAssembledIllustration,
5451
+ buildHtmlPatternCorpora,
5453
5452
  checkHtmlPatterns,
5454
5453
  readOwnBackgroundColor,
5455
5454
  resolveBackground,
5455
+ resolveBackgroundInfo,
5456
5456
  resolveGradientStops,
5457
5457
  parseRadiusToPx,
5458
5458
  resolveBorderRadiusPx,