Unverified Commit 56fca738 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

Make next-dev-loop browser headless by default (#98318)

## Summary

- make `next-dev-loop` open `agent-browser` headlessly for routine
verification
- keep one worktree-scoped restored `agent-browser` session
- open the current URL in the coding harness's inline browser when the
user asks to see the UI, while making clear that it is a separate
browser context
- relaunch the same `agent-browser` session with `--headed` only when
login or existing browser state must carry over
- update Cache Components adoption guidance to use the same explicit
browser handoff choices

## Why

Runtime browser verification is still needed for rendered behavior,
navigation, browser errors, and React state that compilation and type
checking cannot prove. That verification does not need to open a visible
browser for every task.

The coding harness may not be able to embed an existing `agent-browser`
session. The instructions now distinguish an inline presentation
handoff, which has separate cookies and storage, from a headed
`agent-browser` handoff that preserves the restored session's state.

## Verification

- Prettier passed for `skills/next-dev-loop/SKILL.md` and
`skills/next-cache-components-adoption/SKILL.md`
- verified the headless `agent-browser` flow and a separate
coding-harness inline-browser handoff against a running Next.js app
- not run: test suite (skill instructions only)

<!-- NEXT_JS_LLM -->
parent 9fea2239
...@@ -206,7 +206,7 @@ Per route: ...@@ -206,7 +206,7 @@ Per route:
### loop notes ### loop notes
- The [three blocker classes from background](#background) often get missed when fixing in place. Caching a downstream fetch (`getThing(id)`) doesn't clear an `await params` at the top of the page body — push the param promise into the `<Suspense>`-wrapped child. - The [three blocker classes from background](#background) often get missed when fixing in place. Caching a downstream fetch (`getThing(id)`) doesn't clear an `await params` at the top of the page body — push the param promise into the `<Suspense>`-wrapped child.
- Ambiguous calls are user check-ins, not agent judgment. When you're not sure which fix fits, the blocking code looks security-sensitive, or the user might want to keep the route blocking on purpose — read [references/per-page-decisions.md](./references/per-page-decisions.md) before editing. Show the route while you ask: the `next-dev-loop` session runs the browser headed, so drive to the page and leave it on screen so the user is looking at the thing they're deciding about, with a screenshot as the fallback when a headed browser isn't possible. "Should this stay blocking?" is much easier to answer while looking at the page than at a file path. - Ambiguous calls are user check-ins, not agent judgment. When you're not sure which fix fits, the blocking code looks security-sensitive, or the user might want to keep the route blocking on purpose — read [references/per-page-decisions.md](./references/per-page-decisions.md) before editing. Show the route while you ask using `next-dev-loop`'s browser handoff, with a screenshot as the fallback. "Should this stay blocking?" is much easier to answer while looking at the page than at a file path.
- Don't narrate the refactor with comments. The only comment the codemod (or you) should leave is `// TODO: Cache Components adoption` on opt-outs, and the user's existing comments. Don't annotate every `<Suspense>` boundary or `"use cache"` call with what it does — the code says that. Drop a comment only when the _why_ isn't clear from the code (e.g. a deliberate Block with a reason). - Don't narrate the refactor with comments. The only comment the codemod (or you) should leave is `// TODO: Cache Components adoption` on opt-outs, and the user's existing comments. Don't annotate every `<Suspense>` boundary or `"use cache"` call with what it does — the code says that. Drop a comment only when the _why_ isn't clear from the code (e.g. a deliberate Block with a reason).
- For many routes with the same mechanical fix, verify one representative route first. Then batch disjoint route groups using the same recipe, and run the shared build and browser checks together. - For many routes with the same mechanical fix, verify one representative route first. Then batch disjoint route groups using the same recipe, and run the shared build and browser checks together.
...@@ -226,7 +226,7 @@ Then check in with the user. Same rule as the pre-step: speak their language. Do ...@@ -226,7 +226,7 @@ Then check in with the user. Same rule as the pre-step: speak their language. Do
- What you did: which routes you touched, and the user-visible result per route (e.g. "the post page now streams the article body behind a skeleton while the layout stays static"). - What you did: which routes you touched, and the user-visible result per route (e.g. "the post page now streams the article body behind a skeleton while the layout stays static").
- What changed: opt-outs removed, fallbacks added, caching boundaries introduced. - What changed: opt-outs removed, fallbacks added, caching boundaries introduced.
- Show, don't tell. The `next-dev-loop` session runs the browser headed, so drive the route live for the user so they see the static shell → fallback → final content sequence in real time. If you can't drive a live browser, attach the before/after screenshots you captured instead. - Show, don't tell. Follow `next-dev-loop`'s browser handoff and drive the route live so the user sees the static shell → fallback → final content sequence. If live presentation is unavailable, attach the before/after screenshots you captured.
- Give them the click-through: a short table of the feature's routes — the URL to open and what to look for (what renders instantly, which fallbacks appear, what streams in) — so they can verify each one themselves. - Give them the click-through: a short table of the feature's routes — the URL to open and what to look for (what renders instantly, which fallbacks appear, what streams in) — so they can verify each one themselves.
- The question: "Want to open this feature as a PR and move on to the next, or stop here?" Wait for the answer. - The question: "Want to open this feature as a PR and move on to the next, or stop here?" Wait for the answer.
......
...@@ -65,7 +65,7 @@ Once per session, confirm both views are live. ...@@ -65,7 +65,7 @@ Once per session, confirm both views are live.
Then open the target URL: Then open the target URL:
```bash ```bash
agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url> agent-browser --session "$SESSION" --restore --enable react-devtools open <url>
``` ```
`--scope worktree` keeps parallel worktrees and copied checkouts `--scope worktree` keeps parallel worktrees and copied checkouts
...@@ -75,11 +75,17 @@ Once per session, confirm both views are live. ...@@ -75,11 +75,17 @@ Once per session, confirm both views are live.
launch flags on `open`; agent-browser will reuse, relaunch, or restart launch flags on `open`; agent-browser will reuse, relaunch, or restart
its scoped background state as needed. its scoped background state as needed.
The browser is the user's. If state was not restored (first run, Keep routine verification headless. If the user asks to see the UI, open the
expired session) and the page is gated, the user drives the login — current URL in the coding harness's inline browser. It is a separate browser
pause until they confirm. After login, continue using the same session context, so do not assume state carries over. When login or existing
and restore context; `agent-browser close` saves the cookie state so `agent-browser` state must carry over, reopen that session headed instead:
the next `open` restores it.
```bash
agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>
```
Pause while the user drives login, then continue with the same session and
keep it headed for the rest of the loop.
2. Probe `/_next/mcp` (`tools/list`) — confirm it's reachable and 2. Probe `/_next/mcp` (`tools/list`) — confirm it's reachable and
lists `get_compilation_issues`. First read the port off the lists `get_compilation_issues`. First read the port off the
...@@ -146,11 +152,11 @@ manual rather than from memory. ...@@ -146,11 +152,11 @@ manual rather than from memory.
- A blank read, empty snapshot, `about:blank`, or a "no browser - A blank read, empty snapshot, `about:blank`, or a "no browser
session" error — right after `open` or after a click (even if `open` session" error — right after `open` or after a click (even if `open`
reported the page) — is the browser dropping the page (a stale reported the page) — is the browser dropping the page (a stale
session), not a broken route. Reopen your session at the URL with session), not a broken route. Reopen your session at the URL with the
`--session "$SESSION" --restore` and re-snapshot; if still blank, same launch flags as the active loop, then re-snapshot. If still blank, run
run `agent-browser --session "$SESSION" --restore close`, then open `agent-browser --session "$SESSION" --restore close`, then reopen with
again. Don't fall back to `curl`; it bypasses the browser you're those same flags. Don't fall back to `curl`; it bypasses the browser
testing. you're testing.
- React introspection output is stale after navigation. Re-run. - React introspection output is stale after navigation. Re-run.
- `/_next/mcp` replies are SSE — read the JSON off the `data:` line - `/_next/mcp` replies are SSE — read the JSON off the `data:` line
with `sed -n 's/^data: //p'` (a plain `sed 's/^data: //'` leaves the with `sed -n 's/^data: //p'` (a plain `sed 's/^data: //'` leaves the
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment