@vercel/next-browser 0.1.0 → 0.1.1

package/README.md

@@ -1,28 +1,32 @@
 # @vercel/next-browser
 
-Headed Chromium with React DevTools pre-loaded, driven over a stateless CLI.
-Built for debugging Next.js PPR shells and React component trees.
+Programmatic access to React DevTools and the Next.js dev server. Everything
+you'd click through in a GUI — component trees, props, hooks, PPR shells,
+build errors, Suspense boundaries — exposed as shell commands that return
+structured text.
 
-Stateless CLI → stateful daemon over a Unix socket. The daemon holds the
-browser open between commands, so each CLI invocation is instant.
+Built for agents. An LLM can't read a DevTools panel, but it can run
+`next-browser tree`, parse the output, and decide what to inspect next. Each
+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
 
 ```bash
-pnpm add -D @vercel/next-browser
+pnpm add -g @vercel/next-browser
 ```
 
-Requires Node `>=22.18` (native TypeScript stripping, no build step).
+Requires Node `>=20`.
 
 ## Usage
 
 ```bash
-npx next-browser open http://localhost:3000
-npx next-browser tree
-npx next-browser ppr lock
-npx next-browser push /dashboard
-npx next-browser ppr unlock
-npx next-browser close
+next-browser open http://localhost:3000
+next-browser tree
+next-browser ppr lock
+next-browser push /dashboard
+next-browser ppr unlock
+next-browser close
 ```
 
 ## Commands
