@vercel/next-browser 0.1.8 → 0.3.0

package/README.md

@@ -1,83 +1,184 @@
 # @vercel/next-browser
 
-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.
+React DevTools and the Next.js dev overlay as shell commands — component
+trees, props, hooks, PPR shells, errors, network, accessibility snapshots —
+structured text that agents can parse and act on.
 
-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
+An LLM can't click through a DevTools panel, but it can run
+`next-browser snapshot`, read the output, `click e3`, and keep going. 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.
 
 ## Getting started
 
-You don't install or run this directly. Your agent does.
+**As a skill** (recommended) — from your Next.js repo:
 
-1. **Add the skill to your project.** From your Next.js repo:
+```bash
+npx skills add vercel-labs/next-browser
+```
 
-   ```bash
-   npx skills add vercel-labs/next-browser
-   ```
+Works with Claude Code, Cursor, Cline, and [others](https://skills.sh).
+Start your agent in the project and type `/next-browser` to invoke the
+skill. It installs the CLI and Chromium if needed, asks for your dev server
+URL, and from there it's pair programming — tell it what you're debugging
+and it drives the browser for you.
 
-   Works with Claude Code, Cursor, Cline, and [others](https://skills.sh).
+**Manual install:**
 
-2. **Start your agent** in that project.
+```bash
+pnpm add -g @vercel/next-browser   # or npm, yarn
+playwright install chromium
+```
 
-3. **Type `/next-browser`** to invoke the skill.
+Requires Node >= 20.
 
-4. The skill checks for the CLI and **installs `@vercel/next-browser`
-   globally** if it's missing (plus `playwright install chromium`).
+## Commands
 
-5. It asks for your dev server URL and any cookies it needs, opens the
-   browser, and from there it's **pair programming** — tell it what you're
-   debugging and it drives the tree, navigates pages, inspects components,
-   and reads errors for you.
+### Browser lifecycle
 
-That's the whole flow. Run `npx skills upgrade` later to pull updates.
+| Command                              | Description                                        |
+| ------------------------------------ | -------------------------------------------------- |
+| `open <url> [--cookies-json <file>]` | Launch browser and navigate (with optional cookies) |
+| `close`                              | Close browser and kill daemon                      |
 
-The rest of this README documents the raw CLI for the rare case where you're
-scripting it yourself.
+### Navigation
 
----
+| Command            | Description                                               |
+| ------------------ | --------------------------------------------------------- |
+| `goto <url>`       | Full-page navigation (new document load)                  |
+| `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                                       |
+| `restart-server`   | Restart the Next.js dev server (clears caches)            |
 
-## Manual install
+### Inspection
+
+| Command           | Description                                                   |
+| ----------------- | ------------------------------------------------------------- |
+| `tree`            | Full React component tree (hierarchy, IDs, keys)              |
+| `tree <id>`       | Inspect one component (props, hooks, state, source location)  |
+| `snapshot`        | Accessibility tree with `[ref=eN]` markers on interactive elements |
+| `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)         |
+| `preview [caption]` | Screenshot + open in viewer window (accumulates across calls) |
+| `screenshot`      | Viewport PNG to a temp file (`--full-page` for entire page)   |
+
+### Interaction
+
+| Command                      | Description                                                |
+| ---------------------------- | ---------------------------------------------------------- |
+| `click <ref\|text\|selector>` | Click via real pointer events (works with Radix, Headless UI) |
+| `fill <ref\|selector> <value>` | Fill a text input or textarea                            |
+| `eval [ref] <script>`       | Run JS in page context (supports `--file` and stdin)       |
+| `viewport [WxH]`            | Show or set viewport size                                  |
+
+### Performance & PPR
+
+| Command        | Description                                                  |
+| -------------- | ------------------------------------------------------------ |
+| `perf [url]`   | Core Web Vitals + React hydration timing in one pass         |
+| `ppr lock`     | Freeze dynamic content to inspect the static shell           |
+| `ppr unlock`   | Resume dynamic content and print shell analysis              |
+
+### Next.js MCP
+
+| Command        | Description                                     |
+| -------------- | ----------------------------------------------- |
+| `page`         | Route segments for the current URL              |
+| `project`      | Project root and dev server URL                 |
+| `routes`       | All app router routes                           |
+| `action <id>`  | Inspect a server action by ID                   |
+
+## Examples
+
+**Inspect what's on the page and interact with it:**
 
-```bash
-pnpm add -g @vercel/next-browser
+```
+$ next-browser open http://localhost:3000
+$ next-browser snapshot
+- navigation "Main"
+  - link "Home" [ref=e0]
+  - link "Dashboard" [ref=e1]
+- main
+  - heading "Settings"
+  - tablist
+    - tab "General" [ref=e2] (selected)
+    - tab "Security" [ref=e3]
+
+$ next-browser click e3
+clicked
+
+$ next-browser snapshot
+- tablist
+  - tab "General" [ref=e0]
+  - tab "Security" [ref=e1] (selected)
 ```
 
-Requires Node `>=20`.
+**Profile page load performance:**
 
-## Commands
+```
+$ next-browser perf http://localhost:3000/dashboard
+# Page Load Profile — http://localhost:3000/dashboard
+
+## Core Web Vitals
+  TTFB                   42ms
+  LCP               1205.3ms (img: /_next/image?url=...)
+  CLS                    0.03
+
+## React Hydration — 65.5ms (466.2ms → 531.7ms)
+  Hydrated                         65.5ms  (466.2 → 531.7)
+  Commit                            2.0ms  (531.7 → 533.7)
+  ...
+```
+
+**Debug the PPR shell:**
 
 ```
-open <url> [--cookies-json <file>]  launch browser and navigate
-close              close browser and daemon
-
-goto <url>         full-page navigation (new document load)
-ssr-goto <url>     goto but block external scripts (SSR shell)
-push [path]        client-side navigation (interactive picker if no path)
-back               go back in history
-reload             reload current page
-capture-goto [url] capture loading sequence (PPR shell → hydration → data)
-restart-server     restart the Next.js dev server (clears fs cache)
-
-ppr lock           enter PPR instant-navigation mode (requires cacheComponents)
-ppr unlock         exit PPR mode and show shell analysis
-
-tree               show React component tree
-tree <id>          inspect component (props, hooks, state, source)
-
-viewport [WxH]     show or set viewport size (e.g. 1280x720)
-screenshot         save full-page screenshot to tmp file
-eval <script>      evaluate JS in page context
-
-errors             show build/runtime errors
-logs               show recent dev server log output
-network [idx]      list network requests, or inspect one
+$ next-browser ppr lock
+locked
+$ next-browser goto http://localhost:3000/dashboard
+$ 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
+
+## Quick Reference
+| Boundary              | Type      | Primary blocker           | Source              |
+| ---                   | ---       | ---                       | ---                 |
+| TrackedSuspense       | component | usePathname (client-hook) | tracked-suspense.js |
 ```
 
+**Inspect a React component:**
+
+```
+$ next-browser tree
+0 38167 - Root
+1 38168 38167 HeadManagerContext.Provider
+2 38169 38168 Root
+...
+224 46375 46374 DeploymentsProvider
+
+$ next-browser tree 46375
+path: Root > ... > DeploymentsProvider
+DeploymentsProvider #46375
+props:
+  children: [<Lazy />, <Lazy />, <span />, <Lazy />, <Lazy />]
+hooks:
+  IsMobile: undefined (1 sub)
+  Router: undefined (2 sub)
+source: app/.../deployments/_parts/context.tsx:180:10
+```
+
+## How it works
+
+A daemon process launches Chromium with the React DevTools extension
+pre-loaded and listens on a Unix domain socket (named pipe on Windows).
+CLI commands send JSON-RPC messages to the daemon and print the response.
+The browser stays open across commands — no per-command startup cost.
+
 ## License
 
 MIT