@vercel/next-browser 0.2.0 → 0.4.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 screenshotBrowser = null;
+let screenshotPage = null;
+let screenshotEntries = [];
+/** 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 screenshotBrowser?.close().catch(() => { });
+    screenshotBrowser = null;
+    screenshotPage = null;
+    screenshotEntries = [];
     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,71 @@ 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() {
+/** Render screenshot entries as HTML and refresh (or launch) the log window.
+ *  No-op in headless mode. */
+async function refreshScreenshotLog() {
+    if (process.env.NEXT_BROWSER_HEADLESS)
+        return;
+    const entriesHtml = screenshotEntries
+        .map((e) => {
+        const header = `<div style="padding:4px 12px;display:flex;align-items:baseline;gap:8px">` +
+            (e.caption
+                ? `<span style="font-size:14px">${escapeHtml(e.caption)}</span>`
+                : "") +
+            `<span style="font-size:11px;opacity:0.5">${escapeHtml(e.timestamp)}</span>` +
+            `</div>`;
+        return header + `<img src="data:image/png;base64,${e.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>Screenshot Log</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">Screenshot Log</div>` +
+        `${entriesHtml}` +
+        `</body></html>`;
+    const htmlPath = join(tmpdir(), `next-browser-screenshots-${process.pid}.html`);
+    writeFileSync(htmlPath, html);
+    const target = `file://${htmlPath}`;
+    // Reuse existing log window, or launch a new one.
+    if (screenshotPage && !screenshotPage.isClosed()) {
+        try {
+            await screenshotPage.goto(target);
+            await screenshotPage.bringToFront();
+            return;
+        }
+        catch {
+            // Window was closed by user — fall through to launch a new one.
+            await screenshotBrowser?.close().catch(() => { });
+        }
+    }
+    const { mkdtempSync } = await import("node:fs");
+    const userDataDir = mkdtempSync(join(tmpdir(), "nb-screenshots-"));
+    const ctx = await chromium.launchPersistentContext(userDataDir, {
+        headless: false,
+        args: [`--app=${target}`, "--window-size=820,640"],
+        viewport: null,
+    });
+    screenshotBrowser = ctx;
+    screenshotPage = ctx.pages()[0] ?? (await ctx.waitForEvent("page"));
+    await screenshotPage.waitForLoadState();
+    await screenshotPage.bringToFront();
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** Screenshot saved to a temp file. Opens the Screenshot Log window in headed mode.
+ *  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 });
+    const imgData = readFileSync(path).toString("base64");
+    const timestamp = new Date().toLocaleTimeString();
+    screenshotEntries.unshift({ caption: opts?.caption, imgData, timestamp });
+    await refreshScreenshotLog();
     return path;
 }
 /** Remove Next.js devtools overlay from the page before screenshots. */
@@ -690,6 +771,312 @@ export async function mcp(tool, args) {
     const origin = initialOrigin ?? new URL(page.url()).origin;
     return nextMcp.call(origin, tool, args);
 }
+/** Return browser console output captured by the init-script interceptor. */
+export async function browserLogs() {
+    if (!page)
+        throw new Error("browser not open");
+    return page.evaluate(() => window.__NEXT_BROWSER_CONSOLE_LOGS__ ?? []);
+}
+// ── Render Profiling ────────────────────────────────────────────────────────
+/**
+ * The browser-side script that installs the onCommitFiberRoot hook.
+ * Extracted so it can be used by both rendersStart (page.evaluate)
+ * and rendersAuto (addInitScript).
+ */
+const rendersHookScript = `(() => {
+  const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  if (!hook || window.__NEXT_BROWSER_RENDERS_ACTIVE__) return;
+
+  const MAX_COMPONENTS = 200;
+  const data = {};
+  const fps = { frames: [], last: 0, rafId: 0 };
+
+  window.__NEXT_BROWSER_RENDERS__ = data;
+  window.__NEXT_BROWSER_RENDERS_FPS__ = fps;
+  window.__NEXT_BROWSER_RENDERS_START__ = performance.now();
+  window.__NEXT_BROWSER_RENDERS_ACTIVE__ = true;
+
+  // FPS tracking via requestAnimationFrame
+  function fpsLoop(now) {
+    if (fps.last > 0) fps.frames.push(now - fps.last);
+    fps.last = now;
+    fps.rafId = requestAnimationFrame(fpsLoop);
+  }
+  fps.rafId = requestAnimationFrame(fpsLoop);
+
+  const origOnCommit = hook.onCommitFiberRoot;
+  window.__NEXT_BROWSER_RENDERS_ORIG_COMMIT__ = origOnCommit;
+
+  hook.onCommitFiberRoot = function(rendererID, root) {
+    try { walkFiber(root.current); } catch {}
+    if (typeof origOnCommit === "function") {
+      return origOnCommit.apply(hook, arguments);
+    }
+  };
+
+  function getName(fiber) {
+    if (!fiber.type || typeof fiber.type === "string") return null;
+    return fiber.type.displayName || fiber.type.name || null;
+  }
+
+  function brief(val) {
+    if (val === undefined) return "undefined";
+    if (val === null) return "null";
+    if (typeof val === "function") return "fn()";
+    if (typeof val === "string") return val.length > 60 ? '"' + val.slice(0, 57) + '..."' : '"' + val + '"';
+    if (typeof val === "number" || typeof val === "boolean") return String(val);
+    if (Array.isArray(val)) return "Array(" + val.length + ")";
+    if (typeof val === "object") {
+      try {
+        const keys = Object.keys(val);
+        return keys.length <= 3 ? "{" + keys.join(", ") + "}" : "{" + keys.slice(0, 3).join(", ") + ", ...}";
+      } catch { return "{...}"; }
+    }
+    return String(val).slice(0, 40);
+  }
+
+  function getChanges(fiber) {
+    const changes = [];
+    const alt = fiber.alternate;
+    if (!alt) { changes.push({ type: "mount" }); return changes; }
+
+    // Props
+    if (fiber.memoizedProps !== alt.memoizedProps) {
+      const curr = fiber.memoizedProps || {};
+      const prev = alt.memoizedProps || {};
+      const allKeys = new Set([...Object.keys(curr), ...Object.keys(prev)]);
+      for (const k of allKeys) {
+        if (k !== "children" && curr[k] !== prev[k]) {
+          changes.push({ type: "props", name: k, prev: brief(prev[k]), next: brief(curr[k]) });
+        }
+      }
+    }
+
+    // State — walk memoizedState linked list
+    if (fiber.memoizedState !== alt.memoizedState) {
+      let curr = fiber.memoizedState;
+      let prev = alt.memoizedState;
+      let hookIdx = 0;
+      while (curr || prev) {
+        if (curr?.memoizedState !== prev?.memoizedState) {
+          changes.push({
+            type: "state", name: "hook #" + hookIdx,
+            prev: brief(prev?.memoizedState), next: brief(curr?.memoizedState)
+          });
+        }
+        curr = curr?.next;
+        prev = prev?.next;
+        hookIdx++;
+      }
+    }
+
+    // Context — walk dependencies linked list
+    if (fiber.dependencies?.firstContext) {
+      let ctx = fiber.dependencies.firstContext;
+      let altCtx = alt.dependencies?.firstContext;
+      while (ctx) {
+        if (!altCtx || ctx.memoizedValue !== altCtx?.memoizedValue) {
+          const ctxName = ctx.context?.displayName || ctx.context?.Provider?.displayName || "unknown";
+          changes.push({
+            type: "context", name: ctxName,
+            prev: brief(altCtx?.memoizedValue), next: brief(ctx.memoizedValue)
+          });
+        }
+        ctx = ctx.next;
+        altCtx = altCtx?.next;
+      }
+    }
+
+    if (changes.length === 0) {
+      // Find the nearest parent component name
+      let parent = fiber.return;
+      while (parent) {
+        const pName = getName(parent);
+        if (pName) {
+          const suffix = !parent.alternate ? " (mount)" : "";
+          changes.push({ type: "parent", name: pName + suffix });
+          break;
+        }
+        parent = parent.return;
+      }
+      if (changes.length === 0) changes.push({ type: "parent", name: "unknown" });
+    }
+
+    return changes;
+  }
+
+  function childrenTime(fiber) {
+    let t = 0;
+    let child = fiber.child;
+    while (child) {
+      if (typeof child.actualDuration === "number") t += child.actualDuration;
+      child = child.sibling;
+    }
+    return t;
+  }
+
+  function hasDomMutation(fiber) {
+    // Check if this fiber or any host (DOM) child has the Mutation flag (4)
+    // or Placement flag (2) or Update flag (4) in subtreeFlags/flags
+    if (!fiber.alternate) return true; // mount always mutates
+    let child = fiber.child;
+    while (child) {
+      if (typeof child.type === "string" && (child.flags & 6) > 0) return true;
+      child = child.sibling;
+    }
+    return false;
+  }
+
+  function walkFiber(fiber) {
+    if (!fiber) return;
+
+    const tag = fiber.tag;
+    if (tag === 0 || tag === 1 || tag === 2 || tag === 11 || tag === 15) {
+      const didRender =
+        fiber.alternate === null ||
+        fiber.flags > 0 ||
+        fiber.memoizedProps !== fiber.alternate?.memoizedProps ||
+        fiber.memoizedState !== fiber.alternate?.memoizedState;
+
+      if (didRender) {
+        const name = getName(fiber);
+        if (name) {
+          if (!(name in data) && Object.keys(data).length >= MAX_COMPONENTS) {
+            // skip — at cap
+          } else {
+            if (!data[name]) {
+              data[name] = {
+                count: 0, mounts: 0, totalTime: 0, selfTime: 0,
+                domMutations: 0, changes: [],
+                _instances: new Set()
+              };
+            }
+            data[name].count++;
+            if (!fiber.alternate) data[name].mounts++;
+            if (!data[name]._instances.has(fiber)) {
+              data[name]._instances.add(fiber);
+              if (fiber.alternate) data[name]._instances.add(fiber.alternate);
+            }
+            if (typeof fiber.actualDuration === "number") {
+              data[name].totalTime += fiber.actualDuration;
+              data[name].selfTime += Math.max(0, fiber.actualDuration - childrenTime(fiber));
+            }
+            if (hasDomMutation(fiber)) data[name].domMutations++;
+            const ch = getChanges(fiber);
+            // Keep last 50 change entries per component to cap memory
+            for (const c of ch) {
+              if (data[name].changes.length < 50) data[name].changes.push(c);
+            }
+          }
+        }
+      }
+    }
+
+    walkFiber(fiber.child);
+    walkFiber(fiber.sibling);
+  }
+})()`;
+/**
+ * Start recording React re-renders by hooking into onCommitFiberRoot.
+ * Installs via both addInitScript (survives navigations, captures mount)
+ * and page.evaluate (activates immediately on current page).
+ */
+export async function rendersStart() {
+    if (!page)
+        throw new Error("browser not open");
+    const ctx = page.context();
+    await ctx.addInitScript(rendersHookScript);
+    await page.evaluate(rendersHookScript);
+}
+/**
+ * Stop recording and return a per-component render profile with raw data.
+ */
+export async function rendersStop() {
+    if (!page)
+        throw new Error("browser not open");
+    return page.evaluate(() => {
+        const active = window.__NEXT_BROWSER_RENDERS_ACTIVE__;
+        if (!active)
+            throw new Error("renders recording not active — run `renders start` first");
+        const data = window.__NEXT_BROWSER_RENDERS__;
+        const startTime = window.__NEXT_BROWSER_RENDERS_START__;
+        const elapsed = performance.now() - startTime;
+        // Collect FPS data
+        const fpsData = window.__NEXT_BROWSER_RENDERS_FPS__;
+        let fpsStats = { avg: 0, min: 0, max: 0, drops: 0 };
+        if (fpsData) {
+            cancelAnimationFrame(fpsData.rafId);
+            if (fpsData.frames.length > 0) {
+                const fpsSamples = fpsData.frames.map((dt) => dt > 0 ? 1000 / dt : 0);
+                const sum = fpsSamples.reduce((a, b) => a + b, 0);
+                fpsStats = {
+                    avg: Math.round(sum / fpsSamples.length),
+                    min: Math.round(Math.min(...fpsSamples)),
+                    max: Math.round(Math.max(...fpsSamples)),
+                    drops: fpsSamples.filter((f) => f < 30).length,
+                };
+            }
+        }
+        // Restore original hook
+        const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+        const orig = window.__NEXT_BROWSER_RENDERS_ORIG_COMMIT__;
+        if (hook) {
+            hook.onCommitFiberRoot = orig || undefined;
+        }
+        delete window.__NEXT_BROWSER_RENDERS__;
+        delete window.__NEXT_BROWSER_RENDERS_START__;
+        delete window.__NEXT_BROWSER_RENDERS_ACTIVE__;
+        delete window.__NEXT_BROWSER_RENDERS_ORIG_COMMIT__;
+        delete window.__NEXT_BROWSER_RENDERS_FPS__;
+        if (!data)
+            return {
+                elapsed: 0,
+                fps: fpsStats,
+                totalRenders: 0,
+                totalMounts: 0,
+                totalReRenders: 0,
+                totalComponents: 0,
+                components: [],
+            };
+        const round = (n) => Math.round(n * 100) / 100;
+        const components = Object.entries(data)
+            .map(([name, entry]) => {
+            // Summarize changes: count by type+name for the table view
+            const summary = {};
+            for (const c of entry.changes) {
+                const key = c.type === "props" ? "props." + c.name
+                    : c.type === "state" ? "state (" + c.name + ")"
+                        : c.type === "context" ? "context (" + c.name + ")"
+                            : c.type === "parent" ? "parent (" + c.name + ")"
+                                : c.type;
+                summary[key] = (summary[key] || 0) + 1;
+            }
+            return {
+                name,
+                count: entry.count,
+                mounts: entry.mounts,
+                reRenders: entry.count - entry.mounts,
+                instanceCount: entry._instances.size,
+                totalTime: round(entry.totalTime),
+                selfTime: round(entry.selfTime),
+                domMutations: entry.domMutations,
+                changes: entry.changes,
+                changeSummary: summary,
+            };
+        })
+            .sort((a, b) => b.totalTime - a.totalTime || b.count - a.count);
+        const totalMounts = components.reduce((s, c) => s + c.mounts, 0);
+        return {
+            elapsed: round(elapsed / 1000),
+            fps: fpsStats,
+            totalRenders: components.reduce((s, c) => s + c.count, 0),
+            totalMounts,
+            totalReRenders: components.reduce((s, c) => s + c.reRenders, 0),
+            totalComponents: components.length,
+            components,
+        };
+    });
+}
 /** Get network request log, or detail for a specific request index. */
 export function network(idx) {
     return idx == null ? net.format() : net.detail(idx);
@@ -791,6 +1178,44 @@ async function launch() {
             return orig.apply(console, [label, ...args]);
         };
     });