@@ -51,20 +55,6 @@ logs               show recent dev server log output
 network [idx]      list network requests, or inspect one
 ```
 
-## How it works
-
-- Daemon spawns on first CLI call, listens on `~/.next-browser/default.sock`
-- Chromium launched via `launchPersistentContext` with the React DevTools
-  extension sideloaded (`--load-extension`)
-- `installHook.js` pre-injected via `addInitScript` to beat the content-script
-  race — DevTools hook is always available on first render
-- Component tree read directly from `__REACT_DEVTOOLS_GLOBAL_HOOK__` by
-  intercepting the `operations` wire format
-- Source locations resolved via Next's `/__nextjs_original-stack-frames`
-  endpoint, falling back to raw source-map lookup for framework code
-- PPR lock holds `@next/playwright`'s `instant()` callback open across CLI
-  calls so you can poke at the frozen shell interactively
-
 ## License
 
 MIT

package/dist/browser.js

@@ -0,0 +1,377 @@
+/**
+ * Browser manager — single headed Chromium instance with React DevTools.
+ *
+ * Launches via Playwright with the React DevTools Chrome extension pre-loaded
+ * and --auto-open-devtools-for-tabs so the extension activates naturally.
+ * 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 { join, resolve } from "node:path";
+import { chromium } from "playwright";
+import { instant } from "@next/playwright";
+import * as componentTree from "./tree.js";
+import * as suspenseTree from "./suspense.js";
+import * as sourcemap from "./sourcemap.js";
+import * as nextMcp from "./mcp.js";
+import * as net from "./network.js";
+// React DevTools extension — vendored or overridden via env var.
+const extensionPath = process.env.REACT_DEVTOOLS_EXTENSION ??
+    resolve(import.meta.dirname, "../extensions/react-devtools-chrome");
+// Pre-read the hook script so it's ready for addInitScript on launch.
+const installHook = readFileSync(join(extensionPath, "build", "installHook.js"), "utf-8");
+let context = null;
+let page = null;
+// ── Browser lifecycle ────────────────────────────────────────────────────────
+/**
+ * Launch the browser (if not already open) and optionally navigate to a URL.
+ * The first call spawns Chromium with the DevTools extension; subsequent calls
+ * 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 (url) {
+        await page.goto(url, { waitUntil: "domcontentloaded" });
+    }
+}
+/**
+ * Set cookies on the browser context. Must be called after open() but before
+ * navigating to the target page, so the cookies are present on the first request.
+ * Accepts the same {name, value}[] format as ppr-optimizer's AUTH_COOKIES.
+ */
+export async function cookies(cookies, domain) {
+    if (!context)
+        throw new Error("browser not open");
+    await context.addCookies(cookies.map((c) => ({ name: c.name, value: c.value, domain, path: "/" })));
+    return cookies.length;
+}
+/** Close the browser and reset all state. */
+export async function close() {
+    await context?.close();
+    context = null;
+    page = null;
+    release = null;
+    settled = null;
+}
+// ── PPR lock/unlock ──────────────────────────────────────────────────────────
+//
+// The lock uses @next/playwright's `instant()` which sets the
+// `next-instant-navigation-testing=1` cookie. While locked:
+//   - goto: server sends the raw PPR shell (static HTML + <template> holes)
+//   - push: Next.js router blocks dynamic data writes, shows prefetched shell
+//
+// The lock is held by stashing instant()'s inner promise resolver (`release`).
+// Calling unlock() resolves it, which lets instant() finish and clear the cookie.
+let release = null;
+let settled = null;
+/** Enter PPR instant-navigation mode. The cookie is set immediately. */
+export function lock() {
+    if (!page)
+        throw new Error("browser not open");
+    if (release)
+        throw new Error("already locked");
+    return new Promise((locked) => {
+        settled = instant(page, () => {
+            locked();
+            return new Promise((r) => (release = r));
+        });
+    });
+}
+/**
+ * Exit PPR mode and produce a shell analysis report.
+ *
+ * Two-phase capture:
+ *   1. LOCKED snapshot — which boundaries are currently suspended (= holes in the shell).
+ *      Waits for the suspended count to stabilize first, so fast-resolving boundaries
+ *      (e.g. a feature flag guard that completes in <100ms) don't get falsely reported.
+ *      Falls back to counting <template id="B:..."> DOM elements for the goto case
+ *      where React DevTools can't inspect the production-like shell.
+ *
+ *   2. Release the lock. For push: dynamic content streams in (no reload).
+ *      For goto: cookie cleared → page auto-reloads.
+ *
+ *   3. UNLOCKED snapshot — all boundaries resolved, with full suspendedBy data
+ *      (what blocked each one: hooks, server calls, cache, scripts, etc.)
+ *
+ *   4. Match locked holes against unlocked data by JSX source location,
+ *      producing the final "Dynamic holes / Static" report.
+ */
+export async function unlock() {
+    if (!release)
+        return null;
+    if (!page)
+        return null;
+    const origin = new URL(page.url()).origin;
+    // Wait for the suspended boundary count to stop changing. This filters out
+    // boundaries that suspend briefly then resolve (e.g. fast flag checks) —
+    // only truly stuck boundaries remain as "holes."
+    await stabilizeSuspenseState(page);
+    // Capture what's suspended right now under the lock.
+    let locked = await suspenseTree.snapshot(page).catch(() => []);
+    // For initial-load (goto) under lock, DevTools may not be connected —
+    // the shell uses a production-like renderer. Fall back to counting
+    // <template id="B:..."> elements in the DOM (PPR's Suspense placeholders).
+    const hasDevToolsData = locked.some((b) => b.parentID !== 0);
+    if (!hasDevToolsData) {
+        locked = await suspenseTree.snapshotFromDom(page);
+    }
+    // Release the lock. instant() clears the cookie.
+    // - push case: dynamic content streams in immediately (no reload)
+    // - goto case: cookieStore change → auto-reload → full page load
+    release();
+    release = null;
+    await settled;
+    settled = null;
+    // Wait for all boundaries to resolve after unlock.
+    // Polls the DevTools suspense tree (works for both push and goto cases).
+    await waitForSuspenseToSettle(page);
+    // Capture the fully-resolved state with rich suspendedBy data.
+    const unlocked = await suspenseTree.snapshot(page).catch(() => []);
+    if (locked.length === 0 && unlocked.length === 0)
+        return null;
+    return suspenseTree.formatAnalysis(unlocked, locked, origin);
+}
+/**
+ * Wait for the suspended boundary count to stop changing.
+ *
+ * Polls every 300ms. Returns once two consecutive polls show the same
+ * suspended count. This lets fast-resolving boundaries (feature flag guards,
+ * instant cache hits) settle before we snapshot — preventing false positives
+ * where a boundary appears as a "hole" but resolves before the shell paints.
+ */
+async function stabilizeSuspenseState(p) {
+    const deadline = Date.now() + 5_000;
+    let lastSuspended = -1;
+    await new Promise((r) => setTimeout(r, 300));
+    while (Date.now() < deadline) {
+        const { suspended } = await suspenseTree.countBoundaries(p);
+        if (suspended === lastSuspended)
+            return;
+        lastSuspended = suspended;
+        await new Promise((r) => setTimeout(r, 300));
+    }
+}
+/**
+ * Wait for all Suspense boundaries to resolve after unlock.
+ *
+ * Used after releasing the PPR lock. For push: dynamic content streams in
+ * via JS. For goto: the page auto-reloads after the cookie clears.
+ * In both cases, we poll the DevTools suspense tree until no boundaries
+ * are suspended (or timeout after 10s).
+ *
+ * Tracks whether we've ever seen boundaries — if DevTools never reports any
+ * (e.g. during a goto reload where it takes time to reconnect), we wait up
+ * to 5s for them to appear before giving up.
+ */
+async function waitForSuspenseToSettle(p) {
+    const deadline = Date.now() + 10_000;
+    await new Promise((r) => setTimeout(r, 500));
+    let sawBoundaries = false;
+    while (Date.now() < deadline) {
+        const { total, suspended } = await suspenseTree.countBoundaries(p);
+        if (total > 0) {
+            sawBoundaries = true;
+            if (suspended === 0)
+                return;
+        }
+        else if (!sawBoundaries && Date.now() > deadline - 5000) {
+            return;
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+}
+// ── Navigation ───────────────────────────────────────────────────────────────
+/** Hard reload the current page. Returns the URL after reload. */
+export async function reload() {
+    if (!page)
+        throw new Error("browser not open");
+    await page.reload({ waitUntil: "domcontentloaded" });
+    return page.url();
+}
+/**
+ * Restart the Next.js dev server via its internal endpoint, then reload.
+ * Polls /__nextjs_server_status until the executionId changes (new process).
+ */
+export async function restart() {
+    if (!page)
+        throw new Error("browser not open");
+    const origin = new URL(page.url()).origin;
+    const before = await executionId(origin);
+    const url = `${origin}/__nextjs_restart_dev?invalidateFileSystemCache=1`;
+    await fetch(url, { method: "POST" }).catch(() => { });
+    const deadline = Date.now() + 30_000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 1_000));
+        const after = await executionId(origin).catch(() => null);
+        if (after != null && after !== before)
+            break;
+    }
+    await page.reload({ waitUntil: "domcontentloaded" });
+    return page.url();
+}
+async function executionId(origin) {
+    const res = await fetch(`${origin}/__nextjs_server_status`);
+    const data = (await res.json());
+    return data.executionId;
+}
+/**
+ * Collect all same-origin <a> links on the current page.
+ * Used by the interactive `push` picker — shows what routes are navigable
+ * from the current page (i.e. have <Link> components that trigger prefetch).
+ */
+export async function links() {
+    if (!page)
+        throw new Error("browser not open");
+    return page.evaluate(() => {
+        const origin = location.origin;
+        const seen = new Set();
+        const results = [];
+        for (const a of document.querySelectorAll("a[href]")) {
+            const url = new URL(a.getAttribute("href"), location.href);
+            if (url.origin !== origin)
+                continue;
+            const path = url.pathname + url.search + url.hash;
+            if (seen.has(path) || path === location.pathname)
+                continue;
+            seen.add(path);
+            const text = (a.textContent || "").trim().slice(0, 80);
+            results.push({ href: path, text });
+        }
+        return results;
+    });
+}
+/**
+ * Client-side navigation via Next.js router.push().
+ * Requires the target route to be prefetched (a <Link> must exist on the
+ * current page pointing to it). If the route isn't prefetched, push silently
+ * fails and returns the current URL unchanged.
+ */
+export async function push(path) {
+    if (!page)
+        throw new Error("browser not open");
+    const before = page.url();
+    await page.evaluate((p) => window.next.router.push(p), path);
+    await page.waitForURL((u) => u.href !== before, { timeout: 10_000 }).catch(() => { });
+    return page.url();
+}
+/** 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");
+    const target = new URL(url, page.url()).href;
+    await page.goto(target, { waitUntil: "domcontentloaded" });
+    return target;
+}
+/** Go back in browser history. */
+export async function back() {
+    if (!page)
+        throw new Error("browser not open");
+    await page.goBack({ waitUntil: "domcontentloaded" });
+}
+// ── React component tree ─────────────────────────────────────────────────────
+let lastSnapshot = [];
+/**
+ * Get the full React component tree via DevTools' flushInitialOperations().
+ * Decodes TREE_OPERATION_ADD entries from the operations wire format into
+ * a flat node list with depth/id/parent/name columns.
+ */
+export async function tree() {
+    if (!page)
+        throw new Error("browser not open");
+    lastSnapshot = await componentTree.snapshot(page);
+    return componentTree.format(lastSnapshot);
+}
+/**
+ * Inspect a single component by fiber ID. Returns props, hooks, state,
+ * ownership chain, and source-mapped file location. Uses the last tree
+ * snapshot to build the ancestor path.
+ */
+export async function node(id) {
+    if (!page)
+        throw new Error("browser not open");
+    const { text, source } = await componentTree.inspect(page, id);
+    const lines = [];
+    const path = componentTree.path(lastSnapshot, id);
+    if (path)
+        lines.push(`path: ${path}`);
+    lines.push(text);
+    if (source)
+        lines.push(await formatSource(source));
+    return lines.join("\n");
+}
+/**
+ * Resolve a bundled source location to its original file via source maps.
+ * Tries the Next.js dev server endpoint first (resolves user code),
+ * then falls back to fetching .map files directly (handles node_modules).
+ */
+async function formatSource([file, line, col]) {
+    const origin = new URL(page.url()).origin;
+    const resolved = await sourcemap.resolve(origin, file, line, col);
+    if (resolved)
+        return `source: ${resolved.file}:${resolved.line}:${resolved.column}`;
+    const viaMap = await sourcemap.resolveViaMap(origin, file, line, col);
+    if (viaMap)
+        return `source: ${viaMap.file}:${viaMap.line}:${viaMap.column}`;
+    return `source: ${file}:${line}:${col}`;
+}
+// ── Utilities ────────────────────────────────────────────────────────────────
+/** Full-page screenshot saved to a temp file. Returns the file path. */
+export async function screenshot() {
+    if (!page)
+        throw new Error("browser not open");
+    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: true });
+    return path;
+}
+/** Evaluate arbitrary JavaScript in the page context. */
+export async function evaluate(script) {
+    if (!page)
+        throw new Error("browser not open");
+    return page.evaluate(script);
+}
+/** Call a Next.js dev server MCP tool (JSON-RPC over SSE at /_next/mcp). */
+export async function mcp(tool, args) {
+    if (!page)
+        throw new Error("browser not open");
+    const origin = new URL(page.url()).origin;
+    return nextMcp.call(origin, tool, args);
+}
+/** Get network request log, or detail for a specific request index. */
+export function network(idx) {
+    return idx == null ? net.format() : net.detail(idx);
+}
+// ── Browser launch ───────────────────────────────────────────────────────────
+/**
+ * Launch Chromium with React DevTools extension.
+ *
+ * - launchPersistentContext("") — empty user data dir (fresh profile each time)
+ * - --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)
+ * - waitForEvent("serviceworker") ensures the extension's background script
+ *   is running before we navigate
+ * - addInitScript(installHook) injects the DevTools hook before any page JS,
+ *   winning the race against the extension's content script
+ */
+async function launch() {
+    const ctx = await chromium.launchPersistentContext("", {
+        headless: false,
+        viewport: null,
+        args: [
+            `--disable-extensions-except=${extensionPath}`,
+            `--load-extension=${extensionPath}`,
+            "--auto-open-devtools-for-tabs",
+        ],
+    });
+    await ctx.waitForEvent("serviceworker");
+    await ctx.addInitScript(installHook);
+    return ctx;
+}

package/dist/cli.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { send } from "./client.js";
+const args = process.argv.slice(2);
+const cmd = args[0];
+const arg = args[1];
+if (cmd === "--help" || cmd === "-h" || !cmd) {
+    printUsage();
+    process.exit(0);
+}
+if (cmd === "open") {
+    if (!arg) {
+        console.error("usage: next-browser open <url> [--cookies-json <file>]");
+        process.exit(1);
+    }
+    const cookieIdx = args.indexOf("--cookies-json");
+    const cookieFile = cookieIdx >= 0 ? args[cookieIdx + 1] : undefined;
+    if (cookieFile) {
+        const res = await send("open");
+        if (!res.ok)
+            exit(res, "");
+        const raw = readFileSync(cookieFile, "utf-8");
+        const cookies = JSON.parse(raw);
+        const domain = new URL(arg).hostname;
+        const cRes = await send("cookies", { cookies, domain });
+        if (!cRes.ok)
+            exit(cRes, "");
+        await send("goto", { url: arg });
+        exit(res, `opened → ${arg} (${cookies.length} cookies for ${domain})`);
+    }
+    const res = await send("open", { url: arg });
+    exit(res, `opened → ${arg}`);
+}
+if (cmd === "ppr" && arg === "lock") {
+    const res = await send("lock");
+    exit(res, "locked");
+}
+if (cmd === "ppr" && arg === "unlock") {
+    const res = await send("unlock");
+    exit(res, res.ok && res.data ? `unlocked\n\n${res.data}` : "unlocked");
+}
+if (cmd === "reload") {
+    const res = await send("reload");
+    exit(res, res.ok ? `reloaded → ${res.data}` : "");
+}
+if (cmd === "restart-server") {
+    const res = await send("restart");
+    exit(res, res.ok ? `restarted → ${res.data}` : "");
+}
+if (cmd === "push") {
+    if (arg) {
+        const res = await send("push", { url: arg });
+        exit(res, res.ok ? `→ ${res.data}` : "");
+    }
+    const linksRes = await send("links");
+    if (!linksRes.ok)
+        exit(linksRes, "");
+    const links = linksRes.data;
+    if (links.length === 0) {
+        console.error("no links on current page");
+        process.exit(1);
+    }
+    const picked = await pick(links.map((l) => `${l.href}  ${l.text}`));
+    const res = await send("push", { url: links[picked].href });
+    exit(res, res.ok ? `→ ${res.data}` : "");
+}
+if (cmd === "goto") {
+    const res = await send("goto", { url: arg });
+    exit(res, res.ok ? `→ ${res.data}` : "");
+}
+if (cmd === "back") {
+    const res = await send("back");
+    exit(res, "back");
+}
+if (cmd === "screenshot") {
+    const res = await send("screenshot");
+    exit(res, res.ok ? String(res.data) : "");
+}
+if (cmd === "eval") {
+    if (!arg) {
+        console.error("usage: next-browser eval <script>");
+        process.exit(1);
+    }
+    const res = await send("eval", { script: arg });
+    exit(res, res.ok ? json(res.data) : "");
+}
+if (cmd === "tree") {
+    const res = arg != null
+        ? await send("node", { nodeId: Number(arg) })
+        : await send("tree");
+    exit(res, res.ok ? String(res.data) : "");
+}
+const mcpTools = {
+    errors: "get_errors",
+    page: "get_page_metadata",
+    project: "get_project_metadata",
+    routes: "get_routes",
+};
+if (cmd in mcpTools) {
+    const res = await send("mcp", { tool: mcpTools[cmd] });
+    exit(res, res.ok ? json(res.data) : "");
+}
+if (cmd === "logs") {
+    const res = await send("mcp", { tool: "get_logs" });
+    if (!res.ok)
+        exit(res, "");
+    const data = res.data;
+    if (!data?.logFilePath)
+        exit(res, json(data));
+    const content = readTail(data.logFilePath, 100);
+    console.log(content || "(log file is empty)");
+    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) : "");
+}
+if (cmd === "network") {
+    const res = await send("network", arg != null ? { idx: Number(arg) } : {});
+    exit(res, res.ok ? String(res.data) : "");
+}
+if (cmd === "close") {
+    const res = await send("close");
+    exit(res, "closed");
+}
+console.error(`unknown command: ${cmd}\n`);
+printUsage();
+process.exit(1);
+function exit(res, message) {
+    if (res.ok) {
+        console.log(message);
+        process.exit(0);
+    }
+    console.error(`error: ${res.error}`);
+    process.exit(1);
+}
+function json(data) {
+    return JSON.stringify(data, null, 2);
+}
+function readTail(path, lines) {
+    try {
+        const content = readFileSync(path, "utf-8");
+        const all = content.split("\n");
+        return all.slice(-lines).join("\n").trim();
+    }
+    catch {
+        return `(could not read ${path})`;
+    }
+}
+function pick(items) {
+    return new Promise((resolve) => {
+        let idx = 0;
+        const render = () => {
+            process.stdout.write("\x1B[?25l");
+            for (let i = 0; i < items.length; i++) {
+                if (i > 0)
+                    process.stdout.write("\n");
+                process.stdout.write(i === idx ? `\x1B[36m❯ ${items[i]}\x1B[0m` : `  ${items[i]}`);
+            }
+            process.stdout.write(`\x1B[${items.length - 1}A\r`);
+        };
+        render();
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on("data", (key) => {
+            const k = key.toString();
+            if (k === "\x1B[A" && idx > 0) {
+                idx--;
+                process.stdout.write(`\r\x1B[J`);
+                render();
+            }
+            else if (k === "\x1B[B" && idx < items.length - 1) {
+                idx++;
+                process.stdout.write(`\r\x1B[J`);
+                render();
+            }
+            else if (k === "\r" || k === "\n") {
+                process.stdin.setRawMode(false);
+                process.stdin.pause();
+                process.stdout.write(`\r\x1B[J\x1B[?25h`);
+                resolve(idx);
+            }
+            else if (k === "\x03" || k === "q") {
+                process.stdout.write(`\r\x1B[J\x1B[?25h`);
+                process.exit(0);
+            }
+        });
+    });
+}
+function printUsage() {
+    console.error("usage: next-browser <command> [args]\n" +
+        "\n" +
+        "  open <url> [--cookies-json <file>]  launch browser and navigate\n" +
+        "  close              close browser and daemon\n" +
+        "\n" +
+        "  goto <url>         full-page navigation (new document load)\n" +
+        "  push [path]        client-side navigation (interactive picker if no path)\n" +
+        "  back               go back in history\n" +
+        "  reload             reload current page\n" +
+        "  restart-server     restart the Next.js dev server (clears fs cache)\n" +
+        "\n" +
+        "  ppr lock           enter PPR instant-navigation mode\n" +
+        "  ppr unlock         exit PPR mode and show shell analysis\n" +
+        "\n" +
+        "  tree               show React component tree\n" +
+        "  tree <id>          inspect component (props, hooks, state, source)\n" +
+        "\n" +
+        "  screenshot         save full-page screenshot to tmp file\n" +
+        "  eval <script>      evaluate JS in page context\n" +
+        "\n" +
+        "  errors             show build/runtime errors\n" +
+        "  logs               show recent dev server log output\n" +
+        "  network [idx]      list network requests, or inspect one\n" +
+        "\n" +
+        "  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");
+}