[pull] canary from vercel:canary

AGENTS.md

@@ -70,7 +70,7 @@ pnpm --filter=next exec taskr <task>
 
 ## Fast Local Development
 
-For iterative development, default to watch mode + skip-isolate for the inner loop (not full builds), with exceptions noted below.
+For iterative development, default to watch mode plus the explicit test script that matches the mode and bundler being verified.
 
 **Default agent rule:** If you are changing Next.js source or integration tests, start `pnpm --filter=next dev` in a separate terminal session before making edits (unless it is already running). If you skip this, explicitly state why (for example: docs-only, read-only investigation, or CI-only analysis).
 
@@ -82,13 +82,20 @@ For iterative development, default to watch mode + skip-isolate for the inner lo
 pnpm --filter=next dev
 ```
 
-**2. Run tests fast (no isolation, no packing):**
+**2. Run focused tests with the matching mode script:**
 
 ```bash
-# NEXT_SKIP_ISOLATE=1 - skip packing Next.js for each test (~100s faster)
-# NEXT_TEST_MODE=<mode> - run dev or start based on the context provided
-# testheadless - runs headless with --runInBand (no worker isolation overhead)
-NEXT_SKIP_ISOLATE=1 NEXT_TEST_MODE=<dev|start> pnpm testheadless test/path/to/test.ts
+# Development mode with Turbopack
+pnpm test-dev-turbo test/path/to/test.ts
+
+# Development mode with Webpack
+pnpm test-dev-webpack test/path/to/test.ts
+
+# Production build+start with Turbopack
+pnpm test-start-turbo test/path/to/test.ts
+
+# Production build+start with Webpack
+pnpm test-start-webpack test/path/to/test.ts
 ```
 
 **3. When done, kill the background watch process (if you started it).**
@@ -104,8 +111,6 @@ git checkout <branch>
 pnpm build-all   # Sets up outputs for dependent packages (Turborepo dedupes if unchanged)
 ```
 
-**When NOT to use NEXT_SKIP_ISOLATE:** Drop it when testing module resolution changes (new require() paths, new exports from entry-base.ts, edge route imports). Without isolation, the test uses local dist/ directly, hiding resolution failures that occur when Next.js is packed as a real npm package.
-
 ## Bundler Selection
 
 Turbopack is the default bundler for both `next dev` and `next build`. To force webpack:
@@ -140,7 +145,6 @@ pnpm test-dev-turbo test/development/
 **Other test commands:**
 
 - `pnpm test-unit` - Run unit tests only (fast, no browser)
-- `pnpm testheadless <path>` - Run tests headless without rebuilding (faster iteration when build artifacts are already up to date)
 - `pnpm new-test` - Generate a new test file from template (interactive)
 
 **Generate tests non-interactively (for AI agents):**
@@ -245,7 +249,7 @@ General triage rules (always apply; `$pr-status-triage` skill expands on these):
 - Prioritize blocking failures first: build, lint, types, then tests.
 - Assume failures are real until disproven; use "Known Flaky Tests" as context, not auto-dismissal.
 - Reproduce with the same CI mode/env vars (especially `IS_WEBPACK_TEST=1` when present).
-- For module-resolution/build-graph fixes, verify without `NEXT_SKIP_ISOLATE=1`.
+- For module-resolution/build-graph fixes, use the normal mode-specific test command so package resolution is exercised.
 
 For full triage workflow (failure prioritization, mode selection, CI env reproduction, and common failure patterns), use the `$pr-status-triage` skill:
 
@@ -392,7 +396,7 @@ For runtime internals, use focused skills:
 
 Keep these high-frequency guardrails in mind:
 
-- Reproduce module resolution and bundling issues without `NEXT_SKIP_ISOLATE=1`
+- Reproduce module resolution and bundling issues with the normal mode-specific test command so package resolution is exercised.
 - Validate edge bundling regressions with `pnpm test-start-webpack test/e2e/app-dir/app/standalone.test.ts`
 - Use `__NEXT_SHOW_IGNORE_LISTED=true` when you need full internal stack traces
 
@@ -413,7 +417,7 @@ Core runtime/bundling rules (always apply; skills above expand on these with ver
 - Don't rely on exact log messages - filter by content patterns, find sequences not positions
 - **Snapshot tests vary by env flags**: Tests with inline snapshots can produce different output depending on env flags. When updating snapshots, always run the test with the exact env flags the CI job uses (check `.github/workflows/build_and_test.yml` `afterBuild:` sections). Turbopack resolves `react-dom/server.edge` (no Node APIs like `renderToPipeableStream`), while webpack resolves the `.node` build (has them).
 - **`app-page.ts` is a build template compiled by the user's bundler**: Any `require()` in this file is traced by webpack/turbopack at `next build` time. You cannot require internal modules with relative paths because they won't be resolvable from the user's project. Instead, export new helpers from `entry-base.ts` and access them via `entryBase.*` in the template.
-- **Reproducing CI failures locally**: Always match the exact CI env vars (check `pr-status` output for "Job Environment Variables"). Key differences: `IS_WEBPACK_TEST=1` forces webpack (turbopack is default), `NEXT_SKIP_ISOLATE=1` skips packing next.js (hides module resolution failures). Always run without `NEXT_SKIP_ISOLATE` when verifying module resolution fixes.
+- **Reproducing CI failures locally**: Always match the exact CI env vars (check `pr-status` output for "Job Environment Variables"). Key differences such as `IS_WEBPACK_TEST=1` can change bundler selection and snapshot output, so use the CI command and mode when verifying module resolution fixes.
 - **Showing full stack traces**: Set `__NEXT_SHOW_IGNORE_LISTED=true` to disable the ignore-list filtering in dev server error output. By default, Next.js collapses internal frames to `at ignore-listed frames`, which hides useful context when debugging framework internals. Defined in `packages/next/src/server/patch-error-inspect.ts`.
 - **Router act tests must use LinkAccordion to control prefetches**: Always use `LinkAccordion` to control when prefetches happen inside `act` scopes. Never use `browser.back()` to return to a page where accordion links are already visible — BFCache restores state and triggers uncontrolled re-prefetches. See `$router-act` for full patterns.