@vercel/next-browser 0.2.0 → 0.3.0

package/README.md

@@ -46,7 +46,8 @@ Requires Node >= 20.
 | Command            | Description                                               |
 | ------------------ | --------------------------------------------------------- |
 | `goto <url>`       | Full-page navigation (new document load)                  |
-| `ssr-goto <url>`   | Navigate blocking external scripts (inspect SSR shell)    |
+| `ssr lock`         | Block external scripts on all navigations (SSR-only mode) |
+| `ssr unlock`       | Re-enable external scripts                                |
 | `push [path]`      | Client-side navigation (interactive picker if no path)    |
 | `back`             | Go back in history                                        |
 | `reload`           | Reload current page                                       |
@@ -62,7 +63,8 @@ Requires Node >= 20.
 | `errors`          | Build and runtime errors for the current page                 |
 | `logs`            | Recent dev server log output                                  |
 | `network [idx]`   | List network requests, or inspect one (headers, body)         |
-| `screenshot`      | Full-page PNG to a temp file                                  |
+| `preview [caption]` | Screenshot + open in viewer window (accumulates across calls) |
+| `screenshot`      | Viewport PNG to a temp file (`--full-page` for entire page)   |
 
 ### Interaction
 
@@ -138,8 +140,8 @@ $ next-browser perf http://localhost:3000/dashboard
 $ next-browser ppr lock
 locked
 $ next-browser goto http://localhost:3000/dashboard
-$ next-browser screenshot
-/var/folders/.../next-browser-screenshot.png
+$ next-browser preview "PPR shell — locked"
+preview → /var/folders/.../next-browser-screenshot.png
 $ next-browser ppr unlock
 # PPR Shell Analysis — 131 boundaries: 3 dynamic holes, 128 static
 

package/dist/browser.js

@@ -10,7 +10,7 @@
  *
  * Module-level state: one browser context, one page, one PPR lock.
  */
-import { readFileSync, mkdirSync } 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";
@@ -29,6 +29,23 @@ let context = null;
 let page = null;
 let profileDirPath = null;
 let initialOrigin = null;
