@vercel/next-browser 0.1.6 → 0.1.8

package/README.md

@@ -56,6 +56,7 @@ 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

package/dist/browser.js

@@ -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 new Promise((r) => setTimeout(r, 2000));
     // 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.
@@ -228,6 +235,7 @@ export async function captureGoto(url) {
     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++;
@@ -336,10 +344,31 @@ 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");
     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;
 }
@@ -396,16 +425,25 @@ 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;
 }
+/** 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(() => { });
+}
 /** Evaluate arbitrary JavaScript in the page context. */
 export async function evaluate(script) {
     if (!page)
@@ -501,5 +539,6 @@ async function launch() {
         args: headless ? ["--no-sandbox"] : [],
     });
     await ctx.addInitScript(installHook);
+    // Next.js devtools overlay is removed before each screenshot via hideDevOverlay().
     return ctx;
 }

package/dist/cli.js

@@ -18,6 +18,7 @@ if (cmd === "open") {
         console.error("usage: next-browser open <url> [--cookies-json <file>]");
         process.exit(1);
     }
+    const url = /^https?:\/\//.test(arg) ? arg : `http://${arg}`;
     const cookieIdx = args.indexOf("--cookies-json");
     const cookieFile = cookieIdx >= 0 ? args[cookieIdx + 1] : undefined;
     if (cookieFile) {
@@ -26,15 +27,15 @@ if (cmd === "open") {
             exit(res, "");
         const raw = readFileSync(cookieFile, "utf-8");
         const cookies = JSON.parse(raw);
-        const domain = new URL(arg).hostname;
+        const domain = new URL(url).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})`);
+        await send("goto", { url });
+        exit(res, `opened → ${url} (${cookies.length} cookies for ${domain})`);
     }
-    const res = await send("open", { url: arg });
-    exit(res, `opened → ${arg}`);
+    const res = await send("open", { url });
+    exit(res, `opened → ${url}`);
 }
 if (cmd === "ppr" && arg === "lock") {
     const res = await send("lock");
@@ -42,7 +43,9 @@ 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");
@@ -82,6 +85,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");
@@ -226,6 +233,7 @@ 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" +

package/dist/daemon.js

@@ -81,6 +81,10 @@ async function run(cmd) {
         const data = await browser.goto(cmd.url);
         return { ok: true, data };
     }
+    if (cmd.action === "ssr-goto") {
+        const data = await browser.ssrGoto(cmd.url);
+        return { ok: true, data };
+    }
     if (cmd.action === "back") {
         await browser.back();
         return { ok: true };

package/dist/mcp.js

@@ -27,5 +27,12 @@ export async function call(origin, tool, args = {}) {
     if (parsed.error)
         throw new Error(parsed.error.message);
     const text = parsed.result?.content?.[0]?.text;
-    return text ? JSON.parse(text) : parsed.result;
+    if (!text)
+        return parsed.result;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
 }

package/dist/suspense.js

@@ -7,46 +7,24 @@ export async function countBoundaries(page) {
     const nonRoot = boundaries.filter((b) => b.parentID !== 0);
     return { total: nonRoot.length, suspended: nonRoot.filter((b) => b.isSuspended).length };
 }
-export async function snapshotFromDom(page) {
-    const count = await page.evaluate(() => document.querySelectorAll('template[id^="B:"]').length).catch(() => 0);
-    const boundaries = [];
-    for (let i = 0; i < count; i++) {
-        boundaries.push({
-            id: -(i + 1),
-            parentID: 1,
-            name: `shell-hole-${i}`,
-            isSuspended: true,
-            environments: [],
-            suspendedBy: [],
-            unknownSuspenders: null,
-            owners: [],
-            jsxSource: null,
-        });
-    }
-    return boundaries;
-}
 export async function formatAnalysis(unlocked, locked, origin) {
+    const report = await analyzeBoundaries(unlocked, locked, origin);
+    return formatReport(report);
+}
+export async function analyzeBoundaries(unlocked, locked, origin) {
     await resolveSources(unlocked, origin);
     await resolveSources(locked, origin);
-    const fromDom = locked.length > 0 && locked[0].id < 0;
     const holes = [];
     const statics = [];
-    if (fromDom) {
-        const dynamicUnlocked = unlocked.filter((b) => b.parentID !== 0 && b.suspendedBy.length > 0);
-        for (const lb of locked) {
-            const match = dynamicUnlocked.shift();
-            holes.push({ shell: lb, full: match });
-        }
-        for (const ub of unlocked) {
-            if (ub.parentID !== 0 && ub.suspendedBy.length === 0)
-                statics.push(ub);
-        }
-    }
-    else {
+    const hasLockedData = locked.some((b) => b.parentID !== 0);
+    if (hasLockedData) {
+        // DevTools was connected during lock — match locked vs unlocked by key
         const unlockedByKey = new Map();
         for (const b of unlocked)
             unlockedByKey.set(boundaryKey(b), b);
         for (const lb of locked) {
+            if (lb.parentID === 0)
+                continue;
             if (lb.isSuspended) {
                 holes.push({ shell: lb, full: unlockedByKey.get(boundaryKey(lb)) });
             }
@@ -55,49 +33,470 @@ export async function formatAnalysis(unlocked, locked, origin) {
             }
         }
     }
-    const totalBoundaries = fromDom ? holes.length + statics.length : locked.length;
+    else {
+        // DevTools wasn't connected during lock (goto case) — derive from unlocked.
+        // Boundaries with suspendedBy data were dynamic holes in the shell.
+        for (const b of unlocked) {
+            if (b.parentID === 0)
+                continue;
+            if (b.suspendedBy.length > 0 || b.unknownSuspenders) {
+                holes.push({ shell: b, full: b });
+            }
+            else {
+                statics.push(b);
+            }
+        }
+    }
+    const holeInsights = holes
+        .map(({ shell, full }) => buildBoundaryInsight(shell, full ?? shell))
+        .sort(compareBoundaryInsights);
+    const staticSummaries = statics.map((b) => ({
+        id: b.id,
+        name: b.name,
+        source: b.jsxSource,
+        renderedBy: b.owners,
+    }));
+    const rootCauses = buildRootCauseGroups(holeInsights);
+    const filesToRead = collectFilesToRead(holeInsights, rootCauses);
+    return {
+        totalBoundaries: holeInsights.length + staticSummaries.length,
+        dynamicHoleCount: holeInsights.length,
+        staticCount: staticSummaries.length,
+        holes: holeInsights,
+        statics: staticSummaries,
+        rootCauses,
+        filesToRead,
+    };
+}
+export function formatReport(report) {
     const lines = [
         "# PPR Shell Analysis",
-        `# ${totalBoundaries} boundaries: ${holes.length} dynamic holes, ${statics.length} static`,
+        `# ${report.totalBoundaries} boundaries: ${report.dynamicHoleCount} dynamic holes, ${report.staticCount} static`,
         "",
     ];
