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.
@@ -139,16 +139,6 @@ const ANTIPATTERNS = [
139
139
  skillSection: 'Typography',
140
140
  skillGuideline: 'overused fonts like Inter',
141
141
  },
142
- {
143
- id: 'single-font',
144
- category: 'slop',
145
- scopes: ['type'],
146
- name: 'Single font without hierarchy',
147
- description:
148
- 'Only one font family is used for the entire page. A single family can work when weight and size contrast carry the hierarchy; otherwise pair a distinctive display font with a refined body font.',
149
- skillSection: 'Typography',
150
- skillGuideline: 'only one font family for the entire page',
151
- },
152
142
  {
153
143
  id: 'flat-type-hierarchy',
154
144
  category: 'slop',
@@ -751,11 +741,43 @@ function contrastRatio(c1, c2) {
751
741
  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
752
742
  }
753
743
 
744
+ // The CSS color functions worth pulling out of a longer declaration. The set
745
+ // is deliberately closed: `linear-gradient(` and `url(` also look like
746
+ // `name(` and must not be read as colors.
747
+ const COLOR_FUNCTION_NAMES = new Set([
748
+ 'rgb', 'rgba', 'hsl', 'hsla', 'hwb', 'oklch', 'oklab', 'lch', 'lab', 'color', 'color-mix',
749
+ ]);
750
+
751
+ // Pull every color-function token out of a value, with balanced-paren capture
752
+ // so nested forms (`color-mix(in oklab, oklch(...) 20%, transparent)`) survive
753
+ // whole. Returns the raw substrings in source order.
754
+ function extractColorFunctionTokens(value) {
755
+ const str = String(value || '');
756
+ const tokens = [];
757
+ const re = /([a-z][a-z-]*)\(/gi;
758
+ let m;
759
+ while ((m = re.exec(str)) !== null) {
760
+ if (!COLOR_FUNCTION_NAMES.has(m[1].toLowerCase())) continue;
761
+ let depth = 0, end = -1;
762
+ for (let i = m.index + m[0].length - 1; i < str.length; i++) {
763
+ if (str[i] === '(') depth++;
764
+ else if (str[i] === ')') { depth--; if (depth === 0) { end = i; break; } }
765
+ }
766
+ if (end < 0) break;
767
+ tokens.push(str.slice(m.index, end + 1));
768
+ re.lastIndex = end + 1;
769
+ }
770
+ return tokens;
771
+ }
772
+
754
773
  function parseGradientColors(bgImage) {
755
774
  if (!bgImage || !bgImage.includes('gradient')) return [];
756
775
  const colors = [];
757
- for (const m of bgImage.matchAll(/rgba?\([^)]+\)/g)) {
758
- const c = parseRgb(m[0]);
776
+ // Stops arrive in whatever syntax the author wrote and the browser kept.
777
+ // A dark ground painted as `linear-gradient(oklch(...), oklch(...))` used
778
+ // to read as a gradient with no stops at all.
779
+ for (const token of extractColorFunctionTokens(bgImage)) {
780
+ const c = parseAnyColor(token);
759
781
  if (c) colors.push(c);
760
782
  }
761
783
  for (const m of bgImage.matchAll(/#([0-9a-f]{6}|[0-9a-f]{3})\b/gi)) {
@@ -792,141 +814,587 @@ function colorToHex(c) {
792
814
  return '#' + [c.r, c.g, c.b].map(v => v.toString(16).padStart(2, '0')).join('');
793
815
  }
794
816
 
795
- // --- cli/engine/shared/fonts.mjs ---
796
- const GOOGLE_FONTS_URL_RE = /fonts\.googleapis\.com\/css2?\?[^"'\s)<>]*/gi;
817
+ // ─── Color-space conversions ────────────────────────────────────────────────
818
+ //
819
+ // Every function here lands on 8-bit sRGB, clamped to gamut. Chrome, Safari,
820
+ // and Firefox all keep the authored color space in getComputedStyle output
821
+ // (`oklch(0.84 0.19 80.46)`, `lch(20 5 60)`, `color(srgb 1.04 0.72 -0.21)`),
822
+ // so a detector that only reads rgb() is blind on any modern palette. The
823
+ // expected outputs are pinned in tests/detect-antipatterns.test.js against
824
+ // what Chrome itself paints for the same strings.
797
825
 
798
- function normalizeGoogleFontFamilyParam(value) {
799
- return String(value || '')
800
- .split('|')
801
- .map(part => part.split(':')[0].trim().toLowerCase())
802
- .filter(Boolean);
826
+ function clamp01(x) {
827
+ return Number.isFinite(x) ? Math.max(0, Math.min(1, x)) : 0;
803
828
  }
804
829
 
805
- function extractGoogleFontFamilies(text) {
806
- const families = [];
807
- if (!text) return families;
830
+ // Linear-light sRGB channel to the encoded 0-255 value.
831
+ function encodeSrgbChannel(x) {
832
+ const c = clamp01(x);
833
+ return Math.round((c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055) * 255);
834
+ }
808
835
 
809
- GOOGLE_FONTS_URL_RE.lastIndex = 0;
810
- let urlMatch;
811
- while ((urlMatch = GOOGLE_FONTS_URL_RE.exec(text)) !== null) {
812
- const url = urlMatch[0];
813
- const queryStart = url.indexOf('?');
814
- if (queryStart === -1) continue;
836
+ function decodeSrgbChannel(x) {
837
+ const c = Number.isFinite(x) ? x : 0;
838
+ const sign = c < 0 ? -1 : 1;
839
+ const abs = Math.abs(c);
840
+ return sign * (abs <= 0.04045 ? abs / 12.92 : Math.pow((abs + 0.055) / 1.055, 2.4));
841
+ }
815
842
 
816
- const params = new URLSearchParams(url.slice(queryStart + 1).replace(/&amp;/g, '&'));
817
- for (const value of params.getAll('family')) {
818
- families.push(...normalizeGoogleFontFamilyParam(value));
819
- }
820
- }
843
+ function linearSrgbToColor(r, g, b, a = 1) {
844
+ return { r: encodeSrgbChannel(r), g: encodeSrgbChannel(g), b: encodeSrgbChannel(b), a };
845
+ }
821
846
 
822
- return families;
847
+ // OKLab to sRGB (Björn Ottosson's matrices). L in 0..1, a/b are signed axes.
848
+ function oklabToRgb(L, a, b) {
849
+ const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
850
+ const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
851
+ const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
852
+ const lc = l_ * l_ * l_, mc = m_ * m_ * m_, sc = s_ * s_ * s_;
853
+ return linearSrgbToColor(
854
+ 4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc,
855
+ -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc,
856
+ -0.0041960863 * lc - 0.7034186147 * mc + 1.7076147010 * sc,
857
+ );
823
858
  }
824
859
 
825
- // --- cli/engine/rules/checks.mjs ---
826
- const DETECTOR_IS_BROWSER = typeof window !== 'undefined';
860
+ // OKLCH to sRGB. L in 0..1, C in 0..~0.4 typical, H in degrees. Chroma past
861
+ // the sRGB gamut clamps per channel rather than producing NaN.
862
+ function oklchToRgb(L, C, H) {
863
+ const hRad = (H * Math.PI) / 180;
864
+ return oklabToRgb(L, C * Math.cos(hRad), C * Math.sin(hRad));
865
+ }
827
866
 
828
- // ─── Section 3: Pure Detection ──────────────────────────────────────────────
867
+ // CIE Lab to sRGB. CSS lab()/lch() use the D50 white point; the matrix below
868
+ // is the Bradford-adapted XYZ-D50 to linear-sRGB transform from CSS Color 4.
869
+ function labToRgb(L, a, b) {
870
+ const kappa = 24389 / 27, epsilon = 216 / 24389;
871
+ const fy = (L + 16) / 116, fx = fy + a / 500, fz = fy - b / 200;
872
+ const invert = (t) => (t * t * t > epsilon ? t * t * t : (116 * t - 16) / kappa);
873
+ const yr = L > kappa * epsilon ? Math.pow((L + 16) / 116, 3) : L / kappa;
874
+ const Xn = 0.3457 / 0.3585, Zn = (1 - 0.3457 - 0.3585) / 0.3585;
875
+ const x = invert(fx) * Xn, y = yr, z = invert(fz) * Zn;
876
+ return linearSrgbToColor(
877
+ 3.1341359569958707 * x - 1.6173863321612538 * y - 0.4906619460083532 * z,
878
+ -0.9787955029120890 * x + 1.9162545672595240 * y + 0.0334427311613195 * z,
879
+ 0.0719553798841168 * x - 0.2289768264158322 * y + 1.4053860583241250 * z,
880
+ );
881
+ }
829
882
 
830
- function checkBorders(tag, widths, colors, radius, opts = {}) {
831
- // Badge-shaped <span>s (own visible background) are a real stripe target
832
- // for the top/bottom variant — the inline-tag exemption exists to quiet
833
- // text-level borders, not chips. They skip the left/right arms below.
834
- const spanBadge = tag === 'span' && !!opts.badgeLike;
835
- if (BORDER_SAFE_TAGS.has(tag) && !spanBadge) return [];
836
- // A live status/alert region wears a colored single-edge border as a
837
- // severity accent (toast, snackbar, callout), not as the side-tab tell.
838
- if (opts.statusContext) return [];
839
- const findings = [];
840
- const sides = ['Top', 'Right', 'Bottom', 'Left'];
883
+ function lchToRgb(L, C, H) {
884
+ const hRad = (H * Math.PI) / 180;
885
+ return labToRgb(L, C * Math.cos(hRad), C * Math.sin(hRad));
886
+ }
887
+
888
+ // color(<space> c1 c2 c3) for the spaces that turn up in real stylesheets.
889
+ // `srgb` is what Chrome serializes most color-mix() results into, routinely
890
+ // with channels outside 0..1. Spaces we do not model return null so callers
891
+ // abstain instead of measuring against a color we invented.
892
+ function colorFunctionToRgb(space, c1, c2, c3) {
893
+ switch (space) {
894
+ case 'srgb':
895
+ return { r: Math.round(clamp01(c1) * 255), g: Math.round(clamp01(c2) * 255), b: Math.round(clamp01(c3) * 255), a: 1 };
896
+ case 'srgb-linear':
897
+ return linearSrgbToColor(c1, c2, c3);
898
+ case 'display-p3': {
899
+ const [R, G, B] = [decodeSrgbChannel(c1), decodeSrgbChannel(c2), decodeSrgbChannel(c3)];
900
+ return linearSrgbToColor(
901
+ 1.2249401762805587 * R - 0.2249404646817506 * G + 0.0000002884022551 * B,
902
+ -0.0420569547096138 * R + 1.0420571661298634 * G - 0.0000002113202247 * B,
903
+ -0.0196375587040044 * R - 0.0786360772174755 * G + 1.0982736359214800 * B,
904
+ );
905
+ }
906
+ default:
907
+ return null;
908
+ }
909
+ }
841
910
 
842
- for (const side of sides) {
843
- const w = widths[side];
844
- if (w < 1 || isNeutralColor(colors[side])) continue;
911
+ function hslToRgb(h, s, l) {
912
+ h = ((h % 360) + 360) % 360;
913
+ const c = (1 - Math.abs(2 * l - 1)) * s;
914
+ const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
915
+ const m0 = l - c / 2;
916
+ const [r, g, b] =
917
+ h < 60 ? [c, x, 0] :
918
+ h < 120 ? [x, c, 0] :
919
+ h < 180 ? [0, c, x] :
920
+ h < 240 ? [0, x, c] :
921
+ h < 300 ? [x, 0, c] : [c, 0, x];
922
+ return {
923
+ r: Math.round((r + m0) * 255),
924
+ g: Math.round((g + m0) * 255),
925
+ b: Math.round((b + m0) * 255),
926
+ a: 1,
927
+ };
928
+ }
845
929
 
846
- const otherSides = sides.filter(s => s !== side);
847
- const maxOther = Math.max(...otherSides.map(s => widths[s]));
848
- if (!(w >= 2 && (maxOther <= 1 || w >= maxOther * 2))) continue;
930
+ function hwbToRgb(h, w, bl) {
931
+ if (w + bl >= 1) {
932
+ const g = Math.round((w / (w + bl)) * 255);
933
+ return { r: g, g, b: g, a: 1 };
934
+ }
935
+ const base = hslToRgb(h, 1, 0.5);
936
+ const mix = (c) => Math.round(((c / 255) * (1 - w - bl) + w) * 255);
937
+ return { r: mix(base.r), g: mix(base.g), b: mix(base.b), a: 1 };
938
+ }
849
939
 
850
- const sn = side.toLowerCase();
851
- const isSide = side === 'Left' || side === 'Right';
940
+ // Common CSS named colors — the handful that actually show up in generated
941
+ // UIs, not the full 148-name spec list. Includes the achromatic names so a
942
+ // named gray parses (and correctly reads as no-chroma) instead of being
943
+ // treated as an unknown color.
944
+ const CSS_NAMED_COLORS = {
945
+ black: { r: 0, g: 0, b: 0 },
946
+ white: { r: 255, g: 255, b: 255 },
947
+ gray: { r: 128, g: 128, b: 128 },
948
+ grey: { r: 128, g: 128, b: 128 },
949
+ silver: { r: 192, g: 192, b: 192 },
950
+ dimgray: { r: 105, g: 105, b: 105 },
951
+ darkgray: { r: 169, g: 169, b: 169 },
952
+ lightgray: { r: 211, g: 211, b: 211 },
953
+ gainsboro: { r: 220, g: 220, b: 220 },
954
+ whitesmoke: { r: 245, g: 245, b: 245 },
955
+ red: { r: 255, g: 0, b: 0 },
956
+ crimson: { r: 220, g: 20, b: 60 },
957
+ tomato: { r: 255, g: 99, b: 71 },
958
+ coral: { r: 255, g: 127, b: 80 },
959
+ salmon: { r: 250, g: 128, b: 114 },
960
+ orange: { r: 255, g: 165, b: 0 },
961
+ gold: { r: 255, g: 215, b: 0 },
962
+ yellow: { r: 255, g: 255, b: 0 },
963
+ olive: { r: 128, g: 128, b: 0 },
964
+ lime: { r: 0, g: 255, b: 0 },
965
+ green: { r: 0, g: 128, b: 0 },
966
+ teal: { r: 0, g: 128, b: 128 },
967
+ turquoise: { r: 64, g: 224, b: 208 },
968
+ cyan: { r: 0, g: 255, b: 255 },
969
+ aqua: { r: 0, g: 255, b: 255 },
970
+ skyblue: { r: 135, g: 206, b: 235 },
971
+ dodgerblue: { r: 30, g: 144, b: 255 },
972
+ blue: { r: 0, g: 0, b: 255 },
973
+ navy: { r: 0, g: 0, b: 128 },
974
+ indigo: { r: 75, g: 0, b: 130 },
975
+ rebeccapurple: { r: 102, g: 51, b: 153 },
976
+ purple: { r: 128, g: 0, b: 128 },
977
+ violet: { r: 238, g: 130, b: 238 },
978
+ orchid: { r: 218, g: 112, b: 214 },
979
+ magenta: { r: 255, g: 0, b: 255 },
980
+ fuchsia: { r: 255, g: 0, b: 255 },
981
+ hotpink: { r: 255, g: 105, b: 180 },
982
+ pink: { r: 255, g: 192, b: 203 },
983
+ maroon: { r: 128, g: 0, b: 0 },
984
+ };
852
985
 
853
- if (isSide) {
854
- if (spanBadge) continue;
855
- if (radius > 0) findings.push({ id: 'side-tab', snippet: `border-${sn}: ${w}px + border-radius: ${radius}px` });
856
- else if (w >= 3) findings.push({ id: 'side-tab', snippet: `border-${sn}: ${w}px` });
857
- } else {
858
- if (radius > 0 && w >= 2) findings.push({ id: 'border-accent-on-rounded', snippet: `border-${sn}: ${w}px + border-radius: ${radius}px` });
859
- // Horizontal variant of the side-tab stripe: a thick chromatic accent
860
- // riding the top or bottom edge of a card/badge/container. Same
861
- // dominant-edge + chroma gates as left/right, 3-12px band. Selected-
862
- // tab underlines are exempt via opts.tabContext (adapters look for
863
- // tablist/nav/tab ancestors and aria-selected); links, buttons,
864
- // table cells, and <hr> never reach here (BORDER_SAFE_TAGS).
865
- else if (!opts.tabContext && w >= 3 && w <= 12) {
866
- findings.push({ id: 'side-tab', snippet: `border-${sn}: ${w}px` });
867
- }
986
+ // Split a string on top-level commas (ignoring commas nested in parens).
987
+ function splitTopLevelCommas(str) {
988
+ const parts = [];
989
+ let depth = 0, start = 0;
990
+ for (let i = 0; i < str.length; i++) {
991
+ const ch = str[i];
992
+ if (ch === '(') depth++;
993
+ else if (ch === ')') depth = Math.max(0, depth - 1);
994
+ else if (ch === ',' && depth === 0) {
995
+ parts.push(str.slice(start, i).trim());
996
+ start = i + 1;
868
997
  }
869
998
  }
870
-
871
- return findings;
872
- }
873
-
874
- // Returns true if the given text is composed entirely of emoji characters
875
- // (plus whitespace / variation selectors). Emojis render as multicolor glyphs
876
- // regardless of CSS `color`, so contrast checks against the element's text
877
- // color are meaningless for these nodes.
878
- const EMOJI_CHAR_RE = /[\u{1F1E6}-\u{1F1FF}\u{1F300}-\u{1F9FF}\u{1FA00}-\u{1FAFF}\u{2600}-\u{27BF}\u{2300}-\u{23FF}\u{FE0F}\u{200D}\u{1F3FB}-\u{1F3FF}]/u;
879
- const EMOJI_CHARS_GLOBAL = /[\u{1F1E6}-\u{1F1FF}\u{1F300}-\u{1F9FF}\u{1FA00}-\u{1FAFF}\u{2600}-\u{27BF}\u{2300}-\u{23FF}\u{FE0F}\u{200D}\u{1F3FB}-\u{1F3FF}]/gu;
880
- function isEmojiOnlyText(text) {
881
- if (!text) return false;
882
- if (!EMOJI_CHAR_RE.test(text)) return false;
883
- return text.replace(EMOJI_CHARS_GLOBAL, '').trim() === '';
999
+ const tail = str.slice(start).trim();
1000
+ if (tail) parts.push(tail);
1001
+ return parts;
884
1002
  }
885
1003
 
886
- function checkColors(opts) {
887
- const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList } = opts;
888
- if (SAFE_TAGS.has(tag)) {
889
- // Exception for elements styled as controls or chips. SAFE_TAGS exists to
890
- // suppress contrast noise on inline links and unstyled spans, where the
891
- // element has no own background and the contrast against the ancestor
892
- // surface is already the intended visual. When the element paints its own
893
- // opaque background under direct text, it is a styled button, chip, or
894
- // badge regardless of tag, and contrast on its own surface is a real,
895
- // frequent bug worth flagging. (The shipped miss: a <span> severity chip
896
- // whose white text lost a specificity fight and rendered muted-on-red at
897
- // 1.2:1; the old a/button-only exception never looked at it.) The 9px
898
- // font floor keeps sub-text decorations out.
899
- const isStyledControl = hasDirectText
900
- && ((bgColor && bgColor.a > 0.5)
901
- // A gradient painted on the element itself is an own surface the
902
- // same way a solid background is. Without this branch a nav CTA
903
- // built as `<a>` with `background: linear-gradient(…)` and a text
904
- // color that fails against every stop sails through on the
905
- // SAFE_TAGS suppression (the shipped escape).
906
- || (bgImage && /gradient/i.test(bgImage)))
907
- && fontSize >= 9;
908
- if (!isStyledControl) return [];
1004
+ // Evaluate a CSS color-mix() expression to {r,g,b,a}. Returns null when
1005
+ // the expression can't be resolved (unresolved var(), unknown colors).
1006
+ //
1007
+ // Mixing is done with premultiplied alpha in sRGB regardless of the
1008
+ // declared interpolation space. That is exact for the dominant generated-UI
1009
+ // pattern — `color-mix(in oklab, <color> N%, transparent)` — where the
1010
+ // result is simply <color> at alpha N% in ANY rectangular space, and a
1011
+ // close-enough approximation for opaque-opaque mixes (the detector only
1012
+ // consumes these values for contrast/chroma thresholds, not for display).
1013
+ function parseColorMix(str) {
1014
+ const m = String(str).trim().match(/^color-mix\(/i);
1015
+ if (!m) return null;
1016
+ // Balanced-paren capture of the arguments.
1017
+ let depth = 0, end = -1;
1018
+ const open = str.indexOf('(');
1019
+ for (let i = open; i < str.length; i++) {
1020
+ if (str[i] === '(') depth++;
1021
+ else if (str[i] === ')') { depth--; if (depth === 0) { end = i; break; } }
909
1022
  }
910
- const findings = [];
1023
+ if (end < 0) return null;
1024
+ const args = splitTopLevelCommas(str.slice(open + 1, end));
1025
+ if (args.length !== 3 || !/^in\s/i.test(args[0])) return null;
911
1026
 
912
- if (hasDirectText && textColor && !isEmojiOnly) {
913
- // Gradient-clipped text (`background-clip: text`, typically with a
914
- // transparent text-fill) paints its glyphs *with* the element's own
915
- // gradient. The `color` value the cascade still reports is never painted,
916
- // and the gradient is the fill, not a backdrop — so measuring `color`
917
- // against that gradient (which resolveGradientStops picks up as the
918
- // element's own background-image) is a guaranteed false positive
919
- // (issue #409 Case A). Skip the backdrop-contrast checks; the gradient-text
920
- // rule below still flags the pattern itself. Skipping a rule beats a false
921
- // positive here — the true painted contrast can't be measured from `color`.
922
- const isGradientClippedText = bgClip === 'text';
923
- // Run background-dependent checks against either a solid bg or, if the
924
- // ancestor is a gradient, against every gradient stop (use the worst case).
925
- const bgs = isGradientClippedText
926
- ? null
927
- : (effectiveBg ? [effectiveBg] : (effectiveBgStops && effectiveBgStops.length ? effectiveBgStops : null));
928
- if (bgs) {
929
- // Gray on colored background — flag if every stop is chromatic
1027
+ const parseComponent = (component) => {
1028
+ // Percentage may lead or trail the color per spec.
1029
+ let pct = null;
1030
+ let colorStr = component;
1031
+ const trail = component.match(/\s+([\d.]+)%$/);
1032
+ const lead = component.match(/^([\d.]+)%\s+/);
1033
+ if (trail) { pct = parseFloat(trail[1]); colorStr = component.slice(0, trail.index).trim(); }
1034
+ else if (lead) { pct = parseFloat(lead[1]); colorStr = component.slice(lead[0].length).trim(); }
1035
+ let color;
1036
+ if (/^transparent$/i.test(colorStr)) color = { r: 0, g: 0, b: 0, a: 0 };
1037
+ else color = parseAnyColor(colorStr);
1038
+ if (!color) return null;
1039
+ return { color, pct };
1040
+ };
1041
+
1042
+ const c1 = parseComponent(args[1]);
1043
+ const c2 = parseComponent(args[2]);
1044
+ if (!c1 || !c2) return null;
1045
+ let p1 = c1.pct, p2 = c2.pct;
1046
+ if (p1 == null && p2 == null) { p1 = 50; p2 = 50; }
1047
+ else if (p1 == null) p1 = 100 - p2;
1048
+ else if (p2 == null) p2 = 100 - p1;
1049
+ const sum = p1 + p2;
1050
+ if (sum <= 0) return null;
1051
+ // Per spec: weights normalize to sum; when sum < 100 the result alpha is
1052
+ // additionally scaled by sum/100.
1053
+ const w1 = p1 / sum, w2 = p2 / sum;
1054
+ const alphaScale = sum < 100 ? sum / 100 : 1;
1055
+ const a1 = c1.color.a ?? 1, a2 = c2.color.a ?? 1;
1056
+ const a = (a1 * w1 + a2 * w2) * alphaScale;
1057
+ if (a <= 0) return { r: 0, g: 0, b: 0, a: 0 };
1058
+ const mix = (ch) => Math.round((c1.color[ch] * a1 * w1 + c2.color[ch] * a2 * w2) / (a1 * w1 + a2 * w2));
1059
+ return { r: mix('r'), g: mix('g'), b: mix('b'), a: Math.min(1, a) };
1060
+ }
1061
+
1062
+ // Composite a translucent color over an opaque(ish) base (simple
1063
+ // source-over in sRGB). Returns an opaque {r,g,b,a:1}.
1064
+ function compositeColorOver(top, base) {
1065
+ const a = top.a ?? 1;
1066
+ return {
1067
+ r: Math.round(top.r * a + base.r * (1 - a)),
1068
+ g: Math.round(top.g * a + base.g * (1 - a)),
1069
+ b: Math.round(top.b * a + base.b * (1 - a)),
1070
+ a: 1,
1071
+ };
1072
+ }
1073
+
1074
+ // A color() / lab() / lch() component: a bare number, a percentage against
1075
+ // `scale`, or the `none` keyword (which resolves to zero for our purposes).
1076
+ function parseColorComponent(token, scale = 1) {
1077
+ if (token == null) return null;
1078
+ const t = String(token).trim();
1079
+ if (/^none$/i.test(t)) return 0;
1080
+ const num = parseFloat(t);
1081
+ if (!Number.isFinite(num)) return null;
1082
+ return t.endsWith('%') ? (num / 100) * scale : num;
1083
+ }
1084
+
1085
+ function parseAlphaToken(token) {
1086
+ if (token == null) return 1;
1087
+ const t = String(token).trim();
1088
+ if (/^none$/i.test(t)) return 1;
1089
+ const num = parseFloat(t);
1090
+ if (!Number.isFinite(num)) return 1;
1091
+ return t.endsWith('%') ? num / 100 : num;
1092
+ }
1093
+
1094
+ // Extended color parser: rgb/rgba/hex/oklch/oklab/lch/lab/hsl/hwb/color()/
1095
+ // color-mix/common named colors. Returns null on no match. Use this when the
1096
+ // input might be any CSS color form; use plain parseRgb when you only expect
1097
+ // computed rgb() values from real browsers.
1098
+ function parseAnyColor(s) {
1099
+ if (!s || typeof s !== 'string') return null;
1100
+ const str = s.trim();
1101
+ if (str === 'transparent' || str === 'currentcolor' || str === 'inherit') return null;
1102
+ if (/^color-mix\(/i.test(str)) return parseColorMix(str);
1103
+ let m;
1104
+ m = str.match(/rgba?\(\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)(?:\s*[,/]\s*([\d.]+)(%)?)?\s*\)/);
1105
+ if (m) {
1106
+ const c = { r: Math.round(+m[1]), g: Math.round(+m[2]), b: Math.round(+m[3]), a: 1 };
1107
+ if (m[4] !== undefined) c.a = m[5] === '%' ? parseFloat(m[4]) / 100 : +m[4];
1108
+ return c;
1109
+ }
1110
+ m = str.match(/^#([0-9a-f]{3,8})$/i);
1111
+ if (m) {
1112
+ const h = m[1];
1113
+ if (h.length === 3 || h.length === 4) {
1114
+ return {
1115
+ r: parseInt(h[0] + h[0], 16),
1116
+ g: parseInt(h[1] + h[1], 16),
1117
+ b: parseInt(h[2] + h[2], 16),
1118
+ a: h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1,
1119
+ };
1120
+ }
1121
+ if (h.length === 6 || h.length === 8) {
1122
+ return {
1123
+ r: parseInt(h.slice(0, 2), 16),
1124
+ g: parseInt(h.slice(2, 4), 16),
1125
+ b: parseInt(h.slice(4, 6), 16),
1126
+ a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
1127
+ };
1128
+ }
1129
+ }
1130
+ // OKLCH parser. Tailwind v4's CSS minifier squishes the space after
1131
+ // `%` ("21.5%.02 50"), so the separator between L and C may be absent.
1132
+ // Match L (with optional %), then C and H separated permissively.
1133
+ m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
1134
+ if (m) {
1135
+ const Lnum = parseFloat(m[1]);
1136
+ const L = m[2] === '%' ? Lnum / 100 : Lnum;
1137
+ const rgb = oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]));
1138
+ if (m[5] !== undefined) {
1139
+ const alpha = parseFloat(m[5]);
1140
+ rgb.a = m[6] === '%' ? alpha / 100 : alpha;
1141
+ }
1142
+ return rgb;
1143
+ }
1144
+ // OKLAB — a/b are signed axes; percentages map 100% → 0.4.
1145
+ m = str.match(/oklab\(\s*([\d.]+)(%?)\s+(-?[\d.]+)(%?)\s+(-?[\d.]+)(%?)(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
1146
+ if (m) {
1147
+ const L = m[2] === '%' ? parseFloat(m[1]) / 100 : parseFloat(m[1]);
1148
+ const a = m[4] === '%' ? parseFloat(m[3]) * 0.004 : parseFloat(m[3]);
1149
+ const b = m[6] === '%' ? parseFloat(m[5]) * 0.004 : parseFloat(m[5]);
1150
+ const rgb = oklabToRgb(L, a, b);
1151
+ if (m[7] !== undefined) {
1152
+ const alpha = parseFloat(m[7]);
1153
+ rgb.a = m[8] === '%' ? alpha / 100 : alpha;
1154
+ }
1155
+ return rgb;
1156
+ }
1157
+ // LCH / LAB — CIE, D50 white point. Chrome serializes lch(20% 5 60) as
1158
+ // `lch(20 5 60)`, so L arrives with or without its percent sign. In both
1159
+ // spaces L runs 0..100 and 100% means 100.
1160
+ m = str.match(/^lch\(\s*([\d.]+%?|none)\s+([\d.]+%?|none)\s+(-?[\d.]+)(?:deg)?(?:\s*\/\s*([\d.]+%?|none))?\s*\)$/i);
1161
+ if (m) {
1162
+ const L = parseColorComponent(m[1], 100);
1163
+ const C = parseColorComponent(m[2], 150);
1164
+ const H = parseFloat(m[3]);
1165
+ if (L == null || C == null || !Number.isFinite(H)) return null;
1166
+ const rgb = lchToRgb(L, C, H);
1167
+ rgb.a = parseAlphaToken(m[4]);
1168
+ return rgb;
1169
+ }
1170
+ m = str.match(/^lab\(\s*([\d.]+%?|none)\s+(-?[\d.]+%?|none)\s+(-?[\d.]+%?|none)(?:\s*\/\s*([\d.]+%?|none))?\s*\)$/i);
1171
+ if (m) {
1172
+ const L = parseColorComponent(m[1], 100);
1173
+ const a = parseColorComponent(m[2], 125);
1174
+ const b = parseColorComponent(m[3], 125);
1175
+ if (L == null || a == null || b == null) return null;
1176
+ const rgb = labToRgb(L, a, b);
1177
+ rgb.a = parseAlphaToken(m[4]);
1178
+ return rgb;
1179
+ }
1180
+ // color(<space> c1 c2 c3 [/ alpha]) — what Chrome hands back for most
1181
+ // color-mix() results and for any wide-gamut color an author wrote.
1182
+ m = str.match(/^color\(\s*([a-z0-9-]+)\s+(-?[\d.eE+-]+%?|none)\s+(-?[\d.eE+-]+%?|none)\s+(-?[\d.eE+-]+%?|none)(?:\s*\/\s*([\d.]+%?|none))?\s*\)$/i);
1183
+ if (m) {
1184
+ const c1 = parseColorComponent(m[2]);
1185
+ const c2 = parseColorComponent(m[3]);
1186
+ const c3 = parseColorComponent(m[4]);
1187
+ if (c1 == null || c2 == null || c3 == null) return null;
1188
+ const rgb = colorFunctionToRgb(m[1].toLowerCase(), c1, c2, c3);
1189
+ if (!rgb) return null;
1190
+ rgb.a = parseAlphaToken(m[5]);
1191
+ return rgb;
1192
+ }
1193
+ // HSL/HSLA — comma or space syntax, optional deg on hue.
1194
+ m = str.match(/hsla?\(\s*(-?[\d.]+)(?:deg)?\s*[,\s]\s*([\d.]+)%\s*[,\s]\s*([\d.]+)%(?:\s*[,/]\s*([\d.]+)(%)?)?\s*\)/i);
1195
+ if (m) {
1196
+ const rgb = hslToRgb(parseFloat(m[1]), parseFloat(m[2]) / 100, parseFloat(m[3]) / 100);
1197
+ if (m[4] !== undefined) {
1198
+ const alpha = parseFloat(m[4]);
1199
+ rgb.a = m[5] === '%' ? alpha / 100 : alpha;
1200
+ }
1201
+ return rgb;
1202
+ }
1203
+ // HWB — hue whiteness% blackness%.
1204
+ m = str.match(/hwb\(\s*(-?[\d.]+)(?:deg)?\s+([\d.]+)%\s+([\d.]+)%(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
1205
+ if (m) {
1206
+ const rgb = hwbToRgb(parseFloat(m[1]), parseFloat(m[2]) / 100, parseFloat(m[3]) / 100);
1207
+ if (m[4] !== undefined) {
1208
+ const alpha = parseFloat(m[4]);
1209
+ rgb.a = m[5] === '%' ? alpha / 100 : alpha;
1210
+ }
1211
+ return rgb;
1212
+ }
1213
+ const named = CSS_NAMED_COLORS[str.toLowerCase()];
1214
+ if (named) return { ...named, a: 1 };
1215
+ return null;
1216
+ }
1217
+
1218
+ // True when a computed background-color string names no paint at all. Used to
1219
+ // tell "this layer is see-through" (walk on to the ancestor) apart from "this
1220
+ // layer has a color we could not read" (stop and abstain).
1221
+ //
1222
+ // `inherit` belongs here even though it is not literally see-through: it means
1223
+ // "paint with the parent's background-color", and walking on to the parent IS
1224
+ // that resolution. Real browsers resolve the keyword before getComputedStyle
1225
+ // output; only jsdom's partial cascade hands it through verbatim, and treating
1226
+ // it as unreadable would make the walk abstain on a surface it can know.
1227
+ // (`currentcolor` is NOT here — it is real paint in the element's own text
1228
+ // color; resolveBackgroundInfo substitutes the computed color for it.)
1229
+ function isNoPaintColorValue(value) {
1230
+ const v = String(value || '').trim().toLowerCase();
1231
+ if (!v) return true;
1232
+ return v === 'transparent' || v === 'none' || v === 'initial' || v === 'inherit' || v === 'unset' || v === 'revert' || v === 'revert-layer';
1233
+ }
1234
+
1235
+ // --- cli/engine/shared/fonts.mjs ---
1236
+ const GOOGLE_FONTS_URL_RE = /fonts\.googleapis\.com\/css2?\?[^"'\s)<>]*/gi;
1237
+
1238
+ function normalizeGoogleFontFamilyParam(value) {
1239
+ return String(value || '')
1240
+ .split('|')
1241
+ .map(part => part.split(':')[0].trim().toLowerCase())
1242
+ .filter(Boolean);
1243
+ }
1244
+
1245
+ function extractGoogleFontFamilies(text) {
1246
+ const families = [];
1247
+ if (!text) return families;
1248
+
1249
+ GOOGLE_FONTS_URL_RE.lastIndex = 0;
1250
+ let urlMatch;
1251
+ while ((urlMatch = GOOGLE_FONTS_URL_RE.exec(text)) !== null) {
1252
+ const url = urlMatch[0];
1253
+ const queryStart = url.indexOf('?');
1254
+ if (queryStart === -1) continue;
1255
+
1256
+ const params = new URLSearchParams(url.slice(queryStart + 1).replace(/&amp;/g, '&'));
1257
+ for (const value of params.getAll('family')) {
1258
+ families.push(...normalizeGoogleFontFamilyParam(value));
1259
+ }
1260
+ }
1261
+
1262
+ return families;
1263
+ }
1264
+
1265
+ // --- cli/engine/rules/checks.mjs ---
1266
+ const DETECTOR_IS_BROWSER = typeof window !== 'undefined';
1267
+
1268
+ // ─── Section 3: Pure Detection ──────────────────────────────────────────────
1269
+
1270
+ function checkBorders(tag, widths, colors, radius, opts = {}) {
1271
+ // Badge-shaped <span>s (own visible background) are a real stripe target
1272
+ // for the top/bottom variant — the inline-tag exemption exists to quiet
1273
+ // text-level borders, not chips. They skip the left/right arms below.
1274
+ const spanBadge = tag === 'span' && !!opts.badgeLike;
1275
+ if (BORDER_SAFE_TAGS.has(tag) && !spanBadge) return [];
1276
+ // A live status/alert region wears a colored single-edge border as a
1277
+ // severity accent (toast, snackbar, callout), not as the side-tab tell.
1278
+ if (opts.statusContext) return [];
1279
+ const findings = [];
1280
+ const sides = ['Top', 'Right', 'Bottom', 'Left'];
1281
+
1282
+ for (const side of sides) {
1283
+ const w = widths[side];
1284
+ if (w < 1 || isNeutralColor(colors[side])) continue;
1285
+
1286
+ const otherSides = sides.filter(s => s !== side);
1287
+ const maxOther = Math.max(...otherSides.map(s => widths[s]));
1288
+ if (!(w >= 2 && (maxOther <= 1 || w >= maxOther * 2))) continue;
1289
+
1290
+ const sn = side.toLowerCase();
1291
+ const isSide = side === 'Left' || side === 'Right';
1292
+
1293
+ if (isSide) {
1294
+ if (spanBadge) continue;
1295
+ if (radius > 0) findings.push({ id: 'side-tab', snippet: `border-${sn}: ${w}px + border-radius: ${radius}px` });
1296
+ else if (w >= 3) findings.push({ id: 'side-tab', snippet: `border-${sn}: ${w}px` });
1297
+ } else {
1298
+ if (radius > 0 && w >= 2) findings.push({ id: 'border-accent-on-rounded', snippet: `border-${sn}: ${w}px + border-radius: ${radius}px` });
1299
+ // Horizontal variant of the side-tab stripe: a thick chromatic accent
1300
+ // riding the top or bottom edge of a card/badge/container. Same
1301
+ // dominant-edge + chroma gates as left/right, 3-12px band. Selected-
1302
+ // tab underlines are exempt via opts.tabContext (adapters look for
1303
+ // tablist/nav/tab ancestors and aria-selected); links, buttons,
1304
+ // table cells, and <hr> never reach here (BORDER_SAFE_TAGS).
1305
+ else if (!opts.tabContext && w >= 3 && w <= 12) {
1306
+ findings.push({ id: 'side-tab', snippet: `border-${sn}: ${w}px` });
1307
+ }
1308
+ }
1309
+ }
1310
+
1311
+ return findings;
1312
+ }
1313
+
1314
+ // ─── Scoped ignores: data-impeccable-ignore ─────────────────────────────────
1315
+ //
1316
+ // An element-scoped waiver that travels with the markup: any element carrying
1317
+ // `data-impeccable-ignore="rule-a rule-b"` (or `*`, or an empty value, for
1318
+ // every rule) suppresses matching findings from itself and its entire subtree,
1319
+ // in every engine that walks elements — the browser overlay, the extension,
1320
+ // and the static scan. This is the DOM twin of the line-based
1321
+ // `impeccable-disable` comment directives, which the browser cannot apply (a
1322
+ // live DOM has no line numbers), and the generalization of the one-off
1323
+ // `data-impeccable-allow-kickers` opt-out.
1324
+ //
1325
+ // The intended use is curated exhibits: a page that documents anti-patterns by
1326
+ // example, or renders a deliberate "before" specimen, marks the container once
1327
+ // and every engine skips it while still scanning the page around it.
1328
+ function scopedIgnoreActive(el, ruleId) {
1329
+ const rule = String(ruleId || '').toLowerCase();
1330
+ let cur = el;
1331
+ while (cur && cur.nodeType === 1) {
1332
+ const attr = typeof cur.getAttribute === 'function' ? cur.getAttribute('data-impeccable-ignore') : null;
1333
+ if (attr != null) {
1334
+ const rules = String(attr).trim().toLowerCase().split(/[\s,]+/).filter(Boolean);
1335
+ if (rules.length === 0 || rules.includes('*') || rules.includes(rule)) return true;
1336
+ }
1337
+ cur = cur.parentElement;
1338
+ }
1339
+ return false;
1340
+ }
1341
+
1342
+ // Returns true if the given text is composed entirely of emoji characters
1343
+ // (plus whitespace / variation selectors). Emojis render as multicolor glyphs
1344
+ // regardless of CSS `color`, so contrast checks against the element's text
1345
+ // color are meaningless for these nodes.
1346
+ const EMOJI_CHAR_RE = /[\u{1F1E6}-\u{1F1FF}\u{1F300}-\u{1F9FF}\u{1FA00}-\u{1FAFF}\u{2600}-\u{27BF}\u{2300}-\u{23FF}\u{FE0F}\u{200D}\u{1F3FB}-\u{1F3FF}]/u;
1347
+ const EMOJI_CHARS_GLOBAL = /[\u{1F1E6}-\u{1F1FF}\u{1F300}-\u{1F9FF}\u{1FA00}-\u{1FAFF}\u{2600}-\u{27BF}\u{2300}-\u{23FF}\u{FE0F}\u{200D}\u{1F3FB}-\u{1F3FF}]/gu;
1348
+ function isEmojiOnlyText(text) {
1349
+ if (!text) return false;
1350
+ if (!EMOJI_CHAR_RE.test(text)) return false;
1351
+ return text.replace(EMOJI_CHARS_GLOBAL, '').trim() === '';
1352
+ }
1353
+
1354
+ function checkColors(opts) {
1355
+ const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList } = opts;
1356
+ if (SAFE_TAGS.has(tag)) {
1357
+ // Exception for elements styled as controls or chips. SAFE_TAGS exists to
1358
+ // suppress contrast noise on inline links and unstyled spans, where the
1359
+ // element has no own background and the contrast against the ancestor
1360
+ // surface is already the intended visual. When the element paints its own
1361
+ // opaque background under direct text, it is a styled button, chip, or
1362
+ // badge regardless of tag, and contrast on its own surface is a real,
1363
+ // frequent bug worth flagging. (The shipped miss: a <span> severity chip
1364
+ // whose white text lost a specificity fight and rendered muted-on-red at
1365
+ // 1.2:1; the old a/button-only exception never looked at it.) The 9px
1366
+ // font floor keeps sub-text decorations out.
1367
+ const isStyledControl = hasDirectText
1368
+ && ((bgColor && bgColor.a > 0.5)
1369
+ // A gradient painted on the element itself is an own surface the
1370
+ // same way a solid background is. Without this branch a nav CTA
1371
+ // built as `<a>` with `background: linear-gradient(…)` and a text
1372
+ // color that fails against every stop sails through on the
1373
+ // SAFE_TAGS suppression (the shipped escape).
1374
+ || (bgImage && /gradient/i.test(bgImage)))
1375
+ && fontSize >= 9;
1376
+ if (!isStyledControl) return [];
1377
+ }
1378
+ const findings = [];
1379
+
1380
+ if (hasDirectText && textColor && !isEmojiOnly) {
1381
+ // Gradient-clipped text (`background-clip: text`, typically with a
1382
+ // transparent text-fill) paints its glyphs *with* the element's own
1383
+ // gradient. The `color` value the cascade still reports is never painted,
1384
+ // and the gradient is the fill, not a backdrop — so measuring `color`
1385
+ // against that gradient (which resolveGradientStops picks up as the
1386
+ // element's own background-image) is a guaranteed false positive
1387
+ // (issue #409 Case A). Skip the backdrop-contrast checks; the gradient-text
1388
+ // rule below still flags the pattern itself. Skipping a rule beats a false
1389
+ // positive here — the true painted contrast can't be measured from `color`.
1390
+ const isGradientClippedText = bgClip === 'text';
1391
+ // Run background-dependent checks against either a solid bg or, if the
1392
+ // ancestor is a gradient, against every gradient stop (use the worst case).
1393
+ const bgs = isGradientClippedText
1394
+ ? null
1395
+ : (effectiveBg ? [effectiveBg] : (effectiveBgStops && effectiveBgStops.length ? effectiveBgStops : null));
1396
+ if (bgs) {
1397
+ // Gray on colored background — flag if every stop is chromatic
930
1398
  const textLum = relativeLuminance(textColor);
931
1399
  const isGray = !hasChroma(textColor, 20) && textLum > 0.05 && textLum < 0.85;
932
1400
  if (isGray && bgs.every(b => hasChroma(b, 40))) {
@@ -1438,6 +1906,26 @@ function cssTextHasDarkRootBg(content, customProps) {
1438
1906
  return false;
1439
1907
  }
1440
1908
 
1909
+ // Best-effort extraction of the CSS selector whose declaration block contains
1910
+ // the given index in raw CSS text. Lets CSS-text findings carry a live-DOM
1911
+ // anchor, so the browser pass can resolve scoped ignores against the actual
1912
+ // element and drop patterns that render nowhere on the page. Returns null for
1913
+ // @-rule preludes, keyframe steps, nested blocks, and anything that does not
1914
+ // read as a selector; those findings stay page-level.
1915
+ function enclosingCssSelector(cssText, index) {
1916
+ if (!cssText || !Number.isFinite(index)) return null;
1917
+ const open = cssText.lastIndexOf('{', index);
1918
+ if (open === -1) return null;
1919
+ const prevClose = Math.max(cssText.lastIndexOf('}', open - 1), cssText.lastIndexOf(';', open - 1));
1920
+ const raw = cssText.slice(prevClose + 1, open).trim().replace(/\s+/g, ' ');
1921
+ if (!raw || raw.startsWith('@') || /^\d/.test(raw) || /[{}<]/.test(raw)) return null;
1922
+ // Keyframe steps: percentage steps fail the digit test above, but `from`
1923
+ // and `to` would read as (never-matching) type selectors and get a valid
1924
+ // finding wrongly dropped by the zero-match rule downstream.
1925
+ if (/^(?:from|to)(?:\s*,\s*(?:from|to))*$/i.test(raw)) return null;
1926
+ return raw;
1927
+ }
1928
+
1441
1929
  function scanCssTextForGlow(content) {
1442
1930
  const customProps = collectCssCustomProps(content);
1443
1931
  const hasDarkBg = cssTextHasDarkRootBg(content, customProps);
@@ -1749,6 +2237,7 @@ function scanCssTextForPseudoStripe(rawContent) {
1749
2237
  id: 'side-tab',
1750
2238
  snippet: `${selector} — absolute ${thicknessPx}px pseudo-element stripe (${edge}: 0)`,
1751
2239
  index: selectorStart,
2240
+ selector,
1752
2241
  });
1753
2242
  }
1754
2243
  return findings;
@@ -1811,6 +2300,7 @@ function scanCssTextForInsetStripe(content) {
1811
2300
  findings.push({
1812
2301
  id: 'side-tab',
1813
2302
  snippet: `${selector} — inset box-shadow ${ay === 0 ? ax : ay}px stripe (${edge})`,
2303
+ selector,
1814
2304
  });
1815
2305
  break;
1816
2306
  }
@@ -1863,10 +2353,12 @@ function collectMarqueeKeyframes(content) {
1863
2353
  // bound to a keyframe loop that travels a large horizontal distance.
1864
2354
  // Rotation/opacity animations never qualify (no X travel); JS-driven
1865
2355
  // carousels with user controls have no infinite CSS X-loop to match.
1866
- function scanCssTextForMarquee(content) {
2356
+ // `content` is CSS-bearing text; `markup` (defaulting to the same string
2357
+ // for single-corpus callers) is where the <marquee> tag itself lives.
2358
+ function scanCssTextForMarquee(content, markup = content) {
1867
2359
  const findings = [];
1868
- if (/<marquee\b/i.test(content)) {
1869
- findings.push({ id: 'marquee', snippet: '<marquee> element' });
2360
+ if (/<marquee\b/i.test(markup)) {
2361
+ findings.push({ id: 'marquee', snippet: '<marquee> element', selector: 'marquee' });
1870
2362
  }
1871
2363
  const marqueeKeyframes = collectMarqueeKeyframes(content);
1872
2364
  if (marqueeKeyframes.size === 0) return findings;
@@ -1881,7 +2373,7 @@ function scanCssTextForMarquee(content) {
1881
2373
  const key = `${selector} ${name}`;
1882
2374
  if (seen.has(key)) continue;
1883
2375
  seen.add(key);
1884
- findings.push({ id: 'marquee', snippet: `${selector} — infinite horizontal loop animation "${name}"` });
2376
+ findings.push({ id: 'marquee', snippet: `${selector} — infinite horizontal loop animation "${name}"`, selector });
1885
2377
  }
1886
2378
  }
1887
2379
  return findings;
@@ -2044,10 +2536,14 @@ function selectorHitsLandmark(content, selector, ranges) {
2044
2536
  // element sits inside a header/nav landmark is the hero liveness cliché
2045
2537
  // and is promoted to error severity; occurrences elsewhere keep the
2046
2538
  // registry default severity.
2047
- function scanCssTextForPulsingDot(content) {
2539
+ //
2540
+ // `content` is CSS-bearing text (rules and keyframes); `markup` — defaulting
2541
+ // to the same string for single-corpus callers like the regex source
2542
+ // engine — is where landmark ranges and Tailwind class attributes live.
2543
+ function scanCssTextForPulsingDot(content, markup = content) {
2048
2544
  const customProps = collectCssCustomProps(content);
2049
2545
  const keyframes = collectPulseKeyframes(content);
2050
- const heroRanges = landmarkSourceRanges(content);
2546
+ const heroRanges = landmarkSourceRanges(markup);
2051
2547
  const findings = [];
2052
2548
  const seen = new Set();
2053
2549
 
@@ -2096,7 +2592,7 @@ function scanCssTextForPulsingDot(content) {
2096
2592
 
2097
2593
  if (seen.has(selector)) continue;
2098
2594
  seen.add(selector);
2099
- const inLandmark = selectorHitsLandmark(content, selector, heroRanges);
2595
+ const inLandmark = selectorHitsLandmark(markup, selector, heroRanges);
2100
2596
  findings.push({
2101
2597
  id: 'pulsing-dot',
2102
2598
  snippet: `${selector} — ${w}x${h}px dot with infinite "${pulseName}" animation${inLandmark ? ' in header/nav' : ''}`,
@@ -2106,10 +2602,11 @@ function scanCssTextForPulsingDot(content) {
2106
2602
  }
2107
2603
 
2108
2604
  // Tailwind utilities: animate-ping / animate-pulse on a tiny rounded-full
2109
- // element declared entirely in the class attribute.
2605
+ // element declared entirely in the class attribute. Scanned in the markup
2606
+ // corpus so the match index lines up with the landmark ranges.
2110
2607
  const classRe = /class\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
2111
2608
  let cm;
2112
- while ((cm = classRe.exec(content)) !== null) {
2609
+ while ((cm = classRe.exec(markup)) !== null) {
2113
2610
  const cls = cm[1] || cm[2] || '';
2114
2611
  const anim = cls.match(/\banimate-(ping|pulse)\b/);
2115
2612
  if (!anim) continue;
@@ -2190,36 +2687,82 @@ function scanHtmlForShapeAssembledIllustration(html) {
2190
2687
  return findings;
2191
2688
  }
2192
2689
 
2690
+ // Scoped scan corpora for the page-level pattern checks. CSS-property
2691
+ // regexes run over the whole source string fire on documentation ABOUT
2692
+ // css — `<code>background-clip: text</code>` prose, <pre> samples, HTML
2693
+ // comments — so the checks scan only the strings that actually style the
2694
+ // page:
2695
+ // styleText — <style> block contents plus style="…" attribute values.
2696
+ // Attribute values keep their `style="…"` form so block-scoped
2697
+ // scanners (grid background) keep treating each attribute as one
2698
+ // declaration block, exactly as they did against raw source. Engines
2699
+ // that already read more CSS (linked stylesheets) prepend it.
2700
+ // classText — class attribute values, for utility-class scans.
2701
+ // Markup-shaped checks (inline <svg> scenes, <img> tags, <marquee>,
2702
+ // landmark ranges) and rendered-text checks (theater phrases) keep the
2703
+ // full source. This extraction serves callers without a parsed document
2704
+ // (the browser bundle scanning outerHTML); attribute reads are tag-scoped
2705
+ // so escaped code samples (&lt;div style="…"&gt;) never contribute. The
2706
+ // static engine passes richer corpora built from its parsed document.
2707
+ // Bare CSS input (no markup at all) is its own style text, which keeps
2708
+ // direct checkHtmlPatterns(css) callers behaving as before.
2709
+ function buildHtmlPatternCorpora(html) {
2710
+ const source = String(html || '');
2711
+ if (!/<[a-zA-Z!/]/.test(source)) {
2712
+ return { styleText: source, classText: source };
2713
+ }
2714
+ const styleParts = [];
2715
+ const classParts = [];
2716
+ const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
2717
+ let m;
2718
+ while ((m = styleBlockRe.exec(source)) !== null) styleParts.push(m[1]);
2719
+ const tagRe = /<[a-zA-Z][^>]*>/g;
2720
+ while ((m = tagRe.exec(source)) !== null) {
2721
+ const tag = m[0];
2722
+ const sm = tag.match(/\bstyle\s*=\s*("[^"]*"|'[^']*')/i);
2723
+ if (sm) styleParts.push(`style=${sm[1]}`);
2724
+ const cm = tag.match(/\bclass\s*=\s*(?:"([^"]*)"|'([^']*)')/i);
2725
+ if (cm) classParts.push(cm[1] ?? cm[2] ?? '');
2726
+ }
2727
+ return { styleText: styleParts.join('\n'), classText: classParts.join('\n') };
2728
+ }
2729
+
2193
2730
  /**
2194
2731
  * Regex-on-HTML checks shared between browser and Node page-level detection.
2195
- * These don't need DOM access, just the raw HTML string.
2732
+ * These don't need DOM access, just the raw HTML string. CSS-property and
2733
+ * utility-class patterns scan the scoped corpora (styleText / classText —
2734
+ * see buildHtmlPatternCorpora) so prose about css never flags; only the
2735
+ * markup-shaped and rendered-text checks read the full source.
2196
2736
  */
2197
- function checkHtmlPatterns(html) {
2737
+ function checkHtmlPatterns(html, corpora) {
2738
+ const { styleText, classText } = corpora || buildHtmlPatternCorpora(html);
2198
2739
  const findings = [];
2199
2740
 
2200
2741
  // --- Color ---
2201
2742
 
2202
2743
  // AI color palette: purple/violet
2203
2744
  const purpleHexRe = /#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9|6366f1|764ba2|667eea)\b/gi;
2204
- if (purpleHexRe.test(html)) {
2745
+ if (purpleHexRe.test(styleText)) {
2205
2746
  const purpleTextRe = /(?:(?:^|;)\s*color\s*:\s*(?:.*?)(?:#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9))|gradient.*?#(?:7c3aed|8b5cf6|a855f7|764ba2|667eea))/gi;
2206
- if (purpleTextRe.test(html)) {
2207
- findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet accent colors detected' });
2747
+ purpleTextRe.lastIndex = 0;
2748
+ const purpleMatch = purpleTextRe.exec(styleText);
2749
+ if (purpleMatch) {
2750
+ findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet accent colors detected', selector: enclosingCssSelector(styleText, purpleMatch.index + 1) || undefined });
2208
2751
  }
2209
2752
  }
2210
2753
 
2211
2754
  // Gradient text (background-clip: text + gradient)
2212
2755
  const gradientRe = /(?:-webkit-)?background-clip\s*:\s*text/gi;
2213
2756
  let gm;
2214
- while ((gm = gradientRe.exec(html)) !== null) {
2757
+ while ((gm = gradientRe.exec(styleText)) !== null) {
2215
2758
  const start = Math.max(0, gm.index - 200);
2216
- const context = html.substring(start, gm.index + gm[0].length + 200);
2759
+ const context = styleText.substring(start, gm.index + gm[0].length + 200);
2217
2760
  if (/gradient/i.test(context)) {
2218
- findings.push({ id: 'gradient-text', snippet: 'background-clip: text + gradient' });
2761
+ findings.push({ id: 'gradient-text', snippet: 'background-clip: text + gradient', selector: enclosingCssSelector(styleText, gm.index) || undefined });
2219
2762
  break;
2220
2763
  }
2221
2764
  }
2222
- if (/\bbg-clip-text\b/.test(html) && /\bbg-gradient-to-/.test(html)) {
2765
+ if (/\bbg-clip-text\b/.test(classText) && /\bbg-gradient-to-/.test(classText)) {
2223
2766
  findings.push({ id: 'gradient-text', snippet: 'bg-clip-text + bg-gradient (Tailwind)' });
2224
2767
  }
2225
2768
 
@@ -2228,10 +2771,10 @@ function checkHtmlPatterns(html) {
2228
2771
  // Side-tab accent stripe drawn as an absolutely-positioned pseudo-element
2229
2772
  // (no border property involved, so the element-level border checks and
2230
2773
  // the border-left regexes never see it).
2231
- findings.push(...scanCssTextForPseudoStripe(html));
2774
+ findings.push(...scanCssTextForPseudoStripe(styleText));
2232
2775
 
2233
2776
  // Side-tab accent stripe drawn as a single-edge inset box-shadow.
2234
- findings.push(...scanCssTextForInsetStripe(html));
2777
+ findings.push(...scanCssTextForInsetStripe(styleText));
2235
2778
 
2236
2779
  // --- Layout ---
2237
2780
 
@@ -2239,20 +2782,20 @@ function checkHtmlPatterns(html) {
2239
2782
  const spacingValues = [];
2240
2783
  const spacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*(\d+)px/gi;
2241
2784
  let sm;
2242
- while ((sm = spacingRe.exec(html)) !== null) {
2785
+ while ((sm = spacingRe.exec(styleText)) !== null) {
2243
2786
  const v = parseInt(sm[1], 10);
2244
2787
  if (v > 0 && v < 200) spacingValues.push(v);
2245
2788
  }
2246
2789
  const gapRe = /gap\s*:\s*(\d+)px/gi;
2247
- while ((sm = gapRe.exec(html)) !== null) {
2790
+ while ((sm = gapRe.exec(styleText)) !== null) {
2248
2791
  spacingValues.push(parseInt(sm[1], 10));
2249
2792
  }
2250
2793
  const twSpaceRe = /\b(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-(\d+)\b/g;
2251
- while ((sm = twSpaceRe.exec(html)) !== null) {
2794
+ while ((sm = twSpaceRe.exec(classText)) !== null) {
2252
2795
  spacingValues.push(parseInt(sm[1], 10) * 4);
2253
2796
  }
2254
2797
  const remSpacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*([\d.]+)rem/gi;
2255
- while ((sm = remSpacingRe.exec(html)) !== null) {
2798
+ while ((sm = remSpacingRe.exec(styleText)) !== null) {
2256
2799
  const v = Math.round(parseFloat(sm[1]) * 16);
2257
2800
  if (v > 0 && v < 200) spacingValues.push(v);
2258
2801
  }
@@ -2276,21 +2819,21 @@ function checkHtmlPatterns(html) {
2276
2819
 
2277
2820
  // Bounce/elastic animation names
2278
2821
  const bounceRe = /animation(?:-name)?\s*:\s*([^;{}]*(?:bounce|elastic|wobble|jiggle|spring)[^;{}]*)/gi;
2279
- const bounceMatch = bounceRe.exec(html);
2822
+ const bounceMatch = bounceRe.exec(styleText);
2280
2823
  if (bounceMatch) {
2281
2824
  const animationToken = bounceMatch[1]
2282
2825
  .split(/[,\s]+/)
2283
2826
  .find((part) => /bounce|elastic|wobble|jiggle|spring/i.test(part));
2284
- findings.push({ id: 'bounce-easing', snippet: `animation: ${animationToken || bounceMatch[1].trim()}` });
2827
+ findings.push({ id: 'bounce-easing', snippet: `animation: ${animationToken || bounceMatch[1].trim()}`, selector: enclosingCssSelector(styleText, bounceMatch.index) || undefined });
2285
2828
  }
2286
2829
 
2287
2830
  // Overshoot cubic-bezier
2288
2831
  const bezierRe = /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g;
2289
2832
  let bm;
2290
- while ((bm = bezierRe.exec(html)) !== null) {
2833
+ while ((bm = bezierRe.exec(styleText)) !== null) {
2291
2834
  const y1 = parseFloat(bm[2]), y2 = parseFloat(bm[4]);
2292
2835
  if (y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1) {
2293
- findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${bm[1]}, ${bm[2]}, ${bm[3]}, ${bm[4]})` });
2836
+ findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${bm[1]}, ${bm[2]}, ${bm[3]}, ${bm[4]})`, selector: enclosingCssSelector(styleText, bm.index) || undefined });
2294
2837
  break;
2295
2838
  }
2296
2839
  }
@@ -2298,7 +2841,7 @@ function checkHtmlPatterns(html) {
2298
2841
  // Layout property transitions
2299
2842
  const transRe = /transition(?:-property)?\s*:\s*([^;{}]+)/gi;
2300
2843
  let tm;
2301
- while ((tm = transRe.exec(html)) !== null) {
2844
+ while ((tm = transRe.exec(styleText)) !== null) {
2302
2845
  const val = tm[1].toLowerCase();
2303
2846
  if (/\ball\b/.test(val)) continue;
2304
2847
  const found = val.match(/\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding(?:-(?:top|right|bottom|left))?\b|\bmargin(?:-(?:top|right|bottom|left))?\b/gi);
@@ -2308,31 +2851,36 @@ function checkHtmlPatterns(html) {
2308
2851
  }
2309
2852
  }
2310
2853
 
2311
- // Pulsing status dots (tiny circular elements on infinite pulse animations)
2312
- findings.push(...scanCssTextForPulsingDot(html));
2854
+ // Pulsing status dots (tiny circular elements on infinite pulse animations).
2855
+ // The CSS rules come from styleText; the markup carries the landmark
2856
+ // ranges and Tailwind class attributes.
2857
+ findings.push(...scanCssTextForPulsingDot(styleText, html));
2313
2858
 
2314
2859
  // Shape-assembled illustrations (large pictorial SVGs built from primitives)
2315
2860
  findings.push(...scanHtmlForShapeAssembledIllustration(html));
2316
2861
 
2317
2862
  // Auto-scrolling marquees (<marquee> or infinite horizontal loop animations)
2318
- findings.push(...scanCssTextForMarquee(html));
2863
+ findings.push(...scanCssTextForMarquee(styleText, html));
2319
2864
 
2320
2865
  // --- Dark glow / chromatic halo shadows ---
2321
2866
 
2322
- const glowHits = scanCssTextForGlow(html);
2867
+ const glowHits = scanCssTextForGlow(styleText);
2323
2868
  if (glowHits.length > 0) {
2324
- findings.push({ id: 'dark-glow', snippet: glowHits[0].snippet });
2869
+ findings.push({ id: 'dark-glow', snippet: glowHits[0].snippet, selector: enclosingCssSelector(styleText, glowHits[0].index) || undefined });
2325
2870
  }
2326
2871
 
2327
2872
  // Radial-gradient background halo (gradient-drawn sibling of dark-glow)
2328
- const haloHits = scanCssTextForRadialHalo(html);
2873
+ const haloHits = scanCssTextForRadialHalo(styleText);
2329
2874
  if (haloHits.length > 0) {
2330
- findings.push({ id: 'radial-halo', snippet: haloHits[0].snippet });
2875
+ findings.push({ id: 'radial-halo', snippet: haloHits[0].snippet, selector: enclosingCssSelector(styleText, haloHits[0].index) || undefined });
2331
2876
  }
2332
2877
 
2333
2878
  // --- Generated-UI tells: repeating-gradient stripes ---
2334
- if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(html)) {
2335
- findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
2879
+ {
2880
+ const stripesMatch = /repeating-(?:linear|radial|conic)-gradient\s*\(/i.exec(styleText);
2881
+ if (stripesMatch) {
2882
+ findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes', selector: enclosingCssSelector(styleText, stripesMatch.index) || undefined });
2883
+ }
2336
2884
  }
2337
2885
 
2338
2886
  // --- Generated-UI tells: two-axis grid-line background ---
@@ -2348,9 +2896,9 @@ function checkHtmlPatterns(html) {
2348
2896
  // in for the second axis. Colors like `oklch(96% 0.012 82 / 0.055)` carry
2349
2897
  // nested parens, so match the hairline stop directly rather than parsing
2350
2898
  // whole gradient layers.
2351
- const gridHits = scanCssTextForGridBackground(html);
2899
+ const gridHits = scanCssTextForGridBackground(styleText);
2352
2900
  if (gridHits.length > 0) {
2353
- findings.push({ id: 'codex-grid-background', snippet: gridHits[0].snippet });
2901
+ findings.push({ id: 'codex-grid-background', snippet: gridHits[0].snippet, selector: enclosingCssSelector(styleText, gridHits[0].index) || undefined });
2354
2902
  }
2355
2903
 
2356
2904
  // --- Generated-copy tells: "X theater" framing copy ---
@@ -2370,8 +2918,11 @@ function checkHtmlPatterns(html) {
2370
2918
  // hover:rotate / hover:translate utility on an <img>. Each distinct
2371
2919
  // mechanism is its own finding.
2372
2920
  const imgHoverCss = /\bimg\b[^,{}]*:hover\b[^{}]*\{[^}]*\btransform\s*:\s*(?:scale|rotate|translate|matrix|skew)/i;
2373
- if (imgHoverCss.test(html)) {
2374
- findings.push({ id: 'image-hover-transform', snippet: 'img:hover { transform } rule' });
2921
+ {
2922
+ const imgHoverMatch = imgHoverCss.exec(styleText);
2923
+ if (imgHoverMatch) {
2924
+ findings.push({ id: 'image-hover-transform', snippet: 'img:hover { transform } rule', selector: enclosingCssSelector(styleText, imgHoverMatch.index + imgHoverMatch[0].indexOf('{') + 1) || undefined });
2925
+ }
2375
2926
  }
2376
2927
  const imgTagRe = /<img\b[^>]*\bclass\s*=\s*"([^"]*)"/gi;
2377
2928
  let im;
@@ -2418,7 +2969,46 @@ function readOwnBackgroundColor(el, computedStyle) {
2418
2969
  return bg;
2419
2970
  }
2420
2971
 
2421
- function resolveBackground(el, win, customPropMap) {
2972
+ // One element's background-color as the cascade walk sees it: computed style
2973
+ // first (with the modern-color fallback), then, in static mode only,
2974
+ // custom-prop resolution and the inline-shorthand peek. Shared by
2975
+ // resolveBackgroundInfo and resolveGradientStops so both walks read the same
2976
+ // surfaces.
2977
+ function readCascadeBackgroundColor(current, style, customPropMap) {
2978
+ let bg = parseRgb(style.backgroundColor) || parseAnyColor(style.backgroundColor);
2979
+ if (!DETECTOR_IS_BROWSER && (!bg || bg.a < 0.1)) {
2980
+ // The static engine can return literal "var(--X)" / "oklch(...)" strings.
2981
+ // Resolve through customPropMap so Tailwind v4 color tokens become RGB.
2982
+ if (customPropMap) {
2983
+ bg = parseColorResolved(style.backgroundColor, customPropMap);
2984
+ }
2985
+ if (!bg || bg.a < 0.1) {
2986
+ // Inline-style fallback for colors the static cascade did not surface
2987
+ // on backgroundColor.
2988
+ const rawStyle = current.getAttribute?.('style') || '';
2989
+ const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
2990
+ const inlineBg = bgMatch ? bgMatch[1].trim() : '';
2991
+ if (inlineBg && !/gradient/i.test(inlineBg) && !/url\s*\(/i.test(inlineBg)) {
2992
+ bg = parseColorResolved(inlineBg, customPropMap) || parseAnyColor(inlineBg);
2993
+ }
2994
+ }
2995
+ }
2996
+ return bg;
2997
+ }
2998
+
2999
+ // Walk up for the surface the element's text is painted on.
3000
+ //
3001
+ // Returns { color, unresolved }:
3002
+ // • color set — the effective surface, overlays composited in.
3003
+ // • unresolved: true — a layer on the way up paints a color this parser
3004
+ // cannot read, so the surface is unknown. Callers
3005
+ // must SKIP their contrast checks. Guessing white
3006
+ // here is what flooded dark themes with false
3007
+ // "on #ffffff" findings: one abstention costs a
3008
+ // single finding, one wrong guess costs a hundred.
3009
+ // • both null/false — no solid color, but a gradient or image is in
3010
+ // play; callers fall back to its color stops.
3011
+ function resolveBackgroundInfo(el, win, customPropMap) {
2422
3012
  let current = el;
2423
3013
  // Translucent layers (0.1 < a < 1) found on the way down to an opaque
2424
3014
  // base. A browser composites these over the base; the old behavior
@@ -2446,67 +3036,114 @@ function resolveBackground(el, win, customPropMap) {
2446
3036
  // body backgrounds.
2447
3037
  // Real browsers serialize wide-gamut computed values as oklab()/oklch()
2448
3038
  // (e.g. any color-mix() result), which plain parseRgb misses.
2449
- let bg = parseRgb(style.backgroundColor) || parseAnyColor(style.backgroundColor);
2450
- if (!DETECTOR_IS_BROWSER && (!bg || bg.a < 0.1)) {
2451
- // jsdom returns literal "var(--X)" / "oklch(...)" strings. Resolve
2452
- // through customPropMap so Tailwind v4 color tokens become RGB.
2453
- if (customPropMap) {
2454
- bg = parseColorResolved(style.backgroundColor, customPropMap);
2455
- }
2456
- if (!bg || bg.a < 0.1) {
2457
- // Inline-style fallback. jsdom doesn't decompose background
2458
- // shorthand, so colors set via inline style are otherwise invisible.
2459
- const rawStyle = current.getAttribute?.('style') || '';
2460
- const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
2461
- const inlineBg = bgMatch ? bgMatch[1].trim() : '';
2462
- if (inlineBg && !/gradient/i.test(inlineBg) && !/url\s*\(/i.test(inlineBg)) {
2463
- bg = parseColorResolved(inlineBg, customPropMap) || parseAnyColor(inlineBg);
2464
- }
2465
- }
3039
+ let bg = readCascadeBackgroundColor(current, style, customPropMap);
3040
+
3041
+ // `background-color: currentcolor` paints with the element's own text
3042
+ // color — real paint whose value we know. Real browsers resolve the
3043
+ // keyword before getComputedStyle output; jsdom hands it through
3044
+ // verbatim, and without this substitution the layer would read as
3045
+ // unparseable and force a needless abstention.
3046
+ if ((!bg || bg.a < 0.1) && /^currentcolor$/i.test(String(style.backgroundColor || '').trim())) {
3047
+ // The static cascade resolves var() text tokens before checks run, so
3048
+ // style.color is normally already an rgb string here; parseColorResolved
3049
+ // is defense in depth for any future caller that passes a live
3050
+ // customPropMap (it matches the text-color path in checkElementColors
3051
+ // and reduces to parseAnyColor when the map is null or absent).
3052
+ bg = parseRgb(style.color) || parseColorResolved(style.color, customPropMap);
2466
3053
  }
2467
3054
 
2468
3055
  if (bg && bg.a > 0.1) {
2469
- if (bg.a >= 0.99) return flatten(bg);
3056
+ if (bg.a >= 0.99) return { color: flatten(bg), unresolved: false };
2470
3057
  overlays.push(bg);
2471
- }
2472
- // No solid bg-color at this level. If THIS level has a gradient/url
2473
- // with no underlying solid color we can read:
2474
- // • on body/html: assume white. Body-level gradients are almost
2475
- // always decorative texture (paper grain, noise) on top of a
2476
- // solid bg-color the page set via `background: var(--paper)`
2477
- // shorthand — which jsdom can't decompose into bg-color. The
2478
- // downstream gradient-stops fallback path produces catastrophic
2479
- // false positives in this case (gradient noise stops have
2480
- // accidental browns/blacks that look like card backgrounds).
2481
- // • on other elements: bail to null and let the caller fall back
2482
- // to gradient stops (gradient buttons / hero sections are real
2483
- // bgs worth checking against).
3058
+ } else if (!bg && !isNoPaintColorValue(style.backgroundColor)) {
3059
+ // This layer names a color we could not parse (a color space we do not
3060
+ // model, an unresolved var(), a syntax newer than the parser). It may
3061
+ // well be opaque, which would make every ancestor below it invisible —
3062
+ // so the surface is unknown and the walk stops here rather than
3063
+ // reporting an ancestor the visitor never sees.
3064
+ return { color: null, unresolved: true };
3065
+ }
3066
+ // No solid bg-color at this level, but this level paints an image. CSS
3067
+ // stacks background-image layers first-on-top, so which layer leads
3068
+ // decides what the visitor sees:
3069
+ // • gradient on top — the gradient is the surface. Hand the caller a
3070
+ // null color so it falls back to the gradient's own stops (body
3071
+ // grounds, gradient buttons, hero sections).
3072
+ // • url() on top — the surface is an image whose pixels this engine
3073
+ // cannot read, and it may fully cover every layer and ancestor
3074
+ // beneath it. Same contract as an unparseable color: abstain, so
3075
+ // the gradient-stop fallback never measures a gradient the image
3076
+ // hides (the shipped miss: `url(photo), linear-gradient(...)`
3077
+ // reported low-contrast against the invisible gradient's stops).
2484
3078
  if (hasGradientOrUrl) {
2485
- if (current.tagName === 'BODY' || current.tagName === 'HTML') {
2486
- return flatten({ r: 255, g: 255, b: 255, a: 1 });
3079
+ const layers = splitTopLevelCommas(bgImage);
3080
+ const topPaintLayer = layers.find(
3081
+ (layer) => /gradient\s*\(/i.test(layer) || /url\s*\(/i.test(layer),
3082
+ );
3083
+ const gradientOnTop = !!topPaintLayer
3084
+ && /gradient\s*\(/i.test(topPaintLayer)
3085
+ && !/^\s*url\s*\(/i.test(topPaintLayer);
3086
+ if (!gradientOnTop) return { color: null, unresolved: true };
3087
+ // Gradient on top of a url() layer: the image shows through wherever
3088
+ // the gradient is not fully opaque, so a translucent wash like
3089
+ // `linear-gradient(rgba(0,0,0,.2), rgba(0,0,0,.2)), url(photo)` paints
3090
+ // a blend with pixels this engine cannot read. Only a gradient whose
3091
+ // every readable stop is opaque provably covers the image; otherwise
3092
+ // the surface is unknown — abstain rather than hand callers gradient
3093
+ // stops (or a stop average) the visitor never sees unmixed.
3094
+ const urlBeneath = layers.some(
3095
+ (layer) => layer !== topPaintLayer && /url\s*\(/i.test(layer),
3096
+ );
3097
+ if (urlBeneath) {
3098
+ const topStops = parseGradientColors(topPaintLayer);
3099
+ const provablyOpaque = topStops.length > 0 && topStops.every((s) => (s.a ?? 1) >= 0.99);
3100
+ if (!provablyOpaque) return { color: null, unresolved: true };
2487
3101
  }
2488
- return null;
3102
+ return { color: null, unresolved: false };
2489
3103
  }
2490
3104
  current = current.parentElement;
2491
3105
  }
2492
- return flatten({ r: 255, g: 255, b: 255, a: 1 });
3106
+ // Every layer up to the document root was genuinely see-through, so the
3107
+ // browser paints its default canvas. This is the ONLY case that earns the
3108
+ // white assumption.
3109
+ return { color: flatten({ r: 255, g: 255, b: 255, a: 1 }), unresolved: false };
3110
+ }
3111
+
3112
+ function resolveBackground(el, win, customPropMap) {
3113
+ return resolveBackgroundInfo(el, win, customPropMap).color;
2493
3114
  }
2494
3115
 
2495
3116
  // Walk parents looking for a gradient background and return its color stops.
2496
3117
  // Used as a fallback when resolveBackground() returns null because the
2497
3118
  // effective background is a gradient (no single solid color to compare against).
3119
+ // Translucent solid layers found between the element and the gradient (frosted
3120
+ // panels, glass washes) are composited over every stop, the same way
3121
+ // resolveBackground flattens them over a solid base — raw stops alone would
3122
+ // false-flag dark text on a light frosted wash over a dark gradient, and miss
3123
+ // the inverse.
2498
3124
  function resolveGradientStops(el, win, customPropMap) {
2499
3125
  let current = el;
3126
+ const overlays = [];
2500
3127
  while (current && current.nodeType === 1) {
2501
3128
  const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
2502
3129
  const bgImage = style.backgroundImage || '';
3130
+ // A url() layer anywhere in the stack — alone, or alongside a gradient in
3131
+ // the same declaration (a translucent wash over a texture photo) — paints
3132
+ // pixels the analytic walk cannot know. Measuring the gradient stops over
3133
+ // the wrong base flagged dark ink sitting on a bright gold-leaf image at
3134
+ // 2.6:1; skipping beats a wrong ratio, and the screenshot subsystem owns
3135
+ // image-backed text.
3136
+ if (bgImage && bgImage !== 'none' && /url\s*\(/i.test(bgImage)) return null;
2503
3137
  let stops = null;
2504
3138
  if (bgImage && bgImage !== 'none' && /gradient/i.test(bgImage)) {
3139
+ // parseGradientColors (shared) reads modern-space stops too — oklch,
3140
+ // color-mix and friends via balanced-paren token capture — so browser
3141
+ // computed values that keep the authored syntax stay measurable.
2505
3142
  const parsed = parseGradientColors(bgImage);
2506
3143
  if (parsed.length > 0) stops = parsed;
2507
3144
  }
2508
3145
  if (!stops && !DETECTOR_IS_BROWSER) {
2509
- // jsdom doesn't decompose `background:` shorthand — peek at the raw inline style
3146
+ // Static mode: peek at the raw inline style for gradients the cascade did not surface
2510
3147
  const rawStyle = current.getAttribute?.('style') || '';
2511
3148
  const bgMatch = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
2512
3149
  if (bgMatch && /gradient/i.test(bgMatch[1])) {
@@ -2514,7 +3151,23 @@ function resolveGradientStops(el, win, customPropMap) {
2514
3151
  if (parsed.length > 0) stops = parsed;
2515
3152
  }
2516
3153
  }
2517
- if (stops) return compositeGradientStops(stops, current, win, customPropMap);
3154
+ if (stops) {
3155
+ const composited = compositeGradientStops(stops, current, win, customPropMap);
3156
+ if (!composited || overlays.length === 0) return composited;
3157
+ return composited.map(stop => {
3158
+ let acc = stop;
3159
+ for (let i = overlays.length - 1; i >= 0; i--) acc = compositeColorOver(overlays[i], acc);
3160
+ return acc;
3161
+ });
3162
+ }
3163
+ const bg = readCascadeBackgroundColor(current, style, customPropMap);
3164
+ if (bg && bg.a > 0.1) {
3165
+ // An opaque surface above the gradient means the gradient never shows
3166
+ // through here; resolveBackground would have returned it, so reaching
3167
+ // this is defensive — bail rather than measure the wrong layer.
3168
+ if (bg.a >= 0.99) return null;
3169
+ overlays.push(bg);
3170
+ }
2518
3171
  current = current.parentElement;
2519
3172
  }
2520
3173
  return null;
@@ -2698,491 +3351,224 @@ function checkElementPseudoStripeDOM(el) {
2698
3351
 
2699
3352
  findings.push({
2700
3353
  id: 'side-tab',
2701
- snippet: `${classSelector(el)}${which} — absolute ${thickness}px pseudo-element stripe (${edge})`,
2702
- });
2703
- }
2704
- return findings;
2705
- }
2706
-
2707
- // Full-cover surface pseudo (browser): a ::before/::after positioned
2708
- // absolute/fixed whose box covers (nearly) the whole host and carries an
2709
- // opaque background. That pseudo is the element's visible surface even
2710
- // though the element's own background-color reads transparent — the nav-CTA
2711
- // construction that otherwise escapes every own-background contrast gate.
2712
- function readPseudoSurfaceDOM(el, rect) {
2713
- for (const which of ['::before', '::after']) {
2714
- let ps;
2715
- try { ps = getComputedStyle(el, which); } catch { continue; }
2716
- if (!ps || ps.content === 'none' || ps.content === '') continue;
2717
- if (ps.position !== 'absolute' && ps.position !== 'fixed') continue;
2718
- if (ps.display === 'none' || (parseFloat(ps.opacity) || 1) < 0.9) continue;
2719
- const w = parseFloat(ps.width) || 0;
2720
- const h = parseFloat(ps.height) || 0;
2721
- if (w < rect.width - 4 || h < rect.height - 4) continue;
2722
- const bg = parseRgb(ps.backgroundColor) || parseAnyColor(ps.backgroundColor);
2723
- if (!bg || (bg.a ?? 1) < 0.9) continue;
2724
- return bg;
2725
- }
2726
- return null;
2727
- }
2728
-
2729
- function checkElementColorsDOM(el) {
2730
- const tag = el.tagName.toLowerCase();
2731
- // No early SAFE_TAGS bail here — checkColors() does its own gating that
2732
- // includes the styled-button exception for <a> / <button> with their own
2733
- // opaque background. Bailing here would prevent that exception from firing.
2734
- const rect = el.getBoundingClientRect();
2735
- if (rect.width < 10 || rect.height < 10) return [];
2736
- const style = getComputedStyle(el);
2737
- const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
2738
- const hasDirectText = directText.trim().length > 0;
2739
- let effectiveBg = resolveBackground(el);
2740
- let ownBg = readOwnBackgroundColor(el, style);
2741
- if (!ownBg || (ownBg.a ?? 1) <= 0.5) {
2742
- const pseudoSurface = readPseudoSurfaceDOM(el, rect);
2743
- if (pseudoSurface) {
2744
- ownBg = pseudoSurface;
2745
- effectiveBg = pseudoSurface;
2746
- }
2747
- }
2748
- return checkColors({
2749
- tag,
2750
- // Chrome serializes computed colors specified in modern spaces as
2751
- // oklch()/oklab() strings; without the parseAnyColor fallback the text
2752
- // color comes back null and the low-contrast / gray-on-color checks
2753
- // silently never run (the shipped miss: a nav CTA whose text color was
2754
- // an oklch token near its own oklch background).
2755
- textColor: parseRgb(style.color) || parseAnyColor(style.color),
2756
- bgColor: ownBg,
2757
- effectiveBg,
2758
- effectiveBgStops: effectiveBg ? null : resolveGradientStops(el),
2759
- fontSize: parseFloat(style.fontSize) || 16,
2760
- fontWeight: parseInt(style.fontWeight) || 400,
2761
- hasDirectText,
2762
- isEmojiOnly: isEmojiOnlyText(directText),
2763
- bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
2764
- bgImage: style.backgroundImage || '',
2765
- classList: el.getAttribute('class') || '',
2766
- });
2767
- }
2768
-
2769
- function checkElementIconTileDOM(el) {
2770
- const tag = el.tagName.toLowerCase();
2771
- if (!HEADING_TAGS.has(tag)) return [];
2772
- const sibling = el.previousElementSibling;
2773
- if (!sibling) return [];
2774
-
2775
- const sibRect = sibling.getBoundingClientRect();
2776
- const headRect = el.getBoundingClientRect();
2777
- const sibStyle = getComputedStyle(sibling);
2778
-
2779
- // The tile may either contain an <svg>/<i> icon child, OR the tile itself
2780
- // may contain an emoji/symbol character directly as its only text content
2781
- // (the "card-icon" pattern from many AI-generated demos).
2782
- const iconChild = sibling.querySelector('svg, i[data-lucide], i[class*="fa-"], i[class*="icon"]');
2783
- const iconRect = iconChild?.getBoundingClientRect();
2784
- const sibDirectText = [...sibling.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
2785
- const hasInlineEmojiIcon = sibling.children.length === 0 && isEmojiOnlyText(sibDirectText);
2786
-
2787
- return checkIconTile({
2788
- headingTag: tag,
2789
- headingText: el.textContent || '',
2790
- headingTop: headRect.top,
2791
- siblingTag: sibling.tagName.toLowerCase(),
2792
- siblingWidth: sibRect.width,
2793
- siblingHeight: sibRect.height,
2794
- siblingBottom: sibRect.bottom,
2795
- siblingBgColor: parseRgb(sibStyle.backgroundColor),
2796
- siblingBgImage: sibStyle.backgroundImage || '',
2797
- siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
2798
- siblingBorderRadius: parseFloat(sibStyle.borderRadius) || 0,
2799
- hasIconChild: !!iconChild || hasInlineEmojiIcon,
2800
- iconChildWidth: iconRect?.width || 0,
2801
- });
2802
- }
2803
-
2804
- function checkElementItalicSerifDOM(el) {
2805
- const tag = el.tagName.toLowerCase();
2806
- if (tag !== 'h1' && tag !== 'h2') return [];
2807
- const style = getComputedStyle(el);
2808
- return checkItalicSerif({
2809
- tag,
2810
- fontStyle: style.fontStyle || '',
2811
- fontFamily: style.fontFamily || '',
2812
- fontSize: parseFloat(style.fontSize) || 0,
2813
- headingText: el.textContent || '',
2814
- });
3354
+ snippet: `${classSelector(el)}${which} — absolute ${thickness}px pseudo-element stripe (${edge})`,
3355
+ });
3356
+ }
3357
+ return findings;
2815
3358
  }
2816
3359
 
2817
- function domAccentDashPseudo(el) {
3360
+ // Full-cover surface pseudo (browser): a ::before/::after positioned
3361
+ // absolute/fixed whose box covers (nearly) the whole host and carries an
3362
+ // opaque background. That pseudo is the element's visible surface even
3363
+ // though the element's own background-color reads transparent — the nav-CTA
3364
+ // construction that otherwise escapes every own-background contrast gate.
3365
+ function readPseudoSurfaceDOM(el, rect) {
2818
3366
  for (const which of ['::before', '::after']) {
2819
3367
  let ps;
2820
3368
  try { ps = getComputedStyle(el, which); } catch { continue; }
2821
3369
  if (!ps || ps.content === 'none' || ps.content === '') continue;
3370
+ if (ps.position !== 'absolute' && ps.position !== 'fixed') continue;
3371
+ if (ps.display === 'none' || (parseFloat(ps.opacity) || 1) < 0.9) continue;
2822
3372
  const w = parseFloat(ps.width) || 0;
2823
3373
  const h = parseFloat(ps.height) || 0;
2824
- if (!(w >= 8 && w <= 80 && h >= 1 && h <= 6)) continue;
3374
+ if (w < rect.width - 4 || h < rect.height - 4) continue;
2825
3375
  const bg = parseRgb(ps.backgroundColor) || parseAnyColor(ps.backgroundColor);
2826
- if (!bg || (bg.a ?? 1) < 0.1) continue;
2827
- if (Math.max(bg.r, bg.g, bg.b) - Math.min(bg.r, bg.g, bg.b) >= 30) return true;
3376
+ if (!bg || (bg.a ?? 1) < 0.9) continue;
3377
+ return bg;
2828
3378
  }
2829
- return false;
3379
+ return null;
2830
3380
  }
2831
3381
 
2832
- function checkElementHeroEyebrowDOM(el) {
3382
+ function checkElementColorsDOM(el) {
2833
3383
  const tag = el.tagName.toLowerCase();
2834
- if (tag !== 'h1') return [];
2835
- const sibling = el.previousElementSibling;
2836
- if (!sibling) return [];
2837
- const headStyle = getComputedStyle(el);
2838
- const sibStyle = getComputedStyle(sibling);
2839
- return checkHeroEyebrow({
2840
- headingTag: tag,
2841
- headingText: el.textContent || '',
2842
- headingFontSize: parseFloat(headStyle.fontSize) || 0,
2843
- headingInApplicationContext: !!el.closest('[role="tabpanel"], [role="dialog"], [role="application"], dialog'),
2844
- siblingTag: sibling.tagName.toLowerCase(),
2845
- siblingText: sibling.textContent || '',
2846
- siblingTextTransform: sibStyle.textTransform || '',
2847
- siblingFontSize: parseFloat(sibStyle.fontSize) || 0,
2848
- siblingLetterSpacing: parseFloat(sibStyle.letterSpacing) || 0,
2849
- siblingFontWeight: sibStyle.fontWeight || '',
2850
- siblingColor: sibStyle.color || '',
2851
- siblingHasAccentDashPseudo: domAccentDashPseudo(sibling),
2852
- });
2853
- }
2854
-
2855
- // Build a map of CSS custom properties declared on :root / :host / html.
2856
- // Used to resolve var(--X) refs that jsdom returns verbatim in
2857
- // getComputedStyle. Tailwind v4 routes every utility class through
2858
- // CSS vars (font-weight: var(--font-weight-bold), font-size:
2859
- // var(--text-xs), letter-spacing: var(--tracking-widest)), so without
2860
- // resolution every style-based check silently fails on Tailwind v4
2861
- // builds — the values come back as literal "var(--font-weight-bold)"
2862
- // strings and parseFloat returns NaN.
2863
- function buildCustomPropMap(document) {
2864
- const map = new Map();
2865
- let sheets;
2866
- try { sheets = Array.from(document.styleSheets || []); }
2867
- catch { return map; }
2868
- for (const sheet of sheets) {
2869
- let rules;
2870
- try { rules = Array.from(sheet.cssRules || []); }
2871
- catch { continue; }
2872
- for (const rule of rules) {
2873
- // Style rules only (type 1). Walk @media / @supports if present.
2874
- if (rule.type === 4 /* MEDIA_RULE */ || rule.type === 12 /* SUPPORTS_RULE */) {
2875
- try { rules.push(...Array.from(rule.cssRules || [])); } catch { /* ignore */ }
2876
- continue;
2877
- }
2878
- if (rule.type !== 1 /* STYLE_RULE */) continue;
2879
- const sel = rule.selectorText || '';
2880
- if (!/(^|,\s*)(:root|html|:host)\b/i.test(sel)) continue;
2881
- const style = rule.style;
2882
- if (!style) continue;
2883
- for (let i = 0; i < style.length; i++) {
2884
- const prop = style[i];
2885
- if (!prop || !prop.startsWith('--')) continue;
2886
- const val = style.getPropertyValue(prop).trim();
2887
- if (val) map.set(prop, val);
2888
- }
3384
+ // No early SAFE_TAGS bail here — checkColors() does its own gating that
3385
+ // includes the styled-button exception for <a> / <button> with their own
3386
+ // opaque background. Bailing here would prevent that exception from firing.
3387
+ const rect = el.getBoundingClientRect();
3388
+ if (rect.width < 10 || rect.height < 10) return [];
3389
+ const style = getComputedStyle(el);
3390
+ // Invisible at rest: hidden scene variants (opacity-0 carousels, swap
3391
+ // decks) are not user-visible, and measuring their inherited colors against
3392
+ // whatever surface happens to sit behind the stack is noise, not audit.
3393
+ if (style.visibility === 'hidden' || effectiveOpacityDOM(el) <= 0.02) return [];
3394
+ const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
3395
+ const hasDirectText = directText.trim().length > 0;
3396
+ const bgInfo = resolveBackgroundInfo(el);
3397
+ let effectiveBg = bgInfo.color;
3398
+ // An unreadable surface anywhere up the chain: skip the gradient-stop
3399
+ // fallback too, so nothing downstream measures against a ground we never
3400
+ // resolved.
3401
+ let surfaceUnresolved = bgInfo.unresolved;
3402
+ let ownBg = readOwnBackgroundColor(el, style);
3403
+ if (!ownBg || (ownBg.a ?? 1) <= 0.5) {
3404
+ const pseudoSurface = readPseudoSurfaceDOM(el, rect);
3405
+ if (pseudoSurface) {
3406
+ ownBg = pseudoSurface;
3407
+ effectiveBg = pseudoSurface;
3408
+ surfaceUnresolved = false;
2889
3409
  }
2890
3410
  }
2891
- return map;
2892
- }
2893
-
2894
- // Resolve var(--X[, fallback]) refs in a computed-style value string.
2895
- // Recurses up to 8 levels for chained refs (--a: var(--b)). Returns
2896
- // the original string when no refs are present or the chain doesn't
2897
- // resolve. Safe to call on already-resolved values.
2898
- function resolveVarRefs(raw, customPropMap, depth = 0) {
2899
- if (typeof raw !== 'string' || !raw.includes('var(')) return raw;
2900
- if (depth > 8) return raw;
2901
- return raw.replace(/var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,\s*([^)]+))?\)/g, (_m, name, fallback) => {
2902
- const v = customPropMap.get(name);
2903
- if (v != null) return resolveVarRefs(v, customPropMap, depth + 1);
2904
- return fallback ? resolveVarRefs(fallback.trim(), customPropMap, depth + 1) : _m;
3411
+ return checkColors({
3412
+ tag,
3413
+ // Chrome serializes computed colors specified in modern spaces as
3414
+ // oklch()/oklab() strings; without the parseAnyColor fallback the text
3415
+ // color comes back null and the low-contrast / gray-on-color checks
3416
+ // silently never run (the shipped miss: a nav CTA whose text color was
3417
+ // an oklch token near its own oklch background).
3418
+ textColor: parseRgb(style.color) || parseAnyColor(style.color),
3419
+ bgColor: ownBg,
3420
+ effectiveBg: surfaceUnresolved ? null : effectiveBg,
3421
+ effectiveBgStops: surfaceUnresolved || effectiveBg ? null : resolveGradientStops(el),
3422
+ fontSize: parseFloat(style.fontSize) || 16,
3423
+ fontWeight: parseInt(style.fontWeight) || 400,
3424
+ hasDirectText,
3425
+ isEmojiOnly: isEmojiOnlyText(directText),
3426
+ bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
3427
+ bgImage: style.backgroundImage || '',
3428
+ classList: el.getAttribute('class') || '',
2905
3429
  });
2906
3430
  }
2907
3431
 
2908
- // OKLCH → sRGB conversion (Björn Ottosson's matrices). L in 0..1 (or %),
2909
- // C in 0..~0.4 typical, H in degrees. Returns clamped {r,g,b,a:1} in 0..255.
2910
- // Needed because jsdom doesn't compute oklch() values — getComputedStyle
2911
- // returns the literal "oklch(...)" string. Without this, the entire
2912
- // Tailwind v4 color palette (which is OKLCH-based) is invisible to the
2913
- // detector's contrast / color checks.
2914
- function oklchToRgb(L, C, H) {
2915
- const hRad = (H * Math.PI) / 180;
2916
- return oklabToRgb(L, C * Math.cos(hRad), C * Math.sin(hRad));
2917
- }
2918
-
2919
- function oklabToRgb(L, a, b) {
2920
- const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
2921
- const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
2922
- const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
2923
- const lc = l_ * l_ * l_, mc = m_ * m_ * m_, sc = s_ * s_ * s_;
2924
- const rLin = 4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc;
2925
- const gLin = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc;
2926
- const bLin = -0.0041960863 * lc - 0.7034186147 * mc + 1.7076147010 * sc;
2927
- const enc = (x) => {
2928
- const c = Math.max(0, Math.min(1, x));
2929
- return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
2930
- };
2931
- return {
2932
- r: Math.round(enc(rLin) * 255),
2933
- g: Math.round(enc(gLin) * 255),
2934
- b: Math.round(enc(bLin) * 255),
2935
- a: 1,
2936
- };
2937
- }
2938
-
2939
- function hslToRgb(h, s, l) {
2940
- h = ((h % 360) + 360) % 360;
2941
- const c = (1 - Math.abs(2 * l - 1)) * s;
2942
- const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
2943
- const m0 = l - c / 2;
2944
- const [r, g, b] =
2945
- h < 60 ? [c, x, 0] :
2946
- h < 120 ? [x, c, 0] :
2947
- h < 180 ? [0, c, x] :
2948
- h < 240 ? [0, x, c] :
2949
- h < 300 ? [x, 0, c] : [c, 0, x];
2950
- return {
2951
- r: Math.round((r + m0) * 255),
2952
- g: Math.round((g + m0) * 255),
2953
- b: Math.round((b + m0) * 255),
2954
- a: 1,
2955
- };
2956
- }
2957
-
2958
- function hwbToRgb(h, w, bl) {
2959
- if (w + bl >= 1) {
2960
- const g = Math.round((w / (w + bl)) * 255);
2961
- return { r: g, g, b: g, a: 1 };
2962
- }
2963
- const base = hslToRgb(h, 1, 0.5);
2964
- const mix = (c) => Math.round(((c / 255) * (1 - w - bl) + w) * 255);
2965
- return { r: mix(base.r), g: mix(base.g), b: mix(base.b), a: 1 };
2966
- }
2967
-
2968
- // Common CSS named colors — the handful that actually show up in generated
2969
- // UIs, not the full 148-name spec list. Includes the achromatic names so a
2970
- // named gray parses (and correctly reads as no-chroma) instead of being
2971
- // treated as an unknown color.
2972
- const CSS_NAMED_COLORS = {
2973
- black: { r: 0, g: 0, b: 0 },
2974
- white: { r: 255, g: 255, b: 255 },
2975
- gray: { r: 128, g: 128, b: 128 },
2976
- grey: { r: 128, g: 128, b: 128 },
2977
- silver: { r: 192, g: 192, b: 192 },
2978
- dimgray: { r: 105, g: 105, b: 105 },
2979
- darkgray: { r: 169, g: 169, b: 169 },
2980
- lightgray: { r: 211, g: 211, b: 211 },
2981
- gainsboro: { r: 220, g: 220, b: 220 },
2982
- whitesmoke: { r: 245, g: 245, b: 245 },
2983
- red: { r: 255, g: 0, b: 0 },
2984
- crimson: { r: 220, g: 20, b: 60 },
2985
- tomato: { r: 255, g: 99, b: 71 },
2986
- coral: { r: 255, g: 127, b: 80 },
2987
- salmon: { r: 250, g: 128, b: 114 },
2988
- orange: { r: 255, g: 165, b: 0 },
2989
- gold: { r: 255, g: 215, b: 0 },
2990
- yellow: { r: 255, g: 255, b: 0 },
2991
- olive: { r: 128, g: 128, b: 0 },
2992
- lime: { r: 0, g: 255, b: 0 },
2993
- green: { r: 0, g: 128, b: 0 },
2994
- teal: { r: 0, g: 128, b: 128 },
2995
- turquoise: { r: 64, g: 224, b: 208 },
2996
- cyan: { r: 0, g: 255, b: 255 },
2997
- aqua: { r: 0, g: 255, b: 255 },
2998
- skyblue: { r: 135, g: 206, b: 235 },
2999
- dodgerblue: { r: 30, g: 144, b: 255 },
3000
- blue: { r: 0, g: 0, b: 255 },
3001
- navy: { r: 0, g: 0, b: 128 },
3002
- indigo: { r: 75, g: 0, b: 130 },
3003
- rebeccapurple: { r: 102, g: 51, b: 153 },
3004
- purple: { r: 128, g: 0, b: 128 },
3005
- violet: { r: 238, g: 130, b: 238 },
3006
- orchid: { r: 218, g: 112, b: 214 },
3007
- magenta: { r: 255, g: 0, b: 255 },
3008
- fuchsia: { r: 255, g: 0, b: 255 },
3009
- hotpink: { r: 255, g: 105, b: 180 },
3010
- pink: { r: 255, g: 192, b: 203 },
3011
- maroon: { r: 128, g: 0, b: 0 },
3012
- };
3013
-
3014
- // Split a string on top-level commas (ignoring commas nested in parens).
3015
- function splitTopLevelCommas(str) {
3016
- const parts = [];
3017
- let depth = 0, start = 0;
3018
- for (let i = 0; i < str.length; i++) {
3019
- const ch = str[i];
3020
- if (ch === '(') depth++;
3021
- else if (ch === ')') depth = Math.max(0, depth - 1);
3022
- else if (ch === ',' && depth === 0) {
3023
- parts.push(str.slice(start, i).trim());
3024
- start = i + 1;
3025
- }
3026
- }
3027
- const tail = str.slice(start).trim();
3028
- if (tail) parts.push(tail);
3029
- return parts;
3030
- }
3031
-
3032
- // Evaluate a CSS color-mix() expression to {r,g,b,a}. Returns null when
3033
- // the expression can't be resolved (unresolved var(), unknown colors).
3034
- //
3035
- // Mixing is done with premultiplied alpha in sRGB regardless of the
3036
- // declared interpolation space. That is exact for the dominant generated-UI
3037
- // pattern — `color-mix(in oklab, <color> N%, transparent)` — where the
3038
- // result is simply <color> at alpha N% in ANY rectangular space, and a
3039
- // close-enough approximation for opaque-opaque mixes (the detector only
3040
- // consumes these values for contrast/chroma thresholds, not for display).
3041
- function parseColorMix(str) {
3042
- const m = String(str).trim().match(/^color-mix\(/i);
3043
- if (!m) return null;
3044
- // Balanced-paren capture of the arguments.
3045
- let depth = 0, end = -1;
3046
- const open = str.indexOf('(');
3047
- for (let i = open; i < str.length; i++) {
3048
- if (str[i] === '(') depth++;
3049
- else if (str[i] === ')') { depth--; if (depth === 0) { end = i; break; } }
3050
- }
3051
- if (end < 0) return null;
3052
- const args = splitTopLevelCommas(str.slice(open + 1, end));
3053
- if (args.length !== 3 || !/^in\s/i.test(args[0])) return null;
3432
+ function checkElementIconTileDOM(el) {
3433
+ const tag = el.tagName.toLowerCase();
3434
+ if (!HEADING_TAGS.has(tag)) return [];
3435
+ const sibling = el.previousElementSibling;
3436
+ if (!sibling) return [];
3054
3437
 
3055
- const parseComponent = (component) => {
3056
- // Percentage may lead or trail the color per spec.
3057
- let pct = null;
3058
- let colorStr = component;
3059
- const trail = component.match(/\s+([\d.]+)%$/);
3060
- const lead = component.match(/^([\d.]+)%\s+/);
3061
- if (trail) { pct = parseFloat(trail[1]); colorStr = component.slice(0, trail.index).trim(); }
3062
- else if (lead) { pct = parseFloat(lead[1]); colorStr = component.slice(lead[0].length).trim(); }
3063
- let color;
3064
- if (/^transparent$/i.test(colorStr)) color = { r: 0, g: 0, b: 0, a: 0 };
3065
- else color = parseAnyColor(colorStr);
3066
- if (!color) return null;
3067
- return { color, pct };
3068
- };
3438
+ const sibRect = sibling.getBoundingClientRect();
3439
+ const headRect = el.getBoundingClientRect();
3440
+ const sibStyle = getComputedStyle(sibling);
3069
3441
 
3070
- const c1 = parseComponent(args[1]);
3071
- const c2 = parseComponent(args[2]);
3072
- if (!c1 || !c2) return null;
3073
- let p1 = c1.pct, p2 = c2.pct;
3074
- if (p1 == null && p2 == null) { p1 = 50; p2 = 50; }
3075
- else if (p1 == null) p1 = 100 - p2;
3076
- else if (p2 == null) p2 = 100 - p1;
3077
- const sum = p1 + p2;
3078
- if (sum <= 0) return null;
3079
- // Per spec: weights normalize to sum; when sum < 100 the result alpha is
3080
- // additionally scaled by sum/100.
3081
- const w1 = p1 / sum, w2 = p2 / sum;
3082
- const alphaScale = sum < 100 ? sum / 100 : 1;
3083
- const a1 = c1.color.a ?? 1, a2 = c2.color.a ?? 1;
3084
- const a = (a1 * w1 + a2 * w2) * alphaScale;
3085
- if (a <= 0) return { r: 0, g: 0, b: 0, a: 0 };
3086
- const mix = (ch) => Math.round((c1.color[ch] * a1 * w1 + c2.color[ch] * a2 * w2) / (a1 * w1 + a2 * w2));
3087
- return { r: mix('r'), g: mix('g'), b: mix('b'), a: Math.min(1, a) };
3442
+ // The tile may either contain an <svg>/<i> icon child, OR the tile itself
3443
+ // may contain an emoji/symbol character directly as its only text content
3444
+ // (the "card-icon" pattern from many AI-generated demos).
3445
+ const iconChild = sibling.querySelector('svg, i[data-lucide], i[class*="fa-"], i[class*="icon"]');
3446
+ const iconRect = iconChild?.getBoundingClientRect();
3447
+ const sibDirectText = [...sibling.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
3448
+ const hasInlineEmojiIcon = sibling.children.length === 0 && isEmojiOnlyText(sibDirectText);
3449
+
3450
+ return checkIconTile({
3451
+ headingTag: tag,
3452
+ headingText: el.textContent || '',
3453
+ headingTop: headRect.top,
3454
+ siblingTag: sibling.tagName.toLowerCase(),
3455
+ siblingWidth: sibRect.width,
3456
+ siblingHeight: sibRect.height,
3457
+ siblingBottom: sibRect.bottom,
3458
+ siblingBgColor: parseRgb(sibStyle.backgroundColor),
3459
+ siblingBgImage: sibStyle.backgroundImage || '',
3460
+ siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
3461
+ siblingBorderRadius: parseFloat(sibStyle.borderRadius) || 0,
3462
+ hasIconChild: !!iconChild || hasInlineEmojiIcon,
3463
+ iconChildWidth: iconRect?.width || 0,
3464
+ });
3088
3465
  }
3089
3466
 
3090
- // Composite a translucent color over an opaque(ish) base (simple
3091
- // source-over in sRGB). Returns an opaque {r,g,b,a:1}.
3092
- function compositeColorOver(top, base) {
3093
- const a = top.a ?? 1;
3094
- return {
3095
- r: Math.round(top.r * a + base.r * (1 - a)),
3096
- g: Math.round(top.g * a + base.g * (1 - a)),
3097
- b: Math.round(top.b * a + base.b * (1 - a)),
3098
- a: 1,
3099
- };
3467
+ function checkElementItalicSerifDOM(el) {
3468
+ const tag = el.tagName.toLowerCase();
3469
+ if (tag !== 'h1' && tag !== 'h2') return [];
3470
+ const style = getComputedStyle(el);
3471
+ return checkItalicSerif({
3472
+ tag,
3473
+ fontStyle: style.fontStyle || '',
3474
+ fontFamily: style.fontFamily || '',
3475
+ fontSize: parseFloat(style.fontSize) || 0,
3476
+ headingText: el.textContent || '',
3477
+ });
3100
3478
  }
3101
3479
 
3102
- // Extended color parser: rgb/rgba/hex/oklch/oklab/hsl/hwb/color-mix/common
3103
- // named colors. Returns null on no match. Use this when the input might be
3104
- // any CSS color form; use plain parseRgb when you only expect computed rgb()
3105
- // values from real browsers.
3106
- function parseAnyColor(s) {
3107
- if (!s || typeof s !== 'string') return null;
3108
- const str = s.trim();
3109
- if (str === 'transparent' || str === 'currentcolor' || str === 'inherit') return null;
3110
- if (/^color-mix\(/i.test(str)) return parseColorMix(str);
3111
- let m;
3112
- m = str.match(/rgba?\(\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)(?:\s*[,/]\s*([\d.]+))?\s*\)/);
3113
- 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 };
3114
- m = str.match(/^#([0-9a-f]{3,8})$/i);
3115
- if (m) {
3116
- const h = m[1];
3117
- if (h.length === 3 || h.length === 4) {
3118
- return {
3119
- r: parseInt(h[0] + h[0], 16),
3120
- g: parseInt(h[1] + h[1], 16),
3121
- b: parseInt(h[2] + h[2], 16),
3122
- a: h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1,
3123
- };
3124
- }
3125
- if (h.length === 6 || h.length === 8) {
3126
- return {
3127
- r: parseInt(h.slice(0, 2), 16),
3128
- g: parseInt(h.slice(2, 4), 16),
3129
- b: parseInt(h.slice(4, 6), 16),
3130
- a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
3131
- };
3132
- }
3133
- }
3134
- // OKLCH parser. Tailwind v4's CSS minifier squishes the space after
3135
- // `%` ("21.5%.02 50"), so the separator between L and C may be absent.
3136
- // Match L (with optional %), then C and H separated permissively.
3137
- m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
3138
- if (m) {
3139
- const Lnum = parseFloat(m[1]);
3140
- const L = m[2] === '%' ? Lnum / 100 : Lnum;
3141
- const rgb = oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]));
3142
- if (m[5] !== undefined) {
3143
- const alpha = parseFloat(m[5]);
3144
- rgb.a = m[6] === '%' ? alpha / 100 : alpha;
3145
- }
3146
- return rgb;
3147
- }
3148
- // OKLAB — a/b are signed axes; percentages map 100% → 0.4.
3149
- m = str.match(/oklab\(\s*([\d.]+)(%?)\s+(-?[\d.]+)(%?)\s+(-?[\d.]+)(%?)(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
3150
- if (m) {
3151
- const L = m[2] === '%' ? parseFloat(m[1]) / 100 : parseFloat(m[1]);
3152
- const a = m[4] === '%' ? parseFloat(m[3]) * 0.004 : parseFloat(m[3]);
3153
- const b = m[6] === '%' ? parseFloat(m[5]) * 0.004 : parseFloat(m[5]);
3154
- const rgb = oklabToRgb(L, a, b);
3155
- if (m[7] !== undefined) {
3156
- const alpha = parseFloat(m[7]);
3157
- rgb.a = m[8] === '%' ? alpha / 100 : alpha;
3158
- }
3159
- return rgb;
3160
- }
3161
- // HSL/HSLA — comma or space syntax, optional deg on hue.
3162
- m = str.match(/hsla?\(\s*(-?[\d.]+)(?:deg)?\s*[,\s]\s*([\d.]+)%\s*[,\s]\s*([\d.]+)%(?:\s*[,/]\s*([\d.]+)(%)?)?\s*\)/i);
3163
- if (m) {
3164
- const rgb = hslToRgb(parseFloat(m[1]), parseFloat(m[2]) / 100, parseFloat(m[3]) / 100);
3165
- if (m[4] !== undefined) {
3166
- const alpha = parseFloat(m[4]);
3167
- rgb.a = m[5] === '%' ? alpha / 100 : alpha;
3168
- }
3169
- return rgb;
3480
+ function domAccentDashPseudo(el) {
3481
+ for (const which of ['::before', '::after']) {
3482
+ let ps;
3483
+ try { ps = getComputedStyle(el, which); } catch { continue; }
3484
+ if (!ps || ps.content === 'none' || ps.content === '') continue;
3485
+ const w = parseFloat(ps.width) || 0;
3486
+ const h = parseFloat(ps.height) || 0;
3487
+ if (!(w >= 8 && w <= 80 && h >= 1 && h <= 6)) continue;
3488
+ const bg = parseRgb(ps.backgroundColor) || parseAnyColor(ps.backgroundColor);
3489
+ if (!bg || (bg.a ?? 1) < 0.1) continue;
3490
+ if (Math.max(bg.r, bg.g, bg.b) - Math.min(bg.r, bg.g, bg.b) >= 30) return true;
3170
3491
  }
3171
- // HWB — hue whiteness% blackness%.
3172
- m = str.match(/hwb\(\s*(-?[\d.]+)(?:deg)?\s+([\d.]+)%\s+([\d.]+)%(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
3173
- if (m) {
3174
- const rgb = hwbToRgb(parseFloat(m[1]), parseFloat(m[2]) / 100, parseFloat(m[3]) / 100);
3175
- if (m[4] !== undefined) {
3176
- const alpha = parseFloat(m[4]);
3177
- rgb.a = m[5] === '%' ? alpha / 100 : alpha;
3492
+ return false;
3493
+ }
3494
+
3495
+ function checkElementHeroEyebrowDOM(el) {
3496
+ const tag = el.tagName.toLowerCase();
3497
+ if (tag !== 'h1') return [];
3498
+ const sibling = el.previousElementSibling;
3499
+ if (!sibling) return [];
3500
+ const headStyle = getComputedStyle(el);
3501
+ const sibStyle = getComputedStyle(sibling);
3502
+ return checkHeroEyebrow({
3503
+ headingTag: tag,
3504
+ headingText: el.textContent || '',
3505
+ headingFontSize: parseFloat(headStyle.fontSize) || 0,
3506
+ headingInApplicationContext: !!el.closest('[role="tabpanel"], [role="dialog"], [role="application"], dialog'),
3507
+ siblingTag: sibling.tagName.toLowerCase(),
3508
+ siblingText: sibling.textContent || '',
3509
+ siblingTextTransform: sibStyle.textTransform || '',
3510
+ siblingFontSize: parseFloat(sibStyle.fontSize) || 0,
3511
+ siblingLetterSpacing: parseFloat(sibStyle.letterSpacing) || 0,
3512
+ siblingFontWeight: sibStyle.fontWeight || '',
3513
+ siblingColor: sibStyle.color || '',
3514
+ siblingHasAccentDashPseudo: domAccentDashPseudo(sibling),
3515
+ });
3516
+ }
3517
+
3518
+ // Build a map of CSS custom properties declared on :root / :host / html.
3519
+ // Used to resolve var(--X) refs that jsdom returns verbatim in
3520
+ // getComputedStyle. Tailwind v4 routes every utility class through
3521
+ // CSS vars (font-weight: var(--font-weight-bold), font-size:
3522
+ // var(--text-xs), letter-spacing: var(--tracking-widest)), so without
3523
+ // resolution every style-based check silently fails on Tailwind v4
3524
+ // builds — the values come back as literal "var(--font-weight-bold)"
3525
+ // strings and parseFloat returns NaN.
3526
+ function buildCustomPropMap(document) {
3527
+ const map = new Map();
3528
+ let sheets;
3529
+ try { sheets = Array.from(document.styleSheets || []); }
3530
+ catch { return map; }
3531
+ for (const sheet of sheets) {
3532
+ let rules;
3533
+ try { rules = Array.from(sheet.cssRules || []); }
3534
+ catch { continue; }
3535
+ for (const rule of rules) {
3536
+ // Style rules only (type 1). Walk @media / @supports if present.
3537
+ if (rule.type === 4 /* MEDIA_RULE */ || rule.type === 12 /* SUPPORTS_RULE */) {
3538
+ try { rules.push(...Array.from(rule.cssRules || [])); } catch { /* ignore */ }
3539
+ continue;
3540
+ }
3541
+ if (rule.type !== 1 /* STYLE_RULE */) continue;
3542
+ const sel = rule.selectorText || '';
3543
+ if (!/(^|,\s*)(:root|html|:host)\b/i.test(sel)) continue;
3544
+ const style = rule.style;
3545
+ if (!style) continue;
3546
+ for (let i = 0; i < style.length; i++) {
3547
+ const prop = style[i];
3548
+ if (!prop || !prop.startsWith('--')) continue;
3549
+ const val = style.getPropertyValue(prop).trim();
3550
+ if (val) map.set(prop, val);
3551
+ }
3178
3552
  }
3179
- return rgb;
3180
3553
  }
3181
- const named = CSS_NAMED_COLORS[str.toLowerCase()];
3182
- if (named) return { ...named, a: 1 };
3183
- return null;
3554
+ return map;
3555
+ }
3556
+
3557
+ // Resolve var(--X[, fallback]) refs in a computed-style value string.
3558
+ // Recurses up to 8 levels for chained refs (--a: var(--b)). Returns
3559
+ // the original string when no refs are present or the chain doesn't
3560
+ // resolve. Safe to call on already-resolved values.
3561
+ function resolveVarRefs(raw, customPropMap, depth = 0) {
3562
+ if (typeof raw !== 'string' || !raw.includes('var(')) return raw;
3563
+ if (depth > 8) return raw;
3564
+ return raw.replace(/var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,\s*([^)]+))?\)/g, (_m, name, fallback) => {
3565
+ const v = customPropMap.get(name);
3566
+ if (v != null) return resolveVarRefs(v, customPropMap, depth + 1);
3567
+ return fallback ? resolveVarRefs(fallback.trim(), customPropMap, depth + 1) : _m;
3568
+ });
3184
3569
  }
3185
3570
 
3571
+
3186
3572
  // Resolve var() refs in a color string (via customPropMap), then parse.
3187
3573
  // Returns null on any failure. Used in jsdom-mode paths where
3188
3574
  // getComputedStyle returns literal "var(--X)" or "oklch(...)" strings.
@@ -3271,7 +3657,11 @@ function isKickerCandidate(opts) {
3271
3657
  || isSmallCaps;
3272
3658
  if (!isUppercased) return false;
3273
3659
  if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false;
3274
- const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08);
3660
+ // Proportional only, no absolute floor: the wild's most common recipe is
3661
+ // 0.08em at a sub-13px size, which computes to under 1px and sailed past
3662
+ // the old Math.max(1, ...) floor (observed live: a page whose kickers were
3663
+ // literally class="kicker" produced zero findings).
3664
+ const minTrackedSpacing = kickerFontSize * 0.06;
3275
3665
  if (!(kickerLetterSpacing >= minTrackedSpacing)) return false;
3276
3666
  return true;
3277
3667
  }
@@ -3540,9 +3930,20 @@ function checkElementGlowDOM(el) {
3540
3930
  if (!boxShadow && !textShadow) return [];
3541
3931
  // Use parent's background — glow radiates outward, so the surrounding context matters
3542
3932
  // If resolveBackground returns null (gradient), try to infer from the gradient colors
3543
- let parentBg = el.parentElement ? resolveBackground(el.parentElement) : resolveBackground(el);
3544
- if (!parentBg) {
3545
- // Gradient background — sample its colors to determine if it's dark
3933
+ const parentBgInfo = resolveBackgroundInfo(el.parentElement || el);
3934
+ // Unknown surface (an unreadable layer on the way up): skip only the
3935
+ // gradient hunt below, which would walk PAST that layer and score the
3936
+ // glow against a background the visitor never sees. checkGlow still runs
3937
+ // with a null surface: the zero-offset chromatic halo tell holds on ANY
3938
+ // background, and the static loop already passes the unresolved walk's
3939
+ // null color straight through (detect-html.mjs uses resolveBackground).
3940
+ let parentBg = parentBgInfo.color;
3941
+ if (!parentBg && !parentBgInfo.unresolved) {
3942
+ // Gradient background — sample its colors to determine if it's dark.
3943
+ // Modern-syntax parsing matters here: body-level gradients now reach this
3944
+ // fallback in browser mode, and their stops usually serialize as oklch —
3945
+ // which the shared parseGradientColors reads via its color-function
3946
+ // token capture.
3546
3947
  let cur = el.parentElement;
3547
3948
  while (cur && cur.nodeType === 1) {
3548
3949
  const bgImage = getComputedStyle(cur).backgroundImage || '';
@@ -3590,10 +3991,13 @@ function checkElementAIPaletteDOM(el) {
3590
3991
  const hue = getHue(textColor);
3591
3992
  const isAIPalette = (hue >= 160 && hue <= 200) || (hue >= 260 && hue <= 310);
3592
3993
  if (isAIPalette) {
3593
- const parentBg = el.parentElement ? resolveBackground(el.parentElement) : null;
3594
- // Also check gradient parents
3595
- let effectiveBg = parentBg;
3596
- if (!effectiveBg) {
3994
+ const parentBgInfo = el.parentElement
3995
+ ? resolveBackgroundInfo(el.parentElement)
3996
+ : { color: null, unresolved: false };
3997
+ // Unknown surface: leave effectiveBg null (no finding) rather than
3998
+ // hunting gradient ancestors past a layer we could not read.
3999
+ let effectiveBg = parentBgInfo.color;
4000
+ if (!effectiveBg && !parentBgInfo.unresolved) {
3597
4001
  let cur = el.parentElement;
3598
4002
  while (cur && cur.nodeType === 1) {
3599
4003
  const gi = getComputedStyle(cur).backgroundImage || '';
@@ -4388,10 +4792,19 @@ function checkElementBorders(tag, style, overrides, resolvedRadius, el = null) {
4388
4792
  }
4389
4793
 
4390
4794
  function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInheritRule) {
4795
+ // Invisible at rest, static twin of the browser walk's skip: opacity does
4796
+ // not inherit, so walk ancestors multiplying declared opacity down.
4797
+ if (style.visibility === 'hidden') return [];
4798
+ let effOpacity = 1;
4799
+ for (let cur = el; cur && cur.nodeType === 1 && effOpacity > 0.02; cur = cur.parentElement) {
4800
+ effOpacity *= parseFloat(window.getComputedStyle(cur).opacity || '1');
4801
+ }
4802
+ if (effOpacity <= 0.02) return [];
4391
4803
  const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
4392
4804
  const hasDirectText = directText.trim().length > 0;
4393
4805
 
4394
- const effectiveBg = resolveBackground(el, window, customPropMap);
4806
+ const bgInfo = resolveBackgroundInfo(el, window, customPropMap);
4807
+ const effectiveBg = bgInfo.color;
4395
4808
  // jsdom returns literal "var(--X)" / "oklch(...)" for color, so plain
4396
4809
  // parseRgb misses Tailwind-tokenized text colors. Resolve through the
4397
4810
  // customPropMap first; fall back to parseRgb for vanilla rgb() pages.
@@ -4437,11 +4850,13 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
4437
4850
  // element itself has no usable own background, that pseudo is the real
4438
4851
  // surface for contrast purposes.
4439
4852
  let finalEffectiveBg = effectiveBg;
4853
+ let surfaceUnresolved = bgInfo.unresolved;
4440
4854
  if ((!ownBg || (ownBg.a ?? 1) <= 0.5) && typeof window.getPseudoSurface === 'function') {
4441
4855
  const pseudoSurface = window.getPseudoSurface(el);
4442
4856
  if (pseudoSurface) {
4443
4857
  ownBg = pseudoSurface;
4444
4858
  finalEffectiveBg = pseudoSurface;
4859
+ surfaceUnresolved = false;
4445
4860
  }
4446
4861
  }
4447
4862
 
@@ -4449,8 +4864,9 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
4449
4864
  tag,
4450
4865
  textColor,
4451
4866
  bgColor: ownBg,
4452
- effectiveBg: finalEffectiveBg,
4453
- effectiveBgStops: finalEffectiveBg ? null : resolveGradientStops(el, window, customPropMap),
4867
+ // Unknown surface: hand the checks nothing rather than a guess.
4868
+ effectiveBg: surfaceUnresolved ? null : finalEffectiveBg,
4869
+ effectiveBgStops: surfaceUnresolved || finalEffectiveBg ? null : resolveGradientStops(el, window, customPropMap),
4454
4870
  fontSize: parseFloat(style.fontSize) || 16,
4455
4871
  fontWeight: parseInt(style.fontWeight) || 400,
4456
4872
  hasDirectText,
@@ -4655,12 +5071,6 @@ function checkTypography() {
4655
5071
  if (isBrandFontOnOwnDomain(font)) continue;
4656
5072
  findings.push({ type: 'overused-font', detail: `Primary font: ${font} (${Math.round(share * 100)}% of text)` });
4657
5073
  }
4658
-
4659
- // Single-font check: only one distinct primary font across all text
4660
- if (fontUsage.size === 1) {
4661
- const only = [...fontUsage.keys()][0];
4662
- findings.push({ type: 'single-font', detail: `only font used is ${only}` });
4663
- }
4664
5074
  }
4665
5075
 
4666
5076
  const sizes = new Set();
@@ -4922,14 +5332,6 @@ function checkPageTypography(doc, win) {
4922
5332
  findings.push({ id: 'overused-font', snippet: `Primary font: ${font}` });
4923
5333
  }
4924
5334
 
4925
- // Single font
4926
- if (fonts.size === 1) {
4927
- const els = doc.querySelectorAll('*');
4928
- if (els.length >= 20) {
4929
- findings.push({ id: 'single-font', snippet: `only font used is ${[...fonts][0]}` });
4930
- }
4931
- }
4932
-
4933
5335
  // Flat type hierarchy
4934
5336
  const sizes = new Set();
4935
5337
  const textEls = doc.querySelectorAll('h1, h2, h3, h4, h5, h6, p, span, a, li, td, th, label, button, div');
@@ -5560,6 +5962,11 @@ function isRenderedForBrowserRule(el) {
5560
5962
  function checkElementTextOverflowDOM(el) {
5561
5963
  const tag = el.tagName.toLowerCase();
5562
5964
  if (TEXT_OVERFLOW_SKIP_TAGS.has(tag)) return [];
5965
+ // scrollWidth/clientWidth are CSS box-model metrics; on SVG content Chrome
5966
+ // returns arbitrary non-zero values for both (a <text> reported 78/48 while
5967
+ // its rendered length sat comfortably inside its box), so the delta is
5968
+ // noise, not overflow. SVG clips to its own viewport anyway.
5969
+ if (el.namespaceURI === 'http://www.w3.org/2000/svg') return [];
5563
5970
  if (!isRenderedForBrowserRule(el)) return [];
5564
5971
  // Only the element that actually owns overflowing text — not its ancestors,
5565
5972
  // which inherit a wider scrollWidth from the spilling descendant.
@@ -5944,6 +6351,22 @@ function isPaintedForOcclusion(el) {
5944
6351
  // path is pure geometry and runs anywhere on the page.
5945
6352
  const OCCLUSION_TEXT_SKIP_TAGS = new Set(['script', 'style', 'noscript', 'template', 'title']);
5946
6353
 
6354
+ // An element whose effective opacity multiplies out to ~0 paints nothing at
6355
+ // rest: it is not user-visible, so visual findings on it (contrast, occlusion)
6356
+ // measure a state nobody sees. Browser-only — the walk needs live computed
6357
+ // styles. Cycling scenes that fade such elements in later are the screenshot
6358
+ // subsystem's territory, not the analytic walk's.
6359
+ function effectiveOpacityDOM(el) {
6360
+ let o = 1;
6361
+ // Walk all the way through body and html: `body { opacity: 0 }` page-fade
6362
+ // wrappers hide every descendant just as thoroughly as a local wrapper.
6363
+ for (let cur = el; cur && cur.nodeType === 1; cur = cur.parentElement) {
6364
+ o *= parseFloat(getComputedStyle(cur).opacity || '1');
6365
+ if (o <= 0.02) return 0;
6366
+ }
6367
+ return o;
6368
+ }
6369
+
5947
6370
  function checkTextOcclusionDOM() {
5948
6371
  const findings = [];
5949
6372
  const seenVictims = new Set();
@@ -5971,6 +6394,11 @@ function checkTextOcclusionDOM() {
5971
6394
  }
5972
6395
  return false;
5973
6396
  };
6397
+ // The classic occluder shape this rules out is an opacity-0 interaction
6398
+ // layer — a range scrubber stretched over a before/after comparison — which
6399
+ // elementFromPoint still returns and whose UA background-color otherwise
6400
+ // reads as an opaque box.
6401
+ const effectiveOpacity = effectiveOpacityDOM;
5974
6402
 
5975
6403
  // Collect renderable text owners in / near the first viewport for the
5976
6404
  // elementFromPoint probe. SVG <text> counts too.
@@ -5983,6 +6411,7 @@ function checkTextOcclusionDOM() {
5983
6411
  const text = inSvg ? (el.textContent || '').trim() : elementDirectText(el);
5984
6412
  if (text.length < 2) continue;
5985
6413
  if (!isPaintedForOcclusion(el)) continue;
6414
+ if (effectiveOpacity(el) <= 0.02) continue;
5986
6415
  let rect; try { rect = el.getBoundingClientRect(); } catch { continue; }
5987
6416
  if (rect.width < 6 || rect.height < 6) continue;
5988
6417
  // Viewport-bound probe: keep text whose box overlaps the live viewport.
@@ -6016,6 +6445,7 @@ function checkTextOcclusionDOM() {
6016
6445
  if (top === el || el.contains(top) || top.contains(el)) continue;
6017
6446
  const topCs = getComputedStyle(top);
6018
6447
  if (isFloated(topCs) || isMarqueeish(top, topCs) || isPinnedOverlay(top)) continue;
6448
+ if (effectiveOpacity(top) <= 0.02) continue;
6019
6449
  const topTag = top.tagName.toLowerCase();
6020
6450
  // Text sitting under a raw image/video is contrast territory (deduped
6021
6451
  // against the pixel low-contrast rule); leave those alone here.
@@ -6908,6 +7338,10 @@ if (IS_BROWSER) {
6908
7338
 
6909
7339
  const reasons = collectVisualContrastReasons(el, style);
6910
7340
  if (reasons.length === 0) continue;
7341
+ // Image-only mode filters here, inside the cap: gradient/opacity/filter
7342
+ // candidates earlier in DOM order must not consume the budget and
7343
+ // starve the url()-backed texts this mode exists to sample.
7344
+ if (options.imageOnly && !reasons.includes('image background')) continue;
6911
7345
 
6912
7346
  const textColor = parseRgb(style.color);
6913
7347
  const fontSize = parseFloat(style.fontSize) || 16;
@@ -7400,6 +7834,7 @@ if (IS_BROWSER) {
7400
7834
  }
7401
7835
 
7402
7836
  async function analyzeVisualContrast(options = {}) {
7837
+ // imageOnly is enforced inside the collector, before the candidate cap.
7403
7838
  const candidates = collectVisualContrastCandidates(options);
7404
7839
  const results = [];
7405
7840
  const shouldScrollOffscreen = options.scrollOffscreen === true;
@@ -7485,9 +7920,16 @@ if (IS_BROWSER) {
7485
7920
 
7486
7921
  function addBrowserFindings(groupMap, el, findings) {
7487
7922
  if (!findings || findings.length === 0) return;
7923
+ // Element-scoped waivers: a data-impeccable-ignore ancestor suppresses
7924
+ // matching findings for its whole subtree. Applied at this choke point so
7925
+ // every per-element attribution (checks, layout, occlusion, rhythm)
7926
+ // honors it; page-level findings attributed to <body> pass through
7927
+ // untouched, since body has no ignoring ancestor.
7928
+ const kept = findings.filter(f => !scopedIgnoreActive(el, f.type));
7929
+ if (kept.length === 0) return;
7488
7930
  const existing = groupMap.get(el);
7489
- if (existing) existing.push(...findings);
7490
- else groupMap.set(el, [...findings]);
7931
+ if (existing) existing.push(...kept);
7932
+ else groupMap.set(el, [...kept]);
7491
7933
  }
7492
7934
 
7493
7935
  function browserFindingsFromMap(groupMap) {
@@ -7845,9 +8287,27 @@ if (IS_BROWSER) {
7845
8287
  for (const node of docClone.querySelectorAll('[id^="impeccable-live-"]')) {
7846
8288
  node.remove();
7847
8289
  }
7848
- const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
7849
- if (htmlPatternFindings.length > 0) {
7850
- const mapped = htmlPatternFindings.map(f => {
8290
+ // Regex findings that name a live selector resolve against the real DOM:
8291
+ // pseudo-element/class segments are stripped (the host element is the
8292
+ // anchor), a selector that matches nothing on this page drops the finding
8293
+ // (the CSS ships here, but the pattern never renders — the live DOM is
8294
+ // ground truth in the browser), and a match under a data-impeccable-ignore
8295
+ // ancestor is waived. Selector-less findings stay page-level.
8296
+ const scopedHtmlFindings = checkHtmlPatterns(docClone.outerHTML).filter(f => {
8297
+ if (!f.selector) return true;
8298
+ const query = String(f.selector).replace(/::?[a-zA-Z-]+(\([^)]*\))?/g, '').trim().replace(/,\s*(?=,|$)/g, '');
8299
+ if (!query || /^[,\s]*$/.test(query)) return true;
8300
+ let matches;
8301
+ try {
8302
+ matches = document.querySelectorAll(query);
8303
+ } catch {
8304
+ return true;
8305
+ }
8306
+ if (matches.length === 0) return false;
8307
+ return [...matches].some(el => !scopedIgnoreActive(el, f.id));
8308
+ });
8309
+ if (scopedHtmlFindings.length > 0) {
8310
+ const mapped = scopedHtmlFindings.map(f => {
7851
8311
  const item = { type: f.id, detail: f.snippet };
7852
8312
  if (f.severity) {
7853
8313
  item.severity = f.severity;
@@ -7877,8 +8337,27 @@ if (IS_BROWSER) {
7877
8337
  };
7878
8338
  }
7879
8339
 
8340
+ // Visual contrast has three modes. Explicit true runs the full sampled
8341
+ // pass; explicit false disables it entirely (the deterministic-only mode
8342
+ // the test suites use). Unset — the default overlay run — samples ONLY
8343
+ // image-backed text: the one class the analytic walk deliberately skips,
8344
+ // because a url() layer's pixels are unknowable without looking. In-page
8345
+ // sampling draws the source image alone to a canvas (glyph ink never
8346
+ // pollutes it), and a cross-origin image without CORS reports unresolved
8347
+ // instead of guessing.
8348
+ function visualContrastMode(options = {}) {
8349
+ const explicit = typeof options.visualContrast === 'boolean'
8350
+ ? options.visualContrast
8351
+ : typeof window.__IMPECCABLE_CONFIG__?.visualContrast === 'boolean'
8352
+ ? window.__IMPECCABLE_CONFIG__.visualContrast
8353
+ : null;
8354
+ if (explicit === true) return 'full';
8355
+ if (explicit === false) return false;
8356
+ return 'image-only';
8357
+ }
8358
+
7880
8359
  function shouldRunVisualContrast(options = {}) {
7881
- return options.visualContrast === true || window.__IMPECCABLE_CONFIG__?.visualContrast === true;
8360
+ return visualContrastMode(options) !== false;
7882
8361
  }
7883
8362
 
7884
8363
  function visualContrastOptions(options = {}) {
@@ -8055,6 +8534,7 @@ if (IS_BROWSER) {
8055
8534
  return [];
8056
8535
  }
8057
8536
  const resolvedOptions = visualContrastOptions(options);
8537
+ if (visualContrastMode(options) === 'image-only') resolvedOptions.imageOnly = true;
8058
8538
  const analyses = await analyzeVisualContrast(resolvedOptions);
8059
8539
  if (runtime.generation && runtime.generation !== scanGeneration) return analyses;
8060
8540
  lastVisualContrastAnalyses = analyses;