+    // Intercept console.log/warn/error/info to capture browser console output.
+    // This works for both dev and prod builds — unlike `logs`/`errors` which
+    // rely on the Next.js dev server MCP endpoint.
+    await ctx.addInitScript(() => {
+        const MAX = 500;
+        const entries = [];
+        window.__NEXT_BROWSER_CONSOLE_LOGS__ = entries;
+        function safe(val) {
+            if (val === undefined)
+                return "undefined";
+            if (val === null)
+                return "null";
+            if (val instanceof Error)
+                return `${val.name}: ${val.message}`;
+            if (typeof val === "object") {
+                try {
+                    return JSON.stringify(val);
+                }
+                catch {
+                    return String(val);
+                }
+            }
+            return String(val);
+        }
+        for (const level of ["log", "warn", "error", "info"]) {
+            const orig = console[level];
+            console[level] = function (...args) {
+                entries.push({
+                    level,
+                    args: args.map(safe).join(" "),
+                    timestamp: performance.now(),
+                });
+                if (entries.length > MAX)
+                    entries.splice(0, entries.length - MAX);
+                return orig.apply(console, args);
+            };
+        }
+    });
     // Next.js devtools overlay is removed before each screenshot via hideDevOverlay().
     return ctx;
 }

package/dist/cli.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { send } from "./client.js";
 const args = process.argv.slice(2);
 const cmd = args[0];
