impeccable 2.1.7 → 2.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -26,10 +26,11 @@ const IS_BROWSER = typeof window !== 'undefined';
26
26
  const IS_NODE = !IS_BROWSER;
27
27
 
28
28
  // @browser-strip-start
29
- let fs, path;
29
+ let fs, path, fileURLToPath;
30
30
  if (!IS_BROWSER) {
31
31
  fs = (await import('node:fs')).default;
32
32
  path = (await import('node:path')).default;
33
+ fileURLToPath = (await import('node:url')).fileURLToPath;
33
34
  }
34
35
  // @browser-strip-end
35
36
 
@@ -56,7 +57,13 @@ const BORDER_SAFE_TAGS = new Set(
56
57
  );
57
58
 
58
59
  const OVERUSED_FONTS = new Set([
60
+ // Older monoculture (still ubiquitous):
59
61
  'inter', 'roboto', 'open sans', 'lato', 'montserrat', 'arial', 'helvetica',
62
+ // Newer monoculture (the Anthropic-skill / Vercel / GitHub default wave):
63
+ 'fraunces', 'instrument sans',
64
+ 'geist', 'geist sans', 'geist mono',
65
+ 'mona sans',
66
+ 'plus jakarta sans', 'space grotesk', 'recoleta',
60
67
  ]);
61
68
 
62
69
  // Brand-associated fonts: don't flag these as "overused" on the brand's own domains.
@@ -65,10 +72,16 @@ const GOOGLE_DOMAINS = [
65
72
  'google.com', 'youtube.com', 'android.com', 'chromium.org',
66
73
  'chrome.com', 'web.dev', 'gstatic.com', 'firebase.google.com',
67
74
  ];
75
+ const VERCEL_DOMAINS = ['vercel.com', 'nextjs.org', 'v0.app'];
76
+ const GITHUB_DOMAINS = ['github.com', 'githubnext.com'];
68
77
  const BRAND_FONT_DOMAINS = {
69
78
  'roboto': GOOGLE_DOMAINS,
70
79
  'google sans': GOOGLE_DOMAINS,
71
80
  'product sans': GOOGLE_DOMAINS,
81
+ 'geist': VERCEL_DOMAINS,
82
+ 'geist sans': VERCEL_DOMAINS,
83
+ 'geist mono': VERCEL_DOMAINS,
84
+ 'mona sans': GITHUB_DOMAINS,
72
85
  };
73
86
 
74
87
  function isBrandFontOnOwnDomain(font) {
@@ -86,6 +99,23 @@ const GENERIC_FONTS = new Set([
86
99
  'inherit', 'initial', 'unset', 'revert',
87
100
  ]);
88
101
 
102
+ // Serif faces that show up in italic-display heroes. The rule also fires when
103
+ // the primary face is unknown but the stack ends in the generic `serif` token,
104
+ // which catches custom/private faces with a serif fallback.
105
+ const KNOWN_SERIF_FONTS = new Set([
106
+ 'fraunces', 'recoleta', 'newsreader', 'playfair display', 'playfair',
107
+ 'cormorant', 'cormorant garamond', 'garamond', 'eb garamond',
108
+ 'tiempos', 'tiempos headline', 'tiempos text',
109
+ 'lora', 'vollkorn', 'spectral',
110
+ 'source serif pro', 'source serif 4', 'source serif',
111
+ 'ibm plex serif', 'merriweather',
112
+ 'libre caslon', 'libre baskerville', 'baskerville',
113
+ 'georgia', 'times new roman', 'times',
114
+ 'dm serif display', 'dm serif text',
115
+ 'instrument serif', 'gt sectra', 'ogg', 'canela',
116
+ 'freight display', 'freight text',
117
+ ]);
118
+
89
119
  const ANTIPATTERNS = [
90
120
  // ── AI slop: tells that something was AI-generated ──
91
121
  {
@@ -111,7 +141,7 @@ const ANTIPATTERNS = [
111
141
  category: 'slop',
112
142
  name: 'Overused font',
113
143
  description:
114
- 'Inter, Roboto, Open Sans, Lato, Montserrat, and Arial are used on millions of sites. Choose a distinctive font that gives your interface personality.',
144
+ 'Inter, Roboto, Fraunces, Geist, Plus Jakarta Sans, and Space Grotesk are used on so many sites they no longer feel distinctive. Each new wave of AI-generated UIs converges on the same handful of faces. Choose a face that gives your interface personality.',
115
145
  skillSection: 'Typography',
116
146
  skillGuideline: 'overused fonts like Inter',
117
147
  },
@@ -205,6 +235,34 @@ const ANTIPATTERNS = [
205
235
  skillSection: 'Typography',
206
236
  skillGuideline: 'large icons with rounded corners above every heading',
207
237
  },
238
+ {
239
+ id: 'italic-serif-display',
240
+ category: 'slop',
241
+ name: 'Italic serif display headline',
242
+ description:
243
+ 'Oversized italic serif (Fraunces, Recoleta, Playfair, Newsreader-italic) as the primary hero headline reads as taste in isolation but has become the universal AI-startup landing page hero. Set roman, or move to a non-serif display face. Editorial / magazine register may legitimately want this — judge by context.',
244
+ skillSection: 'Typography',
245
+ skillGuideline: 'oversized italic serif as the hero headline',
246
+ },
247
+ {
248
+ id: 'hero-eyebrow-chip',
249
+ category: 'slop',
250
+ name: 'Hero eyebrow / pill chip',
251
+ description:
252
+ 'A tiny uppercase letter-spaced label sitting immediately above an oversized hero headline — or the same shape rendered as a pill chip — is now the default AI SaaS hero. Drop the eyebrow, integrate the kicker into the headline, or run it as a navigation breadcrumb instead.',
253
+ skillSection: 'Typography',
254
+ skillGuideline: 'tiny uppercase tracked label above the hero headline',
255
+ },
256
+ {
257
+ id: 'repeated-section-kickers',
258
+ category: 'slop',
259
+ severity: 'advisory',
260
+ name: 'Repeated section kicker labels',
261
+ description:
262
+ 'Repeating tiny uppercase tracked labels above section headings turns a brand page into AI editorial scaffolding. Replace them with stronger structure, artifacts, imagery, or a deliberate brand system.',
263
+ skillSection: 'Typography',
264
+ skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding',
265
+ },
208
266
 
209
267
  // ── Quality: general design and accessibility issues ──
210
268
  {
@@ -257,6 +315,13 @@ const ANTIPATTERNS = [
257
315
  description:
258
316
  'Text is too close to the edge of its container. Add at least 8px (ideally 12-16px) of padding inside bordered or colored containers.',
259
317
  },
318
+ {
319
+ id: 'body-text-viewport-edge',
320
+ category: 'quality',
321
+ name: 'Body text touching viewport edge',
322
+ description:
323
+ 'Body paragraphs render flush against the left or right viewport edge with no container providing horizontal padding. Wrap content in a container with at least 16px (ideally 24-32px) of horizontal padding, or apply max-width with mx-auto.',
324
+ },
260
325
  {
261
326
  id: 'tight-leading',
262
327
  category: 'quality',
@@ -460,7 +525,18 @@ function isEmojiOnlyText(text) {
460
525
 
461
526
  function checkColors(opts) {
462
527
  const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList } = opts;
463
- if (SAFE_TAGS.has(tag)) return [];
528
+ if (SAFE_TAGS.has(tag)) {
529
+ // Exception for <a> and <button> elements styled as buttons. SAFE_TAGS
530
+ // exists to suppress contrast noise on inline links and unstyled controls,
531
+ // where the element has no own background and the contrast against the
532
+ // ancestor surface is already the intended visual. When the element has
533
+ // its own opaque background and direct text, it is a styled button — and
534
+ // contrast on its own surface is a real, frequent bug worth flagging.
535
+ const isStyledButton = (tag === 'a' || tag === 'button')
536
+ && hasDirectText
537
+ && bgColor && bgColor.a > 0.5;
538
+ if (!isStyledButton) return [];
539
+ }
464
540
  const findings = [];
465
541
 
466
542
  // Pure black background (only solid or near-solid, not semi-transparent overlays)
@@ -490,7 +566,20 @@ function checkColors(opts) {
490
566
  const isLargeText = fontSize >= 18 || (fontSize >= 14 && fontWeight >= 700) || isHeading;
491
567
  const threshold = isLargeText ? 3.0 : 4.5;
492
568
  if (ratio < threshold) {
493
- findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}` });
569
+ // Skip the false-positive class where text has alpha < 1 AND we
570
+ // couldn't find an opaque ancestor (effectiveBg is null, we're
571
+ // comparing against gradient-stop fallback). In jsdom mode the
572
+ // detector can't resolve `var(--X)` color tokens, so a dark
573
+ // section sitting between the text and the body's decorative
574
+ // gradient is invisible to us — we end up measuring contrast
575
+ // against the body's paper-grain noise instead of the real
576
+ // local bg. Real low-contrast bugs use alpha=1 and have a
577
+ // resolvable opaque ancestor; semi-transparent Tailwind tokens
578
+ // like `text-paper/60` on `bg-ink` sections are the FP pattern.
579
+ const isAlphaFallbackFP = !IS_BROWSER && !effectiveBg && (textColor.a != null && textColor.a < 1);
580
+ if (!isAlphaFallbackFP) {
581
+ findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}` });
582
+ }
494
583
  }
495
584
  }
496
585
 
@@ -599,6 +688,150 @@ function checkIconTile(opts) {
599
688
  }];
600
689
  }
601
690
 
