@rangojs/router 0.27.0 → 0.29.0

package/skills/observability/SKILL.md

@@ -277,6 +277,36 @@ Events include `request.start/end/error`, `loader.start/end/error`,
 `handler.error`, `cache.decision`, `revalidation.decision`, `request.timeout`,
 and `request.origin-rejected`.
 
+## Errors reported to onError
+
+`createRouter({ onError })` sees every server error, including errors from
+work no visitor waits on. A stale `cache()` record, document cache entry, PPR
+shell, `"use cache"` function or cached loader is served stale and refreshed
+beside the request. That refresh's error carries `background: true`, with the
+starting request's `request` and `url`, and `handledByBoundary: false`: the
+failed render is not stored, so no one sees its fallback. The stale entry
+keeps serving.
+
+```typescript
+const router = createRouter({
+  onError: ({ error, phase, background, routeKey, duration }) => {
+    errorTracker.capture(error, {
+      // A failed refresh is not a failed page view.
+      level: background ? "warning" : "error",
+      tags: { phase, route: routeKey },
+      extra: { duration },
+    });
+  },
+});
+```
+
+`duration` is the time from the request's start to the error; for a
+`background` error, from the start of the request that started the refresh.
+`segmentId` and `segmentType` name the segment that threw: an intercept's or
+a parallel slot's error reports the slot (`segmentType: "parallel"`), an
+orphan layout's error the orphan layout, even when the owning layout's
+boundary renders the fallback.
+
 ## Debugging revalidation and stale data
 
 When stale UI or unexpected partial renders are the question, use all three

package/skills/ppr/SKILL.md

@@ -450,7 +450,7 @@ non-claiming read option.
 
 The first cold partial request reports `BYPASS; reason=no-entry` because no
 artifact could supply that response; its successful render schedules
-`scheduleShellCapture` with a navigation-only marker. The next request reports
+`planShellCapture` with a navigation-only marker. The next request reports
 `HIT` when the capture produced an eligible snapshot. Navigation snapshots use
 a separate shell key, so they cannot overwrite or be served as a document shell.
 The capture runs with the stripped target document URL and loads SSR support in
@@ -509,7 +509,9 @@ In handlers it is
 too late to prevent a MISS render from already happening, but it still prevents
 the follow-up shell capture. A `ctx.dynamic()` call that only happens during the
 capture itself (for example inside a handler promise, after an await) refuses
-that capture: a dynamic render has no shell.
+that capture: a dynamic render has no shell. A cached handler that calls it in
+the background refresh of a stale `cache()` record does not: the capture
+replayed the record, and the refresh renders the record only.
 
 During `Prerender` + `ppr` build-shell capture, middleware is replayed with
 `ctx.build === true`, `ctx.waitUntil()` inert, and the same `ctx.dynamic()`
@@ -1177,7 +1179,7 @@ their data should bake vs stay live. Your levers, in order of preference:
 3. **Guaranteed-fresh widgets: live loaders with a widget-sized boundary.**
    An unflagged loader read under an inline `<Suspense>` in the widget is
    enough. Alternatively, a parallel slot with its OWN `loading()`:
