@rangojs/router 0.26.5 → 0.27.0

package/dist/bin/rango.js

@@ -1644,7 +1644,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@rangojs/router",
-      version: "0.26.5",
+      version: "0.27.0",
       description: "Django-inspired RSC router with composable URL patterns",
       keywords: [
         "react",
@@ -1852,7 +1852,7 @@ var init_package = __esm({
       },
       dependencies: {
         "@types/debug": "^4.1.12",
-        "@vitejs/plugin-rsc": "^0.5.36",
+        "@vitejs/plugin-rsc": "^0.5.38",
         debug: "^4.4.1",
         "magic-string": "^0.30.17",
         picomatch: "^4.0.4",

package/dist/types/browser/action-coordinator.d.ts

@@ -6,8 +6,6 @@ import type { ActionEntry } from "./event-controller.js";
  */
 type ActionScenario = {
     type: "navigated-away";
-    historyKeyChanged: boolean;
-    onInterceptRoute: boolean;
 } | {
     type: "hmr-missing";
 } | {
@@ -44,8 +42,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;
 }
 /**
  * Classify a post-reconciliation action outcome. Ordered priority chain: each

package/dist/types/browser/action-fence.d.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/dist/types/browser/event-controller.d.ts

@@ -20,6 +20,18 @@ export interface NavigationEntry {
     options?: NavigateOptionsInternal & {
         skipLoadingState?: boolean;
     };
+    /**
+     * Resolves once the navigation has ended: its transaction ended and every
+     * stream it opened closed. True when it committed, false when it ended
+     * without a commit (a failure) or was left (aborted, which settles it at
+     * once). A `prefetch: false` fill holds the transaction open
+     * (partial-update.ts awaits fillHoles before it resolves) and its stream
+     * until the fill's answer streamed, so a waiter never cuts a fill or a
+     * stream short. Only the action bridge's follow-up awaits it
+     * (server-action-bridge.ts followUp); no hook reads it, and settling it
+     * notifies nothing.
+     */
+    settled: Promise<boolean>;
 }
 /**
  * Entry tracking an in-flight action
@@ -279,6 +291,12 @@ export interface EventController {
     /** True once after a `treeless` commit. */
     takeTreelessLocationState(): boolean;
     getCurrentNavigation(): NavigationEntry | null;
+    /**
+     * The newest navigation until it settles (NavigationEntry.settled): before
+     * its commit, and after it while its transaction or a stream is still
+     * open. Null once it settled or was left.
+     */
+    getUnsettledNavigation(): NavigationEntry | null;
     getInflightActions(): Map<string, ActionEntry>;
     /** Whether any concurrent actions have occurred (shared across all handles) */
     hadAnyConcurrentActions(): boolean;

package/dist/types/browser/history-state.d.ts

@@ -46,6 +46,10 @@ export declare function stripShellMissMarker(): void;
  *
  * A slot is recognised by its key alone (the `~r` suffix): at start-up the
  * module that defines it may not be loaded.
+ *
+ * The same pass drops the entry's intercept marks (`intercept`,
+ * `sourceUrl`): a document request never renders an intercept, so the entry
+ * is a full page for later Back/Forward.
  */
 export declare function clearLocationStateOnDocumentLoad(): void;
 /**

package/dist/types/browser/intercept-utils.d.ts

@@ -31,3 +31,26 @@ export declare function hasActiveIntercept(slots?: Record<string, SlotState>): b
  * whether interception happens depends on the current page context.
  */
 export declare function isInterceptOnlyCache(segments: ResolvedSegment[]): boolean;
+/**
+ * An intercept's `matched`: the client's ids without any of the slot's (its
+ * id and every loader segment on it, another intercept's into the same slot
+ * included), then the slot's (interceptSegmentIds). One order for the
+ * prefetch, its fill, an action and a revisit: a fill whose `matched` differs
+ * from its tree's is rendered as a new tree (browser/partial-update.ts
+ * fillHoles). Shared by router/match-result.ts and wholeInterceptMatched.
+ */
+export declare function interceptMatched(clientIds: readonly string[], slotIds: readonly string[]): string[];
+/**
+ * The `matched` the browser keeps for an intercept answer to a request that
+ * held no segments (a followed redirect, a Back/Forward revalidation with
+ * handles pending, the dev HMR refetch), or undefined to keep the answer's.
+ * The server never renders the page under an intercept and lists it only
+ * from the ids a request held, so such an answer has an empty outlet under
+ * the slot. The page it lands over (`held`) stays, as the server lists it for
+ * a request that holds it.
+ */
+export declare function wholeInterceptMatched(held: readonly ResolvedSegment[], answer: {
+    matched?: string[];
+    segments?: ResolvedSegment[];
+    slots?: Record<string, SlotState>;
+}): string[] | undefined;

package/dist/types/browser/rsc-router.d.ts

@@ -21,7 +21,7 @@ export interface InitBrowserAppOptions {
     storeOptions?: {
         /**
          * Maximum number of history entries to cache
-         * @default 10
+         * @default 20
          */
         cacheSize?: number;
     };

package/dist/types/prefetch-markers.d.ts

@@ -1,14 +1,21 @@
 /**
- * The wire markers of prefetches and of `prefetch: false`
- * (docs/design/prefetch-false.md): shared by the browser and the server
- * (router/segment-resolution/prefetch-deferral.ts requestKind,
- * rsc/prefetch-render-error.ts). Dependency free, like segment-fragments.ts:
- * the browser must not import the server modules that use them.
+ * The wire markers of prefetches, of `prefetch: false`
+ * (docs/design/prefetch-false.md) and of stale requests: shared by the browser
+ * and the server (router/segment-resolution/prefetch-deferral.ts requestKind,
+ * rsc/prefetch-render-error.ts, rsc/rsc-rendering.ts,
+ * cache/document-cache.ts, router/navigation-snapshot.ts). Dependency free,
+ * like segment-fragments.ts: the browser must not import the server modules
+ * that use them.
  */
 /** Request header of a `<Link>` prefetch (browser/prefetch/fetch.ts). */
 export declare const PREFETCH_HEADER = "X-Rango-Prefetch";
 /** Query param of a fill request (browser/navigation-client.ts). */
 export declare const FILL_PARAM = "_rsc_fill";
+/**
+ * Query param of a stale request (browser/navigation-client.ts): `revalidate()`
+ * sees `stale: true` (router/navigation-snapshot.ts).
+ */
+export declare const STALE_PARAM = "_rsc_stale";
 /**
  * The last row of a prefetch whose render reported an error
  * (rsc/prefetch-render-error.ts): a Flight hint with a code React does not

package/dist/types/router/match-context.d.ts

@@ -166,6 +166,14 @@ export interface MatchContext<TEnv = any> {
     }>;
     isFullMatch: boolean;
 }
+/**
+ * An action, or a stale partial (`_rsc_stale`: Back/Forward onto an entry
+ * marked stale, `refresh()`, the cross-tab refresh, the action follow-up, a
+ * zero-segment refetch), renders live: no route-cache or prerender-store read
+ * a live handler can replace, and no store. An action's render is never
+ * stored, so a record can be older than the copy the client holds after it.
+ */
+export declare function rendersLive(ctx: Pick<MatchContext, "isAction" | "stale">): boolean;
 /**
  * Mutable state that flows through the pipeline
  */

package/dist/types/router/match-middleware/cache-lookup.d.ts

@@ -93,7 +93,7 @@
  */
 import type { ResolvedSegment } from "../../types.js";
 import { type EntryData } from "../../server/context.js";
-import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import { type MatchContext, type MatchPipelineState } from "../match-context.js";
 import type { PrerenderStore } from "../../prerender/store.js";
 import type { PrerenderTargetObject, ResolvedPrerender } from "../../prerender/on-demand.js";
 import { type RequestContext } from "../../server/request-context.js";

package/dist/types/router/match-middleware/cache-store.d.ts

@@ -19,7 +19,7 @@
  *   +---------------------+
  *   | Should skip cache?  |
  *   | - !cacheScope       |──yes──> return
- *   | - isAction          |
+ *   | - rendersLive       |
  *   | - cacheHit          |
  *   | - method !== GET    |
  *   +---------------------+
@@ -101,7 +101,7 @@
  *   - Non-GET request (only GET requests are cacheable)
  */
 import type { ResolvedSegment } from "../../types.js";
-import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import { type MatchContext, type MatchPipelineState } from "../match-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 /**
  * Creates cache store middleware

package/dist/types/router/revalidation.d.ts

@@ -40,8 +40,13 @@ export interface EvaluateRevalidationOptions<TEnv> {
     context: HandlerContext<any, TEnv>;
     /** Action context if triggered by action */
     actionContext?: ActionContext;
-    /** If true, this is a stale cache revalidation request */
+    /** The browser's `_rsc_stale` signal: seeds the action defaults. */
     stale?: boolean;
+    /**
+     * The route-cache entry is past its TTL (SWR). Predicates see it as `stale`;
+     * it never seeds the action defaults.
+     */
+    cacheStale?: boolean;
     /** Trace source hint for the revalidation trace */
     traceSource?: RevalidationTraceEntry["source"];
     /**

package/dist/types/router/router-context.d.ts

@@ -4,6 +4,7 @@ import type { HandlerContext, ResolvedSegment, ShouldRevalidateFn } from "../typ
 import type { RouteMatchResult } from "./pattern-matching.js";
 import type { TelemetrySink } from "./telemetry.js";
 import type { ResolveSegmentOptions } from "./segment-resolution.js";
+import type { EvaluateRevalidationOptions } from "./revalidation.js";
 /**
  * Revalidation context passed to segment resolution
  */
@@ -70,23 +71,7 @@ export interface RouterContext<TEnv = any> {
         items: T[];
         matchedIds: string[];
     }>;
-    evaluateRevalidation: (params: {
-        segment: ResolvedSegment;
-        prevParams: Record<string, string>;
-        getPrevSegment: (() => Promise<ResolvedSegment | undefined>) | null;
-        request: Request;
-        prevUrl: URL;
-        nextUrl: URL;
-        revalidations: Array<{
-            name: string;
-            fn: any;
-        }>;
-        routeKey: string;
-        context: HandlerContext<any, TEnv>;
-        actionContext?: any;
-        stale?: boolean;
-        traceSource?: "segment-resolution" | "cache-hit" | "loader" | "parallel" | "orphan-layout" | "route-handler" | "layout-handler" | "intercept-loader";
-    }) => Promise<boolean>;
+    evaluateRevalidation: (params: EvaluateRevalidationOptions<TEnv>) => Promise<boolean>;
     getRequestContext: () => {
         waitUntil: (fn: () => Promise<void>) => void;
         _handleStore?: any;

package/dist/types/rsc/shell-capture-constants.d.ts

@@ -41,7 +41,7 @@ export declare const PPR_REPLAY_STATUS_HEADER: string;
  * producer (rsc-rendering.ts) and the parser (testing/shell-status.ts): a
  * reason the parser does not list parses as null.
  */
-export declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "no-navigation-context", "prerender-store", "intercept", "cache-disabled", "read-error", "no-entry", "invalid-version", "corrupt-entry", "no-segment-snapshot", "snapshot-miss", "explicit-cache-hit", "rewritten"];
+export declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "stale", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "no-navigation-context", "prerender-store", "intercept", "cache-disabled", "read-error", "no-entry", "invalid-version", "corrupt-entry", "no-segment-snapshot", "snapshot-miss", "explicit-cache-hit", "rewritten"];
 /** One of {@link PPR_REPLAY_BYPASS_REASONS}. */
 export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
 /**

package/dist/types/testing/serve-shell-request.d.ts

@@ -76,6 +76,12 @@ export interface ServeShellRequestOptions<TEnv = any> {
      * that source. `rewriteTarget` sends the `metadata.rewriteTarget` the page at
      * `from` carried when middleware rewrote it (`_rsc_rt`), as the browser
      * does: the server then 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`)
+     * and segments take an action's revalidation defaults; it renders live, as
+     * an action does, so neither the route cache nor the document cache answers
+     * or stores it, and a `ppr` route's `replayStatus` is
+     * `{ outcome: "BYPASS", reason: "stale" }`.
      */
     partial?: true | {
         from?: string;
@@ -84,6 +90,7 @@ export interface ServeShellRequestOptions<TEnv = any> {
         prefetch?: boolean;
         fill?: boolean;
         interceptSource?: string;
+        stale?: boolean;
     };
     /**
      * POST this form as a submit before hydration: the no-JS request the

package/dist/types/types/handler-context.d.ts

@@ -510,10 +510,10 @@ export type IsActionFn = (...actions: ActionRef[]) => boolean;
  * ```ts
  * import * as CartActions from "./actions/cart";
  *
- * // Idiom A — "mine, else defer": re-render on my actions, otherwise return
- * // undefined so the segment's default decision still applies (and downstream
- * // revalidators get a say).
- * revalidate((ctx) => ctx.isAction(CartActions) || undefined)
+ * // Idiom A — "mine, else defer": re-render on my actions and on Back after
+ * // an action, otherwise return undefined so the segment's default decision
+ * // still applies (and downstream revalidators get a say).
+ * revalidate((ctx) => ctx.isAction(CartActions) || ctx.stale || undefined)
  *
  * // Idiom B — "mine only": re-render on my actions and suppress everything
  * // else (isAction returns a raw boolean, so an unrelated action yields false).
@@ -629,8 +629,11 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
      */
     toRouteName?: DefaultRouteName;
     /**
-     * `true` when the browser signals that data may be stale — typically because
-     * a server action was executed in this or another tab (`_rsc_stale` header).
+     * `true` on a revalidation of a page the browser marked stale (the
+     * `_rsc_stale` query param): Back/Forward onto a history entry after a
+     * server action in this or another tab, or while one is in flight. A request
+     * that holds no segments (the follow-up after an action, `refresh()`) is
+     * marked stale too, but there every segment renders and no predicate runs.
      *
      * This is NOT segment cache staleness (loaders are never segment-cached).
      * Use this to decide whether loader data should be re-fetched after an

package/dist/types/vite/plugins/server-ref-hashing.d.ts

@@ -3,7 +3,14 @@ import type { Plugin } from "vite";
  * Replace dev-style server-reference ids with their production hashes. The temp
  * server renders Static/Prerender in a dev/serve Vite server, so plugin-rsc mints
  * a dev-style id (e.g. "/src/urls/prerender.tsx"); rewriting only the id (group 2)
- * leaves the hoisted function and its trailing encrypted .bind(...) untouched.
+ * leaves the hoisted function untouched.
+ *
+ * The same id also prefixes the action id ("<id>#<name>") that plugin-rsc
+ * >= 0.5.37 passes to encryptActionBoundArgs/decryptActionBoundArgs as AES-GCM
+ * additional data. The production bundle decrypts under "<hash>#<name>", so bound
+ * args encrypted at build time under the dev-style id fail with OperationError on
+ * invocation. Rewriting every `"<id>#` literal to `"<hash>#` binds them to the
+ * runtime's id.
  * Exported for testing; used by hashServerRefs. Returns null if nothing changed.
  */
 export declare function transformServerRefs(code: string, projectRoot: string): string | null;

package/dist/vite/index.js

@@ -7078,7 +7078,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.26.5",
+  version: "0.27.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -7286,7 +7286,7 @@ var package_default = {
   },
   dependencies: {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.36",
+    "@vitejs/plugin-rsc": "^0.5.38",
     debug: "^4.4.1",
     "magic-string": "^0.30.17",
     picomatch: "^4.0.4",
@@ -10468,18 +10468,22 @@ init_client_ref_hashing();
 var debug9 = createRangoDebugger(NS.transform);
 function transformServerRefs(code, projectRoot) {
   if (!code.includes("registerServerReference")) return null;
-  let hasReplacement = false;
-  const result = code.replace(
+  const hashes = /* @__PURE__ */ new Map();
+  let result = code.replace(
     registerServerReferenceRegex(),
     (match, _value, refKey) => {
       const cleanKey = refKey.split("?")[0];
       const hash = computeProductionHash(projectRoot, cleanKey);
       if (hash === cleanKey) return match;
-      hasReplacement = true;
+      hashes.set(refKey, hash);
       return match.replace(`"${refKey}"`, `"${hash}"`);
     }
   );
-  return hasReplacement ? result : null;
+  if (hashes.size === 0) return null;
+  for (const [refKey, hash] of hashes) {
+    result = result.replaceAll(`"${refKey}#`, `"${hash}#`);
+  }
+  return result;
 }
 function hashServerRefs(projectRoot) {
   const counter = createCounter(debug9, "hash-server-refs");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.26.5",
+  "version": "0.27.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -194,7 +194,7 @@
   },
   "dependencies": {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.36",
+    "@vitejs/plugin-rsc": "^0.5.38",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.4",

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

@@ -202,6 +202,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

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

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