+let ssrLocked = false;
+let previewBrowser = null;
+let previewPage = null;
+let previewImages = [];
+/** Install or remove the script-blocking route handler based on ssrLocked. */
+async function syncSsrRoutes() {
+    if (!page)
+        return;
+    await page.unrouteAll({ behavior: "wait" });
+    if (ssrLocked) {
+        await page.route("**/*", (route) => {
+            if (route.request().resourceType() === "script")
+                return route.abort();
+            return route.continue();
+        });
+    }
+}
 // ── Browser lifecycle ────────────────────────────────────────────────────────
 /**
  * Launch the browser (if not already open) and optionally navigate to a URL.
@@ -36,11 +53,12 @@ let initialOrigin = null;
  * reuse the existing context.
  */
 export async function open(url) {
-    if (!context) {
-        context = await launch();
-        page = context.pages()[0] ?? (await context.newPage());
-        net.attach(page);
+    if (context) {
+        await close();
     }
+    context = await launch();
+    page = context.pages()[0] ?? (await context.newPage());
+    net.attach(page);
     if (url) {
         initialOrigin = new URL(url).origin;
         await page.goto(url, { waitUntil: "domcontentloaded" });
@@ -59,11 +77,16 @@ export async function cookies(cookies, domain) {
 }
 /** Close the browser and reset all state. */
 export async function close() {
+    await previewBrowser?.close().catch(() => { });
+    previewBrowser = null;
+    previewPage = null;
+    previewImages = [];
     await context?.close();
     context = null;
     page = null;
     release = null;
     settled = null;
+    ssrLocked = false;
     // Clean up temp profile directory.
     if (profileDirPath) {
         const { rmSync } = await import("node:fs");
@@ -88,7 +111,7 @@ export function lock() {
     if (!page)
         throw new Error("browser not open");
     if (release)
-        throw new Error("already locked");
+        return Promise.resolve();
     return new Promise((locked) => {
         settled = instant(page, () => {
             locked();
@@ -225,6 +248,29 @@ async function waitForDevToolsReconnect(p) {
         await new Promise((r) => setTimeout(r, 200));
     }
 }
+// ── SSR lock/unlock ──────────────────────────────────────────────────────────
+//
+// While SSR-locked, every navigation blocks external script resources so the
+// page renders only the server-side HTML shell (no React hydration, no client
+// bundles). Useful for inspecting raw SSR output across multiple navigations.
+/** Enter SSR-locked mode. All subsequent navigations block external scripts. */
+export async function ssrLock() {
+    if (!page)
+        throw new Error("browser not open");
+    if (ssrLocked)
+        return;
+    ssrLocked = true;
+    await syncSsrRoutes();
+}
+/** Exit SSR-locked mode. Re-enables external scripts. */
+export async function ssrUnlock() {
+    if (!page)
+        throw new Error("browser not open");
+    if (!ssrLocked)
+        return;
+    ssrLocked = false;
+    await syncSsrRoutes();
+}
 // ── Navigation ───────────────────────────────────────────────────────────────
 /** Hard reload the current page. Returns the URL after reload. */
 export async function reload() {
@@ -412,30 +458,9 @@ export async function push(path) {
 /** Full-page navigation (new document load). Resolves relative URLs against the current page. */
 export async function goto(url) {
     if (!page)
-        throw new Error("browser not open");
-    await page.unrouteAll({ behavior: "wait" });
-    const target = new URL(url, page.url()).href;
-    initialOrigin = new URL(target).origin;
-    await page.goto(target, { waitUntil: "domcontentloaded" });
-    return target;
-}
-/**
- * Navigate like goto but block external script resources.
- * The HTML loads and inline <script> blocks still execute, but external JS
- * bundles (React, hydration, etc.) are aborted. Shows the SSR shell.
- */
-export async function ssrGoto(url) {
-    if (!page)
-        throw new Error("browser not open");
+        await open(undefined);
     const target = new URL(url, page.url()).href;
     initialOrigin = new URL(target).origin;
-    // Clear any stale route handlers from previous ssr-goto calls.
-    await page.unrouteAll({ behavior: "wait" });
-    await page.route("**/*", (route) => {
-        if (route.request().resourceType() === "script")
-            return route.abort();
-        return route.continue();
-    });
     await page.goto(target, { waitUntil: "domcontentloaded" });
     return target;
 }
@@ -492,15 +517,73 @@ async function formatSource([file, line, col]) {
     return `source: ${file}:${line}:${col}`;
 }
 // ── Utilities ────────────────────────────────────────────────────────────────
-/** Viewport screenshot saved to a temp file. Returns the file path. */
-export async function screenshot() {
+/** Take a screenshot and display it in a separate headed Chromium window.
+ *  Images accumulate across calls — use `clear` to reset. */
+export async function preview(caption, clear) {
+    if (!page)
+        throw new Error("browser not open");
+    if (clear)
+        previewImages = [];
+    const path = await screenshot();
+    const imgData = readFileSync(path).toString("base64");
+    const timestamp = new Date().toLocaleTimeString();
+    previewImages.unshift({ caption, imgData, timestamp });
+    const imagesHtml = previewImages
+        .map((img) => `<div style="padding:4px 12px;display:flex;align-items:baseline;gap:8px">` +
+        (img.caption
+            ? `<span style="font-size:14px">${escapeHtml(img.caption)}</span>`
+            : "") +
+        `<span style="font-size:11px;opacity:0.5">${escapeHtml(img.timestamp)}</span>` +
+        `</div>` +
+        `<img src="data:image/png;base64,${img.imgData}" style="display:block;max-width:100%">`)
+        .join(`<hr style="border:none;border-top:1px solid #333;margin:12px 0">`);
+    const html = `<html><head><title>next-browser preview</title></head>` +
+        `<body style="margin:0;background:#111;color:#fff;font-family:system-ui">` +
+        `<div style="padding:8px 12px;font-size:11px;opacity:0.5;text-transform:uppercase;letter-spacing:0.05em">next-browser preview</div>` +
+        `${imagesHtml}` +
+        `</body></html>`;
+    const htmlPath = path.replace(/\.png$/, ".html");
+    writeFileSync(htmlPath, html);
+    const target = `file://${htmlPath}`;
+    // Reuse existing preview window, or launch a new one.
+    if (previewPage && !previewPage.isClosed()) {
+        try {
+            await previewPage.goto(target);
+            await previewPage.bringToFront();
+            return path;
+        }
+        catch {
+            // Window was closed by user — fall through to launch a new one.
+            await previewBrowser?.close().catch(() => { });
+        }
+    }
+    const { mkdtempSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    const { tmpdir } = await import("node:os");
+    const userDataDir = mkdtempSync(join(tmpdir(), "nb-preview-"));
+    const ctx = await chromium.launchPersistentContext(userDataDir, {
+        headless: false,
+        args: [`--app=${target}`, "--window-size=820,640"],
+        viewport: null,
+    });
+    previewBrowser = ctx;
+    previewPage = ctx.pages()[0] ?? (await ctx.waitForEvent("page"));
+    await previewPage.waitForLoadState();
+    await previewPage.bringToFront();
+    return path;
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** Screenshot saved to a temp file. Returns the file path. */
+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 });
+    await page.screenshot({ path, fullPage: opts?.fullPage });
     return path;
 }
 /** Remove Next.js devtools overlay from the page before screenshots. */

package/dist/cli.js

@@ -120,16 +120,27 @@ if (cmd === "goto") {
     const res = await send("goto", { url: arg });
     exit(res, res.ok ? `→ ${res.data}` : "");
 }
-if (cmd === "ssr-goto") {
-    const res = await send("ssr-goto", { url: arg });
-    exit(res, res.ok ? `→ ${res.data} (external scripts blocked)` : "");
+if (cmd === "ssr" && arg === "lock") {
+    const res = await send("ssr-lock");
+    exit(res, "ssr locked — external scripts blocked on all navigations");
+}
+if (cmd === "ssr" && arg === "unlock") {
+    const res = await send("ssr-unlock");
+    exit(res, "ssr unlocked — external scripts re-enabled");
 }
 if (cmd === "back") {
     const res = await send("back");
     exit(res, "back");
 }
+if (cmd === "preview") {
+    const clear = args.includes("--clear");
+    const caption = args.filter((a) => a !== "--clear").slice(1).join(" ") || undefined;
+    const res = await send("preview", { caption, clear });
+    exit(res, res.ok ? `preview → ${res.data}` : "");
+}
 if (cmd === "screenshot") {
-    const res = await send("screenshot");
+    const fullPage = args.includes("--full-page");
+    const res = await send("screenshot", { fullPage });
     exit(res, res.ok ? String(res.data) : "");
 }
 if (cmd === "snapshot") {
@@ -317,7 +328,8 @@ function printUsage() {
         "  close              close browser and daemon\n" +
         "\n" +
         "  goto <url>         full-page navigation (new document load)\n" +
-        "  ssr-goto <url>     goto but block external scripts (SSR shell)\n" +
+        "  ssr lock           block external scripts on all navigations\n" +
+        "  ssr unlock         re-enable external scripts\n" +
         "  push [path]        client-side navigation (interactive picker if no path)\n" +
         "  back               go back in history\n" +
         "  reload             reload current page\n" +
@@ -331,7 +343,8 @@ function printUsage() {
         "  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" +
+        "  preview [caption] [--clear]  screenshot + open in viewer (accumulates)\n" +
+        "  screenshot [--full-page]  save screenshot to tmp file\n" +
         "  snapshot           accessibility tree with interactive refs\n" +
         "  click <ref|sel>    click an element (real pointer events)\n" +
         "  fill <ref|sel> <v> fill a text input\n" +

package/dist/daemon.js

@@ -65,8 +65,12 @@ async function run(cmd) {
         const data = await browser.restart();
         return { ok: true, data };
     }
+    if (cmd.action === "preview") {
+        const data = await browser.preview(cmd.caption, cmd.clear);
+        return { ok: true, data };
+    }
     if (cmd.action === "screenshot") {
-        const data = await browser.screenshot();
+        const data = await browser.screenshot({ fullPage: cmd.fullPage });
         return { ok: true, data };
     }
     if (cmd.action === "links") {
@@ -81,9 +85,13 @@ async function run(cmd) {
         const data = await browser.goto(cmd.url);
         return { ok: true, data };
     }
-    if (cmd.action === "ssr-goto") {
-        const data = await browser.ssrGoto(cmd.url);
-        return { ok: true, data };
+    if (cmd.action === "ssr-lock") {
+        await browser.ssrLock();
+        return { ok: true };
+    }
+    if (cmd.action === "ssr-unlock") {
+        await browser.ssrUnlock();
+        return { ok: true };
     }
     if (cmd.action === "back") {
         await browser.back();

package/package.json

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