@@ -120,16 +122,22 @@ 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 === "screenshot") {
-    const res = await send("screenshot");
+    const fullPage = args.includes("--full-page");
+    const caption = args.slice(1).filter((a) => a !== "--full-page").join(" ") || undefined;
+    const res = await send("screenshot", { fullPage, caption });
     exit(res, res.ok ? String(res.data) : "");
 }
 if (cmd === "snapshot") {
@@ -216,6 +224,113 @@ if (cmd === "logs") {
     console.log(content || "(log file is empty)");
     process.exit(0);
 }
+if (cmd === "browser-logs") {
+    const res = await send("browser-logs");
+    if (!res.ok)
+        exit(res, "");
+    const entries = res.data;
+    if (entries.length === 0) {
+        console.log("(no console output captured)");
+        process.exit(0);
+    }
+    const lines = entries.map((e) => `[${e.level.toUpperCase().padEnd(5)}] ${e.args}`);
+    const output = lines.join("\n");
+    if (output.length > 4000) {
+        const path = join(tmpdir(), `next-browser-console-${process.pid}.log`);
+        writeFileSync(path, output);
+        console.log(`(${entries.length} entries written to ${path})`);
+    }
+    else {
+        console.log(output);
+    }
+    process.exit(0);
+}
+if (cmd === "renders" && arg === "start") {
+    const res = await send("renders-start");
+    exit(res, "recording renders — interact with the page, then run `renders stop`");
+}
+if (cmd === "renders" && arg === "stop") {
+    const useJson = args.includes("--json");
+    const res = await send("renders-stop");
+    if (!res.ok)
+        exit(res, "");
+    const d = res.data;
+    if (d.components.length === 0) {
+        if (useJson)
+            console.log(JSON.stringify(d, null, 2));
+        else
+            console.log("(no renders captured)");
+        process.exit(0);
+    }
+    if (useJson) {
+        const output = JSON.stringify(d, null, 2);
+        if (output.length > 4000) {
+            const path = join(tmpdir(), `next-browser-renders-${process.pid}.json`);
+            writeFileSync(path, output);
+            console.log(path);
+        }
+        else {
+            console.log(output);
+        }
+        process.exit(0);
+    }
+    const lines = [
+        `# Render Profile — ${d.elapsed}s recording`,
+        `# ${d.totalRenders} renders (${d.totalMounts} mounts + ${d.totalReRenders} re-renders) across ${d.totalComponents} components`,
+        `# FPS: avg ${d.fps.avg}, min ${d.fps.min}, max ${d.fps.max}, drops (<30fps): ${d.fps.drops}`,
+        "",
+        "## Components by total render time",
+    ];
+    const nameW = Math.max(9, ...d.components.slice(0, 50).map((c) => c.name.length));
+    const header = `| ${"Component".padEnd(nameW)} | Insts | Mounts | Re-renders | Total    | Self     | DOM   | Top change reason          |`;
+    const sep = `| ${"-".repeat(nameW)} | ----- | ------ | ---------- | -------- | -------- | ----- | -------------------------- |`;
+    lines.push(header, sep);
+    for (const c of d.components.slice(0, 50)) {
+        const total = c.totalTime > 0 ? `${c.totalTime}ms` : "—";
+        const self = c.selfTime > 0 ? `${c.selfTime}ms` : "—";
+        const dom = `${c.domMutations}/${c.count}`;
+        const topChange = Object.entries(c.changeSummary).sort((a, b) => b[1] - a[1])[0];
+        const changeStr = topChange ? topChange[0] : "—";
+        lines.push(`| ${c.name.padEnd(nameW)} | ${String(c.instanceCount).padStart(5)} | ${String(c.mounts).padStart(6)} | ${String(c.reRenders).padStart(10)} | ${total.padStart(8)} | ${self.padStart(8)} | ${dom.padStart(5)} | ${changeStr.padEnd(26)} |`);
+    }
+    if (d.components.length > 50) {
+        lines.push(`... and ${d.components.length - 50} more`);
+    }
+    // Detail: show prev→next values for top components with non-mount changes
+    const detailed = d.components
+        .filter((c) => c.changes.some((ch) => ch.type !== "mount" && ch.type !== "parent"))
+        .slice(0, 15);
+    if (detailed.length > 0) {
+        lines.push("", "## Change details (prev → next)");
+        for (const c of detailed) {
+            lines.push(`  ${c.name}`);
+            // Deduplicate: show unique type+name combinations with their prev→next
+            const seen = new Set();
+            for (const ch of c.changes) {
+                if (ch.type === "mount" || ch.type === "parent")
+                    continue;
+                const key = `${ch.type}:${ch.name}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const label = ch.type === "props" ? `props.${ch.name}`
+                    : ch.type === "state" ? `state (${ch.name})`
+                        : `context (${ch.name})`;
+                lines.push(`    ${label}: ${ch.prev ?? "?"} → ${ch.next ?? "?"}`);
+            }
+        }
+    }
+    const output = lines.join("\n");
+    if (output.length > 4000) {
+        const path = join(tmpdir(), `next-browser-renders-${process.pid}.txt`);
+        writeFileSync(path, output);
+        console.log(`(${d.totalComponents} components written to ${path})`);
+    }
+    else {
+        console.log(output);
+    }
+    process.exit(0);
+}
 if (cmd === "action") {
     const res = await send("mcp", { tool: "get_server_action_by_id", args: { actionId: arg } });
     exit(res, res.ok ? json(res.data) : "");
@@ -317,11 +432,14 @@ 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" +
         "  perf [url]         profile page load (CWVs + React hydration timing)\n" +
+        "  renders start      start recording React re-renders\n" +
+        "  renders stop [--json]  stop and print render profile\n" +
         "  restart-server     restart the Next.js dev server (clears fs cache)\n" +
         "\n" +
         "  ppr lock           enter PPR instant-navigation mode\n" +
@@ -331,7 +449,7 @@ 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" +
+        "  screenshot [caption] [--full-page]  screenshot + Screenshot Log\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" +
@@ -341,6 +459,7 @@ function printUsage() {
         "\n" +
         "  errors             show build/runtime errors\n" +
         "  logs               show recent dev server log output\n" +
+        "  browser-logs       show browser console output (log/warn/error/info)\n" +
         "  network [idx]      list network requests, or inspect one\n" +
         "\n" +
         "  page               show current page segments and router info\n" +

package/dist/daemon.js

@@ -61,12 +61,24 @@ async function run(cmd) {
         const data = await browser.perf(cmd.url);
         return { ok: true, data };
     }
+    if (cmd.action === "browser-logs") {
+        const data = await browser.browserLogs();
+        return { ok: true, data };
+    }
+    if (cmd.action === "renders-start") {
+        await browser.rendersStart();
+        return { ok: true };
+    }
+    if (cmd.action === "renders-stop") {
+        const data = await browser.rendersStop();
+        return { ok: true, data };
+    }
     if (cmd.action === "restart") {
         const data = await browser.restart();
         return { ok: true, data };
     }
     if (cmd.action === "screenshot") {
-        const data = await browser.screenshot();
+        const data = await browser.screenshot({ fullPage: cmd.fullPage, caption: cmd.caption });
         return { ok: true, data };
     }
     if (cmd.action === "links") {
@@ -81,9 +93,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.4.0",
   "description": "Headed Playwright browser with React DevTools pre-loaded",
   "license": "MIT",
   "repository": {