impeccable 2.1.7 → 2.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.repo.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable
2
2
 
3
- The vocabulary you didn't know you needed. 1 skill, 18 commands, and curated anti-patterns for impeccable frontend design.
3
+ The vocabulary you didn't know you needed. 1 skill, 23 commands, and curated anti-patterns for impeccable frontend design.
4
4
 
5
5
  > **Quick start:** Visit [impeccable.style](https://impeccable.style) to download ready-to-use bundles.
6
6
 
@@ -12,7 +12,7 @@ Every LLM learned from the same generic templates. Without guidance, you get the
12
12
 
13
13
  Impeccable fights that bias with:
14
14
  - **An expanded skill** with 7 domain-specific reference files ([view source](source/skills/impeccable/))
15
- - **18 steering commands** to audit, review, polish, distill, animate, and more
15
+ - **23 commands** to audit, review, polish, distill, animate, and more
16
16
  - **Curated anti-patterns** that explicitly tell the AI what NOT to do
17
17
 
18
18
  ## What's Included
@@ -31,65 +31,50 @@ A comprehensive design skill with 7 domain-specific references ([view skill](sou
31
31
  | [responsive-design](source/skills/impeccable/reference/responsive-design.md) | Mobile-first, fluid design, container queries |
32
32
  | [ux-writing](source/skills/impeccable/reference/ux-writing.md) | Button labels, error messages, empty states |
33
33
 
34
- ### 18 Commands
34
+ ### 23 Commands
35
+
36
+ All commands are accessed through `/impeccable`:
35
37
 
36
38
  | Command | What it does |
37
39
  |---------|--------------|
38
- | `/impeccable teach` | One-time setup: gather design context, save to config |
39
40
  | `/impeccable craft` | Full shape-then-build flow with visual iteration |
41
+ | `/impeccable teach` | One-time setup: gather design context, write PRODUCT.md and DESIGN.md |
42
+ | `/impeccable document` | Generate DESIGN.md from existing project code |
40
43
  | `/impeccable extract` | Pull reusable components and tokens into the design system |
41
- | `/audit` | Run technical quality checks (a11y, performance, responsive) |
42
- | `/critique` | UX design review: hierarchy, clarity, emotional resonance |
43
- | `/polish` | Final pass, design system alignment, and shipping readiness |
44
- | `/distill` | Strip to essence |
45
- | `/clarify` | Improve unclear UX copy |
46
- | `/optimize` | Performance improvements |
47
- | `/harden` | Error handling, onboarding, i18n, edge cases |
48
- | `/animate` | Add purposeful motion |
49
- | `/colorize` | Introduce strategic color |
50
- | `/bolder` | Amplify boring designs |
51
- | `/quieter` | Tone down overly bold designs |
52
- | `/delight` | Add moments of joy |
53
- | `/adapt` | Adapt for different devices |
54
- | `/typeset` | Fix font choices, hierarchy, sizing |
55
- | `/layout` | Fix layout, spacing, visual rhythm |
56
- | `/overdrive` | Add technically extraordinary effects |
44
+ | `/impeccable shape` | Plan UX/UI before writing code |
45
+ | `/impeccable critique` | UX design review: hierarchy, clarity, emotional resonance |
46
+ | `/impeccable audit` | Run technical quality checks (a11y, performance, responsive) |
47
+ | `/impeccable polish` | Final pass, design system alignment, and shipping readiness |
48
+ | `/impeccable bolder` | Amplify boring designs |
49
+ | `/impeccable quieter` | Tone down overly bold designs |
50
+ | `/impeccable distill` | Strip to essence |
51
+ | `/impeccable harden` | Error handling, i18n, text overflow, edge cases |
52
+ | `/impeccable onboard` | First-run flows, empty states, activation paths |
53
+ | `/impeccable animate` | Add purposeful motion |
54
+ | `/impeccable colorize` | Introduce strategic color |
55
+ | `/impeccable typeset` | Fix font choices, hierarchy, sizing |
56
+ | `/impeccable layout` | Fix layout, spacing, visual rhythm |
57
+ | `/impeccable delight` | Add moments of joy |
58
+ | `/impeccable overdrive` | Add technically extraordinary effects |
59
+ | `/impeccable clarify` | Improve unclear UX copy |
60
+ | `/impeccable adapt` | Adapt for different devices |
61
+ | `/impeccable optimize` | Performance improvements |
62
+ | `/impeccable live` | Visual variant mode: iterate on elements in the browser |
63
+
64
+ Use `/impeccable pin <command>` to create standalone shortcuts (e.g., `pin audit` creates `/audit`).
57
65
 
58
66
  #### Usage Examples
59
67
 
60
- **`/audit`** - Run quality checks, get a report (no edits)
61
- ```
62
- /audit blog # Audit blog hub + post pages
63
- /audit dashboard # Check dashboard components
64
- /audit checkout flow # Focus on checkout UX
65
- ```
66
- *When to use:* Before making changes, to understand what needs fixing.
67
-
68
- **`/normalize`** - Align with design system
69
- ```
70
- /normalize blog # Apply design tokens, fix spacing
71
- /normalize buttons # Standardize button styles
72
- ```
73
- *When to use:* After audit, to fix inconsistencies.
74
-
75
- **`/critique`** - UX design review
76
68
  ```
77
- /critique landing page # Review landing page UX
78
- /critique onboarding # Check onboarding flow
69
+ /impeccable audit blog # Audit blog hub + post pages
70
+ /impeccable critique landing # UX design review
71
+ /impeccable polish settings # Final pass before shipping
72
+ /impeccable harden checkout # Add error handling + edge cases
79
73
  ```
80
- *When to use:* When you want design feedback, not technical fixes.
81
74
 
82
- **`/polish`** - Final pass before shipping
75
+ Or use `/impeccable` directly with a description:
83
76
  ```
84
- /polish feature modal # Clean up modal before release
85
- /polish settings page # Final review of settings UI
86
- ```
87
- *When to use:* Last step before deploying to production.
88
-
89
- **Combining commands:**
90
- ```
91
- /audit /normalize /polish blog # Full workflow: audit → fix → polish
92
- /critique /harden checkout # UX review + add error handling
77
+ /impeccable redo this hero section
93
78
  ```
94
79
 
95
80
  ### Anti-Patterns
@@ -158,7 +143,17 @@ cp -r dist/gemini/.gemini your-project/
158
143
 
159
144
  **Codex CLI:**
160
145
  ```bash
161
- cp -r dist/codex/.codex/* ~/.codex/
146
+ # Project-local
147
+ cp -r dist/agents/.agents your-project/
148
+
149
+ # Or user-wide
150
+ mkdir -p ~/.agents/skills
151
+ cp -r dist/agents/.agents/skills/* ~/.agents/skills/
152
+ ```
153
+
154
+ **GitHub Copilot:**
155
+ ```bash
156
+ cp -r dist/github/.github your-project/
162
157
  ```
163
158
 
164
159
  **Trae:**
@@ -203,7 +198,7 @@ Most commands accept an optional argument to focus on a specific area:
203
198
  /polish checkout-form
204
199
  ```
205
200
 
206
- **Note:** Codex CLI uses a different syntax: `/prompts:audit`, `/prompts:polish`, etc.
201
+ **Note:** Codex uses skills here, not `/prompts:` commands. Open `/skills` or type `$impeccable`. Repo-local installs live in `.agents/skills/`; user-wide installs live in `~/.agents/skills/`. GitHub Copilot uses `.github/skills/`. Restart the tool if a newly installed skill does not appear.
207
202
 
208
203
  ## CLI
209
204
 
package/bin/cli.js CHANGED
@@ -5,8 +5,6 @@
5
5
  *
6
6
  * Usage:
7
7
  * npx impeccable detect [file-or-dir-or-url...]
8
- * npx impeccable live [--port=PORT]
9
- * npx impeccable live stop
10
8
  * npx impeccable skills help|install|update
11
9
  * npx impeccable --help
12
10
  */
@@ -24,8 +22,6 @@ if (!command || command === '--help' || command === '-h') {
24
22
 
25
23
  Commands:
26
24
  detect [file-or-dir-or-url...] Scan for UI anti-patterns and design quality issues
27
- live [--port=PORT] Start browser detection overlay server
28
- live stop Stop a running live server
29
25
  skills help List all available skills and commands
30
26
  skills install Install impeccable skills into your project
31
27
  skills update Update skills to the latest version
@@ -49,10 +45,6 @@ if (command === 'detect') {
49
45
  process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
50
46
  const { detectCli } = await import('../src/detect-antipatterns.mjs');
51
47
  await detectCli();
52
- } else if (command === 'live') {
53
- process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
54
- const { liveCli } = await import('../src/detect-antipatterns.mjs');
55
- await liveCli();
56
48
  } else if (command === 'skills') {
57
49
  const { run } = await import('./commands/skills.mjs');
58
50
  await run(args.slice(1));
@@ -20,7 +20,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
20
20
  const API_BASE = 'https://impeccable.style';
21
21
 
22
22
  // Provider folder names in project roots
23
- const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.codex', '.agents', '.kiro', '.opencode', '.pi', '.trae', '.trae-cn'];
23
+ const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.kiro', '.opencode', '.pi', '.trae', '.trae-cn'];
24
24
 
25
25
  function ask(question) {
26
26
  const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -112,7 +112,7 @@ async function downloadAndExtractBundle() {
112
112
  */
113
113
  function normalizeForHash(content) {
114
114
  return content
115
- .replace(/\.(claude|cursor|agents|gemini|codex|kiro|opencode|pi|trae|trae-cn|rovodev)\/skills\//g, '.PROVIDER/skills/')
115
+ .replace(/\.(claude|cursor|agents|github|gemini|codex|kiro|opencode|pi|trae|trae-cn|rovodev)\/skills\//g, '.PROVIDER/skills/')
116
116
  .replace(/^version:\s*.+$/m, 'version: NORMALIZED');
117
117
  }
118
118
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "impeccable",
3
- "version": "2.1.7",
3
+ "version": "2.1.8",
4
4
  "author": "Paul Bakaus",
5
5
  "description": "Design skills, commands, and anti-pattern detection for AI coding agents",
6
6
  "keywords": [
@@ -49,23 +49,35 @@
49
49
  "dev": "bun run server/index.js",
50
50
  "preview": "bun run build && wrangler pages dev",
51
51
  "deploy": "bun run build && wrangler pages deploy build/",
52
- "test": "bun test tests/build.test.js tests/detect-antipatterns.test.js && node --test tests/detect-antipatterns-fixtures.test.mjs && node --test tests/detect-antipatterns-browser.test.mjs && node --test tests/cleanup-deprecated.test.mjs",
52
+ "test": "bun test tests/build.test.js tests/detect-antipatterns.test.js tests/windows-path-fix.test.js && node --test tests/detect-antipatterns-fixtures.test.mjs && node --test tests/detect-antipatterns-browser.test.mjs && node --test tests/cleanup-deprecated.test.mjs && node --test tests/live-wrap.test.mjs && node --test tests/live-accept.test.mjs && node --test tests/live-inject.test.mjs && node --test tests/live-server.test.mjs && node --test tests/framework-fixtures.test.mjs",
53
+ "test:live-e2e": "node --test --test-timeout=600000 tests/live-e2e.test.mjs",
53
54
  "prepack": "cp README.md README.repo.md && cp README.npm.md README.md",
54
55
  "postpack": "cp README.repo.md README.md && rm README.repo.md",
56
+ "release:skill": "node scripts/release.mjs skill",
57
+ "release:cli": "node scripts/release.mjs cli",
58
+ "release:ext": "node scripts/release.mjs extension",
55
59
  "screenshot": "bun run scripts/screenshot-antipatterns.js",
56
60
  "og-image": "bun run scripts/generate-og-image.js"
57
61
  },
58
62
  "dependencies": {
59
- "jsdom": "^29.0.0",
60
- "marked": "^16.1.0"
63
+ "jsdom": "29.0.0",
64
+ "marked": "^16.4.2"
61
65
  },
62
66
  "optionalDependencies": {
63
- "puppeteer": "^24.39.1"
67
+ "puppeteer": "^24.42.0"
64
68
  },
65
69
  "devDependencies": {
70
+ "@ai-sdk/anthropic": "^3.0.71",
71
+ "@ai-sdk/openai": "^3.0.53",
72
+ "@anthropic-ai/claude-agent-sdk": "^0.2.119",
73
+ "@anthropic-ai/sdk": "^0.91.1",
74
+ "@google/genai": "^1.50.1",
75
+ "ai": "^6.0.168",
66
76
  "archiver": "^7.0.1",
77
+ "modern-screenshot": "^4.7.0",
67
78
  "motion": "^12.38.0",
68
- "playwright": "^1.58.2",
69
- "wrangler": "^4.75.0"
79
+ "playwright": "^1.59.1",
80
+ "wrangler": "^4.85.0",
81
+ "zod": "^4.3.6"
70
82
  }
71
83
  }
@@ -885,6 +885,82 @@ function resolveGradientStops(el, win) {
885
885
  return null;
886
886
  }
887
887
 
888
+ // Parse a single CSS length token to pixels. Accepts "12px", "50%", a
889
+ // shorthand like "12px 4px" (uses the first value), or empty / null.
890
+ // Returns the pixel value, or null when the input is unparseable.
891
+ // Percentages convert against `widthPx` when one is supplied. Without a
892
+ // usable width (jsdom returns "auto" for many real-world elements,
893
+ // which parseFloat collapses to 0), fall back to the raw percentage
894
+ // number so callers gating on `> 0` (border-accent-on-rounded,
895
+ // isCardLike's hasRadius) still see a positive value, matching the
896
+ // original parseFloat("50%") === 50 behavior.
897
+ function parseRadiusToPx(value, widthPx) {
898
+ if (!value || typeof value !== 'string') return null;
899
+ const trimmed = value.trim();
900
+ if (!trimmed) return null;
901
+ const first = trimmed.split(/\s+/)[0];
902
+ const num = parseFloat(first);
903
+ if (Number.isNaN(num)) return null;
904
+ if (/%$/.test(first)) {
905
+ if (widthPx && widthPx > 0) return (num / 100) * widthPx;
906
+ return num;
907
+ }
908
+ return num;
909
+ }
910
+
911
+ // jsdom from 29.0.2 onward returns "" for the `border-radius` shorthand
912
+ // in computed style and "0" for longhand reads when the source rule used
913
+ // the shorthand. The rule engine relied on parseFloat(style.borderRadius)
914
+ // to identify circular avatars (border-radius >= width/2) and rounded
915
+ // cards (border-radius > 0); both checks broke silently. This helper
916
+ // recovers the radius via a chain of fallbacks. Browsers resolve the
917
+ // shorthand correctly and exit on the first line.
918
+ function resolveBorderRadiusPx(el, style, widthPx, win) {
919
+ const fromComputed = parseRadiusToPx(style.borderRadius, widthPx);
920
+ if (fromComputed !== null) return fromComputed;
921
+
922
+ if (IS_BROWSER || !win) return 0;
923
+
924
+ const fromLonghand = parseRadiusToPx(style.borderTopLeftRadius, widthPx);
925
+ if (fromLonghand !== null && fromLonghand > 0) return fromLonghand;
926
+
927
+ const fromInlineProp = parseRadiusToPx(el.style?.borderRadius, widthPx);
928
+ if (fromInlineProp !== null) return fromInlineProp;
929
+
930
+ const rawStyle = el.getAttribute?.('style') || '';
931
+ const inlineMatch = rawStyle.match(/border-radius\s*:\s*([^;]+)/i);
932
+ if (inlineMatch) {
933
+ const fromRaw = parseRadiusToPx(inlineMatch[1].trim(), widthPx);
934
+ if (fromRaw !== null) return fromRaw;
935
+ }
936
+
937
+ // Walk every stylesheet looking for matching rules. Take the maximum
938
+ // pixel value across all matches so a circle declaration overridden by
939
+ // a more specific rounded-square selector still registers as a circle
940
+ // for the exclusion check (better to under-flag than to false-positive
941
+ // on round avatars).
942
+ let max = 0;
943
+ const sheets = win.document?.styleSheets;
944
+ if (sheets) {
945
+ for (const sheet of sheets) {
946
+ let rules;
947
+ try { rules = sheet.cssRules || []; } catch { continue; }
948
+ for (const rule of rules) {
949
+ if (!rule.style || !rule.selectorText) continue;
950
+ let matches = false;
951
+ try { matches = el.matches(rule.selectorText); } catch { continue; }
952
+ if (!matches) continue;
953
+ const ruleValue = rule.style.borderRadius
954
+ || (rule.style.getPropertyValue && rule.style.getPropertyValue('border-radius'))
955
+ || rule.style.borderTopLeftRadius;
956
+ const px = parseRadiusToPx(ruleValue, widthPx);
957
+ if (px !== null && px > max) max = px;
958
+ }
959
+ }
960
+ }
961
+ return max;
962
+ }
963
+
888
964
  // ─── Section 5: Element Adapters ────────────────────────────────────────────
889
965
 
890
966
  // Browser adapters — call getComputedStyle/getBoundingClientRect on live DOM
@@ -1271,7 +1347,7 @@ function checkElementQuality(el, style, tag, window) {
1271
1347
  return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null });
1272
1348
  }
1273
1349
 
1274
- function checkElementBorders(tag, style, overrides) {
1350
+ function checkElementBorders(tag, style, overrides, resolvedRadius) {
1275
1351
  const sides = ['Top', 'Right', 'Bottom', 'Left'];
1276
1352
  const widths = {}, colors = {};
1277
1353
  for (const s of sides) {
@@ -1291,7 +1367,14 @@ function checkElementBorders(tag, style, overrides) {
1291
1367
  colors[s] = overrides[s].color;
1292
1368
  }
1293
1369
  }
1294
- return checkBorders(tag, widths, colors, parseFloat(style.borderRadius) || 0);
1370
+ // resolvedRadius lets the caller pre-resolve the radius via
1371
+ // resolveBorderRadiusPx so the value survives jsdom 29.1.0's broken
1372
+ // shorthand serialization. Falls back to the computed value for tests
1373
+ // and browser callers that don't pre-resolve.
1374
+ const radius = resolvedRadius != null
1375
+ ? resolvedRadius
1376
+ : (parseFloat(style.borderRadius) || 0);
1377
+ return checkBorders(tag, widths, colors, radius);
1295
1378
  }
1296
1379
 
1297
1380
  function checkElementColors(el, style, tag, window) {
@@ -1346,7 +1429,7 @@ function checkElementIconTile(el, tag, window) {
1346
1429
  siblingBgColor: parseRgb(sibStyle.backgroundColor),
1347
1430
  siblingBgImage: sibStyle.backgroundImage || '',
1348
1431
  siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
1349
- siblingBorderRadius: parseFloat(sibStyle.borderRadius) || 0,
1432
+ siblingBorderRadius: resolveBorderRadiusPx(sibling, sibStyle, sibWidth, window),
1350
1433
  hasIconChild: !!iconChild || hasInlineEmojiIcon,
1351
1434
  iconChildWidth: iconWidth,
1352
1435
  });
@@ -1565,7 +1648,8 @@ function isCardLike(el, win) {
1565
1648
  const hasShadow = (style.boxShadow && style.boxShadow !== 'none') ||
1566
1649
  /\bshadow(?:-sm|-md|-lg|-xl|-2xl)?\b/.test(cls) || /box-shadow/i.test(rawStyle);
1567
1650
  const hasBorder = /\bborder\b/.test(cls);
1568
- const hasRadius = (parseFloat(style.borderRadius) || 0) > 0 ||
1651
+ const widthPx = parseFloat(style.width) || 0;
1652
+ const hasRadius = resolveBorderRadiusPx(el, style, widthPx, win) > 0 ||
1569
1653
  /\brounded(?:-sm|-md|-lg|-xl|-2xl|-full)?\b/.test(cls) || /border-radius/i.test(rawStyle);
1570
1654
  const hasBg = /\bbg-(?:white|gray-\d+|slate-\d+)\b/.test(cls) ||
1571
1655
  /background(?:-color)?\s*:\s*(?!transparent)/i.test(rawStyle);
@@ -2246,6 +2330,9 @@ if (IS_BROWSER) {
2246
2330
  // Skip browser extension elements (Claude, etc.)
2247
2331
  const elId = el.id || '';
2248
2332
  if (elId.startsWith('claude-') || elId.startsWith('cic-')) continue;
2333
+ // Skip the impeccable live-mode overlay (highlight, tooltip, bar, picker, toast).
2334
+ // These are inspector chrome, not part of the user's design.
2335
+ if (el.closest('[id^="impeccable-live-"]')) continue;
2249
2336
  // Skip html/body -- page-level findings go in the banner, not a full-page overlay
2250
2337
  if (el === document.body || el === document.documentElement) continue;
2251
2338
 
@@ -2299,7 +2386,14 @@ if (IS_BROWSER) {
2299
2386
  }
2300
2387
 
2301
2388
  // Regex-on-HTML checks (shared with Node)
2302
- const htmlPatternFindings = checkHtmlPatterns(document.documentElement.outerHTML);
2389
+ // Clone the document and strip impeccable-live overlay nodes before the
2390
+ // regex scan, so the inspector's own inline styles (transitions on top/
2391
+ // left/width/height, etc.) don't register as page anti-patterns.
2392
+ const docClone = document.documentElement.cloneNode(true);
2393
+ for (const node of docClone.querySelectorAll('[id^="impeccable-live-"]')) {
2394
+ node.remove();
2395
+ }
2396
+ const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
2303
2397
  if (htmlPatternFindings.length > 0) {
2304
2398
  const mapped = htmlPatternFindings.map(f => ({ type: f.id, detail: f.snippet })).filter(f => _ruleOk(f.type));
2305
2399
  pageLevelFindings.push(...mapped);
@@ -26,10 +26,11 @@ const IS_BROWSER = typeof window !== 'undefined';
26
26
  const IS_NODE = !IS_BROWSER;
27
27
 
28
28
  // @browser-strip-start
29
- let fs, path;
29
+ let fs, path, fileURLToPath;
30
30
  if (!IS_BROWSER) {
31
31
  fs = (await import('node:fs')).default;
32
32
  path = (await import('node:path')).default;
33
+ fileURLToPath = (await import('node:url')).fileURLToPath;
33
34
  }
34
35
  // @browser-strip-end
35
36
 
@@ -880,6 +881,82 @@ function resolveGradientStops(el, win) {
880
881
  return null;
881
882
  }
882
883
 
884
+ // Parse a single CSS length token to pixels. Accepts "12px", "50%", a
885
+ // shorthand like "12px 4px" (uses the first value), or empty / null.
886
+ // Returns the pixel value, or null when the input is unparseable.
887
+ // Percentages convert against `widthPx` when one is supplied. Without a
888
+ // usable width (jsdom returns "auto" for many real-world elements,
889
+ // which parseFloat collapses to 0), fall back to the raw percentage
890
+ // number so callers gating on `> 0` (border-accent-on-rounded,
891
+ // isCardLike's hasRadius) still see a positive value, matching the
892
+ // original parseFloat("50%") === 50 behavior.
893
+ function parseRadiusToPx(value, widthPx) {
894
+ if (!value || typeof value !== 'string') return null;
895
+ const trimmed = value.trim();
896
+ if (!trimmed) return null;
897
+ const first = trimmed.split(/\s+/)[0];
898
+ const num = parseFloat(first);
899
+ if (Number.isNaN(num)) return null;
900
+ if (/%$/.test(first)) {
901
+ if (widthPx && widthPx > 0) return (num / 100) * widthPx;
902
+ return num;
903
+ }
904
+ return num;
905
+ }
906
+
907
+ // jsdom from 29.0.2 onward returns "" for the `border-radius` shorthand
908
+ // in computed style and "0" for longhand reads when the source rule used
909
+ // the shorthand. The rule engine relied on parseFloat(style.borderRadius)
910
+ // to identify circular avatars (border-radius >= width/2) and rounded
911
+ // cards (border-radius > 0); both checks broke silently. This helper
912
+ // recovers the radius via a chain of fallbacks. Browsers resolve the
913
+ // shorthand correctly and exit on the first line.
914
+ function resolveBorderRadiusPx(el, style, widthPx, win) {
915
+ const fromComputed = parseRadiusToPx(style.borderRadius, widthPx);
916
+ if (fromComputed !== null) return fromComputed;
917
+
918
+ if (IS_BROWSER || !win) return 0;
919
+
920
+ const fromLonghand = parseRadiusToPx(style.borderTopLeftRadius, widthPx);
921
+ if (fromLonghand !== null && fromLonghand > 0) return fromLonghand;
922
+
923
+ const fromInlineProp = parseRadiusToPx(el.style?.borderRadius, widthPx);
924
+ if (fromInlineProp !== null) return fromInlineProp;
925
+
926
+ const rawStyle = el.getAttribute?.('style') || '';
927
+ const inlineMatch = rawStyle.match(/border-radius\s*:\s*([^;]+)/i);
928
+ if (inlineMatch) {
929
+ const fromRaw = parseRadiusToPx(inlineMatch[1].trim(), widthPx);
930
+ if (fromRaw !== null) return fromRaw;
931
+ }
932
+
933
+ // Walk every stylesheet looking for matching rules. Take the maximum
934
+ // pixel value across all matches so a circle declaration overridden by
935
+ // a more specific rounded-square selector still registers as a circle
936
+ // for the exclusion check (better to under-flag than to false-positive
937
+ // on round avatars).
938
+ let max = 0;
939
+ const sheets = win.document?.styleSheets;
940
+ if (sheets) {
941
+ for (const sheet of sheets) {
942
+ let rules;
943
+ try { rules = sheet.cssRules || []; } catch { continue; }
944
+ for (const rule of rules) {
945
+ if (!rule.style || !rule.selectorText) continue;
946
+ let matches = false;
947
+ try { matches = el.matches(rule.selectorText); } catch { continue; }
948
+ if (!matches) continue;
949
+ const ruleValue = rule.style.borderRadius
950
+ || (rule.style.getPropertyValue && rule.style.getPropertyValue('border-radius'))
951
+ || rule.style.borderTopLeftRadius;
952
+ const px = parseRadiusToPx(ruleValue, widthPx);
953
+ if (px !== null && px > max) max = px;
954
+ }
955
+ }
956
+ }
957
+ return max;
958
+ }
959
+
883
960
  // ─── Section 5: Element Adapters ────────────────────────────────────────────
884
961
 
885
962
  // Browser adapters — call getComputedStyle/getBoundingClientRect on live DOM
@@ -1266,7 +1343,7 @@ function checkElementQuality(el, style, tag, window) {
1266
1343
  return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null });
1267
1344
  }
1268
1345
 
1269
- function checkElementBorders(tag, style, overrides) {
1346
+ function checkElementBorders(tag, style, overrides, resolvedRadius) {
1270
1347
  const sides = ['Top', 'Right', 'Bottom', 'Left'];
1271
1348
  const widths = {}, colors = {};
1272
1349
  for (const s of sides) {
@@ -1286,7 +1363,14 @@ function checkElementBorders(tag, style, overrides) {
1286
1363
  colors[s] = overrides[s].color;
1287
1364
  }
1288
1365
  }
1289
- return checkBorders(tag, widths, colors, parseFloat(style.borderRadius) || 0);
1366
+ // resolvedRadius lets the caller pre-resolve the radius via
1367
+ // resolveBorderRadiusPx so the value survives jsdom 29.1.0's broken
1368
+ // shorthand serialization. Falls back to the computed value for tests
1369
+ // and browser callers that don't pre-resolve.
1370
+ const radius = resolvedRadius != null
1371
+ ? resolvedRadius
1372
+ : (parseFloat(style.borderRadius) || 0);
1373
+ return checkBorders(tag, widths, colors, radius);
1290
1374
  }
1291
1375
 
1292
1376
  function checkElementColors(el, style, tag, window) {
@@ -1341,7 +1425,7 @@ function checkElementIconTile(el, tag, window) {
1341
1425
  siblingBgColor: parseRgb(sibStyle.backgroundColor),
1342
1426
  siblingBgImage: sibStyle.backgroundImage || '',
1343
1427
  siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
1344
- siblingBorderRadius: parseFloat(sibStyle.borderRadius) || 0,
1428
+ siblingBorderRadius: resolveBorderRadiusPx(sibling, sibStyle, sibWidth, window),
1345
1429
  hasIconChild: !!iconChild || hasInlineEmojiIcon,
1346
1430
  iconChildWidth: iconWidth,
1347
1431
  });
@@ -1560,7 +1644,8 @@ function isCardLike(el, win) {
1560
1644
  const hasShadow = (style.boxShadow && style.boxShadow !== 'none') ||
1561
1645
  /\bshadow(?:-sm|-md|-lg|-xl|-2xl)?\b/.test(cls) || /box-shadow/i.test(rawStyle);
1562
1646
  const hasBorder = /\bborder\b/.test(cls);
1563
- const hasRadius = (parseFloat(style.borderRadius) || 0) > 0 ||
1647
+ const widthPx = parseFloat(style.width) || 0;
1648
+ const hasRadius = resolveBorderRadiusPx(el, style, widthPx, win) > 0 ||
1564
1649
  /\brounded(?:-sm|-md|-lg|-xl|-2xl|-full)?\b/.test(cls) || /border-radius/i.test(rawStyle);
1565
1650
  const hasBg = /\bbg-(?:white|gray-\d+|slate-\d+)\b/.test(cls) ||
1566
1651
  /background(?:-color)?\s*:\s*(?!transparent)/i.test(rawStyle);
@@ -2241,6 +2326,9 @@ if (IS_BROWSER) {
2241
2326
  // Skip browser extension elements (Claude, etc.)
2242
2327
  const elId = el.id || '';
2243
2328
  if (elId.startsWith('claude-') || elId.startsWith('cic-')) continue;
2329
+ // Skip the impeccable live-mode overlay (highlight, tooltip, bar, picker, toast).
2330
+ // These are inspector chrome, not part of the user's design.
2331
+ if (el.closest('[id^="impeccable-live-"]')) continue;
2244
2332
  // Skip html/body -- page-level findings go in the banner, not a full-page overlay
2245
2333
  if (el === document.body || el === document.documentElement) continue;
2246
2334
 
@@ -2294,7 +2382,14 @@ if (IS_BROWSER) {
2294
2382
  }
2295
2383
 
2296
2384
  // Regex-on-HTML checks (shared with Node)
2297
- const htmlPatternFindings = checkHtmlPatterns(document.documentElement.outerHTML);
2385
+ // Clone the document and strip impeccable-live overlay nodes before the
2386
+ // regex scan, so the inspector's own inline styles (transitions on top/
2387
+ // left/width/height, etc.) don't register as page anti-patterns.
2388
+ const docClone = document.documentElement.cloneNode(true);
2389
+ for (const node of docClone.querySelectorAll('[id^="impeccable-live-"]')) {
2390
+ node.remove();
2391
+ }
2392
+ const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
2298
2393
  if (htmlPatternFindings.length > 0) {
2299
2394
  const mapped = htmlPatternFindings.map(f => ({ type: f.id, detail: f.snippet })).filter(f => _ruleOk(f.type));
2300
2395
  pageLevelFindings.push(...mapped);
@@ -2633,7 +2728,8 @@ async function detectHtml(filePath) {
2633
2728
  for (const el of document.querySelectorAll('*')) {
2634
2729
  const tag = el.tagName.toLowerCase();
2635
2730
  const style = window.getComputedStyle(el);
2636
- for (const f of checkElementBorders(tag, style, borderOverrides.get(el))) {
2731
+ const resolvedRadius = resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0, window);
2732
+ for (const f of checkElementBorders(tag, style, borderOverrides.get(el), resolvedRadius)) {
2637
2733
  findings.push(finding(f.id, filePath, f.snippet));
2638
2734
  }
2639
2735
  for (const f of checkElementColors(el, style, tag, window)) {
@@ -2687,7 +2783,7 @@ async function detectUrl(url) {
2687
2783
 
2688
2784
  // Read the browser detection script — reuse it instead of reimplementing
2689
2785
  const browserScriptPath = path.resolve(
2690
- path.dirname(new URL(import.meta.url).pathname),
2786
+ path.dirname(fileURLToPath(import.meta.url)),
2691
2787
  'detect-antipatterns-browser.js'
2692
2788
  );
2693
2789
  let browserScript;
@@ -3442,124 +3538,6 @@ async function main() {
3442
3538
  process.exit(0);
3443
3539
  }
3444
3540
 
3445
- // ---------------------------------------------------------------------------
3446
- // Live detection server
3447
- // ---------------------------------------------------------------------------
3448
-
3449
- async function findOpenPort(start = 8400) {
3450
- const net = await import('node:net');
3451
- return new Promise((resolve) => {
3452
- const server = net.default.createServer();
3453
- server.listen(start, '127.0.0.1', () => {
3454
- const port = server.address().port;
3455
- server.close(() => resolve(port));
3456
- });
3457
- server.on('error', () => resolve(findOpenPort(start + 1)));
3458
- });
3459
- }
3460
-
3461
- const LIVE_PID_FILE = path.join((await import('node:os')).default.tmpdir(), 'impeccable-live.json');
3462
-
3463
- async function liveCli() {
3464
- const args = process.argv.slice(2);
3465
- const helpMode = args.includes('--help');
3466
- const stopMode = args.includes('stop');
3467
- const portArg = args.find(a => a.startsWith('--port='));
3468
- const requestedPort = portArg ? parseInt(portArg.split('=')[1], 10) : null;
3469
-
3470
- if (helpMode) {
3471
- console.log(`Usage: impeccable live [options]
3472
-
3473
- Start a local server that serves the browser detection overlay script.
3474
- Inject the script into any page to scan for anti-patterns in real time.
3475
-
3476
- Commands:
3477
- live Start the server (default)
3478
- live stop Stop a running live server
3479
-
3480
- Options:
3481
- --port=PORT Use a specific port (default: auto-detect unused port)
3482
- --help Show this help message
3483
-
3484
- The server provides:
3485
- /detect.js The detection overlay script (inject via <script> tag)
3486
- /health Health check endpoint
3487
- /stop Stop the server remotely`);
3488
- process.exit(0);
3489
- }
3490
-
3491
- // Stop a running server
3492
- if (stopMode) {
3493
- try {
3494
- const info = JSON.parse(fs.readFileSync(LIVE_PID_FILE, 'utf-8'));
3495
- const res = await fetch(`http://localhost:${info.port}/stop`);
3496
- if (res.ok) {
3497
- console.log(`Stopped live server on port ${info.port}.`);
3498
- }
3499
- } catch {
3500
- console.log('No running live server found.');
3501
- }
3502
- process.exit(0);
3503
- }
3504
-
3505
- const http = await import('node:http');
3506
- const scriptPath = path.join(path.dirname(new URL(import.meta.url).pathname), 'detect-antipatterns-browser.js');
3507
-
3508
- let browserScript;
3509
- try {
3510
- browserScript = fs.readFileSync(scriptPath, 'utf-8');
3511
- } catch {
3512
- process.stderr.write('Error: Browser script not found. Run `npm run build:browser` first.\n');
3513
- process.exit(1);
3514
- }
3515
-
3516
- const port = requestedPort || await findOpenPort();
3517
-
3518
- const shutdown = () => {
3519
- try { fs.unlinkSync(LIVE_PID_FILE); } catch { /* ignore */ }
3520
- server.close();
3521
- process.exit(0);
3522
- };
3523
-
3524
- const server = http.default.createServer((req, res) => {
3525
- // CORS headers for cross-origin injection
3526
- res.setHeader('Access-Control-Allow-Origin', '*');
3527
- res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
3528
- if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
3529
-
3530
- if (req.url === '/detect.js' || req.url === '/') {
3531
- res.writeHead(200, { 'Content-Type': 'application/javascript' });
3532
- res.end(browserScript);
3533
- } else if (req.url === '/health') {
3534
- res.writeHead(200, { 'Content-Type': 'application/json' });
3535
- res.end(JSON.stringify({ status: 'ok', port }));
3536
- } else if (req.url === '/stop') {
3537
- res.writeHead(200, { 'Content-Type': 'text/plain' });
3538
- res.end('stopping');
3539
- shutdown();
3540
- } else {
3541
- res.writeHead(404);
3542
- res.end('Not found');
3543
- }
3544
- });
3545
-
3546
- server.listen(port, '127.0.0.1', () => {
3547
- // Write PID file so `live stop` can find us
3548
- fs.writeFileSync(LIVE_PID_FILE, JSON.stringify({ pid: process.pid, port }));
3549
-
3550
- const url = `http://localhost:${port}`;
3551
- console.log(`Impeccable live detection server running on ${url}\n`);
3552
- console.log(`Inject into any page:`);
3553
- console.log(` const s = document.createElement('script');`);
3554
- console.log(` s.src = '${url}/detect.js';`);
3555
- console.log(` document.head.appendChild(s);\n`);
3556
- console.log(`Stop: npx impeccable live stop`);
3557
- });
3558
-
3559
- process.on('SIGINT', shutdown);
3560
- process.on('SIGTERM', shutdown);
3561
- }
3562
-
3563
3541
  // ---------------------------------------------------------------------------
3564
3542
  // Entry point
3565
3543
  // ---------------------------------------------------------------------------
@@ -3584,7 +3562,6 @@ export {
3584
3562
  buildImportGraph, resolveImport,
3585
3563
  detectFrameworkConfig, isPortListening, FRAMEWORK_CONFIGS,
3586
3564
  main as detectCli,
3587
- liveCli,
3588
3565
  };
3589
3566
 
3590
3567
  // @browser-strip-end