691
+ // Resolve the primary (non-generic) face from a font-family string and return
692
+ // whether the resolved primary is serif. Two paths:
693
+ // 1. Primary face is in KNOWN_SERIF_FONTS → serif.
694
+ // 2. Primary face is unknown but the stack ends in the generic `serif`
695
+ // token → treat as serif. Authors who declare `font-family: 'X', serif`
696
+ // almost always have a serif primary; a sans declared with a serif
697
+ // fallback is a code smell, not the common case.
698
+ // Returns { primary, isSerif } so the snippet can name the face.
699
+ function resolveSerif(fontFamily) {
700
+ if (!fontFamily) return { primary: null, isSerif: false };
701
+ const tokens = fontFamily.split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase());
702
+ const primary = tokens.find(f => f && !GENERIC_FONTS.has(f)) || null;
703
+ if (!primary) return { primary: null, isSerif: false };
704
+ if (KNOWN_SERIF_FONTS.has(primary)) return { primary, isSerif: true };
705
+ if (tokens.includes('serif')) return { primary, isSerif: true };
706
+ return { primary, isSerif: false };
707
+ }
708
+
709
+ function checkItalicSerif(opts) {
710
+ const { tag, fontStyle, fontFamily, fontSize, headingText } = opts;
711
+ if (fontStyle !== 'italic') return [];
712
+ // Anchor the rule on hero-scale text. h1 is the canonical hero element;
713
+ // h2 ≥ 48px catches the cases where the design demotes the visual hero
714
+ // to an h2 but keeps the size.
715
+ if (tag !== 'h1' && !(tag === 'h2' && fontSize >= 48)) return [];
716
+ if (fontSize < 48) return [];
717
+ const { primary, isSerif } = resolveSerif(fontFamily);
718
+ if (!isSerif) return [];
719
+
720
+ const text = (headingText || '').trim().slice(0, 60);
721
+ return [{
722
+ id: 'italic-serif-display',
723
+ snippet: `italic serif ${tag} (${primary || 'serif'}) at ${Math.round(fontSize)}px "${text}"`,
724
+ }];
725
+ }
726
+
727
+ // Color saturation check. Returns true when the color has visible
728
+ // chroma — i.e., it's an "accent color" rather than near-neutral.
729
+ // Handles rgb()/rgba(), #hex, oklch(), and hsl(). var() refs are
730
+ // expected to be pre-resolved by the caller.
731
+ function isAccentColor(cssColor) {
732
+ if (!cssColor) return false;
733
+ const s = String(cssColor).trim();
734
+ // rgb / rgba — direct channel-distance check.
735
+ const rgbM = /rgba?\(\s*(\d+)\s*,?\s+|\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(s.replace(/rgba?\(\s*/, 'rgb(').replace(/,/g, ', '));
736
+ const rgbStrict = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(s);
737
+ if (rgbStrict) {
738
+ const r = +rgbStrict[1], g = +rgbStrict[2], b = +rgbStrict[3];
739
+ return (Math.max(r, g, b) - Math.min(r, g, b)) >= 40;
740
+ }
741
+ // #hex — 3, 4, 6, or 8 digit.
742
+ const hexM = /^#([0-9a-f]{3,8})\b/i.exec(s);
743
+ if (hexM) {
744
+ let h = hexM[1];
745
+ if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('').slice(0, 6);
746
+ else h = h.slice(0, 6);
747
+ if (h.length === 6) {
748
+ const r = parseInt(h.slice(0, 2), 16);
749
+ const g = parseInt(h.slice(2, 4), 16);
750
+ const b = parseInt(h.slice(4, 6), 16);
751
+ return (Math.max(r, g, b) - Math.min(r, g, b)) >= 40;
752
+ }
753
+ }
754
+ // oklch(L C H) — chroma C is what matters. Typical neutral grays
755
+ // have C < 0.02; visible accents are 0.05+. CSS minification can
756
+ // collapse spaces between L% and C ("oklch(43%.15 34)"), so we
757
+ // extract all numbers and take the second rather than matching a
758
+ // strict L-then-whitespace-then-C pattern.
759
+ if (/^oklch\(/i.test(s)) {
760
+ const nums = s.match(/\d*\.\d+|\d+/g);
761
+ if (nums && nums.length >= 2) {
762
+ const c = parseFloat(nums[1]);
763
+ return !Number.isNaN(c) && c >= 0.05;
764
+ }
765
+ }
766
+ // hsl(H, S%, L%) — saturation > 20% reads as accent.
767
+ const hslM = /hsla?\(\s*[\d.]+\s*,\s*([\d.]+)%/i.exec(s);
768
+ if (hslM) {
769
+ const sat = parseFloat(hslM[1]);
770
+ return !Number.isNaN(sat) && sat >= 20;
771
+ }
772
+ return false;
773
+ }
774
+
775
+ // Sibling-relationship rule. Anchor on a hero-scale h1, look at the
776
+ // previousElementSibling, and gate on EITHER the classic tracked-
777
+ // uppercase eyebrow OR the modern accent-colored bold eyebrow.
778
+ function checkHeroEyebrow(opts) {
779
+ const {
780
+ headingTag, headingText, headingFontSize,
781
+ siblingTag, siblingText, siblingTextTransform,
782
+ siblingFontSize, siblingLetterSpacing,
783
+ siblingFontWeight, siblingColor,
784
+ } = opts;
785
+ if (headingTag !== 'h1') return [];
786
+ // We previously gated on headingFontSize >= 48 to anchor "hero scale".
787
+ // But modern hero h1s use clamp() / vw / var(--text-*), none of which
788
+ // jsdom can resolve — the computed value comes back as "2em" or
789
+ // "var(--text-9xl)" and parseFloat returns 2 or NaN. The gate fails
790
+ // on virtually every Tailwind v4 / framework build. The other gates
791
+ // (sibling text 2-60 chars, font-size ≤ 14px, accent-bold OR
792
+ // tracked-caps) are tight enough to avoid false positives on non-
793
+ // hero h1s — a tiny tan label directly above any h1 is the
794
+ // antipattern regardless of how big the h1 ends up.
795
+ if (!siblingTag) return [];
796
+ // An h2 above an h1 is a different anti-pattern (heading hierarchy / dual
797
+ // headings) — never an eyebrow.
798
+ if (HEADING_TAGS.has(siblingTag)) return [];
799
+
800
+ const text = (siblingText || '').trim();
801
+ if (text.length < 2 || text.length > 60) return [];
802
+ if (!(siblingFontSize > 0 && siblingFontSize <= 14)) return [];
803
+
804
+ // Branch A: classic tracked-uppercase eyebrow.
805
+ const isUppercased = siblingTextTransform === 'uppercase'
806
+ || (/[A-Z]/.test(text) && !/[a-z]/.test(text));
807
+ const isClassicTracked = isUppercased && siblingLetterSpacing >= 1.6;
808
+
809
+ // Branch B: modern accent-bold eyebrow — sentence case, low
810
+ // tracking, but bold + accent-colored. The style choices changed;
811
+ // the pattern is the same kicker-above-headline anti-pattern.
812
+ const weight = Number(siblingFontWeight) || 400;
813
+ const isAccentBold = weight >= 700 && isAccentColor(siblingColor || '');
814
+
815
+ if (!isClassicTracked && !isAccentBold) return [];
816
+
817
+ const headingTextSnippet = (headingText || '').trim().slice(0, 60);
818
+ const eyebrowSnippet = text.slice(0, 40);
819
+ const style = isClassicTracked ? 'tracked-caps' : 'accent-bold';
820
+ return [{
821
+ id: 'hero-eyebrow-chip',
822
+ snippet: `eyebrow chip (${style}) "${eyebrowSnippet}" above ${headingTag} "${headingTextSnippet}"`,
823
+ }];
824
+ }
825
+
826
+ function checkRepeatedSectionKickers(opts) {
827
+ const { candidates, minCount = 3 } = opts;
828
+ if (!Array.isArray(candidates) || candidates.length < minCount) return [];
829
+ return candidates.map(candidate => ({
830
+ id: 'repeated-section-kickers',
831
+ snippet: `repeated section kicker "${candidate.kickerText}" before ${candidate.headingTag} "${candidate.headingText}" (${candidates.length} on page)`,
832
+ }));
833
+ }
834
+
602
835
  const LAYOUT_TRANSITION_PROPS = new Set([
603
836
  'width', 'height', 'padding', 'margin',
604
837
  'max-height', 'max-width', 'min-height', 'min-width',
@@ -812,43 +1045,88 @@ function checkHtmlPatterns(html) {
812
1045
 
813
1046
  // ─── Section 4: resolveBackground (unified) ─────────────────────────────────
814
1047
 
815
- function resolveBackground(el, win) {
1048
+ // Read the element's own background color, computed-style first, with a
1049
+ // jsdom-friendly fallback that parses the inline `background:` shorthand
1050
+ // from the raw style attribute. jsdom (~v29) does not decompose the
1051
+ // shorthand into `backgroundColor`, so without this fallback the CLI silently
1052
+ // returns null for any element styled via `background: rgb(...)` or
1053
+ // `background: #abc`. Real browsers always decompose, so the fallback is
1054
+ // a no-op there.
1055
+ function readOwnBackgroundColor(el, computedStyle) {
1056
+ const bg = parseRgb(computedStyle.backgroundColor);
1057
+ if (IS_BROWSER || (bg && bg.a >= 0.1)) return bg;
1058
+ const rawStyle = el.getAttribute?.('style') || '';
1059
+ const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
1060
+ const inlineBg = bgMatch ? bgMatch[1].trim() : '';
1061
+ if (!inlineBg) return bg;
1062
+ if (/gradient/i.test(inlineBg) || /url\s*\(/i.test(inlineBg)) return bg;
1063
+ const fromRgb = parseRgb(inlineBg);
1064
+ if (fromRgb) return fromRgb;
1065
+ const hexMatch = inlineBg.match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i);
1066
+ if (hexMatch) {
1067
+ const h = hexMatch[1];
1068
+ if (h.length === 6) {
1069
+ return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16), a: 1 };
1070
+ }
1071
+ return { r: parseInt(h[0] + h[0], 16), g: parseInt(h[1] + h[1], 16), b: parseInt(h[2] + h[2], 16), a: 1 };
1072
+ }
1073
+ return bg;
1074
+ }
1075
+
1076
+ function resolveBackground(el, win, customPropMap) {
816
1077
  let current = el;
817
1078
  while (current && current.nodeType === 1) {
818
1079
  const style = IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
819
-
820
- // If this element has a background-image (gradient or url), it's visually
821
- // opaque but we can't determine the effective color — bail out so callers
822
- // don't get a false solid-color answer.
823
1080
  const bgImage = style.backgroundImage || '';
824
- if (bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage))) {
825
- return null;
826
- }
827
-
1081
+ const hasGradientOrUrl = bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage));
1082
+
1083
+ // Try the solid bg-color FIRST. If the element has both a solid color
1084
+ // and a gradient/url overlay (a common pattern: `background: var(--paper)
1085
+ // radial-gradient(...)` for paper-grain texture), the solid color is the
1086
+ // dominant visible surface for contrast purposes; the overlay is
1087
+ // decorative. The old behavior bailed on any gradient ancestor, which
1088
+ // caused massive false-positive contrast findings on grain-textured
1089
+ // body backgrounds.
828
1090
  let bg = parseRgb(style.backgroundColor);
829
1091
  if (!IS_BROWSER && (!bg || bg.a < 0.1)) {
830
- // jsdom doesn't decompose background shorthand — parse raw style attr
831
- const rawStyle = current.getAttribute?.('style') || '';
832
- const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
833
- const inlineBg = bgMatch ? bgMatch[1].trim() : '';
834
- // Check for gradient or url() image in inline style too
835
- if (/gradient/i.test(inlineBg) || /url\s*\(/i.test(inlineBg)) return null;
836
- bg = parseRgb(inlineBg);
837
- if (!bg && inlineBg) {
838
- const hexMatch = inlineBg.match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i);
839
- if (hexMatch) {
840
- const h = hexMatch[1];
841
- if (h.length === 6) {
842
- bg = { r: parseInt(h.slice(0,2), 16), g: parseInt(h.slice(2,4), 16), b: parseInt(h.slice(4,6), 16), a: 1 };
843
- } else {
844
- bg = { r: parseInt(h[0]+h[0], 16), g: parseInt(h[1]+h[1], 16), b: parseInt(h[2]+h[2], 16), a: 1 };
845
- }
1092
+ // jsdom returns literal "var(--X)" / "oklch(...)" strings. Resolve
1093
+ // through customPropMap so Tailwind v4 color tokens become RGB.
1094
+ if (customPropMap) {
1095
+ bg = parseColorResolved(style.backgroundColor, customPropMap);
1096
+ }
1097
+ if (!bg || bg.a < 0.1) {
1098
+ // Inline-style fallback. jsdom doesn't decompose background
1099
+ // shorthand, so colors set via inline style are otherwise invisible.
1100
+ const rawStyle = current.getAttribute?.('style') || '';
1101
+ const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
1102
+ const inlineBg = bgMatch ? bgMatch[1].trim() : '';
1103
+ if (inlineBg && !/gradient/i.test(inlineBg) && !/url\s*\(/i.test(inlineBg)) {
1104
+ bg = parseColorResolved(inlineBg, customPropMap) || parseAnyColor(inlineBg);
846
1105
  }
847
1106
  }
848
1107
  }
1108
+
849
1109
  if (bg && bg.a > 0.1) {
850
1110
  if (IS_BROWSER || bg.a >= 0.5) return bg;
851
1111
  }
1112
+ // No solid bg-color at this level. If THIS level has a gradient/url
1113
+ // with no underlying solid color we can read:
1114
+ // • on body/html: assume white. Body-level gradients are almost
1115
+ // always decorative texture (paper grain, noise) on top of a
1116
+ // solid bg-color the page set via `background: var(--paper)`
1117
+ // shorthand — which jsdom can't decompose into bg-color. The
1118
+ // downstream gradient-stops fallback path produces catastrophic
1119
+ // false positives in this case (gradient noise stops have
1120
+ // accidental browns/blacks that look like card backgrounds).
1121
+ // • on other elements: bail to null and let the caller fall back
1122
+ // to gradient stops (gradient buttons / hero sections are real
1123
+ // bgs worth checking against).
1124
+ if (hasGradientOrUrl) {
1125
+ if (current.tagName === 'BODY' || current.tagName === 'HTML') {
1126
+ return { r: 255, g: 255, b: 255, a: 1 };
1127
+ }
1128
+ return null;
1129
+ }
852
1130
  current = current.parentElement;
853
1131
  }
854
1132
  return { r: 255, g: 255, b: 255 };
@@ -880,6 +1158,82 @@ function resolveGradientStops(el, win) {
880
1158
  return null;
881
1159
  }
882
1160
 
1161
+ // Parse a single CSS length token to pixels. Accepts "12px", "50%", a
1162
+ // shorthand like "12px 4px" (uses the first value), or empty / null.
1163
+ // Returns the pixel value, or null when the input is unparseable.
1164
+ // Percentages convert against `widthPx` when one is supplied. Without a
1165
+ // usable width (jsdom returns "auto" for many real-world elements,
1166
+ // which parseFloat collapses to 0), fall back to the raw percentage
1167
+ // number so callers gating on `> 0` (border-accent-on-rounded,
1168
+ // isCardLike's hasRadius) still see a positive value, matching the
1169
+ // original parseFloat("50%") === 50 behavior.
1170
+ function parseRadiusToPx(value, widthPx) {
1171
+ if (!value || typeof value !== 'string') return null;
1172
+ const trimmed = value.trim();
1173
+ if (!trimmed) return null;
1174
+ const first = trimmed.split(/\s+/)[0];
1175
+ const num = parseFloat(first);
1176
+ if (Number.isNaN(num)) return null;
1177
+ if (/%$/.test(first)) {
1178
+ if (widthPx && widthPx > 0) return (num / 100) * widthPx;
1179
+ return num;
1180
+ }
1181
+ return num;
1182
+ }
1183
+
1184
+ // jsdom from 29.0.2 onward returns "" for the `border-radius` shorthand
1185
+ // in computed style and "0" for longhand reads when the source rule used
1186
+ // the shorthand. The rule engine relied on parseFloat(style.borderRadius)
1187
+ // to identify circular avatars (border-radius >= width/2) and rounded
1188
+ // cards (border-radius > 0); both checks broke silently. This helper
1189
+ // recovers the radius via a chain of fallbacks. Browsers resolve the
1190
+ // shorthand correctly and exit on the first line.
1191
+ function resolveBorderRadiusPx(el, style, widthPx, win) {
1192
+ const fromComputed = parseRadiusToPx(style.borderRadius, widthPx);
1193
+ if (fromComputed !== null) return fromComputed;
1194
+
1195
+ if (IS_BROWSER || !win) return 0;
1196
+
1197
+ const fromLonghand = parseRadiusToPx(style.borderTopLeftRadius, widthPx);
1198
+ if (fromLonghand !== null && fromLonghand > 0) return fromLonghand;
1199
+
1200
+ const fromInlineProp = parseRadiusToPx(el.style?.borderRadius, widthPx);
1201
+ if (fromInlineProp !== null) return fromInlineProp;
1202
+
1203
+ const rawStyle = el.getAttribute?.('style') || '';
1204
+ const inlineMatch = rawStyle.match(/border-radius\s*:\s*([^;]+)/i);
1205
+ if (inlineMatch) {
1206
+ const fromRaw = parseRadiusToPx(inlineMatch[1].trim(), widthPx);
1207
+ if (fromRaw !== null) return fromRaw;
1208
+ }
1209
+
1210
+ // Walk every stylesheet looking for matching rules. Take the maximum
1211
+ // pixel value across all matches so a circle declaration overridden by
1212
+ // a more specific rounded-square selector still registers as a circle
1213
+ // for the exclusion check (better to under-flag than to false-positive
1214
+ // on round avatars).
1215
+ let max = 0;
1216
+ const sheets = win.document?.styleSheets;
1217
+ if (sheets) {
1218
+ for (const sheet of sheets) {
1219
+ let rules;
1220
+ try { rules = sheet.cssRules || []; } catch { continue; }
1221
+ for (const rule of rules) {
1222
+ if (!rule.style || !rule.selectorText) continue;
1223
+ let matches = false;
1224
+ try { matches = el.matches(rule.selectorText); } catch { continue; }
1225
+ if (!matches) continue;
1226
+ const ruleValue = rule.style.borderRadius
1227
+ || (rule.style.getPropertyValue && rule.style.getPropertyValue('border-radius'))
1228
+ || rule.style.borderTopLeftRadius;
1229
+ const px = parseRadiusToPx(ruleValue, widthPx);
1230
+ if (px !== null && px > max) max = px;
1231
+ }
1232
+ }
1233
+ }
1234
+ return max;
1235
+ }
1236
+
883
1237
  // ─── Section 5: Element Adapters ────────────────────────────────────────────
884
1238
 
885
1239
  // Browser adapters — call getComputedStyle/getBoundingClientRect on live DOM
@@ -901,7 +1255,9 @@ function checkElementBordersDOM(el) {
901
1255
 
902
1256
  function checkElementColorsDOM(el) {
903
1257
  const tag = el.tagName.toLowerCase();
904
- if (SAFE_TAGS.has(tag)) return [];
1258
+ // No early SAFE_TAGS bail here — checkColors() does its own gating that
1259
+ // includes the styled-button exception for <a> / <button> with their own
1260
+ // opaque background. Bailing here would prevent that exception from firing.
905
1261
  const rect = el.getBoundingClientRect();
906
1262
  if (rect.width < 10 || rect.height < 10) return [];
907
1263
  const style = getComputedStyle(el);
@@ -911,7 +1267,7 @@ function checkElementColorsDOM(el) {
911
1267
  return checkColors({
912
1268
  tag,
913
1269
  textColor: parseRgb(style.color),
914
- bgColor: parseRgb(style.backgroundColor),
1270
+ bgColor: readOwnBackgroundColor(el, style),
915
1271
  effectiveBg,
916
1272
  effectiveBgStops: effectiveBg ? null : resolveGradientStops(el),
917
1273
  fontSize: parseFloat(style.fontSize) || 16,
@@ -959,6 +1315,274 @@ function checkElementIconTileDOM(el) {
959
1315
  });
960
1316
  }
961
1317
 
1318
+ function checkElementItalicSerifDOM(el) {
1319
+ const tag = el.tagName.toLowerCase();
1320
+ if (tag !== 'h1' && tag !== 'h2') return [];
1321
+ const style = getComputedStyle(el);
1322
+ return checkItalicSerif({
1323
+ tag,
1324
+ fontStyle: style.fontStyle || '',
1325
+ fontFamily: style.fontFamily || '',
1326
+ fontSize: parseFloat(style.fontSize) || 0,
1327
+ headingText: el.textContent || '',
1328
+ });
1329
+ }
1330
+
1331
+ function checkElementHeroEyebrowDOM(el) {
1332
+ const tag = el.tagName.toLowerCase();
1333
+ if (tag !== 'h1') return [];
1334
+ const sibling = el.previousElementSibling;
1335
+ if (!sibling) return [];
1336
+ const headStyle = getComputedStyle(el);
1337
+ const sibStyle = getComputedStyle(sibling);
1338
+ return checkHeroEyebrow({
1339
+ headingTag: tag,
1340
+ headingText: el.textContent || '',
1341
+ headingFontSize: parseFloat(headStyle.fontSize) || 0,
1342
+ siblingTag: sibling.tagName.toLowerCase(),
1343
+ siblingText: sibling.textContent || '',
1344
+ siblingTextTransform: sibStyle.textTransform || '',
1345
+ siblingFontSize: parseFloat(sibStyle.fontSize) || 0,
1346
+ siblingLetterSpacing: parseFloat(sibStyle.letterSpacing) || 0,
1347
+ siblingFontWeight: sibStyle.fontWeight || '',
1348
+ siblingColor: sibStyle.color || '',
1349
+ });
1350
+ }
1351
+
1352
+ // Build a map of CSS custom properties declared on :root / :host / html.
1353
+ // Used to resolve var(--X) refs that jsdom returns verbatim in
1354
+ // getComputedStyle. Tailwind v4 routes every utility class through
1355
+ // CSS vars (font-weight: var(--font-weight-bold), font-size:
1356
+ // var(--text-xs), letter-spacing: var(--tracking-widest)), so without
1357
+ // resolution every style-based check silently fails on Tailwind v4
1358
+ // builds — the values come back as literal "var(--font-weight-bold)"
1359
+ // strings and parseFloat returns NaN.
1360
+ function buildCustomPropMap(document) {
1361
+ const map = new Map();
1362
+ let sheets;
1363
+ try { sheets = Array.from(document.styleSheets || []); }
1364
+ catch { return map; }
1365
+ for (const sheet of sheets) {
1366
+ let rules;
1367
+ try { rules = Array.from(sheet.cssRules || []); }
1368
+ catch { continue; }
1369
+ for (const rule of rules) {
1370
+ // Style rules only (type 1). Walk @media / @supports if present.
1371
+ if (rule.type === 4 /* MEDIA_RULE */ || rule.type === 12 /* SUPPORTS_RULE */) {
1372
+ try { rules.push(...Array.from(rule.cssRules || [])); } catch { /* ignore */ }
1373
+ continue;
1374
+ }
1375
+ if (rule.type !== 1 /* STYLE_RULE */) continue;
1376
+ const sel = rule.selectorText || '';
1377
+ if (!/(^|,\s*)(:root|html|:host)\b/i.test(sel)) continue;
1378
+ const style = rule.style;
1379
+ if (!style) continue;
1380
+ for (let i = 0; i < style.length; i++) {
1381
+ const prop = style[i];
1382
+ if (!prop || !prop.startsWith('--')) continue;
1383
+ const val = style.getPropertyValue(prop).trim();
1384
+ if (val) map.set(prop, val);
1385
+ }
1386
+ }
1387
+ }
1388
+ return map;
1389
+ }
1390
+
1391
+ // Resolve var(--X[, fallback]) refs in a computed-style value string.
1392
+ // Recurses up to 8 levels for chained refs (--a: var(--b)). Returns
1393
+ // the original string when no refs are present or the chain doesn't
1394
+ // resolve. Safe to call on already-resolved values.
1395
+ function resolveVarRefs(raw, customPropMap, depth = 0) {
1396
+ if (typeof raw !== 'string' || !raw.includes('var(')) return raw;
1397
+ if (depth > 8) return raw;
1398
+ return raw.replace(/var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,\s*([^)]+))?\)/g, (_m, name, fallback) => {
1399
+ const v = customPropMap.get(name);
1400
+ if (v != null) return resolveVarRefs(v, customPropMap, depth + 1);
1401
+ return fallback ? resolveVarRefs(fallback.trim(), customPropMap, depth + 1) : _m;
1402
+ });
1403
+ }
1404
+
1405
+ // OKLCH → sRGB conversion (Björn Ottosson's matrices). L in 0..1 (or %),
1406
+ // C in 0..~0.4 typical, H in degrees. Returns clamped {r,g,b,a:1} in 0..255.
1407
+ // Needed because jsdom doesn't compute oklch() values — getComputedStyle
1408
+ // returns the literal "oklch(...)" string. Without this, the entire
1409
+ // Tailwind v4 color palette (which is OKLCH-based) is invisible to the
1410
+ // detector's contrast / color checks.
1411
+ function oklchToRgb(L, C, H) {
1412
+ const hRad = (H * Math.PI) / 180;
1413
+ const a = C * Math.cos(hRad);
1414
+ const b = C * Math.sin(hRad);
1415
+ const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
1416
+ const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
1417
+ const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
1418
+ const lc = l_ * l_ * l_, mc = m_ * m_ * m_, sc = s_ * s_ * s_;
1419
+ const rLin = 4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc;
1420
+ const gLin = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc;
1421
+ const bLin = -0.0041960863 * lc - 0.7034186147 * mc + 1.7076147010 * sc;
1422
+ const enc = (x) => {
1423
+ const c = Math.max(0, Math.min(1, x));
1424
+ return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
1425
+ };
1426
+ return {
1427
+ r: Math.round(enc(rLin) * 255),
1428
+ g: Math.round(enc(gLin) * 255),
1429
+ b: Math.round(enc(bLin) * 255),
1430
+ a: 1,
1431
+ };
1432
+ }
1433
+
1434
+ // Extended color parser: rgb/rgba/hex/oklch. Returns null on no match.
1435
+ // Use this when the input might be any CSS color form; use plain parseRgb
1436
+ // when you only expect computed rgb() values from real browsers.
1437
+ function parseAnyColor(s) {
1438
+ if (!s || typeof s !== 'string') return null;
1439
+ const str = s.trim();
1440
+ if (str === 'transparent' || str === 'currentcolor' || str === 'inherit') return null;
1441
+ let m;
1442
+ m = str.match(/rgba?\(\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)(?:\s*[,/]\s*([\d.]+))?\s*\)/);
1443
+ 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 };
1444
+ m = str.match(/^#([0-9a-f]{3,8})$/i);
1445
+ if (m) {
1446
+ const h = m[1];
1447
+ if (h.length === 3 || h.length === 4) {
1448
+ return {
1449
+ r: parseInt(h[0] + h[0], 16),
1450
+ g: parseInt(h[1] + h[1], 16),
1451
+ b: parseInt(h[2] + h[2], 16),
1452
+ a: h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1,
1453
+ };
1454
+ }
1455
+ if (h.length === 6 || h.length === 8) {
1456
+ return {
1457
+ r: parseInt(h.slice(0, 2), 16),
1458
+ g: parseInt(h.slice(2, 4), 16),
1459
+ b: parseInt(h.slice(4, 6), 16),
1460
+ a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
1461
+ };
1462
+ }
1463
+ }
1464
+ // OKLCH parser. Tailwind v4's CSS minifier squishes the space after
1465
+ // `%` ("21.5%.02 50"), so the separator between L and C may be absent.
1466
+ // Match L (with optional %), then C and H separated permissively.
1467
+ m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?\s*\)/i);
1468
+ if (m) {
1469
+ const Lnum = parseFloat(m[1]);
1470
+ const L = m[2] === '%' ? Lnum / 100 : Lnum;
1471
+ return oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]));
1472
+ }
1473
+ return null;
1474
+ }
1475
+
1476
+ // Resolve var() refs in a color string (via customPropMap), then parse.
1477
+ // Returns null on any failure. Used in jsdom-mode paths where
1478
+ // getComputedStyle returns literal "var(--X)" or "oklch(...)" strings.
1479
+ function parseColorResolved(str, customPropMap) {
1480
+ if (!str) return null;
1481
+ const resolved = customPropMap ? resolveVarRefs(str, customPropMap) : str;
1482
+ return parseAnyColor(resolved);
1483
+ }
1484
+
1485
+ const REPEATED_KICKER_SKIP_SELECTOR = [
1486
+ 'nav',
1487
+ 'form',
1488
+ 'table',
1489
+ 'thead',
1490
+ 'tbody',
1491
+ 'tfoot',
1492
+ 'figure',
1493
+ 'figcaption',
1494
+ 'ol',
1495
+ 'ul',
1496
+ 'li',
1497
+ '[role="navigation"]',
1498
+ '[aria-label*="breadcrumb" i]',
1499
+ '[class*="breadcrumb" i]',
1500
+ '[data-impeccable-allow-kickers]',
1501
+ ].join(',');
1502
+
1503
+ function cleanInlineText(el) {
1504
+ return [...el.childNodes]
1505
+ .filter(n => n.nodeType === 3)
1506
+ .map(n => n.textContent)
1507
+ .join(' ')
1508
+ .replace(/\s+/g, ' ')
1509
+ .trim();
1510
+ }
1511
+
1512
+ function isRepeatedKickerCandidate(opts) {
1513
+ const {
1514
+ headingTag,
1515
+ headingText,
1516
+ headingFontSize,
1517
+ kickerTag,
1518
+ kickerText,
1519
+ kickerTextTransform,
1520
+ kickerFontSize,
1521
+ kickerLetterSpacing,
1522
+ } = opts;
1523
+ if (!['h2', 'h3', 'h4'].includes(headingTag)) return false;
1524
+ if (!headingText || headingText.length < 3) return false;
1525
+ if (!(headingFontSize >= 20)) return false;
1526
+ if (!kickerTag || HEADING_TAGS.has(kickerTag)) return false;
1527
+ if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false;
1528
+ if (!kickerText || kickerText.length < 2 || kickerText.length > 34) return false;
1529
+ if (/^step\s*\d+/i.test(kickerText) || /^\d{1,2}$/.test(kickerText)) return false;
1530
+
1531
+ const isUppercased = kickerTextTransform === 'uppercase'
1532
+ || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText));
1533
+ if (!isUppercased) return false;
1534
+ if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false;
1535
+ const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08);
1536
+ if (!(kickerLetterSpacing >= minTrackedSpacing)) return false;
1537
+ return true;
1538
+ }
1539
+
1540
+ function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpacing) {
1541
+ const candidates = [];
1542
+ for (const heading of doc.querySelectorAll('h2, h3, h4')) {
1543
+ if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
1544
+ const kicker = heading.previousElementSibling;
1545
+ if (!kicker || kicker.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
1546
+
1547
+ const headingStyle = getStyle(heading);
1548
+ const kickerStyle = getStyle(kicker);
1549
+ const headingText = (heading.textContent || '').replace(/\s+/g, ' ').trim();
1550
+ const kickerText = cleanInlineText(kicker) || (kicker.textContent || '').replace(/\s+/g, ' ').trim();
1551
+ const headingFontSize = resolveLetterSpacing(headingStyle.fontSize || '', 16) || parseFloat(headingStyle.fontSize) || 0;
1552
+ const kickerFontSize = resolveLetterSpacing(kickerStyle.fontSize || '', 16) || parseFloat(kickerStyle.fontSize) || 0;
1553
+ const kickerLetterSpacing = resolveLetterSpacing(kickerStyle.letterSpacing || '', kickerFontSize);
1554
+
1555
+ if (!isRepeatedKickerCandidate({
1556
+ headingTag: heading.tagName.toLowerCase(),
1557
+ headingText,
1558
+ headingFontSize,
1559
+ kickerTag: kicker.tagName.toLowerCase(),
1560
+ kickerText,
1561
+ kickerTextTransform: kickerStyle.textTransform || '',
1562
+ kickerFontSize,
1563
+ kickerLetterSpacing,
1564
+ })) {
1565
+ continue;
1566
+ }
1567
+
1568
+ candidates.push({
1569
+ headingTag: heading.tagName.toLowerCase(),
1570
+ headingText: headingText.replace(/^"|"$/g, '').slice(0, 60),
1571
+ kickerText: kickerText.slice(0, 40),
1572
+ });
1573
+ }
1574
+ return candidates;
1575
+ }
1576
+
1577
+ function checkRepeatedSectionKickersDOM() {
1578
+ const candidates = collectRepeatedSectionKickerCandidates(
1579
+ document,
1580
+ (el) => getComputedStyle(el),
1581
+ (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
1582
+ );
1583
+ return checkRepeatedSectionKickers({ candidates });
1584
+ }
1585
+
962
1586
  function checkElementMotionDOM(el) {
963
1587
  const tag = el.tagName.toLowerCase();
964
1588
  if (SAFE_TAGS.has(tag)) return [];
@@ -1109,7 +1733,7 @@ function resolveLengthPx(value, fontSizePx) {
1109
1733
  // Both adapters resolve font-size, line-height and letter-spacing to pixels
1110
1734
  // before calling this so the pure function only deals with numbers.
1111
1735
  function checkQuality(opts) {
1112
- const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80 } = opts;
1736
+ const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0 } = opts;
1113
1737
  const findings = [];
1114
1738
  // Skip browser extension injected elements
1115
1739
  const elId = el.id || '';
@@ -1160,6 +1784,40 @@ function checkQuality(opts) {
1160
1784
  }
1161
1785
  }
1162
1786
 
1787
+ // --- Body text touching viewport edge --- (browser-only: needs rect)
1788
+ // Catches the failure mode where the agent ships body paragraphs
1789
+ // with NO container providing horizontal padding — text bleeds
1790
+ // directly to the viewport edge. Different from cramped-padding,
1791
+ // which requires a colored/bordered container. Here the failure
1792
+ // is the absence of the container entirely.
1793
+ //
1794
+ // Gate aggressively to avoid false positives:
1795
+ // - <p> or <li> only (body content; not headings, not nav, not
1796
+ // wrappers)
1797
+ // - text > 40 chars (paragraph-like, not a label)
1798
+ // - rect.width > 50% of viewport (real body, not a pull-quote)
1799
+ // - rect.left < 16 OR rect.right > viewport - 16 (actually
1800
+ // touching the edge)
1801
+ // - not inside <nav> or <header> (those legitimately bleed)
1802
+ // - element itself has no background-color (intentional full-bleed
1803
+ // sections set a bg-color and provide their own internal padding)
1804
+ if (rect && hasDirectText && textLen > 40 && ['P', 'LI'].includes(tag.toUpperCase()) && viewportWidth > 0) {
1805
+ const inNavHeader = el.closest && (el.closest('nav') || el.closest('header'));
1806
+ const hasOwnBg = style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)' && style.backgroundColor !== 'transparent';
1807
+ const isPositioned = ['fixed', 'absolute'].includes(style.position || '');
1808
+ const widthRatio = rect.width / viewportWidth;
1809
+ const leftClose = rect.left < 16;
1810
+ const rightClose = rect.right > viewportWidth - 16;
1811
+ if (!inNavHeader && !hasOwnBg && !isPositioned && widthRatio > 0.5 && (leftClose || rightClose)) {
1812
+ const which = leftClose && rightClose
1813
+ ? `left ${Math.round(rect.left)}px / right ${Math.round(viewportWidth - rect.right)}px`
1814
+ : leftClose
1815
+ ? `left ${Math.round(rect.left)}px`
1816
+ : `right ${Math.round(viewportWidth - rect.right)}px`;
1817
+ findings.push({ id: 'body-text-viewport-edge', snippet: `<${tag.toLowerCase()}> with ${textLen}-char body bleeds to viewport edge (${which})` });
1818
+ }
1819
+ }
1820
+
1163
1821
  // --- Tight line height ---
1164
1822
  if (hasDirectText && textLen > 50 && !['h1','h2','h3','h4','h5','h6'].includes(tag)) {
1165
1823
  if (lineHeightPx != null && fontSize > 0) {
@@ -1221,7 +1879,8 @@ function checkElementQualityDOM(el) {
1221
1879
  const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize);
1222
1880
  const rect = el.getBoundingClientRect();
1223
1881
  const lineMax = (typeof window !== 'undefined' && window.__IMPECCABLE_CONFIG__?.lineLengthMax) || 80;
1224
- return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax });
1882
+ const viewportWidth = (typeof window !== 'undefined' ? window.innerWidth : 0) || 0;
1883
+ return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax, viewportWidth });
1225
1884
  }
