@rangojs/router 0.26.6 → 0.28.0

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

@@ -87,10 +87,12 @@ are immune to partial-revalidation staleness by construction.
    the entry's children too — a hard `false` on one side of a
    producer/consumer pair desyncs it.
 4. **Cross-entry sharing** — an outer `layout()` entry feeding descendants.
-   Outer entries do NOT revalidate on actions by default (the revalidation
-   trace calls this `action:parent-chain-skip`), so this rung always requires
-   a shared revalidation contract: the same named `revalidate()` function on
-   the producer and every consumer. See `/layout` → "Revalidation Contracts".
+   Outer entries do NOT revalidate on actions, or on Back/Forward onto a page
+   an action made stale, by default (the revalidation trace calls this
+   `action:parent-chain-skip` / `stale:parent-chain-skip`), so this rung always
+   requires a shared revalidation contract: the same named `revalidate()`
+   function on the producer and every consumer, returning `true` on `stale`
+   as well as on its actions. See `/layout` → "Revalidation Contracts".
    Before writing one, check whether the producer can move down a rung.
 
 The failure mode this ladder prevents: a consumer re-runs, its producer
@@ -247,9 +249,15 @@ 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).
+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
+false on it).
 `actionId`, `actionUrl`, `actionResult`, and `formData` are `undefined` on plain
 navigation; `method` is `"GET"` there and `"POST"` for an action. Call
 `ctx.isAction()` with no arguments to ask "was this any action?".
@@ -258,9 +266,10 @@ navigation; `method` is `"GET"` there and `"POST"` for an action. Call
 default already does: after an action, loaders, the route, and segments inside
 the `path()` re-run; layouts and parallels above the route are skipped.
 
-- **Add a signal** where the default skips: `ctx.isAction(CartActions) || undefined`
-  on a parent layout re-renders it after cart actions and defers otherwise. On a
-  loader or route segment it changes nothing.
+- **Add a signal** where the default skips:
+  `ctx.isAction(CartActions) || ctx.stale || undefined` on a parent layout
+  re-renders it after cart actions and on Back after an action, and defers
+  otherwise. On a loader or route segment it changes nothing.
 - **Narrow after actions** where the default re-runs:
   `ctx.isAction() ? ctx.isAction(CartActions) : undefined` re-runs only for cart
   actions and keeps the navigation default (params or search changed).
@@ -270,8 +279,11 @@ the `path()` re-run; layouts and parallels above the route are skipped.
 
 ```ts
 // on a parent layout (skipped after actions by default): also re-render when
-// checkout succeeded; defer to the default otherwise
-revalidate((ctx) => (ctx.isAction(checkout) && ctx.actionResult?.ok) || undefined),
+// checkout succeeded, and on Back after an action; defer to the default otherwise
+revalidate(
+  (ctx) =>
+    (ctx.isAction(checkout) && ctx.actionResult?.ok) || ctx.stale || undefined,
+),
 ```
 
 The same `actionResult` idiom works in a `clientUrls()` group's loader

package/skills/server-actions/SKILL.md

@@ -428,8 +428,9 @@ several actions, or a namespace import (`import * as CartActions`). Wrap it by
 what the segment's default already does:
 
 - **Add a signal** where the default skips (a parent layout or layout-level
-  parallel): `ctx.isAction(CartActions) || undefined` re-renders it after cart
-  actions and defers otherwise. On a loader or route segment it changes nothing.
+  parallel): `ctx.isAction(CartActions) || ctx.stale || undefined` re-renders it
+  after cart actions and on Back after an action, and defers otherwise. On a
+  loader or route segment it changes nothing.
 - **Narrow after actions** where the default re-runs (loaders, the route, and
   segments inside the `path()`):
   `ctx.isAction() ? ctx.isAction(CartActions) : undefined` re-runs only for cart
