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 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
- # Temporary Holding Version
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
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=cli.d.ts.map
@@ -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
@@ -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"}
@@ -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"}
@@ -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