@vercel/next-browser 0.1.1 → 0.1.3

package/README.md

@@ -10,25 +10,45 @@ Built for agents. An LLM can't read a DevTools panel, but it can run
 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
+## Getting started
 
-```bash
-pnpm add -g @vercel/next-browser
-```
+You don't install or run this directly. Your agent does.
 
-Requires Node `>=20`.
+1. **Add the skill to your project.** From your Next.js repo:
+
+   ```bash
+   npx skills add vercel-labs/next-browser
+   ```
+
+   Works with Claude Code, Cursor, Cline, and [others](https://skills.sh).
+
+2. **Start your agent** in that project.
+
+3. **Type `/next-browser`** to invoke the skill.
 
-## Usage
+4. The skill checks for the CLI and **installs `@vercel/next-browser`
+   globally** if it's missing (plus `playwright install chromium`).
+
+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.
+
+That's the whole flow. Run `npx skills upgrade` later to pull updates.
+
+The rest of this README documents the raw CLI for the rare case where you're
+scripting it yourself.
+
+---
+
+## Manual install
 
 ```bash
-next-browser open http://localhost:3000
-next-browser tree
-next-browser ppr lock
-next-browser push /dashboard
-next-browser ppr unlock
-next-browser close
+pnpm add -g @vercel/next-browser
 ```
 
+Requires Node `>=20`.
+
 ## Commands
 
 ```
@@ -41,7 +61,7 @@ back               go back in history
 reload             reload current page
 restart-server     restart the Next.js dev server (clears fs cache)
 
-ppr lock           enter PPR instant-navigation mode
+ppr lock           enter PPR instant-navigation mode (requires cacheComponents)
 ppr unlock         exit PPR mode and show shell analysis
 
 tree               show React component tree

package/dist/sourcemap.js

@@ -24,6 +24,23 @@ export async function resolve(origin, file, line, column) {
         return null;
     return { file: frame.file, line: frame.line1, column: frame.column1 };
 }
+import { resolve as resolvePath } from "node:path";
+import * as mcp from "./mcp.js";
+const projectRoots = new Map();
+async function projectRoot(origin) {
+    if (projectRoots.has(origin))
+        return projectRoots.get(origin);
+    const meta = await mcp.call(origin, "get_project_metadata").catch(() => null);
+    const root = typeof meta?.projectPath === "string" ? meta.projectPath : null;
+    projectRoots.set(origin, root);
+    return root;
+}
+async function absolutize(origin, path) {
+    if (path.startsWith("/") || path.startsWith("node_modules/"))
+        return path;
+    const root = await projectRoot(origin);
+    return root ? resolvePath(root, path) : path;
+}
 function normalize(file, origin) {
     const stripped = file.replace(/^about:\/\/React\/[^/]+\//, "");
     const isServer = file !== stripped;
@@ -48,7 +65,7 @@ export async function resolveViaMap(origin, file, line, column) {
     const pos = consumer.originalPositionFor({ line, column });
     if (!pos.source)
         return null;
-    return { file: cleanPath(pos.source), line: pos.line, column: pos.column };
+    return { file: await absolutize(origin, cleanPath(pos.source)), line: pos.line, column: pos.column };
 }
 async function load(origin, path) {
     if (consumers.has(path))

package/dist/suspense.js

@@ -276,10 +276,7 @@ async function inPageSuspense(inspect) {
                 const awaited = entry?.awaited;
                 if (!awaited)
                     continue;
-                const desc = awaited.description
-                    || awaited.value?.value
-                    || awaited.value?.preview_long
-                    || "";
+                const desc = preview(awaited.description) || preview(awaited.value);
                 boundary.suspendedBy.push({
                     name: awaited.name ?? "unknown",
                     description: desc,
@@ -311,4 +308,25 @@ async function inPageSuspense(inspect) {
             }
         }
     }
+    function preview(v) {
+        if (v == null)
+            return "";
+        if (typeof v === "string")
+            return v;
+        if (typeof v !== "object")
+            return String(v);
+        if (typeof v.preview_long === "string")
+            return v.preview_long;
+        if (typeof v.preview_short === "string")
+            return v.preview_short;
+        if (typeof v.value === "string")
+            return v.value;
+        try {
+            const s = JSON.stringify(v);
+            return s.length > 80 ? s.slice(0, 77) + "..." : s;
+        }
+        catch {
+            return "";
+        }
+    }
 }

package/package.json

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