@nyx-intelligence/val-mcp 0.3.0 → 0.4.0

package/README.md

@@ -9,7 +9,9 @@ does the reasoning and the fixing on your own key.
 ## What it catches
 
 Passive (crawl): broken links & 404s, uncaught JS errors, console errors,
-failed network requests (4xx/5xx), broken images, missing `<title>`.
+failed network requests (4xx/5xx), broken images, missing `<title>`,
+horizontal layout overflow, clipped text, and janky load (layout shift / CLS).
+Pass a `device` (e.g. `iPhone 14`, `Pixel 7`) to test the **mobile** rendering.
 
 Interactive (the agent drives the browser): **dead buttons** (clicks every
 button, flags the ones with no effect or that throw) and **broken funnels**

package/dist/index.js

@@ -23,13 +23,13 @@ function fmtSnapshot(els) {
 }
 // ───────────────────────── CLI (testing without an MCP client) ─────────────────────────
 async function runCli(args) {
-    const [cmd, url, arg2] = args;
+    const [cmd, url, arg2, arg3] = args;
     if (cmd === "scan" && url) {
-        const { findings, pagesVisited } = await scanSite(url, { maxPages: Number(arg2) || 12 });
+        const { findings, pagesVisited } = await scanSite(url, { maxPages: Number(arg2) || 12, device: arg3 || undefined });
         console.log(formatReport(findings, pagesVisited));
     }
     else if (cmd === "exercise" && url) {
-        console.log(fmtAction(await session.open(url)));
+        console.log(fmtAction(await session.open(url, arg2 || undefined)));
         const res = await session.exercise();
         console.log(`\nexercised ${res.tested} button(s): ${res.dead.length} dead, ${res.errored.length} errored`);
         for (const d of res.dead)
@@ -39,7 +39,7 @@ async function runCli(args) {
         await session.close();
     }
     else {
-        console.error("Usage:\n  val-mcp scan <url> [maxPages]\n  val-mcp exercise <url>\n  val-mcp            (start MCP server on stdio)");
+        console.error("Usage:\n  val-mcp scan <url> [maxPages] [device]\n  val-mcp exercise <url> [device]\n  val-mcp            (start MCP server on stdio)");
         process.exit(1);
     }
     process.exit(0);
@@ -66,25 +66,25 @@ async function runServer() {
     const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
     const { chromium } = await import("playwright");
     const { z } = await import("zod");
-    const server = new McpServer({ name: "val", version: "0.3.0" });
+    const server = new McpServer({ name: "val", version: "0.4.0" });
     const text = (t) => ({ content: [{ type: "text", text: t }] });
     // ── Passive crawl ──
     server.registerTool("val_scan", {
         title: "Scan an app for UX bugs (crawl)",
-        description: "Crawl an app (localhost or live), following same-origin links, and report passive bugs: broken links/404s, uncaught JS errors, console errors, failed network requests, broken images, missing titles. Good first pass. Does NOT click buttons or fill forms — use the val_open/val_click/val_type/val_exercise tools for that.",
-        inputSchema: { url: z.string(), maxPages: z.number().int().min(1).max(50).optional() },
-    }, async ({ url, maxPages }) => {
-        const { findings, pagesVisited } = await scanSite(url, { maxPages: maxPages ?? 12 });
+        description: "Crawl an app (localhost or live), following same-origin links, and report passive bugs: broken links/404s, uncaught JS errors, console errors, failed network requests, broken images, missing titles, horizontal layout overflow, clipped text, and janky load (layout shift / CLS). Pass `device` to test the MOBILE rendering (e.g. 'iPhone 14'). Good first pass. Does NOT click buttons — use val_open/val_click/val_type/val_exercise for that.",
+        inputSchema: { url: z.string(), maxPages: z.number().int().min(1).max(50).optional(), device: z.string().optional().describe("Emulate a mobile device, e.g. 'iPhone 14' or 'Pixel 7'") },
+    }, async ({ url, maxPages, device }) => {
+        const { findings, pagesVisited } = await scanSite(url, { maxPages: maxPages ?? 12, device });
         return text(`${formatReport(findings, pagesVisited)}\n\nJSON:\n${JSON.stringify(findings)}`);
     });
     server.registerTool("val_check", {
         title: "Re-check one page (verify a fix)",
         description: "Run the passive checks on a SINGLE page. Use after fixing a bug to confirm it is gone.",
-        inputSchema: { url: z.string() },
-    }, async ({ url }) => {
+        inputSchema: { url: z.string(), device: z.string().optional() },
+    }, async ({ url, device }) => {
         const browser = await chromium.launch({ headless: true });
         try {
-            const { findings } = await checkPage(browser, url);
+            const { findings } = await checkPage(browser, url, { device });
             return text(`${formatReport(findings, [url])}\n\nJSON:\n${JSON.stringify(findings)}`);
         }
         finally {
@@ -95,8 +95,8 @@ async function runServer() {
     server.registerTool("val_open", {
         title: "Open a page in the live session",
         description: "Start (or reuse) the browser session and navigate to a URL. Returns the page state and any load errors. This begins an interactive session you drive with val_snapshot / val_click / val_type to walk a funnel (e.g. sign up, checkout).",
-        inputSchema: { url: z.string() },
-    }, async ({ url }) => text(fmtAction(await session.open(url))));
+        inputSchema: { url: z.string(), device: z.string().optional().describe("Emulate a mobile device, e.g. 'iPhone 14'") },
+    }, async ({ url, device }) => text(fmtAction(await session.open(url, device))));
     server.registerTool("val_snapshot", {
         title: "List the interactive elements on the current page",
         description: "Return every clickable/fillable element on the current page with a [ref] you can pass to val_click / val_type, plus its kind and label. Call this to see what you can act on before clicking or typing.",
@@ -133,9 +133,9 @@ async function runServer() {
     server.registerTool("val_screenshot", {
         title: "Screenshot a page",
         description: "Capture a PNG of a URL so you can reason about layout/visual issues.",
-        inputSchema: { url: z.string(), fullPage: z.boolean().optional() },
-    }, async ({ url, fullPage }) => {
-        const data = await screenshot(url, fullPage ?? false);
+        inputSchema: { url: z.string(), fullPage: z.boolean().optional(), device: z.string().optional() },
+    }, async ({ url, fullPage, device }) => {
+        const data = await screenshot(url, fullPage ?? false, device);
         return { content: [{ type: "image", data, mimeType: "image/png" }] };
     });
     server.registerTool("val_close", {

package/dist/scanner.js

@@ -1,9 +1,8 @@
-import { chromium } from "playwright";
+import { chromium, devices } from "playwright";
 let _seq = 0;
 function finding(type, severity, page, detail, evidence) {
     return { id: `f${++_seq}`, type, severity, page, detail, evidence };
 }
-/** Strip the hash and normalize so we don't visit the same page twice. */
 function normalize(u) {
     try {
         const url = new URL(u);
@@ -14,14 +13,21 @@ function normalize(u) {
         return "";
     }
 }
-/**
- * Load one page in a fresh context, capture browser-level signals
- * (HTTP status, uncaught errors, console errors, failed responses,
- * broken images, missing title) and the outgoing links.
- */
-export async function checkPage(browser, url, timeoutMs = 20000) {
-    const ctx = await browser.newContext();
+/** Build a context, optionally emulating a mobile device (e.g. "iPhone 14", "Pixel 7"). */
+export async function makeContext(browser, device) {
+    if (device && devices[device])
+        return browser.newContext({ ...devices[device] });
+    if (device)
+        return browser.newContext({ ...devices["iPhone 14"] }); // unknown name → sensible mobile default
+    return browser.newContext();
+}
+// Registered before load so it captures the cumulative layout shift during paint.
+const CLS_INIT = `(() => { try { window.__valCLS = 0; new PerformanceObserver((l) => { for (const e of l.getEntries()) { if (!e.hadRecentInput) window.__valCLS += e.value || 0; } }).observe({ type: "layout-shift", buffered: true }); } catch (e) {} })();`;
+export async function checkPage(browser, url, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 20000;
+    const ctx = await makeContext(browser, opts.device);
     const page = await ctx.newPage();
+    await page.addInitScript(CLS_INIT);
     const findings = [];
     const consoleErrors = new Set();
     const pageErrors = new Set();
@@ -30,8 +36,6 @@ export async function checkPage(browser, url, timeoutMs = 20000) {
         if (m.type() !== "error")
             return;
         const t = m.text();
-        // Browser-generated "Failed to load resource" lines just duplicate the
-        // network-error findings, so drop them to keep the report clean.
         if (/Failed to load resource/i.test(t))
             return;
         consoleErrors.add(t.slice(0, 300));
@@ -50,12 +54,12 @@ export async function checkPage(browser, url, timeoutMs = 20000) {
         const status = resp?.status() ?? 0;
         if (status >= 400)
             findings.push(finding("page-status", "high", url, `Page returned HTTP ${status}`, String(status)));
-        // let late JS / lazy images settle
-        await page.waitForTimeout(900);
+        await page.waitForTimeout(1100);
         const title = (await page.title()).trim();
         if (!title)
             findings.push(finding("missing-title", "low", url, "Page has no <title>"));
         const dom = await page.evaluate(() => {
+            const w = window;
             const links = Array.from(document.querySelectorAll("a[href]"))
                 .map((a) => a.href)
                 .filter((h) => h.startsWith("http"));
@@ -65,12 +69,45 @@ export async function checkPage(browser, url, timeoutMs = 20000) {
                 return i.complete && i.naturalWidth === 0 && !!(i.currentSrc || i.src);
             })
                 .map((img) => img.currentSrc || img.src);
-            return { links, brokenImgs };
+            // Horizontal overflow: content wider than the viewport (a classic broken layout).
+            const vw = w.innerWidth;
+            const docW = document.documentElement.scrollWidth;
+            const horizontalOverflow = docW > vw + 2 ? docW - vw : 0;
+            // Clipped text: a container hides its own overflowing text (and not on purpose).
+            const clipped = [];
+            const nodes = Array.from(document.querySelectorAll("*")).slice(0, 4000);
+            for (const el of nodes) {
+                const e = el;
+                if (e.children.length !== 0)
+                    continue; // leaf text only
+                const text = (e.textContent || "").trim();
+                if (text.length < 10)
+                    continue;
+                const cs = getComputedStyle(e);
+                const hidden = cs.overflow === "hidden" || cs.overflowX === "hidden" || cs.overflowY === "hidden";
+                if (!hidden)
+                    continue;
+                if (cs.textOverflow === "ellipsis" || cs.getPropertyValue("-webkit-line-clamp") !== "none")
+                    continue; // intentional
+                if (e.scrollWidth > e.clientWidth + 4 || e.scrollHeight > e.clientHeight + 4) {
+                    const r = e.getBoundingClientRect();
+                    if (r.width > 0 && r.height > 0)
+                        clipped.push(text.slice(0, 50));
+                }
+                if (clipped.length >= 8)
+                    break;
+            }
+            return { links, brokenImgs, horizontalOverflow, clipped, cls: w.__valCLS || 0 };
         });
         links = dom.links;
-        for (const src of new Set(dom.brokenImgs)) {
+        for (const src of new Set(dom.brokenImgs))
             findings.push(finding("broken-image", "medium", url, "Image failed to load", src));
-        }
+        if (dom.horizontalOverflow > 0)
+            findings.push(finding("layout-overflow", "medium", url, `Page scrolls horizontally — content ${Math.round(dom.horizontalOverflow)}px wider than the viewport`));
+        for (const t of new Set(dom.clipped))
+            findings.push(finding("clipped-text", "low", url, "Text appears clipped by its container", t));
+        if (dom.cls > 0.25)
+            findings.push(finding("layout-shift", "medium", url, `Janky load: cumulative layout shift ${dom.cls.toFixed(2)} (target < 0.1)`));
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
@@ -82,16 +119,14 @@ export async function checkPage(browser, url, timeoutMs = 20000) {
         findings.push(finding("console-error", "medium", url, `Console error: ${t}`));
     for (const [u, s] of netErrors) {
         if (u === mainUrl)
-            continue; // the main document status is already reported as page-status
+            continue;
         findings.push(finding("network-error", s >= 500 ? "high" : "medium", url, `Resource returned HTTP ${s}`, u));
     }
     await ctx.close();
     return { findings, links };
 }
-/** BFS-crawl same-origin pages from startUrl and check each one. */
 export async function scanSite(startUrl, opts = {}) {
     const maxPages = opts.maxPages ?? 12;
-    const timeoutMs = opts.timeoutMs ?? 20000;
     const start = normalize(startUrl);
     if (!start)
         throw new Error(`Invalid URL: ${startUrl}`);
@@ -108,7 +143,7 @@ export async function scanSite(startUrl, opts = {}) {
             if (visited.has(url))
                 continue;
             visited.add(url);
-            const res = await checkPage(browser, url, timeoutMs);
+            const res = await checkPage(browser, url, { timeoutMs: opts.timeoutMs, device: opts.device });
             findings.push(...res.findings);
             pagesVisited.push(url);
             for (const link of res.links) {
@@ -122,7 +157,7 @@ export async function scanSite(startUrl, opts = {}) {
                     }
                 }
                 catch {
-                    /* ignore unparseable links */
+                    /* ignore */
                 }
             }
         }
@@ -132,11 +167,11 @@ export async function scanSite(startUrl, opts = {}) {
     }
     return { findings, pagesVisited };
 }
-/** Screenshot a single page, return base64 PNG. */
-export async function screenshot(url, fullPage = false, timeoutMs = 20000) {
+export async function screenshot(url, fullPage = false, device, timeoutMs = 20000) {
     const browser = await chromium.launch({ headless: true });
     try {
-        const page = await browser.newPage();
+        const ctx = await makeContext(browser, device);
+        const page = await ctx.newPage();
         await page.goto(url, { waitUntil: "load", timeout: timeoutMs });
         await page.waitForTimeout(700);
         const buf = await page.screenshot({ fullPage, type: "png" });

package/dist/session.js

@@ -1,10 +1,11 @@
-import { chromium } from "playwright";
+import { chromium, devices } from "playwright";
 function dedupe(a) {
     return Array.from(new Set(a));
 }
 class ValSession {
     browser;
     page;
+    device;
     consoleErrors = [];
     pageErrors = [];
     netErrors = [];
@@ -12,7 +13,7 @@ class ValSession {
         if (this.browser && this.page)
             return this.page;
         this.browser = await chromium.launch({ headless: true });
-        const ctx = await this.browser.newContext();
+        const ctx = await this.browser.newContext(this.device && devices[this.device] ? { ...devices[this.device] } : this.device ? { ...devices["iPhone 14"] } : {});
         this.page = await ctx.newPage();
         this.page.on("console", (m) => {
             if (m.type() === "error" && !/Failed to load resource/i.test(m.text())) {
@@ -50,7 +51,10 @@ class ValSession {
             return byRef.first();
         return page.getByText(refOrText, { exact: false }).first();
     }
-    async open(url) {
+    async open(url, device) {
+        if (device !== this.device && this.browser)
+            await this.close();
+        this.device = device;
         const page = await this.ensure();
         this.drain();
         let note;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyx-intelligence/val-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Val — a 100% MCP QA agent for vibecoders. Drives a real browser to catch UX bugs (broken links, 404s, console errors, broken images) so your coding agent can fix them.",
   "type": "module",
   "license": "UNLICENSED",