viewprobe 0.0.0-stage → 0.2.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/LICENSE +21 -0
- package/README.md +248 -2
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +87 -0
- package/dist/cli.js.map +1 -0
- package/dist/cropper.d.ts +18 -0
- package/dist/cropper.d.ts.map +1 -0
- package/dist/cropper.js +53 -0
- package/dist/cropper.js.map +1 -0
- package/dist/engine.d.ts +10 -0
- package/dist/engine.d.ts.map +1 -0
- package/dist/engine.js +186 -0
- package/dist/engine.js.map +1 -0
- package/dist/formatter.d.ts +15 -0
- package/dist/formatter.d.ts.map +1 -0
- package/dist/formatter.js +95 -0
- package/dist/formatter.js.map +1 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +4 -0
- package/dist/index.js.map +1 -0
- package/dist/injector.d.ts +9 -0
- package/dist/injector.d.ts.map +1 -0
- package/dist/injector.js +165 -0
- package/dist/injector.js.map +1 -0
- package/dist/mcp-server.d.ts +13 -0
- package/dist/mcp-server.d.ts.map +1 -0
- package/dist/mcp-server.js +172 -0
- package/dist/mcp-server.js.map +1 -0
- package/dist/remediator.d.ts +15 -0
- package/dist/remediator.d.ts.map +1 -0
- package/dist/remediator.js +77 -0
- package/dist/remediator.js.map +1 -0
- package/dist/scanner.d.ts +27 -0
- package/dist/scanner.d.ts.map +1 -0
- package/dist/scanner.js +184 -0
- package/dist/scanner.js.map +1 -0
- package/dist/types.d.ts +58 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +13 -0
- package/dist/types.js.map +1 -0
- package/package.json +51 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Umang Kumar
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,249 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src=".github/assets/viewprobe-icon.jpg" width="100" height="100" style="border-radius: 20px" alt="ViewProbe Logo" />
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
<h1 align="center">ViewProbe</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<b>Headless layout verification engine & autonomous CSS healing for AI coding agents.</b>
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="https://glama.ai/mcp/servers/Umang-sudo-su/ViewProbe"><img src="https://glama.ai/mcp/servers/Umang-sudo-su/ViewProbe/badges/score.svg" alt="Glama Score" /></a>
|
|
13
|
+
<a href="https://www.npmjs.com/package/viewprobe"><img src="https://img.shields.io/npm/v/viewprobe?color=cb3837&logo=npm" alt="npm version" /></a>
|
|
14
|
+
<a href="https://github.com/Umang-sudo-su/ViewProbe/actions/workflows/ci.yml"><img src="https://github.com/Umang-sudo-su/ViewProbe/actions/workflows/ci.yml/badge.svg" alt="CI Status" /></a>
|
|
15
|
+
<a href="https://github.com/Umang-sudo-su/ViewProbe/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
|
|
16
|
+
</p>
|
|
17
|
+
|
|
18
|
+
<p align="center">
|
|
19
|
+
🎬 <b><a href="https://github.com/Umang-sudo-su/ViewProbe/raw/main/.github/assets/videos/viewprobe-demo.webm">Watch 15-second autonomous self-healing demo (HD WebM)</a></b>
|
|
20
|
+
</p>
|
|
21
|
+
|
|
22
|
+
ViewProbe gives coding agents a fast, deterministic way to catch CSS and layout bugs — horizontal overflow, broken responsive layouts, truncated text, undersized tap targets — without relying on expensive vision models or manual human review.
|
|
23
|
+
|
|
24
|
+
It runs headless Chromium, performs geometric analysis on the rendered DOM, and returns compact, structured diagnostics that an LLM can parse in a single turn. When something breaks, it tells the agent *exactly which element* and *which CSS properties* caused the problem, along with an optional micro-crop screenshot of just the broken region.
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 🚀 1-Click Agent Setup
|
|
29
|
+
|
|
30
|
+
### Claude Code (CLI)
|
|
31
|
+
```bash
|
|
32
|
+
claude mcp add viewprobe npx -y viewprobe-mcp
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### Cursor
|
|
36
|
+
Add directly in **Settings (`Cmd + ,`) → Features → MCP → + Add New MCP Server**:
|
|
37
|
+
* **Name**: `viewprobe`
|
|
38
|
+
* **Type**: `command`
|
|
39
|
+
* **Command**: `npx -y viewprobe-mcp`
|
|
40
|
+
|
|
41
|
+
### Claude Desktop
|
|
42
|
+
Add to `claude_desktop_config.json`:
|
|
43
|
+
```json
|
|
44
|
+
{
|
|
45
|
+
"mcpServers": {
|
|
46
|
+
"viewprobe": {
|
|
47
|
+
"command": "npx",
|
|
48
|
+
"args": ["-y", "viewprobe-mcp"]
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Why
|
|
57
|
+
|
|
58
|
+
AI coding agents (Cursor, Claude Code, Cline, Aider, etc.) are surprisingly good at writing logic but consistently bad at CSS. They produce layouts that overflow on mobile, text that clips without ellipsis, and buttons too small to tap. The human developer ends up as a visual QA layer, manually checking every UI change.
|
|
59
|
+
|
|
60
|
+
ViewProbe closes that feedback loop. The agent writes the code, ViewProbe checks the layout across viewports in under a second, and if something breaks, the agent gets back the exact selector and computed styles needed to fix it — no guessing, no print-statement debugging.
|
|
61
|
+
|
|
62
|
+
## Visual Verification in Action
|
|
63
|
+
|
|
64
|
+
### Autonomous Self-Healing on Mobile Viewports
|
|
65
|
+
|
|
66
|
+
When an agent introduces a CSS defect (such as a rigid `min-width` that overflows on mobile, or text clipping without ellipsis), ViewProbe identifies the exact culprit and verifies the fix:
|
|
67
|
+
|
|
68
|
+
| Before Fix (Broken Layout) | After Fix (Self-Healed) |
|
|
69
|
+
| :---: | :---: |
|
|
70
|
+
| <img src=".github/assets/before-fix.png" width="340" alt="Mobile layout before fix: card overflows viewport by 23px" /> | <img src=".github/assets/after-fix.png" width="340" alt="Mobile layout after fix: responsive fluid bounds" /> |
|
|
71
|
+
| ❌ *Card overflows 375px screen by 23px, text clipped, 22px button* | ✅ *Fluid responsive bounds, clean ellipsis, 44px accessible touch target* |
|
|
72
|
+
|
|
73
|
+
## How ViewProbe Compares
|
|
74
|
+
|
|
75
|
+
Most developers currently try to verify agent UI changes using raw browser screenshots, DOM dumps, or visual regression dashboards. Here is why those approaches fail autonomous coding agents:
|
|
76
|
+
|
|
77
|
+
| Feature / Approach | Full Screenshots (`page.screenshot`) | Raw DOM / HTML Dumps | Visual Regression (Percy / Chromatic) | **ViewProbe** |
|
|
78
|
+
| :--- | :---: | :---: | :---: | :---: |
|
|
79
|
+
| **Token Cost per Turn** | ~1,500 – 3,000 vision tokens | 20,000+ text tokens | N/A (Web UI only) | **~80 tokens** (micro-crop + JSON) |
|
|
80
|
+
| **Identifies CSS Culprit** | ❌ No (Agent must guess) | ❌ No (Markup only) | ❌ No (Pixel diff only) | ✅ **Yes** (Exact computed style & selector) |
|
|
81
|
+
| **Deterministic Math** | ❌ No (Probabilistic vision) | ❌ No (No geometry data) | ⚠️ Partial (Pixel threshold) | ✅ **Yes** (DOM geometry & viewport math) |
|
|
82
|
+
| **Autonomous Agent Loop** | ⚠️ High latency & cost | ❌ Context window blowup | ❌ Human review required | ✅ **Native MCP & CLI tool-calling** |
|
|
83
|
+
| **Execution Environment** | ✅ Local | ✅ Local | ❌ Paid Cloud / SaaS | ✅ **100% Local & Free** |
|
|
84
|
+
|
|
85
|
+
### Why Existing Approaches Fall Short:
|
|
86
|
+
|
|
87
|
+
* **vs. Raw Full Screenshots (`page.screenshot()`)**: Full-screen vision prompts burn 1,500+ tokens per viewport turn. Furthermore, vision models are probabilistic—they frequently hallucinate alignment, miss 15px mobile overflows, and cannot tell the agent *which* CSS rule (`min-width: 420px;`) caused the problem.
|
|
88
|
+
* **vs. Raw DOM / Accessibility Tree Dumps**: Dumping 50,000 characters of HTML into an LLM context wastes tokens on unchanged markup and completely ignores the rendered layout, CSS cascade, media queries, and flexbox wrapping.
|
|
89
|
+
* **vs. Traditional Visual Regression (Percy, Chromatic)**: Designed for human reviewers to click "Approve / Reject" on pixel diffs in a web dashboard. They don't output machine-readable remediation diagnostics for LLM tool-calling.
|
|
90
|
+
* **vs. Accessibility Linters (axe-core, Lighthouse)**: A11y linters check semantic HTML, ARIA roles, and contrast, but are completely blind to responsive layout breakage, clipped text, and broken flex containers.
|
|
91
|
+
|
|
92
|
+
## Quick Start
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
# install
|
|
96
|
+
npm install -g viewprobe
|
|
97
|
+
|
|
98
|
+
# scan a running page across mobile and desktop
|
|
99
|
+
viewprobe check http://localhost:3000
|
|
100
|
+
|
|
101
|
+
# scan a local HTML file directly without a server
|
|
102
|
+
viewprobe check ./dist/index.html -v mobile,desktop
|
|
103
|
+
|
|
104
|
+
# scan raw HTML markup in-memory
|
|
105
|
+
viewprobe check --html "<div style='width:600px;'>test</div>" -v mobile
|
|
106
|
+
|
|
107
|
+
# scan specific viewports
|
|
108
|
+
viewprobe check http://localhost:3000 -v mobile,tablet,desktop
|
|
109
|
+
|
|
110
|
+
# get markdown report with suggested fixes
|
|
111
|
+
viewprobe check http://localhost:3000 -f markdown
|
|
112
|
+
|
|
113
|
+
# focus on specific elements
|
|
114
|
+
viewprobe check http://localhost:3000 -s ".hero,.pricing-grid"
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## What It Catches & Heals
|
|
118
|
+
|
|
119
|
+
| Check | Severity | Description | Autonomous Suggested Fix |
|
|
120
|
+
|-------|----------|-------------|--------------------------|
|
|
121
|
+
| **Horizontal Overflow** | error | Elements wider than container or viewport | Provides fluid `max-width: 100%` and Tailwind `max-w-full shrink` patches |
|
|
122
|
+
| **Text Truncation** | warning | Text clipped without `text-overflow: ellipsis` | Generates CSS `ellipsis` + `nowrap` or Tailwind `truncate` |
|
|
123
|
+
| **Tap Target Sizing** | warning | Interactive elements smaller than 44×44px (WCAG 2.5.8) | Adds accessible padding and `min-w-[44px] min-h-[44px]` bounds |
|
|
124
|
+
| **Body Scroll** | error | Viewport-level horizontal scroll caused by breakout elements | Generates root containment (`overflow-x: hidden`) patches |
|
|
125
|
+
|
|
126
|
+
## Output Formats
|
|
127
|
+
|
|
128
|
+
### Agent format (default)
|
|
129
|
+
|
|
130
|
+
Compact JSON designed for LLM consumption, complete with actionable suggested patches:
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
{
|
|
134
|
+
"status": "FAIL",
|
|
135
|
+
"url": "http://localhost:3000",
|
|
136
|
+
"duration": "340ms",
|
|
137
|
+
"summary": "Found 1 error across 1 viewport.",
|
|
138
|
+
"violations": [
|
|
139
|
+
{
|
|
140
|
+
"type": "HORIZONTAL_OVERFLOW",
|
|
141
|
+
"severity": "error",
|
|
142
|
+
"viewport": "mobile",
|
|
143
|
+
"message": "Element extends 24px beyond viewport edge",
|
|
144
|
+
"selector": "div.pricing-grid > div:nth-child(2) > button",
|
|
145
|
+
"culpritStyles": [
|
|
146
|
+
"min-width: 400px",
|
|
147
|
+
"flex-shrink: 0"
|
|
148
|
+
],
|
|
149
|
+
"suggestedFix": {
|
|
150
|
+
"css": "max-width: 100%; min-width: 0; flex-shrink: 1;",
|
|
151
|
+
"tailwind": "max-w-full min-w-0 shrink",
|
|
152
|
+
"explanation": "Relax rigid min-width and allow element to shrink within parent container bounds."
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
]
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### Markdown format
|
|
160
|
+
|
|
161
|
+
Human-readable report with severity badges, bounding box data, and computed style blocks. Good for PR comments or documentation.
|
|
162
|
+
|
|
163
|
+
### One-liner format
|
|
164
|
+
|
|
165
|
+
Single line for CI pipelines: `FAIL: 1 layout error(s) — Element extends 24px beyond viewport edge`
|
|
166
|
+
|
|
167
|
+
## MCP Server
|
|
168
|
+
|
|
169
|
+
ViewProbe ships as an MCP server so any MCP-compatible agent can use it as a tool:
|
|
170
|
+
|
|
171
|
+
```json
|
|
172
|
+
{
|
|
173
|
+
"mcpServers": {
|
|
174
|
+
"viewprobe": {
|
|
175
|
+
"command": "npx",
|
|
176
|
+
"args": ["-y", "viewprobe-mcp"]
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Or when running from a local clone:
|
|
183
|
+
```json
|
|
184
|
+
{
|
|
185
|
+
"mcpServers": {
|
|
186
|
+
"viewprobe": {
|
|
187
|
+
"command": "node",
|
|
188
|
+
"args": ["/absolute/path/to/ViewProbe/dist/mcp-server.js"]
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
### Tools
|
|
195
|
+
|
|
196
|
+
**`viewprobe_check`** — Scan a URL, local file, or raw HTML for layout violations.
|
|
197
|
+
|
|
198
|
+
| Parameter | Type | Required | Description |
|
|
199
|
+
|-----------|------|----------|-------------|
|
|
200
|
+
| `url` | string | no* | URL or local file path to scan (*required unless `html` is provided) |
|
|
201
|
+
| `html` | string | no* | Raw HTML string to scan in-memory without a server |
|
|
202
|
+
| `viewports` | string | no | Comma-separated: mobile, tablet, desktop, wide |
|
|
203
|
+
| `selectors` | string | no | CSS selectors to focus on |
|
|
204
|
+
| `skipSelectors` | string | no | CSS selectors to skip |
|
|
205
|
+
| `microCrops` | boolean | no | Attach cropped violation screenshots (default: true) |
|
|
206
|
+
|
|
207
|
+
**`viewprobe_viewports`** — List available viewport presets with dimensions.
|
|
208
|
+
|
|
209
|
+
## Micro-Crops (~80 tokens vs ~1,500 tokens)
|
|
210
|
+
|
|
211
|
+
Instead of sending a full-page screenshot (1,500+ vision tokens), ViewProbe computes the exact screen-space bounding box of the violation, highlights it with a red debug border, and crops only that region (~80 tokens):
|
|
212
|
+
|
|
213
|
+
<p align="center">
|
|
214
|
+
<img src=".github/assets/micro-crop-overflow.jpg" width="460" alt="ViewProbe Micro-Crop with Red Highlight Box" />
|
|
215
|
+
</p>
|
|
216
|
+
|
|
217
|
+
You can disable micro-crops with `--no-crops` or `microCrops: false` in the MCP call.
|
|
218
|
+
|
|
219
|
+
## Programmatic API
|
|
220
|
+
|
|
221
|
+
```typescript
|
|
222
|
+
import { ProbeEngine, formatForAgent } from "viewprobe";
|
|
223
|
+
|
|
224
|
+
const engine = new ProbeEngine();
|
|
225
|
+
const result = await engine.probe({
|
|
226
|
+
url: "http://localhost:3000",
|
|
227
|
+
viewports: [
|
|
228
|
+
{ name: "mobile", width: 375, height: 812 },
|
|
229
|
+
{ name: "desktop", width: 1280, height: 900 },
|
|
230
|
+
],
|
|
231
|
+
});
|
|
232
|
+
|
|
233
|
+
console.log(formatForAgent(result));
|
|
234
|
+
await engine.close();
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
## Development
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
git clone https://github.com/Umang-sudo-su/ViewProbe.git
|
|
241
|
+
cd ViewProbe
|
|
242
|
+
npm install
|
|
243
|
+
npm run build
|
|
244
|
+
npm test
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
## License
|
|
248
|
+
|
|
249
|
+
MIT
|
package/dist/cli.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
|
package/dist/cli.js
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { Command } from "commander";
|
|
3
|
+
import chalk from "chalk";
|
|
4
|
+
import { ProbeEngine } from "./engine.js";
|
|
5
|
+
import { formatForAgent, formatAsMarkdown, formatAsOneLiner } from "./formatter.js";
|
|
6
|
+
import { DEFAULT_VIEWPORTS } from "./types.js";
|
|
7
|
+
const program = new Command();
|
|
8
|
+
program
|
|
9
|
+
.name("viewprobe")
|
|
10
|
+
.description("Headless layout verification for AI coding agents")
|
|
11
|
+
.version("0.1.0");
|
|
12
|
+
program
|
|
13
|
+
.command("check")
|
|
14
|
+
.description("Scan a URL, local HTML file, or raw HTML string for layout violations")
|
|
15
|
+
.argument("[target]", "URL or local HTML file path to scan (e.g. http://localhost:3000, ./index.html)")
|
|
16
|
+
.option("--html <html>", "Raw HTML string to scan directly in-memory without a server")
|
|
17
|
+
.option("-v, --viewports <viewports>", "Comma-separated viewport names: mobile,tablet,desktop,wide", "mobile,desktop")
|
|
18
|
+
.option("-f, --format <format>", "Output format: agent, markdown, oneline", "agent")
|
|
19
|
+
.option("-s, --selectors <selectors>", "Comma-separated CSS selectors to focus on")
|
|
20
|
+
.option("--skip <selectors>", "Comma-separated CSS selectors to skip")
|
|
21
|
+
.option("--no-crops", "Disable micro-crop screenshots")
|
|
22
|
+
.option("--timeout <ms>", "Page load timeout in milliseconds", "10000")
|
|
23
|
+
.option("--wait-for <selector>", "Wait for this selector before scanning")
|
|
24
|
+
.action(async (target, opts) => {
|
|
25
|
+
if (!target && !opts.html) {
|
|
26
|
+
console.error(chalk.red("Error: Must provide a target URL/file path or --html string."));
|
|
27
|
+
console.error("Usage: viewprobe check <url|file> [options] OR viewprobe check --html '<div>...'");
|
|
28
|
+
process.exit(1);
|
|
29
|
+
}
|
|
30
|
+
const viewportNames = opts.viewports.split(",").map((s) => s.trim());
|
|
31
|
+
const viewports = viewportNames
|
|
32
|
+
.map((name) => DEFAULT_VIEWPORTS.find((v) => v.name === name))
|
|
33
|
+
.filter(Boolean);
|
|
34
|
+
if (viewports.length === 0) {
|
|
35
|
+
console.error(chalk.red(`Unknown viewport names: ${opts.viewports}`));
|
|
36
|
+
console.error(`Available: ${DEFAULT_VIEWPORTS.map((v) => v.name).join(", ")}`);
|
|
37
|
+
process.exit(1);
|
|
38
|
+
}
|
|
39
|
+
const config = {
|
|
40
|
+
url: target,
|
|
41
|
+
html: opts.html,
|
|
42
|
+
viewports,
|
|
43
|
+
selectors: opts.selectors?.split(",").map((s) => s.trim()),
|
|
44
|
+
skipSelectors: opts.skip?.split(",").map((s) => s.trim()),
|
|
45
|
+
microCrops: opts.crops !== false,
|
|
46
|
+
timeout: parseInt(opts.timeout, 10),
|
|
47
|
+
waitForSelector: opts.waitFor,
|
|
48
|
+
};
|
|
49
|
+
const engine = new ProbeEngine();
|
|
50
|
+
try {
|
|
51
|
+
const scanLabel = opts.html ? "raw HTML in-memory" : target;
|
|
52
|
+
console.error(chalk.dim(`Scanning ${scanLabel} across ${viewports.map((v) => v.name).join(", ")}...`));
|
|
53
|
+
const result = await engine.probe(config);
|
|
54
|
+
switch (opts.format) {
|
|
55
|
+
case "agent":
|
|
56
|
+
console.log(formatForAgent(result));
|
|
57
|
+
break;
|
|
58
|
+
case "markdown":
|
|
59
|
+
console.log(formatAsMarkdown(result));
|
|
60
|
+
break;
|
|
61
|
+
case "oneline":
|
|
62
|
+
console.log(formatAsOneLiner(result));
|
|
63
|
+
break;
|
|
64
|
+
default:
|
|
65
|
+
console.log(formatForAgent(result));
|
|
66
|
+
}
|
|
67
|
+
process.exit(result.passed ? 0 : 1);
|
|
68
|
+
}
|
|
69
|
+
catch (err) {
|
|
70
|
+
console.error(chalk.red(`Scan failed: ${err.message}`));
|
|
71
|
+
process.exit(2);
|
|
72
|
+
}
|
|
73
|
+
finally {
|
|
74
|
+
await engine.close();
|
|
75
|
+
}
|
|
76
|
+
});
|
|
77
|
+
program
|
|
78
|
+
.command("viewports")
|
|
79
|
+
.description("List available viewport presets")
|
|
80
|
+
.action(() => {
|
|
81
|
+
console.log(chalk.bold("Available viewports:\n"));
|
|
82
|
+
for (const vp of DEFAULT_VIEWPORTS) {
|
|
83
|
+
console.log(` ${chalk.cyan(vp.name.padEnd(10))} ${vp.width}\u00D7${vp.height}`);
|
|
84
|
+
}
|
|
85
|
+
});
|
|
86
|
+
program.parse();
|
|
87
|
+
//# sourceMappingURL=cli.js.map
|
package/dist/cli.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { Page } from "playwright";
|
|
2
|
+
import type { BoundingBox } from "./types.js";
|
|
3
|
+
interface CropOptions {
|
|
4
|
+
padding: number;
|
|
5
|
+
quality: number;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* Captures a small region around a violation bounding box and returns
|
|
9
|
+
* a base64-encoded JPEG. Uses Playwright's native clipping for fast,
|
|
10
|
+
* dependency-free cropping.
|
|
11
|
+
*/
|
|
12
|
+
export declare function cropViolation(page: Page, bounds: BoundingBox, options: CropOptions): Promise<string>;
|
|
13
|
+
/**
|
|
14
|
+
* Draws a red debug outline around a violation on the page.
|
|
15
|
+
*/
|
|
16
|
+
export declare function highlightViolation(page: Page, selector: string): Promise<void>;
|
|
17
|
+
export {};
|
|
18
|
+
//# sourceMappingURL=cropper.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cropper.d.ts","sourceRoot":"","sources":["../src/cropper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,UAAU,WAAW;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,CA+BjB;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAwBf"}
|
package/dist/cropper.js
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Captures a small region around a violation bounding box and returns
|
|
3
|
+
* a base64-encoded JPEG. Uses Playwright's native clipping for fast,
|
|
4
|
+
* dependency-free cropping.
|
|
5
|
+
*/
|
|
6
|
+
export async function cropViolation(page, bounds, options) {
|
|
7
|
+
const viewport = page.viewportSize();
|
|
8
|
+
if (!viewport) {
|
|
9
|
+
throw new Error("Page has no viewport set");
|
|
10
|
+
}
|
|
11
|
+
const pad = options.padding;
|
|
12
|
+
const clip = {
|
|
13
|
+
x: Math.max(0, bounds.x - pad),
|
|
14
|
+
y: Math.max(0, bounds.y - pad),
|
|
15
|
+
width: Math.min(bounds.width + pad * 2, viewport.width - Math.max(0, bounds.x - pad)),
|
|
16
|
+
height: Math.min(bounds.height + pad * 2, viewport.height - Math.max(0, bounds.y - pad)),
|
|
17
|
+
};
|
|
18
|
+
clip.width = Math.max(clip.width, 48);
|
|
19
|
+
clip.height = Math.max(clip.height, 48);
|
|
20
|
+
const buffer = await page.screenshot({
|
|
21
|
+
clip,
|
|
22
|
+
type: "jpeg",
|
|
23
|
+
quality: options.quality,
|
|
24
|
+
});
|
|
25
|
+
return buffer.toString("base64");
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Draws a red debug outline around a violation on the page.
|
|
29
|
+
*/
|
|
30
|
+
export async function highlightViolation(page, selector) {
|
|
31
|
+
await page.evaluate((sel) => {
|
|
32
|
+
const el = document.querySelector(sel);
|
|
33
|
+
if (!el)
|
|
34
|
+
return;
|
|
35
|
+
const overlay = document.createElement("div");
|
|
36
|
+
const rect = el.getBoundingClientRect();
|
|
37
|
+
Object.assign(overlay.style, {
|
|
38
|
+
position: "fixed",
|
|
39
|
+
top: `${rect.y}px`,
|
|
40
|
+
left: `${rect.x}px`,
|
|
41
|
+
width: `${rect.width}px`,
|
|
42
|
+
height: `${rect.height}px`,
|
|
43
|
+
border: "3px solid #ff2d55",
|
|
44
|
+
borderRadius: "2px",
|
|
45
|
+
pointerEvents: "none",
|
|
46
|
+
zIndex: "999999",
|
|
47
|
+
boxShadow: "0 0 8px rgba(255, 45, 85, 0.5)",
|
|
48
|
+
});
|
|
49
|
+
overlay.setAttribute("data-viewprobe-highlight", "true");
|
|
50
|
+
document.body.appendChild(overlay);
|
|
51
|
+
}, selector);
|
|
52
|
+
}
|
|
53
|
+
//# sourceMappingURL=cropper.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cropper.js","sourceRoot":"","sources":["../src/cropper.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAU,EACV,MAAmB,EACnB,OAAoB;IAEpB,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;IACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;IAE5B,MAAM,IAAI,GAAG;QACX,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC;QAC9B,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC;QAC9B,KAAK,EAAE,IAAI,CAAC,GAAG,CACb,MAAM,CAAC,KAAK,GAAG,GAAG,GAAG,CAAC,EACtB,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC,CAC7C;QACD,MAAM,EAAE,IAAI,CAAC,GAAG,CACd,MAAM,CAAC,MAAM,GAAG,GAAG,GAAG,CAAC,EACvB,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC,CAC9C;KACF,CAAC;IAEF,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAExC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC;QACnC,IAAI;QACJ,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAU,EACV,QAAgB;IAEhB,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAW,EAAE,EAAE;QAClC,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,EAAE;YAAE,OAAO;QAEhB,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC9C,MAAM,IAAI,GAAG,EAAE,CAAC,qBAAqB,EAAE,CAAC;QAExC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE;YAC3B,QAAQ,EAAE,OAAO;YACjB,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI;YAClB,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI;YACnB,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI;YACxB,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,IAAI;YAC1B,MAAM,EAAE,mBAAmB;YAC3B,YAAY,EAAE,KAAK;YACnB,aAAa,EAAE,MAAM;YACrB,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,gCAAgC;SAC5C,CAAC,CAAC;QAEH,OAAO,CAAC,YAAY,CAAC,0BAA0B,EAAE,MAAM,CAAC,CAAC;QACzD,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC,EAAE,QAAQ,CAAC,CAAC;AACf,CAAC"}
|
package/dist/engine.d.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { type ProbeConfig, type ProbeResult } from "./types.js";
|
|
2
|
+
export declare class ProbeEngine {
|
|
3
|
+
private browser;
|
|
4
|
+
launch(): Promise<void>;
|
|
5
|
+
close(): Promise<void>;
|
|
6
|
+
probe(config: ProbeConfig): Promise<ProbeResult>;
|
|
7
|
+
private scanViewport;
|
|
8
|
+
private deduplicateViolations;
|
|
9
|
+
}
|
|
10
|
+
//# sourceMappingURL=engine.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,WAAW,EAKjB,MAAM,YAAY,CAAC;AAuBpB,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAwB;IAEjC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;YA8CxC,YAAY;IA6F1B,OAAO,CAAC,qBAAqB;CAW9B"}
|
package/dist/engine.js
ADDED
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
import fs from "fs";
|
|
2
|
+
import path from "path";
|
|
3
|
+
import { pathToFileURL } from "url";
|
|
4
|
+
import { chromium } from "playwright";
|
|
5
|
+
import { cropViolation, highlightViolation } from "./cropper.js";
|
|
6
|
+
import { generateSuggestedFix } from "./remediator.js";
|
|
7
|
+
import { DEFAULT_VIEWPORTS, DEFAULT_CONFIG, } from "./types.js";
|
|
8
|
+
import { getScannerSource } from "./injector.js";
|
|
9
|
+
function resolveTargetUrl(config) {
|
|
10
|
+
if (config.filePath) {
|
|
11
|
+
return pathToFileURL(path.resolve(config.filePath)).href;
|
|
12
|
+
}
|
|
13
|
+
const raw = config.url ?? "";
|
|
14
|
+
if (raw.startsWith("http://") || raw.startsWith("https://") || raw.startsWith("file://")) {
|
|
15
|
+
return raw;
|
|
16
|
+
}
|
|
17
|
+
if (fs.existsSync(raw) ||
|
|
18
|
+
raw.startsWith("./") ||
|
|
19
|
+
raw.startsWith("../") ||
|
|
20
|
+
raw.startsWith("/") ||
|
|
21
|
+
raw.endsWith(".html")) {
|
|
22
|
+
return pathToFileURL(path.resolve(raw)).href;
|
|
23
|
+
}
|
|
24
|
+
return raw;
|
|
25
|
+
}
|
|
26
|
+
export class ProbeEngine {
|
|
27
|
+
browser = null;
|
|
28
|
+
async launch() {
|
|
29
|
+
try {
|
|
30
|
+
this.browser = await chromium.launch({ headless: true });
|
|
31
|
+
}
|
|
32
|
+
catch (err) {
|
|
33
|
+
const msg = err?.message ?? "";
|
|
34
|
+
if (msg.includes("Executable doesn't exist") ||
|
|
35
|
+
msg.includes("looks like Playwright was just installed")) {
|
|
36
|
+
try {
|
|
37
|
+
this.browser = await chromium.launch({
|
|
38
|
+
channel: "chrome",
|
|
39
|
+
headless: true,
|
|
40
|
+
});
|
|
41
|
+
return;
|
|
42
|
+
}
|
|
43
|
+
catch {
|
|
44
|
+
throw new Error("Chromium browser not found. Please install Playwright browsers with:\n npx playwright install chromium");
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
throw err;
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
async close() {
|
|
51
|
+
if (this.browser) {
|
|
52
|
+
await this.browser.close();
|
|
53
|
+
this.browser = null;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
async probe(config) {
|
|
57
|
+
if (!this.browser) {
|
|
58
|
+
await this.launch();
|
|
59
|
+
}
|
|
60
|
+
const mergedConfig = { ...DEFAULT_CONFIG, ...config };
|
|
61
|
+
const viewports = mergedConfig.viewports ?? DEFAULT_VIEWPORTS;
|
|
62
|
+
const allViolations = [];
|
|
63
|
+
const startTime = Date.now();
|
|
64
|
+
for (const viewport of viewports) {
|
|
65
|
+
const violations = await this.scanViewport(mergedConfig, viewport);
|
|
66
|
+
allViolations.push(...violations);
|
|
67
|
+
}
|
|
68
|
+
const duration = Date.now() - startTime;
|
|
69
|
+
const deduped = this.deduplicateViolations(allViolations);
|
|
70
|
+
const passed = deduped.filter((v) => v.severity === "error").length === 0;
|
|
71
|
+
const errorCount = deduped.filter((v) => v.severity === "error").length;
|
|
72
|
+
const warnCount = deduped.filter((v) => v.severity === "warning").length;
|
|
73
|
+
let summary;
|
|
74
|
+
if (passed && warnCount === 0) {
|
|
75
|
+
summary = `All clean \u2014 no layout issues found across ${viewports.length} viewport${viewports.length > 1 ? "s" : ""}.`;
|
|
76
|
+
}
|
|
77
|
+
else if (passed) {
|
|
78
|
+
summary = `Passed with ${warnCount} warning${warnCount > 1 ? "s" : ""}. No blocking layout errors.`;
|
|
79
|
+
}
|
|
80
|
+
else {
|
|
81
|
+
summary = `Found ${errorCount} error${errorCount > 1 ? "s" : ""} and ${warnCount} warning${warnCount > 1 ? "s" : ""} across ${viewports.length} viewport${viewports.length > 1 ? "s" : ""}.`;
|
|
82
|
+
}
|
|
83
|
+
const targetLabel = config.html
|
|
84
|
+
? "raw:html"
|
|
85
|
+
: config.filePath ?? config.url ?? "unknown";
|
|
86
|
+
return {
|
|
87
|
+
url: targetLabel,
|
|
88
|
+
timestamp: new Date().toISOString(),
|
|
89
|
+
duration,
|
|
90
|
+
viewportsChecked: viewports,
|
|
91
|
+
violations: deduped,
|
|
92
|
+
passed,
|
|
93
|
+
summary,
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
async scanViewport(config, viewport) {
|
|
97
|
+
const page = await this.browser.newPage({
|
|
98
|
+
viewport: { width: viewport.width, height: viewport.height },
|
|
99
|
+
});
|
|
100
|
+
try {
|
|
101
|
+
// Inject the scanner function before navigation
|
|
102
|
+
const scannerSrc = getScannerSource();
|
|
103
|
+
await page.addInitScript({ content: scannerSrc });
|
|
104
|
+
if (config.html) {
|
|
105
|
+
await page.setContent(config.html, {
|
|
106
|
+
waitUntil: "networkidle",
|
|
107
|
+
timeout: config.timeout,
|
|
108
|
+
});
|
|
109
|
+
await page.addScriptTag({ content: scannerSrc });
|
|
110
|
+
}
|
|
111
|
+
else {
|
|
112
|
+
const targetUrl = resolveTargetUrl(config);
|
|
113
|
+
if (!targetUrl) {
|
|
114
|
+
throw new Error("Must provide a target url, filePath, or raw html string.");
|
|
115
|
+
}
|
|
116
|
+
await page.goto(targetUrl, {
|
|
117
|
+
waitUntil: "networkidle",
|
|
118
|
+
timeout: config.timeout,
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
// Ensure the scanner function is available in the page execution context
|
|
122
|
+
const isScannerLoaded = await page.evaluate(() => typeof window.__viewprobe_scan === "function");
|
|
123
|
+
if (!isScannerLoaded) {
|
|
124
|
+
await page.addScriptTag({ content: scannerSrc });
|
|
125
|
+
}
|
|
126
|
+
if (config.waitForSelector) {
|
|
127
|
+
await page.waitForSelector(config.waitForSelector, {
|
|
128
|
+
timeout: config.timeout,
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
const rawViolations = await page.evaluate((opts) => {
|
|
132
|
+
return window.__viewprobe_scan(opts);
|
|
133
|
+
}, {
|
|
134
|
+
skipSelectors: config.skipSelectors,
|
|
135
|
+
targetSelectors: config.selectors,
|
|
136
|
+
});
|
|
137
|
+
const violations = [];
|
|
138
|
+
for (const raw of rawViolations) {
|
|
139
|
+
const violation = {
|
|
140
|
+
type: raw.type,
|
|
141
|
+
severity: raw.severity,
|
|
142
|
+
viewport,
|
|
143
|
+
message: raw.message,
|
|
144
|
+
selector: raw.selector,
|
|
145
|
+
bounds: raw.bounds,
|
|
146
|
+
culpritStyles: raw.styles,
|
|
147
|
+
suggestedFix: generateSuggestedFix({
|
|
148
|
+
type: raw.type,
|
|
149
|
+
selector: raw.selector,
|
|
150
|
+
bounds: raw.bounds,
|
|
151
|
+
culpritStyles: raw.styles,
|
|
152
|
+
message: raw.message,
|
|
153
|
+
}),
|
|
154
|
+
};
|
|
155
|
+
if (config.microCrops) {
|
|
156
|
+
try {
|
|
157
|
+
await highlightViolation(page, raw.selector);
|
|
158
|
+
violation.microCrop = await cropViolation(page, raw.bounds, {
|
|
159
|
+
padding: config.cropPadding ?? 20,
|
|
160
|
+
quality: config.cropQuality ?? 60,
|
|
161
|
+
});
|
|
162
|
+
}
|
|
163
|
+
catch {
|
|
164
|
+
// cropping is best-effort
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
violations.push(violation);
|
|
168
|
+
}
|
|
169
|
+
return violations;
|
|
170
|
+
}
|
|
171
|
+
finally {
|
|
172
|
+
await page.close();
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
deduplicateViolations(violations) {
|
|
176
|
+
const seen = new Set();
|
|
177
|
+
return violations.filter((v) => {
|
|
178
|
+
const key = `${v.type}::${v.selector}::${v.viewport.name}`;
|
|
179
|
+
if (seen.has(key))
|
|
180
|
+
return false;
|
|
181
|
+
seen.add(key);
|
|
182
|
+
return true;
|
|
183
|
+
});
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
//# sourceMappingURL=engine.js.map
|