@vercel/next-browser 0.1.8 → 0.3.0

package/dist/browser.js

@@ -29,6 +29,23 @@ let context = null;
 let page = null;
 let profileDirPath = null;
 let initialOrigin = null;
+let ssrLocked = false;
+let previewBrowser = null;
+let previewPage = null;
+let previewImages = [];
+/** Install or remove the script-blocking route handler based on ssrLocked. */
+async function syncSsrRoutes() {
+    if (!page)
+        return;
+    await page.unrouteAll({ behavior: "wait" });
+    if (ssrLocked) {
+        await page.route("**/*", (route) => {
+            if (route.request().resourceType() === "script")
+                return route.abort();
+            return route.continue();
+        });
+    }
+}
 // ── Browser lifecycle ────────────────────────────────────────────────────────
 /**
  * Launch the browser (if not already open) and optionally navigate to a URL.
@@ -36,11 +53,12 @@ let initialOrigin = null;
  * 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 (context) {
+        await close();
     }
+    context = await launch();
+    page = context.pages()[0] ?? (await context.newPage());
+    net.attach(page);
     if (url) {
         initialOrigin = new URL(url).origin;
         await page.goto(url, { waitUntil: "domcontentloaded" });
@@ -59,11 +77,16 @@ export async function cookies(cookies, domain) {
 }
 /** Close the browser and reset all state. */
 export async function close() {
+    await previewBrowser?.close().catch(() => { });
+    previewBrowser = null;
+    previewPage = null;
+    previewImages = [];
     await context?.close();
     context = null;
     page = null;
     release = null;
     settled = null;
+    ssrLocked = false;
     // Clean up temp profile directory.
     if (profileDirPath) {
         const { rmSync } = await import("node:fs");
@@ -88,7 +111,7 @@ export function lock() {
     if (!page)
         throw new Error("browser not open");
     if (release)
-        throw new Error("already locked");
+        return Promise.resolve();
     return new Promise((locked) => {
         settled = instant(page, () => {
             locked();
@@ -139,7 +162,7 @@ export async function unlock() {
     // 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 new Promise((r) => setTimeout(r, 2000));
+    await waitForDevToolsReconnect(page);
     // Wait for all boundaries to resolve after unlock.
     await waitForSuspenseToSettle(page);
     // Capture the fully-resolved state with rich suspendedBy data.
@@ -206,6 +229,48 @@ 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));
+    }
+}
+// ── SSR lock/unlock ──────────────────────────────────────────────────────────
+//
+// While SSR-locked, every navigation blocks external script resources so the
+// page renders only the server-side HTML shell (no React hydration, no client
+// bundles). Useful for inspecting raw SSR output across multiple navigations.
+/** Enter SSR-locked mode. All subsequent navigations block external scripts. */
+export async function ssrLock() {
+    if (!page)
+        throw new Error("browser not open");
+    if (ssrLocked)
+        return;
+    ssrLocked = true;
+    await syncSsrRoutes();
+}
+/** Exit SSR-locked mode. Re-enables external scripts. */
+export async function ssrUnlock() {
+    if (!page)
+        throw new Error("browser not open");
+    if (!ssrLocked)
+        return;
+    ssrLocked = false;
+    await syncSsrRoutes();
+}
 // ── Navigation ───────────────────────────────────────────────────────────────
 /** Hard reload the current page. Returns the URL after reload. */
 export async function reload() {
@@ -215,66 +280,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.
+ *
+ * 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()).
  *
- * Frame 0 is always the PPR shell. Remaining frames capture the transition
- * through hydration and data loading. Stops after 3s of no visual change.
+ * 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() {
-        await hideDevOverlay();
-        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.
@@ -345,30 +458,9 @@ export async function push(path) {
 /** 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");
-    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");
+        await open(undefined);
     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;
 }
@@ -425,15 +517,73 @@ async function formatSource([file, line, col]) {
     return `source: ${file}:${line}:${col}`;
 }
 // ── Utilities ────────────────────────────────────────────────────────────────
-/** Viewport screenshot saved to a temp file. Returns the file path. */
-export async function screenshot() {
+/** Take a screenshot and display it in a separate headed Chromium window.
+ *  Images accumulate across calls — use `clear` to reset. */
+export async function preview(caption, clear) {
+    if (!page)
+        throw new Error("browser not open");
+    if (clear)
+        previewImages = [];
+    const path = await screenshot();
+    const imgData = readFileSync(path).toString("base64");
+    const timestamp = new Date().toLocaleTimeString();
+    previewImages.unshift({ caption, imgData, timestamp });
+    const imagesHtml = previewImages
+        .map((img) => `<div style="padding:4px 12px;display:flex;align-items:baseline;gap:8px">` +
+        (img.caption
+            ? `<span style="font-size:14px">${escapeHtml(img.caption)}</span>`
+            : "") +
+        `<span style="font-size:11px;opacity:0.5">${escapeHtml(img.timestamp)}</span>` +
+        `</div>` +
+        `<img src="data:image/png;base64,${img.imgData}" style="display:block;max-width:100%">`)
+        .join(`<hr style="border:none;border-top:1px solid #333;margin:12px 0">`);
+    const html = `<html><head><title>next-browser preview</title></head>` +
+        `<body style="margin:0;background:#111;color:#fff;font-family:system-ui">` +
+        `<div style="padding:8px 12px;font-size:11px;opacity:0.5;text-transform:uppercase;letter-spacing:0.05em">next-browser preview</div>` +
+        `${imagesHtml}` +
+        `</body></html>`;
+    const htmlPath = path.replace(/\.png$/, ".html");
+    writeFileSync(htmlPath, html);
+    const target = `file://${htmlPath}`;
+    // Reuse existing preview window, or launch a new one.
+    if (previewPage && !previewPage.isClosed()) {
+        try {
+            await previewPage.goto(target);
+            await previewPage.bringToFront();
+            return path;
+        }
+        catch {
+            // Window was closed by user — fall through to launch a new one.
+            await previewBrowser?.close().catch(() => { });
+        }
+    }
+    const { mkdtempSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    const { tmpdir } = await import("node:os");
+    const userDataDir = mkdtempSync(join(tmpdir(), "nb-preview-"));
+    const ctx = await chromium.launchPersistentContext(userDataDir, {
+        headless: false,
+        args: [`--app=${target}`, "--window-size=820,640"],
+        viewport: null,
+    });
+    previewBrowser = ctx;
+    previewPage = ctx.pages()[0] ?? (await ctx.waitForEvent("page"));
+    await previewPage.waitForLoadState();
+    await previewPage.bringToFront();
+    return path;
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** Screenshot saved to a temp file. Returns the file path. */
+export async function screenshot(opts) {
     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 });
+    await page.screenshot({ path, fullPage: opts?.fullPage });
     return path;
 }
 /** Remove Next.js devtools overlay from the page before screenshots. */
@@ -444,10 +594,170 @@ async function hideDevOverlay() {
         document.querySelectorAll("[data-nextjs-dev-overlay]").forEach((el) => el.remove());
     }).catch(() => { });
 }
-/** Evaluate arbitrary JavaScript in the page context. */
-export async function evaluate(script) {
+// ── 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);
 }
 /**
@@ -534,11 +844,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;
 }