impeccable 3.2.1 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable CLI
2
2
 
3
- Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 46 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
3
+ Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 58 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
4
4
 
5
5
  ## Quick Start
6
6
 
@@ -56,7 +56,7 @@ npx impeccable detect --fast src/
56
56
 
57
57
  **Quality**: tiny body text, cramped padding, long line lengths, small touch targets
58
58
 
59
- 46 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 58 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
60
60
 
61
61
  ## Exit Codes
62
62
 
package/README.npm.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable CLI
2
2
 
3
- Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 46 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
3
+ Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 58 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
4
4
 
5
5
  ## Quick Start
6
6
 
@@ -56,7 +56,7 @@ npx impeccable detect --fast src/
56
56
 
57
57
  **Quality**: tiny body text, cramped padding, long line lengths, small touch targets
58
58
 
59
- 46 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 58 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
60
60
 
61
61
  ## Exit Codes
62
62
 
package/README.repo.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable
2
2
 
3
- Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 46 deterministic detector rules for AI-generated frontend design.
3
+ Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 58 deterministic detector rules for AI-generated frontend design.
4
4
 
5
5
  > **Quick start:** From your project root, run `npx impeccable install`, then run `/impeccable init` inside your AI coding tool. Full docs: [impeccable.style](https://impeccable.style).
6
6
 
@@ -13,7 +13,7 @@ Every model trained on the same SaaS templates. Skip the guidance and you get th
13
13
  Impeccable adds:
14
14
  - **One setup flow.** `/impeccable init` writes `PRODUCT.md` and offers `DESIGN.md`, so later commands know the audience, brand/product lane, voice, anti-references, colors, type, and components.
15
15
  - **23 commands.** A shared design vocabulary with your AI: `polish`, `audit`, `critique`, `distill`, `animate`, `bolder`, `quieter`, and more.
16
- - **46 deterministic detector rules** plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.
16
+ - **58 deterministic detector rules** plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.
17
17
 
18
18
  ## What's Included
19
19
 
@@ -103,7 +103,7 @@ From the root of your project, run:
103
103
  npx impeccable install
104
104
  ```
105
105
 
106
- This shows the harness folders it detected (for example `~/.claude`, `~/.codex`, or project-local `.cursor`), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use `--providers=claude,codex,cursor` and `--scope=project|global` to skip those choices in scripts. On Claude Code, Cursor, and Codex, it also installs the provider-native hook manifest for the current project. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, Grok Build, and every other supported tool. Reload your harness afterward.
106
+ This shows the harness folders it detected (for example `~/.claude`, `~/.codex`, `~/.grok`, or project-local `.cursor`), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use `--providers=claude,codex,cursor,grok` and `--scope=project|global` to skip those choices in scripts. On Claude Code, Cursor, Codex, GitHub Copilot, and Grok Build, it also installs the provider-native hook manifest for the current project. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, Grok Build, and every other supported tool. Reload your harness afterward.
107
107
 
108
108
  To refresh an existing install, run:
109
109
 
@@ -111,7 +111,7 @@ To refresh an existing install, run:
111
111
  npx impeccable update
112
112
  ```
113
113
 
114
- Codex users should open `/hooks` after install or update and approve the project hook when prompted. Codex tracks trust by hook definition, so updates that change `.codex/hooks.json` can require approval again.
114
+ Codex users should open `/hooks` after install or update and approve the project hook when prompted. Codex tracks trust by hook definition, so updates that change `.codex/hooks.json` can require approval again. Grok Build users need project folder trust (`/hooks-trust` or launch with `--trust`) before `.grok/hooks/` scripts run.
115
115
 
116
116
  ### Option 2: Git Submodule
117
117
 
@@ -124,7 +124,7 @@ git add .gitmodules .impeccable .claude .cursor
124
124
  git commit -m "Add Impeccable skills"
125
125
  ```
126
126
 
127
- Use the providers your project needs, for example `claude`, `cursor`, `gemini`, `codex`, `github`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`, or `rovo-dev`. The command links individual skill folders from `.impeccable/dist/universal/` and leaves existing real skill directories untouched unless you pass `--force`.
127
+ Use the providers your project needs, for example `claude`, `cursor`, `gemini`, `codex`, `github`, `grok`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`, `rovo-dev`, or `vibe`. The command links individual skill folders from `.impeccable/dist/universal/` and leaves existing real skill directories untouched unless you pass `--force`.
128
128
 
129
129
  To update later:
130
130
 
@@ -144,10 +144,10 @@ npx impeccable link --source=.impeccable --providers=claude,cursor
144
144
 
145
145
  **Grok Build:**
146
146
  ```bash
147
- grok plugin install pbakaus/impeccable --trust
147
+ grok plugin install pbakaus/impeccable#plugin --trust
148
148
  ```
149
149
 
150
- > Grok Build only. Then run `/impeccable init` in a Grok session.
150
+ > Grok Build only. The `#plugin` suffix installs the slim plugin package (skills, agents, and hooks) instead of the full monorepo. Then run `/impeccable init` in a Grok session. Project-scoped installs via `npx impeccable install --providers=grok` also work and write `.grok/skills/` plus `.grok/hooks/impeccable.json`.
151
151
 
152
152
  ### Option 4: Download from Website
153
153
 
@@ -250,6 +250,26 @@ cp -r dist/qoder/.qoder your-project/
250
250
  cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/
251
251
  ```
252
252
 
253
+ **Mistral Vibe:**
254
+ ```bash
255
+ # Project-specific
256
+ cp -r dist/vibe/.vibe your-project/
257
+
258
+ # Or global (applies to all projects)
259
+ cp -r dist/vibe/.vibe/skills/* ~/.vibe/skills/
260
+ ```
261
+
262
+ **Grok Build:**
263
+ ```bash
264
+ # Project-specific
265
+ cp -r dist/grok/.grok your-project/
266
+
267
+ # Or global (applies to all projects)
268
+ cp -r dist/grok/.grok/skills/* ~/.grok/skills/
269
+ ```
270
+
271
+ > Prefer `npx impeccable install --providers=grok` or `grok plugin install pbakaus/impeccable#plugin --trust` so the design hook installs too. Project hooks need `/hooks-trust` (or `--trust`) once per folder.
272
+
253
273
  ## Usage
254
274
 
255
275
  Once installed, every command runs through the single `/impeccable` skill:
@@ -316,7 +336,7 @@ If an ephemeral file (a screenshot, `config.local.json`) was committed before yo
316
336
 
317
337
  ## Design hook
318
338
 
319
- On Claude Code, GitHub Copilot, Codex, and Cursor, `npx impeccable install` and `npx impeccable update` install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code, GitHub Copilot, and Codex surface findings after the edit. Cursor blocks bad proposed writes before they land.
339
+ On Claude Code, GitHub Copilot, Codex, Cursor, and Grok Build, `npx impeccable install` and `npx impeccable update` install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code, GitHub Copilot, Codex, and Grok Build surface findings after the edit (and run a deeper pass on Stop where supported). Cursor blocks bad proposed writes before they land.
320
340
 
321
341
  Installed hook surfaces:
322
342
 
@@ -357,7 +377,7 @@ npx impeccable ignores add-file "src/legacy/**"
357
377
  npx impeccable ignores add-value overused-font Inter --reason "Brand font"
358
378
  ```
359
379
 
360
- The detector catches 46 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
380
+ The detector catches 49 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
361
381
 
362
382
  By default, `detect` respects the same `.impeccable/config.json` and `.impeccable/config.local.json` detector config as the design hook: `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`. Hook lifecycle settings such as `hook.enabled` only affect automatic hook execution.
363
383
 
@@ -379,6 +399,7 @@ Full detector docs: [impeccable.style/docs/detector](https://impeccable.style/do
379
399
  - [Trae](https://trae.ai)
380
400
  - [Rovo Dev](https://www.atlassian.com/software/rovo)
381
401
  - [Qoder](https://qoder.com)
402
+ - [Mistral Vibe](https://docs.mistral.ai/vibe/code/overview)
382
403
 
383
404
  ## Community & Ecosystem
384
405
 
@@ -78,6 +78,20 @@ function parseScope(args, { allowAll = false } = {}) {
78
78
  return { local, all, rest };
79
79
  }
80
80
 
81
+ // An empty glob used to be dropped by filter(Boolean), so `--file=` reported
82
+ // success and wrote an entry with no files: the user asked to scope a rule to one
83
+ // file and silently got the project-wide suppression instead. Refuse it.
84
+ function requireGlob(raw, flag) {
85
+ const glob = String(raw ?? '').trim();
86
+ if (!glob) throw new Error(`${flag} requires a non-empty glob`);
87
+ // A following flag is not a glob. `--file --reason "why"` consumed `--reason`
88
+ // as the scope and left the reason text to fold into the value, storing
89
+ // value="* why" files=["--reason"] and reporting success. Same silent-no-op
90
+ // class as an unknown flag folding into the value; refuse it the same way.
91
+ if (glob.startsWith('--')) throw new Error(`${flag} requires a glob, got the flag ${glob}`);
92
+ return glob;
93
+ }
94
+
81
95
  function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
82
96
  const positionals = [];
83
97
  const files = [];
@@ -93,11 +107,11 @@ function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
93
107
  reason = arg.slice('--reason='.length).trim();
94
108
  } else if (arg === '--file' || arg === '--files') {
95
109
  if (i + 1 >= args.length) throw new Error(`${arg} requires a glob`);
96
- files.push(String(args[++i]).trim());
110
+ files.push(requireGlob(args[++i], arg));
97
111
  } else if (arg.startsWith('--file=')) {
98
- files.push(arg.slice('--file='.length).trim());
112
+ files.push(requireGlob(arg.slice('--file='.length), '--file'));
99
113
  } else if (arg.startsWith('--files=')) {
100
- files.push(arg.slice('--files='.length).trim());
114
+ files.push(requireGlob(arg.slice('--files='.length), '--files'));
101
115
  } else if (arg.startsWith('--')) {
102
116
  throw new Error(`Unknown add-value flag: ${arg}`);
103
117
  } else {
@@ -108,7 +122,9 @@ function parseValueArgs(args, { allowUnscopedWildcard = false } = {}) {
108
122
  const [rule, ...valueParts] = positionals;
109
123
  const value = normalizeIgnoreValue(valueParts.join(' '));
110
124
  if (!rule || !value) throw new Error('Pass a rule id and value, e.g. impeccable ignores add-value overused-font Inter');
111
- const scopedFiles = Array.from(new Set(files.filter(Boolean)));
125
+ // Sorted: the dedup key compares the files array, so an unsorted scope made
126
+ // `--file b.css --file a.css` a different entry from `--file a.css --file b.css`.
127
+ const scopedFiles = Array.from(new Set(files.filter(Boolean))).sort();
112
128
  if (value === '*' && scopedFiles.length === 0 && !allowUnscopedWildcard) {
113
129
  throw new Error('Wildcard value ignores must be scoped with --file <glob>.');
114
130
  }
@@ -226,12 +242,14 @@ function addValue(cwd, args) {
226
242
  if (parsed.reason) existing.reason = parsed.reason;
227
243
  if (parsed.files.length) existing.files = parsed.files;
228
244
  } else {
245
+ // rule, value, files, createdAt, reason — the same order the normalizers emit,
246
+ // so a fresh entry survives the next write untouched.
229
247
  const entry = {
230
248
  rule: parsed.rule,
231
249
  value: parsed.value,
232
- createdAt: new Date().toISOString(),
233
250
  };
234
251
  if (parsed.files.length) entry.files = parsed.files;
252
+ entry.createdAt = new Date().toISOString();
235
253
  if (parsed.reason) entry.reason = parsed.reason;
236
254
  config.ignoreValues.push(entry);
237
255
  }
@@ -299,7 +317,10 @@ function clear(cwd, args) {
299
317
  }
300
318
 
301
319
  function ignoreValueKey(entry) {
302
- const files = Array.isArray(entry.files) && entry.files.length ? entry.files.join('\x1f') : '';
320
+ // Sorted: a file scope is a set. Comparing stored order made an on-disk scope
321
+ // miss the sorted argv form, so a re-add duplicated the entry and a remove
322
+ // silently failed. Every key that hashes `files` must sort — there are four.
323
+ const files = Array.isArray(entry.files) && entry.files.length ? [...entry.files].sort().join('\x1f') : '';
303
324
  return `${String(entry.rule || '').trim().toLowerCase()}\0${normalizeIgnoreValue(entry.value)}\0${files}`;
304
325
  }
305
326
 
@@ -23,7 +23,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
23
23
  const API_BASE = 'https://impeccable.style';
24
24
 
25
25
  // Provider folder names in project roots
26
- const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn', '.rovodev'];
26
+ const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.grok', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn', '.rovodev', '.vibe'];
27
27
  const PROVIDER_ALIASES = {
28
28
  agents: '.agents',
29
29
  claude: '.claude',
@@ -33,6 +33,9 @@ const PROVIDER_ALIASES = {
33
33
  cursor: '.cursor',
34
34
  gemini: '.gemini',
35
35
  github: '.github',
36
+ grok: '.grok',
37
+ 'grok-build': '.grok',
38
+ xai: '.grok',
36
39
  kiro: '.kiro',
37
40
  opencode: '.opencode',
38
41
  pi: '.pi',
@@ -41,6 +44,7 @@ const PROVIDER_ALIASES = {
41
44
  rovodev: '.rovodev',
42
45
  trae: '.trae',
43
46
  'trae-cn': '.trae-cn',
47
+ vibe: '.vibe',
44
48
  };
45
49
 
46
50
  const PROVIDER_DISPLAY = {
@@ -49,6 +53,7 @@ const PROVIDER_DISPLAY = {
49
53
  '.cursor': { name: 'Cursor', input: 'cursor' },
50
54
  '.gemini': { name: 'Gemini CLI', input: 'gemini' },
51
55
  '.github': { name: 'GitHub Copilot', input: 'github' },
56
+ '.grok': { name: 'Grok Build', input: 'grok' },
52
57
  '.kiro': { name: 'Kiro', input: 'kiro' },
53
58
  '.opencode': { name: 'OpenCode', input: 'opencode' },
54
59
  '.pi': { name: 'Project Indigo', input: 'pi' },
@@ -56,8 +61,9 @@ const PROVIDER_DISPLAY = {
56
61
  '.rovodev': { name: 'Rovo Dev', input: 'rovo-dev' },
57
62
  '.trae': { name: 'Trae', input: 'trae' },
58
63
  '.trae-cn': { name: 'Trae CN', input: 'trae-cn' },
64
+ '.vibe': { name: 'Mistral Vibe', input: 'vibe' },
59
65
  };
60
- const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev'];
66
+ const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'grok', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev', 'vibe'];
61
67
 
62
68
  // Providers whose GLOBAL (home) skills dir is not `<provider>/skills`.
63
69
  // Pi discovers global skills from ~/.pi/agent/skills/; project scope
@@ -74,11 +80,13 @@ const GLOBAL_HARNESS_HINTS = [
74
80
  { home: '.codex', provider: '.agents' },
75
81
  { home: '.cursor', provider: '.cursor' },
76
82
  { home: '.gemini', provider: '.gemini' },
83
+ { home: '.grok', provider: '.grok' },
77
84
  { home: '.kiro', provider: '.kiro' },
78
85
  { home: '.opencode', provider: '.opencode' },
79
86
  { home: '.pi', provider: '.pi' },
80
87
  { home: '.qoder', provider: '.qoder' },
81
88
  { home: '.rovodev', provider: '.rovodev' },
89
+ { home: '.vibe', provider: '.vibe' },
82
90
  ];
83
91
 
84
92
  // Last-resort default when nothing is detected: Claude Code + the universal
@@ -117,6 +125,12 @@ const PROVIDER_HOOK_ARTIFACTS = {
117
125
  '.github': [
118
126
  { sourceProvider: '.github', rel: 'hooks/impeccable.json', destProvider: '.github' },
119
127
  ],
128
+ // Grok Build discovers project hooks from `.grok/hooks/*.json`. Team-shared
129
+ // by default (commit them if the whole team uses Grok); folder trust is still
130
+ // required via `/hooks-trust` or `--trust` before they run.
131
+ '.grok': [
132
+ { sourceProvider: '.grok', rel: 'hooks/impeccable.json', destProvider: '.grok' },
133
+ ],
120
134
  };
121
135
 
122
136
  function userProviderSkillsDir(home, provider) {
@@ -568,7 +582,7 @@ async function copyOrExtractLocalBundle(sourceValue) {
568
582
  */
569
583
  function normalizeForHash(content) {
570
584
  return content
571
- .replace(/\.(claude|cursor|agents|github|gemini|codex|kiro|opencode|pi|qoder|trae|trae-cn|rovodev)\/skills\//g, '.PROVIDER/skills/');
585
+ .replace(/\.(claude|cursor|agents|github|gemini|codex|grok|kiro|opencode|pi|qoder|trae|trae-cn|rovodev|vibe)\/skills\//g, '.PROVIDER/skills/');
572
586
  }
573
587
 
574
588
  function hashSkillFile(filePath) {
@@ -1222,7 +1222,7 @@ if (IS_BROWSER) {
1222
1222
  return {
1223
1223
  type: f.type || f.id,
1224
1224
  category: ap ? ap.category : 'quality',
1225
- severity: ap?.severity || 'warning',
1225
+ severity: f.severity || ap?.severity || 'warning',
1226
1226
  detail: f.detail || f.snippet,
1227
1227
  ignoreValue: f.ignoreValue || f.value || '',
1228
1228
  name: ap ? ap.name : (f.type || f.id),
@@ -1458,10 +1458,7 @@ if (IS_BROWSER) {
1458
1458
  const _ruleOk = (id) => !_disabled.length || !_disabled.includes(id);
1459
1459
  const designSystem = browserDesignSystemConfig();
1460
1460
  const designSeen = { fonts: new Set(), colors: new Set(), radii: new Set() };
1461
- // Note: provider-gated rules (--gpt / --gemini) are NOT filtered here. In a
1462
- // real browser env (detector page, live overlay, extension) running every
1463
- // check is free, so we always surface them; the gating is purely a CLI
1464
- // output concern, applied in the Node engines' detect* return paths.
1461
+ // All deterministic rules run in the browser and extension path.
1465
1462
 
1466
1463
  for (const el of document.querySelectorAll('*')) {
1467
1464
  // Skip impeccable's own elements and any descendants (overlays, labels, banner, nav buttons)
@@ -1477,6 +1474,7 @@ if (IS_BROWSER) {
1477
1474
 
1478
1475
  const findings = [
1479
1476
  ...checkElementBordersDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1477
+ ...checkElementPseudoStripeDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1480
1478
  ...checkElementColorsDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1481
1479
  ...checkElementMotionDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1482
1480
  ...checkElementGlowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
@@ -1488,6 +1486,7 @@ if (IS_BROWSER) {
1488
1486
  ...checkElementClippedOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1489
1487
  ...checkElementGptBorderShadowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1490
1488
  ...checkElementTextOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1489
+ ...checkElementBlinkingCursorDOM(el).map(f => ({ type: f.id, detail: f.snippet, ...(f.severity ? { severity: f.severity } : {}) })),
1491
1490
  ...checkElementDesignSystemDOM(el, designSystem, designSeen),
1492
1491
  ].filter(f => _ruleOk(f.type));
1493
1492
 
@@ -1526,12 +1525,55 @@ if (IS_BROWSER) {
1526
1525
  addBrowserFindings(groupMap, document.body, sectionKickerFindings);
1527
1526
  }
1528
1527
 
1528
+ const numberedLabelFindings = checkNumberedSectionLabelsDOM()
1529
+ .map(f => ({ type: f.id, detail: f.snippet }))
1530
+ .filter(f => _ruleOk(f.type));
1531
+ if (numberedLabelFindings.length > 0) {
1532
+ pageLevelFindings.push(...numberedLabelFindings);
1533
+ addBrowserFindings(groupMap, document.body, numberedLabelFindings);
1534
+ }
1535
+
1536
+ const repeatedTextFindings = checkRepeatedContainerTextDOM()
1537
+ .map(f => ({ type: f.id, detail: f.snippet }))
1538
+ .filter(f => _ruleOk(f.type));
1539
+ if (repeatedTextFindings.length > 0) {
1540
+ pageLevelFindings.push(...repeatedTextFindings);
1541
+ addBrowserFindings(groupMap, document.body, repeatedTextFindings);
1542
+ }
1543
+
1529
1544
  const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
1530
1545
  for (const f of layoutFindings) {
1531
1546
  const el = f.el || document.body;
1532
1547
  addBrowserFindings(groupMap, el, [{ type: f.type, detail: f.detail || f.snippet }]);
1533
1548
  }
1534
1549
 
1550
+ // Heading rhythm (browser-only: needs real layout for the gap math)
1551
+ const headingRhythmFindings = checkHeadingRhythmDOM().filter(f => _ruleOk(f.type));
1552
+ for (const f of headingRhythmFindings) {
1553
+ addBrowserFindings(groupMap, f.el || document.body, [{ type: f.type, detail: f.detail }]);
1554
+ }
1555
+
1556
+ // Edge-flush cards in horizontal scrollers (browser-only: needs real
1557
+ // layout for the scroller clip box vs card rect math)
1558
+ const edgeFlushFindings = checkEdgeFlushCardsDOM().filter(f => _ruleOk(f.type));
1559
+ for (const f of edgeFlushFindings) {
1560
+ addBrowserFindings(groupMap, f.el || document.body, [{ type: f.type, detail: f.detail }]);
1561
+ }
1562
+
1563
+ // Text occlusion / element overlap (browser-only: needs real layout +
1564
+ // elementFromPoint to confirm what actually paints on top)
1565
+ const occlusionFindings = checkTextOcclusionDOM().filter(f => _ruleOk(f.type));
1566
+ for (const f of occlusionFindings) {
1567
+ addBrowserFindings(groupMap, f.el || document.body, [{ type: f.type, detail: f.detail }]);
1568
+ }
1569
+
1570
+ // First-viewport column overflow — the stretched-hero signature
1571
+ // (browser-only: needs real layout for the content-extent math)
1572
+ const colOverflowFindings = checkFirstViewportColumnOverflowDOM().filter(f => _ruleOk(f.type));
1573
+ for (const f of colOverflowFindings) {
1574
+ addBrowserFindings(groupMap, f.el || document.body, [{ type: f.type, detail: f.detail }]);
1575
+ }
1576
+
1535
1577
  // Page-level quality checks (headings, etc.)
1536
1578
  const qualityFindings = checkPageQualityDOM().filter(f => _ruleOk(f.type));
1537
1579
  if (qualityFindings.length > 0) {
@@ -1557,7 +1599,25 @@ if (IS_BROWSER) {
1557
1599
  }
1558
1600
  const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
1559
1601
  if (htmlPatternFindings.length > 0) {
1560
- const mapped = htmlPatternFindings.map(f => ({ type: f.id, detail: f.snippet })).filter(f => _ruleOk(f.type));
1602
+ const mapped = htmlPatternFindings.map(f => {
1603
+ const item = { type: f.id, detail: f.snippet };
1604
+ if (f.severity) {
1605
+ item.severity = f.severity;
1606
+ } else if (f.id === 'pulsing-dot' && f.selector) {
1607
+ // The string scan promotes header/nav dots on its own; with a live
1608
+ // layout also promote dots resting in the first ~900px of the page
1609
+ // (the hero region), which the source scan cannot measure.
1610
+ try {
1611
+ const dotEl = document.querySelector(f.selector);
1612
+ if (dotEl) {
1613
+ const rect = dotEl.getBoundingClientRect();
1614
+ const pageTop = rect.top + (window.scrollY || 0);
1615
+ if (pageTop <= 900) item.severity = 'error';
1616
+ }
1617
+ } catch { /* unresolvable selector: keep registry severity */ }
1618
+ }
1619
+ return item;
1620
+ }).filter(f => _ruleOk(f.type));
1561
1621
  pageLevelFindings.push(...mapped);
1562
1622
  addBrowserFindings(groupMap, document.body, mapped);
1563
1623
  }
@@ -1931,6 +1991,9 @@ if (IS_BROWSER) {
1931
1991
  window.impeccableDetectAsync = detectAsync;
1932
1992
  window.impeccableScan = scan;
1933
1993
  window.impeccableScanAsync = scanAsync;
1994
+ // Raw measurement for the URL engine's content-hidden-at-rest pass: it
1995
+ // drives a reveal sweep from Node and thresholds the result itself.
1996
+ window.impeccableMeasureHiddenText = measureHiddenTextDOM;
1934
1997
  window.impeccableCollectVisualContrastCandidates = collectVisualContrastCandidates;
1935
1998
  window.impeccableAnalyzeVisualContrast = analyzeVisualContrast;
1936
1999
  window.impeccableGetLastVisualContrastAnalyses = () => lastVisualContrastAnalyses.slice();
@@ -92,10 +92,10 @@ Scan files or URLs for UI anti-patterns and design quality issues.
92
92
  Options:
93
93
  --json Output results as JSON
94
94
  --quiet In text mode, only print the final findings count
95
- --gpt Also report GPT-specific provider tells (off by default)
96
- --gemini Also report Gemini-specific provider tells (off by default)
97
95
  --scope <name> Only report rules in the given design domain
98
96
  (type, layout). Comma-separated.
97
+ --viewport <WxH> Browser viewport for URL scans (default 1280x800),
98
+ e.g. --viewport 390x844 for a mobile-width pass
99
99
  --no-config Do not apply project config, detector ignores, inline
100
100
  ignore comments, or DESIGN.md
101
101
  --no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
@@ -118,7 +118,8 @@ Inline ignores:
118
118
  Detection modes:
119
119
  HTML files Static HTML/CSS analysis (default, catches linked CSS)
120
120
  Non-HTML files Regex pattern matching (CSS, JSX, TSX, etc.)
121
- URLs Puppeteer full browser rendering (auto-detected)
121
+ URLs Puppeteer full browser rendering (auto-detected;
122
+ http(s):// and file:// URLs)
122
123
 
123
124
  Examples:
124
125
  impeccable detect src/
@@ -147,13 +148,15 @@ async function detectCli() {
147
148
  'Note: --fast is deprecated and ignored. The full scan is fast now and runs every rule.\n',
148
149
  );
149
150
  }
151
+ if (args.includes('--gpt') || args.includes('--gemini')) {
152
+ process.stderr.write(
153
+ 'Note: --gpt and --gemini are deprecated and ignored. Generated-UI tells now run by default.\n',
154
+ );
155
+ }
150
156
  const configEnabled = !args.includes('--no-config');
151
157
  const detectionConfig = configEnabled
152
158
  ? readDetectionConfig(process.cwd())
153
159
  : { ignoreRules: [], ignoreFiles: [], ignoreValues: [] };
154
- const providers = [];
155
- if (args.includes('--gpt')) providers.push('gpt');
156
- if (args.includes('--gemini')) providers.push('gemini');
157
160
  const scopes = [];
158
161
  for (let i = 0; i < args.length; i++) {
159
162
  if (args[i] !== '--scope' && !args[i].startsWith('--scope=')) continue;
@@ -174,6 +177,20 @@ async function detectCli() {
174
177
  args.splice(i, inline ? 1 : 2);
175
178
  i -= 1;
176
179
  }
180
+ let viewport = null;
181
+ for (let i = 0; i < args.length; i++) {
182
+ if (args[i] !== '--viewport' && !args[i].startsWith('--viewport=')) continue;
183
+ const inline = args[i].startsWith('--viewport=');
184
+ const value = inline ? args[i].slice('--viewport='.length) : args[i + 1];
185
+ const match = /^(\d{2,5})x(\d{2,5})$/i.exec(value || '');
186
+ if (!match) {
187
+ process.stderr.write('Error: --viewport requires a WxH value, e.g. --viewport 390x844\n');
188
+ process.exit(1);
189
+ }
190
+ viewport = { width: Number(match[1]), height: Number(match[2]) };
191
+ args.splice(i, inline ? 1 : 2);
192
+ i -= 1;
193
+ }
177
194
  const unknownScopes = scopes.filter(s => !RULE_SCOPES.has(s));
178
195
  if (unknownScopes.length > 0) {
179
196
  process.stderr.write(
@@ -187,8 +204,9 @@ async function detectCli() {
187
204
  // apply by default. `--no-config` (raw scan) and the dedicated
188
205
  // `--no-inline-ignores` both turn them off.
189
206
  const inlineIgnoresEnabled = configEnabled && !args.includes('--no-inline-ignores');
190
- const scanOptions = { providers, inlineIgnores: inlineIgnoresEnabled };
207
+ const scanOptions = { inlineIgnores: inlineIgnoresEnabled };
191
208
  if (designSystem) scanOptions.designSystem = designSystem;
209
+ if (viewport) scanOptions.viewport = viewport;
192
210
  const targets = args.filter(a => !a.startsWith('--'));
193
211
 
194
212
  if (helpMode) { printUsage(); process.exit(0); }
@@ -199,12 +217,17 @@ async function detectCli() {
199
217
  allFindings = await handleStdin(scanOptions);
200
218
  } else {
201
219
  const paths = targets.length > 0 ? targets : [process.cwd()];
202
- const urlTargetCount = paths.filter(target => /^https?:\/\//i.test(target)).length;
220
+ // file:// URLs get the same Puppeteer-rendered pass as http(s) — the
221
+ // real cascade, real computed styles, real layout. Callers that want a
222
+ // browser-grade scan of a local artifact can pass file:///abs/path.html
223
+ // instead of the bare path (which stays on the static engine).
224
+ const urlRe = /^(?:https?|file):\/\//i;
225
+ const urlTargetCount = paths.filter(target => urlRe.test(target)).length;
203
226
  const browserDetector = urlTargetCount > 1 ? await createBrowserDetector() : null;
204
227
 
205
228
  try {
206
229
  for (const target of paths) {
207
- if (/^https?:\/\//i.test(target)) {
230
+ if (urlRe.test(target)) {
208
231
  try {
209
232
  const scanner = browserDetector
210
233
  ? (url) => browserDetector.detectUrl(url, scanOptions)