@rangojs/router 0.27.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/cache-guide/SKILL.md

@@ -320,11 +320,14 @@ domains, and the router id keeps two routers on one store apart when both
 serve the same host and path (see `/host-router`, "Shared cache store"); the search part is sorted, excludes the router's internal params, and
 honors `createRouter({ cache: { searchParams } })`.
 
-A custom `key` function replaces the whole default key (e.g., to key by user role
-or locale); it also bypasses the store's `keyGenerator` and the search-param
-filter. It runs once per request and may read `cookies()`. Its result is
-stored namespaced (`key:` plus its URI encoding), so no value it returns, raw
-request input included, names another route's record. A nested `cache()`
+A custom `key` function replaces the URL part of the default key (e.g., to
+key by user role or locale), not the request type: document loads, client
+navigations and intercept navigations still keep their own records, and the
+key decides which requests of one type share a record. It also bypasses the
+store's `keyGenerator` and the search-param filter. It runs once per request
+and may read `cookies()`. Its result is stored namespaced (`key:` plus its URI
+encoding, then the request type), so no value it returns, raw request input
+included, names another route's record. A nested `cache()`
 keys its records within the enclosing `key()` partition (`/caching` → "Keys
 nest"). Normalize the result to the values you serve: each distinct value is
 a record. On a `ppr` route, `key()` (and a store `keyGenerator` that returns

package/skills/caching/SKILL.md

@@ -102,7 +102,9 @@ tainted objects" below).
 
 Handle pushes follow the same split. Handler pushes (`ctx.use(Meta)`,
 `ctx.use(Breadcrumbs)`, custom handles) are stored with the segments and
-replayed on a hit. Pushes from a `loader()` body are not stored: the loader
+replayed on a hit. On a navigation the hit replays them only for the segments
+it sends: a layout the browser keeps keeps its values on screen, as on an
+uncached navigation. Pushes from a `loader()` body are not stored: the loader
 re-runs on the hit and pushes again, so each value appears once. A loader that
 runs only because a cached handler awaited it with `ctx.use(Loader)` does not
 re-run on a hit, so its pushes are stored with the handler's.
@@ -154,7 +156,7 @@ cache(
     swr: 300, // seconds a stale entry is served while it refreshes.
     //           Default: store.defaults.swr, else no SWR window
     tags: ["blog"], // or (ctx) => string[]; see "Tag-Based Invalidation"
-    key: (ctx) => `blog:${ctx.pathname}`, // replaces the default key entirely
+    key: (ctx) => `blog:${ctx.pathname}`, // replaces the URL part of the default key
     condition: (ctx) => !ctx.request.headers.has("x-preview"), // false = bypass
     store: blogStore, // per-boundary store; see "Custom Cache Store"
   },
@@ -164,15 +166,26 @@ cache(
 );
 ```
 
-- **Default key**: `{doc|partial|intercept}:{routerId}@{host}{pathname}[:params][?search]`
-  — document requests, client navigations, and intercept navigations are cached
-  separately, and so are two routers that share a store (see `/host-router`,
-  "Shared cache store"). The search part honors `cache.searchParams` (below).
-- **`key`** is a full override: it bypasses the default key, the store's
-  `keyGenerator`, and the search-param filter. The result is stored
-  namespaced (`key:` plus its URI encoding), so whatever it returns, request
-  input included, never names another route's default-keyed record or a
-  nested partition's. A nested `cache()` keys its records within that
+- **Default key**: `{doc|partial|intercept:<intercept>}:{routerId}@{host}{pathname}[:params][?search]`
+  — under this key, document requests, client navigations, and intercept
+  navigations are cached separately, each intercept that targets the route
+  apart (`<intercept>` names the one the navigation selected), and so are two
+  routers that share a store (see `/host-router`, "Shared cache store"). The
+  search part honors `cache.searchParams` (below).
+- **`key`** replaces the URL part of the default key (host, path, params,
+  search): it bypasses those, the store's `keyGenerator`, and the
+  search-param filter. The request kind stays: document requests, client
+  navigations and each intercept navigation keep their own record under one
+  `key()` result, so `key()` decides which requests of one kind share a
+  record (a `key()` that ignores `:id` shares one document record across
+  ids), never that a document request reads a navigation's record (which
+  keeps the fallback of a `loading(..., { ssr: false })` that a document
+  leaves out) or an intercept's. The
+  result is stored namespaced (`key:` plus its URI encoding, then the kind:
+  `tier:gold` is `key:tier%3Agold|doc` for a document request and
+  `key:tier%3Agold|partial` for a navigation), so whatever it returns,
+  request input included, never names another route's default-keyed record
+  or a nested partition's. A nested `cache()` keys its records within that
   partition (see "Keys nest" under "Nested Cache Boundaries"). On a `ppr`
   route the same key (or, without one, the store's `keyGenerator`)
   partitions the PPR shell: each partition captures and serves its own shell
@@ -532,7 +545,7 @@ const router = createRouter({
   baked-shell manifest gate (a URL whose only params are excluded ones now
   matches the prerendered shell), and `"use cache"` ctx key normalization.
 - **`cache({ key })` override wins**: a custom key bypasses the filter along
-  with the rest of default key generation.
+  with the rest of the default key's URL part.
 - **The footgun**: excluding a param promises the rendered output does not
   depend on it. If it does, the first variant is cached and served to everyone.
   That is why the default is `"all"`.
@@ -725,7 +738,9 @@ default, shared by every router on the host with that prefix; `HttpOnly`,
 `SameSite=Lax`, `Path=/`, `Secure` on https, `Max-Age` 11 s with KV and 3 s
 without at the defaults: the longest memo staleness plus 1 s). It is strictly
 functional: its value is `1`, it identifies no one, and it only sends that
-browser's reads past the memos. The same user's requests that carry it skip
+browser's reads past the memos. A stale entry's background refresh (`cache()`,
+`"use cache"`, a cached loader, the document cache) sets none: no visitor made
+that invalidation. The same user's requests that carry it skip
 both memos on every isolate, so a mutating user never sees a memoized shell or
 marker from before their write. What they read past the memos is the store's
 own consistency. `VercelCacheStore`: `expireTag` is global (about 300 ms), so
@@ -1084,7 +1099,8 @@ cache({ ttl: 300, key: (ctx) => `tier:${tier(ctx)}` }, () => [
       path("/faq", FaqPage, { name: "faq" }),
     ]),
 
-    // Its own key() composes with the outer one ("key:tier%3Agold|key:v%3Ab")
+    // Its own key() composes with the outer one, then the request kind
+    // ("key:tier%3Agold|key:v%3Ab|doc")
     cache(
       { ttl: 60, key: (ctx) => `v:${ctx.searchParams.get("v") ?? "a"}` },
       () => [path("/plans", PlansPage, { name: "plans" })],
@@ -1099,10 +1115,10 @@ results first, outermost first:
 
 | Boundary the route sits in                    | Record key                                                                                                                                                   |
 | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| a single keyed `cache()`                      | Its `key()` result, namespaced (`tier:gold` is stored as `key:tier%3Agold`)                                                                                  |
+| a single keyed `cache()`                      | Its `key()` result, namespaced, then the request kind (`tier:gold` is stored as `key:tier%3Agold\|doc` for a document request)                               |
 | `cache({ ttl })`, no `key`, under a keyed one | The chain's `key()` results, then this boundary's default key (its store's `keyGenerator` result, else the default key), encoded                             |
-| `cache({ key })` under a keyed one            | The chain's `key()` results                                                                                                                                  |
-| deeper nesting                                | Composes the same way; only the innermost boundary's missing `key` adds its default key                                                                      |
+| `cache({ key })` under a keyed one            | The chain's `key()` results, then the request kind                                                                                                           |
+| deeper nesting                                | Composes the same way; the innermost boundary adds its default key without a `key` of its own, its request kind with one                                     |
 | under a `cache({ store })` on another store   | Also that store's `keyGenerator` result, one part per store: empty for a store that returns the default key while another's differs, none when all return it |
 | `cache(false)`                                | No caching, as before; a `cache()` re-enabled below it stays in the partition                                                                                |
 | no `key` anywhere                             | The default key, or the store's `keyGenerator` result, as before                                                                                             |
@@ -1134,7 +1150,10 @@ results first, outermost first:
   empty result there fails key resolution, so the request renders uncached,
   and the router warns once naming the store. On the same store the inner
   boundary's own default key already carries it (or its own `key()`
-  overrides it).
+  overrides it). Keep the default key in the result
+  (`` `${locale}:${defaultKey}` ``): its prefix is the request kind, and a
+  result without it gives a document request, a navigation and each
+  intercept navigation one record.
 - A response route's entry (`path.json()` and the other response routes) is
   keyed the same way, behind a `response:` prefix. A `ppr` route's shell is
   partitioned by the chain's `key()` results, namespaced the same way, since

package/skills/document-cache/SKILL.md

@@ -161,6 +161,16 @@ short-circuits the middleware's downstream pipeline; global middleware that
 wraps it can still run. Route middleware, handlers, and loaders below it do not.
 An external CDN hit is different: the function never runs at all.
 
+The background revalidation re-runs that downstream pipeline for the stale
+entry. Its cookies, and the headers its route handlers and the middleware
+after the cache write, go on its own response, never on the visitor's `STALE`
+response; middleware ahead of the cache gets the `STALE` response from
+`next()`, and its writes after `next()` land there. It
+starts from what middleware ahead of the cache wrote to the response before
+`next()`, as a `MISS` does, and its response is stored by the rules below:
+its headers are kept, and a cookie it sets keeps the refreshed page out of the
+cache.
+
 ## Cache Status Header
 
 Response includes `x-document-cache-status`:
@@ -215,7 +225,9 @@ suffixes are still appended.
   everyone). That includes a response whose request called
   `updateTag()`/`revalidateTag()` on a store that keeps per-isolate memos
   (`CFCacheStore`, `VercelCacheStore`): it carries the fresh-reads cookie
-  (`rango-state-fresh` by default), so it is not stored.
+  (`rango-state-fresh` by default), so it is not stored. A stale entry's
+  background re-run sets no fresh-reads cookie (no visitor made that
+  invalidation), so its invalidation does not keep the refreshed page out.
 - Non-200 responses
 - A 200 whose render reported an error: a component that threw after the
   response started streaming, such as an async server component whose fetch

package/skills/handler-use/SKILL.md

@@ -368,7 +368,7 @@ Per-slot merge order is **handler.use → shared use → slot-local use**. Slot-
 
 Other things to keep in mind about `loading()`:
 
-- Any `loading()` (regardless of source) makes the segment a streaming unit. A handler that includes `loading()` in its `.use` opts every mount site into streaming by default. To opt back out, pass `loading(false)` at the mount site (`loading === false` handling in [segment-resolution/fresh.ts](../../src/router/segment-resolution/fresh.ts)) — use the slot descriptor form for parallel slots so the opt-out doesn't broadcast.
+- Any `loading()` (regardless of source) makes the segment a streaming unit. A handler that includes `loading()` in its `.use` opts every mount site into streaming by default. To opt back out, pass `loading(false)` at the mount site (`loading === false` handling in [segment-resolution/revalidation.ts](../../src/router/segment-resolution/revalidation.ts)) — use the slot descriptor form for parallel slots so the opt-out doesn't broadcast.
 
 Rule of thumb: only put `loading()` in `handler.use` if you genuinely want every mount site to stream by default. Use the slot descriptor's `use` for any per-slot intent at a `parallel()` call.
 

package/skills/intercept/SKILL.md

@@ -370,9 +370,14 @@ below), and `cache()` onto the target route.
 
 To cache a modal, put `cache()` on the target route (or a layout above it).
 An intercept navigation is cached under that scope with its own `intercept:`
-key, so it never collides with the full-page render of the same URL. For
-finer control, use `"use cache"` in the intercept handler, or cache the
-intercept's loader: `loader(ProductLoader, () => [cache()])`.
+key, so it never collides with the full-page render of the same URL. The key
+names the intercept the navigation selected, so two intercepts that target one
+route with different `when()` conditions each keep their own record. Both
+hold under a `cache({ key })` too: the `key()` replaces the URL part of the
+key, never the request kind, so a document request and a plain navigation
+never read an intercept's record (see `/caching`). For finer control, use
+`"use cache"` in the intercept handler, or cache the intercept's loader:
+`loader(ProductLoader, () => [cache()])`.
 
 ## Errors in an Intercept
 
@@ -463,7 +468,9 @@ contract and direction-aware examples.
 ## Interaction with Prerender
 
 When the target route of an intercept uses `Prerender`, the intercept handler is
-also resolved at build time and stored alongside the main pre-rendered segments.
+also resolved at build time and stored in an intercept variant next to the
+route's own pre-rendered page. The variant holds what an intercept navigation
+renders: the layouts above the route and the intercept, not the route's page.
 This means intercept navigations to pre-rendered routes are served from the
 prerender store without executing handler code at runtime.
 
@@ -496,13 +503,16 @@ Build-time behavior:
 - The intercept handler (`<ProductModal />`) is resolved with BuildContext
 - Result is stored under the key `"detail/paramHash/i"` (intercept variant)
 - `when` config conditions are skipped at build time (all intercepts pre-rendered unconditionally)
-- `when` is still evaluated at runtime by the intercept-resolution middleware
+- `when` is still evaluated at runtime by the intercept-resolution middleware,
+  and a navigation shows only the intercept it selected
+- Two intercepts on one layout that fill the same slot are not pre-rendered:
+  they render live
 
 Runtime behavior:
 
-- Intercept navigation: prerender store serves the `/i` variant (frozen handler + fresh loaders)
+- Intercept navigation: prerender store serves the `/i` variant (frozen handler + fresh loaders). A layout the client holds (`ShopLayout`) stays as it is on screen, as on a live intercept, unless its `revalidate()` asks for it
 - Direct navigation: prerender store serves the main variant (full page)
-- If no intercept prerender entry exists, falls through to live intercept resolution
+- If no intercept prerender entry exists, or it lacks the selected intercept, falls through to live intercept resolution
 
 Loaders inside the intercept always run fresh at request time, same as regular
 pre-rendered routes.

package/skills/middleware/SKILL.md

@@ -319,6 +319,24 @@ export const timing: Middleware = async (ctx, next) => {
 };
 ```
 
+A middleware may answer without waiting for its `next()`, as a timeout
+fallback does. The middleware ahead then see its `Response` after `next()`
+and write on it. The abandoned render keeps running and builds its own
+response, which nothing serves.
+
+```typescript
+export const renderTimeout: Middleware = (ctx, next) =>
+  Promise.race([
+    next(),
+    new Promise<Response>((resolve) =>
+      setTimeout(
+        () => resolve(new Response("Try again", { status: 503 })),
+        2000,
+      ),
+    ),
+  ]);
+```
+
 ### Typed context variables in middleware
 
 Use `createVar<T>()` for type-safe data sharing between middleware and handlers:

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

@@ -704,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/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/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/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/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() {

package/src/browser/event-controller.ts

@@ -258,7 +258,8 @@ export interface EventController {
     /** Originating history entry key; scopes location-state arbitration. */
     cohort?: string,
   ): ActionHandle;
-  abortAllActions(): void;
+  /** Abort every action in flight except `except` (an ActionHandle id). */
+  abortAllActions(except?: string): void;
 
   // State access
   getState(): DerivedNavigationState;
@@ -1108,13 +1109,14 @@ export function createEventController(
     };
   }
 
-  function abortAllActions() {
+  /** Abort every action in flight except `except` (an ActionHandle id). */
+  function abortAllActions(except?: string) {
     for (const [id, entry] of inflightActions) {
       // Preserve settling entries — they have already been handled by
       // fail()/complete() and will self-cleanup via the settlement timeout.
       // Clearing them here would prevent debounced notifications from
       // delivering the error/result state to subscribers.
-      if (entry.phase === "settling") continue;
+      if (entry.phase === "settling" || id === except) continue;
       entry.abort.abort();
       inflightActions.delete(id);
     }