@vercel/next-browser 0.1.0 → 0.1.2

package/dist/suspense.js

@@ -0,0 +1,332 @@
+import * as sourcemap from "./sourcemap.js";
+export async function snapshot(page) {
+    return page.evaluate(inPageSuspense, true);
+}
+export async function countBoundaries(page) {
+    const boundaries = await page.evaluate(inPageSuspense, false).catch(() => []);
+    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) {
+    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 unlockedByKey = new Map();
+        for (const b of unlocked)
+            unlockedByKey.set(boundaryKey(b), b);
+        for (const lb of locked) {
+            if (lb.isSuspended) {
+                holes.push({ shell: lb, full: unlockedByKey.get(boundaryKey(lb)) });
+            }
+            else {
+                statics.push(lb);
+            }
+        }
+    }
+    const totalBoundaries = fromDom ? holes.length + statics.length : locked.length;
+    const lines = [
+        "# PPR Shell Analysis",
+        `# ${totalBoundaries} boundaries: ${holes.length} dynamic holes, ${statics.length} static`,
+        "",
+    ];
+    if (holes.length > 0) {
+        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;
+            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) {
+                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}`);
+                }
+            }
+            else if (full?.unknownSuspenders) {
+                lines.push(`    suspenders unknown: ${full.unknownSuspenders}`);
+            }
+        }
+        lines.push("");
+    }
+    if (statics.length > 0) {
+        lines.push("## Static (pre-rendered in shell)");
+        for (const b of statics) {
+            const name = b.name ?? "(unnamed)";
+            const src = b.jsxSource ? ` at ${b.jsxSource[0]}:${b.jsxSource[1]}:${b.jsxSource[2]}` : "";
+            lines.push(`  ${name}${src}`);
+        }
+    }
+    return lines.join("\n");
+}
+function boundaryKey(b) {
+    if (b.jsxSource)
+        return `${b.jsxSource[0]}:${b.jsxSource[1]}:${b.jsxSource[2]}`;
+    return b.name ?? `id-${b.id}`;
+}
+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];
+        }
+    }
+}
+async function inPageSuspense(inspect) {
+    const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    if (!hook)
+        throw new Error("React DevTools hook not installed");
+    const ri = hook.rendererInterfaces?.get?.(1);
+    if (!ri)
+        throw new Error("no React renderer attached");
+    const batches = await collect(ri);
+    const boundaryMap = new Map();
+    for (const ops of batches)
+        decodeSuspenseOps(ops, boundaryMap);
+    const results = [];
+    for (const b of boundaryMap.values()) {
+        if (b.parentID === 0)
+            continue;
+        const boundary = {
+            id: b.id,
+            parentID: b.parentID,
+            name: b.name,
+            isSuspended: b.isSuspended,
+            environments: b.environments,
+            suspendedBy: [],
+            unknownSuspenders: null,
+            owners: [],
+            jsxSource: null,
+        };
+        if (inspect && ri.hasElementWithId(b.id)) {
+            const displayName = ri.getDisplayNameForElementID(b.id);
+            if (displayName)
+                boundary.name = displayName;
+            const result = ri.inspectElement(1, b.id, null, true);
+            if (result?.type === "full-data") {
+                parseInspection(boundary, result.value);
+            }
+        }
+        results.push(boundary);
+    }
+    return results;
+    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);
+                }
+            };
+            window.addEventListener("message", listener);
+            renderer.flushInitialOperations();
+            setTimeout(() => {
+                window.removeEventListener("message", listener);
+                resolve(out);
+            }, 50);
+        });
+    }
+    function decodeSuspenseOps(ops, map) {
+        let i = 2;
+        const strings = [null];
+        const tableEnd = ++i + ops[i - 1];
+        while (i < tableEnd) {
+            const len = ops[i++];
+            strings.push(String.fromCodePoint(...ops.slice(i, i + len)));
+            i += len;
+        }
+        while (i < ops.length) {
+            const op = ops[i];
+            if (op === 1) {
+                const type = ops[i + 2];
+                i += 3 + (type === 11 ? 4 : 5);
+            }
+            else if (op === 2) {
+                i += 2 + ops[i + 1];
+            }
+            else if (op === 3) {
+                i += 3 + ops[i + 2];
+            }
+            else if (op === 4) {
+                i += 3;
+            }
+            else if (op === 5) {
+                i += 4;
+            }
+            else if (op === 6) {
+                i++;
+            }
+            else if (op === 7) {
+                i += 3;
+            }
+            else if (op === 8) {
+                const id = ops[i + 1];
+                const parentID = ops[i + 2];
+                const nameStrID = ops[i + 3];
+                const isSuspended = ops[i + 4] === 1;
+                const numRects = ops[i + 5];
+                i += 6;
+                if (numRects !== -1)
+                    i += numRects * 4;
+                map.set(id, {
+                    id,
+                    parentID,
+                    name: strings[nameStrID] ?? null,
+                    isSuspended,
+                    environments: [],
+                });
+            }
+            else if (op === 9) {
+                i += 2 + ops[i + 1];
+            }
+            else if (op === 10) {
+                i += 3 + ops[i + 2];
+            }
+            else if (op === 11) {
+                const numRects = ops[i + 2];
+                i += 3;
+                if (numRects !== -1)
+                    i += numRects * 4;
+            }
+            else if (op === 12) {
+                i++;
+                const changeLen = ops[i++];
+                for (let c = 0; c < changeLen; c++) {
+                    const id = ops[i++];
+                    i++; // hasUniqueSuspenders
+                    i++; // endTime
+                    const isSuspended = ops[i++] === 1;
+                    const envLen = ops[i++];
+                    const envs = [];
+                    for (let e = 0; e < envLen; e++) {
+                        const name = strings[ops[i++]];
+                        if (name != null)
+                            envs.push(name);
+                    }
+                    const node = map.get(id);
+                    if (node) {
+                        node.isSuspended = isSuspended;
+                        for (const env of envs) {
+                            if (!node.environments.includes(env))
+                                node.environments.push(env);
+                        }
+                    }
+                }
+            }
+            else if (op === 13) {
+                i += 2;
+            }
+            else {
+                i++;
+            }
+        }
+    }
+    function parseInspection(boundary, data) {
+        const rawSuspendedBy = data.suspendedBy;
+        const rawSuspenders = Array.isArray(rawSuspendedBy)
+            ? rawSuspendedBy
+            : Array.isArray(rawSuspendedBy?.data)
+                ? rawSuspendedBy.data
+                : null;
+        if (rawSuspenders) {
+            for (const entry of rawSuspenders) {
+                const awaited = entry?.awaited;
+                if (!awaited)
+                    continue;
+                const desc = preview(awaited.description) || preview(awaited.value);
+                boundary.suspendedBy.push({
+                    name: awaited.name ?? "unknown",
+                    description: desc,
+                    duration: awaited.end && awaited.start ? Math.round(awaited.end - awaited.start) : 0,
+                    env: awaited.env ?? entry?.env ?? null,
+                    ownerName: awaited.owner?.displayName ?? null,
+                    awaiterName: entry?.owner?.displayName ?? null,
+                });
+            }
+        }
+        if (data.unknownSuspenders && data.unknownSuspenders !== 0) {
+            const reasons = {
+                1: "production build (no debug info)",
+                2: "old React version (missing tracking)",
+                3: "thrown Promise (library using throw instead of use())",
+            };
+            boundary.unknownSuspenders = reasons[data.unknownSuspenders] ?? "unknown reason";
+        }
+        if (Array.isArray(data.owners)) {
+            for (const o of data.owners) {
+                if (o?.displayName)
+                    boundary.owners.push(o.displayName);
+            }
+        }
+        if (Array.isArray(data.stack) && data.stack.length > 0) {
+            const frame = data.stack[0];
+            if (Array.isArray(frame) && frame.length >= 4) {
+                boundary.jsxSource = [frame[1] || "(unknown)", frame[2], frame[3]];
+            }
+        }
+    }
+    function preview(v) {
+        if (v == null)
+            return "";
+        if (typeof v === "string")
+            return v;
+        if (typeof v !== "object")
+            return String(v);
+        if (typeof v.preview_long === "string")
+            return v.preview_long;
+        if (typeof v.preview_short === "string")
+            return v.preview_short;
+        if (typeof v.value === "string")
+            return v.value;
+        try {
+            const s = JSON.stringify(v);
+            return s.length > 80 ? s.slice(0, 77) + "..." : s;
+        }
+        catch {
+            return "";
+        }
+    }
+}

package/dist/tree.js

@@ -0,0 +1,231 @@
+export async function snapshot(page) {
+    return page.evaluate(inPageSnapshot);
+}
+export async function inspect(page, id) {
+    return page.evaluate(inPageInspect, id);
+}
+export function path(nodes, id) {
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const names = [];
+    for (let n = byId.get(id); n; n = byId.get(n.parent)) {
+        names.push(n.name ?? typeName(n.type));
+    }
+    return names.reverse().join(" > ");
+}
+const HEADER = "# React component tree\n" +
+    "# Columns: depth id parent name [key=...]\n" +
+    "# Use `tree <id>` for props/hooks/state. IDs valid until next navigation.\n";
+export function format(nodes) {
+    const children = new Map();
+    for (const n of nodes) {
+        const list = children.get(n.parent) ?? [];
+        list.push(n);
+        children.set(n.parent, list);
+    }
+    const lines = [HEADER];
+    for (const root of children.get(0) ?? [])
+        walk(root, 0);
+    return lines.join("\n");
+    function walk(node, depth) {
+        const name = node.name ?? typeName(node.type);
+        const key = node.key ? ` key=${JSON.stringify(node.key)}` : "";
+        const parent = node.parent || "-";
+        lines.push(`${depth} ${node.id} ${parent} ${name}${key}`);
+        for (const c of children.get(node.id) ?? [])
+            walk(c, depth + 1);
+    }
+}
+function typeName(type) {
+    const names = {
+        11: "Root",
+        12: "Suspense",
+        13: "SuspenseList",
+    };
+    return names[type] ?? `(${type})`;
+}
+/**
+ * Runs inside the page. Asks the DevTools backend to flush the full
+ * component tree as an operations batch, then decodes TREE_OPERATION_ADD
+ * entries into a flat node list.
+ *
+ * Wire format (React DevTools v6/v7):
+ *   Header:  [rendererID, rootID, stringTableSize, ...stringTable]
+ *   ADD:     [1, id, type, ...4 ints]              if type == 11 (Root)
+ *            [1, id, type, parentID, ownerID,
+ *                displayNameStrID, keyStrID, _]    otherwise
+ */
+async function inPageSnapshot() {
+    const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    if (!hook)
+        throw new Error("React DevTools hook not installed");
+    const ri = hook.rendererInterfaces?.get?.(1);
+    if (!ri)
+        throw new Error("no React renderer attached");
+    const batches = await collect(ri);
+    return batches.flatMap(decode);
+    function collect(ri) {
+        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);
+                }
+            };
+            window.addEventListener("message", listener);
+            ri.flushInitialOperations();
+            setTimeout(() => {
+                window.removeEventListener("message", listener);
+                resolve(out);
+            }, 50);
+        });
+    }
+    function decode(ops) {
+        let i = 2;
+        const strings = [null];
+        const tableEnd = ++i + ops[i - 1];
+        while (i < tableEnd) {
+            const len = ops[i++];
+            strings.push(String.fromCodePoint(...ops.slice(i, i + len)));
+            i += len;
+        }
+        const nodes = [];
+        while (i < ops.length) {
+            const op = ops[i];
+            if (op === 1) {
+                const id = ops[i + 1];
+                const type = ops[i + 2];
+                i += 3;
+                if (type === 11) {
+                    nodes.push({ id, type, name: null, key: null, parent: 0 });
+                    i += 4;
+                }
+                else {
+                    nodes.push({
+                        id,
+                        type,
+                        name: strings[ops[i + 2]] ?? null,
+                        key: strings[ops[i + 3]] ?? null,
+                        parent: ops[i],
+                    });
+                    i += 5;
+                }
+            }
+            else {
+                i += skip(op, ops, i);
+            }
+        }
+        return nodes;
+    }
+    function skip(op, ops, i) {
+        if (op === 2)
+            return 2 + ops[i + 1];
+        if (op === 3)
+            return 3 + ops[i + 2];
+        if (op === 4)
+            return 3;
+        if (op === 5)
+            return 4;
+        if (op === 6)
+            return 1;
+        if (op === 7)
+            return 3;
+        if (op === 8)
+            return 6 + rects(ops[i + 5]);
+        if (op === 9)
+            return 2 + ops[i + 1];
+        if (op === 10)
+            return 3 + ops[i + 2];
+        if (op === 11)
+            return 3 + rects(ops[i + 2]);
+        if (op === 12)
+            return suspenders(ops, i);
+        if (op === 13)
+            return 2;
+        return 1;
+    }
+    function rects(n) {
+        return n === -1 ? 0 : n * 4;
+    }
+    function suspenders(ops, i) {
+        let j = i + 2;
+        for (let c = 0; c < ops[i + 1]; c++)
+            j += 5 + ops[j + 4];
+        return j - i;
+    }
+}
+/**
+ * Runs inside the page. Calls rendererInterface.inspectElement(id) —
+ * the same call the DevTools sidebar uses — and formats the dehydrated
+ * props/hooks/state into a plain-text summary.
+ */
+function inPageInspect(id) {
+    const hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    const ri = hook?.rendererInterfaces?.get?.(1);
+    if (!ri)
+        throw new Error("no React renderer attached");
+    if (!ri.hasElementWithId(id))
+        throw new Error(`element ${id} not found (page reloaded?)`);
+    const result = ri.inspectElement(1, id, null, true);
+    if (result?.type !== "full-data")
+        throw new Error(`inspect failed: ${result?.type}`);
+    const v = result.value;
+    const name = ri.getDisplayNameForElementID(id);
+    const lines = [`${name} #${id}`];
+    if (v.key != null)
+        lines.push(`key: ${JSON.stringify(v.key)}`);
+    section("props", v.props);
+    section("hooks", v.hooks);
+    section("state", v.state);
+    section("context", v.context);
+    if (v.owners?.length) {
+        const chain = v.owners.map((o) => o.displayName).join(" > ");
+        lines.push(`rendered by: ${chain}`);
+    }
+    const source = Array.isArray(v.source)
+        ? [v.source[1], v.source[2], v.source[3]]
+        : null;
+    return { text: lines.join("\n"), source };
+    function section(label, payload) {
+        const data = payload?.data ?? payload;
+        if (data == null)
+            return;
+        if (Array.isArray(data)) {
+            if (data.length === 0)
+                return;
+            lines.push(`${label}:`);
+            for (const h of data)
+                lines.push(`  ${hookLine(h)}`);
+        }
+        else if (typeof data === "object") {
+            const entries = Object.entries(data);
+            if (entries.length === 0)
+                return;
+            lines.push(`${label}:`);
+            for (const [k, val] of entries)
+                lines.push(`  ${k}: ${preview(val)}`);
+        }
+    }
+    function hookLine(h) {
+        const idx = h.id != null ? `[${h.id}] ` : "";
+        const sub = h.subHooks?.length ? ` (${h.subHooks.length} sub)` : "";
+        return `${idx}${h.name}: ${preview(h.value)}${sub}`;
+    }
+    function preview(v) {
+        if (v == null)
+            return String(v);
+        if (typeof v !== "object")
+            return JSON.stringify(v);
+        const d = v;
+        if (d.type === "undefined")
+            return "undefined";
+        if (d.preview_long)
+            return d.preview_long;
+        if (d.preview_short)
+            return d.preview_short;
+        if (Array.isArray(v))
+            return `[${v.map(preview).join(", ")}]`;
+        const entries = Object.entries(v).map(([k, val]) => `${k}: ${preview(val)}`);
+        return `{${entries.join(", ")}}`;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/next-browser",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Headed Playwright browser with React DevTools pre-loaded",
   "license": "MIT",
   "repository": {
@@ -9,21 +9,23 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=22.18"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
-    "src",
+    "dist",
     "extensions"
   ],
   "bin": {
-    "next-browser": "./src/cli.ts"
+    "next-browser": "./dist/cli.js"
   },
   "scripts": {
     "start": "node src/cli.ts",
-    "typecheck": "tsc"
+    "typecheck": "tsc",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "pnpm build"
   },
   "dependencies": {
     "@next/playwright": "16.2.0-canary.80",