@vercel/next-browser 0.5.0 → 0.6.0

package/README.md

@@ -38,7 +38,7 @@ Requires Node >= 20.
 
 | Command                              | Description                                        |
 | ------------------------------------ | -------------------------------------------------- |
-| `open <url> [--cookies-json <file>]` | Launch browser and navigate (with optional cookies) |
+| `open <url> [--cookies <file>]`      | Launch browser and navigate (with optional cookies) |
 | `close`                              | Close browser and kill daemon                      |
 
 ### Navigation
@@ -62,9 +62,9 @@ Requires Node >= 20.
 | `snapshot`        | Accessibility tree with `[ref=eN]` markers on interactive elements |
 | `errors`          | Build and runtime errors for the current page                 |
 | `logs`            | Recent dev server log output                                  |
+| `browser-logs`    | Browser console output (log, warn, error, info)               |
 | `network [idx]`   | List network requests, or inspect one (headers, body)         |
-| `preview [caption]` | Screenshot + open in viewer window (accumulates across calls) |
-| `screenshot`      | Viewport PNG to a temp file (`--full-page` for entire page)   |
+| `screenshot [caption] [--full-page]` | Viewport PNG to a temp file (caption shown in Screenshot Log) |
 
 ### Interaction
 
@@ -77,11 +77,20 @@ Requires Node >= 20.
 
 ### Performance & PPR
 
-| Command        | Description                                                  |
-| -------------- | ------------------------------------------------------------ |
-| `perf [url]`   | Core Web Vitals + React hydration timing in one pass         |
-| `ppr lock`     | Freeze dynamic content to inspect the static shell           |
-| `ppr unlock`   | Resume dynamic content and print shell analysis              |
+| Command                        | Description                                          |
+| ------------------------------ | ---------------------------------------------------- |
+| `perf [url]`                   | Core Web Vitals + React hydration timing in one pass |
+| `renders start`                | Start recording React re-renders                     |
+| `renders stop [--json]`        | Stop and print per-component render profile          |
+| `ppr lock`                     | Freeze dynamic content to inspect the static shell   |
+| `ppr unlock`                   | Resume dynamic content and print shell analysis      |
+
+### Instrumentation
+
+| Command                        | Description                                          |
+| ------------------------------ | ---------------------------------------------------- |
+| `instrumentation set <path>`   | Inject script before page scripts on every navigation |
+| `instrumentation clear`        | Remove instrumentation script                        |
 
 ### Next.js MCP
 

package/dist/browser.js

@@ -10,7 +10,7 @@
  *
  * Module-level state: one browser context, one page, one PPR lock.
  */
