@vercel/next-browser 0.1.7 → 0.2.0

package/dist/browser.js

@@ -10,7 +10,7 @@
  *
  * Module-level state: one browser context, one page, one PPR lock.
  */
-import { readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { readFileSync, mkdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { chromium } from "playwright";
@@ -126,14 +126,9 @@ export async function unlock() {
     // 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);
-    }
+    // Under goto + lock, DevTools may not be connected (shell is static HTML).
+    // That's fine — we get all the rich data from the unlocked snapshot below.
+    const locked = await suspenseTree.snapshot(page).catch(() => []);
     // 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
@@ -141,14 +136,26 @@ export async function unlock() {
     release = null;
     await settled;
     settled = null;
+    // For goto case: the page auto-reloads. Wait for the new page to load
+    // and React/DevTools to reconnect before trying to snapshot boundaries.
+    await page.waitForLoadState("load").catch(() => { });
+    await waitForDevToolsReconnect(page);
     // 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);
+    if (locked.length === 0 && unlocked.length === 0) {
+        return { text: "No suspense boundaries detected.", boundaries: unlocked, locked, report: null };
+    }
+    const report = await suspenseTree.analyzeBoundaries(unlocked, locked, origin);
+    const pageMetadata = await nextMcp
+        .call(initialOrigin ?? origin, "get_page_metadata")
+        .catch(() => null);
+    if (pageMetadata) {
+        suspenseTree.annotateReportWithPageMetadata(report, pageMetadata);
+    }
+    const text = suspenseTree.formatReport(report);
+    return { text, boundaries: unlocked, locked, report };
 }
 /**
  * Wait for the suspended boundary count to stop changing.
@@ -199,6 +206,25 @@ async function waitForSuspenseToSettle(p) {
         await new Promise((r) => setTimeout(r, 500));
     }
 }
+/**
+ * Wait for React DevTools to reconnect after a page reload.
+ *
+ * After the goto case unlocks, the page auto-reloads and DevTools loses its
+ * renderer connection. Poll until the DevTools hook reports at least one
+ * renderer, or bail after 5s. This replaces the old hardcoded 2s sleep.
+ */
+async function waitForDevToolsReconnect(p) {
+    const deadline = Date.now() + 5_000;
+    while (Date.now() < deadline) {
+        const connected = await p.evaluate(() => {
+            const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+            return hook?.rendererInterfaces?.size > 0;
+        }).catch(() => false);
+        if (connected)
+            return;
+        await new Promise((r) => setTimeout(r, 200));
+    }
+}
 // ── Navigation ───────────────────────────────────────────────────────────────
 /** Hard reload the current page. Returns the URL after reload. */
 export async function reload() {
@@ -208,65 +234,114 @@ export async function reload() {
     return page.url();
 }
 /**
- * Reload the page while capturing screenshots every ~150ms.
- * Stops when: load has fired AND no new layout-shift entries for 2s.
- * Hard timeout at 30s. Returns the list of screenshot paths plus any
- * LayoutShift entries observed during the reload.
- */
-/**
- * Lock PPR → goto → screenshot the shell → unlock → screenshot frames
- * until the page settles. Just PNGs in a directory — the AI reads them.
+ * Profile a page load: reload (or navigate to a URL) and collect Core Web
+ * Vitals (LCP, CLS, TTFB) plus React hydration timing.
  *
- * Frame 0 is always the PPR shell. Remaining frames capture the transition
- * through hydration and data loading. Stops after 3s of no visual change.
+ * CWVs come from PerformanceObserver and Navigation Timing API.
+ * Hydration timing comes from console.timeStamp entries emitted by React's
+ * profiling build (see the addInitScript interceptor in launch()).
+ *
+ * Returns structured data that the CLI formats into a readable report.
  */
-export async function captureGoto(url) {
+export async function perf(url) {
     if (!page)
         throw new Error("browser not open");
     const targetUrl = url || page.url();
-    const dir = join(tmpdir(), `next-browser-capture-goto-${Date.now()}`);
-    mkdirSync(dir, { recursive: true });
-    let frameIdx = 0;
-    async function snap() {
-        const path = join(dir, `frame-${String(frameIdx).padStart(4, "0")}.png`);
-        const buf = await page.screenshot({ path }).catch(() => null);
-        frameIdx++;
-        return buf;
+    // Install CWV observers before navigation so they capture everything.
+    await page.evaluate(() => {
+        window.__NEXT_BROWSER_REACT_TIMING__ = [];
+        const cwv = { lcp: null, cls: 0, clsEntries: [] };
+        window.__NEXT_BROWSER_CWV__ = cwv;
+        // Largest Contentful Paint
+        new PerformanceObserver((list) => {
+            const entries = list.getEntries();
+            if (entries.length > 0) {
+                const last = entries[entries.length - 1];
+                cwv.lcp = {
+                    startTime: Math.round(last.startTime * 100) / 100,
+                    size: last.size,
+                    element: last.element?.tagName?.toLowerCase() ?? null,
+                    url: last.url || null,
+                };
+            }
+        }).observe({ type: "largest-contentful-paint", buffered: true });
+        // Cumulative Layout Shift
+        new PerformanceObserver((list) => {
+            for (const entry of list.getEntries()) {
+                if (!entry.hadRecentInput) {
+                    cwv.cls += entry.value;
+                    cwv.clsEntries.push({
+                        value: Math.round(entry.value * 10000) / 10000,
+                        startTime: Math.round(entry.startTime * 100) / 100,
+                    });
+                }
+            }
+        }).observe({ type: "layout-shift", buffered: true });
+    });
+    // Navigate or reload to trigger a full page load.
+    if (url) {
+        await page.goto(targetUrl, { waitUntil: "load" });
     }
-    // PPR shell: lock suppresses hydration.
-    await lock();
-    await page.goto(targetUrl, { waitUntil: "load" }).catch(() => { });
-    await new Promise((r) => setTimeout(r, 300));
-    await snap();
-    // Unlock → page reloads, hydrates, loads data.
-    const unlockDone = unlock();
-    await new Promise((r) => setTimeout(r, 200));
-    let lastChangeTime = Date.now();
-    let prevHash = "";
-    const SETTLE_MS = 3_000;
-    const HARD_TIMEOUT = 30_000;
-    const start = Date.now();
-    while (true) {
-        const buf = await snap();
-        let hash = "";
-        if (buf) {
-            let h = 0;
-            for (let i = 0; i < buf.length; i += 200)
-                h = ((h << 5) - h + buf[i]) | 0;
-            hash = String(h);
-        }
-        if (hash !== prevHash) {
-            lastChangeTime = Date.now();
-            prevHash = hash;
-        }
-        if (Date.now() - start > HARD_TIMEOUT)
-            break;
-        if (lastChangeTime > 0 && Date.now() - lastChangeTime > SETTLE_MS)
-            break;
-        await new Promise((r) => setTimeout(r, 150));
+    else {
+        await page.reload({ waitUntil: "load" });
     }
-    await unlockDone.catch(() => { });
-    return { dir, frames: frameIdx };
+    // Wait for passive effects, late paints, and layout shifts to flush.
+    await new Promise((r) => setTimeout(r, 3000));
+    // Collect all metrics from the page.
+    const metrics = await page.evaluate(() => {
+        const cwv = window.__NEXT_BROWSER_CWV__ ?? {};
+        const timing = window.__NEXT_BROWSER_REACT_TIMING__ ?? [];
+        // TTFB from Navigation Timing API.
+        const nav = performance.getEntriesByType("navigation")[0];
+        const ttfb = nav
+            ? Math.round((nav.responseStart - nav.requestStart) * 100) / 100
+            : null;
+        return { cwv, timing, ttfb };
+    });
+    // Process React hydration timing.
+    const phases = metrics.timing.filter((e) => e.trackGroup === "Scheduler ⚛" && e.endTime > e.startTime);
+    const components = metrics.timing.filter((e) => e.track === "Components ⚛" && e.endTime > e.startTime);
+    const hydrationPhases = phases.filter((e) => e.label === "Hydrated");
+    const hydratedComponents = components.filter((e) => e.color?.startsWith("tertiary"));
+    let hydrationStart = Infinity;
+    let hydrationEnd = 0;
+    for (const p of hydrationPhases) {
+        if (p.startTime < hydrationStart)
+            hydrationStart = p.startTime;
+        if (p.endTime > hydrationEnd)
+            hydrationEnd = p.endTime;
+    }
+    const round = (n) => Math.round(n * 100) / 100;
+    return {
+        url: targetUrl,
+        ttfb: metrics.ttfb,
+        lcp: metrics.cwv.lcp,
+        cls: {
+            score: round(metrics.cwv.cls),
+            entries: metrics.cwv.clsEntries,
+        },
+        hydration: hydrationPhases.length > 0
+            ? {
+                startTime: round(hydrationStart),
+                endTime: round(hydrationEnd),
+                duration: round(hydrationEnd - hydrationStart),
+            }
+            : null,
+        phases: phases.map((p) => ({
+            label: p.label,
+            startTime: round(p.startTime),
+            endTime: round(p.endTime),
+            duration: round(p.endTime - p.startTime),
+        })),
+        hydratedComponents: hydratedComponents
+            .map((c) => ({
+            name: c.label,
+            startTime: round(c.startTime),
+            endTime: round(c.endTime),
+            duration: round(c.endTime - c.startTime),
+        }))
+            .sort((a, b) => b.duration - a.duration),
+    };
 }
 /**
  * Restart the Next.js dev server via its internal endpoint, then reload.
@@ -338,11 +413,32 @@ export async function push(path) {
 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");
+    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;
+}
 /** Go back in browser history. */
 export async function back() {
     if (!page)
@@ -396,20 +492,189 @@ async function formatSource([file, line, col]) {
     return `source: ${file}:${line}:${col}`;
 }
 // ── Utilities ────────────────────────────────────────────────────────────────
-/** Full-page screenshot saved to a temp file. Returns the file path. */
+/** Viewport screenshot saved to a temp file. Returns the file path. */
 export async function screenshot() {
     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, fullPage: true });
+    await page.screenshot({ path });
     return path;
 }
-/** Evaluate arbitrary JavaScript in the page context. */
-export async function evaluate(script) {
+/** Remove Next.js devtools overlay from the page before screenshots. */
+async function hideDevOverlay() {
+    if (!page)
+        return;
+    await page.evaluate(() => {
+        document.querySelectorAll("[data-nextjs-dev-overlay]").forEach((el) => el.remove());
+    }).catch(() => { });
+}
+// ── Ref map for interactive elements ──────────────────────────────────
+const INTERACTIVE_ROLES = new Set([
+    "button", "link", "textbox", "checkbox", "radio", "combobox", "listbox",
+    "menuitem", "menuitemcheckbox", "menuitemradio", "option", "searchbox",
+    "slider", "spinbutton", "switch", "tab", "treeitem",
+]);
+let refMap = [];
+/**
+ * Snapshot the accessibility tree via CDP and return a text representation
+ * with [ref=e0], [ref=e1] … markers on interactive elements.
+ * Stores a ref map so that `click("e3")` can resolve back to role+name.
+ */
+export async function snapshot() {
+    if (!page)
+        throw new Error("browser not open");
+    const cdp = await page.context().newCDPSession(page);
+    try {
+        const { nodes } = (await cdp.send("Accessibility.getFullAXTree"));
+        // Index nodes by ID
+        const byId = new Map();
+        for (const n of nodes)
+            byId.set(n.nodeId, n);
+        refMap = [];
+        const roleNameCount = new Map();
+        const lines = [];
+        function walk(node, depth) {
+            const role = node.role?.value || "unknown";
+            const name = (node.name?.value || "").trim().slice(0, 80);
+            const isInteractive = INTERACTIVE_ROLES.has(role);
+            // Read properties into a map
+            const propMap = new Map();
+            for (const p of node.properties || [])
+                propMap.set(p.name, p.value.value);
+            const ignored = propMap.get("hidden") === true;
+            if (ignored)
+                return;
+            // Always skip leaf text nodes — parent already carries the text
+            if (role === "InlineTextBox" || role === "StaticText" || role === "LineBreak")
+                return;
+            // Skip generic/none wrappers with no name — just recurse children
+            const SKIP_ROLES = new Set(["none", "generic", "GenericContainer"]);
+            if (SKIP_ROLES.has(role) && !name) {
+                for (const id of node.childIds || []) {
+                    const child = byId.get(id);
+                    if (child)
+                        walk(child, depth);
+                }
+                return;
+            }
+            // Skip root WebArea — just recurse
+            if (role === "WebArea" || role === "RootWebArea") {
+                for (const id of node.childIds || []) {
+                    const child = byId.get(id);
+                    if (child)
+                        walk(child, depth);
+                }
+                return;
+            }
+            const indent = "  ".repeat(depth);
+            let line = `${indent}- ${role}`;
+            if (name)
+                line += ` "${name}"`;
+            const disabled = propMap.get("disabled") === true;
+            if (isInteractive && !disabled) {
+                const key = `${role}::${name}`;
+                const count = roleNameCount.get(key) || 0;
+                roleNameCount.set(key, count + 1);
+                const ref = { role, name };
+                if (count > 0)
+                    ref.nth = count;
+                const idx = refMap.length;
+                refMap.push(ref);
+                line += ` [ref=e${idx}]`;
+            }
+            // Append state properties
+            const tags = [];
+            if (propMap.get("checked") === "true" || propMap.get("checked") === true)
+                tags.push("checked");
+            if (propMap.get("checked") === "mixed")
+                tags.push("mixed");
+            if (disabled)
+                tags.push("disabled");
+            if (propMap.get("expanded") === true)
+                tags.push("expanded");
+            if (propMap.get("expanded") === false)
+                tags.push("collapsed");
+            if (propMap.get("selected") === true)
+                tags.push("selected");
+            if (tags.length)
+                line += ` (${tags.join(", ")})`;
+            lines.push(line);
+            for (const id of node.childIds || []) {
+                const child = byId.get(id);
+                if (child)
+                    walk(child, depth + 1);
+            }
+        }
+        // Start from the root (first node)
+        if (nodes.length)
+            walk(nodes[0], 0);
+        return lines.join("\n");
+    }
+    finally {
+        await cdp.detach();
+    }
+}
+/** Resolve a ref (e.g. "e3") or selector string to a Playwright Locator. */
+function resolveLocator(selectorOrRef) {
     if (!page)
         throw new Error("browser not open");
+    const refMatch = selectorOrRef.match(/^e(\d+)$/);
+    if (refMatch) {
+        const idx = Number(refMatch[1]);
+        const ref = refMap[idx];
+        if (!ref)
+            throw new Error(`ref e${idx} not found — run snapshot first`);
+        const locator = page.getByRole(ref.role, {
+            name: ref.name,
+            exact: true,
+        });
+        return ref.nth != null ? locator.nth(ref.nth) : locator;
+    }
+    const hasPrefix = /^(css=|text=|role=|#|\[|\.|\w+\s*>)/.test(selectorOrRef);
+    return page.locator(hasPrefix ? selectorOrRef : `text=${selectorOrRef}`);
+}
+/**
+ * Click an element using real pointer events.
+ * Accepts: "e3" (ref from snapshot), plain text, or Playwright selectors.
+ */
+export async function click(selectorOrRef) {
+    if (!page)
+        throw new Error("browser not open");
+    await resolveLocator(selectorOrRef).click();
+}
+/**
+ * Fill a text input/textarea. Clears existing value, then types the new one.
+ * Accepts: "e3" (ref from snapshot), or a selector.
+ */
+export async function fill(selectorOrRef, value) {
+    if (!page)
+        throw new Error("browser not open");
+    await resolveLocator(selectorOrRef).fill(value);
+}
+/**
+ * Evaluate arbitrary JavaScript in the page context.
+ * If ref is provided (e.g. "e3"), the script receives the DOM element as its
+ * first argument: `next-browser eval e3 'el => el.textContent'`
+ */
+export async function evaluate(script, ref) {
+    if (!page)
+        throw new Error("browser not open");
+    if (ref) {
+        const locator = resolveLocator(ref);
+        const handle = await locator.elementHandle();
+        if (!handle)
+            throw new Error(`ref ${ref} not found in DOM`);
+        // The script should be an arrow/function that receives the element.
+        // We wrap it so page.evaluate can pass the element handle as an arg.
+        return page.evaluate(([fn, el]) => {
+            // eslint-disable-next-line no-eval
+            const f = (0, eval)(fn);
+            return f(el);
+        }, [script, handle]);
+    }
     return page.evaluate(script);
 }
 /**
@@ -496,10 +761,36 @@ async function launch() {
     profileDirPath = dir;
     const ctx = await chromium.launchPersistentContext(dir, {
         headless,
-        viewport: { width: 1440, height: 900 },
+        viewport: null,
         // --no-sandbox is required when Chrome runs as root (common in containers/cloud sandboxes)
-        args: headless ? ["--no-sandbox"] : [],
+        args: [
+            ...(headless ? ["--no-sandbox"] : []),
+            "--window-size=1440,900",
+        ],
     });
     await ctx.addInitScript(installHook);
+    // Intercept console.timeStamp to capture React's Performance Track entries.
+    // React's profiling build calls console.timeStamp(label, startTime, endTime,
+    // track, trackGroup, color) for render phases and per-component timing.
+    // startTime/endTime are performance.now() values from the reconciler.
+    await ctx.addInitScript(() => {
+        const entries = [];
+        window.__NEXT_BROWSER_REACT_TIMING__ = entries;
+        const orig = console.timeStamp;
+        console.timeStamp = function (label, ...args) {
+            if (typeof label === "string" && args.length >= 2 && typeof args[0] === "number") {
+                entries.push({
+                    label,
+                    startTime: args[0],
+                    endTime: args[1],
+                    track: args[2] ?? "",
+                    trackGroup: args[3] ?? "",
+                    color: args[4] ?? "",
+                });
+            }
+            return orig.apply(console, [label, ...args]);
+        };
+    });
+    // Next.js devtools overlay is removed before each screenshot via hideDevOverlay().
     return ctx;
 }

package/dist/cli.js

@@ -43,20 +43,57 @@ if (cmd === "ppr" && arg === "lock") {
 }
 if (cmd === "ppr" && arg === "unlock") {
     const res = await send("unlock");
-    exit(res, res.ok && res.data ? `unlocked\n\n${res.data}` : "unlocked");
+    const d = res.ok ? res.data : null;
+    const text = typeof d === "string" ? d : d?.text ?? "";
+    exit(res, res.ok ? `unlocked${text ? `\n\n${text}` : ""}` : "unlocked");
 }
 if (cmd === "reload") {
     const res = await send("reload");
     exit(res, res.ok ? `reloaded → ${res.data}` : "");
 }
-if (cmd === "capture-goto") {
-    const res = await send("capture-goto", arg ? { url: arg } : {});
+if (cmd === "perf") {
+    const res = await send("perf", arg ? { url: arg } : {});
     if (!res.ok)
         exit(res, "");
-    const data = res.data;
-    exit(res, `${data.frames} frames → ${data.dir}\n` +
-        "\n" +
-        "frame-0000.png is the PPR shell. Remaining frames capture hydration → data.");
+    const d = res.data;
+    const lines = [`# Page Load Profile — ${d.url}`, ""];
+    // Core Web Vitals
+    lines.push("## Core Web Vitals");
+    const ttfbStr = d.ttfb != null ? `${d.ttfb}ms` : "—";
+    lines.push(`  TTFB              ${ttfbStr.padStart(10)}`);
+    if (d.lcp) {
+        const lcpLabel = d.lcp.element ? ` (${d.lcp.element}${d.lcp.url ? `: ${d.lcp.url.slice(0, 60)}` : ""})` : "";
+        lines.push(`  LCP               ${String(d.lcp.startTime + "ms").padStart(10)}${lcpLabel}`);
+    }
+    else {
+        lines.push(`  LCP                        —`);
+    }
+    lines.push(`  CLS               ${String(d.cls.score).padStart(10)}`);
+    lines.push("");
+    // React Hydration
+    if (d.hydration) {
+        lines.push(`## React Hydration — ${d.hydration.duration}ms (${d.hydration.startTime}ms → ${d.hydration.endTime}ms)`);
+    }
+    else {
+        lines.push("## React Hydration — no data (requires profiling build)");
+    }
+    if (d.phases.length > 0) {
+        for (const p of d.phases) {
+            lines.push(`  ${p.label.padEnd(28)} ${String(p.duration + "ms").padStart(10)}  (${p.startTime} → ${p.endTime})`);
+        }
+        lines.push("");
+    }
+    if (d.hydratedComponents.length > 0) {
+        lines.push(`## Hydrated components (${d.hydratedComponents.length} total, sorted by duration)`);
+        const top = d.hydratedComponents.slice(0, 30);
+        for (const c of top) {
+            lines.push(`  ${c.name.padEnd(40)} ${String(c.duration + "ms").padStart(10)}`);
+        }
+        if (d.hydratedComponents.length > 30) {
+            lines.push(`  ... and ${d.hydratedComponents.length - 30} more`);
+        }
+    }
+    exit(res, lines.join("\n"));
 }
 if (cmd === "restart-server") {
     const res = await send("restart");
@@ -83,6 +120,10 @@ 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 === "back") {
     const res = await send("back");
     exit(res, "back");
@@ -91,12 +132,61 @@ if (cmd === "screenshot") {
     const res = await send("screenshot");
     exit(res, res.ok ? String(res.data) : "");
 }
-if (cmd === "eval") {
+if (cmd === "snapshot") {
+    const res = await send("snapshot");
+    exit(res, res.ok ? json(res.data) : "");
+}
+if (cmd === "click") {
     if (!arg) {
-        console.error("usage: next-browser eval <script>");
+        console.error("usage: next-browser click <ref|text|selector>");
+        process.exit(1);
+    }
+    const res = await send("click", { selector: arg });
+    exit(res, "clicked");
+}
+if (cmd === "fill") {
+    const value = args[2];
+    if (!arg || value === undefined) {
+        console.error("usage: next-browser fill <ref|selector> <value>");
+        process.exit(1);
+    }
+    const res = await send("fill", { selector: arg, value });
+    exit(res, "filled");
+}
+if (cmd === "eval") {
+    // Check if first arg is a ref (e.g. "e3") — if so, second arg is the script
+    let ref;
+    let scriptArg = arg;
+    let fileArgIdx = 2;
+    if (arg && /^e\d+$/.test(arg)) {
+        ref = arg;
+        scriptArg = args[2];
+        fileArgIdx = 3;
+    }
+    let script;
+    if (scriptArg === "--file" || scriptArg === "-f") {
+        const filePath = args[fileArgIdx];
+        if (!filePath) {
+            console.error("usage: next-browser eval [ref] --file <path>");
+            process.exit(1);
+        }
+        script = readFileSync(filePath, "utf-8");
+    }
+    else if (scriptArg === "-") {
+        // Read from stdin
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        script = Buffer.concat(chunks).toString("utf-8");
+    }
+    else {
+        script = scriptArg;
+    }
+    if (!script) {
+        console.error("usage: next-browser eval [ref] <script>\n       next-browser eval [ref] --file <path>\n       echo 'script' | next-browser eval -");
         process.exit(1);
     }
-    const res = await send("eval", { script: arg });
+    const res = await send("eval", { script, ...(ref ? { selector: ref } : {}) });
     exit(res, res.ok ? json(res.data) : "");
 }
 if (cmd === "tree") {
@@ -227,10 +317,11 @@ 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" +
         "  push [path]        client-side navigation (interactive picker if no path)\n" +
         "  back               go back in history\n" +
         "  reload             reload current page\n" +
-        "  capture-goto [url]   capture loading sequence (PPR shell → hydration → data)\n" +
+        "  perf [url]         profile page load (CWVs + React hydration timing)\n" +
         "  restart-server     restart the Next.js dev server (clears fs cache)\n" +
         "\n" +
         "  ppr lock           enter PPR instant-navigation mode\n" +
@@ -241,7 +332,12 @@ function printUsage() {
         "\n" +
         "  viewport [WxH]     show or set viewport size (e.g. 1280x720)\n" +
         "  screenshot         save full-page screenshot to tmp file\n" +
-        "  eval <script>      evaluate JS in page context\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" +
+        "  eval [ref] <script> evaluate JS in page context\n" +
+        "  eval --file <path> evaluate JS from a file\n" +
+        "  eval -             evaluate JS from stdin\n" +
         "\n" +
         "  errors             show build/runtime errors\n" +
         "  logs               show recent dev server log output\n" +