@rangojs/router 0.26.5 → 0.27.0

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

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

@@ -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                                                                                  |

package/skills/rango/SKILL.md

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

package/skills/server-actions/SKILL.md

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

package/skills/testing/predicates.md

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

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

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

package/skills/ux-architecture/SKILL.md

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

package/src/browser/action-coordinator.ts

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

package/src/browser/action-fence.ts

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

package/src/browser/event-controller.ts

@@ -52,6 +52,18 @@ export interface NavigationEntry {
   phase: NavigationPhase;
   startedAt: number;
   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>;
 }
 
 /**
@@ -351,6 +363,12 @@ export interface EventController {
 
   // Direct state access for advanced use
   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;
@@ -513,6 +531,9 @@ export function createEventController(
   // links a request to its signal only until then): the navigation stops
   // reading it, and it streams to its end.
   let streamingNavigation: AbortController | null = null;
+  // The newest navigation until it settles (getUnsettledNavigation). Not
+  // derived state: no hook reads it, and moving it notifies nothing.
+  let unsettledNavigation: NavigationEntry | null = null;
 
   const inflightActions = new Map<string, ActionEntry>();
 
@@ -743,19 +764,31 @@ export function createEventController(
     }
 
     const abort = new AbortController();
+    let resolveSettled!: (committed: boolean) => void;
     const entry: NavigationEntry = {
       url,
       abort,
       phase: "fetching",
       startedAt: Date.now(),
       options,
+      settled: new Promise((resolve) => (resolveSettled = resolve)),
+    };
+    const settle = (committed: boolean): void => {
+      if (unsettledNavigation === entry) unsettledNavigation = null;
+      resolveSettled(committed);
     };
+    abort.signal.addEventListener("abort", () => settle(false));
 
     currentNavigation = entry;
+    unsettledNavigation = entry;
     notify();
 
     let completed = false;
+    let disposed = false;
     let openStreams = 0;
+    const settleIfEnded = (): void => {
+      if (disposed && openStreams === 0) settle(completed);
+    };
 
     return {
       abort,
@@ -780,6 +813,7 @@ export function createEventController(
             if (--openStreams === 0 && streamingNavigation === abort) {
               streamingNavigation = null;
             }
+            settleIfEnded();
             notify();
           },
         };
@@ -797,6 +831,8 @@ export function createEventController(
 
       // Disposable: cleanup if not completed (e.g., error thrown)
       [Symbol.dispose]() {
+        disposed = true;
+        settleIfEnded();
         // If aborted by another navigation, don't touch state
         if (abort.signal.aborted) return;
 
@@ -1287,6 +1323,7 @@ export function createEventController(
 
     // Direct access
     getCurrentNavigation: () => currentNavigation,
+    getUnsettledNavigation: () => unsettledNavigation,
     getInflightActions: () => inflightActions,
     hadAnyConcurrentActions: () => hadAnyConcurrentActions,
   };

package/src/browser/history-state.ts

@@ -169,13 +169,21 @@ export 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 function clearLocationStateOnDocumentLoad(): void {
   const state: unknown = window.history.state;
   if (state === null || typeof state !== "object") return;
   let next: Record<string, unknown> | undefined;
   for (const key in state) {
-    if (isLocationStateKey(key) && key.endsWith(CLEAR_ON_RELOAD_KEY_SUFFIX)) {
+    if (
+      (isLocationStateKey(key) && key.endsWith(CLEAR_ON_RELOAD_KEY_SUFFIX)) ||
+      key === "intercept" ||
+      key === "sourceUrl"
+    ) {
       next ??= { ...state };
       delete next[key];
     }

package/src/browser/intercept-utils.ts

@@ -1,5 +1,7 @@
 import type { ResolvedSegment } from "./types.js";
 import type { SlotState } from "../types.js";
+import { isPlaceholder } from "../types/segments.js";
+import { loaderParentId } from "./react/filter-segment-order.js";
 
 /**
  * Check if a segment is an intercept segment.
@@ -51,3 +53,52 @@ export function hasActiveIntercept(slots?: Record<string, SlotState>): boolean {
 export function isInterceptOnlyCache(segments: ResolvedSegment[]): boolean {
   return segments.some(isInterceptSegment);
 }
+
+/**
+ * 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 function interceptMatched(
+  clientIds: readonly string[],
+  slotIds: readonly string[],
+): string[] {
+  // loaderParentId leaves a non-loader id as it is: the slot's own id goes too.
+  return [
+    ...clientIds.filter((id) => loaderParentId(id) !== slotIds[0]),
+    ...slotIds,
+  ];
+}
+
+/**
+ * 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 function wholeInterceptMatched(
+  held: readonly ResolvedSegment[],
+  answer: {
+    matched?: string[];
+    segments?: ResolvedSegment[];
+    slots?: Record<string, SlotState>;
+  },
+): string[] | undefined {
+  if (!hasActiveIntercept(answer.slots)) return undefined;
+  const heldIds = held.filter((s) => !isPlaceholder(s)).map((s) => s.id);
+  if (heldIds.length === 0) return undefined;
+  const slot = answer.segments?.find(
+    (s) => isInterceptSegment(s) && s.type !== "loader",
+  );
+  if (!slot) return undefined;
+  const slotLoaderIds = (answer.matched ?? []).filter(
+    (id) => id !== slot.id && loaderParentId(id) === slot.id,
+  );
+  return interceptMatched(heldIds, [slot.id, ...slotLoaderIds]);
+}

package/src/browser/navigation-bridge.ts

@@ -643,16 +643,17 @@ export function createNavigationBridge(
       const isIntercept = historyState?.intercept === true;
       const interceptSourceUrl = historyState?.sourceUrl;
 
-      // Check if intercept context is changing (same URL, different intercept state)
-      // If so, abort in-flight actions - their results would be for wrong context
+      // Actions in flight keep running across an intercept change, as across
+      // any navigation (server-action-bridge.ts followUp).
       const currentInterceptSource = store.getInterceptSourceUrl();
-      const newInterceptSource = interceptSourceUrl ?? null;
-      if (currentInterceptSource !== newInterceptSource) {
-        debugLog(
-          `[Browser] Intercept context changing (${currentInterceptSource} -> ${newInterceptSource}), aborting in-flight actions`,
-        );
-        eventController.abortAllActions();
-      }
+      // An intercept is fetched only from its source page (the page under
+      // an open intercept counts as on screen). From any other page the
+      // entry loads as a document, which renders its URL's full page.
+      const loadsDocument =
+        isIntercept &&
+        generateHistoryKey(
+          currentInterceptSource ?? store.getSegmentState().currentUrl,
+        ) !== generateHistoryKey(interceptSourceUrl);
 
       // Popstate that exits an intercept to a non-intercept destination. The
       // fallback fetch path below needs `leave-intercept` mode so it filters
@@ -673,13 +674,6 @@ export function createNavigationBridge(
         historyKey,
       );
 
-      // If this is an intercept, restore the intercept context
-      if (isIntercept && interceptSourceUrl) {
-        store.setInterceptSourceUrl(interceptSourceUrl);
-      } else {
-        store.setInterceptSourceUrl(null);
-      }
-
       // Helper to check if streaming is in progress
       const isStreaming = () => eventController.getState().isStreaming;
 
@@ -701,6 +695,7 @@ export function createNavigationBridge(
       const isStale = (cached?.stale ?? false) || isActionFenceActive();
 
       if (isRestorable(cachedSegments)) {
+        store.setInterceptSourceUrl(interceptSourceUrl ?? null);
         // transition({ when }) decides the restore (kind "pop") against the
         // entry being left, so before the store moves to the restored entry.
         // The decision the entry was committed with is not reused: it was
@@ -872,7 +867,15 @@ export function createNavigationBridge(
         debugLog("[Browser] History cache miss for key:", historyKey);
       }
 
-      // Fetch if not cached
+      // Fetch if not cached. The document load starts at the top: pagehide
+      // saves the scroll on screen under this entry, and the browser
+      // restores it after the reload. Instant, so `scroll-behavior: smooth`
+      // cannot leave it part-way when pagehide saves it.
+      if (loadsDocument) {
+        window.scrollTo({ top: 0, behavior: "instant" });
+        return window.location.reload();
+      }
+      store.setInterceptSourceUrl(interceptSourceUrl ?? null);
       const tx = createNavigationTransaction(store, eventController, url, {
         replace: true,
       });