-    if (holes.length > 0) {
+    if (report.holes.length > 0) {
+        lines.push("## Summary");
+        const topBoundary = report.holes[0];
+        if (topBoundary?.primaryBlocker) {
+            lines.push(`- Top actionable hole: ${topBoundary.name ?? "(unnamed)"} — ${topBoundary.primaryBlocker.name} ` +
+                `(${topBoundary.primaryBlocker.kind})`);
+            lines.push(`- Suggested next step: ${topBoundary.recommendation}`);
+        }
+        const topRootCause = report.rootCauses[0];
+        if (topRootCause) {
+            lines.push(`- Most common root cause: ${topRootCause.name} (${topRootCause.kind}) ` +
+                `affecting ${topRootCause.count} boundar${topRootCause.count === 1 ? "y" : "ies"}`);
+        }
+        lines.push("");
+        lines.push("## Quick Reference");
+        lines.push("| Boundary | Type | Fallback source | Primary blocker | Source | Suggested next step |");
+        lines.push("| --- | --- | --- | --- | --- | --- |");
+        for (const hole of report.holes) {
+            const blocker = hole.primaryBlocker;
+            const source = blocker?.sourceFrame
+                ? `${blocker.sourceFrame[1]}:${blocker.sourceFrame[2]}`
+                : hole.source
+                    ? `${hole.source[0]}:${hole.source[1]}`
+                    : "unknown";
+            const fallback = hole.fallbackSource.path ?? hole.fallbackSource.kind;
+            lines.push(`| ${escapeCell(hole.name ?? "(unnamed)")} | ${hole.boundaryKind} | ${escapeCell(fallback)} | ` +
+                `${escapeCell(blocker ? `${blocker.name} (${blocker.kind})` : "unknown")} | ` +
+                `${escapeCell(source)} | ${escapeCell(hole.recommendation)} |`);
+        }
+        lines.push("");
+        if (report.filesToRead.length > 0) {
+            lines.push("## Files to Read");
+            for (const file of report.filesToRead) {
+                lines.push(`- ${file}`);
+            }
+            lines.push("");
+        }
+        if (report.rootCauses.length > 0) {
+            lines.push("## Root Causes");
+            for (const cause of report.rootCauses) {
+                const source = cause.sourceFrame
+                    ? `${cause.sourceFrame[1]}:${cause.sourceFrame[2]}`
+                    : "unknown";
+                lines.push(`- ${cause.name} (${cause.kind}) at ${source} — affects ${cause.count} ` +
+                    `boundar${cause.count === 1 ? "y" : "ies"}`);
+                lines.push(`  next step: ${cause.suggestion}`);
+                lines.push(`  boundaries: ${cause.boundaryNames.join(", ")}`);
+            }
+            lines.push("");
+        }
         lines.push("## Dynamic holes (suspended in shell)");
-        for (const { shell, full } of holes) {
-            const b = full ?? shell;
-            const name = b.name?.startsWith("shell-hole") ? "(hole)" : (b.name ?? "(unnamed)");
-            const src = b.jsxSource ? `${b.jsxSource[0]}:${b.jsxSource[1]}:${b.jsxSource[2]}` : null;
+        for (const hole of report.holes) {
+            const name = hole.name ?? "(unnamed)";
+            const src = hole.source ? `${hole.source[0]}:${hole.source[1]}:${hole.source[2]}` : null;
             lines.push(`  ${name}${src ? ` at ${src}` : ""}`);
-            if (b.owners.length > 0)
-                lines.push(`    rendered by: ${b.owners.join(" > ")}`);
-            if (shell.environments.length > 0)
-                lines.push(`    environments: ${shell.environments.join(", ")}`);
-            if (full && full.suspendedBy.length > 0) {
+            if (hole.renderedBy.length > 0) {
+                lines.push(`    rendered by: ${hole.renderedBy.map((o) => {
+                    const env = o.env ? ` [${o.env}]` : "";
+                    const src = o.source ? ` at ${o.source[0]}:${o.source[1]}` : "";
+                    return `${o.name}${env}${src}`;
+                }).join(" > ")}`);
+            }
+            if (hole.environments.length > 0)
+                lines.push(`    environments: ${hole.environments.join(", ")}`);
+            if (hole.primaryBlocker) {
+                lines.push(`    primary blocker: ${hole.primaryBlocker.name} ` +
+                    `(${hole.primaryBlocker.kind}, actionability ${labelActionability(hole.primaryBlocker.actionability)})`);
+                if (hole.fallbackSource.path) {
+                    lines.push(`    fallback source: ${hole.fallbackSource.path} ` +
+                        `(${hole.fallbackSource.confidence} confidence)`);
+                }
+                if (hole.primaryBlocker.sourceFrame) {
+                    lines.push(`      source: ${hole.primaryBlocker.sourceFrame[0] || "(anonymous)"} ` +
+                        `${hole.primaryBlocker.sourceFrame[1]}:${hole.primaryBlocker.sourceFrame[2]}`);
+                }
+                lines.push(`      next step: ${hole.recommendation}`);
+            }
+            if (hole.blockers.length > 0) {
                 lines.push("    blocked by:");
-                for (const s of full.suspendedBy) {
-                    const dur = s.duration > 0 ? ` (${s.duration}ms)` : "";
-                    const env = s.env ? ` [${s.env}]` : "";
-                    const owner = s.ownerName ? ` initiated by <${s.ownerName}>` : "";
-                    const awaiter = s.awaiterName ? ` awaited in <${s.awaiterName}>` : "";
-                    lines.push(`      - ${s.name}: ${s.description || "(no description)"}${dur}${env}${owner}${awaiter}`);
+                for (const blocker of hole.blockers) {
+                    const dur = hole.primaryBlocker?.name === blocker.name ? " [primary]" : "";
+                    const env = blocker.env ? ` [${blocker.env}]` : "";
+                    const owner = blocker.ownerName ? ` initiated by <${blocker.ownerName}>` : "";
+                    const awaiter = blocker.awaiterName ? ` awaited in <${blocker.awaiterName}>` : "";
+                    lines.push(`      - ${blocker.name}: ${blocker.description || "(no description)"}${env}${dur}${owner}${awaiter}`);
+                    if (blocker.ownerFrame) {
+                        const [fn, file, line] = blocker.ownerFrame;
+                        lines.push(`          owner: ${fn || "(anonymous)"} ${file}:${line}`);
+                    }
+                    if (blocker.awaiterFrame && !blocker.ownerFrame) {
+                        const [fn, file, line] = blocker.awaiterFrame;
+                        lines.push(`          awaiter: ${fn || "(anonymous)"} ${file}:${line}`);
+                    }
+                    if (blocker.ownerFrame && hole.primaryBlocker?.name === blocker.name) {
+                        for (const [fn, file, line] of [blocker.ownerFrame].slice(0, 3)) {
+                            lines.push(`          at ${fn || "(anonymous)"} ${file}:${line}`);
+                        }
+                    }
                 }
             }
-            else if (full?.unknownSuspenders) {
-                lines.push(`    suspenders unknown: ${full.unknownSuspenders}`);
+            else if (hole.unknownSuspenders) {
+                lines.push(`    suspenders unknown: ${hole.unknownSuspenders}`);
             }
         }
         lines.push("");
     }
-    if (statics.length > 0) {
+    if (report.statics.length > 0) {
         lines.push("## Static (pre-rendered in shell)");
-        for (const b of statics) {
+        for (const b of report.statics) {
             const name = b.name ?? "(unnamed)";
-            const src = b.jsxSource ? ` at ${b.jsxSource[0]}:${b.jsxSource[1]}:${b.jsxSource[2]}` : "";
+            const src = b.source ? ` at ${b.source[0]}:${b.source[1]}:${b.source[2]}` : "";
             lines.push(`  ${name}${src}`);
         }
     }
     return lines.join("\n");
 }
+function buildBoundaryInsight(shell, resolved) {
+    const boundaryKind = inferBoundaryKind(resolved);
+    const blockers = resolved.suspendedBy
+        .map((blocker) => buildActionableBlocker(blocker))
+        .sort(compareActionableBlockers);
+    const primaryBlocker = blockers[0] ?? null;
+    const recommendation = recommendBoundaryFix(boundaryKind, primaryBlocker, resolved.unknownSuspenders);
+    return {
+        id: resolved.id,
+        name: resolved.name,
+        boundaryKind,
+        environments: shell.environments,
+        source: resolved.jsxSource,
+        renderedBy: resolved.owners,
+        fallbackSource: {
+            kind: "unknown",
+            path: null,
+            confidence: boundaryKind === "route-segment" ? "medium" : "low",
+        },
+        primaryBlocker,
+        blockers,
+        unknownSuspenders: resolved.unknownSuspenders,
+        actionability: Math.max(primaryBlocker?.actionability ?? 0, boundaryKind === "route-segment" ? 55 : 0),
+        recommendation: recommendation.text,
+        recommendationKind: recommendation.kind,
+    };
+}
+function buildActionableBlocker(suspender) {
+    const ownerFrame = pickPreferredFrame(suspender.ownerStack);
+    const awaiterFrame = pickPreferredFrame(suspender.awaiterStack);
+    const sourceFrame = ownerFrame ?? awaiterFrame;
+    const kind = classifyBlocker(suspender, sourceFrame);
+    const suggestion = suggestBlockerFix(kind);
+    let actionability = blockerActionability(kind);
+    if (sourceFrame && !isFrameworkishPath(sourceFrame[1]))
+        actionability += 8;
+    if (suspender.ownerName || suspender.awaiterName)
+        actionability += 4;
+    actionability = Math.min(actionability, 100);
+    return {
+        key: buildBlockerKey(suspender.name, kind, sourceFrame),
+        name: suspender.name,
+        kind,
+        env: suspender.env,
+        description: suspender.description,
+        ownerName: suspender.ownerName,
+        awaiterName: suspender.awaiterName,
+        sourceFrame,
+        ownerFrame,
+        awaiterFrame,
+        actionability,
+        suggestion,
+    };
+}
+function buildRootCauseGroups(holes) {
+    const groups = new Map();
+    for (const hole of holes) {
+        const blocker = hole.primaryBlocker;
+        if (!blocker)
+            continue;
+        const existing = groups.get(blocker.key);
+        if (existing) {
+            existing.boundaryIds.push(hole.id);
+            existing.boundaryNames.push(hole.name ?? `boundary-${hole.id}`);
+            existing.count++;
+            existing.actionability = Math.max(existing.actionability, blocker.actionability);
+            continue;
+        }
+        groups.set(blocker.key, {
+            key: blocker.key,
+            kind: blocker.kind,
+            name: blocker.name,
+            sourceFrame: blocker.sourceFrame,
+            boundaryIds: [hole.id],
+            boundaryNames: [hole.name ?? `boundary-${hole.id}`],
+            count: 1,
+            actionability: blocker.actionability,
+            suggestion: blocker.suggestion,
+        });
+    }
+    return [...groups.values()].sort((a, b) => {
+        const scoreA = a.count * a.actionability;
+        const scoreB = b.count * b.actionability;
+        return scoreB - scoreA || a.name.localeCompare(b.name);
+    });
+}
+function collectFilesToRead(holes, rootCauses) {
+    const counts = new Map();
+    const add = (file) => {
+        if (!file)
+            return;
+        counts.set(file, (counts.get(file) ?? 0) + 1);
+    };
+    for (const hole of holes) {
+        add(hole.source?.[0]);
+        add(hole.primaryBlocker?.sourceFrame?.[1]);
+        for (const owner of hole.renderedBy)
+            add(owner.source?.[0]);
+    }
+    for (const cause of rootCauses)
+        add(cause.sourceFrame?.[1]);
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([file]) => file)
+        .slice(0, 12);
+}
+function compareBoundaryInsights(a, b) {
+    return (b.actionability - a.actionability ||
+        boundaryKindWeight(b.boundaryKind) - boundaryKindWeight(a.boundaryKind) ||
+        (b.blockers.length - a.blockers.length) ||
+        (a.name ?? "").localeCompare(b.name ?? ""));
+}
+function compareActionableBlockers(a, b) {
+    return (b.actionability - a.actionability ||
+        blockerKindWeight(b.kind) - blockerKindWeight(a.kind) ||
+        a.name.localeCompare(b.name));
+}
+function boundaryKindWeight(kind) {
+    if (kind === "route-segment")
+        return 3;
+    if (kind === "explicit-suspense")
+        return 2;
+    return 1;
+}
+function blockerKindWeight(kind) {
+    switch (kind) {
+        case "client-hook": return 7;
+        case "request-api": return 6;
+        case "server-fetch": return 5;
+        case "cache": return 4;
+        case "stream": return 3;
+        case "unknown": return 2;
+        case "framework": return 1;
+    }
+}
+function blockerActionability(kind) {
+    switch (kind) {
+        case "client-hook": return 90;
+        case "request-api": return 88;
+        case "server-fetch": return 82;
+        case "cache": return 74;
+        case "stream": return 60;
+        case "unknown": return 35;
+        case "framework": return 18;
+    }
+}
+function inferBoundaryKind(boundary) {
+    const ownerNames = boundary.owners.map((owner) => owner.name);
+    if ((boundary.name && boundary.name.endsWith("/")) ||
+        ownerNames.includes("LoadingBoundary") ||
+        ownerNames.includes("OuterLayoutRouter")) {
+        return "route-segment";
+    }
+    if (boundary.name?.includes("Suspense") ||
+        ownerNames.some((name) => name.includes("Suspense"))) {
+        return "explicit-suspense";
+    }
+    return "component";
+}
+function classifyBlocker(suspender, sourceFrame) {
+    const name = suspender.name.toLowerCase();
+    if (name === "usepathname" ||
+        name === "useparams" ||
+        name === "usesearchparams" ||
+        name === "useselectedlayoutsegments" ||
+        name === "useselectedlayoutsegment" ||
+        name === "userouter") {
+        return "client-hook";
+    }
+    if (name === "cookies" ||
+        name === "headers" ||
+        name === "connection" ||
+        name === "params" ||
+        name === "searchparams" ||
+        name === "draftmode") {
+        return "request-api";
+    }
+    if (name === "rsc stream")
+        return "stream";
+    if (name.includes("fetch"))
+        return "server-fetch";
+    if (name.includes("cache") || suspender.description.toLowerCase().includes("cache")) {
+        return "cache";
+    }
+    if (name.startsWith("use"))
+        return "client-hook";
+    if (sourceFrame && isFrameworkishPath(sourceFrame[1]))
+        return "framework";
+    return "unknown";
+}
+function suggestBlockerFix(kind) {
+    switch (kind) {
+        case "client-hook":
+            return "Move route hooks behind a smaller client Suspense or provide a real non-null loading fallback for this segment.";
+        case "request-api":
+            return "Push request-bound reads to a smaller server leaf, or cache around them so the parent shell can stay static.";
+        case "server-fetch":
+            return "Split static shell content from data widgets, then push the fetch into smaller Suspense leaves or cache it.";
+        case "cache":
+            return "This looks cache-related; check whether \"use cache\" or runtime prefetch can eliminate the suspension.";
+        case "stream":
+            return "A stream is still pending here; extract static siblings outside the boundary and push the stream consumer deeper.";
+        case "framework":
+            return "This currently looks framework-driven; find the nearest user-owned caller above it before changing code.";
+        case "unknown":
+            return "Inspect the nearest user-owned owner/awaiter frame and verify whether this suspender really belongs at this boundary.";
+    }
+}
+function recommendBoundaryFix(boundaryKind, primaryBlocker, unknownSuspenders) {
+    if (boundaryKind === "route-segment" && primaryBlocker?.kind === "client-hook") {
+        return {
+            kind: "check-loading-fallback",
+            text: "This route segment is suspending on client hooks. Check loading.tsx first; if it is null or visually empty, fix the fallback before chasing deeper push-down work.",
+        };
+    }
+    if (primaryBlocker?.kind === "client-hook") {
+        return {
+            kind: "push-client-hooks-down",
+            text: "Push the hook-using client UI behind a smaller local Suspense boundary so the parent shell can prerender.",
+        };
+    }
+    if (primaryBlocker?.kind === "request-api" || primaryBlocker?.kind === "server-fetch") {
+        return {
+            kind: "push-request-io-down",
+            text: "Push the request-bound async work into a smaller leaf or split static siblings out of this boundary.",
+        };
+    }
+    if (primaryBlocker?.kind === "cache") {
+        return {
+            kind: "cache-or-runtime-prefetch",
+            text: "Check whether caching or runtime prefetch can move this personalized content into the shell.",
+        };
+    }
+    if (primaryBlocker?.kind === "stream") {
+        return {
+            kind: "extract-static-shell",
+            text: "Keep the stream behind Suspense, but extract any static shell content outside the boundary.",
+        };
+    }
+    if (primaryBlocker?.kind === "framework") {
+        return {
+            kind: "investigate-framework",
+            text: "The top blocker still looks framework-heavy. Find the nearest user-owned caller before changing boundary placement.",
+        };
+    }
+    if (unknownSuspenders) {
+        return {
+            kind: "investigate-unknown",
+            text: `React could not identify the suspender (${unknownSuspenders}). Investigate the nearest user-owned owner or awaiter frame.`,
+        };
+    }
+    return {
+        kind: "investigate-unknown",
+        text: "No primary blocker was identified. Inspect the boundary source and owner chain directly.",
+    };
+}
+function pickPreferredFrame(stack) {
+    if (!stack || stack.length === 0)
+        return null;
+    return stack.find((frame) => !isFrameworkishPath(frame[1])) ?? stack[0];
+}
+function isFrameworkishPath(file) {
+    return file.includes("/node_modules/");
+}
+function buildBlockerKey(name, kind, sourceFrame) {
+    if (!sourceFrame)
+        return `${kind}:${name}:unknown`;
+    return `${kind}:${name}:${sourceFrame[1]}:${sourceFrame[2]}`;
+}
+function labelActionability(value) {
+    if (value >= 80)
+        return "high";
+    if (value >= 50)
+        return "medium";
+    return "low";
+}
+function escapeCell(value) {
+    return value.replaceAll("|", "\\|");
+}
+export function annotateReportWithPageMetadata(report, pageMetadata) {
+    const sessions = Array.isArray(pageMetadata?.sessions)
+        ? (pageMetadata.sessions)
+        : [];
+    const loadingPaths = sessions.flatMap((session) => (session.segments ?? [])
+        .filter((segment) => segment.type === "boundary:loading" && typeof segment.path === "string")
+        .map((segment) => segment.path));
+    for (const hole of report.holes) {
+        if (hole.boundaryKind !== "route-segment")
+            continue;
+        const segmentName = normalizeBoundarySegmentName(hole.name);
+        if (!segmentName)
+            continue;
+        const exact = loadingPaths.find((path) => path.split("/").at(-2) === segmentName);
+        if (exact) {
+            hole.fallbackSource = {
+                kind: "loading-tsx",
+                path: exact,
+                confidence: "high",
+            };
+        }
+    }
+}
+function normalizeBoundarySegmentName(name) {
+    if (!name)
+        return null;
+    return name.endsWith("/") ? name.slice(0, -1) : name;
+}
 function boundaryKey(b) {
     if (b.jsxSource)
         return `${b.jsxSource[0]}:${b.jsxSource[1]}:${b.jsxSource[2]}`;
@@ -106,13 +505,40 @@ function boundaryKey(b) {
 async function resolveSources(boundaries, origin) {
     for (const b of boundaries) {
         if (b.jsxSource) {
-            const [file, line, col] = b.jsxSource;
-            const resolved = (await sourcemap.resolve(origin, file, line, col)) ??
-                (await sourcemap.resolveViaMap(origin, file, line, col));
-            if (resolved)
-                b.jsxSource = [resolved.file, resolved.line, resolved.column];
+            b.jsxSource = await resolveOne(b.jsxSource, origin);
+        }
+        for (const o of b.owners) {
+            if (o.source) {
+                o.source = await resolveOne(o.source, origin);
+            }
+        }
+        for (const s of b.suspendedBy) {
+            if (s.ownerStack)
+                s.ownerStack = await resolveStack(s.ownerStack, origin);
+            if (s.awaiterStack)
+                s.awaiterStack = await resolveStack(s.awaiterStack, origin);
+        }
+    }
+}
+async function resolveOne(src, origin) {
+    const [file, line, col] = src;
+    const resolved = (await sourcemap.resolve(origin, file, line, col)) ??
+        (await sourcemap.resolveViaMap(origin, file, line, col));
+    return resolved ? [resolved.file, resolved.line, resolved.column] : src;
+}
+async function resolveStack(stack, origin) {
+    const out = [];
+    for (const [name, file, line, col] of stack) {
+        const resolved = (await sourcemap.resolve(origin, file, line, col)) ??
+            (await sourcemap.resolveViaMap(origin, file, line, col));
+        if (resolved) {
+            out.push([name, resolved.file, resolved.line, resolved.column]);
+        }
+        else {
+            out.push([name, file, line, col]);
         }
     }
+    return out;
 }
 async function inPageSuspense(inspect) {
     const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
@@ -155,16 +581,17 @@ async function inPageSuspense(inspect) {
     function collect(renderer) {
         return new Promise((resolve) => {
             const out = [];
-            const listener = (e) => {
-                const p = e.data?.payload;
-                if (e.data?.source === "react-devtools-bridge" && p?.event === "operations") {
-                    out.push(p.payload);
-                }
+            // Operations are emitted via hook.emit("operations", payload),
+            // NOT via window.postMessage.
+            const origEmit = hook.emit;
+            hook.emit = function (event, payload) {
+                if (event === "operations")
+                    out.push(payload);
+                return origEmit.apply(this, arguments);
             };
-            window.addEventListener("message", listener);
             renderer.flushInitialOperations();
             setTimeout(() => {
-                window.removeEventListener("message", listener);
+                hook.emit = origEmit;
                 resolve(out);
             }, 50);
         });
@@ -283,7 +710,9 @@ async function inPageSuspense(inspect) {
                     duration: awaited.end && awaited.start ? Math.round(awaited.end - awaited.start) : 0,
                     env: awaited.env ?? entry?.env ?? null,
                     ownerName: awaited.owner?.displayName ?? null,
+                    ownerStack: parseStack(awaited.owner?.stack ?? awaited.stack),
                     awaiterName: entry?.owner?.displayName ?? null,
+                    awaiterStack: parseStack(entry?.owner?.stack ?? entry?.stack),
                 });
             }
         }
@@ -297,8 +726,16 @@ async function inPageSuspense(inspect) {
         }
         if (Array.isArray(data.owners)) {
             for (const o of data.owners) {
-                if (o?.displayName)
-                    boundary.owners.push(o.displayName);
+                if (o?.displayName) {
+                    const src = Array.isArray(o.stack) && o.stack.length > 0 && Array.isArray(o.stack[0])
+                        ? [o.stack[0][1] || "(unknown)", o.stack[0][2], o.stack[0][3]]
+                        : null;
+                    boundary.owners.push({
+                        name: o.displayName,
+                        env: o.env ?? null,
+                        source: src,
+                    });
+                }
             }
         }
         if (Array.isArray(data.stack) && data.stack.length > 0) {
@@ -308,6 +745,13 @@ async function inPageSuspense(inspect) {
             }
         }
     }
+    function parseStack(raw) {
+        if (!Array.isArray(raw) || raw.length === 0)
+            return null;
+        return raw
+            .filter((f) => Array.isArray(f) && f.length >= 4)
+            .map((f) => [f[0] ?? "", f[1] ?? "", f[2] ?? 0, f[3] ?? 0]);
+    }
     function preview(v) {
         if (v == null)
             return "";

package/package.json

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