1import {
2  BORDER_SAFE_TAGS,
3  GENERIC_FONTS,
4  KNOWN_SERIF_FONTS,
5  OVERUSED_FONTS,
6  SAFE_TAGS,
7  WCAG_LARGE_BOLD_TEXT_PX,
8  WCAG_LARGE_TEXT_PX,
9  isBrandFontOnOwnDomain,
10} from '../shared/constants.mjs';
11import {
12  colorToHex,
13  contrastRatio,
14  getHue,
15  hasChroma,
16  isNeutralColor,
17  parseGradientColors,
18  parseRgb,
19  relativeLuminance,
20} from '../shared/color.mjs';
21 
22const DETECTOR_IS_BROWSER = typeof window !== 'undefined';
23 
24// ─── Section 3: Pure Detection ──────────────────────────────────────────────
25 
26function checkBorders(tag, widths, colors, radius) {
27  if (BORDER_SAFE_TAGS.has(tag)) return [];
28  const findings = [];
29  const sides = ['Top', 'Right', 'Bottom', 'Left'];
30 
31  for (const side of sides) {
32    const w = widths[side];
33    if (w < 1 || isNeutralColor(colors[side])) continue;
34 
35    const otherSides = sides.filter(s => s !== side);
36    const maxOther = Math.max(...otherSides.map(s => widths[s]));
37    if (!(w >= 2 && (maxOther <= 1 || w >= maxOther * 2))) continue;
38 
39    const sn = side.toLowerCase();
40    const isSide = side === 'Left' || side === 'Right';
41 
42    if (isSide) {
43      if (radius > 0) findings.push({ id: 'side-tab', snippet: `border-${sn}: ${w}px + border-radius: ${radius}px` });
44      else if (w >= 3) findings.push({ id: 'side-tab', snippet: `border-${sn}: ${w}px` });
45    } else {
46      if (radius > 0 && w >= 2) findings.push({ id: 'border-accent-on-rounded', snippet: `border-${sn}: ${w}px + border-radius: ${radius}px` });
47    }
48  }
49 
50  return findings;
51}
52 
53// Returns true if the given text is composed entirely of emoji characters
54// (plus whitespace / variation selectors). Emojis render as multicolor glyphs
55// regardless of CSS `color`, so contrast checks against the element's text
56// color are meaningless for these nodes.
57const 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;
58const 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;
59function isEmojiOnlyText(text) {
60  if (!text) return false;
61  if (!EMOJI_CHAR_RE.test(text)) return false;
62  return text.replace(EMOJI_CHARS_GLOBAL, '').trim() === '';
63}
64 
65function checkColors(opts) {
66  const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList } = opts;
67  if (SAFE_TAGS.has(tag)) {
68    // Exception for <a> and <button> elements styled as buttons. SAFE_TAGS
69    // exists to suppress contrast noise on inline links and unstyled controls,
70    // where the element has no own background and the contrast against the
71    // ancestor surface is already the intended visual. When the element has
72    // its own opaque background and direct text, it is a styled button — and
73    // contrast on its own surface is a real, frequent bug worth flagging.
74    const isStyledButton = (tag === 'a' || tag === 'button')
75      && hasDirectText
76      && bgColor && bgColor.a > 0.5;
77    if (!isStyledButton) return [];
78  }
79  const findings = [];
80 
81  if (hasDirectText && textColor && !isEmojiOnly) {
82    // Run background-dependent checks against either a solid bg or, if the
83    // ancestor is a gradient, against every gradient stop (use the worst case).
84    const bgs = effectiveBg ? [effectiveBg] : (effectiveBgStops && effectiveBgStops.length ? effectiveBgStops : null);
85    if (bgs) {
86      // Gray on colored background — flag if every stop is chromatic
87      const textLum = relativeLuminance(textColor);
88      const isGray = !hasChroma(textColor, 20) && textLum > 0.05 && textLum < 0.85;
89      if (isGray && bgs.every(b => hasChroma(b, 40))) {
90        const bgLabel = effectiveBg ? colorToHex(effectiveBg) : `gradient(${bgs.map(colorToHex).join(', ')})`;
91        findings.push({ id: 'gray-on-color', snippet: `text ${colorToHex(textColor)} on bg ${bgLabel}` });
92      }
93 
94      // Low contrast (WCAG AA) — worst case across all bg stops
95      const ratios = bgs.map(b => contrastRatio(textColor, b));
96      let worstIdx = 0;
97      for (let i = 1; i < ratios.length; i++) if (ratios[i] < ratios[worstIdx]) worstIdx = i;
98      const ratio = ratios[worstIdx];
99      const isLargeText = fontSize >= WCAG_LARGE_TEXT_PX || (fontSize >= WCAG_LARGE_BOLD_TEXT_PX && fontWeight >= 700);
100      const threshold = isLargeText ? 3.0 : 4.5;
101      if (ratio < threshold) {
102        // Skip the false-positive class where text has alpha < 1 AND we
103        // couldn't find an opaque ancestor (effectiveBg is null, we're
104        // comparing against gradient-stop fallback). In jsdom mode the
105        // detector can't resolve `var(--X)` color tokens, so a dark
106        // section sitting between the text and the body's decorative
107        // gradient is invisible to us — we end up measuring contrast
108        // against the body's paper-grain noise instead of the real
109        // local bg. Real low-contrast bugs use alpha=1 and have a
110        // resolvable opaque ancestor; semi-transparent Tailwind tokens
111        // like `text-paper/60` on `bg-ink` sections are the FP pattern.
112        const isAlphaFallbackFP = !DETECTOR_IS_BROWSER && !effectiveBg && (textColor.a != null && textColor.a < 1);
113        if (!isAlphaFallbackFP) {
114          findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}` });
115        }
116      }
117    }
118 
119    // AI palette: purple/violet on headings
120    if (hasChroma(textColor, 50)) {
121      const hue = getHue(textColor);
122      if (hue >= 260 && hue <= 310 && (['h1', 'h2', 'h3'].includes(tag) || fontSize >= 20)) {
123        findings.push({ id: 'ai-color-palette', snippet: `Purple/violet text (${colorToHex(textColor)}) on heading` });
124      }
125    }
126  }
127 
128  // Gradient text
129  if (bgClip === 'text' && bgImage && bgImage.includes('gradient')) {
130    findings.push({ id: 'gradient-text', snippet: 'background-clip: text + gradient' });
131  }
132 
133  // Tailwind class checks
134  if (classList) {
135    const classStr = typeof classList === 'string' ? classList : Array.from(classList).join(' ');
136 
137    const grayMatch = classStr.match(/\btext-(?:gray|slate|zinc|neutral|stone)-\d+\b/);
138    const colorBgMatch = classStr.match(/\bbg-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d+\b/);
139    if (grayMatch && colorBgMatch) {
140      findings.push({ id: 'gray-on-color', snippet: `${grayMatch[0]} on ${colorBgMatch[0]}` });
141    }
142 
143    if (/\bbg-clip-text\b/.test(classStr) && /\bbg-gradient-to-/.test(classStr)) {
144      findings.push({ id: 'gradient-text', snippet: 'bg-clip-text + bg-gradient (Tailwind)' });
145    }
146 
147    const purpleText = classStr.match(/\btext-(?:purple|violet|indigo)-\d+\b/);
148    if (purpleText && (['h1', 'h2', 'h3'].includes(tag) || /\btext-(?:[2-9]xl)\b/.test(classStr))) {
149      findings.push({ id: 'ai-color-palette', snippet: `${purpleText[0]} on heading` });
150    }
151 
152    if (/\bfrom-(?:purple|violet|indigo)-\d+\b/.test(classStr) && /\bto-(?:purple|violet|indigo|blue|cyan|pink|fuchsia)-\d+\b/.test(classStr)) {
153      findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet gradient (Tailwind)' });
154    }
155  }
156 
157  return findings;
158}
159 
160function isCardLikeFromProps(hasShadow, hasBorder, hasRadius, hasBg) {
161  if (!hasShadow && !hasBorder) return false;
162  return hasRadius || hasBg;
163}
164 
165const HEADING_TAGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
166 
167// Pure check: given a heading and metrics about its previousElementSibling,
168// decide if the sibling is the canonical "icon-tile-stacked-above-heading" shape.
169//
170// Triggers when ALL of the following hold for the sibling:
171//   • size 32–128px on both axes (not too small, not a hero image)
172//   • aspect ratio 0.7–1.4 (squarish — excludes wide thumbnails / pill badges)
173//   • has a non-transparent background-color, background-image, OR a visible border
174//     (covers solid colors, white-with-border, gradients — anything that visually
175//      defines a tile)
176//   • border-radius < width/2 (excludes round avatars; rounded squares pass)
177//   • contains an <svg> or icon-class <i> element that's smaller than the tile
178//   • the tile sits above the heading (its bottom is above the heading's top)
179function checkIconTile(opts) {
180  const { headingTag, headingText, headingTop,
181          siblingTag, siblingWidth, siblingHeight, siblingBottom,
182          siblingBgColor, siblingBgImage, siblingBorderWidth, siblingBorderRadius,
183          hasIconChild, iconChildWidth } = opts;
184  if (!HEADING_TAGS.has(headingTag)) return [];
185  if (!siblingTag) return [];
186  // Don't recurse into nested headings (e.g. h2 above h3 in a section header)
187  if (HEADING_TAGS.has(siblingTag)) return [];
188 
189  // Size window: 32–128px on each axis
190  if (!(siblingWidth >= 32 && siblingWidth <= 128)) return [];
191  if (!(siblingHeight >= 32 && siblingHeight <= 128)) return [];
192 
193  // Squarish aspect ratio
194  const ratio = siblingWidth / siblingHeight;
195  if (ratio < 0.7 || ratio > 1.4) return [];
196 
197  // Must have something that visually defines the tile
198  const bgVisible = (siblingBgColor && siblingBgColor.a > 0.1)
199    || (siblingBgImage && siblingBgImage !== 'none' && siblingBgImage !== '');
200  const borderVisible = siblingBorderWidth > 0;
201  if (!bgVisible && !borderVisible) return [];
202 
203  // Exclude circles (avatars). Rounded squares pass.
204  if (siblingBorderRadius >= siblingWidth / 2) return [];
205 
206  // Must contain an icon element smaller than the tile
207  if (!hasIconChild) return [];
208  if (iconChildWidth && iconChildWidth >= siblingWidth * 0.95) return [];
209 
210  // Vertical stacking: tile must end above where the heading starts.
211  // (Allow the check to skip when both top/bottom are 0 — jsdom layout case.)
212  if (headingTop && siblingBottom && siblingBottom > headingTop + 4) return [];
213 
214  const text = (headingText || '').trim().slice(0, 60);
215  return [{
216    id: 'icon-tile-stack',
217    snippet: `${Math.round(siblingWidth)}x${Math.round(siblingHeight)}px icon tile above ${headingTag} "${text}"`,
218  }];
219}
220 
221// Resolve the primary (non-generic) face from a font-family string and return
222// whether the resolved primary is serif. Two paths:
223//   1. Primary face is in KNOWN_SERIF_FONTS → serif.
224//   2. Primary face is unknown but the stack ends in the generic `serif`
225//      token → treat as serif. Authors who declare `font-family: 'X', serif`
226//      almost always have a serif primary; a sans declared with a serif
227//      fallback is a code smell, not the common case.
228// Returns { primary, isSerif } so the snippet can name the face.
229function resolveSerif(fontFamily) {
230  if (!fontFamily) return { primary: null, isSerif: false };
231  const tokens = fontFamily.split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase());
232  const primary = tokens.find(f => f && !GENERIC_FONTS.has(f)) || null;
233  if (!primary) return { primary: null, isSerif: false };
234  if (KNOWN_SERIF_FONTS.has(primary)) return { primary, isSerif: true };
235  if (tokens.includes('serif')) return { primary, isSerif: true };
236  return { primary, isSerif: false };
237}
238 
239function checkItalicSerif(opts) {
240  const { tag, fontStyle, fontFamily, fontSize, headingText } = opts;
241  if (fontStyle !== 'italic') return [];
242  // Anchor the rule on hero-scale text. h1 is the canonical hero element;
243  // h2 ≥ 48px catches the cases where the design demotes the visual hero
244  // to an h2 but keeps the size.
245  if (tag !== 'h1' && !(tag === 'h2' && fontSize >= 48)) return [];
246  if (fontSize < 48) return [];
247  const { primary, isSerif } = resolveSerif(fontFamily);
248  if (!isSerif) return [];
249 
250  const text = (headingText || '').trim().slice(0, 60);
251  return [{
252    id: 'italic-serif-display',
253    snippet: `italic serif ${tag} (${primary || 'serif'}) at ${Math.round(fontSize)}px "${text}"`,
254  }];
255}
256 
257// Color saturation check. Returns true when the color has visible
258// chroma — i.e., it's an "accent color" rather than near-neutral.
259// Handles rgb()/rgba(), #hex, oklch(), and hsl(). var() refs are
260// expected to be pre-resolved by the caller.
261function isAccentColor(cssColor) {
262  if (!cssColor) return false;
263  const s = String(cssColor).trim();
264  // rgb / rgba — direct channel-distance check.
265  const rgbM = /rgba?\(\s*(\d+)\s*,?\s+|\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(s.replace(/rgba?\(\s*/, 'rgb(').replace(/,/g, ', '));
266  const rgbStrict = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(s);
267  if (rgbStrict) {
268    const r = +rgbStrict[1], g = +rgbStrict[2], b = +rgbStrict[3];
269    return (Math.max(r, g, b) - Math.min(r, g, b)) >= 40;
270  }
271  // #hex — 3, 4, 6, or 8 digit.
272  const hexM = /^#([0-9a-f]{3,8})\b/i.exec(s);
273  if (hexM) {
274    let h = hexM[1];
275    if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('').slice(0, 6);
276    else h = h.slice(0, 6);
277    if (h.length === 6) {
278      const r = parseInt(h.slice(0, 2), 16);
279      const g = parseInt(h.slice(2, 4), 16);
280      const b = parseInt(h.slice(4, 6), 16);
281      return (Math.max(r, g, b) - Math.min(r, g, b)) >= 40;
282    }
283  }
284  // oklch(L C H) — chroma C is what matters. Typical neutral grays
285  // have C < 0.02; visible accents are 0.05+. CSS minification can
286  // collapse spaces between L% and C ("oklch(43%.15 34)"), so we
287  // extract all numbers and take the second rather than matching a
288  // strict L-then-whitespace-then-C pattern.
289  if (/^oklch\(/i.test(s)) {
290    const nums = s.match(/\d*\.\d+|\d+/g);
291    if (nums && nums.length >= 2) {
292      const c = parseFloat(nums[1]);
293      return !Number.isNaN(c) && c >= 0.05;
294    }
295  }
296  // hsl(H, S%, L%) — saturation > 20% reads as accent.
297  const hslM = /hsla?\(\s*[\d.]+\s*,\s*([\d.]+)%/i.exec(s);
298  if (hslM) {
299    const sat = parseFloat(hslM[1]);
300    return !Number.isNaN(sat) && sat >= 20;
301  }
302  return false;
303}
304 
305// Sibling-relationship rule. Anchor on a hero-scale h1, look at the
306// previousElementSibling, and gate on EITHER the classic tracked-
307// uppercase eyebrow OR the modern accent-colored bold eyebrow.
308function checkHeroEyebrow(opts) {
309  const {
310    headingTag, headingText, headingFontSize,
311    siblingTag, siblingText, siblingTextTransform,
312    siblingFontSize, siblingLetterSpacing,
313    siblingFontWeight, siblingColor,
314  } = opts;
315  if (headingTag !== 'h1') return [];
316  // We previously gated on headingFontSize >= 48 to anchor "hero scale".
317  // But modern hero h1s use clamp() / vw / var(--text-*), none of which
318  // jsdom can resolve — the computed value comes back as "2em" or
319  // "var(--text-9xl)" and parseFloat returns 2 or NaN. The gate fails
320  // on virtually every Tailwind v4 / framework build. The other gates
321  // (sibling text 2-60 chars, font-size ≤ 14px, accent-bold OR
322  // tracked-caps) are tight enough to avoid false positives on non-
323  // hero h1s — a tiny tan label directly above any h1 is the
324  // antipattern regardless of how big the h1 ends up.
325  if (!siblingTag) return [];
326  // An h2 above an h1 is a different anti-pattern (heading hierarchy / dual
327  // headings) — never an eyebrow.
328  if (HEADING_TAGS.has(siblingTag)) return [];
329 
330  const text = (siblingText || '').trim();
331  if (text.length < 2 || text.length > 60) return [];
332  if (!(siblingFontSize > 0 && siblingFontSize <= 14)) return [];
333 
334  // Branch A: classic tracked-uppercase eyebrow.
335  const isUppercased = siblingTextTransform === 'uppercase'
336    || (/[A-Z]/.test(text) && !/[a-z]/.test(text));
337  const isClassicTracked = isUppercased && siblingLetterSpacing >= 1.6;
338 
339  // Branch B: modern accent-bold eyebrow — sentence case, low
340  // tracking, but bold + accent-colored. The style choices changed;
341  // the pattern is the same kicker-above-headline anti-pattern.
342  const weight = Number(siblingFontWeight) || 400;
343  const isAccentBold = weight >= 700 && isAccentColor(siblingColor || '');
344 
345  if (!isClassicTracked && !isAccentBold) return [];
346 
347  const headingTextSnippet = (headingText || '').trim().slice(0, 60);
348  const eyebrowSnippet = text.slice(0, 40);
349  const style = isClassicTracked ? 'tracked-caps' : 'accent-bold';
350  return [{
351    id: 'hero-eyebrow-chip',
352    snippet: `eyebrow chip (${style}) "${eyebrowSnippet}" above ${headingTag} "${headingTextSnippet}"`,
353  }];
354}
355 
356function checkRepeatedSectionKickers(opts) {
357  const { candidates, minCount = 3 } = opts;
358  if (!Array.isArray(candidates) || candidates.length < minCount) return [];
359  return candidates.map(candidate => ({
360    id: 'repeated-section-kickers',
361    snippet: `repeated section kicker "${candidate.kickerText}" before ${candidate.headingTag} "${candidate.headingText}" (${candidates.length} on page)`,
362  }));
363}
364 
365const LAYOUT_TRANSITION_PROPS = new Set([
366  'width', 'height', 'padding', 'margin',
367  'max-height', 'max-width', 'min-height', 'min-width',
368  'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
369  'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
370]);
371 
372function checkMotion(opts) {
373  const { tag, transitionProperty, animationName, timingFunctions, classList } = opts;
374  if (SAFE_TAGS.has(tag)) return [];
375  const findings = [];
376 
377  // --- Bounce/elastic easing ---
378  if (animationName && animationName !== 'none' && /bounce|elastic|wobble|jiggle|spring/i.test(animationName)) {
379    findings.push({ id: 'bounce-easing', snippet: `animation: ${animationName}` });
380  }
381  if (classList && /\banimate-bounce\b/.test(classList)) {
382    findings.push({ id: 'bounce-easing', snippet: 'animate-bounce (Tailwind)' });
383  }
384 
385  // Check timing functions for overshoot cubic-bezier (y values outside [0, 1])
386  if (timingFunctions) {
387    const bezierRe = /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g;
388    let m;
389    while ((m = bezierRe.exec(timingFunctions)) !== null) {
390      const y1 = parseFloat(m[2]), y2 = parseFloat(m[4]);
391      if (y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1) {
392        findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${m[1]}, ${m[2]}, ${m[3]}, ${m[4]})` });
393        break;
394      }
395    }
396  }
397 
398  // --- Layout property transition ---
399  if (transitionProperty && transitionProperty !== 'all' && transitionProperty !== 'none') {
400    const props = transitionProperty.split(',').map(p => p.trim().toLowerCase());
401    const layoutFound = props.filter(p => LAYOUT_TRANSITION_PROPS.has(p));
402    if (layoutFound.length > 0) {
403      findings.push({ id: 'layout-transition', snippet: `transition: ${layoutFound.join(', ')}` });
404    }
405  }
406 
407  return findings;
408}
409 
410function checkGlow(opts) {
411  const { boxShadow, effectiveBg } = opts;
412  if (!boxShadow || boxShadow === 'none') return [];
413  if (!effectiveBg) return [];
414 
415  // Only flag on dark backgrounds (luminance < 0.1)
416  const bgLum = relativeLuminance(effectiveBg);
417  if (bgLum >= 0.1) return [];
418 
419  // Split multiple shadows (commas not inside parentheses)
420  const parts = boxShadow.split(/,(?![^(]*\))/);
421  for (const shadow of parts) {
422    const colorMatch = shadow.match(/rgba?\([^)]+\)/);
423    if (!colorMatch) continue;
424    const color = parseRgb(colorMatch[0]);
425    if (!color || !hasChroma(color, 30)) continue;
426 
427    // Extract px values — in computed style: "color Xpx Ypx BLURpx [SPREADpx]"
428    const afterColor = shadow.substring(shadow.indexOf(colorMatch[0]) + colorMatch[0].length);
429    const beforeColor = shadow.substring(0, shadow.indexOf(colorMatch[0]));
430    const pxVals = [...beforeColor.matchAll(/([\d.]+)px/g), ...afterColor.matchAll(/([\d.]+)px/g)]
431      .map(m => parseFloat(m[1]));
432 
433    // Third value is blur (offset-x, offset-y, blur, [spread])
434    if (pxVals.length >= 3 && pxVals[2] > 4) {
435      return [{ id: 'dark-glow', snippet: `Colored glow (${colorToHex(color)}) on dark background` }];
436    }
437  }
438 
439  return [];
440}
441 
442/**
443 * Regex-on-HTML checks shared between browser and Node page-level detection.
444 * These don't need DOM access, just the raw HTML string.
445 */
446function checkHtmlPatterns(html) {
447  const findings = [];
448 
449  // --- Color ---
450 
451  // AI color palette: purple/violet
452  const purpleHexRe = /#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9|6366f1|764ba2|667eea)\b/gi;
453  if (purpleHexRe.test(html)) {
454    const purpleTextRe = /(?:(?:^|;)\s*color\s*:\s*(?:.*?)(?:#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9))|gradient.*?#(?:7c3aed|8b5cf6|a855f7|764ba2|667eea))/gi;
455    if (purpleTextRe.test(html)) {
456      findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet accent colors detected' });
457    }
458  }
459 
460  // Gradient text (background-clip: text + gradient)
461  const gradientRe = /(?:-webkit-)?background-clip\s*:\s*text/gi;
462  let gm;
463  while ((gm = gradientRe.exec(html)) !== null) {
464    const start = Math.max(0, gm.index - 200);
465    const context = html.substring(start, gm.index + gm[0].length + 200);
466    if (/gradient/i.test(context)) {
467      findings.push({ id: 'gradient-text', snippet: 'background-clip: text + gradient' });
468      break;
469    }
470  }
471  if (/\bbg-clip-text\b/.test(html) && /\bbg-gradient-to-/.test(html)) {
472    findings.push({ id: 'gradient-text', snippet: 'bg-clip-text + bg-gradient (Tailwind)' });
473  }
474 
475  // --- Layout ---
476 
477  // Monotonous spacing
478  const spacingValues = [];
479  const spacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*(\d+)px/gi;
480  let sm;
481  while ((sm = spacingRe.exec(html)) !== null) {
482    const v = parseInt(sm[1], 10);
483    if (v > 0 && v < 200) spacingValues.push(v);
484  }
485  const gapRe = /gap\s*:\s*(\d+)px/gi;
486  while ((sm = gapRe.exec(html)) !== null) {
487    spacingValues.push(parseInt(sm[1], 10));
488  }
489  const twSpaceRe = /\b(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-(\d+)\b/g;
490  while ((sm = twSpaceRe.exec(html)) !== null) {
491    spacingValues.push(parseInt(sm[1], 10) * 4);
492  }
493  const remSpacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*([\d.]+)rem/gi;
494  while ((sm = remSpacingRe.exec(html)) !== null) {
495    const v = Math.round(parseFloat(sm[1]) * 16);
496    if (v > 0 && v < 200) spacingValues.push(v);
497  }
498  const roundedSpacing = spacingValues.map(v => Math.round(v / 4) * 4);
499  if (roundedSpacing.length >= 10) {
500    const counts = {};
501    for (const v of roundedSpacing) counts[v] = (counts[v] || 0) + 1;
502    const maxCount = Math.max(...Object.values(counts));
503    const dominantPct = maxCount / roundedSpacing.length;
504    const unique = [...new Set(roundedSpacing)].filter(v => v > 0);
505    if (dominantPct > 0.6 && unique.length <= 3) {
506      const dominant = Object.entries(counts).sort((a, b) => b[1] - a[1])[0][0];
507      findings.push({
508        id: 'monotonous-spacing',
509        snippet: `~${dominant}px used ${maxCount}/${roundedSpacing.length} times (${Math.round(dominantPct * 100)}%)`,
510      });
511    }
512  }
513 
514  // --- Motion ---
515 
516  // Bounce/elastic animation names
517  const bounceRe = /animation(?:-name)?\s*:\s*([^;{}]*(?:bounce|elastic|wobble|jiggle|spring)[^;{}]*)/gi;
518  const bounceMatch = bounceRe.exec(html);
519  if (bounceMatch) {
520    const animationToken = bounceMatch[1]
521      .split(/[,\s]+/)
522      .find((part) => /bounce|elastic|wobble|jiggle|spring/i.test(part));
523    findings.push({ id: 'bounce-easing', snippet: `animation: ${animationToken || bounceMatch[1].trim()}` });
524  }
525 
526  // Overshoot cubic-bezier
527  const bezierRe = /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g;
528  let bm;
529  while ((bm = bezierRe.exec(html)) !== null) {
530    const y1 = parseFloat(bm[2]), y2 = parseFloat(bm[4]);
531    if (y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1) {
532      findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${bm[1]}, ${bm[2]}, ${bm[3]}, ${bm[4]})` });
533      break;
534    }
535  }
536 
537  // Layout property transitions
538  const transRe = /transition(?:-property)?\s*:\s*([^;{}]+)/gi;
539  let tm;
540  while ((tm = transRe.exec(html)) !== null) {
541    const val = tm[1].toLowerCase();
542    if (/\ball\b/.test(val)) continue;
543    const found = val.match(/\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding(?:-(?:top|right|bottom|left))?\b|\bmargin(?:-(?:top|right|bottom|left))?\b/gi);
544    if (found) {
545      findings.push({ id: 'layout-transition', snippet: `transition: ${found.join(', ')}` });
546      break;
547    }
548  }
549 
550  // --- Dark glow ---
551 
552  const darkBgRe = /background(?:-color)?\s*:\s*(?:#(?:0[0-9a-f]|1[0-9a-f]|2[0-3])[0-9a-f]{4}\b|#(?:0|1)[0-9a-f]{2}\b|rgb\(\s*(\d{1,2})\s*,\s*(\d{1,2})\s*,\s*(\d{1,2})\s*\))/gi;
553  const twDarkBg = /\bbg-(?:gray|slate|zinc|neutral|stone)-(?:9\d{2}|800)\b/;
554  if (darkBgRe.test(html) || twDarkBg.test(html)) {
555    const shadowRe = /box-shadow\s*:\s*([^;{}]+)/gi;
556    let shm;
557    while ((shm = shadowRe.exec(html)) !== null) {
558      const val = shm[1];
559      const colorMatch = val.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
560      if (!colorMatch) continue;
561      const [r, g, b] = [+colorMatch[1], +colorMatch[2], +colorMatch[3]];
562      if ((Math.max(r, g, b) - Math.min(r, g, b)) < 30) continue;
563      const pxVals = [...val.matchAll(/(\d+)px|(?<![.\d])\b(0)\b(?![.\d])/g)].map(p => +(p[1] || p[2]));
564      if (pxVals.length >= 3 && pxVals[2] > 4) {
565        findings.push({ id: 'dark-glow', snippet: `Colored glow (rgb(${r},${g},${b})) on dark page` });
566        break;
567      }
568    }
569  }
570 
571  // --- Provider tells (gated): repeating-gradient stripes (GPT) ---
572  if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(html)) {
573    findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
574  }
575 
576  // --- Provider tells (gated): "X theater" framing copy (GPT) ---
577  // Lives here (regex-on-HTML) rather than in the text-content analyzers so it
578  // runs in the bundled browser path too, not just the CLI/static path.
579  {
580    const bodyText = html
581      .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ')
582      .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ')
583      .replace(/<[^>]+>/g, ' ');
584    const tm = /\b(\w+)\s+theater\b/i.exec(bodyText);
585    if (tm) findings.push({ id: 'theater-slop-phrase', snippet: `"${tm[0].trim()}"` });
586  }
587 
588  // --- Provider tells (gated): image hover transform (Gemini) ---
589  // A CSS `img...:hover { transform: ... }` rule, or a Tailwind hover:scale /
590  // hover:rotate / hover:translate utility on an <img>. Each distinct
591  // mechanism is its own finding.
592  const imgHoverCss = /\bimg\b[^,{}]*:hover\b[^{}]*\{[^}]*\btransform\s*:\s*(?:scale|rotate|translate|matrix|skew)/i;
593  if (imgHoverCss.test(html)) {
594    findings.push({ id: 'image-hover-transform', snippet: 'img:hover { transform } rule' });
595  }
596  const imgTagRe = /<img\b[^>]*\bclass\s*=\s*"([^"]*)"/gi;
597  let im;
598  while ((im = imgTagRe.exec(html)) !== null) {
599    if (/\bhover:(?:scale|rotate|translate|skew)-/.test(im[1])) {
600      findings.push({ id: 'image-hover-transform', snippet: 'Tailwind hover transform on <img>' });
601    }
602  }
603 
604  return findings;
605}
606 
607// ─── Section 4: resolveBackground (unified) ─────────────────────────────────
608 
609// Read the element's own background color, computed-style first, with a
610// jsdom-friendly fallback that parses the inline `background:` shorthand
611// from the raw style attribute. jsdom (~v29) does not decompose the
612// shorthand into `backgroundColor`, so without this fallback the CLI silently
613// returns null for any element styled via `background: rgb(...)` or
614// `background: #abc`. Real browsers always decompose, so the fallback is
615// a no-op there.
616function readOwnBackgroundColor(el, computedStyle) {
617  const bg = parseRgb(computedStyle.backgroundColor);
618  if (DETECTOR_IS_BROWSER || (bg && bg.a >= 0.1)) return bg;
619  const rawStyle = el.getAttribute?.('style') || '';
620  const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
621  const inlineBg = bgMatch ? bgMatch[1].trim() : '';
622  if (!inlineBg) return bg;
623  if (/gradient/i.test(inlineBg) || /url\s*\(/i.test(inlineBg)) return bg;
624  const fromRgb = parseRgb(inlineBg);
625  if (fromRgb) return fromRgb;
626  const hexMatch = inlineBg.match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i);
627  if (hexMatch) {
628    const h = hexMatch[1];
629    if (h.length === 6) {
630      return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16), a: 1 };
631    }
632    return { r: parseInt(h[0] + h[0], 16), g: parseInt(h[1] + h[1], 16), b: parseInt(h[2] + h[2], 16), a: 1 };
633  }
634  return bg;
635}
636 
637function resolveBackground(el, win, customPropMap) {
638  let current = el;
639  while (current && current.nodeType === 1) {
640    const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
641    const bgImage = style.backgroundImage || '';
642    const hasGradientOrUrl = bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage));
643 
644    // Try the solid bg-color FIRST. If the element has both a solid color
645    // and a gradient/url overlay (a common pattern: `background: var(--paper)
646    // radial-gradient(...)` for paper-grain texture), the solid color is the
647    // dominant visible surface for contrast purposes; the overlay is
648    // decorative. The old behavior bailed on any gradient ancestor, which
649    // caused massive false-positive contrast findings on grain-textured
650    // body backgrounds.
651    let bg = parseRgb(style.backgroundColor);
652    if (!DETECTOR_IS_BROWSER && (!bg || bg.a < 0.1)) {
653      // jsdom returns literal "var(--X)" / "oklch(...)" strings. Resolve
654      // through customPropMap so Tailwind v4 color tokens become RGB.
655      if (customPropMap) {
656        bg = parseColorResolved(style.backgroundColor, customPropMap);
657      }
658      if (!bg || bg.a < 0.1) {
659        // Inline-style fallback. jsdom doesn't decompose background
660        // shorthand, so colors set via inline style are otherwise invisible.
661        const rawStyle = current.getAttribute?.('style') || '';
662        const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
663        const inlineBg = bgMatch ? bgMatch[1].trim() : '';
664        if (inlineBg && !/gradient/i.test(inlineBg) && !/url\s*\(/i.test(inlineBg)) {
665          bg = parseColorResolved(inlineBg, customPropMap) || parseAnyColor(inlineBg);
666        }
667      }
668    }
669 
670    if (bg && bg.a > 0.1) {
671      if (DETECTOR_IS_BROWSER || bg.a >= 0.5) return bg;
672    }
673    // No solid bg-color at this level. If THIS level has a gradient/url
674    // with no underlying solid color we can read:
675    //   • on body/html: assume white. Body-level gradients are almost
676    //     always decorative texture (paper grain, noise) on top of a
677    //     solid bg-color the page set via `background: var(--paper)`
678    //     shorthand — which jsdom can't decompose into bg-color. The
679    //     downstream gradient-stops fallback path produces catastrophic
680    //     false positives in this case (gradient noise stops have
681    //     accidental browns/blacks that look like card backgrounds).
682    //   • on other elements: bail to null and let the caller fall back
683    //     to gradient stops (gradient buttons / hero sections are real
684    //     bgs worth checking against).
685    if (hasGradientOrUrl) {
686      if (current.tagName === 'BODY' || current.tagName === 'HTML') {
687        return { r: 255, g: 255, b: 255, a: 1 };
688      }
689      return null;
690    }
691    current = current.parentElement;
692  }
693  return { r: 255, g: 255, b: 255 };
694}
695 
696// Walk parents looking for a gradient background and return its color stops.
697// Used as a fallback when resolveBackground() returns null because the
698// effective background is a gradient (no single solid color to compare against).
699function resolveGradientStops(el, win) {
700  let current = el;
701  while (current && current.nodeType === 1) {
702    const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
703    const bgImage = style.backgroundImage || '';
704    if (bgImage && bgImage !== 'none' && /gradient/i.test(bgImage)) {
705      const stops = parseGradientColors(bgImage);
706      if (stops.length > 0) return stops;
707    }
708    if (!DETECTOR_IS_BROWSER) {
709      // jsdom doesn't decompose `background:` shorthand — peek at the raw inline style
710      const rawStyle = current.getAttribute?.('style') || '';
711      const bgMatch = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
712      if (bgMatch && /gradient/i.test(bgMatch[1])) {
713        const stops = parseGradientColors(bgMatch[1]);
714        if (stops.length > 0) return stops;
715      }
716    }
717    current = current.parentElement;
718  }
719  return null;
720}
721 
722// Parse a single CSS length token to pixels. Accepts "12px", "50%", a
723// shorthand like "12px 4px" (uses the first value), or empty / null.
724// Returns the pixel value, or null when the input is unparseable.
725// Percentages convert against `widthPx` when one is supplied. Without a
726// usable width (jsdom returns "auto" for many real-world elements,
727// which parseFloat collapses to 0), fall back to the raw percentage
728// number so callers gating on `> 0` (border-accent-on-rounded,
729// isCardLike's hasRadius) still see a positive value, matching the
730// original parseFloat("50%") === 50 behavior.
731function parseRadiusToPx(value, widthPx) {
732  if (!value || typeof value !== 'string') return null;
733  const trimmed = value.trim();
734  if (!trimmed) return null;
735  const first = trimmed.split(/\s+/)[0];
736  const num = parseFloat(first);
737  if (Number.isNaN(num)) return null;
738  if (/%$/.test(first)) {
739    if (widthPx && widthPx > 0) return (num / 100) * widthPx;
740    return num;
741  }
742  return num;
743}
744 
745function resolveBorderRadiusPx(el, style, widthPx, win) {
746  const fromComputed = parseRadiusToPx(style.borderRadius, widthPx);
747  if (fromComputed !== null) return fromComputed;
748  return 0;
749}
750 
751// ─── Section 5: Element Adapters ────────────────────────────────────────────
752 
753// Browser adapters — call getComputedStyle/getBoundingClientRect on live DOM
754 
755function checkElementBordersDOM(el) {
756  const tag = el.tagName.toLowerCase();
757  if (BORDER_SAFE_TAGS.has(tag)) return [];
758  const rect = el.getBoundingClientRect();
759  if (rect.width < 20 || rect.height < 20) return [];
760  const style = getComputedStyle(el);
761  const sides = ['Top', 'Right', 'Bottom', 'Left'];
762  const widths = {}, colors = {};
763  for (const s of sides) {
764    widths[s] = parseFloat(style[`border${s}Width`]) || 0;
765    colors[s] = style[`border${s}Color`] || '';
766  }
767  return checkBorders(tag, widths, colors, parseFloat(style.borderRadius) || 0);
768}
769 
770function checkElementColorsDOM(el) {
771  const tag = el.tagName.toLowerCase();
772  // No early SAFE_TAGS bail here — checkColors() does its own gating that
773  // includes the styled-button exception for <a> / <button> with their own
774  // opaque background. Bailing here would prevent that exception from firing.
775  const rect = el.getBoundingClientRect();
776  if (rect.width < 10 || rect.height < 10) return [];
777  const style = getComputedStyle(el);
778  const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
779  const hasDirectText = directText.trim().length > 0;
780  const effectiveBg = resolveBackground(el);
781  return checkColors({
782    tag,
783    textColor: parseRgb(style.color),
784    bgColor: readOwnBackgroundColor(el, style),
785    effectiveBg,
786    effectiveBgStops: effectiveBg ? null : resolveGradientStops(el),
787    fontSize: parseFloat(style.fontSize) || 16,
788    fontWeight: parseInt(style.fontWeight) || 400,
789    hasDirectText,
790    isEmojiOnly: isEmojiOnlyText(directText),
791    bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
792    bgImage: style.backgroundImage || '',
793    classList: el.getAttribute('class') || '',
794  });
795}
796 
797function checkElementIconTileDOM(el) {
798  const tag = el.tagName.toLowerCase();
799  if (!HEADING_TAGS.has(tag)) return [];
800  const sibling = el.previousElementSibling;
801  if (!sibling) return [];
802 
803  const sibRect = sibling.getBoundingClientRect();
804  const headRect = el.getBoundingClientRect();
805  const sibStyle = getComputedStyle(sibling);
806 
807  // The tile may either contain an <svg>/<i> icon child, OR the tile itself
808  // may contain an emoji/symbol character directly as its only text content
809  // (the "card-icon" pattern from many AI-generated demos).
810  const iconChild = sibling.querySelector('svg, i[data-lucide], i[class*="fa-"], i[class*="icon"]');
811  const iconRect = iconChild?.getBoundingClientRect();
812  const sibDirectText = [...sibling.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
813  const hasInlineEmojiIcon = sibling.children.length === 0 && isEmojiOnlyText(sibDirectText);
814 
815  return checkIconTile({
816    headingTag: tag,
817    headingText: el.textContent || '',
818    headingTop: headRect.top,
819    siblingTag: sibling.tagName.toLowerCase(),
820    siblingWidth: sibRect.width,
821    siblingHeight: sibRect.height,
822    siblingBottom: sibRect.bottom,
823    siblingBgColor: parseRgb(sibStyle.backgroundColor),
824    siblingBgImage: sibStyle.backgroundImage || '',
825    siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
826    siblingBorderRadius: parseFloat(sibStyle.borderRadius) || 0,
827    hasIconChild: !!iconChild || hasInlineEmojiIcon,
828    iconChildWidth: iconRect?.width || 0,
829  });
830}
831 
832function checkElementItalicSerifDOM(el) {
833  const tag = el.tagName.toLowerCase();
834  if (tag !== 'h1' && tag !== 'h2') return [];
835  const style = getComputedStyle(el);
836  return checkItalicSerif({
837    tag,
838    fontStyle: style.fontStyle || '',
839    fontFamily: style.fontFamily || '',
840    fontSize: parseFloat(style.fontSize) || 0,
841    headingText: el.textContent || '',
842  });
843}
844 
845function checkElementHeroEyebrowDOM(el) {
846  const tag = el.tagName.toLowerCase();
847  if (tag !== 'h1') return [];
848  const sibling = el.previousElementSibling;
849  if (!sibling) return [];
850  const headStyle = getComputedStyle(el);
851  const sibStyle = getComputedStyle(sibling);
852  return checkHeroEyebrow({
853    headingTag: tag,
854    headingText: el.textContent || '',
855    headingFontSize: parseFloat(headStyle.fontSize) || 0,
856    siblingTag: sibling.tagName.toLowerCase(),
857    siblingText: sibling.textContent || '',
858    siblingTextTransform: sibStyle.textTransform || '',
859    siblingFontSize: parseFloat(sibStyle.fontSize) || 0,
860    siblingLetterSpacing: parseFloat(sibStyle.letterSpacing) || 0,
861    siblingFontWeight: sibStyle.fontWeight || '',
862    siblingColor: sibStyle.color || '',
863  });
864}
865 
866// Build a map of CSS custom properties declared on :root / :host / html.
867// Used to resolve var(--X) refs that jsdom returns verbatim in
868// getComputedStyle. Tailwind v4 routes every utility class through
869// CSS vars (font-weight: var(--font-weight-bold), font-size:
870// var(--text-xs), letter-spacing: var(--tracking-widest)), so without
871// resolution every style-based check silently fails on Tailwind v4
872// builds — the values come back as literal "var(--font-weight-bold)"
873// strings and parseFloat returns NaN.
874function buildCustomPropMap(document) {
875  const map = new Map();
876  let sheets;
877  try { sheets = Array.from(document.styleSheets || []); }
878  catch { return map; }
879  for (const sheet of sheets) {
880    let rules;
881    try { rules = Array.from(sheet.cssRules || []); }
882    catch { continue; }
883    for (const rule of rules) {
884      // Style rules only (type 1). Walk @media / @supports if present.
885      if (rule.type === 4 /* MEDIA_RULE */ || rule.type === 12 /* SUPPORTS_RULE */) {
886        try { rules.push(...Array.from(rule.cssRules || [])); } catch { /* ignore */ }
887        continue;
888      }
889      if (rule.type !== 1 /* STYLE_RULE */) continue;
890      const sel = rule.selectorText || '';
891      if (!/(^|,\s*)(:root|html|:host)\b/i.test(sel)) continue;
892      const style = rule.style;
893      if (!style) continue;
894      for (let i = 0; i < style.length; i++) {
895        const prop = style[i];
896        if (!prop || !prop.startsWith('--')) continue;
897        const val = style.getPropertyValue(prop).trim();
898        if (val) map.set(prop, val);
899      }
900    }
901  }
902  return map;
903}
904 
905// Resolve var(--X[, fallback]) refs in a computed-style value string.
906// Recurses up to 8 levels for chained refs (--a: var(--b)). Returns
907// the original string when no refs are present or the chain doesn't
908// resolve. Safe to call on already-resolved values.
909function resolveVarRefs(raw, customPropMap, depth = 0) {
910  if (typeof raw !== 'string' || !raw.includes('var(')) return raw;
911  if (depth > 8) return raw;
912  return raw.replace(/var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,\s*([^)]+))?\)/g, (_m, name, fallback) => {
913    const v = customPropMap.get(name);
914    if (v != null) return resolveVarRefs(v, customPropMap, depth + 1);
915    return fallback ? resolveVarRefs(fallback.trim(), customPropMap, depth + 1) : _m;
916  });
917}
918 
919// OKLCH → sRGB conversion (Björn Ottosson's matrices). L in 0..1 (or %),
920// C in 0..~0.4 typical, H in degrees. Returns clamped {r,g,b,a:1} in 0..255.
921// Needed because jsdom doesn't compute oklch() values — getComputedStyle
922// returns the literal "oklch(...)" string. Without this, the entire
923// Tailwind v4 color palette (which is OKLCH-based) is invisible to the
924// detector's contrast / color checks.
925function oklchToRgb(L, C, H) {
926  const hRad = (H * Math.PI) / 180;
927  const a = C * Math.cos(hRad);
928  const b = C * Math.sin(hRad);
929  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
930  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
931  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
932  const lc = l_ * l_ * l_, mc = m_ * m_ * m_, sc = s_ * s_ * s_;
933  const rLin =  4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc;
934  const gLin = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc;
935  const bLin = -0.0041960863 * lc - 0.7034186147 * mc + 1.7076147010 * sc;
936  const enc = (x) => {
937    const c = Math.max(0, Math.min(1, x));
938    return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
939  };
940  return {
941    r: Math.round(enc(rLin) * 255),
942    g: Math.round(enc(gLin) * 255),
943    b: Math.round(enc(bLin) * 255),
944    a: 1,
945  };
946}
947 
948// Extended color parser: rgb/rgba/hex/oklch. Returns null on no match.
949// Use this when the input might be any CSS color form; use plain parseRgb
950// when you only expect computed rgb() values from real browsers.
951function parseAnyColor(s) {
952  if (!s || typeof s !== 'string') return null;
953  const str = s.trim();
954  if (str === 'transparent' || str === 'currentcolor' || str === 'inherit') return null;
955  let m;
956  m = str.match(/rgba?\(\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)(?:\s*[,/]\s*([\d.]+))?\s*\)/);
957  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 };
958  m = str.match(/^#([0-9a-f]{3,8})$/i);
959  if (m) {
960    const h = m[1];
961    if (h.length === 3 || h.length === 4) {
962      return {
963        r: parseInt(h[0] + h[0], 16),
964        g: parseInt(h[1] + h[1], 16),
965        b: parseInt(h[2] + h[2], 16),
966        a: h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1,
967      };
968    }
969    if (h.length === 6 || h.length === 8) {
970      return {
971        r: parseInt(h.slice(0, 2), 16),
972        g: parseInt(h.slice(2, 4), 16),
973        b: parseInt(h.slice(4, 6), 16),
974        a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
975      };
976    }
977  }
978  // OKLCH parser. Tailwind v4's CSS minifier squishes the space after
979  // `%` ("21.5%.02 50"), so the separator between L and C may be absent.
980  // Match L (with optional %), then C and H separated permissively.
981  m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
982  if (m) {
983    const Lnum = parseFloat(m[1]);
984    const L = m[2] === '%' ? Lnum / 100 : Lnum;
985    const rgb = oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]));
986    if (m[5] !== undefined) {
987      const alpha = parseFloat(m[5]);
988      rgb.a = m[6] === '%' ? alpha / 100 : alpha;
989    }
990    return rgb;
991  }
992  return null;
993}
994 
995// Resolve var() refs in a color string (via customPropMap), then parse.
996// Returns null on any failure. Used in jsdom-mode paths where
997// getComputedStyle returns literal "var(--X)" or "oklch(...)" strings.
998function parseColorResolved(str, customPropMap) {
999  if (!str) return null;
1000  const resolved = customPropMap ? resolveVarRefs(str, customPropMap) : str;
1001  return parseAnyColor(resolved);
1002}
1003 
1004const REPEATED_KICKER_SKIP_SELECTOR = [
1005  'nav',
1006  'form',
1007  'table',
1008  'thead',
1009  'tbody',
1010  'tfoot',
1011  'figure',
1012  'figcaption',
1013  'ol',
1014  'ul',
1015  'li',
1016  '[role="navigation"]',
1017  '[aria-label*="breadcrumb" i]',
1018  '[class*="breadcrumb" i]',
1019  '[aria-hidden="true"]',
1020  '[data-impeccable-allow-kickers]',
1021].join(',');
1022 
1023const REPEATED_KICKER_CARD_CONTEXT_SELECTOR = [
1024  'article',
1025  'button',
1026  'a',
1027  'li',
1028  '[role="listitem"]',
1029  '[role="option"]',
1030].join(',');
1031 
1032function cleanInlineText(el) {
1033  return [...el.childNodes]
1034    .filter(n => n.nodeType === 3)
1035    .map(n => n.textContent)
1036    .join(' ')
1037    .replace(/\s+/g, ' ')
1038    .trim();
1039}
1040 
1041function isRepeatedKickerCardContext(heading, kicker) {
1042  const item = heading.closest?.(REPEATED_KICKER_CARD_CONTEXT_SELECTOR);
1043  return Boolean(item && (!item.contains || item.contains(kicker)));
1044}
1045 
1046function isRepeatedKickerCandidate(opts) {
1047  const {
1048    headingTag,
1049    headingText,
1050    headingFontSize,
1051    kickerTag,
1052    kickerText,
1053    kickerTextTransform,
1054    kickerFontSize,
1055    kickerLetterSpacing,
1056  } = opts;
1057  if (!['h2', 'h3', 'h4'].includes(headingTag)) return false;
1058  if (!headingText || headingText.length < 3) return false;
1059  if (/^\/[\w-]+/i.test(headingText.replace(/^"|"$/g, '').trim())) return false;
1060  if (!(headingFontSize >= 20)) return false;
1061  if (!kickerTag || HEADING_TAGS.has(kickerTag)) return false;
1062  if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false;
1063  if (!kickerText || kickerText.length < 2 || kickerText.length > 34) return false;
1064  if (/^step\s*\d+/i.test(kickerText) || /^\d{1,2}$/.test(kickerText)) return false;
1065 
1066  const isUppercased = kickerTextTransform === 'uppercase'
1067    || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText));
1068  if (!isUppercased) return false;
1069  if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false;
1070  const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08);
1071  if (!(kickerLetterSpacing >= minTrackedSpacing)) return false;
1072  return true;
1073}
1074 
1075function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpacing) {
1076  const candidates = [];
1077  for (const heading of doc.querySelectorAll('h2, h3, h4')) {
1078    if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
1079    const kicker = heading.previousElementSibling;
1080    if (!kicker || kicker.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
1081    if (isRepeatedKickerCardContext(heading, kicker)) continue;
1082 
1083    const headingStyle = getStyle(heading);
1084    const kickerStyle = getStyle(kicker);
1085    const headingText = (heading.textContent || '').replace(/\s+/g, ' ').trim();
1086    const kickerText = cleanInlineText(kicker) || (kicker.textContent || '').replace(/\s+/g, ' ').trim();
1087    const headingFontSize = resolveLetterSpacing(headingStyle.fontSize || '', 16) || parseFloat(headingStyle.fontSize) || 0;
1088    const kickerFontSize = resolveLetterSpacing(kickerStyle.fontSize || '', 16) || parseFloat(kickerStyle.fontSize) || 0;
1089    const kickerLetterSpacing = resolveLetterSpacing(kickerStyle.letterSpacing || '', kickerFontSize);
1090 
1091    if (!isRepeatedKickerCandidate({
1092      headingTag: heading.tagName.toLowerCase(),
1093      headingText,
1094      headingFontSize,
1095      kickerTag: kicker.tagName.toLowerCase(),
1096      kickerText,
1097      kickerTextTransform: kickerStyle.textTransform || '',
1098      kickerFontSize,
1099      kickerLetterSpacing,
1100    })) {
1101      continue;
1102    }
1103 
1104    candidates.push({
1105      headingTag: heading.tagName.toLowerCase(),
1106      headingText: headingText.replace(/^"|"$/g, '').slice(0, 60),
1107      kickerText: kickerText.slice(0, 40),
1108    });
1109  }
1110  return candidates;
1111}
1112 
1113function checkRepeatedSectionKickersDOM() {
1114  const candidates = collectRepeatedSectionKickerCandidates(
1115    document,
1116    (el) => getComputedStyle(el),
1117    (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
1118  );
1119  return checkRepeatedSectionKickers({ candidates });
1120}
1121 
1122function checkElementMotionDOM(el) {
1123  const tag = el.tagName.toLowerCase();
1124  if (SAFE_TAGS.has(tag)) return [];
1125  const style = getComputedStyle(el);
1126  return checkMotion({
1127    tag,
1128    transitionProperty: style.transitionProperty || '',
1129    animationName: style.animationName || '',
1130    timingFunctions: [style.animationTimingFunction, style.transitionTimingFunction].filter(Boolean).join(' '),
1131    classList: el.getAttribute('class') || '',
1132  });
1133}
1134 
1135function checkElementGlowDOM(el) {
1136  const tag = el.tagName.toLowerCase();
1137  const style = getComputedStyle(el);
1138  if (!style.boxShadow || style.boxShadow === 'none') return [];
1139  // Use parent's background — glow radiates outward, so the surrounding context matters
1140  // If resolveBackground returns null (gradient), try to infer from the gradient colors
1141  let parentBg = el.parentElement ? resolveBackground(el.parentElement) : resolveBackground(el);
1142  if (!parentBg) {
1143    // Gradient background — sample its colors to determine if it's dark
1144    let cur = el.parentElement;
1145    while (cur && cur.nodeType === 1) {
1146      const bgImage = getComputedStyle(cur).backgroundImage || '';
1147      const gradColors = parseGradientColors(bgImage);
1148      if (gradColors.length > 0) {
1149        // Average the gradient colors
1150        const avg = { r: 0, g: 0, b: 0 };
1151        for (const c of gradColors) { avg.r += c.r; avg.g += c.g; avg.b += c.b; }
1152        avg.r = Math.round(avg.r / gradColors.length);
1153        avg.g = Math.round(avg.g / gradColors.length);
1154        avg.b = Math.round(avg.b / gradColors.length);
1155        parentBg = avg;
1156        break;
1157      }
1158      cur = cur.parentElement;
1159    }
1160  }
1161  return checkGlow({ tag, boxShadow: style.boxShadow, effectiveBg: parentBg });
1162}
1163 
1164function checkElementAIPaletteDOM(el) {
1165  const style = getComputedStyle(el);
1166  const findings = [];
1167 
1168  // Check gradient backgrounds for purple/violet or cyan
1169  const bgImage = style.backgroundImage || '';
1170  const gradColors = parseGradientColors(bgImage);
1171  for (const c of gradColors) {
1172    if (hasChroma(c, 50)) {
1173      const hue = getHue(c);
1174      if (hue >= 260 && hue <= 310) {
1175        findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet gradient background' });
1176        break;
1177      }
1178      if (hue >= 160 && hue <= 200) {
1179        findings.push({ id: 'ai-color-palette', snippet: 'Cyan gradient background' });
1180        break;
1181      }
1182    }
1183  }
1184 
1185  // Check for neon text (vivid cyan/purple color on dark background)
1186  const textColor = parseRgb(style.color);
1187  if (textColor && hasChroma(textColor, 80)) {
1188    const hue = getHue(textColor);
1189    const isAIPalette = (hue >= 160 && hue <= 200) || (hue >= 260 && hue <= 310);
1190    if (isAIPalette) {
1191      const parentBg = el.parentElement ? resolveBackground(el.parentElement) : null;
1192      // Also check gradient parents
1193      let effectiveBg = parentBg;
1194      if (!effectiveBg) {
1195        let cur = el.parentElement;
1196        while (cur && cur.nodeType === 1) {
1197          const gi = getComputedStyle(cur).backgroundImage || '';
1198          const gc = parseGradientColors(gi);
1199          if (gc.length > 0) {
1200            const avg = { r: 0, g: 0, b: 0 };
1201            for (const c of gc) { avg.r += c.r; avg.g += c.g; avg.b += c.b; }
1202            avg.r = Math.round(avg.r / gc.length);
1203            avg.g = Math.round(avg.g / gc.length);
1204            avg.b = Math.round(avg.b / gc.length);
1205            effectiveBg = avg;
1206            break;
1207          }
1208          cur = cur.parentElement;
1209        }
1210      }
1211      if (effectiveBg && relativeLuminance(effectiveBg) < 0.1) {
1212        const label = hue >= 260 ? 'Purple/violet' : 'Cyan';
1213        findings.push({ id: 'ai-color-palette', snippet: `${label} neon text on dark background` });
1214      }
1215    }
1216  }
1217 
1218  return findings;
1219}
1220 
1221const QUALITY_TEXT_TAGS = new Set(['p', 'li', 'td', 'th', 'dd', 'blockquote', 'figcaption']);
1222 
1223// Resolve a CSS font-size value to pixels by walking up the parent chain.
1224// Browsers resolve em/rem/% to px in getComputedStyle, but jsdom returns the
1225// specified value verbatim — so for the Node path we walk parents ourselves.
1226function resolveFontSizePx(el, win) {
1227  const chain = []; // raw font-size strings, leaf → root
1228  let cur = el;
1229  while (cur && cur.nodeType === 1) {
1230    const fs = (win ? win.getComputedStyle(cur) : getComputedStyle(cur)).fontSize;
1231    chain.push(fs || '');
1232    cur = cur.parentElement;
1233  }
1234  // Walk root → leaf, resolving each value relative to its parent context.
1235  let px = 16; // root default
1236  for (let i = chain.length - 1; i >= 0; i--) {
1237    const v = chain[i];
1238    if (!v || v === 'inherit') continue;
1239    const num = parseFloat(v);
1240    if (isNaN(num)) continue;
1241    if (v.endsWith('px')) px = num;
1242    else if (v.endsWith('rem')) px = num * 16;
1243    else if (v.endsWith('em')) px = num * px;
1244    else if (v.endsWith('%')) px = (num / 100) * px;
1245    else px = num; // unitless — already resolved
1246  }
1247  return px;
1248}
1249 
1250// Resolve a CSS length value (line-height, letter-spacing, etc.) given a
1251// known font-size context. Returns null for "normal" / unparseable values.
1252function resolveLengthPx(value, fontSizePx) {
1253  if (!value || value === 'normal' || value === 'auto' || value === 'inherit') return null;
1254  const num = parseFloat(value);
1255  if (isNaN(num)) return null;
1256  if (value.endsWith('px')) return num;
1257  if (value.endsWith('rem')) return num * 16;
1258  if (value.endsWith('em')) return num * fontSizePx;
1259  if (value.endsWith('%')) return (num / 100) * fontSizePx;
1260  // Unitless line-height = multiplier, return px equivalent
1261  return num * fontSizePx;
1262}
1263 
1264function cssColorIsTransparent(value) {
1265  if (!value) return true;
1266  const str = String(value).trim().toLowerCase();
1267  if (!str || str === 'transparent' || str === 'rgba(0, 0, 0, 0)') return true;
1268  const parsed = parseAnyColor(str);
1269  if (parsed) return (parsed.a ?? 1) <= 0.05;
1270  return /^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*0(?:\.0+)?\s*\)$/.test(str);
1271}
1272 
1273function colorsNearlyMatch(a, b) {
1274  const ca = parseAnyColor(a);
1275  const cb = parseAnyColor(b);
1276  if (!ca || !cb) return false;
1277  const alphaDelta = Math.abs((ca.a ?? 1) - (cb.a ?? 1));
1278  const channelDelta = Math.max(
1279    Math.abs(ca.r - cb.r),
1280    Math.abs(ca.g - cb.g),
1281    Math.abs(ca.b - cb.b),
1282  );
1283  return alphaDelta <= 0.03 && channelDelta <= 3;
1284}
1285 
1286function getComputedStyleFor(win, el) {
1287  if (win && typeof win.getComputedStyle === 'function') {
1288    try { return win.getComputedStyle(el); } catch {}
1289  }
1290  if (typeof getComputedStyle === 'function') {
1291    try { return getComputedStyle(el); } catch {}
1292  }
1293  return null;
1294}
1295 
1296function hasVisibleBackgroundBoundary(style, el, win) {
1297  const bg = style?.backgroundColor || '';
1298  if (cssColorIsTransparent(bg)) return false;
1299 
1300  let parent = el?.parentElement || null;
1301  while (parent) {
1302    const parentStyle = getComputedStyleFor(win, parent);
1303    const parentBg = parentStyle?.backgroundColor || '';
1304    if (!cssColorIsTransparent(parentBg)) {
1305      return !colorsNearlyMatch(bg, parentBg);
1306    }
1307    parent = parent.parentElement;
1308  }
1309 
1310  return true;
1311}
1312 
1313const TEXT_EDGE_TAGS = new Set(['A', 'BUTTON', 'CODE', 'DD', 'DT', 'FIGCAPTION', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'LI', 'P', 'PRE', 'SPAN', 'TD', 'TH']);
1314 
1315function hasMeaningfulDirectText(node) {
1316  if (!node?.childNodes) return false;
1317  for (const child of node.childNodes) {
1318    if (child.nodeType === 3 && child.textContent.trim().length > 4) return true;
1319  }
1320  return false;
1321}
1322 
1323function textDescendantsFlushSides(el, rect) {
1324  const flush = { top: false, right: false, bottom: false, left: false };
1325  if (!rect || !el?.querySelectorAll) return flush;
1326  const TEXT_EDGE_THRESHOLD = 4;
1327  const candidates = el.querySelectorAll('a, button, code, dd, dt, figcaption, h1, h2, h3, h4, h5, h6, li, p, pre, span, td, th');
1328  for (const node of candidates) {
1329    if (!TEXT_EDGE_TAGS.has(node.tagName) || !hasMeaningfulDirectText(node)) continue;
1330    let nodeRect = null;
1331    try { nodeRect = node.getBoundingClientRect(); } catch {}
1332    if (!nodeRect || nodeRect.width <= 0 || nodeRect.height <= 0) continue;
1333    if (nodeRect.bottom < rect.top || nodeRect.top > rect.bottom || nodeRect.right < rect.left || nodeRect.left > rect.right) continue;
1334    if (nodeRect.top - rect.top <= TEXT_EDGE_THRESHOLD) flush.top = true;
1335    if (rect.right - nodeRect.right <= TEXT_EDGE_THRESHOLD) flush.right = true;
1336    if (rect.bottom - nodeRect.bottom <= TEXT_EDGE_THRESHOLD) flush.bottom = true;
1337    if (nodeRect.left - rect.left <= TEXT_EDGE_THRESHOLD) flush.left = true;
1338  }
1339  return flush;
1340}
1341 
1342// Pure quality checks. Most run on computed CSS and DOM-only inputs (work in
1343// jsdom and the browser). Two checks (line-length, cramped-padding) gate on
1344// element rect dimensions, which jsdom can't compute — pass `rect: null` from
1345// the Node adapter to skip those.
1346//
1347// Both adapters resolve font-size, line-height and letter-spacing to pixels
1348// before calling this so the pure function only deals with numbers.
1349function checkQuality(opts) {
1350  const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0, win = null } = opts;
1351  const findings = [];
1352  // Skip browser extension injected elements
1353  const elId = el.id || '';
1354  if (elId.startsWith('claude-') || elId.startsWith('cic-')) return findings;
1355 
1356  // --- Line length too long --- (browser-only: needs rect.width)
1357  if (rect && hasDirectText && QUALITY_TEXT_TAGS.has(tag) && rect.width > 0 && textLen > lineMax) {
1358    const charsPerLine = rect.width / (fontSize * 0.5);
1359    if (charsPerLine > lineMax + 5) {
1360      findings.push({ id: 'line-length', snippet: `~${Math.round(charsPerLine)} chars/line (aim for <${lineMax})` });
1361    }
1362  }
1363 
1364  // --- Cramped padding --- (browser-only: needs rect to skip small badges/labels)
1365  // Vertical and horizontal thresholds are independent because line-height
1366  // already provides built-in vertical breathing room (the line box is taller
1367  // than the cap height), but horizontal has no equivalent. Both scale with
1368  // font-size — bigger text demands proportionally more padding.
1369  //   vertical:   max(4px, fontSize × 0.3)
1370  //   horizontal: max(8px, fontSize × 0.5)
1371  const isInlineCode = tag === 'code' && !(el.closest && el.closest('pre'));
1372  if (!isInlineCode && rect && hasDirectText && textLen > 20 && rect.width > 100 && rect.height > 30) {
1373    const borders = {
1374      top: parseFloat(style.borderTopWidth) || 0,
1375      right: parseFloat(style.borderRightWidth) || 0,
1376      bottom: parseFloat(style.borderBottomWidth) || 0,
1377      left: parseFloat(style.borderLeftWidth) || 0,
1378    };
1379    const borderCount = Object.values(borders).filter(w => w > 0).length;
1380    const hasBg = hasVisibleBackgroundBoundary(style, el, win);
1381    if (borderCount >= 2 || hasBg) {
1382      const vPads = [], hPads = [];
1383      if (hasBg || borders.top > 0) vPads.push(parseFloat(style.paddingTop) || 0);
1384      if (hasBg || borders.bottom > 0) vPads.push(parseFloat(style.paddingBottom) || 0);
1385      if (hasBg || borders.left > 0) hPads.push(parseFloat(style.paddingLeft) || 0);
1386      if (hasBg || borders.right > 0) hPads.push(parseFloat(style.paddingRight) || 0);
1387 
1388      const vMin = vPads.length ? Math.min(...vPads) : Infinity;
1389      const hMin = hPads.length ? Math.min(...hPads) : Infinity;
1390      const vThresh = Math.max(4, fontSize * 0.3);
1391      const hThresh = Math.max(8, fontSize * 0.5);
1392 
1393      // Emit at most one finding per element — pick whichever axis is worse.
1394      if (vMin < vThresh) {
1395        findings.push({ id: 'cramped-padding', snippet: `${vMin}px vertical padding (need ≥${vThresh.toFixed(1)}px for ${fontSize}px text)` });
1396      } else if (hMin < hThresh) {
1397        findings.push({ id: 'cramped-padding', snippet: `${hMin}px horizontal padding (need ≥${hThresh.toFixed(1)}px for ${fontSize}px text)` });
1398      }
1399    }
1400  }
1401 
1402  // --- Flush against a visible boundary ---
1403  // Fires when a container has a visible boundary (border, outline, OR a
1404  // non-transparent background) AND near-zero padding on the bounded
1405  // side(s) AND text-bearing children land flush against the boundary.
1406  //
1407  // Distinct from cramped-padding: that rule needs the element itself to
1408  // have direct text (hasDirectText). This rule targets the OPPOSITE
1409  // shape — a container with NO direct text, only children — which is
1410  // exactly what cramped-padding misses (a section wrapping a label +
1411  // list lands a free pass).
1412  //
1413  // The classic shape: agent writes `padding: 28px 0 0` shorthand on a
1414  // section that also has a border, zeroing horizontal padding so the
1415  // text-bearing children touch the side borders. Background and
1416  // outline count too: a colored card with zero padding has the same
1417  // visual failure mode.
1418  {
1419    const FLUSH_SKIP_TAGS = new Set(['HTML', 'BODY', 'MAIN', 'HEADER', 'FOOTER', 'NAV', 'ARTICLE', 'ASIDE', 'BUTTON', 'A', 'LABEL', 'SUMMARY', 'CODE', 'PRE', 'INPUT', 'TEXTAREA', 'SELECT', 'FORM', 'FIGURE', 'TABLE', 'TBODY', 'THEAD', 'TR', 'TD', 'TH']);
1420    const upperTag = tag ? tag.toUpperCase() : '';
1421    const elPosition = style.position || '';
1422    if (
1423      !FLUSH_SKIP_TAGS.has(upperTag) &&
1424      !hasDirectText &&
1425      !['fixed', 'absolute'].includes(elPosition) &&
1426      el.children && el.children.length > 0
1427    ) {
1428      const borderW = {
1429        top:    parseFloat(style.borderTopWidth)    || 0,
1430        right:  parseFloat(style.borderRightWidth)  || 0,
1431        bottom: parseFloat(style.borderBottomWidth) || 0,
1432        left:   parseFloat(style.borderLeftWidth)   || 0,
1433      };
1434      const borderVisible = {
1435        top:    borderW.top    > 0 && !cssColorIsTransparent(style.borderTopColor),
1436        right:  borderW.right  > 0 && !cssColorIsTransparent(style.borderRightColor),
1437        bottom: borderW.bottom > 0 && !cssColorIsTransparent(style.borderBottomColor),
1438        left:   borderW.left   > 0 && !cssColorIsTransparent(style.borderLeftColor),
1439      };
1440      // Outline detection. jsdom decomposes `border` shorthand into
1441      // border{Top,…}Width/Color but does NOT decompose `outline` —
1442      // the longhands come back empty when the value was set via the
1443      // shorthand. Fall back to parsing `style.outline` ourselves.
1444      let outlineW = parseFloat(style.outlineWidth) || 0;
1445      let outlineStyleVal = style.outlineStyle || '';
1446      let outlineColorVal = style.outlineColor || '';
1447      if (!outlineW && style.outline) {
1448        const wMatch = style.outline.match(/(\d+(?:\.\d+)?)\s*px/);
1449        if (wMatch) outlineW = parseFloat(wMatch[1]) || 0;
1450        if (!outlineStyleVal) {
1451          outlineStyleVal = /\b(solid|dashed|dotted|double|groove|ridge|inset|outset)\b/.test(style.outline) ? 'solid' : '';
1452        }
1453        if (!outlineColorVal) {
1454          const cMatch = style.outline.match(/(rgba?\([^)]+\)|#[0-9a-fA-F]{3,8}|[a-zA-Z]+)\s*$/);
1455          if (cMatch) outlineColorVal = cMatch[1];
1456        }
1457      }
1458      const outlineVisible = outlineW > 0 && !cssColorIsTransparent(outlineColorVal) && outlineStyleVal && outlineStyleVal !== 'none';
1459      const bgVisible = hasVisibleBackgroundBoundary(style, el, win);
1460 
1461      const anyVisible = borderVisible.top || borderVisible.right || borderVisible.bottom || borderVisible.left || outlineVisible || bgVisible;
1462      if (anyVisible) {
1463        // Resolve padding to px (jsdom returns raw "1.5rem" etc., not the
1464        // computed px value; parseFloat would strip the unit and treat
1465        // 1.5rem as 1.5px, false-flagging legitimate insets).
1466        const pad = {
1467          top:    resolveLengthPx(style.paddingTop,    fontSize) ?? 0,
1468          right:  resolveLengthPx(style.paddingRight,  fontSize) ?? 0,
1469          bottom: resolveLengthPx(style.paddingBottom, fontSize) ?? 0,
1470          left:   resolveLengthPx(style.paddingLeft,   fontSize) ?? 0,
1471        };
1472        const PAD_THRESHOLD = 2;
1473        // Children-insulate-this-side: a side is insulated if ANY direct
1474        // child has its own padding ≥ 4px on that side. Rationale: in
1475        // typical flow, only the first/last (or leftmost/rightmost)
1476        // children actually sit at the parent's edges. If even one of
1477        // them has its own padding, the visual flush is broken on that
1478        // side. Classic example: a column-flow card frame where the
1479        // top child (header) has padding-top:12 and the bottom child
1480        // (footer) has padding-bottom:8 — the parent's padding:0 doesn't
1481        // matter; nothing is actually flush. The `any-child-insulates`
1482        // heuristic accepts some false negatives (a card with one heavily
1483        // padded middle child won't flag) for far fewer false positives.
1484        const CHILD_INSULATE_THRESHOLD = 4;
1485        const childrenInsulate = { top: false, right: false, bottom: false, left: false };
1486        for (const child of el.children) {
1487          let childStyle = getComputedStyleFor(win, child);
1488          if (!childStyle) continue;
1489          const childPad = {
1490            top:    resolveLengthPx(childStyle.paddingTop,    fontSize) ?? 0,
1491            right:  resolveLengthPx(childStyle.paddingRight,  fontSize) ?? 0,
1492            bottom: resolveLengthPx(childStyle.paddingBottom, fontSize) ?? 0,
1493            left:   resolveLengthPx(childStyle.paddingLeft,   fontSize) ?? 0,
1494          };
1495          const childMargin = {
1496            top:    resolveLengthPx(childStyle.marginTop,    fontSize) ?? 0,
1497            right:  resolveLengthPx(childStyle.marginRight,  fontSize) ?? 0,
1498            bottom: resolveLengthPx(childStyle.marginBottom, fontSize) ?? 0,
1499            left:   resolveLengthPx(childStyle.marginLeft,   fontSize) ?? 0,
1500          };
1501          if (rect && typeof child.getBoundingClientRect === 'function') {
1502            try {
1503              const childRect = child.getBoundingClientRect();
1504              if (childRect && childRect.width > 0 && childRect.height > 0) {
1505                if (childRect.top - rect.top >= CHILD_INSULATE_THRESHOLD) childrenInsulate.top = true;
1506                if (rect.right - childRect.right >= CHILD_INSULATE_THRESHOLD) childrenInsulate.right = true;
1507                if (rect.bottom - childRect.bottom >= CHILD_INSULATE_THRESHOLD) childrenInsulate.bottom = true;
1508                if (childRect.left - rect.left >= CHILD_INSULATE_THRESHOLD) childrenInsulate.left = true;
1509              }
1510            } catch {}
1511          }
1512          for (const s of ['top', 'right', 'bottom', 'left']) {
1513            if (childPad[s] >= CHILD_INSULATE_THRESHOLD || childMargin[s] >= CHILD_INSULATE_THRESHOLD) {
1514              childrenInsulate[s] = true;
1515            }
1516          }
1517        }
1518 
1519        const textFlush = rect ? textDescendantsFlushSides(el, rect) : null;
1520        const fullBleedBgBand = rect && viewportWidth > 0 && rect.width >= viewportWidth * 0.94 && bgVisible && !outlineVisible;
1521        const flushSides = [];
1522        for (const side of ['top', 'right', 'bottom', 'left']) {
1523          const bgBoundsSide = bgVisible && !(fullBleedBgBand && (side === 'left' || side === 'right'));
1524          const sideBounded = borderVisible[side] || outlineVisible || bgBoundsSide;
1525          if (sideBounded && pad[side] <= PAD_THRESHOLD && !childrenInsulate[side] && (!textFlush || textFlush[side])) {
1526            flushSides.push(side);
1527          }
1528        }
1529 
1530        if (flushSides.length > 0) {
1531          // Confirm at least one direct child has substantial text content
1532          // (> 4 chars). Without this, the flush is harmless: e.g. an
1533          // image-only card.
1534          let hasTextChild = false;
1535          for (const child of el.children) {
1536            const childText = (child.textContent || '').trim();
1537            if (childText.length > 4) { hasTextChild = true; break; }
1538          }
1539          if (hasTextChild) {
1540            const cls = (typeof el.className === 'string' && el.className.trim())
1541              ? el.className.trim().split(/\s+/)[0]
1542              : '';
1543            const boundaryParts = [];
1544            const borderSidesVisible = ['top', 'right', 'bottom', 'left'].filter(s => borderVisible[s]);
1545            if (borderSidesVisible.length === 4) boundaryParts.push('border');
1546            else if (borderSidesVisible.length > 0) boundaryParts.push(`border-${borderSidesVisible.join('/')}`);
1547            if (outlineVisible) boundaryParts.push('outline');
1548            if (bgVisible) boundaryParts.push('bg');
1549            const sidesLabel = flushSides.length === 4 ? 'all sides' : flushSides.join('/');
1550            const ident = cls
1551              ? `<${tag.toLowerCase()}> "${cls}"`
1552              : `<${tag.toLowerCase()}>`;
1553            findings.push({
1554              id: 'cramped-padding',
1555              snippet: `${ident}: children flush against ${boundaryParts.join('+')} on ${sidesLabel} (no inset)`,
1556            });
1557          }
1558        }
1559      }
1560    }
1561  }
1562 
1563  // --- Body text touching viewport edge --- (browser-only: needs rect)
1564  // Catches the failure mode where the agent ships body paragraphs
1565  // with NO container providing horizontal padding — text bleeds
1566  // directly to the viewport edge. Different from cramped-padding,
1567  // which requires a colored/bordered container. Here the failure
1568  // is the absence of the container entirely.
1569  //
1570  // Gate aggressively to avoid false positives:
1571  //   - <p> or <li> only (body content; not headings, not nav, not
1572  //     wrappers)
1573  //   - text > 40 chars (paragraph-like, not a label)
1574  //   - rect.width > 50% of viewport (real body, not a pull-quote)
1575  //   - rect.left < 16 OR rect.right > viewport - 16 (actually
1576  //     touching the edge)
1577  //   - not inside <nav> or <header> (those legitimately bleed)
1578  //   - element itself has no background-color (intentional full-bleed
1579  //     sections set a bg-color and provide their own internal padding)
1580  if (rect && hasDirectText && textLen > 40 && ['P', 'LI'].includes(tag.toUpperCase()) && viewportWidth > 0) {
1581    const inNavHeader = el.closest && (el.closest('nav') || el.closest('header'));
1582    const hasOwnBg = style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)' && style.backgroundColor !== 'transparent';
1583    const isPositioned = ['fixed', 'absolute'].includes(style.position || '');
1584    const widthRatio = rect.width / viewportWidth;
1585    const leftClose = rect.left < 16;
1586    const rightClose = rect.right > viewportWidth - 16;
1587    if (!inNavHeader && !hasOwnBg && !isPositioned && widthRatio > 0.5 && (leftClose || rightClose)) {
1588      const which = leftClose && rightClose
1589        ? `left ${Math.round(rect.left)}px / right ${Math.round(viewportWidth - rect.right)}px`
1590        : leftClose
1591          ? `left ${Math.round(rect.left)}px`
1592          : `right ${Math.round(viewportWidth - rect.right)}px`;
1593      findings.push({ id: 'body-text-viewport-edge', snippet: `<${tag.toLowerCase()}> with ${textLen}-char body bleeds to viewport edge (${which})` });
1594    }
1595  }
1596 
1597  // --- Tight line height ---
1598  if (hasDirectText && textLen > 50 && !['h1','h2','h3','h4','h5','h6'].includes(tag)) {
1599    if (lineHeightPx != null && fontSize > 0) {
1600      const ratio = lineHeightPx / fontSize;
1601      if (ratio > 0 && ratio < 1.3) {
1602        findings.push({ id: 'tight-leading', snippet: `line-height ${ratio.toFixed(2)}x (need >=1.3)` });
1603      }
1604    }
1605  }
1606 
1607  // --- Justified text (without hyphens) ---
1608  if (hasDirectText && style.textAlign === 'justify') {
1609    const hyphens = style.hyphens || style.webkitHyphens || '';
1610    if (hyphens !== 'auto') {
1611      findings.push({ id: 'justified-text', snippet: 'text-align: justify without hyphens: auto' });
1612    }
1613  }
1614 
1615  // --- Tiny body text ---
1616  // Only flag actual body content, not UI labels (buttons, tabs, badges, captions, footer text, etc.)
1617  if (hasDirectText && textLen > 20 && fontSize < 12) {
1618    const skipTags = ['sub', 'sup', 'code', 'kbd', 'samp', 'var', 'caption', 'figcaption'];
1619    const inUIContext = el.closest && el.closest('button, a, label, summary, pre, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="option"], nav, footer, [aria-hidden="true"], [class*="badge" i], [class*="caption" i], [class*="chip" i], [class*="code" i], [class*="console" i], [class*="diff" i], [class*="label" i], [class*="meta" i], [class*="mock" i], [class*="pill" i], [class*="preview" i], [class*="tag" i], [class*="terminal" i], [class*="writes" i]');
1620    const isUppercase = style.textTransform === 'uppercase';
1621    if (!skipTags.includes(tag) && !inUIContext && !isUppercase) {
1622      findings.push({ id: 'tiny-text', snippet: `${fontSize}px body text` });
1623    }
1624  }
1625 
1626  // --- All-caps body text ---
1627  if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
1628    if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
1629      findings.push({ id: 'all-caps-body', snippet: `text-transform: uppercase on ${textLen} chars of body text` });
1630    }
1631  }
1632 
1633  // --- Wide letter spacing on body text ---
1634  if (hasDirectText && textLen > 20 && style.textTransform !== 'uppercase') {
1635    if (letterSpacingPx != null && letterSpacingPx > 0 && fontSize > 0) {
1636      const trackingEm = letterSpacingPx / fontSize;
1637      if (trackingEm > 0.05) {
1638        findings.push({ id: 'wide-tracking', snippet: `letter-spacing: ${trackingEm.toFixed(2)}em on body text` });
1639      }
1640    }
1641  }
1642 
1643  // --- Crushed letter spacing (mirror of wide-tracking) ---
1644  // Tracking pulled tighter than ~-0.05em crushes characters into each other.
1645  // Optical tightening that display type legitimately wants (around -0.02em)
1646  // stays well above this floor.
1647  if (hasDirectText && textLen > 20 && fontSize > 0) {
1648    if (letterSpacingPx != null && letterSpacingPx < 0) {
1649      const trackingEm = letterSpacingPx / fontSize;
1650      if (trackingEm <= -0.05) {
1651        const excerpt = (el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 40);
1652        findings.push({ id: 'extreme-negative-tracking', snippet: `letter-spacing: ${trackingEm.toFixed(2)}em — "${excerpt}"` });
1653      }
1654    }
1655  }
1656 
1657  return findings;
1658}
1659 
1660function checkElementQualityDOM(el) {
1661  const tag = el.tagName.toLowerCase();
1662  const style = getComputedStyle(el);
1663  const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 10);
1664  const textLen = el.textContent?.trim().length || 0;
1665  // Browser getComputedStyle resolves everything to px — direct parseFloat
1666  // works.
1667  const fontSize = parseFloat(style.fontSize) || 16;
1668  const lineHeightPx = resolveLengthPx(style.lineHeight, fontSize);
1669  const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize);
1670  const rect = el.getBoundingClientRect();
1671  const lineMax = (typeof window !== 'undefined' && window.__IMPECCABLE_CONFIG__?.lineLengthMax) || 80;
1672  const viewportWidth = (typeof window !== 'undefined' ? window.innerWidth : 0) || 0;
1673  return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax, viewportWidth, win: typeof window !== 'undefined' ? window : null });
1674}
1675 
1676// Pure page-level skipped-heading walk. Takes a Document so it works in both
1677// the browser and jsdom.
1678function checkPageQualityFromDoc(doc) {
1679  const findings = [];
1680  const headings = doc.querySelectorAll('h1, h2, h3, h4, h5, h6');
1681  let prevLevel = 0;
1682  let prevText = '';
1683  for (const h of headings) {
1684    const level = parseInt(h.tagName[1]);
1685    const text = (h.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 60);
1686    if (prevLevel > 0 && level > prevLevel + 1) {
1687      findings.push({
1688        id: 'skipped-heading',
1689        snippet: `<h${prevLevel}> "${prevText}" followed by <h${level}> "${text}" (missing h${prevLevel + 1})`,
1690      });
1691    }
1692    prevLevel = level;
1693    prevText = text;
1694  }
1695  return findings;
1696}
1697 
1698// Browser adapter (returns the legacy { type, detail } shape used by the overlay loop)
1699function checkPageQualityDOM() {
1700  return checkPageQualityFromDoc(document).map(f => ({ type: f.id, detail: f.snippet }));
1701}
1702 
1703// Node adapters — take pre-extracted jsdom computed style
1704 
1705// jsdom doesn't lay out OR resolve em/rem/% to px — so we pre-resolve every
1706// CSS length the rule needs ourselves (walking the parent chain for
1707// font-size inheritance), and pass `rect: null` to skip the two rules that
1708// genuinely need element rects (line-length, cramped-padding).
1709function checkElementQuality(el, style, tag, window) {
1710  const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 10);
1711  const textLen = el.textContent?.trim().length || 0;
1712  const fontSize = resolveFontSizePx(el, window);
1713  const lineHeightPx = resolveLengthPx(style.lineHeight, fontSize);
1714  const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize);
1715  return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null, win: window });
1716}
1717 
1718function checkElementBorders(tag, style, overrides, resolvedRadius) {
1719  const sides = ['Top', 'Right', 'Bottom', 'Left'];
1720  const widths = {}, colors = {};
1721  for (const s of sides) {
1722    widths[s] = parseFloat(style[`border${s}Width`]) || 0;
1723    colors[s] = style[`border${s}Color`] || '';
1724    // jsdom silently drops any border shorthand containing var(), leaving
1725    // both width and color empty on the computed style. When the detectHtml
1726    // pre-pass pulled a resolved value off the rule, use it to fill in the
1727    // missing side so the side-tab check can run. Real browsers resolve
1728    // var() natively, so this fallback is a no-op in the browser path.
1729    if (widths[s] === 0 && overrides && overrides[s]) {
1730      widths[s] = overrides[s].width;
1731      colors[s] = overrides[s].color;
1732    } else if (colors[s] && colors[s].startsWith('var(') && overrides && overrides[s]) {
1733      // Longhand case: jsdom kept the width but left the color as the
1734      // literal `var(...)` string. Substitute the resolved color.
1735      colors[s] = overrides[s].color;
1736    }
1737  }
1738  // resolvedRadius lets the caller pre-resolve the radius via
1739  // resolveBorderRadiusPx so the value survives jsdom 29.1.0's broken
1740  // shorthand serialization. Falls back to the computed value for tests
1741  // and browser callers that don't pre-resolve.
1742  const radius = resolvedRadius != null
1743    ? resolvedRadius
1744    : (parseFloat(style.borderRadius) || 0);
1745  return checkBorders(tag, widths, colors, radius);
1746}
1747 
1748function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInheritRule) {
1749  const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
1750  const hasDirectText = directText.trim().length > 0;
1751 
1752  const effectiveBg = resolveBackground(el, window, customPropMap);
1753  // jsdom returns literal "var(--X)" / "oklch(...)" for color, so plain
1754  // parseRgb misses Tailwind-tokenized text colors. Resolve through the
1755  // customPropMap first; fall back to parseRgb for vanilla rgb() pages.
1756  let textColor = customPropMap ? parseColorResolved(style.color, customPropMap) : null;
1757  if (!textColor) textColor = parseRgb(style.color);
1758 
1759  // Anchor-inherit FP workaround: jsdom's UA stylesheet has `:link { color:
1760  // blue }` at high specificity. The page's `a { color: inherit }` rule
1761  // (Tailwind v4 preflight) loses to jsdom even though it WINS in real
1762  // browsers (Chrome's UA wraps :link in :where() — zero specificity).
1763  // When the page declares the inherit rule AND we see jsdom's default
1764  // link blue on an anchor, walk to the nearest non-anchor ancestor and
1765  // use its color instead.
1766  if (
1767    hasAnchorInheritRule &&
1768    textColor &&
1769    textColor.r === 0 && textColor.g === 0 && textColor.b === 238 &&
1770    (tag === 'a' || el.closest?.('a'))
1771  ) {
1772    let cur = el.parentElement;
1773    while (cur && cur.tagName !== 'HTML') {
1774      if (cur.tagName !== 'A') {
1775        const ps = window.getComputedStyle(cur);
1776        const inh = (customPropMap ? parseColorResolved(ps.color, customPropMap) : null) || parseRgb(ps.color);
1777        if (inh && !(inh.r === 0 && inh.g === 0 && inh.b === 238)) {
1778          textColor = inh;
1779          break;
1780        }
1781      }
1782      cur = cur.parentElement;
1783    }
1784  }
1785 
1786  return checkColors({
1787    tag,
1788    textColor,
1789    bgColor: readOwnBackgroundColor(el, style),
1790    effectiveBg,
1791    effectiveBgStops: effectiveBg ? null : resolveGradientStops(el, window),
1792    fontSize: parseFloat(style.fontSize) || 16,
1793    fontWeight: parseInt(style.fontWeight) || 400,
1794    hasDirectText,
1795    isEmojiOnly: isEmojiOnlyText(directText),
1796    bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
1797    bgImage: style.backgroundImage || '',
1798    classList: el.getAttribute?.('class') || el.className || '',
1799  });
1800}
1801 
1802function checkElementIconTile(el, tag, window) {
1803  if (!HEADING_TAGS.has(tag)) return [];
1804  const sibling = el.previousElementSibling;
1805  if (!sibling) return [];
1806 
1807  const sibStyle = window.getComputedStyle(sibling);
1808  // jsdom doesn't lay out — read explicit pixel dimensions from CSS instead.
1809  const sibWidth = parseFloat(sibStyle.width) || 0;
1810  const sibHeight = parseFloat(sibStyle.height) || 0;
1811 
1812  const iconChild = sibling.querySelector('svg, i[data-lucide], i[class*="fa-"], i[class*="icon"]');
1813  let iconWidth = 0;
1814  if (iconChild) {
1815    const iconStyle = window.getComputedStyle(iconChild);
1816    iconWidth = parseFloat(iconStyle.width) || parseFloat(iconChild.getAttribute('width')) || 0;
1817  }
1818  // Or: tile contains an emoji/symbol character directly as its only content
1819  const sibDirectText = [...sibling.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
1820  const hasInlineEmojiIcon = sibling.children.length === 0 && isEmojiOnlyText(sibDirectText);
1821 
1822  return checkIconTile({
1823    headingTag: tag,
1824    headingText: el.textContent || '',
1825    headingTop: 0, // jsdom: no layout, skip vertical-stacking gate
1826    siblingTag: sibling.tagName.toLowerCase(),
1827    siblingWidth: sibWidth,
1828    siblingHeight: sibHeight,
1829    siblingBottom: 0,
1830    siblingBgColor: parseRgb(sibStyle.backgroundColor),
1831    siblingBgImage: sibStyle.backgroundImage || '',
1832    siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
1833    siblingBorderRadius: resolveBorderRadiusPx(sibling, sibStyle, sibWidth, window),
1834    hasIconChild: !!iconChild || hasInlineEmojiIcon,
1835    iconChildWidth: iconWidth,
1836  });
1837}
1838 
1839function checkElementItalicSerif(el, style, tag) {
1840  if (tag !== 'h1' && tag !== 'h2') return [];
1841  return checkItalicSerif({
1842    tag,
1843    fontStyle: style.fontStyle || '',
1844    fontFamily: style.fontFamily || '',
1845    fontSize: parseFloat(style.fontSize) || 0,
1846    headingText: el.textContent || '',
1847  });
1848}
1849 
1850function checkElementHeroEyebrow(el, style, tag, window, customPropMap) {
1851  if (tag !== 'h1') return [];
1852  const sibling = el.previousElementSibling;
1853  if (!sibling) return [];
1854  const sibStyle = window.getComputedStyle(sibling);
1855  // Resolve Tailwind v4 CSS-variable wrappers (font-weight:var(--font-weight-bold)
1856  // etc.) before parsing. jsdom returns these verbatim from getComputedStyle;
1857  // without resolution every style-based gate fails silently on Tailwind v4 builds.
1858  const fontSizeRaw = customPropMap ? resolveVarRefs(sibStyle.fontSize, customPropMap) : sibStyle.fontSize;
1859  const fontWeightRaw = customPropMap ? resolveVarRefs(sibStyle.fontWeight, customPropMap) : sibStyle.fontWeight;
1860  const letterSpacingRaw = customPropMap ? resolveVarRefs(sibStyle.letterSpacing, customPropMap) : sibStyle.letterSpacing;
1861  const colorRaw = customPropMap ? resolveVarRefs(sibStyle.color, customPropMap) : sibStyle.color;
1862  const headingFontSizeRaw = customPropMap ? resolveVarRefs(style.fontSize, customPropMap) : style.fontSize;
1863  const siblingFontSize = parseFloat(fontSizeRaw) || 0;
1864  // resolveLengthPx returns null for 'normal' / 'auto'; coerce to 0 so the
1865  // gate falls through cleanly. jsdom returns letter-spacing verbatim
1866  // (e.g. '0.15em'), unlike real browsers, so this conversion is required.
1867  return checkHeroEyebrow({
1868    headingTag: tag,
1869    headingText: el.textContent || '',
1870    headingFontSize: parseFloat(headingFontSizeRaw) || 0,
1871    siblingTag: sibling.tagName.toLowerCase(),
1872    siblingText: sibling.textContent || '',
1873    siblingTextTransform: sibStyle.textTransform || '',
1874    siblingFontSize,
1875    siblingLetterSpacing: resolveLengthPx(letterSpacingRaw, siblingFontSize) || 0,
1876    siblingFontWeight: fontWeightRaw || '',
1877    siblingColor: colorRaw || '',
1878  });
1879}
1880 
1881function checkRepeatedSectionKickersFromDoc(doc, win) {
1882  const candidates = collectRepeatedSectionKickerCandidates(
1883    doc,
1884    (el) => win.getComputedStyle(el),
1885    (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
1886  );
1887  return checkRepeatedSectionKickers({ candidates });
1888}
1889 
1890function checkElementMotion(tag, style) {
1891  return checkMotion({
1892    tag,
1893    transitionProperty: style.transitionProperty || '',
1894    animationName: style.animationName || '',
1895    timingFunctions: [style.animationTimingFunction, style.transitionTimingFunction].filter(Boolean).join(' '),
1896    classList: '',
1897  });
1898}
1899 
1900function checkElementGlow(tag, style, effectiveBg) {
1901  if (!style.boxShadow || style.boxShadow === 'none') return [];
1902  return checkGlow({ tag, boxShadow: style.boxShadow, effectiveBg });
1903}
1904 
1905// ─── Section 6: Page-Level Checks ───────────────────────────────────────────
1906 
1907// Browser page-level checks — use document/getComputedStyle globals
1908 
1909function checkTypography() {
1910  const findings = [];
1911 
1912  // Walk actual text-bearing elements and tally font usage by *computed style*.
1913  // This is much more accurate than scanning CSS rules — it ignores rules that
1914  // exist in the stylesheet but apply to nothing (e.g. demo classes showing
1915  // anti-patterns), and counts what the user actually sees.
1916  const fontUsage = new Map(); // primary font name → count of elements
1917  let totalTextElements = 0;
1918  for (const el of document.querySelectorAll('p, h1, h2, h3, h4, h5, h6, li, td, th, dd, blockquote, figcaption, a, button, label, span')) {
1919    // Skip impeccable's own elements
1920    if (el.closest && el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
1921    // Only count elements that actually have visible direct text
1922    const hasText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 0);
1923    if (!hasText) continue;
1924    const style = getComputedStyle(el);
1925    const ff = style.fontFamily;
1926    if (!ff) continue;
1927    const stack = ff.split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase());
1928    const primary = stack.find(f => f && !GENERIC_FONTS.has(f));
1929    if (!primary) continue;
1930    fontUsage.set(primary, (fontUsage.get(primary) || 0) + 1);
1931    totalTextElements++;
1932  }
1933 
1934  if (totalTextElements >= 20) {
1935    // A font is "primary" if it's used by at least 15% of text elements
1936    const PRIMARY_THRESHOLD = 0.15;
1937    for (const [font, count] of fontUsage) {
1938      const share = count / totalTextElements;
1939      if (share < PRIMARY_THRESHOLD) continue;
1940      if (!OVERUSED_FONTS.has(font)) continue;
1941      if (isBrandFontOnOwnDomain(font)) continue;
1942      findings.push({ type: 'overused-font', detail: `Primary font: ${font} (${Math.round(share * 100)}% of text)` });
1943    }
1944 
1945    // Single-font check: only one distinct primary font across all text
1946    if (fontUsage.size === 1) {
1947      const only = [...fontUsage.keys()][0];
1948      findings.push({ type: 'single-font', detail: `only font used is ${only}` });
1949    }
1950  }
1951 
1952  const sizes = new Set();
1953  for (const el of document.querySelectorAll('h1,h2,h3,h4,h5,h6,p,span,a,li,td,th,label,button,div')) {
1954    const fs = parseFloat(getComputedStyle(el).fontSize);
1955    if (fs > 0 && fs < 200) sizes.add(Math.round(fs * 10) / 10);
1956  }
1957  if (sizes.size >= 3) {
1958    const sorted = [...sizes].sort((a, b) => a - b);
1959    const ratio = sorted[sorted.length - 1] / sorted[0];
1960    if (ratio < 2.0) {
1961      findings.push({ type: 'flat-type-hierarchy', detail: `Sizes: ${sorted.map(s => s + 'px').join(', ')} (ratio ${ratio.toFixed(1)}:1)` });
1962    }
1963  }
1964 
1965  return findings;
1966}
1967 
1968function isCardLikeDOM(el) {
1969  const tag = el.tagName.toLowerCase();
1970  if (SAFE_TAGS.has(tag) || ['input','select','textarea','img','video','canvas','picture'].includes(tag)) return false;
1971  const style = getComputedStyle(el);
1972  const cls = el.getAttribute('class') || '';
1973  const hasShadow = (style.boxShadow && style.boxShadow !== 'none') || /\bshadow(?:-sm|-md|-lg|-xl|-2xl)?\b/.test(cls);
1974  const hasBorder = /\bborder\b/.test(cls);
1975  const hasRadius = parseFloat(style.borderRadius) > 0 || /\brounded(?:-sm|-md|-lg|-xl|-2xl|-full)?\b/.test(cls);
1976  const hasBg = (style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)') || /\bbg-(?:white|gray-\d+|slate-\d+)\b/.test(cls);
1977  return isCardLikeFromProps(hasShadow, hasBorder, hasRadius, hasBg);
1978}
1979 
1980function checkLayout() {
1981  const findings = [];
1982  const flaggedEls = new Set();
1983 
1984  for (const el of document.querySelectorAll('*')) {
1985    if (!isCardLikeDOM(el) || flaggedEls.has(el)) continue;
1986    const cls = el.getAttribute('class') || '';
1987    const style = getComputedStyle(el);
1988    if (style.position === 'absolute' || style.position === 'fixed') continue;
1989    if (/\b(?:dropdown|popover|tooltip|menu|modal|dialog)\b/i.test(cls)) continue;
1990    if ((el.textContent?.trim().length || 0) < 10) continue;
1991    const rect = el.getBoundingClientRect();
1992    if (rect.width < 50 || rect.height < 30) continue;
1993 
1994    let parent = el.parentElement;
1995    while (parent) {
1996      if (isCardLikeDOM(parent)) { flaggedEls.add(el); break; }
1997      parent = parent.parentElement;
1998    }
1999  }
2000 
2001  for (const el of flaggedEls) {
2002    let isAncestor = false;
2003    for (const other of flaggedEls) {
2004      if (other !== el && el.contains(other)) { isAncestor = true; break; }
2005    }
2006    if (!isAncestor) findings.push({ type: 'nested-cards', detail: 'Card inside card', el });
2007  }
2008 
2009  return findings;
2010}
2011 
2012// Node page-level checks — take document/window as parameters
2013 
2014function checkPageTypography(doc, win) {
2015  const findings = [];
2016 
2017  const fonts = new Set();
2018  const overusedFound = new Set();
2019 
2020  for (const sheet of doc.styleSheets) {
2021    let rules;
2022    try { rules = sheet.cssRules || sheet.rules; } catch { continue; }
2023    if (!rules) continue;
2024    for (const rule of rules) {
2025      if (rule.type !== 1) continue;
2026      const ff = rule.style?.fontFamily;
2027      if (!ff) continue;
2028      const stack = ff.split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase());
2029      const primary = stack.find(f => f && !GENERIC_FONTS.has(f));
2030      if (primary) {
2031        fonts.add(primary);
2032        if (OVERUSED_FONTS.has(primary)) overusedFound.add(primary);
2033      }
2034    }
2035  }
2036 
2037  // Check Google Fonts links in HTML
2038  const html = doc.documentElement?.outerHTML || '';
2039  const gfRe = /fonts\.googleapis\.com\/css2?\?family=([^&"'\s]+)/gi;
2040  let m;
2041  while ((m = gfRe.exec(html)) !== null) {
2042    const families = m[1].split('|').map(f => f.split(':')[0].replace(/\+/g, ' ').toLowerCase());
2043    for (const f of families) {
2044      fonts.add(f);
2045      if (OVERUSED_FONTS.has(f)) overusedFound.add(f);
2046    }
2047  }
2048 
2049  // Also parse raw HTML/style content for font-family (jsdom may not expose all via CSSOM)
2050  const ffRe = /font-family\s*:\s*([^;}]+)/gi;
2051  let fm;
2052  while ((fm = ffRe.exec(html)) !== null) {
2053    for (const f of fm[1].split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase())) {
2054      if (f && !GENERIC_FONTS.has(f)) {
2055        fonts.add(f);
2056        if (OVERUSED_FONTS.has(f)) overusedFound.add(f);
2057      }
2058    }
2059  }
2060 
2061  for (const font of overusedFound) {
2062    findings.push({ id: 'overused-font', snippet: `Primary font: ${font}` });
2063  }
2064 
2065  // Single font
2066  if (fonts.size === 1) {
2067    const els = doc.querySelectorAll('*');
2068    if (els.length >= 20) {
2069      findings.push({ id: 'single-font', snippet: `only font used is ${[...fonts][0]}` });
2070    }
2071  }
2072 
2073  // Flat type hierarchy
2074  const sizes = new Set();
2075  const textEls = doc.querySelectorAll('h1, h2, h3, h4, h5, h6, p, span, a, li, td, th, label, button, div');
2076  for (const el of textEls) {
2077    const fontSize = parseFloat(win.getComputedStyle(el).fontSize);
2078    // Filter out sub-8px values (jsdom doesn't resolve relative units properly)
2079    if (fontSize >= 8 && fontSize < 200) sizes.add(Math.round(fontSize * 10) / 10);
2080  }
2081  if (sizes.size >= 3) {
2082    const sorted = [...sizes].sort((a, b) => a - b);
2083    const ratio = sorted[sorted.length - 1] / sorted[0];
2084    if (ratio < 2.0) {
2085      findings.push({ id: 'flat-type-hierarchy', snippet: `Sizes: ${sorted.map(s => s + 'px').join(', ')} (ratio ${ratio.toFixed(1)}:1)` });
2086    }
2087  }
2088 
2089  return findings;
2090}
2091 
2092function isCardLike(el, win) {
2093  const tag = el.tagName.toLowerCase();
2094  if (SAFE_TAGS.has(tag) || ['input', 'select', 'textarea', 'img', 'video', 'canvas', 'picture'].includes(tag)) return false;
2095 
2096  const style = win.getComputedStyle(el);
2097  const rawStyle = el.getAttribute?.('style') || '';
2098  const cls = el.getAttribute?.('class') || '';
2099 
2100  const hasShadow = (style.boxShadow && style.boxShadow !== 'none') ||
2101    /\bshadow(?:-sm|-md|-lg|-xl|-2xl)?\b/.test(cls) || /box-shadow/i.test(rawStyle);
2102  const hasBorder = /\bborder\b/.test(cls);
2103  const widthPx = parseFloat(style.width) || 0;
2104  const hasRadius = resolveBorderRadiusPx(el, style, widthPx, win) > 0 ||
2105    /\brounded(?:-sm|-md|-lg|-xl|-2xl|-full)?\b/.test(cls) || /border-radius/i.test(rawStyle);
2106  const hasBg = /\bbg-(?:white|gray-\d+|slate-\d+)\b/.test(cls) ||
2107    /background(?:-color)?\s*:\s*(?!transparent)/i.test(rawStyle);
2108 
2109  return isCardLikeFromProps(hasShadow, hasBorder, hasRadius, hasBg);
2110}
2111 
2112function checkPageLayout(doc, win) {
2113  const findings = [];
2114 
2115  // Nested cards
2116  const allEls = doc.querySelectorAll('*');
2117  const flaggedEls = new Set();
2118  for (const el of allEls) {
2119    if (!isCardLike(el, win)) continue;
2120    if (flaggedEls.has(el)) continue;
2121 
2122    const tag = el.tagName.toLowerCase();
2123    const cls = el.getAttribute?.('class') || '';
2124    const rawStyle = el.getAttribute?.('style') || '';
2125 
2126    if (['pre', 'code'].includes(tag)) continue;
2127    if (/\b(?:absolute|fixed)\b/.test(cls) || /position\s*:\s*(?:absolute|fixed)/i.test(rawStyle)) continue;
2128    if ((el.textContent?.trim().length || 0) < 10) continue;
2129    if (/\b(?:dropdown|popover|tooltip|menu|modal|dialog)\b/i.test(cls)) continue;
2130 
2131    // Walk up to find card-like ancestor
2132    let parent = el.parentElement;
2133    while (parent) {
2134      if (isCardLike(parent, win)) {
2135        flaggedEls.add(el);
2136        break;
2137      }
2138      parent = parent.parentElement;
2139    }
2140  }
2141 
2142  // Only report innermost nested cards
2143  for (const el of flaggedEls) {
2144    let isAncestorOfFlagged = false;
2145    for (const other of flaggedEls) {
2146      if (other !== el && el.contains(other)) {
2147        isAncestorOfFlagged = true;
2148        break;
2149      }
2150    }
2151    if (!isAncestorOfFlagged) {
2152      findings.push({ id: 'nested-cards', snippet: `Card inside card (${el.tagName.toLowerCase()})` });
2153    }
2154  }
2155 
2156  return findings;
2157}
2158 
2159// ─── Cream / beige palette (the default "tasteful" AI surface) ────────────────
2160// A warm, lightly-tinted off-white page background — light, with R≥G≥B and a
2161// small warm tint (not white, not a strong color). The current reflex surface.
2162function isCreamColor(rgb) {
2163  if (!rgb) return false;
2164  const { r, g, b } = rgb;
2165  if (Math.min(r, g, b) < 209) return false;   // must be light
2166  if (!(r >= g && g >= b)) return false;        // warm ordering
2167  const warmth = r - b;
2168  return warmth >= 6 && warmth <= 48;           // tinted, not white, not strong
2169}
2170 
2171// Tailwind background utilities that render as a warm off-white surface. The
2172// static engine doesn't fetch Tailwind's CSS, so a `bg-amber-50` on <body>
2173// resolves to nothing in computed style — catch it from the class list
2174// instead. Candidate tokens map to their actual Tailwind hex and are still
2175// filtered through isCreamColor, so neutral grays (stone) and over-saturated
2176// shades drop out on their own.
2177const TAILWIND_BG_HEX = {
2178  'bg-amber-50': '#fffbeb', 'bg-amber-100': '#fef3c7',
2179  'bg-orange-50': '#fff7ed', 'bg-orange-100': '#ffedd5',
2180  'bg-yellow-50': '#fefce8',
2181  'bg-stone-50': '#fafaf9', 'bg-stone-100': '#f5f5f4', 'bg-stone-200': '#e7e5e4',
2182};
2183 
2184function creamFromClassList(cls) {
2185  if (!cls) return null;
2186  // Arbitrary value: bg-[#f5f0e6] / bg-[rgb(245_240_230)] (underscores = spaces).
2187  const arb = cls.match(/\bbg-\[([^\]]+)\]/);
2188  if (arb && isCreamColor(parseAnyColor(arb[1].replace(/_/g, ' ')))) return `bg-[${arb[1]}]`;
2189  // Named warm-light utilities.
2190  for (const [tok, hex] of Object.entries(TAILWIND_BG_HEX)) {
2191    if (new RegExp(`(^|\\s)${tok}($|\\s)`).test(cls) && isCreamColor(parseAnyColor(hex))) return tok;
2192  }
2193  return null;
2194}
2195 
2196function checkCreamPalette(doc, win) {
2197  const findings = [];
2198  const body = doc.body || (doc.querySelector ? doc.querySelector('body') : null);
2199  if (!body) return findings;
2200  const html = doc.documentElement;
2201  const getCS = (el) => (win ? win.getComputedStyle(el) : getComputedStyle(el));
2202 
2203  // 1. Computed background — covers inline / <style> / linked CSS, and Tailwind
2204  //    once it's actually rendered (browser path).
2205  let bg = readOwnBackgroundColor(body, getCS(body));
2206  if (!bg || bg.a === 0) {
2207    if (html) bg = readOwnBackgroundColor(html, getCS(html));
2208  }
2209  if (isCreamColor(bg)) {
2210    findings.push({ id: 'cream-palette', snippet: `cream/beige page background rgb(${bg.r}, ${bg.g}, ${bg.b})` });
2211    return findings;
2212  }
2213 
2214  // 2. Tailwind class fallback — for the static path, where utility classes
2215  //    never resolve to computed CSS.
2216  for (const el of [body, html]) {
2217    const tok = creamFromClassList(el && el.getAttribute ? el.getAttribute('class') : '');
2218    if (tok) {
2219      findings.push({ id: 'cream-palette', snippet: `cream/beige page background (Tailwind ${tok})` });
2220      break;
2221    }
2222  }
2223  return findings;
2224}
2225 
2226// ─── Oversized hero headline ────────────────────────────────────────────────
2227// Fires when a *long* headline is set at display size and actually dominates
2228// the viewport. A punchy one- or two-word headline at the same size is a
2229// legitimate stylistic choice, and a large-but-contained two-line hero should
2230// pass too — length and viewport share together are the tell.
2231const OVERSIZED_H1_FONT_PX = 72;
2232const OVERSIZED_H1_MIN_CHARS = 40;
2233const OVERSIZED_H1_MIN_VIEWPORT_HEIGHT_RATIO = 0.28;
2234const OVERSIZED_H1_MIN_VIEWPORT_AREA_RATIO = 0.25;
2235function checkOversizedH1({ tag, fontSize, headingText, rect = null, viewportWidth = 0, viewportHeight = 0 }) {
2236  if (tag !== 'h1') return [];
2237  const textLen = headingText.length;
2238  if (fontSize >= OVERSIZED_H1_FONT_PX && textLen >= OVERSIZED_H1_MIN_CHARS) {
2239    let viewportDetail = '';
2240    if (rect && viewportWidth > 0 && viewportHeight > 0) {
2241      const heightRatio = rect.height / viewportHeight;
2242      const areaRatio = (rect.width * rect.height) / (viewportWidth * viewportHeight);
2243      const dominatesViewport = heightRatio >= OVERSIZED_H1_MIN_VIEWPORT_HEIGHT_RATIO
2244        || areaRatio >= OVERSIZED_H1_MIN_VIEWPORT_AREA_RATIO;
2245      if (!dominatesViewport) return [];
2246      viewportDetail = `, ${Math.round(heightRatio * 100)}vh`;
2247    }
2248    return [{ id: 'oversized-h1', snippet: `${Math.round(fontSize)}px h1, ${textLen} chars${viewportDetail} "${headingText.slice(0, 60)}"` }];
2249  }
2250  return [];
2251}
2252 
2253function checkElementOversizedH1(el, style, tag, window) {
2254  if (tag !== 'h1') return [];
2255  const fontSize = resolveFontSizePx(el, window);
2256  const headingText = (el.textContent || '').trim().replace(/\s+/g, ' ');
2257  return checkOversizedH1({ tag, fontSize, headingText });
2258}
2259 
2260function checkElementOversizedH1DOM(el) {
2261  const tag = el.tagName.toLowerCase();
2262  if (tag !== 'h1') return [];
2263  const style = getComputedStyle(el);
2264  const fontSize = parseFloat(style.fontSize) || 0;
2265  const headingText = (el.textContent || '').trim().replace(/\s+/g, ' ');
2266  const rect = el.getBoundingClientRect();
2267  const viewportWidth = (typeof window !== 'undefined' ? window.innerWidth : 0) || 0;
2268  const viewportHeight = (typeof window !== 'undefined' ? window.innerHeight : 0) || 0;
2269  return checkOversizedH1({ tag, fontSize, headingText, rect, viewportWidth, viewportHeight });
2270}
2271 
2272// ─── GPT tell: hairline border + wide diffuse shadow (gated --gpt) ────────────
2273const CSS_COLOR_TOKEN_RE = /(?:rgba?|hsla?|oklch|oklab|lab|lch|color)\([^)]*\)|#[0-9a-fA-F]{3,8}\b|\b(?:black|white|transparent|currentcolor)\b/gi;
2274 
2275function shadowLayerAlpha(layer) {
2276  CSS_COLOR_TOKEN_RE.lastIndex = 0;
2277  const match = CSS_COLOR_TOKEN_RE.exec(layer);
2278  if (!match) return 1;
2279  if (match[0].toLowerCase() === 'transparent') return 0;
2280  const parsed = parseAnyColor(match[0]);
2281  return parsed ? (parsed.a ?? 1) : 1;
2282}
2283 
2284function shadowMaxBlurPx(boxShadow, { minAlpha = 0 } = {}) {
2285  if (!boxShadow || boxShadow === 'none') return 0;
2286  let maxBlur = 0;
2287  // Split into layers on commas not inside parentheses (rgba(...) etc.).
2288  for (const layer of boxShadow.split(/,(?![^()]*\))/)) {
2289    if (shadowLayerAlpha(layer) < minAlpha) continue;
2290    // Strip colors and keywords (rgba()/hsl()/hex/named/inset/px), leaving the
2291    // ordered length tokens: offsetX offsetY blur [spread]. Static jsdom keeps
2292    // unitless zeros ("0 0 24px"); browsers normalize to px ("0px 0px 24px") —
2293    // both reduce to the same numbers here.
2294    const cleaned = layer.replace(CSS_COLOR_TOKEN_RE, ' ').replace(/\b[a-z]+\b/gi, ' ');
2295    const nums = [...cleaned.matchAll(/-?\d*\.?\d+/g)].map(m => parseFloat(m[0]));
2296    if (nums.length >= 3) maxBlur = Math.max(maxBlur, nums[2]);
2297  }
2298  return maxBlur;
2299}
2300 
2301function cssColorAlpha(value) {
2302  if (cssColorIsTransparent(value)) return 0;
2303  const parsed = parseAnyColor(value);
2304  return parsed ? (parsed.a ?? 1) : 1;
2305}
2306 
2307function checkGptThinBorderWideShadow({ borderWidths, borderColors, boxShadow }) {
2308  const visibleThinBorders = borderWidths
2309    .map((width, index) => ({ width, alpha: cssColorAlpha(borderColors?.[index] || '') }))
2310    .filter(({ width, alpha }) => width > 0 && width <= 1.5 && alpha >= 0.28);
2311  const maxBorder = Math.max(0, ...visibleThinBorders.map(({ width }) => width));
2312  const blur = shadowMaxBlurPx(boxShadow, { minAlpha: 0.12 });
2313  if (visibleThinBorders.length >= 2 && blur >= 16) {
2314    return [{ id: 'gpt-thin-border-wide-shadow', snippet: `${maxBorder}px border + ${Math.round(blur)}px shadow blur` }];
2315  }
2316  return [];
2317}
2318 
2319function borderWidthsFromStyle(style) {
2320  return [
2321    parseFloat(style.borderTopWidth) || 0,
2322    parseFloat(style.borderRightWidth) || 0,
2323    parseFloat(style.borderBottomWidth) || 0,
2324    parseFloat(style.borderLeftWidth) || 0,
2325  ];
2326}
2327 
2328function borderColorsFromStyle(style) {
2329  return [
2330    style.borderTopColor || '',
2331    style.borderRightColor || '',
2332    style.borderBottomColor || '',
2333    style.borderLeftColor || '',
2334  ];
2335}
2336 
2337function checkElementGptBorderShadow(el, style) {
2338  return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), borderColors: borderColorsFromStyle(style), boxShadow: style.boxShadow || '' });
2339}
2340 
2341function checkElementGptBorderShadowDOM(el) {
2342  const style = getComputedStyle(el);
2343  return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), borderColors: borderColorsFromStyle(style), boxShadow: style.boxShadow || '' });
2344}
2345 
2346// ─── Clipped overflow container ───────────────────────────────────────────────
2347// A clipping container (overflow hidden/clip, not a scroll region) wrapping an
2348// absolutely/fixed-positioned descendant clips popovers/menus that must escape.
2349function classSelector(el) {
2350  const cls = (el.getAttribute ? el.getAttribute('class') : el.className) || '';
2351  const tokens = String(cls).trim().split(/\s+/).filter(Boolean);
2352  const tag = el.tagName ? el.tagName.toLowerCase() : 'el';
2353  return tokens.length ? `${tag}.${tokens.join('.')}` : tag;
2354}
2355 
2356function positionedChildIsDecorative(child) {
2357  if (!child || typeof child.getAttribute !== 'function') return false;
2358  if (child.closest?.('[aria-hidden="true"]')) return true;
2359  const role = (child.getAttribute('role') || '').toLowerCase();
2360  if (role === 'none' || role === 'presentation') return true;
2361  const tag = child.tagName ? child.tagName.toLowerCase() : '';
2362  if (['img', 'svg', 'canvas', 'video'].includes(tag)) return true;
2363  const ident = `${child.getAttribute('class') || ''} ${child.getAttribute('id') || ''}`;
2364  if (
2365    /\b(art|bg|background|badge|blob|crop|decor|dot|glow|grain|image|mask|ornament|overlay|photo|scrim|shadow|shine|texture)\b/i.test(ident) &&
2366    !positionedChildHasSubstantiveContent(child)
2367  ) {
2368    return true;
2369  }
2370  return false;
2371}
2372 
2373const POSITIONED_CHILD_INTERACTIVE_SELECTOR = [
2374  'a[href]',
2375  'button',
2376  'input',
2377  'select',
2378  'summary',
2379  'textarea',
2380  '[tabindex]:not([tabindex="-1"])',
2381  '[role="button"]',
2382  '[role="dialog"]',
2383  '[role="link"]',
2384  '[role="listbox"]',
2385  '[role="menu"]',
2386  '[role="menuitem"]',
2387  '[role="option"]',
2388  '[role="tooltip"]',
2389].join(',');
2390 
2391function positionedChildHasSubstantiveContent(child) {
2392  const text = (child.textContent || '').replace(/\s+/g, ' ').trim();
2393  if (text.length > 0) return true;
2394  if (typeof child.matches === 'function') {
2395    try {
2396      if (child.matches(POSITIONED_CHILD_INTERACTIVE_SELECTOR)) return true;
2397    } catch {}
2398  }
2399  if (typeof child.querySelector === 'function') {
2400    try {
2401      if (child.querySelector(POSITIONED_CHILD_INTERACTIVE_SELECTOR)) return true;
2402    } catch {}
2403  }
2404  return false;
2405}
2406 
2407function clippingContainerIsIntentionalViewport(el) {
2408  if (!el || typeof el.getAttribute !== 'function') return false;
2409  const roleDescription = (el.getAttribute('aria-roledescription') || '').toLowerCase();
2410  if (/\b(carousel|slider)\b/.test(roleDescription)) return true;
2411  const ident = `${el.getAttribute('class') || ''} ${el.getAttribute('id') || ''}`.toLowerCase();
2412  return /\b(carousel|comparison|compare|fisheye|marquee|preview|scroller|slider|slideshow|split|viewport)\b/.test(ident) ||
2413    /\b(demo-area|demo-stage|demo-viewport)\b/.test(ident);
2414}
2415 
2416function elementRect(el) {
2417  if (!el || typeof el.getBoundingClientRect !== 'function') return null;
2418  try {
2419    const rect = el.getBoundingClientRect();
2420    if (!rect) return null;
2421    const values = [rect.top, rect.right, rect.bottom, rect.left, rect.width, rect.height];
2422    if (!values.every(Number.isFinite)) return null;
2423    if (rect.width <= 0 && rect.height <= 0) return null;
2424    return rect;
2425  } catch {
2426    return null;
2427  }
2428}
2429 
2430function positionedStyleImpliesEscape(style) {
2431  const values = [
2432    style.top,
2433    style.right,
2434    style.bottom,
2435    style.left,
2436    style.inset,
2437    style.insetBlock,
2438    style.insetInline,
2439    style.insetBlockStart,
2440    style.insetBlockEnd,
2441    style.insetInlineStart,
2442    style.insetInlineEnd,
2443  ].filter(Boolean).map(value => String(value).trim().toLowerCase());
2444  for (const value of values) {
2445    if (/(^|[\s(])-+(?:\d|\.)/.test(value)) return true;
2446    if (/(^|[\s(])100(?:\.0+)?%/.test(value)) return true;
2447  }
2448  return false;
2449}
2450 
2451function positionedChildEscapesClip(el, child, clipX, clipY) {
2452  const parentRect = elementRect(el);
2453  const childRect = elementRect(child);
2454  if (!parentRect || !childRect) return null;
2455  const threshold = 2;
2456  return Boolean(
2457    (clipX && (childRect.left < parentRect.left - threshold || childRect.right > parentRect.right + threshold)) ||
2458    (clipY && (childRect.top < parentRect.top - threshold || childRect.bottom > parentRect.bottom + threshold))
2459  );
2460}
2461 
2462function checkClippedOverflow(el, style, getStyle) {
2463  const clips = (v) => v === 'hidden' || v === 'clip';
2464  const scrolls = (v) => v === 'auto' || v === 'scroll';
2465  const ox = style.overflowX || '', oy = style.overflowY || '', ov = style.overflow || '';
2466  const clipX = clips(ox) || clips(ov);
2467  const clipY = clips(oy) || clips(ov);
2468  const anyClip = clipX || clipY;
2469  const anyScroll = scrolls(ox) || scrolls(oy) || scrolls(ov);
2470  if (!anyClip || anyScroll) return [];
2471  if (clippingContainerIsIntentionalViewport(el)) return [];
2472  if (!el.querySelectorAll) return [];
2473  for (const child of el.querySelectorAll('*')) {
2474    const childStyle = getStyle(child);
2475    const pos = childStyle.position || '';
2476    if (pos === 'absolute' || pos === 'fixed') {
2477      if (positionedChildIsDecorative(child)) continue;
2478      const escapes = positionedChildEscapesClip(el, child, clipX, clipY);
2479      if (escapes === false) continue;
2480      if (escapes === null && !positionedStyleImpliesEscape(childStyle)) continue;
2481      return [{ id: 'clipped-overflow-container', snippet: `${classSelector(el)} clips a positioned child` }];
2482    }
2483  }
2484  return [];
2485}
2486 
2487function checkElementClippedOverflow(el, style, tag, window) {
2488  return checkClippedOverflow(el, style, (n) => window.getComputedStyle(n));
2489}
2490 
2491function checkElementClippedOverflowDOM(el) {
2492  const style = getComputedStyle(el);
2493  return checkClippedOverflow(el, style, (n) => getComputedStyle(n));
2494}
2495 
2496// ─── Text overflow (browser-only: needs scrollWidth/clientWidth) ──────────────
2497const TEXT_OVERFLOW_SKIP_TAGS = new Set(['pre', 'code', 'textarea', 'svg', 'canvas', 'select', 'option', 'marquee']);
2498 
2499function metricLengthPx(value, fontSizePx = 16) {
2500  if (typeof value === 'number' && Number.isFinite(value)) return value;
2501  if (typeof value !== 'string') return null;
2502  return resolveLengthPx(value, fontSizePx);
2503}
2504 
2505function firstMetricLengthPx(fontSizePx, ...values) {
2506  for (const value of values) {
2507    const parsed = metricLengthPx(value, fontSizePx);
2508    if (parsed !== null) return parsed;
2509  }
2510  return null;
2511}
2512 
2513function expandBoxShorthand(parts) {
2514  if (parts.length === 1) return [parts[0], parts[0], parts[0], parts[0]];
2515  if (parts.length === 2) return [parts[0], parts[1], parts[0], parts[1]];
2516  if (parts.length === 3) return [parts[0], parts[1], parts[2], parts[1]];
2517  return [parts[0], parts[1], parts[2], parts[3]];
2518}
2519 
2520function clippedByInset(clipPath) {
2521  const match = String(clipPath || '').trim().toLowerCase().match(/^inset\s*\(([^)]*)\)$/);
2522  if (!match) return false;
2523  const beforeRound = match[1].split(/\s+round\s+/)[0].trim();
2524  if (!beforeRound) return false;
2525  const values = expandBoxShorthand(beforeRound.split(/\s+/).slice(0, 4));
2526  const percents = values.map(value => String(value).trim().match(/^(-?\d+(?:\.\d+)?)%$/));
2527  if (percents.some(match => !match)) return false;
2528  const [top, right, bottom, left] = percents.map(match => parseFloat(match[1]));
2529  return top + bottom >= 100 || left + right >= 100;
2530}
2531 
2532function clippedByRect(clip) {
2533  const match = String(clip || '').trim().toLowerCase().match(/^rect\s*\(([^)]*)\)$/);
2534  if (!match) return false;
2535  const values = match[1].split(/[,\s]+/).map(value => value.trim()).filter(Boolean);
2536  if (values.length !== 4) return false;
2537  const [top, right, bottom, left] = values.map(value => metricLengthPx(value, 16));
2538  if ([top, right, bottom, left].some(value => value === null)) return false;
2539  return bottom <= top || right <= left;
2540}
2541 
2542function isScreenReaderOnlyTextStyle(style, metrics = {}) {
2543  if (!style) return false;
2544  const overflowValues = [style.overflow, style.overflowX, style.overflowY]
2545    .map(value => String(value || '').toLowerCase());
2546  const clipsOverflow = overflowValues.some(value => value === 'hidden' || value === 'clip');
2547 
2548  const fontSize = metricLengthPx(style.fontSize, 16) || 16;
2549  const width = firstMetricLengthPx(fontSize, metrics.width, metrics.clientWidth, style.width, style.inlineSize);
2550  const height = firstMetricLengthPx(fontSize, metrics.height, metrics.clientHeight, style.height, style.blockSize);
2551  const isTiny = width !== null && height !== null && width <= 2 && height <= 2;
2552  const isAbsolutelyHidden = String(style.position || '').toLowerCase() === 'absolute' && isTiny && clipsOverflow;
2553 
2554  const clipPath = String(style.clipPath || style.webkitClipPath || '').trim();
2555  const clip = String(style.clip || '').trim();
2556  return isAbsolutelyHidden || clippedByInset(clipPath) || clippedByRect(clip);
2557}
2558 
2559function isRenderedForBrowserRule(el) {
2560  for (let cur = el; cur && cur.nodeType === 1; cur = cur.parentElement) {
2561    if (cur.getAttribute?.('aria-hidden') === 'true') return false;
2562    const style = getComputedStyle(cur);
2563    const visibility = String(style.visibility || '').toLowerCase();
2564    if (style.display === 'none' || visibility === 'hidden' || visibility === 'collapse') return false;
2565    if ((parseFloat(style.opacity) || 0) <= 0.01) return false;
2566    if (String(style.contentVisibility || '').toLowerCase() === 'hidden') return false;
2567  }
2568  return true;
2569}
2570 
2571function checkElementTextOverflowDOM(el) {
2572  const tag = el.tagName.toLowerCase();
2573  if (TEXT_OVERFLOW_SKIP_TAGS.has(tag)) return [];
2574  if (!isRenderedForBrowserRule(el)) return [];
2575  // Only the element that actually owns overflowing text — not its ancestors,
2576  // which inherit a wider scrollWidth from the spilling descendant.
2577  const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 0);
2578  if (!hasDirectText) return [];
2579  const style = getComputedStyle(el);
2580  const rect = el.getBoundingClientRect ? el.getBoundingClientRect() : null;
2581  if (isScreenReaderOnlyTextStyle(style, {
2582    width: rect?.width,
2583    height: rect?.height,
2584    clientWidth: el.clientWidth,
2585    clientHeight: el.clientHeight,
2586  })) return [];
2587  const isScrollRegion = (s) => /(auto|scroll)/.test(s.overflowX || '') || /(auto|scroll)/.test(s.overflow || '');
2588  if (isScrollRegion(style)) return [];
2589  // A scrollable ancestor means this overflow is intentional and scrollable.
2590  for (let p = el.parentElement; p; p = p.parentElement) {
2591    if (isScrollRegion(getComputedStyle(p))) return [];
2592  }
2593  const delta = el.scrollWidth - el.clientWidth;
2594  if (el.clientWidth > 0 && delta >= 16) {
2595    return [{ id: 'text-overflow', snippet: `${classSelector(el)} overflows its box by ${Math.round(delta)}px` }];
2596  }
2597  return [];
2598}
2599 
2600export {
2601  checkBorders,
2602  isEmojiOnlyText,
2603  checkColors,
2604  isCardLikeFromProps,
2605  checkIconTile,
2606  resolveSerif,
2607  checkItalicSerif,
2608  isAccentColor,
2609  checkHeroEyebrow,
2610  checkRepeatedSectionKickers,
2611  checkMotion,
2612  checkGlow,
2613  checkHtmlPatterns,
2614  readOwnBackgroundColor,
2615  resolveBackground,
2616  resolveGradientStops,
2617  parseRadiusToPx,
2618  resolveBorderRadiusPx,
2619  checkElementBordersDOM,
2620  checkElementColorsDOM,
2621  checkElementIconTileDOM,
2622  checkElementItalicSerifDOM,
2623  checkElementHeroEyebrowDOM,
2624  buildCustomPropMap,
2625  resolveVarRefs,
2626  oklchToRgb,
2627  parseAnyColor,
2628  parseColorResolved,
2629  cleanInlineText,
2630  isRepeatedKickerCandidate,
2631  collectRepeatedSectionKickerCandidates,
2632  checkRepeatedSectionKickersDOM,
2633  checkElementMotionDOM,
2634  checkElementGlowDOM,
2635  checkElementAIPaletteDOM,
2636  resolveFontSizePx,
2637  resolveLengthPx,
2638  checkQuality,
2639  checkElementQualityDOM,
2640  checkPageQualityFromDoc,
2641  checkPageQualityDOM,
2642  checkElementQuality,
2643  checkElementBorders,
2644  checkElementColors,
2645  checkElementIconTile,
2646  checkElementItalicSerif,
2647  checkElementHeroEyebrow,
2648  checkRepeatedSectionKickersFromDoc,
2649  checkElementMotion,
2650  checkElementGlow,
2651  checkTypography,
2652  isCardLikeDOM,
2653  checkLayout,
2654  checkPageTypography,
2655  isCardLike,
2656  checkPageLayout,
2657  isCreamColor,
2658  checkCreamPalette,
2659  checkOversizedH1,
2660  checkElementOversizedH1,
2661  checkElementOversizedH1DOM,
2662  shadowMaxBlurPx,
2663  checkGptThinBorderWideShadow,
2664  checkElementGptBorderShadow,
2665  checkElementGptBorderShadowDOM,
2666  checkClippedOverflow,
2667  checkElementClippedOverflow,
2668  checkElementClippedOverflowDOM,
2669  isScreenReaderOnlyTextStyle,
2670  checkElementTextOverflowDOM,
2671};
2672