1226
1885
 
1227
1886
  // Pure page-level skipped-heading walk. Takes a Document so it works in both
@@ -1266,7 +1925,7 @@ function checkElementQuality(el, style, tag, window) {
1266
1925
  return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null });
1267
1926
  }
1268
1927
 
1269
- function checkElementBorders(tag, style, overrides) {
1928
+ function checkElementBorders(tag, style, overrides, resolvedRadius) {
1270
1929
  const sides = ['Top', 'Right', 'Bottom', 'Left'];
1271
1930
  const widths = {}, colors = {};
1272
1931
  for (const s of sides) {
@@ -1286,18 +1945,58 @@ function checkElementBorders(tag, style, overrides) {
1286
1945
  colors[s] = overrides[s].color;
1287
1946
  }
1288
1947
  }
1289
- return checkBorders(tag, widths, colors, parseFloat(style.borderRadius) || 0);
1948
+ // resolvedRadius lets the caller pre-resolve the radius via
1949
+ // resolveBorderRadiusPx so the value survives jsdom 29.1.0's broken
1950
+ // shorthand serialization. Falls back to the computed value for tests
1951
+ // and browser callers that don't pre-resolve.
1952
+ const radius = resolvedRadius != null
1953
+ ? resolvedRadius
1954
+ : (parseFloat(style.borderRadius) || 0);
1955
+ return checkBorders(tag, widths, colors, radius);
1290
1956
  }
1291
1957
 
1292
- function checkElementColors(el, style, tag, window) {
1958
+ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInheritRule) {
1293
1959
  const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
1294
1960
  const hasDirectText = directText.trim().length > 0;
1295
1961
 
1296
- const effectiveBg = resolveBackground(el, window);
1962
+ const effectiveBg = resolveBackground(el, window, customPropMap);
1963
+ // jsdom returns literal "var(--X)" / "oklch(...)" for color, so plain
1964
+ // parseRgb misses Tailwind-tokenized text colors. Resolve through the
1965
+ // customPropMap first; fall back to parseRgb for vanilla rgb() pages.
1966
+ let textColor = customPropMap ? parseColorResolved(style.color, customPropMap) : null;
1967
+ if (!textColor) textColor = parseRgb(style.color);
1968
+
1969
+ // Anchor-inherit FP workaround: jsdom's UA stylesheet has `:link { color:
1970
+ // blue }` at high specificity. The page's `a { color: inherit }` rule
1971
+ // (Tailwind v4 preflight) loses to jsdom even though it WINS in real
1972
+ // browsers (Chrome's UA wraps :link in :where() — zero specificity).
1973
+ // When the page declares the inherit rule AND we see jsdom's default
1974
+ // link blue on an anchor, walk to the nearest non-anchor ancestor and
1975
+ // use its color instead.
1976
+ if (
1977
+ hasAnchorInheritRule &&
1978
+ textColor &&
1979
+ textColor.r === 0 && textColor.g === 0 && textColor.b === 238 &&
1980
+ (tag === 'a' || el.closest?.('a'))
1981
+ ) {
1982
+ let cur = el.parentElement;
1983
+ while (cur && cur.tagName !== 'HTML') {
1984
+ if (cur.tagName !== 'A') {
1985
+ const ps = window.getComputedStyle(cur);
1986
+ const inh = (customPropMap ? parseColorResolved(ps.color, customPropMap) : null) || parseRgb(ps.color);
1987
+ if (inh && !(inh.r === 0 && inh.g === 0 && inh.b === 238)) {
1988
+ textColor = inh;
1989
+ break;
1990
+ }
1991
+ }
1992
+ cur = cur.parentElement;
1993
+ }
1994
+ }
1995
+
1297
1996
  return checkColors({
1298
1997
  tag,
1299
- textColor: parseRgb(style.color),
1300
- bgColor: parseRgb(style.backgroundColor),
1998
+ textColor,
1999
+ bgColor: readOwnBackgroundColor(el, style),
1301
2000
  effectiveBg,
1302
2001
  effectiveBgStops: effectiveBg ? null : resolveGradientStops(el, window),
1303
2002
  fontSize: parseFloat(style.fontSize) || 16,
@@ -1341,12 +2040,63 @@ function checkElementIconTile(el, tag, window) {
1341
2040
  siblingBgColor: parseRgb(sibStyle.backgroundColor),
1342
2041
  siblingBgImage: sibStyle.backgroundImage || '',
1343
2042
  siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
1344
- siblingBorderRadius: parseFloat(sibStyle.borderRadius) || 0,
2043
+ siblingBorderRadius: resolveBorderRadiusPx(sibling, sibStyle, sibWidth, window),
1345
2044
  hasIconChild: !!iconChild || hasInlineEmojiIcon,
1346
2045
  iconChildWidth: iconWidth,
1347
2046
  });
1348
2047
  }
1349
2048
 
2049
+ function checkElementItalicSerif(el, style, tag) {
2050
+ if (tag !== 'h1' && tag !== 'h2') return [];
2051
+ return checkItalicSerif({
2052
+ tag,
2053
+ fontStyle: style.fontStyle || '',
2054
+ fontFamily: style.fontFamily || '',
2055
+ fontSize: parseFloat(style.fontSize) || 0,
2056
+ headingText: el.textContent || '',
2057
+ });
2058
+ }
2059
+
2060
+ function checkElementHeroEyebrow(el, style, tag, window, customPropMap) {
2061
+ if (tag !== 'h1') return [];
2062
+ const sibling = el.previousElementSibling;
2063
+ if (!sibling) return [];
2064
+ const sibStyle = window.getComputedStyle(sibling);
2065
+ // Resolve Tailwind v4 CSS-variable wrappers (font-weight:var(--font-weight-bold)
2066
+ // etc.) before parsing. jsdom returns these verbatim from getComputedStyle;
2067
+ // without resolution every style-based gate fails silently on Tailwind v4 builds.
2068
+ const fontSizeRaw = customPropMap ? resolveVarRefs(sibStyle.fontSize, customPropMap) : sibStyle.fontSize;
2069
+ const fontWeightRaw = customPropMap ? resolveVarRefs(sibStyle.fontWeight, customPropMap) : sibStyle.fontWeight;
2070
+ const letterSpacingRaw = customPropMap ? resolveVarRefs(sibStyle.letterSpacing, customPropMap) : sibStyle.letterSpacing;
2071
+ const colorRaw = customPropMap ? resolveVarRefs(sibStyle.color, customPropMap) : sibStyle.color;
2072
+ const headingFontSizeRaw = customPropMap ? resolveVarRefs(style.fontSize, customPropMap) : style.fontSize;
2073
+ const siblingFontSize = parseFloat(fontSizeRaw) || 0;
2074
+ // resolveLengthPx returns null for 'normal' / 'auto'; coerce to 0 so the
2075
+ // gate falls through cleanly. jsdom returns letter-spacing verbatim
2076
+ // (e.g. '0.15em'), unlike real browsers, so this conversion is required.
2077
+ return checkHeroEyebrow({
2078
+ headingTag: tag,
2079
+ headingText: el.textContent || '',
2080
+ headingFontSize: parseFloat(headingFontSizeRaw) || 0,
2081
+ siblingTag: sibling.tagName.toLowerCase(),
2082
+ siblingText: sibling.textContent || '',
2083
+ siblingTextTransform: sibStyle.textTransform || '',
2084
+ siblingFontSize,
2085
+ siblingLetterSpacing: resolveLengthPx(letterSpacingRaw, siblingFontSize) || 0,
2086
+ siblingFontWeight: fontWeightRaw || '',
2087
+ siblingColor: colorRaw || '',
2088
+ });
2089
+ }
2090
+
2091
+ function checkRepeatedSectionKickersFromDoc(doc, win) {
2092
+ const candidates = collectRepeatedSectionKickerCandidates(
2093
+ doc,
2094
+ (el) => win.getComputedStyle(el),
2095
+ (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
2096
+ );
2097
+ return checkRepeatedSectionKickers({ candidates });
2098
+ }
2099
+
1350
2100
  function checkElementMotion(tag, style) {
1351
2101
  return checkMotion({
1352
2102
  tag,
@@ -1560,7 +2310,8 @@ function isCardLike(el, win) {
1560
2310
  const hasShadow = (style.boxShadow && style.boxShadow !== 'none') ||
1561
2311
  /\bshadow(?:-sm|-md|-lg|-xl|-2xl)?\b/.test(cls) || /box-shadow/i.test(rawStyle);
1562
2312
  const hasBorder = /\bborder\b/.test(cls);
1563
- const hasRadius = (parseFloat(style.borderRadius) || 0) > 0 ||
2313
+ const widthPx = parseFloat(style.width) || 0;
2314
+ const hasRadius = resolveBorderRadiusPx(el, style, widthPx, win) > 0 ||
1564
2315
  /\brounded(?:-sm|-md|-lg|-xl|-2xl|-full)?\b/.test(cls) || /border-radius/i.test(rawStyle);
1565
2316
  const hasBg = /\bbg-(?:white|gray-\d+|slate-\d+)\b/.test(cls) ||
1566
2317
  /background(?:-color)?\s*:\s*(?!transparent)/i.test(rawStyle);
@@ -2199,6 +2950,7 @@ if (IS_BROWSER) {
2199
2950
  return {
2200
2951
  type: f.type || f.id,
2201
2952
  category: ap ? ap.category : 'quality',
2953
+ severity: ap?.severity || 'warning',
2202
2954
  detail: f.detail || f.snippet,
2203
2955
  name: ap ? ap.name : (f.type || f.id),
2204
2956
  description: ap ? ap.description : '',
@@ -2241,6 +2993,9 @@ if (IS_BROWSER) {
2241
2993
  // Skip browser extension elements (Claude, etc.)
2242
2994
  const elId = el.id || '';
2243
2995
  if (elId.startsWith('claude-') || elId.startsWith('cic-')) continue;
2996
+ // Skip the impeccable live-mode overlay (highlight, tooltip, bar, picker, toast).
2997
+ // These are inspector chrome, not part of the user's design.
2998
+ if (el.closest('[id^="impeccable-live-"]')) continue;
2244
2999
  // Skip html/body -- page-level findings go in the banner, not a full-page overlay
2245
3000
  if (el === document.body || el === document.documentElement) continue;
2246
3001
 
@@ -2251,6 +3006,8 @@ if (IS_BROWSER) {
2251
3006
  ...checkElementGlowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
2252
3007
  ...checkElementAIPaletteDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
2253
3008
  ...checkElementIconTileDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
3009
+ ...checkElementItalicSerifDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
3010
+ ...checkElementHeroEyebrowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
2254
3011
  ...checkElementQualityDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
2255
3012
  ].filter(f => _ruleOk(f.type));
2256
3013
 
@@ -2268,6 +3025,14 @@ if (IS_BROWSER) {
2268
3025
  allFindings.push({ el: document.body, findings: typoFindings });
2269
3026
  }
2270
3027
 
3028
+ const sectionKickerFindings = checkRepeatedSectionKickersDOM()
3029
+ .map(f => ({ type: f.id, detail: f.snippet }))
3030
+ .filter(f => _ruleOk(f.type));
3031
+ if (sectionKickerFindings.length > 0) {
3032
+ pageLevelFindings.push(...sectionKickerFindings);
3033
+ allFindings.push({ el: document.body, findings: sectionKickerFindings });
3034
+ }
3035
+
2271
3036
  const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
2272
3037
  for (const f of layoutFindings) {
2273
3038
  const el = f.el || document.body;
@@ -2294,7 +3059,14 @@ if (IS_BROWSER) {
2294
3059
  }
2295
3060
 
2296
3061
  // Regex-on-HTML checks (shared with Node)
2297
- const htmlPatternFindings = checkHtmlPatterns(document.documentElement.outerHTML);
3062
+ // Clone the document and strip impeccable-live overlay nodes before the
3063
+ // regex scan, so the inspector's own inline styles (transitions on top/
3064
+ // left/width/height, etc.) don't register as page anti-patterns.
3065
+ const docClone = document.documentElement.cloneNode(true);
3066
+ for (const node of docClone.querySelectorAll('[id^="impeccable-live-"]')) {
3067
+ node.remove();
3068
+ }
3069
+ const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
2298
3070
  if (htmlPatternFindings.length > 0) {
2299
3071
  const mapped = htmlPatternFindings.map(f => ({ type: f.id, detail: f.snippet })).filter(f => _ruleOk(f.type));
2300
3072
  pageLevelFindings.push(...mapped);
@@ -2399,7 +3171,7 @@ function getAP(id) {
2399
3171
 
2400
3172
  function finding(id, filePath, snippet, line = 0) {
2401
3173
  const ap = getAP(id);
2402
- return { antipattern: id, name: ap.name, description: ap.description, file: filePath, line, snippet };
3174
+ return { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', file: filePath, line, snippet };
2403
3175
  }
2404
3176
 
2405
3177
  /** Check if content looks like a full page (not a component/partial) */
@@ -2580,6 +3352,48 @@ function buildBorderOverrideMap(document, window) {
2580
3352
  return map;
2581
3353
  }
2582
3354
 
3355
+ // Strip `@layer NAME { … }` wrappers from a CSS / HTML source, leaving
3356
+ // the inner rules as flat CSS. jsdom doesn't implement CSS @layer, so
3357
+ // any rule inside a layer block becomes invisible to getComputedStyle.
3358
+ // Tailwind v4 makes this ubiquitous: every utility class lives in
3359
+ // `@layer utilities`, and Preflight lives in `@layer base`. Without
3360
+ // unwrapping, every Tailwind-styled element returns empty computed
3361
+ // styles. We walk the source character-by-character, balancing braces
3362
+ // so we correctly handle nested style rules inside the layer block.
3363
+ function unwrapCssAtLayer(source) {
3364
+ if (!source || !source.includes('@layer')) return source;
3365
+ // Find `@layer <name>? {` openers. The match starts at the @, and
3366
+ // we then balance braces from the opening { onward.
3367
+ const re = /@layer\b[^{;]*\{/g;
3368
+ let out = '';
3369
+ let lastIdx = 0;
3370
+ let m;
3371
+ while ((m = re.exec(source)) !== null) {
3372
+ const openStart = m.index;
3373
+ const openEnd = m.index + m[0].length; // position right after `{`
3374
+ let depth = 1;
3375
+ let i = openEnd;
3376
+ while (i < source.length && depth > 0) {
3377
+ const c = source.charCodeAt(i);
3378
+ if (c === 0x7b /* { */) depth++;
3379
+ else if (c === 0x7d /* } */) depth--;
3380
+ i++;
3381
+ }
3382
+ if (depth !== 0) {
3383
+ // Unbalanced — bail and return source unchanged.
3384
+ return source;
3385
+ }
3386
+ // Emit everything before the @layer, then the inner contents
3387
+ // (between the opening { and the matched closing }), then advance.
3388
+ out += source.slice(lastIdx, openStart);
3389
+ out += source.slice(openEnd, i - 1); // i-1 = position of the closing }
3390
+ lastIdx = i;
3391
+ re.lastIndex = i;
3392
+ }
3393
+ out += source.slice(lastIdx);
3394
+ return out;
3395
+ }
3396
+
2583
3397
  // ---------------------------------------------------------------------------
2584
3398
  // jsdom detection (default for HTML files)
2585
3399
  // ---------------------------------------------------------------------------
@@ -2616,6 +3430,16 @@ async function detectHtml(filePath) {
2616
3430
  }
2617
3431
  }
2618
3432
 
3433
+ // jsdom does not implement CSS `@layer` rules — every utility class
3434
+ // inside `@layer utilities { ... }` is silently ignored, so computed
3435
+ // styles come back empty. Tailwind v4 wraps every utility class in
3436
+ // an @layer, which means jsdom returns empty strings for fontSize /
3437
+ // fontWeight / textTransform / letterSpacing on every Tailwind-styled
3438
+ // element. Strip the @layer wrapper, keep the inner rules as flat
3439
+ // CSS that jsdom can process. The cascade ordering @layer provides
3440
+ // doesn't matter for our checks — we only read computed values.
3441
+ processedHtml = unwrapCssAtLayer(processedHtml);
3442
+
2619
3443
  const dom = new JSDOM(processedHtml, {
2620
3444
  url: `file://${resolvedPath}`,
2621
3445
  });
@@ -2629,17 +3453,51 @@ async function detectHtml(filePath) {
2629
3453
  // by the border check adapter as a fallback.
2630
3454
  const borderOverrides = buildBorderOverrideMap(document, window);
2631
3455
 
3456
+ // Pre-pass: collect :root / :host / html CSS custom properties so the
3457
+ // checks can resolve var(--X) refs that jsdom returns verbatim from
3458
+ // getComputedStyle. Tailwind v4 wraps every utility-class value in a
3459
+ // CSS var; without this, font-weight / font-size / letter-spacing /
3460
+ // color all come back as literal "var(--X)" strings.
3461
+ const customPropMap = buildCustomPropMap(document);
3462
+
3463
+ // Pre-pass: detect whether the page's CSS declares `a { color: inherit }`
3464
+ // (Tailwind v4 preflight signature). When present, real browsers render
3465
+ // anchors using the cascaded ancestor color, but jsdom's UA stylesheet
3466
+ // applies `:link { color: blue }` at higher specificity, so anchors come
3467
+ // back as `rgb(0, 0, 238)` regardless. checkElementColors uses this
3468
+ // flag to walk for the cascaded color when it sees jsdom's blue default
3469
+ // on an anchor — preventing a whole class of contrast false positives
3470
+ // on Tailwind v4 pages.
3471
+ let hasAnchorInheritRule = false;
3472
+ const scanForAnchorInherit = (rules) => {
3473
+ for (const rule of rules) {
3474
+ if (rule.selectorText === 'a' && rule.style && rule.style.color === 'inherit') return true;
3475
+ // Recurse into @layer / @media / @supports / etc.
3476
+ if (rule.cssRules && scanForAnchorInherit(rule.cssRules)) return true;
3477
+ }
3478
+ return false;
3479
+ };
3480
+ for (const sheet of document.styleSheets) {
3481
+ try {
3482
+ if (scanForAnchorInherit(sheet.cssRules || [])) {
3483
+ hasAnchorInheritRule = true;
3484
+ break;
3485
+ }
3486
+ } catch (e) { /* cross-origin sheet, skip */ }
3487
+ }
3488
+
2632
3489
  // Element-level checks (borders + colors + motion)
2633
3490
  for (const el of document.querySelectorAll('*')) {
2634
3491
  const tag = el.tagName.toLowerCase();
2635
3492
  const style = window.getComputedStyle(el);
2636
- for (const f of checkElementBorders(tag, style, borderOverrides.get(el))) {
3493
+ const resolvedRadius = resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0, window);
3494
+ for (const f of checkElementBorders(tag, style, borderOverrides.get(el), resolvedRadius)) {
2637
3495
  findings.push(finding(f.id, filePath, f.snippet));
2638
3496
  }
2639
- for (const f of checkElementColors(el, style, tag, window)) {
3497
+ for (const f of checkElementColors(el, style, tag, window, customPropMap, hasAnchorInheritRule)) {
2640
3498
  findings.push(finding(f.id, filePath, f.snippet));
2641
3499
  }
2642
- for (const f of checkElementGlow(tag, style, resolveBackground(el.parentElement || el, window))) {
3500
+ for (const f of checkElementGlow(tag, style, resolveBackground(el.parentElement || el, window, customPropMap))) {
2643
3501
  findings.push(finding(f.id, filePath, f.snippet));
2644
3502
  }
2645
3503
  for (const f of checkElementMotion(tag, style)) {
@@ -2648,6 +3506,12 @@ async function detectHtml(filePath) {
2648
3506
  for (const f of checkElementIconTile(el, tag, window)) {
2649
3507
  findings.push(finding(f.id, filePath, f.snippet));
2650
3508
  }
3509
+ for (const f of checkElementItalicSerif(el, style, tag)) {
3510
+ findings.push(finding(f.id, filePath, f.snippet));
3511
+ }
3512
+ for (const f of checkElementHeroEyebrow(el, style, tag, window, customPropMap)) {
3513
+ findings.push(finding(f.id, filePath, f.snippet));
3514
+ }
2651
3515
  for (const f of checkElementQuality(el, style, tag, window)) {
2652
3516
  findings.push(finding(f.id, filePath, f.snippet));
2653
3517
  }
@@ -2658,6 +3522,9 @@ async function detectHtml(filePath) {
2658
3522
  for (const f of checkPageTypography(document, window)) {
2659
3523
  findings.push(finding(f.id, filePath, f.snippet));
2660
3524
  }
3525
+ for (const f of checkRepeatedSectionKickersFromDoc(document, window)) {
3526
+ findings.push(finding(f.id, filePath, f.snippet));
3527
+ }
2661
3528
  for (const f of checkPageLayout(document, window)) {
2662
3529
  findings.push(finding(f.id, filePath, f.snippet));
2663
3530
  }
@@ -2687,7 +3554,7 @@ async function detectUrl(url) {
2687
3554
 
2688
3555
  // Read the browser detection script — reuse it instead of reimplementing
2689
3556
  const browserScriptPath = path.resolve(
2690
- path.dirname(new URL(import.meta.url).pathname),
3557
+ path.dirname(fileURLToPath(import.meta.url)),
2691
3558
  'detect-antipatterns-browser.js'
2692
3559
  );
2693
3560
  let browserScript;
@@ -2774,10 +3641,10 @@ const REGEX_MATCHERS = [
2774
3641
  test: (m, line) => +m[1] >= 3 && hasBorderRadius(line),
2775
3642
  fmt: (m) => m[0] },
2776
3643
  // --- Overused font ---
2777
- { id: 'overused-font', regex: /font-family\s*:\s*['"]?(Inter|Roboto|Open Sans|Lato|Montserrat|Arial|Helvetica)\b/gi,
3644
+ { id: 'overused-font', regex: /font-family\s*:\s*['"]?(Inter|Roboto|Open Sans|Lato|Montserrat|Arial|Helvetica|Fraunces|Geist Sans|Geist Mono|Geist|Mona Sans|Plus Jakarta Sans|Space Grotesk|Recoleta|Instrument Sans)\b/gi,
2778
3645
  test: () => true,
2779
3646
  fmt: (m) => m[0] },
2780
- { id: 'overused-font', regex: /fonts\.googleapis\.com\/css2?\?family=(Inter|Roboto|Open\+Sans|Lato|Montserrat)\b/gi,
3647
+ { id: 'overused-font', regex: /fonts\.googleapis\.com\/css2?\?family=(Inter|Roboto|Open\+Sans|Lato|Montserrat|Fraunces|Plus\+Jakarta\+Sans|Space\+Grotesk|Instrument\+Sans|Mona\+Sans|Geist)\b/gi,
2781
3648
  test: () => true,
2782
3649
  fmt: (m) => `Google Fonts: ${m[1].replace(/\+/g, ' ')}` },
2783
3650
  // --- Pure black background ---
@@ -3326,7 +4193,11 @@ Examples:
3326
4193
  }
3327
4194
 
3328
4195
  async function main() {
3329
- const args = process.argv.slice(2);
4196
+ const args = process.argv.slice(2).map(arg => {
4197
+ if (arg === '-json') return '--json';
4198
+ if (arg === '-fast') return '--fast';
4199
+ return arg;
4200
+ });
3330
4201
  const jsonMode = args.includes('--json');
3331
4202
  const helpMode = args.includes('--help');
3332
4203
  const fastMode = args.includes('--fast');
@@ -3435,131 +4306,14 @@ async function main() {
3435
4306
  }
3436
4307
 
3437
4308
  if (allFindings.length > 0) {
3438
- process.stderr.write(formatFindings(allFindings, jsonMode) + '\n');
4309
+ if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
4310
+ else process.stderr.write(formatFindings(allFindings, false) + '\n');
3439
4311
  process.exit(2);
3440
4312
  }
3441
4313
  if (jsonMode) process.stdout.write('[]\n');
3442
4314
  process.exit(0);
3443
4315
  }
3444
4316
 
3445
- // ---------------------------------------------------------------------------
3446
- // Live detection server
3447
- // ---------------------------------------------------------------------------
3448
-
3449
- async function findOpenPort(start = 8400) {
3450
- const net = await import('node:net');
3451
- return new Promise((resolve) => {
3452
- const server = net.default.createServer();
3453
- server.listen(start, '127.0.0.1', () => {
3454
- const port = server.address().port;
3455
- server.close(() => resolve(port));
3456
- });
3457
- server.on('error', () => resolve(findOpenPort(start + 1)));
3458
- });
3459
- }
3460
-
3461
- const LIVE_PID_FILE = path.join((await import('node:os')).default.tmpdir(), 'impeccable-live.json');
3462
-
3463
- async function liveCli() {
3464
- const args = process.argv.slice(2);
3465
- const helpMode = args.includes('--help');
3466
- const stopMode = args.includes('stop');
3467
- const portArg = args.find(a => a.startsWith('--port='));
3468
- const requestedPort = portArg ? parseInt(portArg.split('=')[1], 10) : null;
3469
-
3470
- if (helpMode) {
3471
- console.log(`Usage: impeccable live [options]
3472
-
3473
- Start a local server that serves the browser detection overlay script.
3474
- Inject the script into any page to scan for anti-patterns in real time.
3475
-
3476
- Commands:
3477
- live Start the server (default)
3478
- live stop Stop a running live server
3479
-
3480
- Options:
3481
- --port=PORT Use a specific port (default: auto-detect unused port)
3482
- --help Show this help message
3483
-
3484
- The server provides:
3485
- /detect.js The detection overlay script (inject via <script> tag)
3486
- /health Health check endpoint
3487
- /stop Stop the server remotely`);
3488
- process.exit(0);
3489
- }
3490
-
3491
- // Stop a running server
3492
- if (stopMode) {
3493
- try {
3494
- const info = JSON.parse(fs.readFileSync(LIVE_PID_FILE, 'utf-8'));
3495
- const res = await fetch(`http://localhost:${info.port}/stop`);
3496
- if (res.ok) {
3497
- console.log(`Stopped live server on port ${info.port}.`);
3498
- }
3499
- } catch {
3500
- console.log('No running live server found.');
3501
- }
3502
- process.exit(0);
3503
- }
3504
-
3505
- const http = await import('node:http');
3506
- const scriptPath = path.join(path.dirname(new URL(import.meta.url).pathname), 'detect-antipatterns-browser.js');
3507
-
3508
- let browserScript;
3509
- try {
3510
- browserScript = fs.readFileSync(scriptPath, 'utf-8');
3511
- } catch {
3512
- process.stderr.write('Error: Browser script not found. Run `npm run build:browser` first.\n');
3513
- process.exit(1);
3514
- }
3515
-
3516
- const port = requestedPort || await findOpenPort();
3517
-
3518
- const shutdown = () => {
3519
- try { fs.unlinkSync(LIVE_PID_FILE); } catch { /* ignore */ }
3520
- server.close();
3521
- process.exit(0);
3522
- };
3523
-
3524
- const server = http.default.createServer((req, res) => {
3525
- // CORS headers for cross-origin injection
3526
- res.setHeader('Access-Control-Allow-Origin', '*');
3527
- res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
3528
- if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
3529
-
3530
- if (req.url === '/detect.js' || req.url === '/') {
3531
- res.writeHead(200, { 'Content-Type': 'application/javascript' });
3532
- res.end(browserScript);
3533
- } else if (req.url === '/health') {
3534
- res.writeHead(200, { 'Content-Type': 'application/json' });
3535
- res.end(JSON.stringify({ status: 'ok', port }));
3536
- } else if (req.url === '/stop') {
3537
- res.writeHead(200, { 'Content-Type': 'text/plain' });
3538
- res.end('stopping');
3539
- shutdown();
3540
- } else {
3541
- res.writeHead(404);
3542
- res.end('Not found');
3543
- }
3544
- });
3545
-
3546
- server.listen(port, '127.0.0.1', () => {
3547
- // Write PID file so `live stop` can find us
3548
- fs.writeFileSync(LIVE_PID_FILE, JSON.stringify({ pid: process.pid, port }));
3549
-
3550
- const url = `http://localhost:${port}`;
3551
- console.log(`Impeccable live detection server running on ${url}\n`);
3552
- console.log(`Inject into any page:`);
3553
- console.log(` const s = document.createElement('script');`);
3554
- console.log(` s.src = '${url}/detect.js';`);
3555
- console.log(` document.head.appendChild(s);\n`);
3556
- console.log(`Stop: npx impeccable live stop`);
3557
- });
3558
-
3559
- process.on('SIGINT', shutdown);
3560
- process.on('SIGTERM', shutdown);
3561
- }
3562
-
3563
4317
  // ---------------------------------------------------------------------------
3564
4318
  // Entry point
3565
4319
  // ---------------------------------------------------------------------------
@@ -3584,7 +4338,6 @@ export {
3584
4338
  buildImportGraph, resolveImport,
3585
4339
  detectFrameworkConfig, isPortListening, FRAMEWORK_CONFIGS,
3586
4340
  main as detectCli,
3587
- liveCli,
3588
4341
  };
3589
4342
 
3590
4343
  // @browser-strip-end