@vercel/next-browser 0.1.0 → 0.1.1

package/src/browser.ts

@@ -1,408 +0,0 @@
-/**
- * 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, type BrowserContext, type Page } from "playwright";
-import { instant } from "@next/playwright";
-import * as componentTree from "./tree.ts";
-import * as suspenseTree from "./suspense.ts";
-import * as sourcemap from "./sourcemap.ts";
-import * as nextMcp from "./mcp.ts";
-import * as net from "./network.ts";
-
-// 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: BrowserContext | null = null;
-let page: Page | null = 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: string | undefined) {
-  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: { name: string; value: string }[], domain: string) {
-  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: (() => void) | null = null;
-let settled: Promise<void> | null = 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<void>((locked) => {
-    settled = instant(page!, () => {
-      locked();
-      return new Promise<void>((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(() => [] as suspenseTree.Boundary[]);
-
-  // 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(() => [] as suspenseTree.Boundary[]);
-
-  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: Page) {
-  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: Page) {
-  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: string) {
-  const res = await fetch(`${origin}/__nextjs_server_status`);
-  const data = (await res.json()) as { executionId: number };
-  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<string>();
-    const results: { href: string; text: string }[] = [];
-    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: string) {
-  if (!page) throw new Error("browser not open");
-  const before = page.url();
-  await page.evaluate((p) => (window as any).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: string) {
-  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: componentTree.Node[] = [];
-
-/**
- * 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: number) {
-  if (!page) throw new Error("browser not open");
-  const { text, source } = await componentTree.inspect(page, id);
-
-  const lines: string[] = [];
-  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]: [string, number, number]) {
-  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: string) {
-  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: string, args?: Record<string, unknown>) {
-  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?: number) {
-  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/src/cli.ts

@@ -1,233 +0,0 @@
-#!/usr/bin/env node
-import { readFileSync } from "node:fs";
-import { send } from "./client.ts";
-
-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 as { href: string; text: string }[];
-  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: Record<string, string> = {
-  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 as { logFilePath?: string };
-  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: { ok: true; data?: unknown } | { ok: false; error: string }, message: string): never {
-  if (res.ok) {
-    console.log(message);
-    process.exit(0);
-  }
-  console.error(`error: ${res.error}`);
-  process.exit(1);
-}
-
-function json(data: unknown) {
-  return JSON.stringify(data, null, 2);
-}
-
-function readTail(path: string, lines: number): string {
-  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: string[]): Promise<number> {
-  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: Buffer) => {
-      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",
-  );
-}