@@ -508,8 +509,10 @@ consumer:
 import type { Revalidate } from "@rangojs/router";
 import * as CartActions from "./actions/cart";
 
+// True on a stale Back/Forward too: it re-runs CartPage, and a producer that
+// sits it out leaves the page reading undefined.
 const revalidateCart: Revalidate = (ctx) =>
-  ctx.isAction(CartActions) || undefined;
+  ctx.stale || ctx.isAction(CartActions) || undefined;
 
 urls(({ path, layout, loader, revalidate }) => [
   layout(CartLayout, () => [
@@ -534,6 +537,41 @@ revalidates), flushes the prefetch cache, rotates the router's state cookie,
 and tells other open tabs to do the same. This happens for every action that
 reached the server, including ones that threw. No setup is needed.
 
+### When the user navigates while the action runs
+
+Users rarely wait for an action. They click "Add to cart" and then a link, or
+go Back. That navigation is an ordinary one: a prefetched link shows its page at
+once, as it would with no action in flight. That page may show data from before
+the write, such as a layout's cart count the navigation kept. So once the last
+action in flight settles, the router revalidates the page on screen once, in
+the background: every loader on it re-runs, and the result commits with no
+`loading()` fallback and no remount. `useNavigation().state` stays `"idle"`. This covers an action that failed too.
+
+```text
+/product/1: click "Add to cart", then a link to /checkout
+  /checkout shows at once        (layout: cart:0)
+  the action settles
+  one background revalidation    (layout: cart:1)
+```
+
+A few details:
+
+- If the user stays on the page, nothing extra is sent. The action's own
+  response already re-ran that page's loaders.
+- The revalidation waits for a navigation the user started and never cancels
+  it. Several actions in flight share one revalidation.
+- A `redirect()` from the action replaces it: the redirect target renders
+  fresh.
+- If an `intercept()` is on screen, nothing runs. Leaving the intercept with
+  Back restores the page underneath and revalidates it as stale (the
+  action marked the history cache stale). Only loaders that opt in with
+  `revalidate(({ stale }) => stale)` re-run there; the others keep their data
+  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.
+- 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.
+
 ### `keepClientCache()` — skip it for no-op actions
 
 Some hot actions change nothing a route renders: a debounced draft autosave, an
@@ -555,8 +593,8 @@ export async function saveDraft(formData: FormData) {
 
 What it suppresses, for this action only: the stale-marking of the history
 cache, the prefetch flush, the state-cookie rotation, the cross-tab broadcast,
-and the background re-fetch the client runs when the user navigated away while
-the action was in flight. What it does not change:
+and the background revalidation the client runs when the user navigated while
+the action was in flight (above). What it does not change:
 
 - The action's own response still carries the revalidation render your
   `revalidate()` rules select, and the client applies it.
@@ -666,7 +704,14 @@ 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. An action sent from an intercept
+gets the boundary alone.
 
 ```typescript
 // urls.tsx — inside the urls() callback

package/skills/testing/predicates.md

@@ -80,7 +80,7 @@ Defaults model a same-URL navigation with no action, for a route-owned loader: a
 | `method`         | `string`                                                        | Overrides the request method (`POST` with an `action`, otherwise `GET`).                                                                                                                                                    |
 | `segmentType`    | `"layout" \| "route" \| "parallel" \| "loader"`                 | The segment type the predicate is attached to. Defaults to `"loader"`.                                                                                                                                                      |
 | `belongsToRoute` | `boolean`                                                       | Defaults to `true`; `false` models a layout's loader, which a navigation keeps by default.                                                                                                                                  |
-| `stale`          | `boolean`                                                       | The `stale` arg (a history-entry background revalidation). Defaults to `false`.                                                                                                                                             |
+| `stale`          | `boolean`                                                       | The `stale` arg (a history-entry background revalidation), which takes an action's defaults. Defaults to `false`.                                                                                                           |
 | `routeName`      | `string`                                                        | `toRouteName` (and `routeName`).                                                                                                                                                                                            |
 | `fromRouteName`  | `string`                                                        | `fromRouteName`.                                                                                                                                                                                                            |
 | `env`            | `TEnv`                                                          | Environment bindings of the seeded context.                                                                                                                                                                                 |

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 }` | 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. |
-| `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 }` | 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 
 ### 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/ux-architecture/SKILL.md

@@ -228,8 +228,9 @@ them right:
 
 - A boolean is a hard answer, `undefined` defers to the default. Pick by the
   default you are changing: the ternary narrows a loader that re-runs after
-  every action; `isAction(X) || undefined` adds a re-run where the default
-  skips (a server layout's own handler).
+  every action; `isAction(X) || stale || undefined` adds a re-run, after `X`
+  and on Back after an action, where the default skips (a server layout's own
+  handler).
 - `revalidate(true)` and `revalidate(false)` are shorthands for `() => true`
   and `() => false`.
 - Never `revalidate(false)` on data keyed by a param: product to product then

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-coordinator.ts

@@ -6,11 +6,7 @@ import type { ActionEntry } from "./event-controller.js";
  * reconciliation; this only covers successfully-reconciled partial responses.
  */
 type ActionScenario =
-  | {
-      type: "navigated-away";
-      historyKeyChanged: boolean;
-      onInterceptRoute: boolean;
-    }
+  | { type: "navigated-away" }
   | { type: "hmr-missing" }
   | { type: "consolidation-needed"; segmentIds: string[] }
   | { type: "concurrent-skip"; otherFetchingCount: number }
@@ -41,8 +37,6 @@ export interface ActionOutcomeInput {
   reconciledSegmentCount: number;
   /** Number of matched segment IDs from server */
   matchedCount: number;
-  /** Current intercept source URL (null when not on intercept route) */
-  currentInterceptSource: string | null;
 }
 
 // Segment IDs to re-fetch when concurrent actions each revalidated different
@@ -85,12 +79,7 @@ export function classifyActionOutcome(
     input.currentPathname !== input.actionStartPathname ||
     input.currentLocationKey !== input.actionStartLocationKey
   ) {
-    return {
-      type: "navigated-away",
-      historyKeyChanged:
-        input.currentLocationKey !== input.actionStartLocationKey,
-      onInterceptRoute: input.currentInterceptSource !== null,
-    };
+    return { type: "navigated-away" };
   }
 
   if (input.reconciledSegmentCount < input.matchedCount) {

package/src/browser/action-fence.ts

@@ -6,9 +6,11 @@
  * start. While the fence is up, the decision of whether the action invalidated
  * anything is deferred to the response:
  *
- * - prefetch consumption is suspended (a queued prefetch result is not served),
- * - a genuine navigation during the flight fetches with `cache: "no-store"` so
- *   it cannot be served stale bytes from the browser's Vary-keyed HTTP cache,
+ * - a navigation during the flight is an ordinary one: a prefetch is served,
+ *   and the page it commits may hold pre-write data until the follow-up below,
+ * - a navigation without a prefetch, and a prefetch, fetch with
+ *   `cache: "no-store"` so they cannot be served stale bytes from the
+ *   browser's Vary-keyed HTTP cache,
  * - popstate reads are treated as stale-while-revalidate.
  *
  * Nothing is wiped, rotated, or broadcast while the fence is up — that is what
@@ -16,6 +18,12 @@
  * actions compose: each action raises and lowers its own reference, and the
  * fence is down only when the count reaches zero.
  *
+ * 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
+ * screen (server-action-bridge.ts followUp; the rules are R1-R7 in
+ * docs/internal/execution-model.md).
+ *
  * The refcount is a single module-level counter, not keyed by routerId.
  * Consumers (navigation-client.ts, prefetch/fetch.ts, navigation-bridge.ts)
  * read it unscoped, so an action in one router would suppress another router's

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() {