@rangojs/router 0.26.6 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.26.6",
+  "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/client-urls/SKILL.md

@@ -326,7 +326,8 @@ Per request: a JS action POST runs the predicate with `method: "POST"`,
 `FormData` argument) and `actionUrl`; the default is true. An in-group
 navigation GET defaults to true when params or search changed. A prefetch
 partial runs the predicate, so a prefetched in-group navigation honours it. A
-stale back/forward revalidation sees `stale: true`. Document requests and
+stale back/forward revalidation sees `stale: true` and takes an action's
+defaults (the default is true). Document requests and
 no-JS form posts hold no segments, so every loader renders whatever a predicate
 says. On the action-triggered refetch GET (consolidation) `isAction()` is false,
 as for `urls()`. `currentParams`/`nextParams` are the server's route params,

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`:
@@ -202,6 +212,11 @@ suffixes are still appended.
 
 - Server actions (`_rsc_action`)
 - Loader requests (`_rsc_loader`)
+- Stale requests (`_rsc_stale`): the client marks stale the follow-up
+  revalidation after an action, a Back/Forward entry's revalidation, and any
+  request that holds no segments (`router.refresh()`, a cross-tab refresh).
+  Each renders at the origin and is not stored, because its data may predate
+  a write and the cache cannot tell.
 - Non-GET requests
 - Responses without an `s-maxage` `Cache-Control` directive
 - Responses whose `Cache-Control` also contains `private`, `no-store`, or an
@@ -210,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

@@ -64,11 +64,29 @@ export const urlpatterns = urls(({ path, layout, intercept, loader, loading }) =
 
 ## Navigation Behavior
 
-| Navigation Type                | What Renders                                         |
-| ------------------------------ | ---------------------------------------------------- |
-| Click link `/shop/product/abc` | `<ProductModal />` in `@modal`, background preserved |
-| Direct URL `/shop/product/abc` | Full `<ProductPage />` page                          |
-| Browser back                   | Close modal, restore previous state                  |
+| Navigation Type                                       | What Renders                                         |
+| ----------------------------------------------------- | ---------------------------------------------------- |
+| Click link `/shop/product/abc`                        | `<ProductModal />` in `@modal`, background preserved |
+| Direct URL `/shop/product/abc`, or a reload           | Full `<ProductPage />` page                          |
+| Back from the open intercept                          | The intercept closes; the source page stays          |
+| Back/Forward onto the intercept's entry               | The intercept over its source page                   |
+| The same, uncached, from a page other than the source | Full `<ProductPage />` page, as a document load      |
+
+Only a client navigation from the source page shows an intercept. Back/Forward
+restores an intercept's entry from the history cache (`initBrowserApp`'s
+`storeOptions.cacheSize`, 20 by default), or fetches it when its source page is
+on screen. From any other page (after a reload, or once the entry was evicted)
+it costs a full page load, from the top, which drops `clearOnReload` location
+state like any document load, and the entry is a full page from then on. In
+dev, an edit that changes the app version clears the history cache, so the
+next Back/Forward onto an intercept entry takes that path.
+
+A server action on `/shop` that calls `redirect("/shop/product/abc")` opens the
+intercept too, and so does a link from `/shop` to a route that redirects
+there. The page under it is the browser's copy, as on a link click: it
+keeps its last render, so it shows its pre-action data until the intercept
+closes. An action submitted from inside an open intercept leaves that page the
+same way.
 
 ## Intercept with Layout
 
@@ -146,6 +164,18 @@ the modal keeps the data of the others, as it does on a link to another
 intercepted route that reads the same loader. In `clientUrls()` the predicate
 runs on the server too (`/client-urls`).
 
+The page under an intercept does not re-render while the intercept is on
+screen. An action that settles after the intercept opened (one sent from the
+page underneath just before the user opened it) runs no background
+revalidation. The page underneath keeps its data until the user leaves the
+intercept. Leaving it with Back revalidates that page as stale (the
+action marked the history cache stale): loaders that opt in with
+`revalidate(({ stale }) => stale)` re-run. Going Back or Forward out of the
+intercept while an action from it is in flight does not abort the action:
+`useAction()` gets its result, and the page underneath gets the background
+revalidation (`/server-actions`, "When the user navigates while the action
+runs").
+
 A `revalidate()` placed directly in the intercept's `use()` (or returned from
 its handler's `.use`) throws at definition time. Attach it to the loader:
 
@@ -177,7 +207,7 @@ import type { Revalidate } from "@rangojs/router";
 import * as ProductActions from "./actions/product";
 
 export const revalidateProductShell: Revalidate = (ctx) =>
-  ctx.isAction(ProductActions) || undefined;
+  ctx.stale || ctx.isAction(ProductActions) || undefined;
 
 layout(ProductLayout, () => [
   revalidate(revalidateProductShell), // producer reruns
@@ -340,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
 
@@ -433,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.
 
@@ -466,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/layout/SKILL.md

@@ -238,7 +238,8 @@ A standalone `layout()` renders when it is first mounted and is then kept as-is:
   params auto-filled) keep the old params too; render param-dependent nav in a
   client component with `useReverse(routes)` (`/links`).
 - **Actions** skip it too (the revalidation trace calls this
-  `action:parent-chain-skip`).
+  `action:parent-chain-skip`), and so does Back/Forward onto a page an action
+  made stale (`stale:parent-chain-skip`).
 
 Orphan layouts inside a `path()` are the opposite: they belong to the route
 entry and re-render with it (on param/search changes and on every action).
@@ -249,9 +250,9 @@ or `undefined` to defer to the default:
 ```typescript
 import * as CartActions from "./actions/cart";
 
