@vercel/next-browser 0.1.2 → 0.1.4

package/README.md

@@ -10,25 +10,45 @@ Built for agents. An LLM can't read a DevTools panel, but it can run
 command is a stateless one-shot against a long-lived browser daemon, so an
 agent loop can fire them off without managing browser lifecycle.
 
-## Install
+## Getting started
 
-```bash
-pnpm add -g @vercel/next-browser
-```
+You don't install or run this directly. Your agent does.
 
-Requires Node `>=20`.
+1. **Add the skill to your project.** From your Next.js repo:
+
+   ```bash
+   npx skills add vercel-labs/next-browser
+   ```
+
+   Works with Claude Code, Cursor, Cline, and [others](https://skills.sh).
+
+2. **Start your agent** in that project.
+
+3. **Type `/next-browser`** to invoke the skill.
 
-## Usage
+4. The skill checks for the CLI and **installs `@vercel/next-browser`
+   globally** if it's missing (plus `playwright install chromium`).
+
+5. It asks for your dev server URL and any cookies it needs, opens the
+   browser, and from there it's **pair programming** — tell it what you're
+   debugging and it drives the tree, navigates pages, inspects components,
+   and reads errors for you.
+
+That's the whole flow. Run `npx skills upgrade` later to pull updates.
+
+The rest of this README documents the raw CLI for the rare case where you're
+scripting it yourself.
+
+---
+
+## Manual install
 
 ```bash
-next-browser open http://localhost:3000
-next-browser tree
-next-browser ppr lock
-next-browser push /dashboard
-next-browser ppr unlock
-next-browser close
+pnpm add -g @vercel/next-browser
 ```
 
+Requires Node `>=20`.
+
 ## Commands
 
 ```
@@ -39,14 +59,16 @@ goto <url>         full-page navigation (new document load)
 push [path]        client-side navigation (interactive picker if no path)
 back               go back in history
 reload             reload current page
+capture-goto [url] capture loading sequence (PPR shell → hydration → data)
 restart-server     restart the Next.js dev server (clears fs cache)
 
-ppr lock           enter PPR instant-navigation mode
+ppr lock           enter PPR instant-navigation mode (requires cacheComponents)
 ppr unlock         exit PPR mode and show shell analysis
 
 tree               show React component tree
 tree <id>          inspect component (props, hooks, state, source)
 
+viewport [WxH]     show or set viewport size (e.g. 1280x720)
 screenshot         save full-page screenshot to tmp file
 eval <script>      evaluate JS in page context
 

package/dist/browser.js

@@ -3,13 +3,16 @@
  *
  * Launches via Playwright with the React DevTools Chrome extension pre-loaded
  * and --auto-open-devtools-for-tabs so the extension activates naturally.
+ * DevTools opens in a separate (undocked) window so the main browser viewport
+ * stays at full desktop size.
  * installHook.js is pre-injected via addInitScript to win the race against
  * the extension's content script registration.
  *
  * Module-level state: one browser context, one page, one PPR lock.
  */
-import { readFileSync } from "node:fs";
+import { readFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
 import { chromium } from "playwright";
 import { instant } from "@next/playwright";
 import * as componentTree from "./tree.js";
@@ -24,6 +27,7 @@ const extensionPath = process.env.REACT_DEVTOOLS_EXTENSION ??
 const installHook = readFileSync(join(extensionPath, "build", "installHook.js"), "utf-8");
 let context = null;
 let page = null;
+let profileDirPath = null;
 // ── Browser lifecycle ────────────────────────────────────────────────────────
 /**
  * Launch the browser (if not already open) and optionally navigate to a URL.
@@ -58,6 +62,12 @@ export async function close() {
     page = null;
     release = null;
     settled = null;
+    // Clean up temp profile directory.
+    if (profileDirPath) {
+        const { rmSync } = await import("node:fs");
+        rmSync(profileDirPath, { recursive: true, force: true });
+        profileDirPath = null;
+    }
 }
 // ── PPR lock/unlock ──────────────────────────────────────────────────────────
 //
@@ -194,6 +204,67 @@ export async function reload() {
     await page.reload({ waitUntil: "domcontentloaded" });
     return page.url();
 }
+/**
+ * Reload the page while capturing screenshots every ~150ms.
+ * Stops when: load has fired AND no new layout-shift entries for 2s.
+ * Hard timeout at 30s. Returns the list of screenshot paths plus any
+ * LayoutShift entries observed during the reload.
+ */
+/**
+ * Lock PPR → goto → screenshot the shell → unlock → screenshot frames
+ * until the page settles. Just PNGs in a directory — the AI reads them.
+ *
+ * Frame 0 is always the PPR shell. Remaining frames capture the transition
+ * through hydration and data loading. Stops after 3s of no visual change.
+ */
+export async function captureGoto(url) {
+    if (!page)
+        throw new Error("browser not open");
+    const targetUrl = url || page.url();
+    const dir = join(tmpdir(), `next-browser-capture-goto-${Date.now()}`);
+    mkdirSync(dir, { recursive: true });
+    let frameIdx = 0;
+    async function snap() {
+        const path = join(dir, `frame-${String(frameIdx).padStart(4, "0")}.png`);
+        const buf = await page.screenshot({ path }).catch(() => null);
+        frameIdx++;
+        return buf;
+    }
+    // PPR shell: lock suppresses hydration.
+    await lock();
+    await page.goto(targetUrl, { waitUntil: "load" }).catch(() => { });
+    await new Promise((r) => setTimeout(r, 300));
+    await snap();
+    // Unlock → page reloads, hydrates, loads data.
+    const unlockDone = unlock();
+    await new Promise((r) => setTimeout(r, 200));
+    let lastChangeTime = Date.now();
+    let prevHash = "";
+    const SETTLE_MS = 3_000;
+    const HARD_TIMEOUT = 30_000;
+    const start = Date.now();
+    while (true) {
+        const buf = await snap();
+        let hash = "";
+        if (buf) {
+            let h = 0;
+            for (let i = 0; i < buf.length; i += 200)
+                h = ((h << 5) - h + buf[i]) | 0;
+            hash = String(h);
+        }
+        if (hash !== prevHash) {
+            lastChangeTime = Date.now();
+            prevHash = hash;
+        }
+        if (Date.now() - start > HARD_TIMEOUT)
+            break;
+        if (lastChangeTime > 0 && Date.now() - lastChangeTime > SETTLE_MS)
+            break;
+        await new Promise((r) => setTimeout(r, 150));
+    }
+    await unlockDone.catch(() => { });
+    return { dir, frames: frameIdx };
+}
 /**
  * Restart the Next.js dev server via its internal endpoint, then reload.
  * Polls /__nextjs_server_status until the executionId changes (new process).
@@ -348,11 +419,79 @@ export async function mcp(tool, args) {
 export function network(idx) {
     return idx == null ? net.format() : net.detail(idx);
 }
+// ── Viewport ─────────────────────────────────────────────────────────────────
+/**
+ * Set the browser viewport to the given dimensions.
+ * Returns the applied size. Once set, the viewport stays fixed across
+ * navigations — use `viewport(null, null)` to restore auto-sizing.
+ */
+export async function viewport(width, height) {
+    if (!page)
+        throw new Error("browser not open");
+    if (width == null || height == null) {
+        // Reset to auto-sizing: match the browser window.
+        // Playwright doesn't expose a "reset viewport" API, so we read the
+        // current window bounds via CDP and set the viewport to match.
+        const cdp = await page.context().newCDPSession(page);
+        const { windowId } = await cdp.send("Browser.getWindowForTarget");
+        const { bounds } = await cdp.send("Browser.getWindowBounds", { windowId });
+        await cdp.detach();
+        // Account for browser chrome (~roughly 80px for title bar + tabs).
+        const w = bounds.width ?? 1280;
+        const h = (bounds.height ?? 800) - 80;
+        await page.setViewportSize({ width: w, height: h });
+        return { width: w, height: h };
+    }
+    await page.setViewportSize({ width, height });
+    // Also resize the physical window to match, so viewport == window.
+    try {
+        const cdp = await page.context().newCDPSession(page);
+        const { windowId } = await cdp.send("Browser.getWindowForTarget");
+        await cdp.send("Browser.setWindowBounds", {
+            windowId,
+            bounds: { width, height: height + 80 }, // +80 for browser chrome
+        });
+        await cdp.detach();
+    }
+    catch { }
+    return { width, height };
+}
+/** Get the current viewport dimensions. */
+export async function viewportSize() {
+    if (!page)
+        throw new Error("browser not open");
+    const size = page.viewportSize();
+    if (size)
+        return size;
+    // viewport: null — read actual inner dimensions from the page.
+    return page.evaluate(() => ({
+        width: window.innerWidth,
+        height: window.innerHeight,
+    }));
+}
 // ── Browser launch ───────────────────────────────────────────────────────────
+/**
+ * Create a temporary Chrome profile directory with DevTools set to "undocked"
+ * so it opens in a separate window instead of docked inside the browser.
+ * This keeps the main browser viewport at full desktop size.
+ */
+function createProfileDir() {
+    const dir = join(tmpdir(), `next-browser-profile-${process.pid}`);
+    mkdirSync(join(dir, "Default"), { recursive: true });
+    writeFileSync(join(dir, "Default", "Preferences"), JSON.stringify({
+        devtools: {
+            preferences: {
+                currentDockState: '"undocked"',
+            },
+        },
+    }));
+    return dir;
+}
 /**
  * Launch Chromium with React DevTools extension.
  *
- * - launchPersistentContext("") — empty user data dir (fresh profile each time)
+ * - launchPersistentContext with a pre-configured profile that sets DevTools
+ *   to undocked mode — DevTools opens in a separate window, not docked
  * - --load-extension loads the vendored React DevTools Chrome extension
  * - --auto-open-devtools-for-tabs makes the extension activate its backend
  *   on every tab (same as a developer manually opening DevTools)
@@ -362,13 +501,16 @@ export function network(idx) {
  *   winning the race against the extension's content script
  */
 async function launch() {
-    const ctx = await chromium.launchPersistentContext("", {
+    const profileDir = createProfileDir();
+    profileDirPath = profileDir;
+    const ctx = await chromium.launchPersistentContext(profileDir, {
         headless: false,
-        viewport: null,
+        viewport: null, // let viewport follow the physical window size
         args: [
             `--disable-extensions-except=${extensionPath}`,
             `--load-extension=${extensionPath}`,
             "--auto-open-devtools-for-tabs",
+            "--window-size=1440,900",
         ],
     });
     await ctx.waitForEvent("serviceworker");

package/dist/cli.js

@@ -8,6 +8,11 @@ if (cmd === "--help" || cmd === "-h" || !cmd) {
     printUsage();
     process.exit(0);
 }
+if (cmd === "--version" || cmd === "-v") {
+    const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+    console.log(version);
+    process.exit(0);
+}
 if (cmd === "open") {
     if (!arg) {
         console.error("usage: next-browser open <url> [--cookies-json <file>]");
@@ -43,6 +48,15 @@ if (cmd === "reload") {
     const res = await send("reload");
     exit(res, res.ok ? `reloaded → ${res.data}` : "");
 }
+if (cmd === "capture-goto") {
+    const res = await send("capture-goto", arg ? { url: arg } : {});
+    if (!res.ok)
+        exit(res, "");
+    const data = res.data;
+    exit(res, `${data.frames} frames → ${data.dir}\n` +
+        "\n" +
+        "frame-0000.png is the PPR shell. Remaining frames capture hydration → data.");
+}
 if (cmd === "restart-server") {
     const res = await send("restart");
     exit(res, res.ok ? `restarted → ${res.data}` : "");
@@ -119,6 +133,24 @@ if (cmd === "network") {
     const res = await send("network", arg != null ? { idx: Number(arg) } : {});
     exit(res, res.ok ? String(res.data) : "");
 }
+if (cmd === "viewport") {
+    if (arg) {
+        const match = arg.match(/^(\d+)x(\d+)$/);
+        if (!match) {
+            console.error("usage: next-browser viewport <width>x<height>");
+            process.exit(1);
+        }
+        const width = Number(match[1]);
+        const height = Number(match[2]);
+        const res = await send("viewport", { width, height });
+        exit(res, res.ok ? `viewport set to ${width}x${height}` : "");
+    }
+    const res = await send("viewport", {});
+    if (!res.ok)
+        exit(res, "");
+    const data = res.data;
+    exit(res, `${data.width}x${data.height}`);
+}
 if (cmd === "close") {
     const res = await send("close");
     exit(res, "closed");
@@ -197,6 +229,7 @@ function printUsage() {
         "  push [path]        client-side navigation (interactive picker if no path)\n" +
         "  back               go back in history\n" +
         "  reload             reload current page\n" +
+        "  capture-goto [url]   capture loading sequence (PPR shell → hydration → data)\n" +
         "  restart-server     restart the Next.js dev server (clears fs cache)\n" +
         "\n" +
         "  ppr lock           enter PPR instant-navigation mode\n" +
@@ -205,6 +238,7 @@ function printUsage() {
         "  tree               show React component tree\n" +
         "  tree <id>          inspect component (props, hooks, state, source)\n" +
         "\n" +
+        "  viewport [WxH]     show or set viewport size (e.g. 1280x720)\n" +
         "  screenshot         save full-page screenshot to tmp file\n" +
         "  eval <script>      evaluate JS in page context\n" +
         "\n" +

package/dist/daemon.js

@@ -57,6 +57,10 @@ async function run(cmd) {
         const data = await browser.reload();
         return { ok: true, data };
     }
+    if (cmd.action === "capture-goto") {
+        const data = await browser.captureGoto(cmd.url);
+        return { ok: true, data };
+    }
     if (cmd.action === "restart") {
         const data = await browser.restart();
         return { ok: true, data };
@@ -101,6 +105,14 @@ async function run(cmd) {
         const data = await browser.network(cmd.idx);
         return { ok: true, data };
     }
+    if (cmd.action === "viewport") {
+        if (cmd.width !== undefined) {
+            const data = await browser.viewport(cmd.width, cmd.height);
+            return { ok: true, data };
+        }
+        const data = await browser.viewportSize();
+        return { ok: true, data };
+    }
     if (cmd.action === "close") {
         await browser.close();
         return { ok: true };

package/package.json

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