[Skill] Runtime prefetch scenario, screenshot error surfacing, cURL -b parsing (#33)

* [Skill] Runtime prefetch scenario, screenshot error surfacing, cURL -b parsing

* Distinguish PPR shell formats: HTML (goto) vs RSC payload (push)

Author: gaojude

.changeset/runtime-prefetch-scenario.md

@@ -0,0 +1,5 @@
+---
+"@vercel/next-browser": minor
+---
+
+Surface errors alongside screenshots, parse macOS Chrome cURL `-b` cookie format, guard `push` against same-URL navigation, add runtime prefetch scenario to SKILL.md

skills/next-browser/SKILL.md

@@ -318,13 +318,16 @@ server is back. Don't treat this error as a failure.
 **Prerequisite:** PPR requires `cacheComponents` to be enabled in
 `next.config`. Without it the shell won't have pre-rendered content to show.
 
-Freeze dynamic content so you can inspect the static shell — the part of
-the page that's instantly available before any data loads. After locking:
-- `goto` — shows the server-rendered shell with holes where dynamic
-  content would appear.
-- `push` — shows what the client already has from prefetching. Requires
-  the current page to already be hydrated (prefetch is client-side),
-  so lock *after* you've landed on the origin, not before.
+Freeze dynamic content so you can inspect the static shell. After
+locking:
+- `goto` — shows the **PPR shell as HTML**: the server-rendered static
+  shell with `<template>` holes where dynamic content would stream in.
+  This is what a direct page load delivers.
+- `push` — shows the **PPR shell as RSC payload**: the same static shell
+  concept, but delivered as an RSC stream during client navigation — no
+  HTML, no hydration. In dev mode there is no prefetching — the lock
+  uses a cookie that tells the dev server to simulate instant navigation,
+  so lock + push works on any route.
 
 ```
 $ next-browser ppr lock
@@ -470,12 +473,22 @@ is skipped.
 The optional caption describes the screenshot or the rationale for taking
 it. Captions appear in the Screenshot Log above each image.
 
+Also fetches errors from the Next.js dev server alongside the capture.
+When errors are present, they are printed after the file path so you get
+both the visual state and the error details in one call.
+
 ```
 $ next-browser screenshot "Homepage after login"
 /tmp/next-browser-1711234567890.png
 
-$ next-browser screenshot "Full page layout" --full-page
+$ next-browser screenshot "After bad import"
 /tmp/next-browser-1711234567891.png
+
+errors:
+{ ... }
+
+$ next-browser screenshot "Full page layout" --full-page
+/tmp/next-browser-1711234567892.png
 ```
 
 ### `snapshot`
@@ -859,20 +872,24 @@ component is the root cause, find evidence — inspect it with `tree`,
 read its source, check what's changing via the change reason column.
 Don't propose changes from a single observation.
 
-### Growing the static shell
+### Growing the HTML shell (direct page load)
+
+The HTML shell is the PPR prerender delivered on a direct page load —
+what the user sees before any JavaScript runs. It's the static parts of
+the component tree baked into HTML, with `<template>` holes where
+dynamic data will stream in.
 
-The shell is what the user sees the instant they land — before any dynamic
-data arrives. The measure is the screenshot while locked: does it read as
-the page itself? A shell can be non-empty and still bad — one Suspense
-fallback wrapping the whole content area renders *something*, but it's a
+The measure is the screenshot while locked: does it read as the page
+itself? A shell can be non-empty and still bad — one Suspense fallback
+wrapping the whole content area renders *something*, but it's a
 monolithic loading state, not the page.
 
 A meaningful shell is the real component tree with small, local fallbacks
-where data is genuinely pending. Getting there means the composition layer
-— the layouts and wrappers between those leaf boundaries — can't itself
-suspend. `ppr unlock`'s Quick Reference table names the primary blocker
-and source for each hole; the Detail section adds owner chains and
-secondary blockers. A suspend high in the tree is what collapses
+where data is genuinely pending. Getting there means the composition
+layer — the layouts and wrappers between those leaf boundaries — can't
+itself suspend. `ppr unlock`'s Quick Reference table names the primary
+blocker and source for each hole; the Detail section adds owner chains
+and secondary blockers. A suspend high in the tree is what collapses
 everything beneath it into one fallback.
 
 Work it top-down. For the component that's suspending: can the dynamic
@@ -889,23 +906,143 @@ component with `tree`, or compare a route where the shell works to
 one where it doesn't. Don't commit to a root cause or propose changes
 from a single observation.
 
-There are two shells depending on how the user arrives — establish which
-one you're optimizing first (see **Working with the user → Escalate,
-don't decide**).
+**Workflow:**
+
+1. `ppr lock`
+2. `goto` the target URL — the lock suppresses dynamic content so you
+   see exactly what the server pre-rendered as HTML.
+3. `screenshot "HTML shell"` — evaluate visually.
+4. `ppr unlock` — read the shell analysis (holes, blockers, sources).
+5. Fix the top-most blocker, let HMR pick it up, re-lock, `goto`,
+   and compare.
+
+Between iterations: check `errors` while unlocked.
+
+### Optimizing instant navigations
+
+The instant shell is what the user sees the moment they click a link
+(or `router.push`) — before any dynamic data for the target route
+arrives. In production, Next.js prefetches the target route's static
+shell while the user is still on the origin page. When the link is
+clicked, the router reveals this prefetched shell instantly, then
+streams in the dynamic parts.
+
+This is the same PPR shell concept as the HTML shell above, but
+delivered as an RSC payload stream during client navigation — there is
+no HTML, no hydration. Client components in the shell are rendered with
+JavaScript on the client side.
+
+**In dev mode there is no prefetching.** The `ppr lock` + `push`
+workflow simulates instant navigation using a cookie mechanism that tells
+the dev server to respond as it would to a prefetch — rendering only the
+static shell and holding back dynamic content. This lets you inspect the
+instant shell without needing a production build.
+
+**Workflow:**
 
-**Direct load — the PPR shell.** Server HTML for a cold hit on the URL.
-Lock first, then `goto` the target — the lock suppresses hydration so you
-see exactly what the server sent. Screenshot once the load settles, then
-unlock.
+1. `ppr lock`
+2. `push` to the target route — shows the instant shell.
+3. `screenshot "Instant shell"` — evaluate visually.
+4. `ppr unlock` — read the shell analysis.
+5. Fix the top-most blocker, let HMR pick it up, re-lock, `push`,
+   and compare.
 
-**Client navigation — the prefetched shell.** What the router already
-holds when a link is clicked. The origin page decides this — it's the one
-doing the prefetching — so `goto` the origin *unlocked* and let it fully
-hydrate. Then lock, `push` to the target, let the navigation settle,
-screenshot, unlock. Locking before the origin hydrates means nothing got
-prefetched and `push` has nothing to show.
+The same principles from "Growing the HTML shell" apply — work top-down,
+move dynamic access into children, and escalate boundary placement and
+caching decisions to the user.
 
 Between iterations: check `errors` while unlocked.
 
-**After making a code change:** HMR picks it up — just re-lock,
-`goto` the page, and re-test. No need to `restart-server`.
+### Runtime prefetching for cookie-dependent instant shells
+
+When the instant shell (via `ppr lock` + `push`) is empty or shows only
+skeletons for routes that depend on `cookies()` or other request-scoped
+data, the static prefetch can't include that content — it runs without
+request context. Runtime prefetching solves this: the server generates
+prefetch data using real cookies, and the client caches it for instant
+navigations.
+
+Three features compose to make this work:
+
+| Feature                          | Role                                                                                  |
+| -------------------------------- | ------------------------------------------------------------------------------------- |
+| `unstable_instant`               | Declares the route must support instant navigation; validates a static shell exists    |
+| `unstable_prefetch = 'runtime'`  | Tells the server to produce a runtime prefetch stream with request context             |
+| `"use cache: private"`           | Caches per-request data (cookies) in the request-scoped Resume Data Cache so the runtime prefetch rerender reuses it without re-fetching |
+
+Without `unstable_prefetch = 'runtime'`, the prefetch only includes the
+static shell. Without `"use cache: private"`, the runtime prefetch
+re-executes every data call. All three are needed for instant
+navigations that show real personalized content.
+
+Read `node_modules/next/dist/docs/` for the full technical breakdown
+before starting — your training data may be outdated on these APIs.
+
+**Diagnosis:**
+
+1. Audit instant shells across the target routes:
+   ```
+   ppr lock
+   push /route-a → screenshot "route-a instant shell"
+   push /route-b → screenshot "route-b instant shell"
+   ...
+   ppr unlock
+   ```
+   Identify which routes show empty/skeleton shells.
+
+2. For each empty route, add `unstable_instant` temporarily and navigate
+   to it — `errors` will surface validation failures that name the
+   blocking API (`cookies()`, `connection()`, etc.) and the component
+   calling it. This is a diagnostic tool, not the fix itself.
+
+3. Read the source of the blocking components. The pattern to look for:
+   a data-fetching function reads `cookies()` → this makes the component
+   dynamic → it becomes a hole in the static shell → the instant shell
+   has nothing to show there.
+
+**The fix pattern (per route):**
+
+1. In the page's route segment config, export both:
+   ```ts
+   export const unstable_instant = true
+   export const unstable_prefetch = 'runtime'
+   ```
+
+2. In the data-fetching functions that read `cookies()`, add
+   `"use cache: private"` so the result is cached per-request and reused
+   by the runtime prefetch rerender. If `"use cache: private"` can't be
+   applied directly (e.g., file has `"use server"` directive), extract
+   the function to a separate file.
+
+3. If a shared layout or utility calls `connection()` to prevent sync
+   I/O during prefetch, investigate whether it also blocks runtime
+   prefetching. `connection()` opts into dynamic rendering, which
+   prevents the runtime prefetch stream from being generated. A
+   `setTimeout(resolve, 0)` macro task boundary provides the same sync
+   I/O protection without blocking runtime prefetch — but this is a
+   judgment call for the user (see **Escalate, don't decide**).
+
+**Verification:**
+
+Runtime prefetch data is generated during the initial page load and
+streamed to the client alongside the page content. The client's segment
+cache fills asynchronously — it is not instant.
+
+To verify:
+1. `goto` the origin page (the page the user navigates *from*).
+2. Wait 10–15 seconds for the runtime prefetch stream to complete.
+   The prefetch runs as a side-channel during the initial render — it
+   needs time to execute all `"use cache: private"` functions and stream
+   the results.
+3. `ppr lock`
+4. `push` to the target route — the instant shell should now show real
+   content, not just skeletons.
+5. `screenshot` to confirm.
+6. `ppr unlock` to see the shell analysis.
+
+If the shell is still empty after waiting, check:
+- Did the page actually load with runtime prefetch? `network` should
+  show the initial document response — runtime prefetch data is embedded
+  in the RSC payload, not a separate request.
+- Did `errors` surface any `unstable_instant` validation failures?
+- Is `unstable_prefetch = 'runtime'` exported from the correct segment?

src/browser.ts

@@ -535,6 +535,8 @@ export async function links() {
 export async function push(path: string) {
   if (!page) throw new Error("browser not open");
   const before = page.url();
+  const resolved = new URL(path, before).href;
+  if (resolved === before) throw new Error("already on this URL");
   await page.evaluate((p) => (window as any).next.router.push(p), path);
   await page.waitForURL((u) => u.href !== before, { timeout: 10_000 }).catch(() => {});
   return page.url();

src/cli.ts

@@ -171,7 +171,14 @@ if (cmd === "screenshot") {
   const fullPage = args.includes("--full-page");
   const caption = args.slice(1).filter((a) => a !== "--full-page").join(" ") || undefined;
   const res = await send("screenshot", { fullPage, caption });
-  exit(res, res.ok ? String(res.data) : "");
+  if (res.ok) {
+    const { path, errors } = res.data as { path: string; errors: unknown };
+    const parts = [path];
+    if (errors) parts.push("\nerrors:\n" + json(errors));
+    console.log(parts.join(""));
+    process.exit(0);
+  }
+  exit(res, "");
 }
 
 if (cmd === "snapshot") {

src/cookies.ts

@@ -6,7 +6,8 @@ export type CookiePair = { name: string; value: string };
  *
  *   1. JSON array — Playwright-style `[{"name": "x", "value": "y"}, ...]`.
  *   2. cURL command — as produced by DevTools → Network → Copy as cURL.
- *      The Cookie header is extracted from the `-H 'cookie: …'` argument.
+ *      Cookies are extracted from `-H 'cookie: …'` or `-b '…'`/`--cookie '…'`
+ *      (macOS Chrome uses `-b` instead of `-H`).
  *   3. Bare cookie header — `name=v; name=v; ...` (e.g. the value of the
  *      Cookie row in DevTools → Network → Request Headers).
  *
@@ -51,8 +52,11 @@ function extractCookieHeaderFromCurl(curl: string): string | null {
   const joined = curl.replace(/\\\r?\n\s*/g, " ").replace(/\^\r?\n\s*/g, " ");
   // -H 'cookie: …' (bash) or -H "cookie: …" (cmd). Chrome/Firefox use one
   // or the other depending on which Copy-as-cURL variant the user picked.
-  const m = joined.match(/-H\s+(['"])\s*cookie\s*:\s*([\s\S]*?)\1/i);
-  return m ? m[2] : null;
+  const h = joined.match(/-H\s+(['"])\s*cookie\s*:\s*([\s\S]*?)\1/i);
+  if (h) return h[2];
+  // macOS Chrome uses -b (or --cookie) instead of -H for cookies.
+  const b = joined.match(/(?:-b|--cookie)\s+(['"])([\s\S]*?)\1/);
+  return b ? b[2] : null;
 }
 
 function parseCookieHeader(header: string): CookiePair[] {

src/daemon.ts

@@ -104,8 +104,11 @@ async function run(cmd: Cmd) {
     return { ok: true, data };
   }
   if (cmd.action === "screenshot") {
-    const data = await browser.screenshot({ fullPage: cmd.fullPage, caption: cmd.caption });
-    return { ok: true, data };
+    const [path, errors] = await Promise.all([
+      browser.screenshot({ fullPage: cmd.fullPage, caption: cmd.caption }),
+      browser.mcp("get_errors").catch(() => null),
+    ]);
+    return { ok: true, data: { path, errors } };
   }
   if (cmd.action === "links") {
     const data = await browser.links();