-import { readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { readFileSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { chromium } from "playwright";
@@ -30,6 +30,7 @@ let page = null;
 let profileDirPath = null;
 let initialOrigin = null;
 let ssrLocked = false;
+let instrumentationVersion = 0;
 let screenshotBrowser = null;
 let screenshotPage = null;
 let screenshotEntries = [];
@@ -87,6 +88,7 @@ export async function close() {
     release = null;
     settled = null;
     ssrLocked = false;
+    instrumentationVersion = 0;
     // Clean up temp profile directory.
     if (profileDirPath) {
         const { rmSync } = await import("node:fs");
@@ -95,6 +97,30 @@ export async function close() {
         initialOrigin = null;
     }
 }
+// ── Instrumentation ─────────────────────────────────────────────────────────
+//
+// addInitScript can't be removed, so we version-gate: each `set` bumps the
+// version and registers a new script that only runs when its version matches.
+// `clear` bumps the version with no matching script, disabling the old one.
+export async function instrumentationSet(script) {
+    if (!page)
+        throw new Error("browser not open");
+    const ctx = page.context();
+    const v = ++instrumentationVersion;
+    // The version gate runs first, then the guarded script.
+    await ctx.addInitScript(`window.__NB_IV__=${v}`);
+    await ctx.addInitScript(`if(window.__NB_IV__===${v}){${script}}`);
+    // Apply immediately on the current page.
+    await page.evaluate(script);
+}
+export async function instrumentationClear() {
+    if (!page)
+        throw new Error("browser not open");
+    const ctx = page.context();
+    // Bump version — no matching script, so nothing runs.
+    const v = ++instrumentationVersion;
+    await ctx.addInitScript(`window.__NB_IV__=${v}`);
+}
 // ── PPR lock/unlock ──────────────────────────────────────────────────────────
 //
 // The lock uses @next/playwright's `instant()` which sets the
@@ -568,21 +594,99 @@ async function refreshScreenshotLog() {
 function escapeHtml(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
+/** Max screenshot dimension in pixels — keeps images under the 2000px limit
+ *  that multi-image LLM requests impose. */
+const SCREENSHOT_MAX_DIM = 1280;
 /** Screenshot saved to a temp file. Opens the Screenshot Log window in headed mode.
- *  Returns the file path. */
+ *  Returns the file path for a single image, or a directory path when the
+ *  image is sliced into multiple chunks (full-page on long pages). */
 export async function screenshot(opts) {
     if (!page)
         throw new Error("browser not open");
     await hideDevOverlay();
-    const { join } = await import("node:path");
-    const { tmpdir } = await import("node:os");
     const path = join(tmpdir(), `next-browser-${Date.now()}.png`);
-    await page.screenshot({ path, fullPage: opts?.fullPage });
-    const imgData = readFileSync(path).toString("base64");
+    // scale: 'css' prevents Retina 2x doubling (1440x900 stays 1440x900).
+    await page.screenshot({ path, fullPage: opts?.fullPage, scale: "css" });
+    const result = await sliceIfNeeded(path, SCREENSHOT_MAX_DIM);
     const timestamp = new Date().toLocaleTimeString();
-    screenshotEntries.unshift({ caption: opts?.caption, imgData, timestamp });
+    if (typeof result === "string") {
+        // Single file — fits within limits.
+        const imgData = readFileSync(result).toString("base64");
+        screenshotEntries.unshift({ caption: opts?.caption, imgData, timestamp });
+    }
+    else {
+        // Multiple chunks — add each to the screenshot log.
+        for (const chunk of result.files) {
+            const imgData = readFileSync(chunk).toString("base64");
+            const label = opts?.caption
+                ? `${opts.caption} (${result.files.indexOf(chunk) + 1}/${result.files.length})`
+                : `chunk ${result.files.indexOf(chunk) + 1}/${result.files.length}`;
+            screenshotEntries.unshift({ caption: label, imgData, timestamp });
+        }
+    }
     await refreshScreenshotLog();
-    return path;
+    return typeof result === "string" ? result : result.dir;
+}
+/** If the screenshot fits within `maxDim`, scale it in-place and return the
+ *  path. Otherwise slice it into ≤maxDim chunks inside a temp directory and
+ *  return `{ dir, files }`. */
+async function sliceIfNeeded(filePath, maxDim) {
+    const buf = readFileSync(filePath);
+    if (buf.length < 24)
+        return filePath;
+    const w = buf.readUInt32BE(16);
+    const h = buf.readUInt32BE(20);
+    if (w <= maxDim && h <= maxDim)
+        return filePath;
+    if (!page)
+        return filePath;
+    const b64 = buf.toString("base64");
+    const wScale = Math.min(maxDim / w, 1);
+    const scaledW = Math.round(w * wScale);
+    const scaledH = Math.round(h * wScale);
+    if (scaledH <= maxDim) {
+        // Fits after width scaling — single resized file.
+        const resized = await page.evaluate(async ({ src, nw, nh }) => {
+            const img = new Image();
+            await new Promise((r, e) => { img.onload = () => r(); img.onerror = () => e(); img.src = `data:image/png;base64,${src}`; });
+            const c = document.createElement("canvas");
+            c.width = nw;
+            c.height = nh;
+            c.getContext("2d").drawImage(img, 0, 0, nw, nh);
+            return c.toDataURL("image/png").split(",")[1];
+        }, { src: b64, nw: scaledW, nh: scaledH });
+        writeFileSync(filePath, Buffer.from(resized, "base64"));
+        return filePath;
+    }
+    // Slice into chunks of maxDim height (in scaled pixels).
+    const chunkCount = Math.ceil(scaledH / maxDim);
+    const chunks = await page.evaluate(async ({ src, nw, totalH, max, count }) => {
+        const img = new Image();
+        await new Promise((r, e) => { img.onload = () => r(); img.onerror = () => e(); img.src = `data:image/png;base64,${src}`; });
+        const results = [];
+        for (let i = 0; i < count; i++) {
+            const sy = (i * max) / (totalH / img.height);
+            const sh = Math.min(max, totalH - i * max) / (totalH / img.height);
+            const dh = Math.min(max, totalH - i * max);
+            const c = document.createElement("canvas");
+            c.width = nw;
+            c.height = dh;
+            c.getContext("2d").drawImage(img, 0, sy, img.width, sh, 0, 0, nw, dh);
+            results.push(c.toDataURL("image/png").split(",")[1]);
+        }
+        return results;
+    }, { src: b64, nw: scaledW, totalH: scaledH, max: maxDim, count: chunkCount });
+    const dir = join(tmpdir(), `next-browser-screenshots-${Date.now()}`);
+    mkdirSync(dir, { recursive: true });
+    const files = [];
+    for (let i = 0; i < chunks.length; i++) {
+        const p = join(dir, `${String(i + 1).padStart(3, "0")}.png`);
+        writeFileSync(p, Buffer.from(chunks[i], "base64"));
+        files.push(p);
+    }
+    // Clean up the original full file.
+    unlinkSync(filePath);
+    return { dir, files };
 }
 /** Remove Next.js devtools overlay from the page before screenshots. */
 async function hideDevOverlay() {

package/dist/cli.js

@@ -369,6 +369,20 @@ if (cmd === "viewport") {
     const data = res.data;
     exit(res, `${data.width}x${data.height}`);
 }
+if (cmd === "instrumentation" && arg === "set") {
+    const filePath = args[2];
+    if (!filePath) {
+        console.error("usage: next-browser instrumentation set <path>");
+        process.exit(1);
+    }
+    const script = readFileSync(filePath, "utf-8");
+    const res = await send("instrumentation-set", { instrumentationScript: script });
+    exit(res, "instrumentation set");
+}
+if (cmd === "instrumentation" && arg === "clear") {
+    const res = await send("instrumentation-clear");
+    exit(res, "instrumentation cleared");
+}
 if (cmd === "close") {
     const res = await send("close");
     exit(res, "closed");
@@ -477,5 +491,8 @@ function printUsage() {
         "  page               show current page segments and router info\n" +
         "  project            show project path and dev server url\n" +
         "  routes             list app routes\n" +
-        "  action <id>        inspect a server action by id");
+        "  action <id>        inspect a server action by id\n" +
+        "\n" +
+        "  instrumentation set <path>  inject script before page scripts\n" +
+        "  instrumentation clear       remove instrumentation script");
 }

package/dist/daemon.js

@@ -145,6 +145,14 @@ async function run(cmd) {
         const data = await browser.viewportSize();
         return { ok: true, data };
     }
+    if (cmd.action === "instrumentation-set") {
+        await browser.instrumentationSet(cmd.instrumentationScript);
+        return { ok: true };
+    }
+    if (cmd.action === "instrumentation-clear") {
+        await browser.instrumentationClear();
+        return { ok: true };
+    }
     if (cmd.action === "close") {
         await browser.close();
         return { ok: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/next-browser",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Headed Playwright browser with React DevTools pre-loaded",
   "license": "MIT",
   "repository": {