-// Re-render after any cart action
+// Re-render after any cart action, and on Back after an action
 layout(<CartLayout />, () => [
-  revalidate((ctx) => ctx.isAction(CartActions) || undefined),
+  revalidate((ctx) => ctx.isAction(CartActions) || ctx.stale || undefined),
 
   path("/cart", CartPage, { name: "cart" }),
 ])
@@ -292,7 +293,7 @@ import type { Revalidate } from "@rangojs/router";
 import { addToCart } from "./actions/cart";
 
 export const revalidateCartData: Revalidate = (ctx) =>
-  ctx.isAction(addToCart) || undefined;
+  ctx.stale || ctx.isAction(addToCart) || undefined;
 ```
 
 ```typescript
@@ -305,8 +306,11 @@ layout(<CartLayout />, () => [
 ```
 
 On the layout the contract adds the re-render the default skips after an
-action. The route segment already re-runs after every action, so there it
-changes nothing by default; the shared name documents the dependency.
+action, and on Back/Forward onto a page an action made stale (`ctx.stale`).
+The route segment already re-runs on both, so there it changes nothing by
+default; the shared name documents the dependency. Leave out `ctx.stale` and
+Back after any action re-runs the page without its layout: the page reads
+`undefined`.
 
 If a segment depends on multiple upstream domains, compose multiple
 contracts (`revalidateAuthData`, `revalidateCartData`, and so on).
@@ -319,7 +323,7 @@ import { revalidate, type Revalidate } from "@rangojs/router";
 import * as AuthActions from "./actions/auth";
 
 export const revalidateAuthData: Revalidate = (ctx) =>
-  ctx.isAction(AuthActions) || undefined;
+  ctx.stale || ctx.isAction(AuthActions) || undefined;
 export const revalidateAuth = () => [revalidate(revalidateAuthData)];
 ```
 

package/skills/loader/SKILL.md

@@ -396,12 +396,26 @@ Segment defaults when no revalidator decides (from
 `src/router/revalidation.ts`). A segment the client does not hold yet always
 renders.
 
-| Segment                                                              | After an action (POST) | Navigation                          |
-| -------------------------------------------------------------------- | ---------------------- | ----------------------------------- |
-| Route (`path()`)                                                     | `true`                 | `true` when params or search change |
-| Owned by the route (loaders, layouts, parallels inside the `path()`) | `true`                 | `true` when params or search change |
-| Loader above the route (e.g. on a parent `layout()`)                 | `true`                 | `false`                             |
-| Layout or parallel above the route                                   | `false`                | `false`                             |
+| Segment                                                              | After an action (POST), or a stale Back/Forward | Navigation                          |
+| -------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------- |
+| Route (`path()`)                                                     | `true`                                          | `true` when params or search change |
+| Owned by the route (loaders, layouts, parallels inside the `path()`) | `true`                                          | `true` when params or search change |
+| Loader above the route (e.g. on a parent `layout()`)                 | `true`                                          | `false`                             |
+| Layout or parallel above the route                                   | `false`                                         | `false`                             |
+
+A stale Back/Forward is the background revalidation of a page a server action
+(in this tab or another) marked stale: Back renders the cached page, then
+revalidates it with `stale: true`. It takes an action's defaults, so a layout's
+cart count shows the write with no opt-in. It renders live, as an action does:
+no route-cache record or PPR replay answers it. It is not an action:
+`isAction()` is false and `actionId` is undefined. To keep a loader as it was
+on that request:
+
+```typescript
+loader(RecommendationsLoader, () => [
+  revalidate(({ stale }) => (stale ? false : undefined)),
+]);
+```
 
 #### `|| undefined` (defer) vs `?? false` (hard) — pick deliberately
 
@@ -421,9 +435,10 @@ Pick the idiom by what the segment's default already does (table above). After
 an action, loaders, the route, and segments inside the `path()` already re-run;
 layouts and parallels above the route are skipped:
 
-- **Add a signal where the default skips.** `ctx.isAction(X) || undefined` on a
-  parent layout or a layout-level parallel re-renders it after `X` and defers
-  otherwise. On a loader, the route, or a segment inside the `path()` it
+- **Add a signal where the default skips.**
+  `ctx.isAction(X) || ctx.stale || undefined` on a parent layout or a
+  layout-level parallel re-renders it after `X` and on Back after an action,
+  and defers otherwise. On a loader, the route, or a segment inside the `path()` it
   changes nothing: they already re-run after every action, and on navigation it
   defers.
 - **Narrow after actions where the default re-runs.**
@@ -487,10 +502,12 @@ the same named revalidation contract across producer and consumer segments.
 import type { Revalidate } from "@rangojs/router";
 import * as AccountActions from "./actions/account";
 
-// Match by reference with ctx.isAction() (rename-safe), and defer (|| undefined)
-// so these contracts compose — a hard `false` would short-circuit the rest.
+// Match by reference with ctx.isAction() (rename-safe), true on a stale
+// Back/Forward (the page re-runs, so its producer must), and defer
+// (|| undefined) so these contracts compose — a hard `false` would
+// short-circuit the rest.
 export const revalidateAccountScope: Revalidate = (ctx) =>
-  ctx.isAction(AccountActions) || undefined;
+  ctx.stale || ctx.isAction(AccountActions) || undefined;
 
 // urls.tsx
 layout(AccountLayout, () => [
@@ -955,7 +972,7 @@ function ProductPage() {
 
 A skeleton that has appeared stays on screen for at least about 300 ms before React replaces it with what it was waiting for: React does not replace a fallback sooner than 300 ms after the last fallback committed ([#1078](https://github.com/rangojs/rango/issues/1078)). On a cold click that mounts the `loading()` boundary, a loader that finishes sooner than that still shows its skeleton for about 300 ms, while a slower loader is not delayed. The router leaves this to React: an early skeleton is preferred to holding the click, and a fully prefetched click commits complete and shows none. A nested `loading()` whose data lands after the outer one has been revealed shows its own fallback, and the 300 ms starts again. The loaders feature page on the docs site has the measured figures. Under `transition()` a related cost applies; see [view-transitions](../view-transitions/SKILL.md).
 
-A loader that throws (anything but `notFound()` or `redirect()`) throws at its `useLoader` read on every client lane: a plain or fully prefetched click, Back/Forward restored from the history cache, and the rerun after a server action. A prefetch in which a loader threw is never used, in memory or from the browser's HTTP cache: the click asks the server again, so a loader that has recovered shows its data. The nearest boundary to the read catches it (your React error boundary around the read, else the route's `errorBoundary()`, else the router's root one), and the layouts above keep their instance. The background refresh after Back/Forward onto a stale page is the exception: a loader that fails there leaves the page on screen and logs `[Browser] Background revalidation failed`. Not covered: an `intercept()`'s loaders, and a parallel slot's loaders under its own `loading()`, which are decoded above the slot's content.
+A loader that throws (anything but `notFound()` or `redirect()`) throws at its `useLoader` read on every client lane: a plain or fully prefetched click, Back/Forward restored from the history cache, and the rerun after a server action. A prefetch in which a loader threw is never used, in memory or from the browser's HTTP cache: the click asks the server again, so a loader that has recovered shows its data. The nearest boundary to the read catches it (your React error boundary around the read, else the route's `errorBoundary()`, else the router's root one), and the layouts above keep their instance. The background refresh after Back/Forward onto a stale page is the exception: it re-runs every loader on the defaults (see the defaults table), and a loader that fails there leaves the page on screen as it was and logs `[Browser] Background revalidation failed`. Not covered: an `intercept()`'s loaders, and a parallel slot's loaders under its own `loading()`, which are decoded above the slot's content.
 
 ## Loader Authority: notFound() and redirect()
 

package/skills/middleware/SKILL.md

@@ -90,7 +90,7 @@ import type { Revalidate } from "@rangojs/router";
 import * as CartActions from "./actions/cart";
 
 export const revalidateCartData: Revalidate = (ctx) =>
-  ctx.isAction(CartActions) || undefined;
+  ctx.stale || ctx.isAction(CartActions) || undefined;
 
 layout(CartLayout, () => [
   middleware(cartRenderMiddleware),
@@ -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/migrate-nextjs/SKILL.md

@@ -633,10 +633,11 @@ re-rendering:
 ```typescript
 import { updateBlog } from "./actions/blog";
 
-// Re-run this layout when a blog action fires (layouts above the route are
-// skipped after actions by default; undefined defers otherwise)
+// Re-run this layout when a blog action fires, and on Back after an action
+// (layouts above the route are skipped after actions by default; undefined
+// defers otherwise)
 layout(BlogLayout, () => [
-  revalidate((ctx) => ctx.isAction(updateBlog) || undefined),
+  revalidate((ctx) => ctx.isAction(updateBlog) || ctx.stale || undefined),
   path("/blog/:slug", BlogPost, { name: "blogPost" }),
 ]);
 
@@ -860,7 +861,7 @@ Server actions work the same way — `"use server"` directive, `useActionState`,
 
 Key difference: in Rango, route middleware does NOT wrap action execution. Actions only see global middleware context. Use `getRequestContext()` in actions to access `ctx.set()`/`ctx.get()`.
 
-Next.js's `revalidateTag()` maps directly: tag entries via `cache({ tags })` / `cacheTag(...)`, then invalidate. **In a server action use `await updateTag(tag)`** — it is read-your-own-writes, so the action's own re-render sees fresh data, and it rejects when the store's durable write fails; `revalidateTag(tag)` is a background (non-blocking) hard-purge for route handlers / webhooks. The request that calls `revalidateTag()` also reads its own writes, but a failed durable write only reaches `onError`. `revalidatePath()` has no path-based equivalent — tag the route's entries instead. Separately, the route, the segments inside its `path()`, and all loaders already re-run after every action; layouts and parallels above the route are skipped. To re-render one of those skipped segments after an action, attach `revalidate((ctx) => ctx.isAction(updateBlog) || undefined)` to it; to narrow a loader or route segment to one action, use `revalidate((ctx) => (ctx.isAction() ? ctx.isAction(updateBlog) : undefined))` (match the imported action by reference, as in §3). See `/server-actions` for the full pattern (validation, error handling, file uploads), `/caching` for tag invalidation, and `/loader` for revalidation rule semantics.
+Next.js's `revalidateTag()` maps directly: tag entries via `cache({ tags })` / `cacheTag(...)`, then invalidate. **In a server action use `await updateTag(tag)`** — it is read-your-own-writes, so the action's own re-render sees fresh data, and it rejects when the store's durable write fails; `revalidateTag(tag)` is a background (non-blocking) hard-purge for route handlers / webhooks. The request that calls `revalidateTag()` also reads its own writes, but a failed durable write only reaches `onError`. `revalidatePath()` has no path-based equivalent — tag the route's entries instead. Separately, the route, the segments inside its `path()`, and all loaders already re-run after every action; layouts and parallels above the route are skipped. To re-render one of those skipped segments after an action, and on Back after one, attach `revalidate((ctx) => ctx.isAction(updateBlog) || ctx.stale || undefined)` to it; to narrow a loader or route segment to one action, use `revalidate((ctx) => (ctx.isAction() ? ctx.isAction(updateBlog) : undefined))` (match the imported action by reference, as in §3). See `/server-actions` for the full pattern (validation, error handling, file uploads), `/caching` for tag invalidation, and `/loader` for revalidation rule semantics.
 
 ## 8. Metadata / Head
 

package/skills/parallel/SKILL.md

@@ -392,8 +392,9 @@ parallel(
   () => [
     loader(CartLoader),
     // Layout-level slot (kept after actions by default): also re-render after
-    // cart actions. Under a path() the slot re-renders after every action anyway.
-    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
+    // cart actions and on Back after an action. Under a path() the slot
+    // re-renders after every action anyway.
+    revalidate((ctx) => ctx.isAction(CartActions) || ctx.stale || undefined),
   ]
 )
 ```
@@ -456,7 +457,7 @@ import type { Revalidate } from "@rangojs/router";
 import * as CartActions from "./actions/cart";
 
 export const revalidateCartData: Revalidate = (ctx) =>
-  ctx.isAction(CartActions) || undefined;
+  ctx.stale || ctx.isAction(CartActions) || undefined;
 
 layout(CartLayout, () => [
   revalidate(revalidateCartData), // producer reruns
@@ -575,7 +576,7 @@ export const shopPatterns = urls(({
       () => [
         loader(CartLoader),
         loading(<CartSkeleton />),
-        revalidate((ctx) => ctx.isAction(CartActions) || undefined),
+        revalidate((ctx) => ctx.isAction(CartActions) || ctx.stale || undefined),
       ]
     ),
 

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
@@ -482,6 +482,7 @@ The bounded bypass tokens, grouped by when they are decided:
 | Token                                                                         | Decided           | Meaning                                                                                                                                                                                                              |
 | ----------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `method`, `dynamic`, `nonce`, `store-unavailable`, `passive-read-unsupported` | pre-read          | request/route/store ineligible for replay                                                                                                                                                                            |
+| `stale`                                                                       | pre-read          | a stale request (`_rsc_stale`, Back/Forward onto a page an action made stale) renders live, as an action does: the record may predate the write                                                                      |
 | `no-navigation-context`                                                       | pre-read          | no `X-RSC-Router-Client-Path` and no same-origin `Referer`; a partial match is impossible                                                                                                                            |
 | `prerender-store`                                                             | pre-read or match | `Prerender()` route served by its baked artifact (pre-read probe of the normal variant; reclassified post-match when the store actually served, either variant)                                                      |
 | `intercept`                                                                   | match             | the navigation resolved to an intercept — replay is never armed for intercepts (they keep their normal cache path); no heal capture                                                                                  |
@@ -508,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()`
@@ -1176,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:
@@ -1632,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