-   parallel-owned loaders get their own per-slot boundary (`fresh.ts` tags
+   parallel-owned loaders get their own per-slot boundary (`resolveParallelSegments` tags
    them with the slot's loading; `segment-system.tsx` builds a per-slot
    LoaderBoundary), so the chrome bakes into the shell and each widget is an
    independent, widget-sized hole:
@@ -1633,6 +1635,19 @@ evicted by tag at all — move always-fresh data into a live-lane loader (no
   capture is served as before. Only a throw during the capture counts: a
   component that failed in the live render and succeeds when captured is
   stored.
+- **A handler that throws during capture refuses it too**: when a route,
+  layout or parallel slot handler throws (or throws `notFound()`) on the
+  capture's own run while the request that scheduled it rendered fine, for
+  example on a flaky upstream, its boundary (a declared `errorBoundary()` or
+  `notFoundBoundary()`, or the default error page) would become the shell.
+  The capture stores nothing, logs `[ShellCache] capture`, reports to
+  `onError` as `cache-write`, and backs the key off; the next capture after
+  the window stores normally. A request whose own render fails answers
+  500/404 and schedules no capture, but a recapture has no visitor render
+  behind it: a stale shell whose recapture fails keeps serving until its
+  `ttl` + `swr` ends (a build-time shell, until a recapture stores), as a
+  failed `cache()` refresh does, logging and calling `onError` once per
+  backoff window. When you delete a page, invalidate its tag.
 
 ## Related
 

package/skills/prerender/SKILL.md

@@ -309,16 +309,16 @@ layout(DocsNav, () => [
 
 ## Interaction with DSL Items
 
-| DSL item       | Behavior with Prerender                                                                                                                                                                                                                                                     |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `loader()`     | Live at runtime, bundled normally. Use `cache()` for caching.                                                                                                                                                                                                               |
-| `revalidate()` | Without Passthrough: no effect on the prerendered segments (re-served from the build artifact); loader revalidation still works. With Passthrough: re-renders through the live handler.                                                                                     |
-| `cache()`      | Orthogonal -- prerendered segments bypass the runtime cache. Use `cache()` on parent layouts and loaders.                                                                                                                                                                   |
-| `layout()`     | Child layouts inside path are pre-rendered. Parent layouts are live.                                                                                                                                                                                                        |
-| `parallel()`   | Parallel slots inside path are pre-rendered.                                                                                                                                                                                                                                |
-| `middleware()` | Skipped while collecting build-time Flight payloads (no request). For `Prerender` + `ppr`, the build-shell step replays global and route middleware with `ctx.build === true`; `ctx.dynamic()` skips that shell. At request time middleware runs normally on every request. |
-| `loading()`    | Ignored without Passthrough. Works for live fallback with Passthrough.                                                                                                                                                                                                      |
-| `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside main segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when` config conditions are skipped at build time (all intercepts are pre-rendered unconditionally).    |
+| DSL item       | Behavior with Prerender                                                                                                                                                                                                                                                                                                                                         |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loader()`     | Live at runtime, bundled normally. Use `cache()` for caching.                                                                                                                                                                                                                                                                                                   |
+| `revalidate()` | Without Passthrough: re-runs no prerendered handler (segments are re-served from the build artifact); when the params change, a held parent layout whose `revalidate()` asks for it gets its baked copy. Loader revalidation still works. With Passthrough: re-renders through the live handler.                                                                |
+| `cache()`      | Orthogonal -- prerendered segments bypass the runtime cache. Use `cache()` on parent layouts and loaders.                                                                                                                                                                                                                                                       |
+| `layout()`     | Child layouts inside path are pre-rendered. Parent layouts are pre-rendered too: every hit, intercept variant included, serves them from the build artifact and runs no layout handler. On a navigation a parent layout the client holds stays held, even when the params change, as on a live route.                                                           |
+| `parallel()`   | Parallel slots inside path are pre-rendered. A parent layout's slots are pre-rendered too: a hit serves them from the build artifact with the layout, and one the client holds stays held, as on a live route.                                                                                                                                                  |
+| `middleware()` | Skipped while collecting build-time Flight payloads (no request). For `Prerender` + `ppr`, the build-shell step replays global and route middleware with `ctx.build === true`; `ctx.dynamic()` skips that shell. At request time middleware runs normally on every request.                                                                                     |
+| `loading()`    | Ignored without Passthrough. Works for live fallback with Passthrough.                                                                                                                                                                                                                                                                                          |
+| `intercept()`  | Pre-rendered at build time. Intercept variant stored under `/i` key alongside the main entry, without the route's own segments. At runtime, the correct variant is served based on `ctx.isIntercept`. `when` config conditions are skipped at build time (all intercepts are pre-rendered unconditionally); a navigation serves only the intercept it selected. |
 
 When Passthrough revalidation is enabled, remember that revalidation is
 still partial: opting a child segment into revalidation does not
@@ -1426,19 +1426,24 @@ export const urlpatterns = urls(({ path, include }) => [
 ## Interaction with intercept()
 
 When a pre-rendered route is also the target of an `intercept()`, the build system
-resolves the intercept handler at build time and stores a combined entry (main
-segments + intercept segments) under an `/i`-suffixed key alongside the main entry:
+resolves the intercept handler at build time and stores an intercept variant
+under an `/i`-suffixed key alongside the main entry. The variant holds what an
+intercept navigation renders: the main segments without the route's own (its
+handler, layouts and slots, which a render under an intercept skips), then the
+intercept segments, with the handle values of exactly those segments:
 
 ```
 prerender store keys:
   "blog.post/a1b2c3"      -> main segments (full page)
-  "blog.post/a1b2c3/i"    -> main segments + intercept segments (modal variant)
+  "blog.post/a1b2c3/i"    -> main segments without the route's own + intercept segments
 ```
 
 At runtime, the cache-lookup middleware checks `ctx.isIntercept`:
 
 - **Intercept navigation**: looks up `paramHash/i` first. If found, yields
-  the combined entry. `handleCacheHitIntercept()` extracts intercept segments
+  the variant's segments with only the slot of the intercept the navigation
+  selected (`selectInterceptVariant`); a variant without that slot is a miss.
+  `handleCacheHitIntercept()` extracts intercept segments
   (filtered by `namespace?.startsWith("intercept:")`) and sets up slots.
 - **Direct navigation**: looks up `paramHash` (no suffix). Standard prerender path.
 - **Intercept miss (no `/i` entry)**: falls through to the normal pipeline so
@@ -1447,7 +1452,26 @@ At runtime, the cache-lookup middleware checks `ctx.isIntercept`:
 
 The `when` config selector receives an `InterceptSelectorContext` whose `from`
 location (the page being left) is unknown at build time. All intercepts are pre-rendered unconditionally;
-`when` is evaluated at runtime by the intercept-resolution middleware.
+`when` is evaluated at runtime by the intercept-resolution middleware, and a
+navigation shows only the intercept it selected: the innermost whose `when`
+passes, as on a route that is not pre-rendered. Two intercepts on one layout
+that fill the same slot are not pre-rendered: the variant could not tell them
+apart, so they render live. Intercepts declared in the route's own layouts are
+never selected and are not pre-rendered.
+
+The build warns once per route and slot for an intercept a navigation can
+select that is not pre-rendered: two intercepts that fill one slot, a handler
+or layout that returned a `Response` at build time, or an intercept that
+targets the route by its name inside an `include()` (`"item"` for the route
+`"shop.item"`, or for a route named `"item"` in an unnamed `include()`), which
+only the local-name fallback selects (name the `include()` and target the
+full name, or declare the intercept inside it with `".item"`, to pre-render
+it). That intercept renders live, and its handler runs per request without
+`BuildContext`; a route in an unnamed `include()` is named by its URL:
+
+```
+[rango] Prerender route "item": intercept @modal is not pre-rendered: two intercepts on one layout fill @modal. A navigation that selects it renders it live, and its handler runs per request without BuildContext. To pre-render it, give each intercept its own slot.
+```
 
 ### Example: Pre-rendered route with intercept
 

package/skills/rango/SKILL.md

@@ -249,7 +249,11 @@ identity".
 The predicate arg carries the action's full context, not just its identity. Match
 _which_ action with `ctx.isAction(addToCart)` (rename-safe); branch on _what it
 returned_ with `ctx.actionResult` — the value your `"use server"` function
-returned, for outcome-conditional revalidation. The arg also exposes `actionId`
+returned, for outcome-conditional revalidation. When the action threw into an
+`errorBoundary()`, a predicate above the boundary still runs, with
+`actionResult` set to the thrown value: check a field's shape before reading
+it (`Array.isArray(actionResult?.items)`). A `redirect()` it throws then redirects, as
+after a success. The arg also exposes `actionId`
 (raw `path#export`), `actionUrl`, `formData` (form-based actions only), `method`,
 and `stale` (the `_rsc_stale` signal that an action ran in this or another tab;
 that Back/Forward revalidation takes an action's defaults, but `isAction()` is

package/skills/server-actions/SKILL.md

@@ -569,6 +569,10 @@ A few details:
   until a request re-runs them.
 - It holds no segments, so every loader on the page re-runs whatever its
   `revalidate()` says, and the document cache never answers it.
+- If a later action on that page threw into its `errorBoundary()`, the
+  revalidation keeps the boundary on screen: everything above it re-runs,
+  nothing at or below it. Under the router's default boundary at the root,
+  nothing runs. A link from the page re-runs what is at or below the boundary.
 - Going Back or Forward out of an intercept does not abort an action sent from
   the intercept. `useAction()` and your `await` get its real result.
 
@@ -704,7 +708,17 @@ is usually too aggressive.
 Throw for genuinely exceptional conditions (network failure, DB outage,
 auth violation). The nearest `errorBoundary()` above the page the action was
 called from catches them, and the boundary renders inside route middleware like
-a normal render.
+a normal render. Above the boundary the response is the action's revalidation,
+as after a success: the layouts' loaders re-run as their `revalidate()`
+decides, so a cart count shows what the action wrote before it threw. A
+route's `errorBoundary()` replaces the route: its handler and loaders do not
+run. A layout's `errorBoundary()` replaces what the layout renders in its
+outlet: the layout's own loaders, slots and orphan layouts revalidate as on a
+success, and nothing inside the outlet runs. A link from the page re-runs
+what the boundary replaced and everything under it; under the router's
+default boundary at the root, the whole page. Back to the page later
+restores it and revalidates it, which replaces the boundary with the route. An action sent from an intercept
+gets the boundary alone.
 
 ```typescript
 // urls.tsx — inside the urls() callback

package/skills/testing/client-components.md

@@ -66,9 +66,13 @@ type RenderRouteResult = RenderResult & {
       url: string,
       options?: {
         loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+        handles?: ReadonlyArray<readonly [Handle<any, any>, unknown[]]>;
         state?: HistoryState;
         replace?: boolean;
         transition?: boolean;
+        // the response's stream: opens a task after the call, before the
+        // commit, and stays open until the promise settles (isStreaming)
+        streamUntil?: Promise<unknown>;
       },
     ): Promise<void>;
     // re-render the current location, as router.refresh() does:
@@ -203,13 +207,14 @@ it("lists no product twice while the next page loads", async () => {
 });
 ```
 
-| To bring state to a reader                          | Do                                                                                                                                                                                                                                           |
-| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| a push / replace, the component's own               | click its `<Link state>` or the control that calls `router.push(url, { state })`, then `waitFor`                                                                                                                                             |
-| a push / replace whose loader the test holds        | `router.navigate(url, { state, replace?, loaders: [[Loader, pendingPromise]] })` on a `transition` spec                                                                                                                                      |
-| back/forward onto an entry                          | `history.replaceState(entry, "")`, then `window.dispatchEvent(new Event("popstate"))` inside `act`. The tree has one location, so no page is restored: readers take the entry as history holds it (also how a `Def.write()` becomes visible) |
-| a reader that mounts while a navigation is pending  | hold the navigation as in the row above, then mount the reader inside `await act(async () => { ... })`: it reads the entry on screen                                                                                                         |
-| a server action's state, a redirect's, an intercept | e2e                                                                                                                                                                                                                                          |
+| To bring state to a reader                                    | Do                                                                                                                                                                                        |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| a push / replace, the component's own                         | click its `<Link state>` or the control that calls `router.push(url, { state })`, then `waitFor`                                                                                          |
+| a push / replace whose loader the test holds                  | `router.navigate(url, { state, replace?, loaders: [[Loader, pendingPromise]] })` on a `transition` spec                                                                                   |
+| back/forward onto the mounted entry or one a navigation wrote | `window.history.back()` inside `await act(async () => { ... })`: the entry's page is restored with its state and handle values, as production's history-cache restore is                  |
+| back/forward onto an entry the test wrote                     | `history.replaceState(entry, "")`, then `window.dispatchEvent(new Event("popstate"))` inside `act`: readers take the entry as history holds it (also how a `Def.write()` becomes visible) |
+| a reader that mounts while a navigation is pending            | hold the navigation as in the row above, then mount the reader inside `await act(async () => { ... })`: it reads the entry on screen                                                      |
+| a server action's state, a redirect's, an intercept           | e2e                                                                                                                                                                                       |
 
 ### Definitions with `clearOnReload`
 
@@ -390,17 +395,19 @@ it("dims the held price while the next product streams", async () => {
 });
 ```
 
-| Pending state                                                                                  | Under `renderRoute`                                                                                                                                                                                    |
-| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed            | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                                                          |
-| `transition` navigate(), settled seed (a plain value)                                          | `false`; the data swaps in the commit.                                                                                                                                                                 |
-| navigate() without `transition`, pending seed                                                  | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag.                                         |
-| `transition: { when }` returning false, or `navigate(url, { transition: false })`              | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.                                              |
-| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic) | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                                                                       |
-| `useNavigation().state`, `useLinkStatus().pending`                                             | Modeled: navigate() starts the navigation as a click does. `loading` from the call, `idle` in the commit, held with it; `pending` true for the destination's link until the commit is handed to React. |
-| `useAction().state`                                                                            | Stays `idle`: navigate() runs no action. e2e.                                                                                                                                                          |
-| `useHandle()` on a held navigation, `navigate(url, { handles, loaders })`                      | Modeled: `handles` arrive on the response's handle stream, so readers keep the page being left's values while React holds the page and take the new ones with its commit.                              |
-| A back/forward restored from the history cache (its view transition, `pop`)                    | NOT modeled: the tree has one location and navigate() caches no entries, so a `popstate` restores nothing. Assert it at e2e.                                                                           |
+| Pending state                                                                                  | Under `renderRoute`                                                                                                                                                                                                  |
+| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed            | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                                                                        |
+| `transition` navigate(), settled seed (a plain value)                                          | `false`; the data swaps in the commit.                                                                                                                                                                               |
+| navigate() without `transition`, pending seed                                                  | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag.                                                       |
+| `transition: { when }` returning false, or `navigate(url, { transition: false })`              | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.                                                            |
+| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic) | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                                                                                     |
+| `useNavigation().state`, `useLinkStatus().pending`                                             | Modeled: navigate() starts the navigation as a click does. `loading` from the call, `idle` in the commit, held with it; `pending` true for the destination's link until that commit, held with it too.               |
+| `useAction().state`                                                                            | Stays `idle`: navigate() runs no action. e2e.                                                                                                                                                                        |
+| `useHandle()` on a held navigation, `navigate(url, { handles, loaders })`                      | Modeled: `handles` arrive on the response's handle stream, so readers keep the page being left's values while React holds the page and take the new ones with its commit.                                            |
+| `useNavigation().isStreaming` past the commit, `navigate(url, { streamUntil })`                | Modeled: the stream opens a task after the call (`pendingUrl` clears) and ends when the promise settles or a newer navigation aborts it; settle it inside `await act(async () => ...)`.                              |
+| A navigation started while React holds a page (a newer click, a `transition: false` commit)    | Call it inside `await act(async () => { ... })`: its first update makes React retry the held page, and a synchronous `act()` drops that retry, so a later urgent commit never renders.                               |
+| A back/forward restored from the history cache (`pop`)                                         | Modeled for the mounted entry and one a navigate() wrote: the page and its handle values come back, decided by `transition({ when })` as kind `"pop"`. A stale entry's revalidation and a restore that fetches: e2e. |
 
 - Per-navigation seeds merge over the render-time `loaders`/`loaderData` for THAT navigation only; a later `navigate()` without `loaders` falls back to the render-time data.
 - Pass settled data as a plain value, not `Promise.resolve(value)`: React has not observed a plain promise yet, so it counts as pending and renders one `stale` frame. (A Flight chunk that has already settled carries its status and is skipped, which a plain value mirrors.)

package/skills/testing/response-routes.md

@@ -2,7 +2,7 @@
 
 **Layer:** integration (node) · **Import:** `@rangojs/router/testing` · **DSL it tests:** response routes (json/text/html/xml/md), redirects, 404 (see `/response-routes`, `/mime-routes`)
 
-`dispatch` runs the router's REAL matching (reusing `previewMatch`) and the real global + route-level middleware chain, with no RSC render — so redirects, 404s, response routes, content negotiation, and middleware short-circuits behave exactly as in production. You SEED the request and `env`; everything else (matching, middleware, header/cookie merge) is real machinery.
+`dispatch` runs the production handler's REAL request stages — classify (matching + content negotiation), the terminal plans (reloads, the rewritten-action rule), and the real global + route-level middleware chain — with no RSC render, so redirects, 404s, reloads, response routes, content negotiation, and middleware short-circuits behave exactly as in production. You SEED the request and `env`; everything else (matching, middleware, header/cookie merge) is real machinery.
 
 Matching goes through the route trie, as every request in `vite dev` and production does.
 
@@ -83,8 +83,9 @@ describe("api routes via dispatch", () => {
 - trailing-slash redirects from the trie — a route with `trailingSlash: "never"` or `"always"` answers the other form with a 308 and the `Location` (query preserved). A route with no `trailingSlash` serves its URL with and without a trailing slash, with no redirect, as production does;
 - the open-redirect guard on browser-followed redirects (a cross-origin `Location` is rewritten to the basename root unless `redirect(url, { external: true })`);
 - content-negotiated routes (`Vary: Accept` appended);
+- the reloads production answers inside the global middleware chain: a request whose `_rsc_v` names another deploy's document version (`setBuildVersions`, `./serve-shell-request.md`), and a `_rsc_partial` request whose `_rsc_rid` names another router (a cross-app navigation), get an `X-RSC-Reload` at the visitor's URL — on any route, a component route or an unmatched path included;
 - cached response routes (`cache({ ... })` around a `path.json` etc.): hit, SWR, and tag writes. The cache write is scheduled via `waitUntil` (a microtask in tests), so flush microtasks between the seeding `dispatch` and the one that asserts the hit;
-- `createRouter({ telemetry })` `request.start` / `request.end` / `request.error` events, and `createRouter({ onError })` for cache-read/write failures.
+- `createRouter({ telemetry })` `request.start` / `request.end` / `request.error` events, all with one `requestId`, which a response route's `request.timeout` carries too (a rewritten pass's included), and `createRouter({ onError })` for cache-read/write failures.
 
 ## Caveats
 
@@ -94,9 +95,10 @@ describe("api routes via dispatch", () => {
 - Setup: needs the preset (alias + virtual stubs) or a Vite-RSC env (see `./setup.md`); a bare router import throws on Vite virtuals.
 - Building the trie runs route discovery: every `include()`d `urls()` handler runs once more, and every async include provider (`() => import(...)`) is called. Count provider calls or handler runs after the first `dispatch` on that router, not from router construction. A provider that rejects fails the `dispatch`, as it fails `vite dev` and the build.
 - A router using `Prerender()`/`createLoader()`/`Static()` now constructs in a bare test (each assigns a runtime fallback `$$id`). Importing the whole router _file_ may still need the plugin (its page modules pull app deps / `virtual:` modules) — build from a focused include (your API routes) for whole-router dispatch.
-- A `throw rewrite(target)` from global or route middleware re-dispatches as the router does: global middleware matched on the target's path, the target's route middleware and handler, the same request context, `x-rango-rewrite` on the response, 508 on a loop. The visitor's URL is matched before middleware runs, so it must be a response route (or a redirect or 404) too; a rewrite target that is a component route throws the same error as a direct request.
+- A `throw rewrite(target)` from global or route middleware re-dispatches as the router does: global middleware matched on the target's path, the target's route middleware and handler, the same request context, `x-rango-rewrite` on the response, 508 on a loop. The visitor's URL is matched before middleware runs, so it must be a response route (or a redirect or 404) too; a rewrite target that is a component route throws the same error as a direct request. An action request (`?_rsc_action`) a rewrite moves to a response route, a redirect or an unmatched path rejects with production's error, `A rewrite of a server action or form post must target a page route; …`.
+- The route's params and name are set inside the global middleware chain, as production sets them: a global middleware reads `ctx.routeName` (and `getRequestContext().params`) after `await next()`, not before it. A trailing-slash redirect sets none.
 - A `_rsc_partial` request to a response route runs global middleware first (an auth gate can still 401/redirect), then returns `X-RSC-Reload` — route-level middleware is skipped, exactly like production.
-- `dispatch` does NOT execute server actions (`?_rsc_action`), but it DOES run the global middleware chain on an action request — middleware can still 401/redirect it, and any 3xx redirect on a partial OR action request becomes a `204` + `X-RSC-Redirect` (fetch-safe interception), the raw `Location` dropped. Location state carried on such a redirect is dropped too (production embeds it in a Flight payload); cover that at e2e.
+- `dispatch` does NOT execute server actions (`?_rsc_action`), but it DOES run the global middleware chain on an action request — middleware can still 401/redirect it. When a global middleware matches the path, any 3xx that leaves the chain on a partial OR action request (a global or route middleware's redirect, a response route's, a trailing-slash redirect) becomes a `204` + `X-RSC-Redirect` (fetch-safe interception), the raw `Location` dropped. Without one, an action request's 3xx goes out raw (through the open-redirect guard), as production sends it; a trailing-slash redirect on a partial request is a `204` either way. Location state carried on such a redirect is dropped too (production embeds it in a Flight payload); cover that at e2e.
 - `createRouter({ onError })` is NOT invoked for a thrown non-Response HANDLER error here (the typed error Response still matches production), and `cache.decision` / `loader.*` telemetry never fires (no RSC render runs). Cover both at e2e.
 
 ## See also

package/skills/testing/serve-shell-request.md

@@ -20,13 +20,13 @@ A `Prerender` route is served as in production: from the artifact `router.matchF
 
 ### Options — `ServeShellRequestOptions`
 
-| Field        | Type                                                                                                                                                    | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cacheStore` | `SegmentCacheStore`                                                                                                                                     | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `env`        | `TEnv`                                                                                                                                                  | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `headers`    | `HeadersInit`                                                                                                                                           | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `partial`    | `true \| { from?: string; rewriteTarget?: string; segments?: string[]; prefetch?: boolean; fill?: boolean; interceptSource?: string; stale?: boolean }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none). `prefetch: true` sends it as a `<Link>` prefetch (`X-Rango-Prefetch`), so `prefetch: false` work is deferred. `fill: true` sends the follow-up request (`_rsc_fill=1`) the browser makes after adopting a prefetch; pass the prefetch's delivered ids, without the deferred ones, as `segments`, and the same URL as `from`. `interceptSource` sends the intercept source (`X-RSC-Router-Intercept-Source`) the browser sends with the fill of an intercept, whose `from` is that source too. `rewriteTarget` sends what the page at `from` carried as its payload's `metadata.rewriteTarget` when middleware rewrote it (`_rsc_rt`), as the browser does, so the server diffs against the route that rendered that page. `stale: true` sends a stale request (`_rsc_stale`), as the browser sends it: every `revalidate()` sees `stale: true` (see `revalidate()`'s `stale`), segments take an action's revalidation defaults, and it renders live, as an action does: neither the route cache (`cache()`) nor the document cache serves or stores it, and a `ppr` route's `replayStatus` is `{ outcome: "BYPASS", reason: "stale" }`. |
-| `action`     | `{ ref: Function; id: string; args?: unknown[]; segments?: string[]; rewriteTarget?: string }`                                                          | Send the request a JS server action call makes from the page at `url`: a POST of `args` (encoded as the browser encodes them) with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments` (the page's mounted segment ids, default none), plus the page's `rewriteTarget` as for `partial`. Registers `ref` under `id` (`<module id>#<export name>`). Not with `partial` or `form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Field        | Type                                                                                                                                                                       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cacheStore` | `SegmentCacheStore`                                                                                                                                                        | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `env`        | `TEnv`                                                                                                                                                                     | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `headers`    | `HeadersInit`                                                                                                                                                              | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `partial`    | `true \| { from?: string; rewriteTarget?: string; segments?: string[]; prefetch?: boolean; fill?: boolean; interceptSource?: string; stale?: boolean; boundary?: string }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none). `prefetch: true` sends it as a `<Link>` prefetch (`X-Rango-Prefetch`), so `prefetch: false` work is deferred. `fill: true` sends the follow-up request (`_rsc_fill=1`) the browser makes after adopting a prefetch; pass the prefetch's delivered ids, without the deferred ones, as `segments`, and the same URL as `from`. `interceptSource` sends the intercept source (`X-RSC-Router-Intercept-Source`) the browser sends with the fill of an intercept, whose `from` is that source too. `rewriteTarget` sends what the page at `from` carried as its payload's `metadata.rewriteTarget` when middleware rewrote it (`_rsc_rt`), as the browser does, so the server diffs against the route that rendered that page. `stale: true` sends a stale request (`_rsc_stale`), as the browser sends it: every `revalidate()` sees `stale: true` (see `revalidate()`'s `stale`), segments take an action's revalidation defaults, and it renders live, as an action does: neither the route cache (`cache()`) nor the document cache serves or stores it, and a `ppr` route's `replayStatus` is `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error segment of a thrown action's boundary the page at `from` shows (`_rsc_boundary`), as the background revalidation an earlier action owes that page sends it, with `stale: true` and no `segments`: the response renders every segment above the boundary and nothing at or below it, claims the boundary in `matched` and sends no segment for it. The server reads it only beside `stale`. |
+| `action`     | `{ ref: Function; id: string; args?: unknown[]; segments?: string[]; rewriteTarget?: string }`                                                                             | Send the request a JS server action call makes from the page at `url`: a POST of `args` (encoded as the browser encodes them) with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments` (the page's mounted segment ids, default none), plus the page's `rewriteTarget` as for `partial`. Registers `ref` under `id` (`<module id>#<export name>`). Not with `partial` or `form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 ### Returns — `ServeShellRequestResult`
 

package/skills/use-cache/SKILL.md

@@ -68,10 +68,17 @@ export async function ProductCard({ id }: { id: string }) {
 A result Flight cannot encode cleanly is not cached: an async child component
 that throws, a promise in the result or in a handle push that rejects, a
 function or a class instance. Storing it would bake the failure into every hit
-until expiry. Instead the write is skipped and reported to `onError` (phase
-`"cache"`, category `cache-write`, or `stale-revalidation` for a background
-refresh): a miss still returns the live result, the next call runs the
-function again, and a stale entry keeps serving.
+until expiry. Instead the write is skipped, logged and reported to `onError`
+(phase `"cache"`, category `cache-write`, or `stale-revalidation` for a
+background refresh): the next call runs the function again, and a stale entry
+keeps serving.
+
+A miss renders a decoded copy of what it encodes, as a hit renders the stored
+entry, so a child that throws or a promise that rejects throws where the copy
+renders, as it would on a hit. A value Flight cannot encode at all (a
+function, a class instance) in the data the function returns is the
+exception: the call returns the live value, uncached. One inside a promise in
+that data rejects that promise instead, as it would on a hit.
 
 ## Named Cache Profiles
 
@@ -233,6 +240,35 @@ export const ProductLoader = createLoader(async (ctx) => getProduct(ctx));
 per-request values (cookies, headers) are not reflected in the cache key. Without
 this guard, one user's data would be served to another.
 
+That includes the server components the function returns. The value is
+encoded once, inside the same guard, and the page renders the decoded copy, as
+on a hit, so the guard refuses there every read and write it refuses in the
+body, and a refused read fails the request as it would in the body: at the
+value's root the call throws, and below the root that part renders as an
+error, to its nearest error boundary. Nothing is stored. The same holds for a
+`ctx.use(Loader)` in the returned tree (the loader runs inside the guard, and
+the request's memo of it rejects, so a later read of it in the request throws
+too) and for a `React.lazy` or a memoizing thenable created in the body.
+
+A handle value the function pushes (`ctx.use(Handle)`) is encoded inside the
+guard as well, and one that reads the request is not stored. One handle case
+is not covered yet: a handle value that holds a lazy component or a memoized
+promise. Don't push lazy state that reads the request from a cached function.
+
+Two memo gaps remain, where the read happened before the guard could see it:
+
+- In the body: a `React.cache`-memoized read of `cookies()` or `headers()` (a
+  `getSession = cache(() => cookies()...)` auth helper) that the page called
+  before the cached function runs returns the memo without reading again, so
+  the guard never sees it and the entry stores that visitor's value.
+- In the body or the returned tree: a per-request memo of your own, keyed by
+  `getRequestContext()`, that the page filled and the cached function or a
+  component it returns reads. `React.cache` itself is safe in the returned
+  tree, which renders in its own Flight request.
+
+Pass the value in as an argument instead of reading a memo inside the cached
+function or the tree it returns.
+
 The raw reads throw the same way: `ctx.request.headers` on any `ctx` passed in
 (handler, loader, middleware; it is one `Request` object, also
 `getRequestContext().request`), and `getRequestContext().cookie()` /
@@ -397,9 +433,11 @@ export const Page = Prerender(
 
 ## Performance: waitUntil
 
-On cache miss, the function executes and the result is serialized inline (blocking).
-The cache **store write** (`setItem`) is deferred to `waitUntil` and does NOT block
-the response.
+On cache miss, the function executes and its result is encoded; the call
+returns once the decoded copy's root has arrived, so a server component at the
+root of the value renders before the call resolves. The rest of the encode and
+the cache **store write** (`setItem`) are deferred to `waitUntil` and do NOT
+block the response.
 
 On stale hit, stale data is returned immediately. Background revalidation
 (re-execute + store write) runs entirely inside `waitUntil`.
@@ -407,7 +445,7 @@ On stale hit, stale data is returned immediately. Background revalidation
 | Phase                                | Blocks response? |
 | ------------------------------------ | ---------------- |
 | Function execution (miss)            | Yes              |
-| Result serialization (miss)          | Yes              |
+| Result encode, to its root (miss)    | Yes              |
 | Cache store write (miss)             | No (waitUntil)   |
 | Stale value return (stale hit)       | No (immediate)   |
 | Background revalidation (stale)      | No (waitUntil)   |

package/skills/view-transitions/SKILL.md

@@ -154,7 +154,7 @@ Every commit the router runs in a transition adds its `transition({ when })` kin
 - Tagging alone animates nothing: React starts a view transition only where a `<ViewTransition>` resolves a class other than `"none"` for the commit's types.
 - A commit outside a transition carries no type: a cold click that mounts new segments, a gated-off commit (`when` returned `false`), and a back/forward restored from the history cache on a route without `transition()` (it commits inside the `popstate` event). Under `transition()` that restore carries `"pop"` and `"navigation-back"`.
 - Under `transition()`, a stale entry's revalidation carries `"revalidate"` and `"action"`. An `action`-keyed map that must skip it also keys `revalidate: "none"` (`"none"` wins over any other match).
-- The types reach the commit that brings the page. React keeps one queue of transition types per root, and the first transition commit takes the whole queue. No router hook update takes them first: `useHandle()` and `useSegments()` commit with the page, and a `useNavigation()` value that moves while neither the state nor the URL does (`pendingUrl` as the response starts streaming, `isStreaming` as it ends) commits with the page while the reader has a held value, urgently otherwise, so it starts no view transition of its own. A transition your own code starts while React holds a navigation's page can still take them. Handle values on a held page land in the commit right after the page, by design; see [hooks](../hooks/handle-and-actions.md#when-handle-values-change-by-design). Use a kind map to choose an animation, never for correctness.
+- The types reach the commit that brings the page. React keeps one queue of transition types per root, and the first transition commit takes the whole queue. No router hook update takes them first: `useSegments()` commits with the page and `useHandle()` right after it, and a `useNavigation()` value that moves while neither the state nor the URL does (`pendingUrl` as the response starts streaming, `isStreaming` as it ends) commits with the page while the reader has a held value, urgently otherwise, so it starts no view transition of its own. `useAction()` values commit urgently. `useLinkStatus()` commits `pending` urgently and its end with the page, and a newer navigation or an abort ends it urgently, outside a held commit; neither starts a transition. A transition your own code starts while React holds a navigation's page can still take them. Handle values on a held page land in the commit right after the page, by design; see [hooks](../hooks/handle-and-actions.md#when-handle-values-change-by-design). Use a kind map to choose an animation, never for correctness.
 
 ### Back and Forward
 

package/src/__internal.ts

@@ -85,10 +85,16 @@ export type {
  */
 export type {
   RouterContext,
-  RevalidationContext,
   InterceptResult,
 } from "./router/router-context.js";
 
+/**
+ * @internal
+ * The request side of a revalidating resolution pass (RouterContext's
+ * revalidating resolvers take it).
+ */
+export type { ResolutionPassInput } from "./router/segment-resolution/resolution-pass.js";
+
 /**
  * @internal
  * Route match context during pipeline processing.

package/src/browser/action-fence.ts

@@ -20,7 +20,8 @@
  *
  * The drop runs the batch's follow-up: when an action of the batch did not
  * land on the page on screen, the action bridge refetches that page once,
- * whole, after the navigation the user started, unless an intercept is on
+ * whole (or whole above an action's error boundary on screen, which it
+ * holds), after the navigation the user started, unless an intercept is on
  * screen (server-action-bridge.ts followUp; the rules are R1-R7 in
  * docs/internal/execution-model.md).
  *

package/src/browser/connection-warmup.ts

@@ -17,6 +17,8 @@
  * state regardless of listener ordering.
  */
 
+import { WIRE } from "../wire-params.js";
+
 const IDLE_TIMEOUT = 60_000;
 const DEBOUNCE_DELAY = 150;
 
@@ -61,7 +63,7 @@ export function startConnectionWarmup(
 
   function sendWarmup() {
     coldLatch = false;
-    env.fetch("/?_rsc_warmup", { method: "HEAD" }).catch(() => {});
+    env.fetch(`/?${WIRE.warmup}`, { method: "HEAD" }).catch(() => {});
   }
 
   function triggerWarmup() {