1/**
2 * Anti-Pattern Browser Detector for Impeccable
3 * Copyright (c) 2026 Paul Bakaus
4 * SPDX-License-Identifier: Apache-2.0
5 *
6 * GENERATED -- do not edit. Source: cli/engine/browser/injected/index.mjs
7 * Rebuild: node scripts/build-browser-detector.js
8 *
9 * Usage: <script src="detect-antipatterns-browser.js"></script>
10 * Re-scan: window.impeccableScan()
11 */
12(function () {
13if (typeof window === 'undefined') return;
14// --- cli/engine/shared/constants.mjs ---
15// ─── Section 1: Constants ───────────────────────────────────────────────────
16 
17const SAFE_TAGS = new Set([
18  'blockquote', 'nav', 'a', 'input', 'textarea', 'select',
19  'pre', 'code', 'span', 'th', 'td', 'tr', 'li', 'label',
20  'button', 'hr', 'html', 'head', 'body', 'script', 'style',
21  'link', 'meta', 'title', 'br', 'img', 'svg', 'path', 'circle',
22  'rect', 'line', 'polyline', 'polygon', 'g', 'defs', 'use',
23]);
24 
25// Per-check safe-tags override for the border (side-tab / border-accent)
26// rule. We intentionally re-allow <label> here because card-shaped clickable
27// labels (e.g. .checklist-item wrapping a checkbox + content) are one of the
28// canonical side-tab anti-pattern shapes and must be detected. The rule's
29// other preconditions (non-neutral color, width >= 2px on a single side,
30// radius > 0 or width >= 3, element size >= 20x20 in the browser path)
31// already filter out plain inline form labels so this does not introduce
32// false positives. See modern-color-borders.html for the test matrix.
33const BORDER_SAFE_TAGS = new Set(
34  [...SAFE_TAGS].filter(t => t !== 'label')
35);
36 
37const OVERUSED_FONTS = new Set([
38  // Older monoculture (still ubiquitous):
39  'inter', 'roboto', 'open sans', 'lato', 'montserrat', 'arial', 'helvetica',
40  // Newer monoculture (the Anthropic-skill / Vercel / GitHub default wave):
41  'fraunces', 'instrument sans', 'instrument serif',
42  'geist', 'geist sans', 'geist mono',
43  'mona sans',
44  'plus jakarta sans', 'space grotesk', 'recoleta',
45]);
46 
47// Brand-associated fonts: don't flag these as "overused" on the brand's own domains.
48// Keys are font names, values are arrays of hostname suffixes where the font is allowed.
49const GOOGLE_DOMAINS = [
50  'google.com', 'youtube.com', 'android.com', 'chromium.org',
51  'chrome.com', 'web.dev', 'gstatic.com', 'firebase.google.com',
52];
53const VERCEL_DOMAINS = ['vercel.com', 'nextjs.org', 'v0.app'];
54const GITHUB_DOMAINS = ['github.com', 'githubnext.com'];
55const BRAND_FONT_DOMAINS = {
56  'roboto': GOOGLE_DOMAINS,
57  'google sans': GOOGLE_DOMAINS,
58  'product sans': GOOGLE_DOMAINS,
59  'geist': VERCEL_DOMAINS,
60  'geist sans': VERCEL_DOMAINS,
61  'geist mono': VERCEL_DOMAINS,
62  'mona sans': GITHUB_DOMAINS,
63};
64 
65function isBrandFontOnOwnDomain(font) {
66  if (typeof location === 'undefined') return false;
67  const allowed = BRAND_FONT_DOMAINS[font];
68  if (!allowed) return false;
69  const host = location.hostname.toLowerCase();
70  return allowed.some(suffix => host === suffix || host.endsWith('.' + suffix));
71}
72 
73const GENERIC_FONTS = new Set([
74  'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy',
75  'system-ui', 'ui-serif', 'ui-sans-serif', 'ui-monospace', 'ui-rounded',
76  '-apple-system', 'blinkmacsystemfont', 'segoe ui',
77  'inherit', 'initial', 'unset', 'revert',
78]);
79 
80// WCAG large text thresholds are defined in points: 18pt normal text and
81// 14pt bold text. Browsers expose font-size in CSS pixels at 96px per inch.
82const WCAG_LARGE_TEXT_PX = 18 * (96 / 72);
83const WCAG_LARGE_BOLD_TEXT_PX = 14 * (96 / 72);
84 
85// Serif faces that show up in italic-display heroes. The rule also fires when
86// the primary face is unknown but the stack ends in the generic `serif` token,
87// which catches custom/private faces with a serif fallback.
88const KNOWN_SERIF_FONTS = new Set([
89  'fraunces', 'recoleta', 'newsreader', 'playfair display', 'playfair',
90  'cormorant', 'cormorant garamond', 'garamond', 'eb garamond',
91  'tiempos', 'tiempos headline', 'tiempos text',
92  'lora', 'vollkorn', 'spectral',
93  'source serif pro', 'source serif 4', 'source serif',
94  'ibm plex serif', 'merriweather',
95  'libre caslon', 'libre baskerville', 'baskerville',
96  'georgia', 'times new roman', 'times',
97  'dm serif display', 'dm serif text',
98  'instrument serif', 'gt sectra', 'ogg', 'canela',
99  'freight display', 'freight text',
100]);
101 
102// --- cli/engine/registry/antipatterns.mjs ---
103const ANTIPATTERNS = [
104  // ── AI slop: tells that something was AI-generated ──
105  {
106    id: 'side-tab',
107    category: 'slop',
108    name: 'Side-tab accent border',
109    description:
110      'Thick colored border on one side of a card — the most recognizable tell of AI-generated UIs. Use a subtler accent or remove it entirely.',
111    skillSection: 'Visual Details',
112    skillGuideline: 'colored accent stripe',
113  },
114  {
115    id: 'border-accent-on-rounded',
116    category: 'slop',
117    name: 'Border accent on rounded element',
118    description:
119      'Thick accent border on a rounded card — the border clashes with the rounded corners. Remove the border or the border-radius.',
120    skillSection: 'Visual Details',
121    skillGuideline: 'colored accent stripe',
122  },
123  {
124    id: 'overused-font',
125    category: 'slop',
126    name: 'Overused font',
127    description:
128      '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.',
129    skillSection: 'Typography',
130    skillGuideline: 'overused fonts like Inter',
131  },
132  {
133    id: 'single-font',
134    category: 'slop',
135    name: 'Single font for everything',
136    description:
137      'Only one font family is used for the entire page. Pair a distinctive display font with a refined body font to create typographic hierarchy.',
138    skillSection: 'Typography',
139    skillGuideline: 'only one font family for the entire page',
140  },
141  {
142    id: 'flat-type-hierarchy',
143    category: 'slop',
144    name: 'Flat type hierarchy',
145    description:
146      'Font sizes are too close together — no clear visual hierarchy. Use fewer sizes with more contrast (aim for at least a 1.25 ratio between steps).',
147    skillSection: 'Typography',
148    skillGuideline: 'flat type hierarchy',
149  },
150  {
151    id: 'gradient-text',
152    category: 'slop',
153    name: 'Gradient text',
154    description:
155      'Gradient text is decorative rather than meaningful — a common AI tell, especially on headings and metrics. Use solid colors for text.',
156    skillSection: 'Color & Contrast',
157    skillGuideline: 'gradient text for',
158  },
159  {
160    id: 'ai-color-palette',
161    category: 'slop',
162    name: 'AI color palette',
163    description:
164      'Purple/violet gradients and cyan-on-dark are the most recognizable tells of AI-generated UIs. Choose a distinctive, intentional palette.',
165    skillSection: 'Color & Contrast',
166    skillGuideline: 'AI color palette',
167  },
168  {
169    id: 'cream-palette',
170    category: 'slop',
171    name: 'Cream / beige palette',
172    description:
173      'A warm cream or beige page background has become the default "tasteful" AI surface, reached for by reflex. Choose a background that comes from a deliberate palette, not the safe warm off-white.',
174    skillSection: 'Color & Contrast',
175    skillGuideline: 'cream and beige as the default surface',
176  },
177  {
178    id: 'nested-cards',
179    category: 'slop',
180    name: 'Nested cards',
181    description:
182      'Cards inside cards create visual noise and excessive depth. Flatten the hierarchy — use spacing, typography, and dividers instead of nesting containers.',
183    skillSection: 'Layout & Space',
184    skillGuideline: 'Nest cards inside cards',
185  },
186  {
187    id: 'monotonous-spacing',
188    category: 'slop',
189    name: 'Monotonous spacing',
190    description:
191      'The same spacing value used everywhere — no rhythm, no variation. Use tight groupings for related items and generous separations between sections.',
192    skillSection: 'Layout & Space',
193    skillGuideline: 'same spacing everywhere',
194  },
195  {
196    id: 'bounce-easing',
197    category: 'slop',
198    name: 'Bounce or elastic easing',
199    description:
200      'Bounce and elastic easing feel dated and tacky. Real objects decelerate smoothly — use exponential easing (ease-out-quart/quint/expo) instead.',
201    skillSection: 'Motion',
202    skillGuideline: 'bounce or elastic easing',
203  },
204  {
205    id: 'dark-glow',
206    category: 'slop',
207    name: 'Dark mode with glowing accents',
208    description:
209      'Dark backgrounds with colored box-shadow glows are the default "cool" look of AI-generated UIs. Use subtle, purposeful lighting instead — or skip the dark theme entirely.',
210    skillSection: 'Color & Contrast',
211    skillGuideline: 'dark mode with glowing accents',
212  },
213  {
214    id: 'icon-tile-stack',
215    category: 'slop',
216    name: 'Icon tile stacked above heading',
217    description:
218      'A small rounded-square icon container above a heading is the universal AI feature-card template — every generator outputs this exact shape. Try a side-by-side icon and heading, or let the icon sit in flow without its own container.',
219    skillSection: 'Typography',
220    skillGuideline: 'large icons with rounded corners above every heading',
221  },
222  {
223    id: 'italic-serif-display',
224    category: 'slop',
225    name: 'Italic serif display headline',
226    description:
227      '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.',
228    skillSection: 'Typography',
229    skillGuideline: 'oversized italic serif as the hero headline',
230  },
231  {
232    id: 'hero-eyebrow-chip',
233    category: 'slop',
234    name: 'Hero eyebrow / pill chip',
235    description:
236      '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.',
237    skillSection: 'Typography',
238    skillGuideline: 'tiny uppercase tracked label above the hero headline',
239  },
240  {
241    id: 'repeated-section-kickers',
242    category: 'slop',
243    severity: 'advisory',
244    name: 'Repeated section kicker labels',
245    description:
246      '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.',
247    skillSection: 'Typography',
248    skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding',
249  },
250  {
251    id: 'numbered-section-markers',
252    category: 'slop',
253    severity: 'advisory',
254    name: 'Numbered section markers (01 / 02 / 03)',
255    description:
256      'Numbered display markers as section labels (01, 02, 03) are the AI editorial scaffold one tier deeper than tracked eyebrow chips. If you find yourself reaching for them, choose a different section cadence.',
257    skillSection: 'Layout & Space',
258    skillGuideline: 'numbered section markers',
259  },
260  {
261    id: 'em-dash-overuse',
262    category: 'slop',
263    name: 'Em-dash overuse',
264    description:
265      'More than two em-dashes (— or --) in body copy is an AI cadence tell. Use commas, colons, periods, or parentheses instead.',
266    skillSection: 'Copy',
267    skillGuideline: 'no em dashes',
268  },
269  {
270    id: 'marketing-buzzword',
271    category: 'slop',
272    name: 'Marketing buzzword',
273    description:
274      'Generic SaaS phrases (streamline / empower / supercharge / world-class / enterprise-grade / next-generation / cutting-edge / etc) are instant AI tells. Pick a specific verb and noun that says what the product literally does.',
275    skillSection: 'Copy',
276    skillGuideline: 'marketing buzzwords',
277  },
278  {
279    id: 'aphoristic-cadence',
280    category: 'slop',
281    name: 'Aphoristic-cadence copy',
282    description:
283      'Three or more sections landing on a short rebuttal sentence ("X. No Y." / "X. Just Y.") or a manufactured-contrast aphorism ("Not a feature. A platform.") reads as AI cadence, not voice. Once is fine; the pattern is the tell.',
284    skillSection: 'Copy',
285    skillGuideline: 'aphoristic cadence',
286  },
287  {
288    id: 'oversized-h1',
289    category: 'slop',
290    name: 'Oversized hero headline',
291    description:
292      'A full-sentence headline set at display size ends up dominating the viewport, leaving no room for anything else above the fold. A punchy one- or two-word headline at that size is fine — the problem is a long headline blown up too large. Set long headlines smaller, or tighten the copy.',
293    skillSection: 'Typography',
294    skillGuideline: 'long headline set at display size',
295  },
296  {
297    id: 'extreme-negative-tracking',
298    category: 'slop',
299    name: 'Crushed letter spacing',
300    description:
301      'Letter-spacing pulled tighter than the point where characters keep their own shapes costs legibility. Tighten display type optically, not destructively.',
302    skillSection: 'Typography',
303    skillGuideline: 'letter spacing crushed past legibility',
304  },
305  {
306    id: 'broken-image',
307    category: 'quality',
308    name: 'Broken or placeholder image',
309    description:
310      '<img> tags with empty src, missing src, or placeholder values ship as broken-image boxes. Use real images, generated assets, or remove the tag.',
311    skillSection: 'Imagery',
312    skillGuideline: 'broken image references',
313  },
314 
315  // ── Quality: general design and accessibility issues ──
316  {
317    id: 'gray-on-color',
318    category: 'quality',
319    name: 'Gray text on colored background',
320    description:
321      'Gray text looks washed out on colored backgrounds. Use a darker shade of the background color instead, or white/near-white for contrast.',
322    skillSection: 'Color & Contrast',
323    skillGuideline: 'gray text on colored backgrounds',
324  },
325  {
326    id: 'low-contrast',
327    category: 'quality',
328    name: 'Low contrast text',
329    description:
330      'Text does not meet WCAG AA contrast requirements (4.5:1 for body, 3:1 for large text). Increase the contrast between text and background.',
331  },
332  {
333    id: 'layout-transition',
334    category: 'quality',
335    name: 'Layout property animation',
336    description:
337      'Animating width, height, padding, or margin causes layout thrash and janky performance. Use transform and opacity instead, or grid-template-rows for height animations.',
338    skillSection: 'Motion',
339    skillGuideline: 'Animate layout properties',
340  },
341  {
342    id: 'line-length',
343    category: 'quality',
344    name: 'Line length too long',
345    description:
346      'Text lines wider than ~80 characters are hard to read. The eye loses its place tracking back to the start of the next line. Add a max-width (65ch to 75ch) to text containers.',
347    skillSection: 'Layout & Space',
348    skillGuideline: 'wrap beyond ~80 characters',
349  },
350  {
351    id: 'cramped-padding',
352    category: 'quality',
353    name: 'Cramped padding',
354    description:
355      'Text is too close to the edge of its container. Two shapes: (1) an element with its own text where the padding is too low for the font size, and (2) a wrapper with text-bearing children and near-zero padding against a visible boundary (border, outline, or non-transparent background) — children land flush against the boundary line. Add at least 8px (ideally 12–16px) of padding inside bordered, outlined, or colored containers.',
356    skillSection: 'Layout & Space',
357    skillGuideline: 'inside bordered or colored containers',
358  },
359  {
360    id: 'body-text-viewport-edge',
361    category: 'quality',
362    name: 'Body text touching viewport edge',
363    description:
364      '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.',
365  },
366  {
367    id: 'tight-leading',
368    category: 'quality',
369    name: 'Tight line height',
370    description:
371      'Line height below 1.3x the font size makes multi-line text hard to read. Use 1.5 to 1.7 for body text so lines have room to breathe.',
372  },
373  {
374    id: 'skipped-heading',
375    category: 'quality',
376    name: 'Skipped heading level',
377    description:
378      'Heading levels should not skip (e.g. h1 then h3 with no h2). Screen readers use heading hierarchy for navigation. Skipping levels breaks the document outline.',
379  },
380  {
381    id: 'justified-text',
382    category: 'quality',
383    name: 'Justified text',
384    description:
385      'Justified text without hyphenation creates uneven word spacing ("rivers of white"). Use text-align: left for body text, or enable hyphens: auto if you must justify.',
386  },
387  {
388    id: 'tiny-text',
389    category: 'quality',
390    name: 'Tiny body text',
391    description:
392      'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
393  },
394  {
395    id: 'all-caps-body',
396    category: 'quality',
397    name: 'All-caps body text',
398    description:
399      'Long passages in uppercase are hard to read. We recognize words by shape (ascenders and descenders), which all-caps removes. Reserve uppercase for short labels and headings.',
400    skillSection: 'Typography',
401    skillGuideline: 'long body passages in uppercase',
402  },
403  {
404    id: 'wide-tracking',
405    category: 'quality',
406    name: 'Wide letter spacing on body text',
407    description:
408      'Letter spacing above 0.05em on body text disrupts natural character groupings and slows reading. Reserve wide tracking for short uppercase labels only.',
409  },
410  {
411    id: 'text-overflow',
412    category: 'quality',
413    name: 'Content overflowing its container',
414    description:
415      'Content renders wider than its container, spilling out or forcing a horizontal scrollbar. Let text wrap, constrain widths, or give the region a deliberate scroll affordance.',
416    skillSection: 'Layout & Space',
417    skillGuideline: 'content wider than its container',
418  },
419  {
420    id: 'clipped-overflow-container',
421    category: 'quality',
422    name: 'Positioned child clipped by overflow container',
423    description:
424      'A clipping container (overflow hidden or clip) wrapping an absolutely-positioned child cuts off tooltips, menus, and popovers that need to escape. Let the overflow be visible, or move the positioned layer out of the clip.',
425    skillSection: 'Layout & Space',
426    skillGuideline: 'overflow container clipping positioned children',
427  },
428  {
429    id: 'design-system-font',
430    category: 'quality',
431    name: 'Font outside DESIGN.md',
432    description:
433      'A font is used that is not declared in DESIGN.md typography. Use the documented type system or update DESIGN.md if this is an intentional brand addition.',
434    skillSection: 'Typography',
435    skillGuideline: 'font family outside the project design system',
436  },
437  {
438    id: 'design-system-color',
439    category: 'quality',
440    severity: 'advisory',
441    name: 'Color outside DESIGN.md',
442    description:
443      'A literal color is outside the DESIGN.md palette and sidecar tonal ramps. This may be legitimate, but it should be an intentional design-system addition rather than drift.',
444    skillSection: 'Color & Contrast',
445    skillGuideline: 'literal color outside the project design system',
446  },
447  {
448    id: 'design-system-radius',
449    category: 'quality',
450    severity: 'advisory',
451    name: 'Radius outside DESIGN.md',
452    description:
453      'A border-radius value is outside the DESIGN.md rounded scale. Use a documented radius token or update the design system if the new shape is intentional.',
454    skillSection: 'Visual Details',
455    skillGuideline: 'border radius outside the project design system',
456  },
457 
458  // ── Provider tells: opt-in via --gpt / --gemini (gated off by default) ──
459  {
460    id: 'gpt-thin-border-wide-shadow',
461    category: 'slop',
462    severity: 'advisory',
463    gated: 'gpt',
464    name: 'Hairline border with wide shadow',
465    description:
466      'A hairline border paired with a wide, diffuse shadow is a recurring generated-UI signature. Commit to one — a defined edge or a soft elevation — rather than both at once.',
467    skillSection: 'Visual Details',
468    skillGuideline: 'hairline border plus wide diffuse shadow',
469  },
470  {
471    id: 'repeating-stripes-gradient',
472    category: 'slop',
473    severity: 'advisory',
474    gated: 'gpt',
475    name: 'Repeating-gradient stripes',
476    description:
477      'Repeating-gradient stripes used as surface decoration are a recurring generated-UI signature. Reach for a deliberate texture or leave the surface plain.',
478    skillSection: 'Visual Details',
479    skillGuideline: 'repeating-gradient decorative stripes',
480  },
481  {
482    id: 'theater-slop-phrase',
483    category: 'slop',
484    severity: 'advisory',
485    gated: 'gpt',
486    name: 'Theater framing copy',
487    description:
488      'Dismissing something as "theater" is a recurring generated-copy tic. Say plainly what the thing does or does not do.',
489    skillSection: 'Copy',
490    skillGuideline: 'theater framing copy',
491  },
492  {
493    id: 'image-hover-transform',
494    category: 'slop',
495    severity: 'advisory',
496    gated: 'gemini',
497    name: 'Image hover transform',
498    description:
499      'Scaling or rotating an image on hover is a recurring generated-UI signature. Let imagery sit still, or use a subtler, purposeful interaction.',
500    skillSection: 'Motion',
501    skillGuideline: 'image scale or rotate on hover',
502  },
503];
504 
505// --- cli/engine/shared/color.mjs ---
506// ─── Section 2: Color Utilities ─────────────────────────────────────────────
507 
508function isNeutralColor(color) {
509  if (!color || color === 'transparent') return true;
510 
511  // rgb/rgba — use channel spread. Threshold 30 ≈ 11.7% of the 0–255 range.
512  const rgb = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
513  if (rgb) {
514    return (Math.max(+rgb[1], +rgb[2], +rgb[3]) - Math.min(+rgb[1], +rgb[2], +rgb[3])) < 30;
515  }
516 
517  // oklch()/lch() — chroma is the second numeric component.
518  // oklch chroma is ~0–0.4 in sRGB gamut; >= 0.02 reads as tinted, not gray.
519  // lch chroma is ~0–150; >= 3 reads as tinted. jsdom emits both formats
520  // literally (it does NOT convert them to rgb).
521  const oklch = color.match(/oklch\(\s*[\d.]+%?\s*([\d.-]+)/i);
522  if (oklch) return parseFloat(oklch[1]) < 0.02;
523  const lch = color.match(/lch\(\s*[\d.]+%?\s*([\d.-]+)/i);
524  if (lch) return parseFloat(lch[1]) < 3;
525 
526  // oklab()/lab() — a and b are signed axes; chroma = sqrt(a² + b²).
527  // oklab a/b are ~-0.4..0.4, threshold 0.02. lab a/b are ~-128..127, threshold 3.
528  const oklab = color.match(/oklab\(\s*[\d.]+%?\s*([\d.-]+)\s+([\d.-]+)/i);
529  if (oklab) {
530    const a = parseFloat(oklab[1]), b = parseFloat(oklab[2]);
531    return Math.hypot(a, b) < 0.02;
532  }
533  const lab = color.match(/lab\(\s*[\d.]+%?\s*([\d.-]+)\s+([\d.-]+)/i);
534  if (lab) {
535    const a = parseFloat(lab[1]), b = parseFloat(lab[2]);
536    return Math.hypot(a, b) < 3;
537  }
538 
539  // hsl/hsla — saturation is the second numeric component (percent).
540  // Modern jsdom usually converts hsl() to rgb, but handle it directly for
541  // safety across versions and for any engine that preserves the format.
542  const hsl = color.match(/hsla?\(\s*[\d.-]+\s*,?\s*([\d.]+)%/i);
543  if (hsl) return parseFloat(hsl[1]) < 10;
544 
545  // hwb(hue whiteness% blackness%) — a pixel is fully gray when
546  // whiteness + blackness >= 100; chroma-like saturation = 1 - (w+b)/100.
547  const hwb = color.match(/hwb\(\s*[\d.-]+\s+([\d.]+)%\s+([\d.]+)%/i);
548  if (hwb) {
549    const w = parseFloat(hwb[1]), b = parseFloat(hwb[2]);
550    return (1 - Math.min(100, w + b) / 100) < 0.1;
551  }
552 
553  // Unknown / unrecognized format — err on the side of DETECTING rather
554  // than silently skipping. This is the opposite of the previous default,
555  // which was the root cause of the oklch bug.
556  return false;
557}
558 
559function parseRgb(color) {
560  if (!color || color === 'transparent') return null;
561  const m = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
562  if (!m) return null;
563  return { r: +m[1], g: +m[2], b: +m[3], a: m[4] !== undefined ? +m[4] : 1 };
564}
565 
566function relativeLuminance({ r, g, b }) {
567  const [rs, gs, bs] = [r / 255, g / 255, b / 255].map(c =>
568    c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
569  );
570  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
571}
572 
573function contrastRatio(c1, c2) {
574  const l1 = relativeLuminance(c1);
575  const l2 = relativeLuminance(c2);
576  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
577}
578 
579function parseGradientColors(bgImage) {
580  if (!bgImage || !bgImage.includes('gradient')) return [];
581  const colors = [];
582  for (const m of bgImage.matchAll(/rgba?\([^)]+\)/g)) {
583    const c = parseRgb(m[0]);
584    if (c) colors.push(c);
585  }
586  for (const m of bgImage.matchAll(/#([0-9a-f]{6}|[0-9a-f]{3})\b/gi)) {
587    const h = m[1];
588    if (h.length === 6) {
589      colors.push({ r: parseInt(h.slice(0,2),16), g: parseInt(h.slice(2,4),16), b: parseInt(h.slice(4,6),16), a: 1 });
590    } else {
591      colors.push({ r: parseInt(h[0]+h[0],16), g: parseInt(h[1]+h[1],16), b: parseInt(h[2]+h[2],16), a: 1 });
592    }
593  }
594  return colors;
595}
596 
597function hasChroma(c, threshold = 30) {
598  if (!c) return false;
599  return (Math.max(c.r, c.g, c.b) - Math.min(c.r, c.g, c.b)) >= threshold;
600}
601 
602function getHue(c) {
603  if (!c) return 0;
604  const r = c.r / 255, g = c.g / 255, b = c.b / 255;
605  const max = Math.max(r, g, b), min = Math.min(r, g, b);
606  if (max === min) return 0;
607  const d = max - min;
608  let h;
609  if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
610  else if (max === g) h = ((b - r) / d + 2) / 6;
611  else h = ((r - g) / d + 4) / 6;
612  return Math.round(h * 360);
613}
614 
615function colorToHex(c) {
616  if (!c) return '?';
617  return '#' + [c.r, c.g, c.b].map(v => v.toString(16).padStart(2, '0')).join('');
618}
619 
620// --- cli/engine/rules/checks.mjs ---
621const DETECTOR_IS_BROWSER = typeof window !== 'undefined';
622 
623// ─── Section 3: Pure Detection ──────────────────────────────────────────────
624 
625function checkBorders(tag, widths, colors, radius) {
626  if (BORDER_SAFE_TAGS.has(tag)) return [];
627  const findings = [];
628  const sides = ['Top', 'Right', 'Bottom', 'Left'];
629 
630  for (const side of sides) {
631    const w = widths[side];
632    if (w < 1 || isNeutralColor(colors[side])) continue;
633 
634    const otherSides = sides.filter(s => s !== side);
635    const maxOther = Math.max(...otherSides.map(s => widths[s]));
636    if (!(w >= 2 && (maxOther <= 1 || w >= maxOther * 2))) continue;
637 
638    const sn = side.toLowerCase();
639    const isSide = side === 'Left' || side === 'Right';
640 
641    if (isSide) {
642      if (radius > 0) findings.push({ id: 'side-tab', snippet: `border-${sn}: ${w}px + border-radius: ${radius}px` });
643      else if (w >= 3) findings.push({ id: 'side-tab', snippet: `border-${sn}: ${w}px` });
644    } else {
645      if (radius > 0 && w >= 2) findings.push({ id: 'border-accent-on-rounded', snippet: `border-${sn}: ${w}px + border-radius: ${radius}px` });
646    }
647  }
648 
649  return findings;
650}
651 
652// Returns true if the given text is composed entirely of emoji characters
653// (plus whitespace / variation selectors). Emojis render as multicolor glyphs
654// regardless of CSS `color`, so contrast checks against the element's text
655// color are meaningless for these nodes.
656const 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;
657const 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;
658function isEmojiOnlyText(text) {
659  if (!text) return false;
660  if (!EMOJI_CHAR_RE.test(text)) return false;
661  return text.replace(EMOJI_CHARS_GLOBAL, '').trim() === '';
662}
663 
664function checkColors(opts) {
665  const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList } = opts;
666  if (SAFE_TAGS.has(tag)) {
667    // Exception for <a> and <button> elements styled as buttons. SAFE_TAGS
668    // exists to suppress contrast noise on inline links and unstyled controls,
669    // where the element has no own background and the contrast against the
670    // ancestor surface is already the intended visual. When the element has
671    // its own opaque background and direct text, it is a styled button — and
672    // contrast on its own surface is a real, frequent bug worth flagging.
673    const isStyledButton = (tag === 'a' || tag === 'button')
674      && hasDirectText
675      && bgColor && bgColor.a > 0.5;
676    if (!isStyledButton) return [];
677  }
678  const findings = [];
679 
680  if (hasDirectText && textColor && !isEmojiOnly) {
681    // Run background-dependent checks against either a solid bg or, if the
682    // ancestor is a gradient, against every gradient stop (use the worst case).
683    const bgs = effectiveBg ? [effectiveBg] : (effectiveBgStops && effectiveBgStops.length ? effectiveBgStops : null);
684    if (bgs) {
685      // Gray on colored background — flag if every stop is chromatic
686      const textLum = relativeLuminance(textColor);
687      const isGray = !hasChroma(textColor, 20) && textLum > 0.05 && textLum < 0.85;
688      if (isGray && bgs.every(b => hasChroma(b, 40))) {
689        const bgLabel = effectiveBg ? colorToHex(effectiveBg) : `gradient(${bgs.map(colorToHex).join(', ')})`;
690        findings.push({ id: 'gray-on-color', snippet: `text ${colorToHex(textColor)} on bg ${bgLabel}` });
691      }
692 
693      // Low contrast (WCAG AA) — worst case across all bg stops
694      const ratios = bgs.map(b => contrastRatio(textColor, b));
695      let worstIdx = 0;
696      for (let i = 1; i < ratios.length; i++) if (ratios[i] < ratios[worstIdx]) worstIdx = i;
697      const ratio = ratios[worstIdx];
698      const isLargeText = fontSize >= WCAG_LARGE_TEXT_PX || (fontSize >= WCAG_LARGE_BOLD_TEXT_PX && fontWeight >= 700);
699      const threshold = isLargeText ? 3.0 : 4.5;
700      if (ratio < threshold) {
701        // Skip the false-positive class where text has alpha < 1 AND we
702        // couldn't find an opaque ancestor (effectiveBg is null, we're
703        // comparing against gradient-stop fallback). In jsdom mode the
704        // detector can't resolve `var(--X)` color tokens, so a dark
705        // section sitting between the text and the body's decorative
706        // gradient is invisible to us — we end up measuring contrast
707        // against the body's paper-grain noise instead of the real
708        // local bg. Real low-contrast bugs use alpha=1 and have a
709        // resolvable opaque ancestor; semi-transparent Tailwind tokens
710        // like `text-paper/60` on `bg-ink` sections are the FP pattern.
711        const isAlphaFallbackFP = !DETECTOR_IS_BROWSER && !effectiveBg && (textColor.a != null && textColor.a < 1);
712        if (!isAlphaFallbackFP) {
713          findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}` });
714        }
715      }
716    }
717 
718    // AI palette: purple/violet on headings
719    if (hasChroma(textColor, 50)) {
720      const hue = getHue(textColor);
721      if (hue >= 260 && hue <= 310 && (['h1', 'h2', 'h3'].includes(tag) || fontSize >= 20)) {
722        findings.push({ id: 'ai-color-palette', snippet: `Purple/violet text (${colorToHex(textColor)}) on heading` });
723      }
724    }
725  }
726 
727  // Gradient text
728  if (bgClip === 'text' && bgImage && bgImage.includes('gradient')) {
729    findings.push({ id: 'gradient-text', snippet: 'background-clip: text + gradient' });
730  }
731 
732  // Tailwind class checks
733  if (classList) {
734    const classStr = typeof classList === 'string' ? classList : Array.from(classList).join(' ');
735 
736    const grayMatch = classStr.match(/\btext-(?:gray|slate|zinc|neutral|stone)-\d+\b/);
737    const colorBgMatch = classStr.match(/\bbg-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d+\b/);
738    if (grayMatch && colorBgMatch) {
739      findings.push({ id: 'gray-on-color', snippet: `${grayMatch[0]} on ${colorBgMatch[0]}` });
740    }
741 
742    if (/\bbg-clip-text\b/.test(classStr) && /\bbg-gradient-to-/.test(classStr)) {
743      findings.push({ id: 'gradient-text', snippet: 'bg-clip-text + bg-gradient (Tailwind)' });
744    }
745 
746    const purpleText = classStr.match(/\btext-(?:purple|violet|indigo)-\d+\b/);
747    if (purpleText && (['h1', 'h2', 'h3'].includes(tag) || /\btext-(?:[2-9]xl)\b/.test(classStr))) {
748      findings.push({ id: 'ai-color-palette', snippet: `${purpleText[0]} on heading` });
749    }
750 
751    if (/\bfrom-(?:purple|violet|indigo)-\d+\b/.test(classStr) && /\bto-(?:purple|violet|indigo|blue|cyan|pink|fuchsia)-\d+\b/.test(classStr)) {
752      findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet gradient (Tailwind)' });
753    }
754  }
755 
756  return findings;
757}
758 
759function isCardLikeFromProps(hasShadow, hasBorder, hasRadius, hasBg) {
760  if (!hasShadow && !hasBorder) return false;
761  return hasRadius || hasBg;
762}
763 
764const HEADING_TAGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
765 
766// Pure check: given a heading and metrics about its previousElementSibling,
767// decide if the sibling is the canonical "icon-tile-stacked-above-heading" shape.
768//
769// Triggers when ALL of the following hold for the sibling:
770//   • size 32–128px on both axes (not too small, not a hero image)
771//   • aspect ratio 0.7–1.4 (squarish — excludes wide thumbnails / pill badges)
772//   • has a non-transparent background-color, background-image, OR a visible border
773//     (covers solid colors, white-with-border, gradients — anything that visually
774//      defines a tile)
775//   • border-radius < width/2 (excludes round avatars; rounded squares pass)
776//   • contains an <svg> or icon-class <i> element that's smaller than the tile
777//   • the tile sits above the heading (its bottom is above the heading's top)
778function checkIconTile(opts) {
779  const { headingTag, headingText, headingTop,
780          siblingTag, siblingWidth, siblingHeight, siblingBottom,
781          siblingBgColor, siblingBgImage, siblingBorderWidth, siblingBorderRadius,
782          hasIconChild, iconChildWidth } = opts;
783  if (!HEADING_TAGS.has(headingTag)) return [];
784  if (!siblingTag) return [];
785  // Don't recurse into nested headings (e.g. h2 above h3 in a section header)
786  if (HEADING_TAGS.has(siblingTag)) return [];
787 
788  // Size window: 32–128px on each axis
789  if (!(siblingWidth >= 32 && siblingWidth <= 128)) return [];
790  if (!(siblingHeight >= 32 && siblingHeight <= 128)) return [];
791 
792  // Squarish aspect ratio
793  const ratio = siblingWidth / siblingHeight;
794  if (ratio < 0.7 || ratio > 1.4) return [];
795 
796  // Must have something that visually defines the tile
797  const bgVisible = (siblingBgColor && siblingBgColor.a > 0.1)
798    || (siblingBgImage && siblingBgImage !== 'none' && siblingBgImage !== '');
799  const borderVisible = siblingBorderWidth > 0;
800  if (!bgVisible && !borderVisible) return [];
801 
802  // Exclude circles (avatars). Rounded squares pass.
803  if (siblingBorderRadius >= siblingWidth / 2) return [];
804 
805  // Must contain an icon element smaller than the tile
806  if (!hasIconChild) return [];
807  if (iconChildWidth && iconChildWidth >= siblingWidth * 0.95) return [];
808 
809  // Vertical stacking: tile must end above where the heading starts.
810  // (Allow the check to skip when both top/bottom are 0 — jsdom layout case.)
811  if (headingTop && siblingBottom && siblingBottom > headingTop + 4) return [];
812 
813  const text = (headingText || '').trim().slice(0, 60);
814  return [{
815    id: 'icon-tile-stack',
816    snippet: `${Math.round(siblingWidth)}x${Math.round(siblingHeight)}px icon tile above ${headingTag} "${text}"`,
817  }];
818}
819 
820// Resolve the primary (non-generic) face from a font-family string and return
821// whether the resolved primary is serif. Two paths:
822//   1. Primary face is in KNOWN_SERIF_FONTS → serif.
823//   2. Primary face is unknown but the stack ends in the generic `serif`
824//      token → treat as serif. Authors who declare `font-family: 'X', serif`
825//      almost always have a serif primary; a sans declared with a serif
826//      fallback is a code smell, not the common case.
827// Returns { primary, isSerif } so the snippet can name the face.
828function resolveSerif(fontFamily) {
829  if (!fontFamily) return { primary: null, isSerif: false };
830  const tokens = fontFamily.split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase());
831  const primary = tokens.find(f => f && !GENERIC_FONTS.has(f)) || null;
832  if (!primary) return { primary: null, isSerif: false };
833  if (KNOWN_SERIF_FONTS.has(primary)) return { primary, isSerif: true };
834  if (tokens.includes('serif')) return { primary, isSerif: true };
835  return { primary, isSerif: false };
836}
837 
838function checkItalicSerif(opts) {
839  const { tag, fontStyle, fontFamily, fontSize, headingText } = opts;
840  if (fontStyle !== 'italic') return [];
841  // Anchor the rule on hero-scale text. h1 is the canonical hero element;
842  // h2 ≥ 48px catches the cases where the design demotes the visual hero
843  // to an h2 but keeps the size.
844  if (tag !== 'h1' && !(tag === 'h2' && fontSize >= 48)) return [];
845  if (fontSize < 48) return [];
846  const { primary, isSerif } = resolveSerif(fontFamily);
847  if (!isSerif) return [];
848 
849  const text = (headingText || '').trim().slice(0, 60);
850  return [{
851    id: 'italic-serif-display',
852    snippet: `italic serif ${tag} (${primary || 'serif'}) at ${Math.round(fontSize)}px "${text}"`,
853  }];
854}
855 
856// Color saturation check. Returns true when the color has visible
857// chroma — i.e., it's an "accent color" rather than near-neutral.
858// Handles rgb()/rgba(), #hex, oklch(), and hsl(). var() refs are
859// expected to be pre-resolved by the caller.
860function isAccentColor(cssColor) {
861  if (!cssColor) return false;
862  const s = String(cssColor).trim();
863  // rgb / rgba — direct channel-distance check.
864  const rgbM = /rgba?\(\s*(\d+)\s*,?\s+|\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(s.replace(/rgba?\(\s*/, 'rgb(').replace(/,/g, ', '));
865  const rgbStrict = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(s);
866  if (rgbStrict) {
867    const r = +rgbStrict[1], g = +rgbStrict[2], b = +rgbStrict[3];
868    return (Math.max(r, g, b) - Math.min(r, g, b)) >= 40;
869  }
870  // #hex — 3, 4, 6, or 8 digit.
871  const hexM = /^#([0-9a-f]{3,8})\b/i.exec(s);
872  if (hexM) {
873    let h = hexM[1];
874    if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('').slice(0, 6);
875    else h = h.slice(0, 6);
876    if (h.length === 6) {
877      const r = parseInt(h.slice(0, 2), 16);
878      const g = parseInt(h.slice(2, 4), 16);
879      const b = parseInt(h.slice(4, 6), 16);
880      return (Math.max(r, g, b) - Math.min(r, g, b)) >= 40;
881    }
882  }
883  // oklch(L C H) — chroma C is what matters. Typical neutral grays
884  // have C < 0.02; visible accents are 0.05+. CSS minification can
885  // collapse spaces between L% and C ("oklch(43%.15 34)"), so we
886  // extract all numbers and take the second rather than matching a
887  // strict L-then-whitespace-then-C pattern.
888  if (/^oklch\(/i.test(s)) {
889    const nums = s.match(/\d*\.\d+|\d+/g);
890    if (nums && nums.length >= 2) {
891      const c = parseFloat(nums[1]);
892      return !Number.isNaN(c) && c >= 0.05;
893    }
894  }
895  // hsl(H, S%, L%) — saturation > 20% reads as accent.
896  const hslM = /hsla?\(\s*[\d.]+\s*,\s*([\d.]+)%/i.exec(s);
897  if (hslM) {
898    const sat = parseFloat(hslM[1]);
899    return !Number.isNaN(sat) && sat >= 20;
900  }
901  return false;
902}
903 
904// Sibling-relationship rule. Anchor on a hero-scale h1, look at the
905// previousElementSibling, and gate on EITHER the classic tracked-
906// uppercase eyebrow OR the modern accent-colored bold eyebrow.
907function checkHeroEyebrow(opts) {
908  const {
909    headingTag, headingText, headingFontSize,
910    siblingTag, siblingText, siblingTextTransform,
911    siblingFontSize, siblingLetterSpacing,
912    siblingFontWeight, siblingColor,
913  } = opts;
914  if (headingTag !== 'h1') return [];
915  // We previously gated on headingFontSize >= 48 to anchor "hero scale".
916  // But modern hero h1s use clamp() / vw / var(--text-*), none of which
917  // jsdom can resolve — the computed value comes back as "2em" or
918  // "var(--text-9xl)" and parseFloat returns 2 or NaN. The gate fails
919  // on virtually every Tailwind v4 / framework build. The other gates
920  // (sibling text 2-60 chars, font-size ≤ 14px, accent-bold OR
921  // tracked-caps) are tight enough to avoid false positives on non-
922  // hero h1s — a tiny tan label directly above any h1 is the
923  // antipattern regardless of how big the h1 ends up.
924  if (!siblingTag) return [];
925  // An h2 above an h1 is a different anti-pattern (heading hierarchy / dual
926  // headings) — never an eyebrow.
927  if (HEADING_TAGS.has(siblingTag)) return [];
928 
929  const text = (siblingText || '').trim();
930  if (text.length < 2 || text.length > 60) return [];
931  if (!(siblingFontSize > 0 && siblingFontSize <= 14)) return [];
932 
933  // Branch A: classic tracked-uppercase eyebrow.
934  const isUppercased = siblingTextTransform === 'uppercase'
935    || (/[A-Z]/.test(text) && !/[a-z]/.test(text));
936  const isClassicTracked = isUppercased && siblingLetterSpacing >= 1.6;
937 
938  // Branch B: modern accent-bold eyebrow — sentence case, low
939  // tracking, but bold + accent-colored. The style choices changed;
940  // the pattern is the same kicker-above-headline anti-pattern.
941  const weight = Number(siblingFontWeight) || 400;
942  const isAccentBold = weight >= 700 && isAccentColor(siblingColor || '');
943 
944  if (!isClassicTracked && !isAccentBold) return [];
945 
946  const headingTextSnippet = (headingText || '').trim().slice(0, 60);
947  const eyebrowSnippet = text.slice(0, 40);
948  const style = isClassicTracked ? 'tracked-caps' : 'accent-bold';
949  return [{
950    id: 'hero-eyebrow-chip',
951    snippet: `eyebrow chip (${style}) "${eyebrowSnippet}" above ${headingTag} "${headingTextSnippet}"`,
952  }];
953}
954 
955function checkRepeatedSectionKickers(opts) {
956  const { candidates, minCount = 3 } = opts;
957  if (!Array.isArray(candidates) || candidates.length < minCount) return [];
958  return candidates.map(candidate => ({
959    id: 'repeated-section-kickers',
960    snippet: `repeated section kicker "${candidate.kickerText}" before ${candidate.headingTag} "${candidate.headingText}" (${candidates.length} on page)`,
961  }));
962}
963 
964const LAYOUT_TRANSITION_PROPS = new Set([
965  'width', 'height', 'padding', 'margin',
966  'max-height', 'max-width', 'min-height', 'min-width',
967  'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
968  'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
969]);
970 
971function checkMotion(opts) {
972  const { tag, transitionProperty, animationName, timingFunctions, classList } = opts;
973  if (SAFE_TAGS.has(tag)) return [];
974  const findings = [];
975 
976  // --- Bounce/elastic easing ---
977  if (animationName && animationName !== 'none' && /bounce|elastic|wobble|jiggle|spring/i.test(animationName)) {
978    findings.push({ id: 'bounce-easing', snippet: `animation: ${animationName}` });
979  }
980  if (classList && /\banimate-bounce\b/.test(classList)) {
981    findings.push({ id: 'bounce-easing', snippet: 'animate-bounce (Tailwind)' });
982  }
983 
984  // Check timing functions for overshoot cubic-bezier (y values outside [0, 1])
985  if (timingFunctions) {
986    const bezierRe = /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g;
987    let m;
988    while ((m = bezierRe.exec(timingFunctions)) !== null) {
989      const y1 = parseFloat(m[2]), y2 = parseFloat(m[4]);
990      if (y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1) {
991        findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${m[1]}, ${m[2]}, ${m[3]}, ${m[4]})` });
992        break;
993      }
994    }
995  }
996 
997  // --- Layout property transition ---
998  if (transitionProperty && transitionProperty !== 'all' && transitionProperty !== 'none') {
999    const props = transitionProperty.split(',').map(p => p.trim().toLowerCase());
1000    const layoutFound = props.filter(p => LAYOUT_TRANSITION_PROPS.has(p));
1001    if (layoutFound.length > 0) {
1002      findings.push({ id: 'layout-transition', snippet: `transition: ${layoutFound.join(', ')}` });
1003    }
1004  }
1005 
1006  return findings;
1007}
1008 
1009function checkGlow(opts) {
1010  const { boxShadow, effectiveBg } = opts;
1011  if (!boxShadow || boxShadow === 'none') return [];
1012  if (!effectiveBg) return [];
1013 
1014  // Only flag on dark backgrounds (luminance < 0.1)
1015  const bgLum = relativeLuminance(effectiveBg);
1016  if (bgLum >= 0.1) return [];
1017 
1018  // Split multiple shadows (commas not inside parentheses)
1019  const parts = boxShadow.split(/,(?![^(]*\))/);
1020  for (const shadow of parts) {
1021    const colorMatch = shadow.match(/rgba?\([^)]+\)/);
1022    if (!colorMatch) continue;
1023    const color = parseRgb(colorMatch[0]);
1024    if (!color || !hasChroma(color, 30)) continue;
1025 
1026    // Extract px values — in computed style: "color Xpx Ypx BLURpx [SPREADpx]"
1027    const afterColor = shadow.substring(shadow.indexOf(colorMatch[0]) + colorMatch[0].length);
1028    const beforeColor = shadow.substring(0, shadow.indexOf(colorMatch[0]));
1029    const pxVals = [...beforeColor.matchAll(/([\d.]+)px/g), ...afterColor.matchAll(/([\d.]+)px/g)]
1030      .map(m => parseFloat(m[1]));
1031 
1032    // Third value is blur (offset-x, offset-y, blur, [spread])
1033    if (pxVals.length >= 3 && pxVals[2] > 4) {
1034      return [{ id: 'dark-glow', snippet: `Colored glow (${colorToHex(color)}) on dark background` }];
1035    }
1036  }
1037 
1038  return [];
1039}
1040 
1041/**
1042 * Regex-on-HTML checks shared between browser and Node page-level detection.
1043 * These don't need DOM access, just the raw HTML string.
1044 */
1045function checkHtmlPatterns(html) {
1046  const findings = [];
1047 
1048  // --- Color ---
1049 
1050  // AI color palette: purple/violet
1051  const purpleHexRe = /#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9|6366f1|764ba2|667eea)\b/gi;
1052  if (purpleHexRe.test(html)) {
1053    const purpleTextRe = /(?:(?:^|;)\s*color\s*:\s*(?:.*?)(?:#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9))|gradient.*?#(?:7c3aed|8b5cf6|a855f7|764ba2|667eea))/gi;
1054    if (purpleTextRe.test(html)) {
1055      findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet accent colors detected' });
1056    }
1057  }
1058 
1059  // Gradient text (background-clip: text + gradient)
1060  const gradientRe = /(?:-webkit-)?background-clip\s*:\s*text/gi;
1061  let gm;
1062  while ((gm = gradientRe.exec(html)) !== null) {
1063    const start = Math.max(0, gm.index - 200);
1064    const context = html.substring(start, gm.index + gm[0].length + 200);
1065    if (/gradient/i.test(context)) {
1066      findings.push({ id: 'gradient-text', snippet: 'background-clip: text + gradient' });
1067      break;
1068    }
1069  }
1070  if (/\bbg-clip-text\b/.test(html) && /\bbg-gradient-to-/.test(html)) {
1071    findings.push({ id: 'gradient-text', snippet: 'bg-clip-text + bg-gradient (Tailwind)' });
1072  }
1073 
1074  // --- Layout ---
1075 
1076  // Monotonous spacing
1077  const spacingValues = [];
1078  const spacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*(\d+)px/gi;
1079  let sm;
1080  while ((sm = spacingRe.exec(html)) !== null) {
1081    const v = parseInt(sm[1], 10);
1082    if (v > 0 && v < 200) spacingValues.push(v);
1083  }
1084  const gapRe = /gap\s*:\s*(\d+)px/gi;
1085  while ((sm = gapRe.exec(html)) !== null) {
1086    spacingValues.push(parseInt(sm[1], 10));
1087  }
1088  const twSpaceRe = /\b(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-(\d+)\b/g;
1089  while ((sm = twSpaceRe.exec(html)) !== null) {
1090    spacingValues.push(parseInt(sm[1], 10) * 4);
1091  }
1092  const remSpacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*([\d.]+)rem/gi;
1093  while ((sm = remSpacingRe.exec(html)) !== null) {
1094    const v = Math.round(parseFloat(sm[1]) * 16);
1095    if (v > 0 && v < 200) spacingValues.push(v);
1096  }
1097  const roundedSpacing = spacingValues.map(v => Math.round(v / 4) * 4);
1098  if (roundedSpacing.length >= 10) {
1099    const counts = {};
1100    for (const v of roundedSpacing) counts[v] = (counts[v] || 0) + 1;
1101    const maxCount = Math.max(...Object.values(counts));
1102    const dominantPct = maxCount / roundedSpacing.length;
1103    const unique = [...new Set(roundedSpacing)].filter(v => v > 0);
1104    if (dominantPct > 0.6 && unique.length <= 3) {
1105      const dominant = Object.entries(counts).sort((a, b) => b[1] - a[1])[0][0];
1106      findings.push({
1107        id: 'monotonous-spacing',
1108        snippet: `~${dominant}px used ${maxCount}/${roundedSpacing.length} times (${Math.round(dominantPct * 100)}%)`,
1109      });
1110    }
1111  }
1112 
1113  // --- Motion ---
1114 
1115  // Bounce/elastic animation names
1116  const bounceRe = /animation(?:-name)?\s*:\s*([^;{}]*(?:bounce|elastic|wobble|jiggle|spring)[^;{}]*)/gi;
1117  const bounceMatch = bounceRe.exec(html);
1118  if (bounceMatch) {
1119    const animationToken = bounceMatch[1]
1120      .split(/[,\s]+/)
1121      .find((part) => /bounce|elastic|wobble|jiggle|spring/i.test(part));
1122    findings.push({ id: 'bounce-easing', snippet: `animation: ${animationToken || bounceMatch[1].trim()}` });
1123  }
1124 
1125  // Overshoot cubic-bezier
1126  const bezierRe = /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g;
1127  let bm;
1128  while ((bm = bezierRe.exec(html)) !== null) {
1129    const y1 = parseFloat(bm[2]), y2 = parseFloat(bm[4]);
1130    if (y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1) {
1131      findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${bm[1]}, ${bm[2]}, ${bm[3]}, ${bm[4]})` });
1132      break;
1133    }
1134  }
1135 
1136  // Layout property transitions
1137  const transRe = /transition(?:-property)?\s*:\s*([^;{}]+)/gi;
1138  let tm;
1139  while ((tm = transRe.exec(html)) !== null) {
1140    const val = tm[1].toLowerCase();
1141    if (/\ball\b/.test(val)) continue;
1142    const found = val.match(/\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding(?:-(?:top|right|bottom|left))?\b|\bmargin(?:-(?:top|right|bottom|left))?\b/gi);
1143    if (found) {
1144      findings.push({ id: 'layout-transition', snippet: `transition: ${found.join(', ')}` });
1145      break;
1146    }
1147  }
1148 
1149  // --- Dark glow ---
1150 
1151  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;
1152  const twDarkBg = /\bbg-(?:gray|slate|zinc|neutral|stone)-(?:9\d{2}|800)\b/;
1153  if (darkBgRe.test(html) || twDarkBg.test(html)) {
1154    const shadowRe = /box-shadow\s*:\s*([^;{}]+)/gi;
1155    let shm;
1156    while ((shm = shadowRe.exec(html)) !== null) {
1157      const val = shm[1];
1158      const colorMatch = val.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
1159      if (!colorMatch) continue;
1160      const [r, g, b] = [+colorMatch[1], +colorMatch[2], +colorMatch[3]];
1161      if ((Math.max(r, g, b) - Math.min(r, g, b)) < 30) continue;
1162      const pxVals = [...val.matchAll(/(\d+)px|(?<![.\d])\b(0)\b(?![.\d])/g)].map(p => +(p[1] || p[2]));
1163      if (pxVals.length >= 3 && pxVals[2] > 4) {
1164        findings.push({ id: 'dark-glow', snippet: `Colored glow (rgb(${r},${g},${b})) on dark page` });
1165        break;
1166      }
1167    }
1168  }
1169 
1170  // --- Provider tells (gated): repeating-gradient stripes (GPT) ---
1171  if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(html)) {
1172    findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
1173  }
1174 
1175  // --- Provider tells (gated): "X theater" framing copy (GPT) ---
1176  // Lives here (regex-on-HTML) rather than in the text-content analyzers so it
1177  // runs in the bundled browser path too, not just the CLI/static path.
1178  {
1179    const bodyText = html
1180      .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ')
1181      .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ')
1182      .replace(/<[^>]+>/g, ' ');
1183    const tm = /\b(\w+)\s+theater\b/i.exec(bodyText);
1184    if (tm) findings.push({ id: 'theater-slop-phrase', snippet: `"${tm[0].trim()}"` });
1185  }
1186 
1187  // --- Provider tells (gated): image hover transform (Gemini) ---
1188  // A CSS `img...:hover { transform: ... }` rule, or a Tailwind hover:scale /
1189  // hover:rotate / hover:translate utility on an <img>. Each distinct
1190  // mechanism is its own finding.
1191  const imgHoverCss = /\bimg\b[^,{}]*:hover\b[^{}]*\{[^}]*\btransform\s*:\s*(?:scale|rotate|translate|matrix|skew)/i;
1192  if (imgHoverCss.test(html)) {
1193    findings.push({ id: 'image-hover-transform', snippet: 'img:hover { transform } rule' });
1194  }
1195  const imgTagRe = /<img\b[^>]*\bclass\s*=\s*"([^"]*)"/gi;
1196  let im;
1197  while ((im = imgTagRe.exec(html)) !== null) {
1198    if (/\bhover:(?:scale|rotate|translate|skew)-/.test(im[1])) {
1199      findings.push({ id: 'image-hover-transform', snippet: 'Tailwind hover transform on <img>' });
1200    }
1201  }
1202 
1203  return findings;
1204}
1205 
1206// ─── Section 4: resolveBackground (unified) ─────────────────────────────────
1207 
1208// Read the element's own background color, computed-style first, with a
1209// jsdom-friendly fallback that parses the inline `background:` shorthand
1210// from the raw style attribute. jsdom (~v29) does not decompose the
1211// shorthand into `backgroundColor`, so without this fallback the CLI silently
1212// returns null for any element styled via `background: rgb(...)` or
1213// `background: #abc`. Real browsers always decompose, so the fallback is
1214// a no-op there.
1215function readOwnBackgroundColor(el, computedStyle) {
1216  const bg = parseRgb(computedStyle.backgroundColor);
1217  if (DETECTOR_IS_BROWSER || (bg && bg.a >= 0.1)) return bg;
1218  const rawStyle = el.getAttribute?.('style') || '';
1219  const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
1220  const inlineBg = bgMatch ? bgMatch[1].trim() : '';
1221  if (!inlineBg) return bg;
1222  if (/gradient/i.test(inlineBg) || /url\s*\(/i.test(inlineBg)) return bg;
1223  const fromRgb = parseRgb(inlineBg);
1224  if (fromRgb) return fromRgb;
1225  const hexMatch = inlineBg.match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i);
1226  if (hexMatch) {
1227    const h = hexMatch[1];
1228    if (h.length === 6) {
1229      return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16), a: 1 };
1230    }
1231    return { r: parseInt(h[0] + h[0], 16), g: parseInt(h[1] + h[1], 16), b: parseInt(h[2] + h[2], 16), a: 1 };
1232  }
1233  return bg;
1234}
1235 
1236function resolveBackground(el, win, customPropMap) {
1237  let current = el;
1238  while (current && current.nodeType === 1) {
1239    const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
1240    const bgImage = style.backgroundImage || '';
1241    const hasGradientOrUrl = bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage));
1242 
1243    // Try the solid bg-color FIRST. If the element has both a solid color
1244    // and a gradient/url overlay (a common pattern: `background: var(--paper)
1245    // radial-gradient(...)` for paper-grain texture), the solid color is the
1246    // dominant visible surface for contrast purposes; the overlay is
1247    // decorative. The old behavior bailed on any gradient ancestor, which
1248    // caused massive false-positive contrast findings on grain-textured
1249    // body backgrounds.
1250    let bg = parseRgb(style.backgroundColor);
1251    if (!DETECTOR_IS_BROWSER && (!bg || bg.a < 0.1)) {
1252      // jsdom returns literal "var(--X)" / "oklch(...)" strings. Resolve
1253      // through customPropMap so Tailwind v4 color tokens become RGB.
1254      if (customPropMap) {
1255        bg = parseColorResolved(style.backgroundColor, customPropMap);
1256      }
1257      if (!bg || bg.a < 0.1) {
1258        // Inline-style fallback. jsdom doesn't decompose background
1259        // shorthand, so colors set via inline style are otherwise invisible.
1260        const rawStyle = current.getAttribute?.('style') || '';
1261        const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
1262        const inlineBg = bgMatch ? bgMatch[1].trim() : '';
1263        if (inlineBg && !/gradient/i.test(inlineBg) && !/url\s*\(/i.test(inlineBg)) {
1264          bg = parseColorResolved(inlineBg, customPropMap) || parseAnyColor(inlineBg);
1265        }
1266      }
1267    }
1268 
1269    if (bg && bg.a > 0.1) {
1270      if (DETECTOR_IS_BROWSER || bg.a >= 0.5) return bg;
1271    }
1272    // No solid bg-color at this level. If THIS level has a gradient/url
1273    // with no underlying solid color we can read:
1274    //   • on body/html: assume white. Body-level gradients are almost
1275    //     always decorative texture (paper grain, noise) on top of a
1276    //     solid bg-color the page set via `background: var(--paper)`
1277    //     shorthand — which jsdom can't decompose into bg-color. The
1278    //     downstream gradient-stops fallback path produces catastrophic
1279    //     false positives in this case (gradient noise stops have
1280    //     accidental browns/blacks that look like card backgrounds).
1281    //   • on other elements: bail to null and let the caller fall back
1282    //     to gradient stops (gradient buttons / hero sections are real
1283    //     bgs worth checking against).
1284    if (hasGradientOrUrl) {
1285      if (current.tagName === 'BODY' || current.tagName === 'HTML') {
1286        return { r: 255, g: 255, b: 255, a: 1 };
1287      }
1288      return null;
1289    }
1290    current = current.parentElement;
1291  }
1292  return { r: 255, g: 255, b: 255 };
1293}
1294 
1295// Walk parents looking for a gradient background and return its color stops.
1296// Used as a fallback when resolveBackground() returns null because the
1297// effective background is a gradient (no single solid color to compare against).
1298function resolveGradientStops(el, win) {
1299  let current = el;
1300  while (current && current.nodeType === 1) {
1301    const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
1302    const bgImage = style.backgroundImage || '';
1303    if (bgImage && bgImage !== 'none' && /gradient/i.test(bgImage)) {
1304      const stops = parseGradientColors(bgImage);
1305      if (stops.length > 0) return stops;
1306    }
1307    if (!DETECTOR_IS_BROWSER) {
1308      // jsdom doesn't decompose `background:` shorthand — peek at the raw inline style
1309      const rawStyle = current.getAttribute?.('style') || '';
1310      const bgMatch = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
1311      if (bgMatch && /gradient/i.test(bgMatch[1])) {
1312        const stops = parseGradientColors(bgMatch[1]);
1313        if (stops.length > 0) return stops;
1314      }
1315    }
1316    current = current.parentElement;
1317  }
1318  return null;
1319}
1320 
1321// Parse a single CSS length token to pixels. Accepts "12px", "50%", a
1322// shorthand like "12px 4px" (uses the first value), or empty / null.
1323// Returns the pixel value, or null when the input is unparseable.
1324// Percentages convert against `widthPx` when one is supplied. Without a
1325// usable width (jsdom returns "auto" for many real-world elements,
1326// which parseFloat collapses to 0), fall back to the raw percentage
1327// number so callers gating on `> 0` (border-accent-on-rounded,
1328// isCardLike's hasRadius) still see a positive value, matching the
1329// original parseFloat("50%") === 50 behavior.
1330function parseRadiusToPx(value, widthPx) {
1331  if (!value || typeof value !== 'string') return null;
1332  const trimmed = value.trim();
1333  if (!trimmed) return null;
1334  const first = trimmed.split(/\s+/)[0];
1335  const num = parseFloat(first);
1336  if (Number.isNaN(num)) return null;
1337  if (/%$/.test(first)) {
1338    if (widthPx && widthPx > 0) return (num / 100) * widthPx;
1339    return num;
1340  }
1341  return num;
1342}
1343 
1344function resolveBorderRadiusPx(el, style, widthPx, win) {
1345  const fromComputed = parseRadiusToPx(style.borderRadius, widthPx);
1346  if (fromComputed !== null) return fromComputed;
1347  return 0;
1348}
1349 
1350// ─── Section 5: Element Adapters ────────────────────────────────────────────
1351 
1352// Browser adapters — call getComputedStyle/getBoundingClientRect on live DOM
1353 
1354function checkElementBordersDOM(el) {
1355  const tag = el.tagName.toLowerCase();
1356  if (BORDER_SAFE_TAGS.has(tag)) return [];
1357  const rect = el.getBoundingClientRect();
1358  if (rect.width < 20 || rect.height < 20) return [];
1359  const style = getComputedStyle(el);
1360  const sides = ['Top', 'Right', 'Bottom', 'Left'];
1361  const widths = {}, colors = {};
1362  for (const s of sides) {
1363    widths[s] = parseFloat(style[`border${s}Width`]) || 0;
1364    colors[s] = style[`border${s}Color`] || '';
1365  }
1366  return checkBorders(tag, widths, colors, parseFloat(style.borderRadius) || 0);
1367}
1368 
1369function checkElementColorsDOM(el) {
1370  const tag = el.tagName.toLowerCase();
1371  // No early SAFE_TAGS bail here — checkColors() does its own gating that
1372  // includes the styled-button exception for <a> / <button> with their own
1373  // opaque background. Bailing here would prevent that exception from firing.
1374  const rect = el.getBoundingClientRect();
1375  if (rect.width < 10 || rect.height < 10) return [];
1376  const style = getComputedStyle(el);
1377  const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
1378  const hasDirectText = directText.trim().length > 0;
1379  const effectiveBg = resolveBackground(el);
1380  return checkColors({
1381    tag,
1382    textColor: parseRgb(style.color),
1383    bgColor: readOwnBackgroundColor(el, style),
1384    effectiveBg,
1385    effectiveBgStops: effectiveBg ? null : resolveGradientStops(el),
1386    fontSize: parseFloat(style.fontSize) || 16,
1387    fontWeight: parseInt(style.fontWeight) || 400,
1388    hasDirectText,
1389    isEmojiOnly: isEmojiOnlyText(directText),
1390    bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
1391    bgImage: style.backgroundImage || '',
1392    classList: el.getAttribute('class') || '',
1393  });
1394}
1395 
1396function checkElementIconTileDOM(el) {
1397  const tag = el.tagName.toLowerCase();
1398  if (!HEADING_TAGS.has(tag)) return [];
1399  const sibling = el.previousElementSibling;
1400  if (!sibling) return [];
1401 
1402  const sibRect = sibling.getBoundingClientRect();
1403  const headRect = el.getBoundingClientRect();
1404  const sibStyle = getComputedStyle(sibling);
1405 
1406  // The tile may either contain an <svg>/<i> icon child, OR the tile itself
1407  // may contain an emoji/symbol character directly as its only text content
1408  // (the "card-icon" pattern from many AI-generated demos).
1409  const iconChild = sibling.querySelector('svg, i[data-lucide], i[class*="fa-"], i[class*="icon"]');
1410  const iconRect = iconChild?.getBoundingClientRect();
1411  const sibDirectText = [...sibling.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
1412  const hasInlineEmojiIcon = sibling.children.length === 0 && isEmojiOnlyText(sibDirectText);
1413 
1414  return checkIconTile({
1415    headingTag: tag,
1416    headingText: el.textContent || '',
1417    headingTop: headRect.top,
1418    siblingTag: sibling.tagName.toLowerCase(),
1419    siblingWidth: sibRect.width,
1420    siblingHeight: sibRect.height,
1421    siblingBottom: sibRect.bottom,
1422    siblingBgColor: parseRgb(sibStyle.backgroundColor),
1423    siblingBgImage: sibStyle.backgroundImage || '',
1424    siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
1425    siblingBorderRadius: parseFloat(sibStyle.borderRadius) || 0,
1426    hasIconChild: !!iconChild || hasInlineEmojiIcon,
1427    iconChildWidth: iconRect?.width || 0,
1428  });
1429}
1430 
1431function checkElementItalicSerifDOM(el) {
1432  const tag = el.tagName.toLowerCase();
1433  if (tag !== 'h1' && tag !== 'h2') return [];
1434  const style = getComputedStyle(el);
1435  return checkItalicSerif({
1436    tag,
1437    fontStyle: style.fontStyle || '',
1438    fontFamily: style.fontFamily || '',
1439    fontSize: parseFloat(style.fontSize) || 0,
1440    headingText: el.textContent || '',
1441  });
1442}
1443 
1444function checkElementHeroEyebrowDOM(el) {
1445  const tag = el.tagName.toLowerCase();
1446  if (tag !== 'h1') return [];
1447  const sibling = el.previousElementSibling;
1448  if (!sibling) return [];
1449  const headStyle = getComputedStyle(el);
1450  const sibStyle = getComputedStyle(sibling);
1451  return checkHeroEyebrow({
1452    headingTag: tag,
1453    headingText: el.textContent || '',
1454    headingFontSize: parseFloat(headStyle.fontSize) || 0,
1455    siblingTag: sibling.tagName.toLowerCase(),
1456    siblingText: sibling.textContent || '',
1457    siblingTextTransform: sibStyle.textTransform || '',
1458    siblingFontSize: parseFloat(sibStyle.fontSize) || 0,
1459    siblingLetterSpacing: parseFloat(sibStyle.letterSpacing) || 0,
1460    siblingFontWeight: sibStyle.fontWeight || '',
1461    siblingColor: sibStyle.color || '',
1462  });
1463}
1464 
1465// Build a map of CSS custom properties declared on :root / :host / html.
1466// Used to resolve var(--X) refs that jsdom returns verbatim in
1467// getComputedStyle. Tailwind v4 routes every utility class through
1468// CSS vars (font-weight: var(--font-weight-bold), font-size:
1469// var(--text-xs), letter-spacing: var(--tracking-widest)), so without
1470// resolution every style-based check silently fails on Tailwind v4
1471// builds — the values come back as literal "var(--font-weight-bold)"
1472// strings and parseFloat returns NaN.
1473function buildCustomPropMap(document) {
1474  const map = new Map();
1475  let sheets;
1476  try { sheets = Array.from(document.styleSheets || []); }
1477  catch { return map; }
1478  for (const sheet of sheets) {
1479    let rules;
1480    try { rules = Array.from(sheet.cssRules || []); }
1481    catch { continue; }
1482    for (const rule of rules) {
1483      // Style rules only (type 1). Walk @media / @supports if present.
1484      if (rule.type === 4 /* MEDIA_RULE */ || rule.type === 12 /* SUPPORTS_RULE */) {
1485        try { rules.push(...Array.from(rule.cssRules || [])); } catch { /* ignore */ }
1486        continue;
1487      }
1488      if (rule.type !== 1 /* STYLE_RULE */) continue;
1489      const sel = rule.selectorText || '';
1490      if (!/(^|,\s*)(:root|html|:host)\b/i.test(sel)) continue;
1491      const style = rule.style;
1492      if (!style) continue;
1493      for (let i = 0; i < style.length; i++) {
1494        const prop = style[i];
1495        if (!prop || !prop.startsWith('--')) continue;
1496        const val = style.getPropertyValue(prop).trim();
1497        if (val) map.set(prop, val);
1498      }
1499    }
1500  }
1501  return map;
1502}
1503 
1504// Resolve var(--X[, fallback]) refs in a computed-style value string.
1505// Recurses up to 8 levels for chained refs (--a: var(--b)). Returns
1506// the original string when no refs are present or the chain doesn't
1507// resolve. Safe to call on already-resolved values.
1508function resolveVarRefs(raw, customPropMap, depth = 0) {
1509  if (typeof raw !== 'string' || !raw.includes('var(')) return raw;
1510  if (depth > 8) return raw;
1511  return raw.replace(/var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,\s*([^)]+))?\)/g, (_m, name, fallback) => {
1512    const v = customPropMap.get(name);
1513    if (v != null) return resolveVarRefs(v, customPropMap, depth + 1);
1514    return fallback ? resolveVarRefs(fallback.trim(), customPropMap, depth + 1) : _m;
1515  });
1516}
1517 
1518// OKLCH → sRGB conversion (Björn Ottosson's matrices). L in 0..1 (or %),
1519// C in 0..~0.4 typical, H in degrees. Returns clamped {r,g,b,a:1} in 0..255.
1520// Needed because jsdom doesn't compute oklch() values — getComputedStyle
1521// returns the literal "oklch(...)" string. Without this, the entire
1522// Tailwind v4 color palette (which is OKLCH-based) is invisible to the
1523// detector's contrast / color checks.
1524function oklchToRgb(L, C, H) {
1525  const hRad = (H * Math.PI) / 180;
1526  const a = C * Math.cos(hRad);
1527  const b = C * Math.sin(hRad);
1528  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
1529  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
1530  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
1531  const lc = l_ * l_ * l_, mc = m_ * m_ * m_, sc = s_ * s_ * s_;
1532  const rLin =  4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc;
1533  const gLin = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc;
1534  const bLin = -0.0041960863 * lc - 0.7034186147 * mc + 1.7076147010 * sc;
1535  const enc = (x) => {
1536    const c = Math.max(0, Math.min(1, x));
1537    return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
1538  };
1539  return {
1540    r: Math.round(enc(rLin) * 255),
1541    g: Math.round(enc(gLin) * 255),
1542    b: Math.round(enc(bLin) * 255),
1543    a: 1,
1544  };
1545}
1546 
1547// Extended color parser: rgb/rgba/hex/oklch. Returns null on no match.
1548// Use this when the input might be any CSS color form; use plain parseRgb
1549// when you only expect computed rgb() values from real browsers.
1550function parseAnyColor(s) {
1551  if (!s || typeof s !== 'string') return null;
1552  const str = s.trim();
1553  if (str === 'transparent' || str === 'currentcolor' || str === 'inherit') return null;
1554  let m;
1555  m = str.match(/rgba?\(\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)(?:\s*[,/]\s*([\d.]+))?\s*\)/);
1556  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 };
1557  m = str.match(/^#([0-9a-f]{3,8})$/i);
1558  if (m) {
1559    const h = m[1];
1560    if (h.length === 3 || h.length === 4) {
1561      return {
1562        r: parseInt(h[0] + h[0], 16),
1563        g: parseInt(h[1] + h[1], 16),
1564        b: parseInt(h[2] + h[2], 16),
1565        a: h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1,
1566      };
1567    }
1568    if (h.length === 6 || h.length === 8) {
1569      return {
1570        r: parseInt(h.slice(0, 2), 16),
1571        g: parseInt(h.slice(2, 4), 16),
1572        b: parseInt(h.slice(4, 6), 16),
1573        a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
1574      };
1575    }
1576  }
1577  // OKLCH parser. Tailwind v4's CSS minifier squishes the space after
1578  // `%` ("21.5%.02 50"), so the separator between L and C may be absent.
1579  // Match L (with optional %), then C and H separated permissively.
1580  m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?(?:\s*\/\s*([\d.]+)(%)?)?\s*\)/i);
1581  if (m) {
1582    const Lnum = parseFloat(m[1]);
1583    const L = m[2] === '%' ? Lnum / 100 : Lnum;
1584    const rgb = oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]));
1585    if (m[5] !== undefined) {
1586      const alpha = parseFloat(m[5]);
1587      rgb.a = m[6] === '%' ? alpha / 100 : alpha;
1588    }
1589    return rgb;
1590  }
1591  return null;
1592}
1593 
1594// Resolve var() refs in a color string (via customPropMap), then parse.
1595// Returns null on any failure. Used in jsdom-mode paths where
1596// getComputedStyle returns literal "var(--X)" or "oklch(...)" strings.
1597function parseColorResolved(str, customPropMap) {
1598  if (!str) return null;
1599  const resolved = customPropMap ? resolveVarRefs(str, customPropMap) : str;
1600  return parseAnyColor(resolved);
1601}
1602 
1603const REPEATED_KICKER_SKIP_SELECTOR = [
1604  'nav',
1605  'form',
1606  'table',
1607  'thead',
1608  'tbody',
1609  'tfoot',
1610  'figure',
1611  'figcaption',
1612  'ol',
1613  'ul',
1614  'li',
1615  '[role="navigation"]',
1616  '[aria-label*="breadcrumb" i]',
1617  '[class*="breadcrumb" i]',
1618  '[aria-hidden="true"]',
1619  '[data-impeccable-allow-kickers]',
1620].join(',');
1621 
1622const REPEATED_KICKER_CARD_CONTEXT_SELECTOR = [
1623  'article',
1624  'button',
1625  'a',
1626  'li',
1627  '[role="listitem"]',
1628  '[role="option"]',
1629].join(',');
1630 
1631function cleanInlineText(el) {
1632  return [...el.childNodes]
1633    .filter(n => n.nodeType === 3)
1634    .map(n => n.textContent)
1635    .join(' ')
1636    .replace(/\s+/g, ' ')
1637    .trim();
1638}
1639 
1640function isRepeatedKickerCardContext(heading, kicker) {
1641  const item = heading.closest?.(REPEATED_KICKER_CARD_CONTEXT_SELECTOR);
1642  return Boolean(item && (!item.contains || item.contains(kicker)));
1643}
1644 
1645function isRepeatedKickerCandidate(opts) {
1646  const {
1647    headingTag,
1648    headingText,
1649    headingFontSize,
1650    kickerTag,
1651    kickerText,
1652    kickerTextTransform,
1653    kickerFontSize,
1654    kickerLetterSpacing,
1655  } = opts;
1656  if (!['h2', 'h3', 'h4'].includes(headingTag)) return false;
1657  if (!headingText || headingText.length < 3) return false;
1658  if (/^\/[\w-]+/i.test(headingText.replace(/^"|"$/g, '').trim())) return false;
1659  if (!(headingFontSize >= 20)) return false;
1660  if (!kickerTag || HEADING_TAGS.has(kickerTag)) return false;
1661  if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false;
1662  if (!kickerText || kickerText.length < 2 || kickerText.length > 34) return false;
1663  if (/^step\s*\d+/i.test(kickerText) || /^\d{1,2}$/.test(kickerText)) return false;
1664 
1665  const isUppercased = kickerTextTransform === 'uppercase'
1666    || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText));
1667  if (!isUppercased) return false;
1668  if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false;
1669  const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08);
1670  if (!(kickerLetterSpacing >= minTrackedSpacing)) return false;
1671  return true;
1672}
1673 
1674function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpacing) {
1675  const candidates = [];
1676  for (const heading of doc.querySelectorAll('h2, h3, h4')) {
1677    if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
1678    const kicker = heading.previousElementSibling;
1679    if (!kicker || kicker.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
1680    if (isRepeatedKickerCardContext(heading, kicker)) continue;
1681 
1682    const headingStyle = getStyle(heading);
1683    const kickerStyle = getStyle(kicker);
1684    const headingText = (heading.textContent || '').replace(/\s+/g, ' ').trim();
1685    const kickerText = cleanInlineText(kicker) || (kicker.textContent || '').replace(/\s+/g, ' ').trim();
1686    const headingFontSize = resolveLetterSpacing(headingStyle.fontSize || '', 16) || parseFloat(headingStyle.fontSize) || 0;
1687    const kickerFontSize = resolveLetterSpacing(kickerStyle.fontSize || '', 16) || parseFloat(kickerStyle.fontSize) || 0;
1688    const kickerLetterSpacing = resolveLetterSpacing(kickerStyle.letterSpacing || '', kickerFontSize);
1689 
1690    if (!isRepeatedKickerCandidate({
1691      headingTag: heading.tagName.toLowerCase(),
1692      headingText,
1693      headingFontSize,
1694      kickerTag: kicker.tagName.toLowerCase(),
1695      kickerText,
1696      kickerTextTransform: kickerStyle.textTransform || '',
1697      kickerFontSize,
1698      kickerLetterSpacing,
1699    })) {
1700      continue;
1701    }
1702 
1703    candidates.push({
1704      headingTag: heading.tagName.toLowerCase(),
1705      headingText: headingText.replace(/^"|"$/g, '').slice(0, 60),
1706      kickerText: kickerText.slice(0, 40),
1707    });
1708  }
1709  return candidates;
1710}
1711 
1712function checkRepeatedSectionKickersDOM() {
1713  const candidates = collectRepeatedSectionKickerCandidates(
1714    document,
1715    (el) => getComputedStyle(el),
1716    (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
1717  );
1718  return checkRepeatedSectionKickers({ candidates });
1719}
1720 
1721function checkElementMotionDOM(el) {
1722  const tag = el.tagName.toLowerCase();
1723  if (SAFE_TAGS.has(tag)) return [];
1724  const style = getComputedStyle(el);
1725  return checkMotion({
1726    tag,
1727    transitionProperty: style.transitionProperty || '',
1728    animationName: style.animationName || '',
1729    timingFunctions: [style.animationTimingFunction, style.transitionTimingFunction].filter(Boolean).join(' '),
1730    classList: el.getAttribute('class') || '',
1731  });
1732}
1733 
1734function checkElementGlowDOM(el) {
1735  const tag = el.tagName.toLowerCase();
1736  const style = getComputedStyle(el);
1737  if (!style.boxShadow || style.boxShadow === 'none') return [];
1738  // Use parent's background — glow radiates outward, so the surrounding context matters
1739  // If resolveBackground returns null (gradient), try to infer from the gradient colors
1740  let parentBg = el.parentElement ? resolveBackground(el.parentElement) : resolveBackground(el);
1741  if (!parentBg) {
1742    // Gradient background — sample its colors to determine if it's dark
1743    let cur = el.parentElement;
1744    while (cur && cur.nodeType === 1) {
1745      const bgImage = getComputedStyle(cur).backgroundImage || '';
1746      const gradColors = parseGradientColors(bgImage);
1747      if (gradColors.length > 0) {
1748        // Average the gradient colors
1749        const avg = { r: 0, g: 0, b: 0 };
1750        for (const c of gradColors) { avg.r += c.r; avg.g += c.g; avg.b += c.b; }
1751        avg.r = Math.round(avg.r / gradColors.length);
1752        avg.g = Math.round(avg.g / gradColors.length);
1753        avg.b = Math.round(avg.b / gradColors.length);
1754        parentBg = avg;
1755        break;
1756      }
1757      cur = cur.parentElement;
1758    }
1759  }
1760  return checkGlow({ tag, boxShadow: style.boxShadow, effectiveBg: parentBg });
1761}
1762 
1763function checkElementAIPaletteDOM(el) {
1764  const style = getComputedStyle(el);
1765  const findings = [];
1766 
1767  // Check gradient backgrounds for purple/violet or cyan
1768  const bgImage = style.backgroundImage || '';
1769  const gradColors = parseGradientColors(bgImage);
1770  for (const c of gradColors) {
1771    if (hasChroma(c, 50)) {
1772      const hue = getHue(c);
1773      if (hue >= 260 && hue <= 310) {
1774        findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet gradient background' });
1775        break;
1776      }
1777      if (hue >= 160 && hue <= 200) {
1778        findings.push({ id: 'ai-color-palette', snippet: 'Cyan gradient background' });
1779        break;
1780      }
1781    }
1782  }
1783 
1784  // Check for neon text (vivid cyan/purple color on dark background)
1785  const textColor = parseRgb(style.color);
1786  if (textColor && hasChroma(textColor, 80)) {
1787    const hue = getHue(textColor);
1788    const isAIPalette = (hue >= 160 && hue <= 200) || (hue >= 260 && hue <= 310);
1789    if (isAIPalette) {
1790      const parentBg = el.parentElement ? resolveBackground(el.parentElement) : null;
1791      // Also check gradient parents
1792      let effectiveBg = parentBg;
1793      if (!effectiveBg) {
1794        let cur = el.parentElement;
1795        while (cur && cur.nodeType === 1) {
1796          const gi = getComputedStyle(cur).backgroundImage || '';
1797          const gc = parseGradientColors(gi);
1798          if (gc.length > 0) {
1799            const avg = { r: 0, g: 0, b: 0 };
1800            for (const c of gc) { avg.r += c.r; avg.g += c.g; avg.b += c.b; }
1801            avg.r = Math.round(avg.r / gc.length);
1802            avg.g = Math.round(avg.g / gc.length);
1803            avg.b = Math.round(avg.b / gc.length);
1804            effectiveBg = avg;
1805            break;
1806          }
1807          cur = cur.parentElement;
1808        }
1809      }
1810      if (effectiveBg && relativeLuminance(effectiveBg) < 0.1) {
1811        const label = hue >= 260 ? 'Purple/violet' : 'Cyan';
1812        findings.push({ id: 'ai-color-palette', snippet: `${label} neon text on dark background` });
1813      }
1814    }
1815  }
1816 
1817  return findings;
1818}
1819 
1820const QUALITY_TEXT_TAGS = new Set(['p', 'li', 'td', 'th', 'dd', 'blockquote', 'figcaption']);
1821 
1822// Resolve a CSS font-size value to pixels by walking up the parent chain.
1823// Browsers resolve em/rem/% to px in getComputedStyle, but jsdom returns the
1824// specified value verbatim — so for the Node path we walk parents ourselves.
1825function resolveFontSizePx(el, win) {
1826  const chain = []; // raw font-size strings, leaf → root
1827  let cur = el;
1828  while (cur && cur.nodeType === 1) {
1829    const fs = (win ? win.getComputedStyle(cur) : getComputedStyle(cur)).fontSize;
1830    chain.push(fs || '');
1831    cur = cur.parentElement;
1832  }
1833  // Walk root → leaf, resolving each value relative to its parent context.
1834  let px = 16; // root default
1835  for (let i = chain.length - 1; i >= 0; i--) {
1836    const v = chain[i];
1837    if (!v || v === 'inherit') continue;
1838    const num = parseFloat(v);
1839    if (isNaN(num)) continue;
1840    if (v.endsWith('px')) px = num;
1841    else if (v.endsWith('rem')) px = num * 16;
1842    else if (v.endsWith('em')) px = num * px;
1843    else if (v.endsWith('%')) px = (num / 100) * px;
1844    else px = num; // unitless — already resolved
1845  }
1846  return px;
1847}
1848 
1849// Resolve a CSS length value (line-height, letter-spacing, etc.) given a
1850// known font-size context. Returns null for "normal" / unparseable values.
1851function resolveLengthPx(value, fontSizePx) {
1852  if (!value || value === 'normal' || value === 'auto' || value === 'inherit') return null;
1853  const num = parseFloat(value);
1854  if (isNaN(num)) return null;
1855  if (value.endsWith('px')) return num;
1856  if (value.endsWith('rem')) return num * 16;
1857  if (value.endsWith('em')) return num * fontSizePx;
1858  if (value.endsWith('%')) return (num / 100) * fontSizePx;
1859  // Unitless line-height = multiplier, return px equivalent
1860  return num * fontSizePx;
1861}
1862 
1863function cssColorIsTransparent(value) {
1864  if (!value) return true;
1865  const str = String(value).trim().toLowerCase();
1866  if (!str || str === 'transparent' || str === 'rgba(0, 0, 0, 0)') return true;
1867  const parsed = parseAnyColor(str);
1868  if (parsed) return (parsed.a ?? 1) <= 0.05;
1869  return /^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*0(?:\.0+)?\s*\)$/.test(str);
1870}
1871 
1872function colorsNearlyMatch(a, b) {
1873  const ca = parseAnyColor(a);
1874  const cb = parseAnyColor(b);
1875  if (!ca || !cb) return false;
1876  const alphaDelta = Math.abs((ca.a ?? 1) - (cb.a ?? 1));
1877  const channelDelta = Math.max(
1878    Math.abs(ca.r - cb.r),
1879    Math.abs(ca.g - cb.g),
1880    Math.abs(ca.b - cb.b),
1881  );
1882  return alphaDelta <= 0.03 && channelDelta <= 3;
1883}
1884 
1885function getComputedStyleFor(win, el) {
1886  if (win && typeof win.getComputedStyle === 'function') {
1887    try { return win.getComputedStyle(el); } catch {}
1888  }
1889  if (typeof getComputedStyle === 'function') {
1890    try { return getComputedStyle(el); } catch {}
1891  }
1892  return null;
1893}
1894 
1895function hasVisibleBackgroundBoundary(style, el, win) {
1896  const bg = style?.backgroundColor || '';
1897  if (cssColorIsTransparent(bg)) return false;
1898 
1899  let parent = el?.parentElement || null;
1900  while (parent) {
1901    const parentStyle = getComputedStyleFor(win, parent);
1902    const parentBg = parentStyle?.backgroundColor || '';
1903    if (!cssColorIsTransparent(parentBg)) {
1904      return !colorsNearlyMatch(bg, parentBg);
1905    }
1906    parent = parent.parentElement;
1907  }
1908 
1909  return true;
1910}
1911 
1912const TEXT_EDGE_TAGS = new Set(['A', 'BUTTON', 'CODE', 'DD', 'DT', 'FIGCAPTION', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'LI', 'P', 'PRE', 'SPAN', 'TD', 'TH']);
1913 
1914function hasMeaningfulDirectText(node) {
1915  if (!node?.childNodes) return false;
1916  for (const child of node.childNodes) {
1917    if (child.nodeType === 3 && child.textContent.trim().length > 4) return true;
1918  }
1919  return false;
1920}
1921 
1922function textDescendantsFlushSides(el, rect) {
1923  const flush = { top: false, right: false, bottom: false, left: false };
1924  if (!rect || !el?.querySelectorAll) return flush;
1925  const TEXT_EDGE_THRESHOLD = 4;
1926  const candidates = el.querySelectorAll('a, button, code, dd, dt, figcaption, h1, h2, h3, h4, h5, h6, li, p, pre, span, td, th');
1927  for (const node of candidates) {
1928    if (!TEXT_EDGE_TAGS.has(node.tagName) || !hasMeaningfulDirectText(node)) continue;
1929    let nodeRect = null;
1930    try { nodeRect = node.getBoundingClientRect(); } catch {}
1931    if (!nodeRect || nodeRect.width <= 0 || nodeRect.height <= 0) continue;
1932    if (nodeRect.bottom < rect.top || nodeRect.top > rect.bottom || nodeRect.right < rect.left || nodeRect.left > rect.right) continue;
1933    if (nodeRect.top - rect.top <= TEXT_EDGE_THRESHOLD) flush.top = true;
1934    if (rect.right - nodeRect.right <= TEXT_EDGE_THRESHOLD) flush.right = true;
1935    if (rect.bottom - nodeRect.bottom <= TEXT_EDGE_THRESHOLD) flush.bottom = true;
1936    if (nodeRect.left - rect.left <= TEXT_EDGE_THRESHOLD) flush.left = true;
1937  }
1938  return flush;
1939}
1940 
1941// Pure quality checks. Most run on computed CSS and DOM-only inputs (work in
1942// jsdom and the browser). Two checks (line-length, cramped-padding) gate on
1943// element rect dimensions, which jsdom can't compute — pass `rect: null` from
1944// the Node adapter to skip those.
1945//
1946// Both adapters resolve font-size, line-height and letter-spacing to pixels
1947// before calling this so the pure function only deals with numbers.
1948function checkQuality(opts) {
1949  const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0, win = null } = opts;
1950  const findings = [];
1951  // Skip browser extension injected elements
1952  const elId = el.id || '';
1953  if (elId.startsWith('claude-') || elId.startsWith('cic-')) return findings;
1954 
1955  // --- Line length too long --- (browser-only: needs rect.width)
1956  if (rect && hasDirectText && QUALITY_TEXT_TAGS.has(tag) && rect.width > 0 && textLen > lineMax) {
1957    const charsPerLine = rect.width / (fontSize * 0.5);
1958    if (charsPerLine > lineMax + 5) {
1959      findings.push({ id: 'line-length', snippet: `~${Math.round(charsPerLine)} chars/line (aim for <${lineMax})` });
1960    }
1961  }
1962 
1963  // --- Cramped padding --- (browser-only: needs rect to skip small badges/labels)
1964  // Vertical and horizontal thresholds are independent because line-height
1965  // already provides built-in vertical breathing room (the line box is taller
1966  // than the cap height), but horizontal has no equivalent. Both scale with
1967  // font-size — bigger text demands proportionally more padding.
1968  //   vertical:   max(4px, fontSize × 0.3)
1969  //   horizontal: max(8px, fontSize × 0.5)
1970  const isInlineCode = tag === 'code' && !(el.closest && el.closest('pre'));
1971  if (!isInlineCode && rect && hasDirectText && textLen > 20 && rect.width > 100 && rect.height > 30) {
1972    const borders = {
1973      top: parseFloat(style.borderTopWidth) || 0,
1974      right: parseFloat(style.borderRightWidth) || 0,
1975      bottom: parseFloat(style.borderBottomWidth) || 0,
1976      left: parseFloat(style.borderLeftWidth) || 0,
1977    };
1978    const borderCount = Object.values(borders).filter(w => w > 0).length;
1979    const hasBg = hasVisibleBackgroundBoundary(style, el, win);
1980    if (borderCount >= 2 || hasBg) {
1981      const vPads = [], hPads = [];
1982      if (hasBg || borders.top > 0) vPads.push(parseFloat(style.paddingTop) || 0);
1983      if (hasBg || borders.bottom > 0) vPads.push(parseFloat(style.paddingBottom) || 0);
1984      if (hasBg || borders.left > 0) hPads.push(parseFloat(style.paddingLeft) || 0);
1985      if (hasBg || borders.right > 0) hPads.push(parseFloat(style.paddingRight) || 0);
1986 
1987      const vMin = vPads.length ? Math.min(...vPads) : Infinity;
1988      const hMin = hPads.length ? Math.min(...hPads) : Infinity;
1989      const vThresh = Math.max(4, fontSize * 0.3);
1990      const hThresh = Math.max(8, fontSize * 0.5);
1991 
1992      // Emit at most one finding per element — pick whichever axis is worse.
1993      if (vMin < vThresh) {
1994        findings.push({ id: 'cramped-padding', snippet: `${vMin}px vertical padding (need ≥${vThresh.toFixed(1)}px for ${fontSize}px text)` });
1995      } else if (hMin < hThresh) {
1996        findings.push({ id: 'cramped-padding', snippet: `${hMin}px horizontal padding (need ≥${hThresh.toFixed(1)}px for ${fontSize}px text)` });
1997      }
1998    }
1999  }
2000 
2001  // --- Flush against a visible boundary ---
2002  // Fires when a container has a visible boundary (border, outline, OR a
2003  // non-transparent background) AND near-zero padding on the bounded
2004  // side(s) AND text-bearing children land flush against the boundary.
2005  //
2006  // Distinct from cramped-padding: that rule needs the element itself to
2007  // have direct text (hasDirectText). This rule targets the OPPOSITE
2008  // shape — a container with NO direct text, only children — which is
2009  // exactly what cramped-padding misses (a section wrapping a label +
2010  // list lands a free pass).
2011  //
2012  // The classic shape: agent writes `padding: 28px 0 0` shorthand on a
2013  // section that also has a border, zeroing horizontal padding so the
2014  // text-bearing children touch the side borders. Background and
2015  // outline count too: a colored card with zero padding has the same
2016  // visual failure mode.
2017  {
2018    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']);
2019    const upperTag = tag ? tag.toUpperCase() : '';
2020    const elPosition = style.position || '';
2021    if (
2022      !FLUSH_SKIP_TAGS.has(upperTag) &&
2023      !hasDirectText &&
2024      !['fixed', 'absolute'].includes(elPosition) &&
2025      el.children && el.children.length > 0
2026    ) {
2027      const borderW = {
2028        top:    parseFloat(style.borderTopWidth)    || 0,
2029        right:  parseFloat(style.borderRightWidth)  || 0,
2030        bottom: parseFloat(style.borderBottomWidth) || 0,
2031        left:   parseFloat(style.borderLeftWidth)   || 0,
2032      };
2033      const borderVisible = {
2034        top:    borderW.top    > 0 && !cssColorIsTransparent(style.borderTopColor),
2035        right:  borderW.right  > 0 && !cssColorIsTransparent(style.borderRightColor),
2036        bottom: borderW.bottom > 0 && !cssColorIsTransparent(style.borderBottomColor),
2037        left:   borderW.left   > 0 && !cssColorIsTransparent(style.borderLeftColor),
2038      };
2039      // Outline detection. jsdom decomposes `border` shorthand into
2040      // border{Top,…}Width/Color but does NOT decompose `outline` —
2041      // the longhands come back empty when the value was set via the
2042      // shorthand. Fall back to parsing `style.outline` ourselves.
2043      let outlineW = parseFloat(style.outlineWidth) || 0;
2044      let outlineStyleVal = style.outlineStyle || '';
2045      let outlineColorVal = style.outlineColor || '';
2046      if (!outlineW && style.outline) {
2047        const wMatch = style.outline.match(/(\d+(?:\.\d+)?)\s*px/);
2048        if (wMatch) outlineW = parseFloat(wMatch[1]) || 0;
2049        if (!outlineStyleVal) {
2050          outlineStyleVal = /\b(solid|dashed|dotted|double|groove|ridge|inset|outset)\b/.test(style.outline) ? 'solid' : '';
2051        }
2052        if (!outlineColorVal) {
2053          const cMatch = style.outline.match(/(rgba?\([^)]+\)|#[0-9a-fA-F]{3,8}|[a-zA-Z]+)\s*$/);
2054          if (cMatch) outlineColorVal = cMatch[1];
2055        }
2056      }
2057      const outlineVisible = outlineW > 0 && !cssColorIsTransparent(outlineColorVal) && outlineStyleVal && outlineStyleVal !== 'none';
2058      const bgVisible = hasVisibleBackgroundBoundary(style, el, win);
2059 
2060      const anyVisible = borderVisible.top || borderVisible.right || borderVisible.bottom || borderVisible.left || outlineVisible || bgVisible;
2061      if (anyVisible) {
2062        // Resolve padding to px (jsdom returns raw "1.5rem" etc., not the
2063        // computed px value; parseFloat would strip the unit and treat
2064        // 1.5rem as 1.5px, false-flagging legitimate insets).
2065        const pad = {
2066          top:    resolveLengthPx(style.paddingTop,    fontSize) ?? 0,
2067          right:  resolveLengthPx(style.paddingRight,  fontSize) ?? 0,
2068          bottom: resolveLengthPx(style.paddingBottom, fontSize) ?? 0,
2069          left:   resolveLengthPx(style.paddingLeft,   fontSize) ?? 0,
2070        };
2071        const PAD_THRESHOLD = 2;
2072        // Children-insulate-this-side: a side is insulated if ANY direct
2073        // child has its own padding ≥ 4px on that side. Rationale: in
2074        // typical flow, only the first/last (or leftmost/rightmost)
2075        // children actually sit at the parent's edges. If even one of
2076        // them has its own padding, the visual flush is broken on that
2077        // side. Classic example: a column-flow card frame where the
2078        // top child (header) has padding-top:12 and the bottom child
2079        // (footer) has padding-bottom:8 — the parent's padding:0 doesn't
2080        // matter; nothing is actually flush. The `any-child-insulates`
2081        // heuristic accepts some false negatives (a card with one heavily
2082        // padded middle child won't flag) for far fewer false positives.
2083        const CHILD_INSULATE_THRESHOLD = 4;
2084        const childrenInsulate = { top: false, right: false, bottom: false, left: false };
2085        for (const child of el.children) {
2086          let childStyle = getComputedStyleFor(win, child);
2087          if (!childStyle) continue;
2088          const childPad = {
2089            top:    resolveLengthPx(childStyle.paddingTop,    fontSize) ?? 0,
2090            right:  resolveLengthPx(childStyle.paddingRight,  fontSize) ?? 0,
2091            bottom: resolveLengthPx(childStyle.paddingBottom, fontSize) ?? 0,
2092            left:   resolveLengthPx(childStyle.paddingLeft,   fontSize) ?? 0,
2093          };
2094          const childMargin = {
2095            top:    resolveLengthPx(childStyle.marginTop,    fontSize) ?? 0,
2096            right:  resolveLengthPx(childStyle.marginRight,  fontSize) ?? 0,
2097            bottom: resolveLengthPx(childStyle.marginBottom, fontSize) ?? 0,
2098            left:   resolveLengthPx(childStyle.marginLeft,   fontSize) ?? 0,
2099          };
2100          if (rect && typeof child.getBoundingClientRect === 'function') {
2101            try {
2102              const childRect = child.getBoundingClientRect();
2103              if (childRect && childRect.width > 0 && childRect.height > 0) {
2104                if (childRect.top - rect.top >= CHILD_INSULATE_THRESHOLD) childrenInsulate.top = true;
2105                if (rect.right - childRect.right >= CHILD_INSULATE_THRESHOLD) childrenInsulate.right = true;
2106                if (rect.bottom - childRect.bottom >= CHILD_INSULATE_THRESHOLD) childrenInsulate.bottom = true;
2107                if (childRect.left - rect.left >= CHILD_INSULATE_THRESHOLD) childrenInsulate.left = true;
2108              }
2109            } catch {}
2110          }
2111          for (const s of ['top', 'right', 'bottom', 'left']) {
2112            if (childPad[s] >= CHILD_INSULATE_THRESHOLD || childMargin[s] >= CHILD_INSULATE_THRESHOLD) {
2113              childrenInsulate[s] = true;
2114            }
2115          }
2116        }
2117 
2118        const textFlush = rect ? textDescendantsFlushSides(el, rect) : null;
2119        const fullBleedBgBand = rect && viewportWidth > 0 && rect.width >= viewportWidth * 0.94 && bgVisible && !outlineVisible;
2120        const flushSides = [];
2121        for (const side of ['top', 'right', 'bottom', 'left']) {
2122          const bgBoundsSide = bgVisible && !(fullBleedBgBand && (side === 'left' || side === 'right'));
2123          const sideBounded = borderVisible[side] || outlineVisible || bgBoundsSide;
2124          if (sideBounded && pad[side] <= PAD_THRESHOLD && !childrenInsulate[side] && (!textFlush || textFlush[side])) {
2125            flushSides.push(side);
2126          }
2127        }
2128 
2129        if (flushSides.length > 0) {
2130          // Confirm at least one direct child has substantial text content
2131          // (> 4 chars). Without this, the flush is harmless: e.g. an
2132          // image-only card.
2133          let hasTextChild = false;
2134          for (const child of el.children) {
2135            const childText = (child.textContent || '').trim();
2136            if (childText.length > 4) { hasTextChild = true; break; }
2137          }
2138          if (hasTextChild) {
2139            const cls = (typeof el.className === 'string' && el.className.trim())
2140              ? el.className.trim().split(/\s+/)[0]
2141              : '';
2142            const boundaryParts = [];
2143            const borderSidesVisible = ['top', 'right', 'bottom', 'left'].filter(s => borderVisible[s]);
2144            if (borderSidesVisible.length === 4) boundaryParts.push('border');
2145            else if (borderSidesVisible.length > 0) boundaryParts.push(`border-${borderSidesVisible.join('/')}`);
2146            if (outlineVisible) boundaryParts.push('outline');
2147            if (bgVisible) boundaryParts.push('bg');
2148            const sidesLabel = flushSides.length === 4 ? 'all sides' : flushSides.join('/');
2149            const ident = cls
2150              ? `<${tag.toLowerCase()}> "${cls}"`
2151              : `<${tag.toLowerCase()}>`;
2152            findings.push({
2153              id: 'cramped-padding',
2154              snippet: `${ident}: children flush against ${boundaryParts.join('+')} on ${sidesLabel} (no inset)`,
2155            });
2156          }
2157        }
2158      }
2159    }
2160  }
2161 
2162  // --- Body text touching viewport edge --- (browser-only: needs rect)
2163  // Catches the failure mode where the agent ships body paragraphs
2164  // with NO container providing horizontal padding — text bleeds
2165  // directly to the viewport edge. Different from cramped-padding,
2166  // which requires a colored/bordered container. Here the failure
2167  // is the absence of the container entirely.
2168  //
2169  // Gate aggressively to avoid false positives:
2170  //   - <p> or <li> only (body content; not headings, not nav, not
2171  //     wrappers)
2172  //   - text > 40 chars (paragraph-like, not a label)
2173  //   - rect.width > 50% of viewport (real body, not a pull-quote)
2174  //   - rect.left < 16 OR rect.right > viewport - 16 (actually
2175  //     touching the edge)
2176  //   - not inside <nav> or <header> (those legitimately bleed)
2177  //   - element itself has no background-color (intentional full-bleed
2178  //     sections set a bg-color and provide their own internal padding)
2179  if (rect && hasDirectText && textLen > 40 && ['P', 'LI'].includes(tag.toUpperCase()) && viewportWidth > 0) {
2180    const inNavHeader = el.closest && (el.closest('nav') || el.closest('header'));
2181    const hasOwnBg = style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)' && style.backgroundColor !== 'transparent';
2182    const isPositioned = ['fixed', 'absolute'].includes(style.position || '');
2183    const widthRatio = rect.width / viewportWidth;
2184    const leftClose = rect.left < 16;
2185    const rightClose = rect.right > viewportWidth - 16;
2186    if (!inNavHeader && !hasOwnBg && !isPositioned && widthRatio > 0.5 && (leftClose || rightClose)) {
2187      const which = leftClose && rightClose
2188        ? `left ${Math.round(rect.left)}px / right ${Math.round(viewportWidth - rect.right)}px`
2189        : leftClose
2190          ? `left ${Math.round(rect.left)}px`
2191          : `right ${Math.round(viewportWidth - rect.right)}px`;
2192      findings.push({ id: 'body-text-viewport-edge', snippet: `<${tag.toLowerCase()}> with ${textLen}-char body bleeds to viewport edge (${which})` });
2193    }
2194  }
2195 
2196  // --- Tight line height ---
2197  if (hasDirectText && textLen > 50 && !['h1','h2','h3','h4','h5','h6'].includes(tag)) {
2198    if (lineHeightPx != null && fontSize > 0) {
2199      const ratio = lineHeightPx / fontSize;
2200      if (ratio > 0 && ratio < 1.3) {
2201        findings.push({ id: 'tight-leading', snippet: `line-height ${ratio.toFixed(2)}x (need >=1.3)` });
2202      }
2203    }
2204  }
2205 
2206  // --- Justified text (without hyphens) ---
2207  if (hasDirectText && style.textAlign === 'justify') {
2208    const hyphens = style.hyphens || style.webkitHyphens || '';
2209    if (hyphens !== 'auto') {
2210      findings.push({ id: 'justified-text', snippet: 'text-align: justify without hyphens: auto' });
2211    }
2212  }
2213 
2214  // --- Tiny body text ---
2215  // Only flag actual body content, not UI labels (buttons, tabs, badges, captions, footer text, etc.)
2216  if (hasDirectText && textLen > 20 && fontSize < 12) {
2217    const skipTags = ['sub', 'sup', 'code', 'kbd', 'samp', 'var', 'caption', 'figcaption'];
2218    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]');
2219    const isUppercase = style.textTransform === 'uppercase';
2220    if (!skipTags.includes(tag) && !inUIContext && !isUppercase) {
2221      findings.push({ id: 'tiny-text', snippet: `${fontSize}px body text` });
2222    }
2223  }
2224 
2225  // --- All-caps body text ---
2226  if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
2227    if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
2228      findings.push({ id: 'all-caps-body', snippet: `text-transform: uppercase on ${textLen} chars of body text` });
2229    }
2230  }
2231 
2232  // --- Wide letter spacing on body text ---
2233  if (hasDirectText && textLen > 20 && style.textTransform !== 'uppercase') {
2234    if (letterSpacingPx != null && letterSpacingPx > 0 && fontSize > 0) {
2235      const trackingEm = letterSpacingPx / fontSize;
2236      if (trackingEm > 0.05) {
2237        findings.push({ id: 'wide-tracking', snippet: `letter-spacing: ${trackingEm.toFixed(2)}em on body text` });
2238      }
2239    }
2240  }
2241 
2242  // --- Crushed letter spacing (mirror of wide-tracking) ---
2243  // Tracking pulled tighter than ~-0.05em crushes characters into each other.
2244  // Optical tightening that display type legitimately wants (around -0.02em)
2245  // stays well above this floor.
2246  if (hasDirectText && textLen > 20 && fontSize > 0) {
2247    if (letterSpacingPx != null && letterSpacingPx < 0) {
2248      const trackingEm = letterSpacingPx / fontSize;
2249      if (trackingEm <= -0.05) {
2250        const excerpt = (el.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 40);
2251        findings.push({ id: 'extreme-negative-tracking', snippet: `letter-spacing: ${trackingEm.toFixed(2)}em — "${excerpt}"` });
2252      }
2253    }
2254  }
2255 
2256  return findings;
2257}
2258 
2259function checkElementQualityDOM(el) {
2260  const tag = el.tagName.toLowerCase();
2261  const style = getComputedStyle(el);
2262  const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 10);
2263  const textLen = el.textContent?.trim().length || 0;
2264  // Browser getComputedStyle resolves everything to px — direct parseFloat
2265  // works.
2266  const fontSize = parseFloat(style.fontSize) || 16;
2267  const lineHeightPx = resolveLengthPx(style.lineHeight, fontSize);
2268  const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize);
2269  const rect = el.getBoundingClientRect();
2270  const lineMax = (typeof window !== 'undefined' && window.__IMPECCABLE_CONFIG__?.lineLengthMax) || 80;
2271  const viewportWidth = (typeof window !== 'undefined' ? window.innerWidth : 0) || 0;
2272  return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax, viewportWidth, win: typeof window !== 'undefined' ? window : null });
2273}
2274 
2275// Pure page-level skipped-heading walk. Takes a Document so it works in both
2276// the browser and jsdom.
2277function checkPageQualityFromDoc(doc) {
2278  const findings = [];
2279  const headings = doc.querySelectorAll('h1, h2, h3, h4, h5, h6');
2280  let prevLevel = 0;
2281  let prevText = '';
2282  for (const h of headings) {
2283    const level = parseInt(h.tagName[1]);
2284    const text = (h.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 60);
2285    if (prevLevel > 0 && level > prevLevel + 1) {
2286      findings.push({
2287        id: 'skipped-heading',
2288        snippet: `<h${prevLevel}> "${prevText}" followed by <h${level}> "${text}" (missing h${prevLevel + 1})`,
2289      });
2290    }
2291    prevLevel = level;
2292    prevText = text;
2293  }
2294  return findings;
2295}
2296 
2297// Browser adapter (returns the legacy { type, detail } shape used by the overlay loop)
2298function checkPageQualityDOM() {
2299  return checkPageQualityFromDoc(document).map(f => ({ type: f.id, detail: f.snippet }));
2300}
2301 
2302// Node adapters — take pre-extracted jsdom computed style
2303 
2304// jsdom doesn't lay out OR resolve em/rem/% to px — so we pre-resolve every
2305// CSS length the rule needs ourselves (walking the parent chain for
2306// font-size inheritance), and pass `rect: null` to skip the two rules that
2307// genuinely need element rects (line-length, cramped-padding).
2308function checkElementQuality(el, style, tag, window) {
2309  const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 10);
2310  const textLen = el.textContent?.trim().length || 0;
2311  const fontSize = resolveFontSizePx(el, window);
2312  const lineHeightPx = resolveLengthPx(style.lineHeight, fontSize);
2313  const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize);
2314  return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null, win: window });
2315}
2316 
2317function checkElementBorders(tag, style, overrides, resolvedRadius) {
2318  const sides = ['Top', 'Right', 'Bottom', 'Left'];
2319  const widths = {}, colors = {};
2320  for (const s of sides) {
2321    widths[s] = parseFloat(style[`border${s}Width`]) || 0;
2322    colors[s] = style[`border${s}Color`] || '';
2323    // jsdom silently drops any border shorthand containing var(), leaving
2324    // both width and color empty on the computed style. When the detectHtml
2325    // pre-pass pulled a resolved value off the rule, use it to fill in the
2326    // missing side so the side-tab check can run. Real browsers resolve
2327    // var() natively, so this fallback is a no-op in the browser path.
2328    if (widths[s] === 0 && overrides && overrides[s]) {
2329      widths[s] = overrides[s].width;
2330      colors[s] = overrides[s].color;
2331    } else if (colors[s] && colors[s].startsWith('var(') && overrides && overrides[s]) {
2332      // Longhand case: jsdom kept the width but left the color as the
2333      // literal `var(...)` string. Substitute the resolved color.
2334      colors[s] = overrides[s].color;
2335    }
2336  }
2337  // resolvedRadius lets the caller pre-resolve the radius via
2338  // resolveBorderRadiusPx so the value survives jsdom 29.1.0's broken
2339  // shorthand serialization. Falls back to the computed value for tests
2340  // and browser callers that don't pre-resolve.
2341  const radius = resolvedRadius != null
2342    ? resolvedRadius
2343    : (parseFloat(style.borderRadius) || 0);
2344  return checkBorders(tag, widths, colors, radius);
2345}
2346 
2347function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInheritRule) {
2348  const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
2349  const hasDirectText = directText.trim().length > 0;
2350 
2351  const effectiveBg = resolveBackground(el, window, customPropMap);
2352  // jsdom returns literal "var(--X)" / "oklch(...)" for color, so plain
2353  // parseRgb misses Tailwind-tokenized text colors. Resolve through the
2354  // customPropMap first; fall back to parseRgb for vanilla rgb() pages.
2355  let textColor = customPropMap ? parseColorResolved(style.color, customPropMap) : null;
2356  if (!textColor) textColor = parseRgb(style.color);
2357 
2358  // Anchor-inherit FP workaround: jsdom's UA stylesheet has `:link { color:
2359  // blue }` at high specificity. The page's `a { color: inherit }` rule
2360  // (Tailwind v4 preflight) loses to jsdom even though it WINS in real
2361  // browsers (Chrome's UA wraps :link in :where() — zero specificity).
2362  // When the page declares the inherit rule AND we see jsdom's default
2363  // link blue on an anchor, walk to the nearest non-anchor ancestor and
2364  // use its color instead.
2365  if (
2366    hasAnchorInheritRule &&
2367    textColor &&
2368    textColor.r === 0 && textColor.g === 0 && textColor.b === 238 &&
2369    (tag === 'a' || el.closest?.('a'))
2370  ) {
2371    let cur = el.parentElement;
2372    while (cur && cur.tagName !== 'HTML') {
2373      if (cur.tagName !== 'A') {
2374        const ps = window.getComputedStyle(cur);
2375        const inh = (customPropMap ? parseColorResolved(ps.color, customPropMap) : null) || parseRgb(ps.color);
2376        if (inh && !(inh.r === 0 && inh.g === 0 && inh.b === 238)) {
2377          textColor = inh;
2378          break;
2379        }
2380      }
2381      cur = cur.parentElement;
2382    }
2383  }
2384 
2385  return checkColors({
2386    tag,
2387    textColor,
2388    bgColor: readOwnBackgroundColor(el, style),
2389    effectiveBg,
2390    effectiveBgStops: effectiveBg ? null : resolveGradientStops(el, window),
2391    fontSize: parseFloat(style.fontSize) || 16,
2392    fontWeight: parseInt(style.fontWeight) || 400,
2393    hasDirectText,
2394    isEmojiOnly: isEmojiOnlyText(directText),
2395    bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
2396    bgImage: style.backgroundImage || '',
2397    classList: el.getAttribute?.('class') || el.className || '',
2398  });
2399}
2400 
2401function checkElementIconTile(el, tag, window) {
2402  if (!HEADING_TAGS.has(tag)) return [];
2403  const sibling = el.previousElementSibling;
2404  if (!sibling) return [];
2405 
2406  const sibStyle = window.getComputedStyle(sibling);
2407  // jsdom doesn't lay out — read explicit pixel dimensions from CSS instead.
2408  const sibWidth = parseFloat(sibStyle.width) || 0;
2409  const sibHeight = parseFloat(sibStyle.height) || 0;
2410 
2411  const iconChild = sibling.querySelector('svg, i[data-lucide], i[class*="fa-"], i[class*="icon"]');
2412  let iconWidth = 0;
2413  if (iconChild) {
2414    const iconStyle = window.getComputedStyle(iconChild);
2415    iconWidth = parseFloat(iconStyle.width) || parseFloat(iconChild.getAttribute('width')) || 0;
2416  }
2417  // Or: tile contains an emoji/symbol character directly as its only content
2418  const sibDirectText = [...sibling.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
2419  const hasInlineEmojiIcon = sibling.children.length === 0 && isEmojiOnlyText(sibDirectText);
2420 
2421  return checkIconTile({
2422    headingTag: tag,
2423    headingText: el.textContent || '',
2424    headingTop: 0, // jsdom: no layout, skip vertical-stacking gate
2425    siblingTag: sibling.tagName.toLowerCase(),
2426    siblingWidth: sibWidth,
2427    siblingHeight: sibHeight,
2428    siblingBottom: 0,
2429    siblingBgColor: parseRgb(sibStyle.backgroundColor),
2430    siblingBgImage: sibStyle.backgroundImage || '',
2431    siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
2432    siblingBorderRadius: resolveBorderRadiusPx(sibling, sibStyle, sibWidth, window),
2433    hasIconChild: !!iconChild || hasInlineEmojiIcon,
2434    iconChildWidth: iconWidth,
2435  });
2436}
2437 
2438function checkElementItalicSerif(el, style, tag) {
2439  if (tag !== 'h1' && tag !== 'h2') return [];
2440  return checkItalicSerif({
2441    tag,
2442    fontStyle: style.fontStyle || '',
2443    fontFamily: style.fontFamily || '',
2444    fontSize: parseFloat(style.fontSize) || 0,
2445    headingText: el.textContent || '',
2446  });
2447}
2448 
2449function checkElementHeroEyebrow(el, style, tag, window, customPropMap) {
2450  if (tag !== 'h1') return [];
2451  const sibling = el.previousElementSibling;
2452  if (!sibling) return [];
2453  const sibStyle = window.getComputedStyle(sibling);
2454  // Resolve Tailwind v4 CSS-variable wrappers (font-weight:var(--font-weight-bold)
2455  // etc.) before parsing. jsdom returns these verbatim from getComputedStyle;
2456  // without resolution every style-based gate fails silently on Tailwind v4 builds.
2457  const fontSizeRaw = customPropMap ? resolveVarRefs(sibStyle.fontSize, customPropMap) : sibStyle.fontSize;
2458  const fontWeightRaw = customPropMap ? resolveVarRefs(sibStyle.fontWeight, customPropMap) : sibStyle.fontWeight;
2459  const letterSpacingRaw = customPropMap ? resolveVarRefs(sibStyle.letterSpacing, customPropMap) : sibStyle.letterSpacing;
2460  const colorRaw = customPropMap ? resolveVarRefs(sibStyle.color, customPropMap) : sibStyle.color;
2461  const headingFontSizeRaw = customPropMap ? resolveVarRefs(style.fontSize, customPropMap) : style.fontSize;
2462  const siblingFontSize = parseFloat(fontSizeRaw) || 0;
2463  // resolveLengthPx returns null for 'normal' / 'auto'; coerce to 0 so the
2464  // gate falls through cleanly. jsdom returns letter-spacing verbatim
2465  // (e.g. '0.15em'), unlike real browsers, so this conversion is required.
2466  return checkHeroEyebrow({
2467    headingTag: tag,
2468    headingText: el.textContent || '',
2469    headingFontSize: parseFloat(headingFontSizeRaw) || 0,
2470    siblingTag: sibling.tagName.toLowerCase(),
2471    siblingText: sibling.textContent || '',
2472    siblingTextTransform: sibStyle.textTransform || '',
2473    siblingFontSize,
2474    siblingLetterSpacing: resolveLengthPx(letterSpacingRaw, siblingFontSize) || 0,
2475    siblingFontWeight: fontWeightRaw || '',
2476    siblingColor: colorRaw || '',
2477  });
2478}
2479 
2480function checkRepeatedSectionKickersFromDoc(doc, win) {
2481  const candidates = collectRepeatedSectionKickerCandidates(
2482    doc,
2483    (el) => win.getComputedStyle(el),
2484    (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
2485  );
2486  return checkRepeatedSectionKickers({ candidates });
2487}
2488 
2489function checkElementMotion(tag, style) {
2490  return checkMotion({
2491    tag,
2492    transitionProperty: style.transitionProperty || '',
2493    animationName: style.animationName || '',
2494    timingFunctions: [style.animationTimingFunction, style.transitionTimingFunction].filter(Boolean).join(' '),
2495    classList: '',
2496  });
2497}
2498 
2499function checkElementGlow(tag, style, effectiveBg) {
2500  if (!style.boxShadow || style.boxShadow === 'none') return [];
2501  return checkGlow({ tag, boxShadow: style.boxShadow, effectiveBg });
2502}
2503 
2504// ─── Section 6: Page-Level Checks ───────────────────────────────────────────
2505 
2506// Browser page-level checks — use document/getComputedStyle globals
2507 
2508function checkTypography() {
2509  const findings = [];
2510 
2511  // Walk actual text-bearing elements and tally font usage by *computed style*.
2512  // This is much more accurate than scanning CSS rules — it ignores rules that
2513  // exist in the stylesheet but apply to nothing (e.g. demo classes showing
2514  // anti-patterns), and counts what the user actually sees.
2515  const fontUsage = new Map(); // primary font name → count of elements
2516  let totalTextElements = 0;
2517  for (const el of document.querySelectorAll('p, h1, h2, h3, h4, h5, h6, li, td, th, dd, blockquote, figcaption, a, button, label, span')) {
2518    // Skip impeccable's own elements
2519    if (el.closest && el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
2520    // Only count elements that actually have visible direct text
2521    const hasText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 0);
2522    if (!hasText) continue;
2523    const style = getComputedStyle(el);
2524    const ff = style.fontFamily;
2525    if (!ff) continue;
2526    const stack = ff.split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase());
2527    const primary = stack.find(f => f && !GENERIC_FONTS.has(f));
2528    if (!primary) continue;
2529    fontUsage.set(primary, (fontUsage.get(primary) || 0) + 1);
2530    totalTextElements++;
2531  }
2532 
2533  if (totalTextElements >= 20) {
2534    // A font is "primary" if it's used by at least 15% of text elements
2535    const PRIMARY_THRESHOLD = 0.15;
2536    for (const [font, count] of fontUsage) {
2537      const share = count / totalTextElements;
2538      if (share < PRIMARY_THRESHOLD) continue;
2539      if (!OVERUSED_FONTS.has(font)) continue;
2540      if (isBrandFontOnOwnDomain(font)) continue;
2541      findings.push({ type: 'overused-font', detail: `Primary font: ${font} (${Math.round(share * 100)}% of text)` });
2542    }
2543 
2544    // Single-font check: only one distinct primary font across all text
2545    if (fontUsage.size === 1) {
2546      const only = [...fontUsage.keys()][0];
2547      findings.push({ type: 'single-font', detail: `only font used is ${only}` });
2548    }
2549  }
2550 
2551  const sizes = new Set();
2552  for (const el of document.querySelectorAll('h1,h2,h3,h4,h5,h6,p,span,a,li,td,th,label,button,div')) {
2553    const fs = parseFloat(getComputedStyle(el).fontSize);
2554    if (fs > 0 && fs < 200) sizes.add(Math.round(fs * 10) / 10);
2555  }
2556  if (sizes.size >= 3) {
2557    const sorted = [...sizes].sort((a, b) => a - b);
2558    const ratio = sorted[sorted.length - 1] / sorted[0];
2559    if (ratio < 2.0) {
2560      findings.push({ type: 'flat-type-hierarchy', detail: `Sizes: ${sorted.map(s => s + 'px').join(', ')} (ratio ${ratio.toFixed(1)}:1)` });
2561    }
2562  }
2563 
2564  return findings;
2565}
2566 
2567function isCardLikeDOM(el) {
2568  const tag = el.tagName.toLowerCase();
2569  if (SAFE_TAGS.has(tag) || ['input','select','textarea','img','video','canvas','picture'].includes(tag)) return false;
2570  const style = getComputedStyle(el);
2571  const cls = el.getAttribute('class') || '';
2572  const hasShadow = (style.boxShadow && style.boxShadow !== 'none') || /\bshadow(?:-sm|-md|-lg|-xl|-2xl)?\b/.test(cls);
2573  const hasBorder = /\bborder\b/.test(cls);
2574  const hasRadius = parseFloat(style.borderRadius) > 0 || /\brounded(?:-sm|-md|-lg|-xl|-2xl|-full)?\b/.test(cls);
2575  const hasBg = (style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)') || /\bbg-(?:white|gray-\d+|slate-\d+)\b/.test(cls);
2576  return isCardLikeFromProps(hasShadow, hasBorder, hasRadius, hasBg);
2577}
2578 
2579function checkLayout() {
2580  const findings = [];
2581  const flaggedEls = new Set();
2582 
2583  for (const el of document.querySelectorAll('*')) {
2584    if (!isCardLikeDOM(el) || flaggedEls.has(el)) continue;
2585    const cls = el.getAttribute('class') || '';
2586    const style = getComputedStyle(el);
2587    if (style.position === 'absolute' || style.position === 'fixed') continue;
2588    if (/\b(?:dropdown|popover|tooltip|menu|modal|dialog)\b/i.test(cls)) continue;
2589    if ((el.textContent?.trim().length || 0) < 10) continue;
2590    const rect = el.getBoundingClientRect();
2591    if (rect.width < 50 || rect.height < 30) continue;
2592 
2593    let parent = el.parentElement;
2594    while (parent) {
2595      if (isCardLikeDOM(parent)) { flaggedEls.add(el); break; }
2596      parent = parent.parentElement;
2597    }
2598  }
2599 
2600  for (const el of flaggedEls) {
2601    let isAncestor = false;
2602    for (const other of flaggedEls) {
2603      if (other !== el && el.contains(other)) { isAncestor = true; break; }
2604    }
2605    if (!isAncestor) findings.push({ type: 'nested-cards', detail: 'Card inside card', el });
2606  }
2607 
2608  return findings;
2609}
2610 
2611// Node page-level checks — take document/window as parameters
2612 
2613function checkPageTypography(doc, win) {
2614  const findings = [];
2615 
2616  const fonts = new Set();
2617  const overusedFound = new Set();
2618 
2619  for (const sheet of doc.styleSheets) {
2620    let rules;
2621    try { rules = sheet.cssRules || sheet.rules; } catch { continue; }
2622    if (!rules) continue;
2623    for (const rule of rules) {
2624      if (rule.type !== 1) continue;
2625      const ff = rule.style?.fontFamily;
2626      if (!ff) continue;
2627      const stack = ff.split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase());
2628      const primary = stack.find(f => f && !GENERIC_FONTS.has(f));
2629      if (primary) {
2630        fonts.add(primary);
2631        if (OVERUSED_FONTS.has(primary)) overusedFound.add(primary);
2632      }
2633    }
2634  }
2635 
2636  // Check Google Fonts links in HTML
2637  const html = doc.documentElement?.outerHTML || '';
2638  const gfRe = /fonts\.googleapis\.com\/css2?\?family=([^&"'\s]+)/gi;
2639  let m;
2640  while ((m = gfRe.exec(html)) !== null) {
2641    const families = m[1].split('|').map(f => f.split(':')[0].replace(/\+/g, ' ').toLowerCase());
2642    for (const f of families) {
2643      fonts.add(f);
2644      if (OVERUSED_FONTS.has(f)) overusedFound.add(f);
2645    }
2646  }
2647 
2648  // Also parse raw HTML/style content for font-family (jsdom may not expose all via CSSOM)
2649  const ffRe = /font-family\s*:\s*([^;}]+)/gi;
2650  let fm;
2651  while ((fm = ffRe.exec(html)) !== null) {
2652    for (const f of fm[1].split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase())) {
2653      if (f && !GENERIC_FONTS.has(f)) {
2654        fonts.add(f);
2655        if (OVERUSED_FONTS.has(f)) overusedFound.add(f);
2656      }
2657    }
2658  }
2659 
2660  for (const font of overusedFound) {
2661    findings.push({ id: 'overused-font', snippet: `Primary font: ${font}` });
2662  }
2663 
2664  // Single font
2665  if (fonts.size === 1) {
2666    const els = doc.querySelectorAll('*');
2667    if (els.length >= 20) {
2668      findings.push({ id: 'single-font', snippet: `only font used is ${[...fonts][0]}` });
2669    }
2670  }
2671 
2672  // Flat type hierarchy
2673  const sizes = new Set();
2674  const textEls = doc.querySelectorAll('h1, h2, h3, h4, h5, h6, p, span, a, li, td, th, label, button, div');
2675  for (const el of textEls) {
2676    const fontSize = parseFloat(win.getComputedStyle(el).fontSize);
2677    // Filter out sub-8px values (jsdom doesn't resolve relative units properly)
2678    if (fontSize >= 8 && fontSize < 200) sizes.add(Math.round(fontSize * 10) / 10);
2679  }
2680  if (sizes.size >= 3) {
2681    const sorted = [...sizes].sort((a, b) => a - b);
2682    const ratio = sorted[sorted.length - 1] / sorted[0];
2683    if (ratio < 2.0) {
2684      findings.push({ id: 'flat-type-hierarchy', snippet: `Sizes: ${sorted.map(s => s + 'px').join(', ')} (ratio ${ratio.toFixed(1)}:1)` });
2685    }
2686  }
2687 
2688  return findings;
2689}
2690 
2691function isCardLike(el, win) {
2692  const tag = el.tagName.toLowerCase();
2693  if (SAFE_TAGS.has(tag) || ['input', 'select', 'textarea', 'img', 'video', 'canvas', 'picture'].includes(tag)) return false;
2694 
2695  const style = win.getComputedStyle(el);
2696  const rawStyle = el.getAttribute?.('style') || '';
2697  const cls = el.getAttribute?.('class') || '';
2698 
2699  const hasShadow = (style.boxShadow && style.boxShadow !== 'none') ||
2700    /\bshadow(?:-sm|-md|-lg|-xl|-2xl)?\b/.test(cls) || /box-shadow/i.test(rawStyle);
2701  const hasBorder = /\bborder\b/.test(cls);
2702  const widthPx = parseFloat(style.width) || 0;
2703  const hasRadius = resolveBorderRadiusPx(el, style, widthPx, win) > 0 ||
2704    /\brounded(?:-sm|-md|-lg|-xl|-2xl|-full)?\b/.test(cls) || /border-radius/i.test(rawStyle);
2705  const hasBg = /\bbg-(?:white|gray-\d+|slate-\d+)\b/.test(cls) ||
2706    /background(?:-color)?\s*:\s*(?!transparent)/i.test(rawStyle);
2707 
2708  return isCardLikeFromProps(hasShadow, hasBorder, hasRadius, hasBg);
2709}
2710 
2711function checkPageLayout(doc, win) {
2712  const findings = [];
2713 
2714  // Nested cards
2715  const allEls = doc.querySelectorAll('*');
2716  const flaggedEls = new Set();
2717  for (const el of allEls) {
2718    if (!isCardLike(el, win)) continue;
2719    if (flaggedEls.has(el)) continue;
2720 
2721    const tag = el.tagName.toLowerCase();
2722    const cls = el.getAttribute?.('class') || '';
2723    const rawStyle = el.getAttribute?.('style') || '';
2724 
2725    if (['pre', 'code'].includes(tag)) continue;
2726    if (/\b(?:absolute|fixed)\b/.test(cls) || /position\s*:\s*(?:absolute|fixed)/i.test(rawStyle)) continue;
2727    if ((el.textContent?.trim().length || 0) < 10) continue;
2728    if (/\b(?:dropdown|popover|tooltip|menu|modal|dialog)\b/i.test(cls)) continue;
2729 
2730    // Walk up to find card-like ancestor
2731    let parent = el.parentElement;
2732    while (parent) {
2733      if (isCardLike(parent, win)) {
2734        flaggedEls.add(el);
2735        break;
2736      }
2737      parent = parent.parentElement;
2738    }
2739  }
2740 
2741  // Only report innermost nested cards
2742  for (const el of flaggedEls) {
2743    let isAncestorOfFlagged = false;
2744    for (const other of flaggedEls) {
2745      if (other !== el && el.contains(other)) {
2746        isAncestorOfFlagged = true;
2747        break;
2748      }
2749    }
2750    if (!isAncestorOfFlagged) {
2751      findings.push({ id: 'nested-cards', snippet: `Card inside card (${el.tagName.toLowerCase()})` });
2752    }
2753  }
2754 
2755  return findings;
2756}
2757 
2758// ─── Cream / beige palette (the default "tasteful" AI surface) ────────────────
2759// A warm, lightly-tinted off-white page background — light, with R≥G≥B and a
2760// small warm tint (not white, not a strong color). The current reflex surface.
2761function isCreamColor(rgb) {
2762  if (!rgb) return false;
2763  const { r, g, b } = rgb;
2764  if (Math.min(r, g, b) < 209) return false;   // must be light
2765  if (!(r >= g && g >= b)) return false;        // warm ordering
2766  const warmth = r - b;
2767  return warmth >= 6 && warmth <= 48;           // tinted, not white, not strong
2768}
2769 
2770// Tailwind background utilities that render as a warm off-white surface. The
2771// static engine doesn't fetch Tailwind's CSS, so a `bg-amber-50` on <body>
2772// resolves to nothing in computed style — catch it from the class list
2773// instead. Candidate tokens map to their actual Tailwind hex and are still
2774// filtered through isCreamColor, so neutral grays (stone) and over-saturated
2775// shades drop out on their own.
2776const TAILWIND_BG_HEX = {
2777  'bg-amber-50': '#fffbeb', 'bg-amber-100': '#fef3c7',
2778  'bg-orange-50': '#fff7ed', 'bg-orange-100': '#ffedd5',
2779  'bg-yellow-50': '#fefce8',
2780  'bg-stone-50': '#fafaf9', 'bg-stone-100': '#f5f5f4', 'bg-stone-200': '#e7e5e4',
2781};
2782 
2783function creamFromClassList(cls) {
2784  if (!cls) return null;
2785  // Arbitrary value: bg-[#f5f0e6] / bg-[rgb(245_240_230)] (underscores = spaces).
2786  const arb = cls.match(/\bbg-\[([^\]]+)\]/);
2787  if (arb && isCreamColor(parseAnyColor(arb[1].replace(/_/g, ' ')))) return `bg-[${arb[1]}]`;
2788  // Named warm-light utilities.
2789  for (const [tok, hex] of Object.entries(TAILWIND_BG_HEX)) {
2790    if (new RegExp(`(^|\\s)${tok}($|\\s)`).test(cls) && isCreamColor(parseAnyColor(hex))) return tok;
2791  }
2792  return null;
2793}
2794 
2795function checkCreamPalette(doc, win) {
2796  const findings = [];
2797  const body = doc.body || (doc.querySelector ? doc.querySelector('body') : null);
2798  if (!body) return findings;
2799  const html = doc.documentElement;
2800  const getCS = (el) => (win ? win.getComputedStyle(el) : getComputedStyle(el));
2801 
2802  // 1. Computed background — covers inline / <style> / linked CSS, and Tailwind
2803  //    once it's actually rendered (browser path).
2804  let bg = readOwnBackgroundColor(body, getCS(body));
2805  if (!bg || bg.a === 0) {
2806    if (html) bg = readOwnBackgroundColor(html, getCS(html));
2807  }
2808  if (isCreamColor(bg)) {
2809    findings.push({ id: 'cream-palette', snippet: `cream/beige page background rgb(${bg.r}, ${bg.g}, ${bg.b})` });
2810    return findings;
2811  }
2812 
2813  // 2. Tailwind class fallback — for the static path, where utility classes
2814  //    never resolve to computed CSS.
2815  for (const el of [body, html]) {
2816    const tok = creamFromClassList(el && el.getAttribute ? el.getAttribute('class') : '');
2817    if (tok) {
2818      findings.push({ id: 'cream-palette', snippet: `cream/beige page background (Tailwind ${tok})` });
2819      break;
2820    }
2821  }
2822  return findings;
2823}
2824 
2825// ─── Oversized hero headline ────────────────────────────────────────────────
2826// Fires when a *long* headline is set at display size and actually dominates
2827// the viewport. A punchy one- or two-word headline at the same size is a
2828// legitimate stylistic choice, and a large-but-contained two-line hero should
2829// pass too — length and viewport share together are the tell.
2830const OVERSIZED_H1_FONT_PX = 72;
2831const OVERSIZED_H1_MIN_CHARS = 40;
2832const OVERSIZED_H1_MIN_VIEWPORT_HEIGHT_RATIO = 0.28;
2833const OVERSIZED_H1_MIN_VIEWPORT_AREA_RATIO = 0.25;
2834function checkOversizedH1({ tag, fontSize, headingText, rect = null, viewportWidth = 0, viewportHeight = 0 }) {
2835  if (tag !== 'h1') return [];
2836  const textLen = headingText.length;
2837  if (fontSize >= OVERSIZED_H1_FONT_PX && textLen >= OVERSIZED_H1_MIN_CHARS) {
2838    let viewportDetail = '';
2839    if (rect && viewportWidth > 0 && viewportHeight > 0) {
2840      const heightRatio = rect.height / viewportHeight;
2841      const areaRatio = (rect.width * rect.height) / (viewportWidth * viewportHeight);
2842      const dominatesViewport = heightRatio >= OVERSIZED_H1_MIN_VIEWPORT_HEIGHT_RATIO
2843        || areaRatio >= OVERSIZED_H1_MIN_VIEWPORT_AREA_RATIO;
2844      if (!dominatesViewport) return [];
2845      viewportDetail = `, ${Math.round(heightRatio * 100)}vh`;
2846    }
2847    return [{ id: 'oversized-h1', snippet: `${Math.round(fontSize)}px h1, ${textLen} chars${viewportDetail} "${headingText.slice(0, 60)}"` }];
2848  }
2849  return [];
2850}
2851 
2852function checkElementOversizedH1(el, style, tag, window) {
2853  if (tag !== 'h1') return [];
2854  const fontSize = resolveFontSizePx(el, window);
2855  const headingText = (el.textContent || '').trim().replace(/\s+/g, ' ');
2856  return checkOversizedH1({ tag, fontSize, headingText });
2857}
2858 
2859function checkElementOversizedH1DOM(el) {
2860  const tag = el.tagName.toLowerCase();
2861  if (tag !== 'h1') return [];
2862  const style = getComputedStyle(el);
2863  const fontSize = parseFloat(style.fontSize) || 0;
2864  const headingText = (el.textContent || '').trim().replace(/\s+/g, ' ');
2865  const rect = el.getBoundingClientRect();
2866  const viewportWidth = (typeof window !== 'undefined' ? window.innerWidth : 0) || 0;
2867  const viewportHeight = (typeof window !== 'undefined' ? window.innerHeight : 0) || 0;
2868  return checkOversizedH1({ tag, fontSize, headingText, rect, viewportWidth, viewportHeight });
2869}
2870 
2871// ─── GPT tell: hairline border + wide diffuse shadow (gated --gpt) ────────────
2872const 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;
2873 
2874function shadowLayerAlpha(layer) {
2875  CSS_COLOR_TOKEN_RE.lastIndex = 0;
2876  const match = CSS_COLOR_TOKEN_RE.exec(layer);
2877  if (!match) return 1;
2878  if (match[0].toLowerCase() === 'transparent') return 0;
2879  const parsed = parseAnyColor(match[0]);
2880  return parsed ? (parsed.a ?? 1) : 1;
2881}
2882 
2883function shadowMaxBlurPx(boxShadow, { minAlpha = 0 } = {}) {
2884  if (!boxShadow || boxShadow === 'none') return 0;
2885  let maxBlur = 0;
2886  // Split into layers on commas not inside parentheses (rgba(...) etc.).
2887  for (const layer of boxShadow.split(/,(?![^()]*\))/)) {
2888    if (shadowLayerAlpha(layer) < minAlpha) continue;
2889    // Strip colors and keywords (rgba()/hsl()/hex/named/inset/px), leaving the
2890    // ordered length tokens: offsetX offsetY blur [spread]. Static jsdom keeps
2891    // unitless zeros ("0 0 24px"); browsers normalize to px ("0px 0px 24px") —
2892    // both reduce to the same numbers here.
2893    const cleaned = layer.replace(CSS_COLOR_TOKEN_RE, ' ').replace(/\b[a-z]+\b/gi, ' ');
2894    const nums = [...cleaned.matchAll(/-?\d*\.?\d+/g)].map(m => parseFloat(m[0]));
2895    if (nums.length >= 3) maxBlur = Math.max(maxBlur, nums[2]);
2896  }
2897  return maxBlur;
2898}
2899 
2900function cssColorAlpha(value) {
2901  if (cssColorIsTransparent(value)) return 0;
2902  const parsed = parseAnyColor(value);
2903  return parsed ? (parsed.a ?? 1) : 1;
2904}
2905 
2906function checkGptThinBorderWideShadow({ borderWidths, borderColors, boxShadow }) {
2907  const visibleThinBorders = borderWidths
2908    .map((width, index) => ({ width, alpha: cssColorAlpha(borderColors?.[index] || '') }))
2909    .filter(({ width, alpha }) => width > 0 && width <= 1.5 && alpha >= 0.28);
2910  const maxBorder = Math.max(0, ...visibleThinBorders.map(({ width }) => width));
2911  const blur = shadowMaxBlurPx(boxShadow, { minAlpha: 0.12 });
2912  if (visibleThinBorders.length >= 2 && blur >= 16) {
2913    return [{ id: 'gpt-thin-border-wide-shadow', snippet: `${maxBorder}px border + ${Math.round(blur)}px shadow blur` }];
2914  }
2915  return [];
2916}
2917 
2918function borderWidthsFromStyle(style) {
2919  return [
2920    parseFloat(style.borderTopWidth) || 0,
2921    parseFloat(style.borderRightWidth) || 0,
2922    parseFloat(style.borderBottomWidth) || 0,
2923    parseFloat(style.borderLeftWidth) || 0,
2924  ];
2925}
2926 
2927function borderColorsFromStyle(style) {
2928  return [
2929    style.borderTopColor || '',
2930    style.borderRightColor || '',
2931    style.borderBottomColor || '',
2932    style.borderLeftColor || '',
2933  ];
2934}
2935 
2936function checkElementGptBorderShadow(el, style) {
2937  return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), borderColors: borderColorsFromStyle(style), boxShadow: style.boxShadow || '' });
2938}
2939 
2940function checkElementGptBorderShadowDOM(el) {
2941  const style = getComputedStyle(el);
2942  return checkGptThinBorderWideShadow({ borderWidths: borderWidthsFromStyle(style), borderColors: borderColorsFromStyle(style), boxShadow: style.boxShadow || '' });
2943}
2944 
2945// ─── Clipped overflow container ───────────────────────────────────────────────
2946// A clipping container (overflow hidden/clip, not a scroll region) wrapping an
2947// absolutely/fixed-positioned descendant clips popovers/menus that must escape.
2948function classSelector(el) {
2949  const cls = (el.getAttribute ? el.getAttribute('class') : el.className) || '';
2950  const tokens = String(cls).trim().split(/\s+/).filter(Boolean);
2951  const tag = el.tagName ? el.tagName.toLowerCase() : 'el';
2952  return tokens.length ? `${tag}.${tokens.join('.')}` : tag;
2953}
2954 
2955function positionedChildIsDecorative(child) {
2956  if (!child || typeof child.getAttribute !== 'function') return false;
2957  if (child.closest?.('[aria-hidden="true"]')) return true;
2958  const role = (child.getAttribute('role') || '').toLowerCase();
2959  if (role === 'none' || role === 'presentation') return true;
2960  const tag = child.tagName ? child.tagName.toLowerCase() : '';
2961  if (['img', 'svg', 'canvas', 'video'].includes(tag)) return true;
2962  const ident = `${child.getAttribute('class') || ''} ${child.getAttribute('id') || ''}`;
2963  if (
2964    /\b(art|bg|background|badge|blob|crop|decor|dot|glow|grain|image|mask|ornament|overlay|photo|scrim|shadow|shine|texture)\b/i.test(ident) &&
2965    !positionedChildHasSubstantiveContent(child)
2966  ) {
2967    return true;
2968  }
2969  return false;
2970}
2971 
2972const POSITIONED_CHILD_INTERACTIVE_SELECTOR = [
2973  'a[href]',
2974  'button',
2975  'input',
2976  'select',
2977  'summary',
2978  'textarea',
2979  '[tabindex]:not([tabindex="-1"])',
2980  '[role="button"]',
2981  '[role="dialog"]',
2982  '[role="link"]',
2983  '[role="listbox"]',
2984  '[role="menu"]',
2985  '[role="menuitem"]',
2986  '[role="option"]',
2987  '[role="tooltip"]',
2988].join(',');
2989 
2990function positionedChildHasSubstantiveContent(child) {
2991  const text = (child.textContent || '').replace(/\s+/g, ' ').trim();
2992  if (text.length > 0) return true;
2993  if (typeof child.matches === 'function') {
2994    try {
2995      if (child.matches(POSITIONED_CHILD_INTERACTIVE_SELECTOR)) return true;
2996    } catch {}
2997  }
2998  if (typeof child.querySelector === 'function') {
2999    try {
3000      if (child.querySelector(POSITIONED_CHILD_INTERACTIVE_SELECTOR)) return true;
3001    } catch {}
3002  }
3003  return false;
3004}
3005 
3006function clippingContainerIsIntentionalViewport(el) {
3007  if (!el || typeof el.getAttribute !== 'function') return false;
3008  const roleDescription = (el.getAttribute('aria-roledescription') || '').toLowerCase();
3009  if (/\b(carousel|slider)\b/.test(roleDescription)) return true;
3010  const ident = `${el.getAttribute('class') || ''} ${el.getAttribute('id') || ''}`.toLowerCase();
3011  return /\b(carousel|comparison|compare|fisheye|marquee|preview|scroller|slider|slideshow|split|viewport)\b/.test(ident) ||
3012    /\b(demo-area|demo-stage|demo-viewport)\b/.test(ident);
3013}
3014 
3015function elementRect(el) {
3016  if (!el || typeof el.getBoundingClientRect !== 'function') return null;
3017  try {
3018    const rect = el.getBoundingClientRect();
3019    if (!rect) return null;
3020    const values = [rect.top, rect.right, rect.bottom, rect.left, rect.width, rect.height];
3021    if (!values.every(Number.isFinite)) return null;
3022    if (rect.width <= 0 && rect.height <= 0) return null;
3023    return rect;
3024  } catch {
3025    return null;
3026  }
3027}
3028 
3029function positionedStyleImpliesEscape(style) {
3030  const values = [
3031    style.top,
3032    style.right,
3033    style.bottom,
3034    style.left,
3035    style.inset,
3036    style.insetBlock,
3037    style.insetInline,
3038    style.insetBlockStart,
3039    style.insetBlockEnd,
3040    style.insetInlineStart,
3041    style.insetInlineEnd,
3042  ].filter(Boolean).map(value => String(value).trim().toLowerCase());
3043  for (const value of values) {
3044    if (/(^|[\s(])-+(?:\d|\.)/.test(value)) return true;
3045    if (/(^|[\s(])100(?:\.0+)?%/.test(value)) return true;
3046  }
3047  return false;
3048}
3049 
3050function positionedChildEscapesClip(el, child, clipX, clipY) {
3051  const parentRect = elementRect(el);
3052  const childRect = elementRect(child);
3053  if (!parentRect || !childRect) return null;
3054  const threshold = 2;
3055  return Boolean(
3056    (clipX && (childRect.left < parentRect.left - threshold || childRect.right > parentRect.right + threshold)) ||
3057    (clipY && (childRect.top < parentRect.top - threshold || childRect.bottom > parentRect.bottom + threshold))
3058  );
3059}
3060 
3061function checkClippedOverflow(el, style, getStyle) {
3062  const clips = (v) => v === 'hidden' || v === 'clip';
3063  const scrolls = (v) => v === 'auto' || v === 'scroll';
3064  const ox = style.overflowX || '', oy = style.overflowY || '', ov = style.overflow || '';
3065  const clipX = clips(ox) || clips(ov);
3066  const clipY = clips(oy) || clips(ov);
3067  const anyClip = clipX || clipY;
3068  const anyScroll = scrolls(ox) || scrolls(oy) || scrolls(ov);
3069  if (!anyClip || anyScroll) return [];
3070  if (clippingContainerIsIntentionalViewport(el)) return [];
3071  if (!el.querySelectorAll) return [];
3072  for (const child of el.querySelectorAll('*')) {
3073    const childStyle = getStyle(child);
3074    const pos = childStyle.position || '';
3075    if (pos === 'absolute' || pos === 'fixed') {
3076      if (positionedChildIsDecorative(child)) continue;
3077      const escapes = positionedChildEscapesClip(el, child, clipX, clipY);
3078      if (escapes === false) continue;
3079      if (escapes === null && !positionedStyleImpliesEscape(childStyle)) continue;
3080      return [{ id: 'clipped-overflow-container', snippet: `${classSelector(el)} clips a positioned child` }];
3081    }
3082  }
3083  return [];
3084}
3085 
3086function checkElementClippedOverflow(el, style, tag, window) {
3087  return checkClippedOverflow(el, style, (n) => window.getComputedStyle(n));
3088}
3089 
3090function checkElementClippedOverflowDOM(el) {
3091  const style = getComputedStyle(el);
3092  return checkClippedOverflow(el, style, (n) => getComputedStyle(n));
3093}
3094 
3095// ─── Text overflow (browser-only: needs scrollWidth/clientWidth) ──────────────
3096const TEXT_OVERFLOW_SKIP_TAGS = new Set(['pre', 'code', 'textarea', 'svg', 'canvas', 'select', 'option', 'marquee']);
3097 
3098function metricLengthPx(value, fontSizePx = 16) {
3099  if (typeof value === 'number' && Number.isFinite(value)) return value;
3100  if (typeof value !== 'string') return null;
3101  return resolveLengthPx(value, fontSizePx);
3102}
3103 
3104function firstMetricLengthPx(fontSizePx, ...values) {
3105  for (const value of values) {
3106    const parsed = metricLengthPx(value, fontSizePx);
3107    if (parsed !== null) return parsed;
3108  }
3109  return null;
3110}
3111 
3112function expandBoxShorthand(parts) {
3113  if (parts.length === 1) return [parts[0], parts[0], parts[0], parts[0]];
3114  if (parts.length === 2) return [parts[0], parts[1], parts[0], parts[1]];
3115  if (parts.length === 3) return [parts[0], parts[1], parts[2], parts[1]];
3116  return [parts[0], parts[1], parts[2], parts[3]];
3117}
3118 
3119function clippedByInset(clipPath) {
3120  const match = String(clipPath || '').trim().toLowerCase().match(/^inset\s*\(([^)]*)\)$/);
3121  if (!match) return false;
3122  const beforeRound = match[1].split(/\s+round\s+/)[0].trim();
3123  if (!beforeRound) return false;
3124  const values = expandBoxShorthand(beforeRound.split(/\s+/).slice(0, 4));
3125  const percents = values.map(value => String(value).trim().match(/^(-?\d+(?:\.\d+)?)%$/));
3126  if (percents.some(match => !match)) return false;
3127  const [top, right, bottom, left] = percents.map(match => parseFloat(match[1]));
3128  return top + bottom >= 100 || left + right >= 100;
3129}
3130 
3131function clippedByRect(clip) {
3132  const match = String(clip || '').trim().toLowerCase().match(/^rect\s*\(([^)]*)\)$/);
3133  if (!match) return false;
3134  const values = match[1].split(/[,\s]+/).map(value => value.trim()).filter(Boolean);
3135  if (values.length !== 4) return false;
3136  const [top, right, bottom, left] = values.map(value => metricLengthPx(value, 16));
3137  if ([top, right, bottom, left].some(value => value === null)) return false;
3138  return bottom <= top || right <= left;
3139}
3140 
3141function isScreenReaderOnlyTextStyle(style, metrics = {}) {
3142  if (!style) return false;
3143  const overflowValues = [style.overflow, style.overflowX, style.overflowY]
3144    .map(value => String(value || '').toLowerCase());
3145  const clipsOverflow = overflowValues.some(value => value === 'hidden' || value === 'clip');
3146 
3147  const fontSize = metricLengthPx(style.fontSize, 16) || 16;
3148  const width = firstMetricLengthPx(fontSize, metrics.width, metrics.clientWidth, style.width, style.inlineSize);
3149  const height = firstMetricLengthPx(fontSize, metrics.height, metrics.clientHeight, style.height, style.blockSize);
3150  const isTiny = width !== null && height !== null && width <= 2 && height <= 2;
3151  const isAbsolutelyHidden = String(style.position || '').toLowerCase() === 'absolute' && isTiny && clipsOverflow;
3152 
3153  const clipPath = String(style.clipPath || style.webkitClipPath || '').trim();
3154  const clip = String(style.clip || '').trim();
3155  return isAbsolutelyHidden || clippedByInset(clipPath) || clippedByRect(clip);
3156}
3157 
3158function isRenderedForBrowserRule(el) {
3159  for (let cur = el; cur && cur.nodeType === 1; cur = cur.parentElement) {
3160    if (cur.getAttribute?.('aria-hidden') === 'true') return false;
3161    const style = getComputedStyle(cur);
3162    const visibility = String(style.visibility || '').toLowerCase();
3163    if (style.display === 'none' || visibility === 'hidden' || visibility === 'collapse') return false;
3164    if ((parseFloat(style.opacity) || 0) <= 0.01) return false;
3165    if (String(style.contentVisibility || '').toLowerCase() === 'hidden') return false;
3166  }
3167  return true;
3168}
3169 
3170function checkElementTextOverflowDOM(el) {
3171  const tag = el.tagName.toLowerCase();
3172  if (TEXT_OVERFLOW_SKIP_TAGS.has(tag)) return [];
3173  if (!isRenderedForBrowserRule(el)) return [];
3174  // Only the element that actually owns overflowing text — not its ancestors,
3175  // which inherit a wider scrollWidth from the spilling descendant.
3176  const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 0);
3177  if (!hasDirectText) return [];
3178  const style = getComputedStyle(el);
3179  const rect = el.getBoundingClientRect ? el.getBoundingClientRect() : null;
3180  if (isScreenReaderOnlyTextStyle(style, {
3181    width: rect?.width,
3182    height: rect?.height,
3183    clientWidth: el.clientWidth,
3184    clientHeight: el.clientHeight,
3185  })) return [];
3186  const isScrollRegion = (s) => /(auto|scroll)/.test(s.overflowX || '') || /(auto|scroll)/.test(s.overflow || '');
3187  if (isScrollRegion(style)) return [];
3188  // A scrollable ancestor means this overflow is intentional and scrollable.
3189  for (let p = el.parentElement; p; p = p.parentElement) {
3190    if (isScrollRegion(getComputedStyle(p))) return [];
3191  }
3192  const delta = el.scrollWidth - el.clientWidth;
3193  if (el.clientWidth > 0 && delta >= 16) {
3194    return [{ id: 'text-overflow', snippet: `${classSelector(el)} overflows its box by ${Math.round(delta)}px` }];
3195  }
3196  return [];
3197}
3198 
3199// --- cli/engine/browser/injected/index.mjs ---
3200const IS_BROWSER = typeof window !== 'undefined';
3201 
3202// ─── Section 7: Browser UI (IS_BROWSER only) ────────────────────────────────
3203 
3204if (IS_BROWSER) {
3205  // Detect extension mode via the script tag's data attribute or the document element fallback.
3206  // currentScript is reliable for synchronously-executing scripts (which our IIFE is).
3207  const _myScript = document.currentScript;
3208  const EXTENSION_MODE = (_myScript && _myScript.dataset.impeccableExtension === 'true')
3209    || document.documentElement.dataset.impeccableExtension === 'true';
3210 
3211  // Kinpaku gold — pinned to the site's brand token (see
3212  // site/styles/kinpaku-tokens.css --ks-kinpaku). Keep this in sync with
3213  // the picker's C.brand in skill/scripts/live-browser.js and the kit's
3214  // picker section in site/styles/kinpaku-kit.css.
3215  //
3216  // One color across both light and dark host pages. The outline is a
3217  // 2px gesture pointing at an element + a labeled tag — it's a marker,
3218  // not body text, so it doesn't need WCAG AA against the page. The
3219  // label text inside the gold tag is dark (LABEL_INK) which has ~16:1
3220  // against the leaf gold, so reading the rule name is solid in both
3221  // modes. Hover deepens the gold (preserves chroma — never drops it,
3222  // dropping chroma washes the gold into a sand/olive tone).
3223  const BRAND_COLOR = 'oklch(84% 0.19 80.46)';
3224  const BRAND_COLOR_HOVER = 'oklch(74% 0.18 80)';
3225  const LABEL_INK = 'oklch(4% 0.004 95)';
3226  const LABEL_BG = BRAND_COLOR;
3227  const OUTLINE_COLOR = BRAND_COLOR;
3228 
3229  // Inject hover styles via CSS (more reliable than JS event listeners)
3230  const styleEl = document.createElement('style');
3231  styleEl.textContent = `
3232    @keyframes impeccable-reveal {
3233      from { opacity: 0; }
3234      to { opacity: 1; }
3235    }
3236    .impeccable-overlay:not(.impeccable-banner) {
3237      pointer-events: none;
3238      outline: 2px solid ${OUTLINE_COLOR};
3239      border-radius: 4px;
3240      transition: outline-color 0.15s ease;
3241      animation: impeccable-reveal 0.4s cubic-bezier(0.16, 1, 0.3, 1) both;
3242      animation-play-state: paused;
3243      border-top-left-radius: 0;
3244    }
3245    .impeccable-overlay.impeccable-visible {
3246      animation-play-state: running;
3247    }
3248    .impeccable-overlay.impeccable-hover {
3249      outline-color: ${BRAND_COLOR_HOVER};
3250      z-index: 100001 !important;
3251    }
3252    .impeccable-overlay.impeccable-hover .impeccable-label {
3253      background: ${BRAND_COLOR_HOVER};
3254    }
3255    .impeccable-overlay.impeccable-spotlight {
3256      z-index: 100002 !important;
3257    }
3258    .impeccable-overlay.impeccable-spotlight-dimmed {
3259      opacity: 0.15 !important;
3260      animation: none !important;
3261      filter: blur(3px);
3262    }
3263    .impeccable-spotlight-backdrop {
3264      position: fixed;
3265      top: 0; left: 0; right: 0; bottom: 0;
3266      backdrop-filter: blur(3px) brightness(0.6);
3267      -webkit-backdrop-filter: blur(3px) brightness(0.6);
3268      pointer-events: none;
3269      z-index: 99998;
3270      opacity: 0;
3271      outline: none !important;
3272      animation: none !important;
3273    }
3274    .impeccable-spotlight-backdrop.impeccable-visible {
3275      opacity: 1;
3276    }
3277    .impeccable-hidden .impeccable-overlay${EXTENSION_MODE ? '' : ':not(.impeccable-banner)'} {
3278      display: none !important;
3279    }
3280  `;
3281  (document.head || document.documentElement).appendChild(styleEl);
3282 
3283  // Spotlight backdrop element (created lazily on first use)
3284  let spotlightBackdrop = null;
3285  let spotlightTarget = null;
3286 
3287  function getSpotlightBackdrop() {
3288    if (!spotlightBackdrop) {
3289      spotlightBackdrop = document.createElement('div');
3290      spotlightBackdrop.className = 'impeccable-spotlight-backdrop';
3291      document.body.appendChild(spotlightBackdrop);
3292    }
3293    return spotlightBackdrop;
3294  }
3295 
3296  function updateSpotlightClipPath() {
3297    if (!spotlightBackdrop || !spotlightTarget) return;
3298    const r = spotlightTarget.getBoundingClientRect();
3299    // Match the overlay's outer edge: element rect + 4px (2px overlay offset + 2px outline width)
3300    const inset = 4;
3301    const radius = 6; // outline border-radius (4) + outline width (2)
3302    const x1 = r.left - inset;
3303    const y1 = r.top - inset;
3304    const x2 = r.right + inset;
3305    const y2 = r.bottom + inset;
3306    const vw = window.innerWidth;
3307    const vh = window.innerHeight;
3308    // Outer rect + rounded inner rect (evenodd creates a hole)
3309    const path = `M0 0H${vw}V${vh}H0Z M${x1 + radius} ${y1}H${x2 - radius}A${radius} ${radius} 0 0 1 ${x2} ${y1 + radius}V${y2 - radius}A${radius} ${radius} 0 0 1 ${x2 - radius} ${y2}H${x1 + radius}A${radius} ${radius} 0 0 1 ${x1} ${y2 - radius}V${y1 + radius}A${radius} ${radius} 0 0 1 ${x1 + radius} ${y1}Z`;
3310    spotlightBackdrop.style.clipPath = `path(evenodd, "${path}")`;
3311  }
3312 
3313  function showSpotlight(target) {
3314    if (!target || !target.getBoundingClientRect) return;
3315    // Respect the spotlightBlur setting: if disabled, don't show the backdrop
3316    if (window.__IMPECCABLE_CONFIG__?.spotlightBlur === false) {
3317      spotlightTarget = target;
3318      return;
3319    }
3320    spotlightTarget = target;
3321    const bd = getSpotlightBackdrop();
3322    updateSpotlightClipPath();
3323    bd.classList.add('impeccable-visible');
3324  }
3325 
3326  function hideSpotlight() {
3327    spotlightTarget = null;
3328    if (spotlightBackdrop) spotlightBackdrop.classList.remove('impeccable-visible');
3329  }
3330 
3331  function isInViewport(el) {
3332    const r = el.getBoundingClientRect();
3333    return r.top >= 0 && r.left >= 0 && r.bottom <= window.innerHeight && r.right <= window.innerWidth;
3334  }
3335 
3336  // Reposition spotlight on scroll/resize
3337  window.addEventListener('scroll', () => {
3338    if (spotlightTarget) updateSpotlightClipPath();
3339  }, { passive: true });
3340  window.addEventListener('resize', () => {
3341    if (spotlightTarget) updateSpotlightClipPath();
3342  });
3343 
3344  const overlays = [];
3345  const TYPE_LABELS = {};
3346  const RULE_CATEGORY = {};
3347  for (const ap of ANTIPATTERNS) {
3348    TYPE_LABELS[ap.id] = ap.name.toLowerCase();
3349    RULE_CATEGORY[ap.id] = ap.category || 'quality';
3350  }
3351 
3352  function isInFixedContext(el) {
3353    let p = el;
3354    while (p && p !== document.body) {
3355      if (getComputedStyle(p).position === 'fixed') return true;
3356      p = p.parentElement;
3357    }
3358    return false;
3359  }
3360 
3361  function positionOverlay(overlay) {
3362    const el = overlay._targetEl;
3363    if (!el) return;
3364    const rect = el.getBoundingClientRect();
3365    if (overlay._isFixed) {
3366      // Viewport-relative coords for fixed targets
3367      overlay.style.top = `${rect.top - 2}px`;
3368      overlay.style.left = `${rect.left - 2}px`;
3369    } else {
3370      // Document-relative coords for normal targets
3371      overlay.style.top = `${rect.top + scrollY - 2}px`;
3372      overlay.style.left = `${rect.left + scrollX - 2}px`;
3373    }
3374    overlay.style.width = `${rect.width + 4}px`;
3375    overlay.style.height = `${rect.height + 4}px`;
3376  }
3377 
3378  function repositionOverlays() {
3379    for (const o of overlays) {
3380      if (!o._targetEl || o.classList.contains('impeccable-banner')) continue;
3381      // Skip overlays whose target is currently hidden (display: none on the overlay)
3382      if (o.style.display === 'none') continue;
3383      positionOverlay(o);
3384    }
3385  }
3386 
3387  let resizeRAF;
3388  const onResize = () => {
3389    cancelAnimationFrame(resizeRAF);
3390    resizeRAF = requestAnimationFrame(repositionOverlays);
3391  };
3392  window.addEventListener('resize', onResize);
3393  // Reposition on scroll too -- catches sticky/parallax shifts
3394  window.addEventListener('scroll', onResize, { passive: true });
3395  // Reposition when body resizes (lazy-loaded images, dynamic content, fonts loading)
3396  if (typeof ResizeObserver !== 'undefined') {
3397    const bodyResizeObserver = new ResizeObserver(onResize);
3398    bodyResizeObserver.observe(document.body);
3399  }
3400 
3401  // Track target element visibility via IntersectionObserver.
3402  // Uses a huge rootMargin so all *rendered* elements count as intersecting,
3403  // while display:none / closed <details> / hidden modals etc. do not.
3404  // This is event-driven -- no polling needed.
3405  let overlayIndex = 0;
3406  const visibilityObserver = new IntersectionObserver((entries) => {
3407    for (const entry of entries) {
3408      const overlay = entry.target._impeccableOverlay;
3409      if (!overlay) continue;
3410      if (entry.isIntersecting) {
3411        overlay.style.display = '';
3412        positionOverlay(overlay);
3413        if (!overlay._revealed) {
3414          overlay._revealed = true;
3415          if (firstScanDone) {
3416            // Subsequent reveals (re-scans, scroll-into-view): instant, no animation
3417            overlay.style.animation = 'none';
3418          } else {
3419            // Initial scan: staggered cascade reveal
3420            overlay.style.animationDelay = `${Math.min((overlay._staggerIndex || 0) * 60, 600)}ms`;
3421          }
3422          requestAnimationFrame(() => {
3423            overlay.classList.add('impeccable-visible');
3424            if (overlay._checkLabel) overlay._checkLabel();
3425          });
3426        }
3427      } else {
3428        overlay.style.display = 'none';
3429      }
3430    }
3431  }, { rootMargin: '99999px' });
3432 
3433  function detachOverlay(overlay) {
3434    if (!overlay) return;
3435    if (typeof overlay._cleanup === 'function') {
3436      try { overlay._cleanup(); } catch { /* best effort overlay teardown */ }
3437    }
3438    if (overlay._targetEl && overlay._targetEl._impeccableOverlay === overlay) {
3439      visibilityObserver.unobserve(overlay._targetEl);
3440      delete overlay._targetEl._impeccableOverlay;
3441    }
3442    const idx = overlays.indexOf(overlay);
3443    if (idx >= 0) overlays.splice(idx, 1);
3444    overlay.remove();
3445  }
3446 
3447  // Reposition overlays after CSS transitions end (e.g. reveal animations).
3448  // Listens at document level so it catches transitions on ancestor elements
3449  // (the transform may be on a parent, not the flagged element itself).
3450  document.addEventListener('transitionend', (e) => {
3451    if (e.propertyName !== 'transform') return;
3452    for (const o of overlays) {
3453      if (!o._targetEl || o.classList.contains('impeccable-banner') || o.style.display === 'none') continue;
3454      if (e.target === o._targetEl || e.target.contains(o._targetEl)) {
3455        positionOverlay(o);
3456      }
3457    }
3458  });
3459 
3460  const highlight = function(el, findings) {
3461    if (el._impeccableOverlay) detachOverlay(el._impeccableOverlay);
3462    const hasSlop = findings.some(f => RULE_CATEGORY[f.type || f.id] === 'slop');
3463 
3464    const fixed = isInFixedContext(el);
3465    const rect = el.getBoundingClientRect();
3466    const outline = document.createElement('div');
3467    outline.className = 'impeccable-overlay';
3468    outline._targetEl = el;
3469    outline._isFixed = fixed;
3470    Object.assign(outline.style, {
3471      position: fixed ? 'fixed' : 'absolute',
3472      top: fixed ? `${rect.top - 2}px` : `${rect.top + scrollY - 2}px`,
3473      left: fixed ? `${rect.left - 2}px` : `${rect.left + scrollX - 2}px`,
3474      width: `${rect.width + 4}px`, height: `${rect.height + 4}px`,
3475      zIndex: '99999', boxSizing: 'border-box',
3476    });
3477 
3478    // Build per-finding label entries: ✦ prefix for slop
3479    const entries = findings.map(f => {
3480      const name = TYPE_LABELS[f.type || f.id] || f.type || f.id;
3481      const prefix = RULE_CATEGORY[f.type || f.id] === 'slop' ? '\u2726 ' : '';
3482      return { name: prefix + name, detail: f.detail || f.snippet };
3483    });
3484    const allText = entries.map(e => e.name).join(', ');
3485 
3486    const label = document.createElement('div');
3487    label.className = 'impeccable-label';
3488    Object.assign(label.style, {
3489      position: 'absolute', bottom: '100%', left: '-2px',
3490      display: 'flex', alignItems: 'center',
3491      whiteSpace: 'nowrap',
3492      fontSize: '11px', fontWeight: '600', letterSpacing: '0.02em',
3493      color: LABEL_INK, lineHeight: '14px',
3494      background: LABEL_BG,
3495      fontFamily: 'system-ui, sans-serif',
3496      borderRadius: '4px 4px 0 0',
3497    });
3498 
3499    const textSpan = document.createElement('span');
3500    textSpan.style.padding = '3px 8px';
3501    textSpan.textContent = allText;
3502    label.appendChild(textSpan);
3503 
3504    // State for cycling mode
3505    let cycleMode = false;
3506    let cycleIndex = 0;
3507    let isHovered = false;
3508    let prevBtn, nextBtn;
3509 
3510    function updateCycleText() {
3511      const e = entries[cycleIndex];
3512      textSpan.textContent = isHovered ? e.detail : e.name;
3513    }
3514 
3515    function enableCycleMode() {
3516      if (cycleMode || entries.length < 2) return;
3517      cycleMode = true;
3518 
3519      const btnStyle = {
3520        background: 'none', border: 'none', color: 'rgba(255,255,255,0.7)',
3521        fontSize: '11px', cursor: 'pointer', padding: '3px 4px',
3522        fontFamily: 'system-ui, sans-serif', lineHeight: '14px',
3523        pointerEvents: 'auto',
3524      };
3525 
3526      const navGroup = document.createElement('span');
3527      Object.assign(navGroup.style, {
3528        display: 'inline-flex', alignItems: 'center', flexShrink: '0',
3529      });
3530 
3531      prevBtn = document.createElement('button');
3532      prevBtn.textContent = '\u2039';
3533      Object.assign(prevBtn.style, btnStyle);
3534      prevBtn.style.paddingLeft = '6px';
3535      prevBtn.addEventListener('click', (e) => {
3536        e.stopPropagation();
3537        cycleIndex = (cycleIndex - 1 + entries.length) % entries.length;
3538        updateCycleText();
3539      });
3540 
3541      nextBtn = document.createElement('button');
3542      nextBtn.textContent = '\u203A';
3543      Object.assign(nextBtn.style, btnStyle);
3544      nextBtn.style.paddingRight = '2px';
3545      nextBtn.addEventListener('click', (e) => {
3546        e.stopPropagation();
3547        cycleIndex = (cycleIndex + 1) % entries.length;
3548        updateCycleText();
3549      });
3550 
3551      navGroup.appendChild(prevBtn);
3552      navGroup.appendChild(nextBtn);
3553      label.insertBefore(navGroup, textSpan);
3554      textSpan.style.padding = '3px 8px 3px 4px';
3555      updateCycleText();
3556    }
3557 
3558    outline.appendChild(label);
3559 
3560    // Start hidden; the IntersectionObserver will show it once the target is rendered
3561    outline.style.display = 'none';
3562    outline._staggerIndex = overlayIndex++;
3563    el._impeccableOverlay = outline;
3564    visibilityObserver.observe(el);
3565 
3566    // After first paint, check label width vs outline
3567    outline._checkLabel = () => {
3568      if (entries.length > 1 && label.offsetWidth > outline.offsetWidth) {
3569        enableCycleMode();
3570      }
3571    };
3572 
3573    // Hover: show detail text, darken
3574    const onMouseEnter = () => {
3575      isHovered = true;
3576      outline.classList.add('impeccable-hover');
3577      outline.style.outlineColor = BRAND_COLOR_HOVER;
3578      label.style.background = BRAND_COLOR_HOVER;
3579      if (cycleMode) {
3580        updateCycleText();
3581      } else {
3582        textSpan.textContent = entries.map(e => e.detail).join(' | ');
3583      }
3584    };
3585    const onMouseLeave = () => {
3586      isHovered = false;
3587      outline.classList.remove('impeccable-hover');
3588      outline.style.outlineColor = '';
3589      label.style.background = LABEL_BG;
3590      if (cycleMode) {
3591        updateCycleText();
3592      } else {
3593        textSpan.textContent = allText;
3594      }
3595    };
3596    el.addEventListener('mouseenter', onMouseEnter);
3597    el.addEventListener('mouseleave', onMouseLeave);
3598    outline._cleanup = () => {
3599      el.removeEventListener('mouseenter', onMouseEnter);
3600      el.removeEventListener('mouseleave', onMouseLeave);
3601    };
3602 
3603    document.body.appendChild(outline);
3604    overlays.push(outline);
3605  };
3606 
3607  const showPageBanner = function(findings) {
3608    if (!findings.length) return;
3609    const banner = document.createElement('div');
3610    banner.className = 'impeccable-overlay impeccable-banner';
3611    Object.assign(banner.style, {
3612      position: 'fixed', top: '0', left: '0', right: '0', zIndex: '100000',
3613      background: LABEL_BG, color: LABEL_INK,
3614      fontFamily: 'system-ui, sans-serif', fontSize: '13px',
3615      display: 'flex', alignItems: 'center', pointerEvents: 'auto',
3616      height: '36px', overflow: 'hidden', maxWidth: '100vw',
3617      transform: 'translateY(-100%)',
3618      transition: 'transform 0.4s cubic-bezier(0.16, 1, 0.3, 1)',
3619    });
3620    requestAnimationFrame(() => requestAnimationFrame(() => {
3621      banner.style.transform = 'translateY(0)';
3622    }));
3623 
3624    // Scrollable findings area
3625    const scrollArea = document.createElement('div');
3626    Object.assign(scrollArea.style, {
3627      flex: '1', minWidth: '0', overflowX: 'auto', overflowY: 'hidden',
3628      display: 'flex', gap: '8px', alignItems: 'center',
3629      padding: '0 12px', scrollSnapType: 'x mandatory',
3630      scrollbarWidth: 'none',
3631    });
3632    for (const f of findings) {
3633      const prefix = RULE_CATEGORY[f.type] === 'slop' ? '\u2726 ' : '';
3634      const tag = document.createElement('span');
3635      tag.textContent = `${prefix}${TYPE_LABELS[f.type] || f.type}: ${f.detail}`;
3636      Object.assign(tag.style, {
3637        background: 'rgba(255,255,255,0.15)', padding: '2px 8px',
3638        borderRadius: '3px', fontSize: '12px', fontFamily: 'ui-monospace, monospace',
3639        whiteSpace: 'nowrap', flexShrink: '0', scrollSnapAlign: 'start',
3640      });
3641      scrollArea.appendChild(tag);
3642    }
3643    banner.appendChild(scrollArea);
3644 
3645    // Controls area (only in standalone mode, not extension)
3646    if (!EXTENSION_MODE) {
3647      const controls = document.createElement('div');
3648      Object.assign(controls.style, {
3649        display: 'flex', alignItems: 'center', gap: '2px',
3650        padding: '0 8px', flexShrink: '0',
3651      });
3652 
3653      // Toggle visibility button
3654      const toggle = document.createElement('button');
3655      toggle.textContent = '\u25C9'; // circle with dot (visible state)
3656      toggle.title = 'Toggle overlay visibility';
3657      Object.assign(toggle.style, {
3658        background: 'none', border: 'none',
3659        color: 'white', fontSize: '16px', cursor: 'pointer', padding: '0 4px',
3660        opacity: '0.85', transition: 'opacity 0.15s',
3661      });
3662      let overlaysVisible = true;
3663      toggle.addEventListener('click', () => {
3664        overlaysVisible = !overlaysVisible;
3665        document.body.classList.toggle('impeccable-hidden', !overlaysVisible);
3666        toggle.textContent = overlaysVisible ? '\u25C9' : '\u25CB'; // filled vs empty circle
3667        toggle.style.opacity = overlaysVisible ? '0.85' : '0.5';
3668      });
3669      controls.appendChild(toggle);
3670 
3671      // Close button
3672      const close = document.createElement('button');
3673      close.textContent = '\u00d7';
3674      close.title = 'Dismiss banner';
3675      Object.assign(close.style, {
3676        background: 'none', border: 'none',
3677        color: 'white', fontSize: '18px', cursor: 'pointer', padding: '0 4px',
3678      });
3679      close.addEventListener('click', () => banner.remove());
3680      controls.appendChild(close);
3681 
3682      banner.appendChild(controls);
3683    }
3684    document.body.appendChild(banner);
3685    overlays.push(banner);
3686  };
3687 
3688  // Heuristic for skipping CSS-in-JS hashed class names like "css-1a2b3c" or "_2x4hG_".
3689  // These change between builds and produce brittle, ugly selectors.
3690  function isLikelyHashedClass(c) {
3691    if (!c) return true;
3692    if (/^(css|sc|emotion|jsx|module)-[\w-]{4,}$/i.test(c)) return true;
3693    if (/^_[\w-]{5,}$/.test(c)) return true;
3694    if (/^[a-z0-9]{6,}$/i.test(c) && /\d/.test(c)) return true;
3695    return false;
3696  }
3697 
3698  function buildSelectorSegment(el) {
3699    const tag = el.tagName.toLowerCase();
3700    let sel = tag;
3701 
3702    if (el.classList && el.classList.length > 0) {
3703      const classes = [...el.classList]
3704        .filter(c => !c.startsWith('impeccable-') && !isLikelyHashedClass(c))
3705        .slice(0, 2);
3706      if (classes.length > 0) {
3707        sel += '.' + classes.map(c => CSS.escape(c)).join('.');
3708      }
3709    }
3710 
3711    // Disambiguate among siblings only if the parent has multiple matches
3712    const parent = el.parentElement;
3713    if (parent) {
3714      try {
3715        const matching = parent.querySelectorAll(':scope > ' + sel);
3716        if (matching.length > 1) {
3717          const sameType = [...parent.children].filter(c => c.tagName === el.tagName);
3718          const idx = sameType.indexOf(el) + 1;
3719          sel += `:nth-of-type(${idx})`;
3720        }
3721      } catch {
3722        const idx = [...parent.children].indexOf(el) + 1;
3723        sel = `${tag}:nth-child(${idx})`;
3724      }
3725    }
3726    return sel;
3727  }
3728 
3729  function generateSelector(el) {
3730    if (el === document.body) return 'body';
3731    if (el === document.documentElement) return 'html';
3732    if (el.id) return '#' + CSS.escape(el.id);
3733 
3734    const parts = [];
3735    let current = el;
3736    let depth = 0;
3737    const MAX_DEPTH = 10;
3738 
3739    while (current && current !== document.body && current !== document.documentElement && depth < MAX_DEPTH) {
3740      parts.unshift(buildSelectorSegment(current));
3741 
3742      // Anchor on an ancestor's ID and stop walking up
3743      if (current.id) {
3744        parts[0] = '#' + CSS.escape(current.id);
3745        break;
3746      }
3747 
3748      // Stop as soon as the partial selector uniquely identifies the target
3749      const trySelector = parts.join(' > ');
3750      try {
3751        const matches = document.querySelectorAll(trySelector);
3752        if (matches.length === 1 && matches[0] === el) {
3753          return trySelector;
3754        }
3755      } catch { /* invalid selector — keep walking */ }
3756 
3757      current = current.parentElement;
3758      depth++;
3759    }
3760 
3761    return parts.join(' > ');
3762  }
3763 
3764  function getDirectText(el) {
3765    return [...el.childNodes]
3766      .filter(n => n.nodeType === 3)
3767      .map(n => n.textContent || '')
3768      .join('');
3769  }
3770 
3771  function getDirectTextRect(el) {
3772    const rects = [];
3773    for (const node of el.childNodes) {
3774      if (node.nodeType !== 3 || !(node.textContent || '').trim()) continue;
3775      const range = document.createRange();
3776      range.selectNodeContents(node);
3777      for (const rect of range.getClientRects()) {
3778        if (rect.width >= 1 && rect.height >= 1) rects.push(rect);
3779      }
3780      range.detach?.();
3781    }
3782    if (rects.length === 0) return null;
3783    const left = Math.min(...rects.map(r => r.left));
3784    const top = Math.min(...rects.map(r => r.top));
3785    const right = Math.max(...rects.map(r => r.right));
3786    const bottom = Math.max(...rects.map(r => r.bottom));
3787    return {
3788      left,
3789      top,
3790      right,
3791      bottom,
3792      width: right - left,
3793      height: bottom - top,
3794      x: left,
3795      y: top,
3796    };
3797  }
3798 
3799  function collectVisualContrastReasons(el, style) {
3800    const reasons = new Set();
3801    const bgClip = style.webkitBackgroundClip || style.backgroundClip || '';
3802    const ownBgImage = style.backgroundImage || '';
3803    if (bgClip === 'text' && ownBgImage && ownBgImage !== 'none') {
3804      reasons.add('background-clip text');
3805    }
3806    if (style.textShadow && style.textShadow !== 'none') reasons.add('text shadow');
3807 
3808    let current = el;
3809    while (current && current.nodeType === 1) {
3810      const tag = current.tagName?.toLowerCase();
3811      const currentStyle = getComputedStyle(current);
3812      const bgImage = currentStyle.backgroundImage || '';
3813      const isDocumentSurface = tag === 'body' || tag === 'html';
3814 
3815      if (!isDocumentSurface && bgImage && bgImage !== 'none') {
3816        if (/url\s*\(/i.test(bgImage)) reasons.add('image background');
3817        if (/gradient/i.test(bgImage)) reasons.add('gradient background');
3818      }
3819      if (parseFloat(currentStyle.opacity) < 0.99) reasons.add('opacity stack');
3820      if (currentStyle.mixBlendMode && currentStyle.mixBlendMode !== 'normal') reasons.add('blend mode');
3821      if (currentStyle.filter && currentStyle.filter !== 'none') reasons.add('filter');
3822      if (currentStyle.backdropFilter && currentStyle.backdropFilter !== 'none') reasons.add('backdrop filter');
3823 
3824      const solidBg = parseRgb(currentStyle.backgroundColor);
3825      if (solidBg && solidBg.a >= 0.95 && (!bgImage || bgImage === 'none')) break;
3826      current = current.parentElement;
3827    }
3828 
3829    const sampleRect = getDirectTextRect(el) || el.getBoundingClientRect();
3830    if (sampleRect && document.elementsFromPoint) {
3831      const points = [
3832        [sampleRect.left + sampleRect.width / 2, sampleRect.top + sampleRect.height / 2],
3833        [sampleRect.left + Math.min(sampleRect.width - 1, Math.max(1, sampleRect.width * 0.25)), sampleRect.top + sampleRect.height / 2],
3834        [sampleRect.left + Math.min(sampleRect.width - 1, Math.max(1, sampleRect.width * 0.75)), sampleRect.top + sampleRect.height / 2],
3835      ];
3836      for (const [x, y] of points) {
3837        if (x < 0 || y < 0 || x > window.innerWidth || y > window.innerHeight) continue;
3838        const stack = document.elementsFromPoint(x, y);
3839        const selfIndex = stack.findIndex(node => node === el || el.contains(node) || node.contains?.(el));
3840        if (selfIndex < 0) continue;
3841        for (const node of stack.slice(selfIndex + 1)) {
3842          const nodeTag = node.tagName?.toLowerCase();
3843          if (nodeTag === 'img' || nodeTag === 'picture' || nodeTag === 'video' || nodeTag === 'canvas' || nodeTag === 'svg') {
3844            reasons.add(`${nodeTag} underlay`);
3845            break;
3846          }
3847        }
3848      }
3849    }
3850 
3851    return [...reasons];
3852  }
3853 
3854  function collectVisualContrastCandidates(options = {}) {
3855    const maxCandidates = Number.isFinite(options.maxCandidates) ? options.maxCandidates : 12;
3856    const candidates = [];
3857    for (const el of document.querySelectorAll('*')) {
3858      if (candidates.length >= maxCandidates) break;
3859      if (el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
3860      if (el.closest('[id^="impeccable-live-"]')) continue;
3861      if (el === document.body || el === document.documentElement) continue;
3862      if (!isRenderedForBrowserRule(el)) continue;
3863 
3864      const tag = el.tagName.toLowerCase();
3865      const style = getComputedStyle(el);
3866      if (style.display === 'none' || style.visibility === 'hidden') continue;
3867      const directText = getDirectText(el);
3868      const hasDirectText = directText.trim().length > 0;
3869      if (!hasDirectText || isEmojiOnlyText(directText)) continue;
3870 
3871      const bgColor = readOwnBackgroundColor(el, style);
3872      const isStyledButton = (tag === 'a' || tag === 'button')
3873        && bgColor && bgColor.a > 0.5;
3874      if (SAFE_TAGS.has(tag) && !isStyledButton) continue;
3875 
3876      const rect = getDirectTextRect(el) || el.getBoundingClientRect();
3877      if (!rect || rect.width < 4 || rect.height < 4) continue;
3878 
3879      const reasons = collectVisualContrastReasons(el, style);
3880      if (reasons.length === 0) continue;
3881 
3882      const textColor = parseRgb(style.color);
3883      const fontSize = parseFloat(style.fontSize) || 16;
3884      const fontWeight = parseInt(style.fontWeight) || 400;
3885      const isLargeText = fontSize >= WCAG_LARGE_TEXT_PX || (fontSize >= WCAG_LARGE_BOLD_TEXT_PX && fontWeight >= 700);
3886      const threshold = isLargeText ? 3.0 : 4.5;
3887      const clip = {
3888        x: Math.max(0, Math.floor(rect.left + window.scrollX - 2)),
3889        y: Math.max(0, Math.floor(rect.top + window.scrollY - 2)),
3890        width: Math.max(1, Math.ceil(rect.width + 4)),
3891        height: Math.max(1, Math.ceil(rect.height + 4)),
3892      };
3893 
3894      candidates.push({
3895        selector: generateSelector(el),
3896        tagName: tag,
3897        text: directText.trim().replace(/\s+/g, ' ').slice(0, 80),
3898        threshold,
3899        reasons,
3900        clip,
3901        textColor,
3902        preferRenderedForeground: !textColor || textColor.a < 0.99 || reasons.some(reason =>
3903          reason === 'opacity stack' ||
3904          reason === 'blend mode' ||
3905          reason === 'filter' ||
3906          reason === 'backdrop filter' ||
3907          reason === 'background-clip text'
3908        ),
3909        backgroundClipText: reasons.includes('background-clip text'),
3910      });
3911    }
3912    return candidates;
3913  }
3914 
3915  const visualContrastImageCache = new Map();
3916  const visualContrastRasterCache = new WeakMap();
3917 
3918  function clampByte(value) {
3919    return Math.max(0, Math.min(255, Math.round(value)));
3920  }
3921 
3922  function blendRgba(fg, bg) {
3923    if (!fg) return bg || null;
3924    if (!bg || fg.a == null || fg.a >= 0.999) {
3925      return { r: clampByte(fg.r), g: clampByte(fg.g), b: clampByte(fg.b), a: fg.a == null ? 1 : fg.a };
3926    }
3927    const alpha = Math.max(0, Math.min(1, fg.a));
3928    return {
3929      r: clampByte(fg.r * alpha + bg.r * (1 - alpha)),
3930      g: clampByte(fg.g * alpha + bg.g * (1 - alpha)),
3931      b: clampByte(fg.b * alpha + bg.b * (1 - alpha)),
3932      a: 1,
3933    };
3934  }
3935 
3936  function pickWorstContrastColor(textColor, colors) {
3937    const usable = (colors || []).filter(Boolean);
3938    if (!usable.length) return null;
3939    let worst = usable[0];
3940    let worstRatio = contrastRatio(textColor, worst);
3941    for (const color of usable.slice(1)) {
3942      const ratio = contrastRatio(textColor, color);
3943      if (ratio < worstRatio) {
3944        worst = color;
3945        worstRatio = ratio;
3946      }
3947    }
3948    return worst;
3949  }
3950 
3951  function firstCssUrl(value) {
3952    const match = String(value || '').match(/url\((?:"([^"]+)"|'([^']+)'|([^)]*))\)/i);
3953    if (!match) return '';
3954    return (match[1] || match[2] || match[3] || '').trim();
3955  }
3956 
3957  function getLayerValue(value, index = 0) {
3958    return String(value || '').split(',')[index]?.trim() || '';
3959  }
3960 
3961  function parsePositionToken(token, container, painted) {
3962    if (!token || token === 'center') return (container - painted) / 2;
3963    if (token === 'left' || token === 'top') return 0;
3964    if (token === 'right' || token === 'bottom') return container - painted;
3965    if (/%$/.test(token)) {
3966      const pct = parseFloat(token) / 100;
3967      return (container - painted) * pct;
3968    }
3969    if (/px$/.test(token)) return parseFloat(token) || 0;
3970    return (container - painted) / 2;
3971  }
3972 
3973  function parsePositionPair(positionValue) {
3974    const tokens = String(positionValue || '50% 50%').trim().split(/\s+/).filter(Boolean);
3975    const first = tokens[0] || '50%';
3976    if (tokens.length < 2) {
3977      if (first === 'top' || first === 'bottom') return ['50%', first];
3978      return [first, '50%'];
3979    }
3980    return [first, tokens[1] || '50%'];
3981  }
3982 
3983  function resolvePaintedImageRect(containerRect, image, sizeValue, positionValue) {
3984    const intrinsicWidth = image.naturalWidth || image.videoWidth || image.width || 1;
3985    const intrinsicHeight = image.naturalHeight || image.videoHeight || image.height || 1;
3986    let paintedWidth = intrinsicWidth;
3987    let paintedHeight = intrinsicHeight;
3988    const size = String(sizeValue || 'auto').trim();
3989 
3990    if (size === 'cover' || size === 'contain') {
3991      const scale = size === 'cover'
3992        ? Math.max(containerRect.width / intrinsicWidth, containerRect.height / intrinsicHeight)
3993        : Math.min(containerRect.width / intrinsicWidth, containerRect.height / intrinsicHeight);
3994      paintedWidth = intrinsicWidth * scale;
3995      paintedHeight = intrinsicHeight * scale;
3996    } else if (size && size !== 'auto') {
3997      const parts = size.split(/\s+/);
3998      const widthToken = parts[0];
3999      const heightToken = parts[1] || 'auto';
4000      if (/%$/.test(widthToken)) paintedWidth = containerRect.width * (parseFloat(widthToken) / 100);
4001      else if (/px$/.test(widthToken)) paintedWidth = parseFloat(widthToken) || paintedWidth;
4002      if (heightToken === 'auto') paintedHeight = paintedWidth * (intrinsicHeight / intrinsicWidth);
4003      else if (/%$/.test(heightToken)) paintedHeight = containerRect.height * (parseFloat(heightToken) / 100);
4004      else if (/px$/.test(heightToken)) paintedHeight = parseFloat(heightToken) || paintedHeight;
4005    }
4006 
4007    const [xToken, yToken] = parsePositionPair(positionValue);
4008    const positionX = parsePositionToken(xToken, containerRect.width, paintedWidth);
4009    const positionY = parsePositionToken(yToken, containerRect.height, paintedHeight);
4010    return {
4011      left: containerRect.left + positionX,
4012      top: containerRect.top + positionY,
4013      width: paintedWidth,
4014      height: paintedHeight,
4015      intrinsicWidth,
4016      intrinsicHeight,
4017    };
4018  }
4019 
4020  function parseObjectPosition(positionValue) {
4021    return parsePositionPair(positionValue);
4022  }
4023 
4024  function resolveObjectImageRect(containerRect, image, style) {
4025    const intrinsicWidth = image.naturalWidth || image.videoWidth || image.width || 1;
4026    const intrinsicHeight = image.naturalHeight || image.videoHeight || image.height || 1;
4027    const fit = style.objectFit || 'fill';
4028    let paintedWidth = containerRect.width;
4029    let paintedHeight = containerRect.height;
4030    if (fit === 'contain' || fit === 'cover') {
4031      const scale = fit === 'cover'
4032        ? Math.max(containerRect.width / intrinsicWidth, containerRect.height / intrinsicHeight)
4033        : Math.min(containerRect.width / intrinsicWidth, containerRect.height / intrinsicHeight);
4034      paintedWidth = intrinsicWidth * scale;
4035      paintedHeight = intrinsicHeight * scale;
4036    } else if (fit === 'none') {
4037      paintedWidth = intrinsicWidth;
4038      paintedHeight = intrinsicHeight;
4039    } else if (fit === 'scale-down') {
4040      const containScale = Math.min(containerRect.width / intrinsicWidth, containerRect.height / intrinsicHeight, 1);
4041      paintedWidth = intrinsicWidth * containScale;
4042      paintedHeight = intrinsicHeight * containScale;
4043    }
4044    const [xToken, yToken] = parseObjectPosition(style.objectPosition);
4045    return {
4046      left: containerRect.left + parsePositionToken(xToken, containerRect.width, paintedWidth),
4047      top: containerRect.top + parsePositionToken(yToken, containerRect.height, paintedHeight),
4048      width: paintedWidth,
4049      height: paintedHeight,
4050      intrinsicWidth,
4051      intrinsicHeight,
4052    };
4053  }
4054 
4055  function pointToImageSource(point, paintedRect) {
4056    if (
4057      point.x < paintedRect.left ||
4058      point.y < paintedRect.top ||
4059      point.x > paintedRect.left + paintedRect.width ||
4060      point.y > paintedRect.top + paintedRect.height
4061    ) {
4062      return null;
4063    }
4064    return {
4065      x: Math.max(0, Math.min(paintedRect.intrinsicWidth - 1, ((point.x - paintedRect.left) / paintedRect.width) * paintedRect.intrinsicWidth)),
4066      y: Math.max(0, Math.min(paintedRect.intrinsicHeight - 1, ((point.y - paintedRect.top) / paintedRect.height) * paintedRect.intrinsicHeight)),
4067    };
4068  }
4069 
4070  async function loadVisualContrastImage(src) {
4071    if (!src) return null;
4072    if (visualContrastImageCache.has(src)) return visualContrastImageCache.get(src);
4073    const promise = new Promise(resolve => {
4074      const img = new Image();
4075      let settled = false;
4076      const finish = value => {
4077        if (settled) return;
4078        settled = true;
4079        clearTimeout(timer);
4080        resolve(value);
4081      };
4082      const timer = setTimeout(() => finish(null), 800);
4083      try {
4084        const absolute = new URL(src, location.href);
4085        if (absolute.origin !== location.origin && absolute.protocol !== 'data:' && absolute.protocol !== 'blob:') {
4086          img.crossOrigin = 'anonymous';
4087        }
4088      } catch {
4089        // Let the browser resolve unusual URLs itself.
4090      }
4091      img.onload = () => finish(img);
4092      img.onerror = () => finish(null);
4093      img.src = src;
4094    });
4095    visualContrastImageCache.set(src, promise);
4096    return promise;
4097  }
4098 
4099  function sampleDrawablePixel(drawable, sourcePoint) {
4100    if (visualContrastRasterCache.has(drawable)) {
4101      const cached = visualContrastRasterCache.get(drawable);
4102      if (!cached || !cached.ctx) return { status: 'unresolved', reason: cached?.reason || 'image sample failed' };
4103      try {
4104        const x = Math.max(0, Math.min(cached.width - 1, Math.floor(sourcePoint.x * cached.scaleX)));
4105        const y = Math.max(0, Math.min(cached.height - 1, Math.floor(sourcePoint.y * cached.scaleY)));
4106        const data = cached.ctx.getImageData(x, y, 1, 1).data;
4107        return {
4108          status: 'sampled',
4109          color: { r: data[0], g: data[1], b: data[2], a: data[3] / 255 },
4110        };
4111      } catch (err) {
4112        return {
4113          status: 'unresolved',
4114          reason: /taint|cross-origin|Security/i.test(err?.message || '') ? 'tainted image' : 'image sample failed',
4115        };
4116      }
4117    }
4118 
4119    const canvas = document.createElement('canvas');
4120    const intrinsicWidth = drawable.naturalWidth || drawable.videoWidth || drawable.width || 1;
4121    const intrinsicHeight = drawable.naturalHeight || drawable.videoHeight || drawable.height || 1;
4122    const maxRasterSide = 640;
4123    const scale = Math.min(1, maxRasterSide / Math.max(intrinsicWidth, intrinsicHeight));
4124    canvas.width = Math.max(1, Math.round(intrinsicWidth * scale));
4125    canvas.height = Math.max(1, Math.round(intrinsicHeight * scale));
4126    const ctx = canvas.getContext('2d', { willReadFrequently: true });
4127    if (!ctx) return { status: 'unresolved', reason: 'canvas unavailable' };
4128    try {
4129      ctx.drawImage(drawable, 0, 0, canvas.width, canvas.height);
4130      const cached = {
4131        ctx,
4132        width: canvas.width,
4133        height: canvas.height,
4134        scaleX: canvas.width / intrinsicWidth,
4135        scaleY: canvas.height / intrinsicHeight,
4136      };
4137      visualContrastRasterCache.set(drawable, cached);
4138      const x = Math.max(0, Math.min(cached.width - 1, Math.floor(sourcePoint.x * cached.scaleX)));
4139      const y = Math.max(0, Math.min(cached.height - 1, Math.floor(sourcePoint.y * cached.scaleY)));
4140      const data = ctx.getImageData(x, y, 1, 1).data;
4141      return {
4142        status: 'sampled',
4143        color: { r: data[0], g: data[1], b: data[2], a: data[3] / 255 },
4144      };
4145    } catch (err) {
4146      const reason = /taint|cross-origin|Security/i.test(err?.message || '') ? 'tainted image' : 'image sample failed';
4147      visualContrastRasterCache.set(drawable, { ctx: null, reason });
4148      return {
4149        status: 'unresolved',
4150        reason,
4151      };
4152    }
4153  }
4154 
4155  async function sampleCssBackground(el, style, point, textColor) {
4156    const rect = el.getBoundingClientRect();
4157    const bgImage = style.backgroundImage || '';
4158    if (bgImage && bgImage !== 'none') {
4159      if (/gradient/i.test(bgImage)) {
4160        const color = pickWorstContrastColor(textColor, parseGradientColors(bgImage));
4161        if (color) return { status: 'sampled', color, method: 'analytic-gradient' };
4162      }
4163      if (/url\s*\(/i.test(bgImage)) {
4164        const img = await loadVisualContrastImage(firstCssUrl(bgImage));
4165        if (!img) return { status: 'unresolved', reason: 'image unavailable' };
4166        const paintedRect = resolvePaintedImageRect(
4167          rect,
4168          img,
4169          getLayerValue(style.backgroundSize) || 'auto',
4170          getLayerValue(style.backgroundPosition) || '50% 50%',
4171        );
4172        const sourcePoint = pointToImageSource(point, paintedRect);
4173        if (!sourcePoint) return { status: 'unresolved', reason: 'point outside background image' };
4174        const sample = sampleDrawablePixel(img, sourcePoint);
4175        if (sample.status === 'sampled') return { ...sample, method: 'canvas-background-image' };
4176        return sample;
4177      }
4178    }
4179    const bg = parseRgb(style.backgroundColor);
4180    if (bg && bg.a > 0.05) return { status: 'sampled', color: bg, method: 'solid-background' };
4181    return { status: 'unresolved', reason: 'no readable background' };
4182  }
4183 
4184  async function sampleImageElement(img, point) {
4185    const rect = img.getBoundingClientRect();
4186    const style = getComputedStyle(img);
4187    const paintedRect = resolveObjectImageRect(rect, img, style);
4188    const sourcePoint = pointToImageSource(point, paintedRect);
4189    if (!sourcePoint) return { status: 'unresolved', reason: 'point outside image' };
4190    const sample = sampleDrawablePixel(img, sourcePoint);
4191    if (sample.status === 'sampled') return { ...sample, method: 'canvas-img-underlay' };
4192 
4193    if (img.currentSrc || img.src) {
4194      const loaded = await loadVisualContrastImage(img.currentSrc || img.src);
4195      if (loaded) {
4196        const loadedRect = { ...paintedRect, intrinsicWidth: loaded.naturalWidth || loaded.width || paintedRect.intrinsicWidth, intrinsicHeight: loaded.naturalHeight || loaded.height || paintedRect.intrinsicHeight };
4197        const loadedPoint = pointToImageSource(point, loadedRect);
4198        if (loadedPoint) {
4199          const loadedSample = sampleDrawablePixel(loaded, loadedPoint);
4200          if (loadedSample.status === 'sampled') return { ...loadedSample, method: 'canvas-img-underlay' };
4201        }
4202      }
4203    }
4204    return sample;
4205  }
4206 
4207  function textSamplePoints(rect) {
4208    const insetX = Math.min(12, Math.max(1, rect.width * 0.12));
4209    const insetY = Math.min(8, Math.max(1, rect.height * 0.22));
4210    const xs = rect.width < 28
4211      ? [rect.left + rect.width / 2]
4212      : [rect.left + insetX, rect.