@rangojs/router 0.28.0 → 0.29.0

package/skills/testing/client-components.md

@@ -66,9 +66,13 @@ type RenderRouteResult = RenderResult & {
       url: string,
       options?: {
         loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+        handles?: ReadonlyArray<readonly [Handle<any, any>, unknown[]]>;
         state?: HistoryState;
         replace?: boolean;
         transition?: boolean;
+        // the response's stream: opens a task after the call, before the
+        // commit, and stays open until the promise settles (isStreaming)
+        streamUntil?: Promise<unknown>;
       },
     ): Promise<void>;
     // re-render the current location, as router.refresh() does:
@@ -203,13 +207,14 @@ it("lists no product twice while the next page loads", async () => {
 });
 ```
 
-| To bring state to a reader                          | Do                                                                                                                                                                                                                                           |
-| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| a push / replace, the component's own               | click its `<Link state>` or the control that calls `router.push(url, { state })`, then `waitFor`                                                                                                                                             |
-| a push / replace whose loader the test holds        | `router.navigate(url, { state, replace?, loaders: [[Loader, pendingPromise]] })` on a `transition` spec                                                                                                                                      |
-| back/forward onto an entry                          | `history.replaceState(entry, "")`, then `window.dispatchEvent(new Event("popstate"))` inside `act`. The tree has one location, so no page is restored: readers take the entry as history holds it (also how a `Def.write()` becomes visible) |
-| a reader that mounts while a navigation is pending  | hold the navigation as in the row above, then mount the reader inside `await act(async () => { ... })`: it reads the entry on screen                                                                                                         |
-| a server action's state, a redirect's, an intercept | e2e                                                                                                                                                                                                                                          |
+| To bring state to a reader                                    | Do                                                                                                                                                                                        |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| a push / replace, the component's own                         | click its `<Link state>` or the control that calls `router.push(url, { state })`, then `waitFor`                                                                                          |
+| a push / replace whose loader the test holds                  | `router.navigate(url, { state, replace?, loaders: [[Loader, pendingPromise]] })` on a `transition` spec                                                                                   |
+| back/forward onto the mounted entry or one a navigation wrote | `window.history.back()` inside `await act(async () => { ... })`: the entry's page is restored with its state and handle values, as production's history-cache restore is                  |
+| back/forward onto an entry the test wrote                     | `history.replaceState(entry, "")`, then `window.dispatchEvent(new Event("popstate"))` inside `act`: readers take the entry as history holds it (also how a `Def.write()` becomes visible) |
+| a reader that mounts while a navigation is pending            | hold the navigation as in the row above, then mount the reader inside `await act(async () => { ... })`: it reads the entry on screen                                                      |
+| a server action's state, a redirect's, an intercept           | e2e                                                                                                                                                                                       |
 
 ### Definitions with `clearOnReload`
 
@@ -390,17 +395,19 @@ it("dims the held price while the next product streams", async () => {
 });
 ```
 
-| Pending state                                                                                  | Under `renderRoute`                                                                                                                                                                                    |
-| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed            | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                                                          |
-| `transition` navigate(), settled seed (a plain value)                                          | `false`; the data swaps in the commit.                                                                                                                                                                 |
-| navigate() without `transition`, pending seed                                                  | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag.                                         |
-| `transition: { when }` returning false, or `navigate(url, { transition: false })`              | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.                                              |
-| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic) | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                                                                       |
-| `useNavigation().state`, `useLinkStatus().pending`                                             | Modeled: navigate() starts the navigation as a click does. `loading` from the call, `idle` in the commit, held with it; `pending` true for the destination's link until the commit is handed to React. |
-| `useAction().state`                                                                            | Stays `idle`: navigate() runs no action. e2e.                                                                                                                                                          |
-| `useHandle()` on a held navigation, `navigate(url, { handles, loaders })`                      | Modeled: `handles` arrive on the response's handle stream, so readers keep the page being left's values while React holds the page and take the new ones with its commit.                              |
-| A back/forward restored from the history cache (its view transition, `pop`)                    | NOT modeled: the tree has one location and navigate() caches no entries, so a `popstate` restores nothing. Assert it at e2e.                                                                           |
+| Pending state                                                                                  | Under `renderRoute`                                                                                                                                                                                                  |
+| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed            | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                                                                        |
+| `transition` navigate(), settled seed (a plain value)                                          | `false`; the data swaps in the commit.                                                                                                                                                                               |
+| navigate() without `transition`, pending seed                                                  | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag.                                                       |
+| `transition: { when }` returning false, or `navigate(url, { transition: false })`              | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.                                                            |
+| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic) | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                                                                                     |
+| `useNavigation().state`, `useLinkStatus().pending`                                             | Modeled: navigate() starts the navigation as a click does. `loading` from the call, `idle` in the commit, held with it; `pending` true for the destination's link until that commit, held with it too.               |
+| `useAction().state`                                                                            | Stays `idle`: navigate() runs no action. e2e.                                                                                                                                                                        |
+| `useHandle()` on a held navigation, `navigate(url, { handles, loaders })`                      | Modeled: `handles` arrive on the response's handle stream, so readers keep the page being left's values while React holds the page and take the new ones with its commit.                                            |
+| `useNavigation().isStreaming` past the commit, `navigate(url, { streamUntil })`                | Modeled: the stream opens a task after the call (`pendingUrl` clears) and ends when the promise settles or a newer navigation aborts it; settle it inside `await act(async () => ...)`.                              |
+| A navigation started while React holds a page (a newer click, a `transition: false` commit)    | Call it inside `await act(async () => { ... })`: its first update makes React retry the held page, and a synchronous `act()` drops that retry, so a later urgent commit never renders.                               |
+| A back/forward restored from the history cache (`pop`)                                         | Modeled for the mounted entry and one a navigate() wrote: the page and its handle values come back, decided by `transition({ when })` as kind `"pop"`. A stale entry's revalidation and a restore that fetches: e2e. |
 
 - Per-navigation seeds merge over the render-time `loaders`/`loaderData` for THAT navigation only; a later `navigate()` without `loaders` falls back to the render-time data.
 - Pass settled data as a plain value, not `Promise.resolve(value)`: React has not observed a plain promise yet, so it counts as pending and renders one `stale` frame. (A Flight chunk that has already settled carries its status and is skipped, which a plain value mirrors.)

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; 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| 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; boundary?: 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. `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" }`. `boundary` names the error segment of a thrown action's boundary the page at `from` shows (`_rsc_boundary`), as the background revalidation an earlier action owes that page sends it, with `stale: true` and no `segments`: the response renders every segment above the boundary and nothing at or below it, claims the boundary in `matched` and sends no segment for it. The server reads it only beside `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/view-transitions/SKILL.md

@@ -154,7 +154,7 @@ Every commit the router runs in a transition adds its `transition({ when })` kin
 - Tagging alone animates nothing: React starts a view transition only where a `<ViewTransition>` resolves a class other than `"none"` for the commit's types.
 - A commit outside a transition carries no type: a cold click that mounts new segments, a gated-off commit (`when` returned `false`), and a back/forward restored from the history cache on a route without `transition()` (it commits inside the `popstate` event). Under `transition()` that restore carries `"pop"` and `"navigation-back"`.
 - Under `transition()`, a stale entry's revalidation carries `"revalidate"` and `"action"`. An `action`-keyed map that must skip it also keys `revalidate: "none"` (`"none"` wins over any other match).
-- The types reach the commit that brings the page. React keeps one queue of transition types per root, and the first transition commit takes the whole queue. No router hook update takes them first: `useHandle()` and `useSegments()` commit with the page, and a `useNavigation()` value that moves while neither the state nor the URL does (`pendingUrl` as the response starts streaming, `isStreaming` as it ends) commits with the page while the reader has a held value, urgently otherwise, so it starts no view transition of its own. A transition your own code starts while React holds a navigation's page can still take them. Handle values on a held page land in the commit right after the page, by design; see [hooks](../hooks/handle-and-actions.md#when-handle-values-change-by-design). Use a kind map to choose an animation, never for correctness.
+- The types reach the commit that brings the page. React keeps one queue of transition types per root, and the first transition commit takes the whole queue. No router hook update takes them first: `useSegments()` commits with the page and `useHandle()` right after it, and a `useNavigation()` value that moves while neither the state nor the URL does (`pendingUrl` as the response starts streaming, `isStreaming` as it ends) commits with the page while the reader has a held value, urgently otherwise, so it starts no view transition of its own. `useAction()` values commit urgently. `useLinkStatus()` commits `pending` urgently and its end with the page, and a newer navigation or an abort ends it urgently, outside a held commit; neither starts a transition. A transition your own code starts while React holds a navigation's page can still take them. Handle values on a held page land in the commit right after the page, by design; see [hooks](../hooks/handle-and-actions.md#when-handle-values-change-by-design). Use a kind map to choose an animation, never for correctness.
 
 ### Back and Forward
 

package/src/browser/action-fence.ts

@@ -20,7 +20,8 @@
  *
  * 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
+ * whole (or whole above an action's error boundary on screen, which it
+ * holds), 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).
  *

package/src/browser/event-controller.ts

@@ -92,6 +92,11 @@ export interface ActionEntry {
   startedAt: number;
   /** Whether action processing is complete (may still be streaming) */
   completed?: boolean;
+  /**
+   * Set when a later call started (see startAction): "id" hides this call
+   * from every reader, "name" from readers that match by export name.
+   */
+  supersededBy?: "id" | "name";
 }
 
 /**
@@ -104,7 +109,7 @@ export interface DerivedNavigationState {
   isStreaming: boolean;
   /** Whether a navigation is active (fetching or streaming, before commit) */
   isNavigating: boolean;
-  /** Current committed location */
+  /** The location of the last page flushed to React (useNavigation keeps the page on screen) */
   location: NavigationLocation;
   /** URL being navigated to (null if idle) */
   pendingUrl: string | null;
@@ -712,15 +717,18 @@ export function createEventController(
     // idle snapshot (the same reference use-action falls back to).
     if (inflightActions.size === 0) return DEFAULT_ACTION_STATE;
 
-    const entry = [...inflightActions.values()]
-      .filter((a) => matchesActionId(actionId, a.actionId))
-      .reduce<ActionEntry | undefined>((best, a) => {
-        if (!best) return a;
-        const aActive = a.phase !== "settling";
-        const bActive = best.phase !== "settling";
-        if (aActive !== bActive) return aActive ? a : best;
-        return a.startedAt > best.startedAt ? a : best;
-      }, undefined);
+    // The latest call this reader matches, or none once a later call left the
+    // map: an earlier call still running is never reported again.
+    const byName = !actionId.includes("#");
+    let entry: ActionEntry | undefined;
+    for (const a of inflightActions.values()) {
+      if (
+        matchesActionId(actionId, a.actionId) &&
+        (byName ? !a.supersededBy : a.supersededBy !== "id")
+      ) {
+        entry = a;
+      }
+    }
 
     if (!entry) {
       return { ...DEFAULT_ACTION_STATE };
@@ -913,6 +921,20 @@ export function createEventController(
       hadAnyConcurrentActions = true;
     }
 
+    // useAction reports the latest call. Every earlier call that a reader of
+    // this one also matches is hidden from that reader for good, so it never
+    // shows again after this call settles and leaves the map: a call of the
+    // same action from every reader, a call of another action with the same
+    // export name from readers that match by name (matchesActionId).
+    const hash = actionId.lastIndexOf("#");
+    const name = hash === -1 ? null : actionId.slice(hash + 1);
+    for (const a of inflightActions.values()) {
+      if (a.actionId === actionId) a.supersededBy = "id";
+      else if (name !== null && matchesActionId(name, a.actionId)) {
+        a.supersededBy ??= "name";
+      }
+    }
+
     const entry: ActionEntry = {
       id,
       actionId,

package/src/browser/navigation-bridge.ts

@@ -45,6 +45,7 @@ import {
 } from "./navigation-store.js";
 import type { EventController } from "./event-controller.js";
 import { isInterceptOnlyCache } from "./intercept-utils.js";
+import { actionBoundaryAt, idsAboveBoundary } from "./segment-reconciler.js";
 import {
   toNetworkError,
   emitNetworkError,
@@ -206,7 +207,10 @@ export function createNavigationBridge(
     error: ServerRedirect,
     url: string,
     hops: number,
-    options: { replace?: boolean; transition?: boolean },
+    options: Pick<
+      NavigateOptionsInternal,
+      "replace" | "transition" | "_redirectFrom"
+    >,
   ): Promise<void> {
     const redirectUrl = validateRedirectOrigin(
       error.url,
@@ -228,6 +232,7 @@ export function createNavigationBridge(
       ...options,
       _skipCache: true,
       _redirectHops: hops + 1,
+      _redirectFrom: options._redirectFrom ?? url,
     });
   }
 
@@ -414,8 +419,11 @@ export function createNavigationBridge(
       // 3. when leaving intercept - we need fresh non-intercept segments from server
       // 4. redirect-with-state - force re-render so hooks read fresh state
       // 5. stale cache - server action invalidated it, need fresh data with loading state
+      // 6. an error boundary in the list - a link renders the page again; its
+      //    ids would tell the server the client holds what the error replaced
       const hasUsableCache =
         isRestorable(cachedSegments) &&
+        !cachedSegments.some((s) => s.type === "error") &&
         !isInterceptOnlyCache(cachedSegments) &&
         !isLeavingIntercept &&
         !cached?.stale &&
@@ -538,7 +546,11 @@ export function createNavigationBridge(
             error,
             url,
             options?._redirectHops ?? 0,
-            { replace: options?.replace, transition: options?.transition },
+            {
+              replace: options?.replace,
+              transition: options?.transition,
+              _redirectFrom: options?._redirectFrom,
+            },
           );
         }
 
@@ -569,9 +581,19 @@ export function createNavigationBridge(
     },
 
     /**
-     * Refresh current route
+     * Refresh current route. A cross-tab refresh holds the action error
+     * boundary the page shows (actionBoundaryAt), as the follow-up does: it
+     * is this tab's own outcome, not a read another tab's write changed. A
+     * refresh the app asks for renders it again.
      */
-    async refresh(): Promise<void> {
+    async refresh(crossTab?: boolean): Promise<void> {
+      const shown =
+        (crossTab &&
+          !store.getInterceptSourceUrl() &&
+          store.getCachedSegments(store.getHistoryKey())?.segments) ||
+        [];
+      const at = actionBoundaryAt(shown);
+      if (at === 0) return;
       eventController.abortNavigation();
 
       const tx = createNavigationTransaction(
@@ -589,7 +611,7 @@ export function createNavigationBridge(
           false,
           tx.handle.signal,
           tx.with({ url: window.location.href, replace: true, scroll: false }),
-          { type: "navigate", refresh: true },
+          { type: "navigate", refresh: true, boundary: shown[at]?.id },
         );
       } catch (error) {
         // Aborted or superseded: bail without rendering a boundary (see navigate()).
@@ -717,9 +739,20 @@ export function createNavigationBridge(
             }),
           });
 
+        // An action error boundary the entry shows (actionBoundaryAt) is
+        // held: the page holds the ids above it, so a link renders it again,
+        // and the revalidation below renders above it. Never under an
+        // intercept, as the follow-up (server-action-bridge.ts).
+        const boundaryAt = isIntercept ? -1 : actionBoundaryAt(cachedSegments);
+        const boundary = cachedSegments[boundaryAt]?.id;
+        const heldIds = idsAboveBoundary(
+          cachedSegments.map((s) => s.id),
+          boundary,
+        );
+
         // Update store to point to this history entry
         store.setHistoryKey(historyKey);
-        store.setSegmentIds(cachedSegments.map((s) => s.id));
+        store.setSegmentIds(heldIds);
         store.setCurrentUrl(url);
         store.setPath(new URL(url).pathname);
 
@@ -798,8 +831,9 @@ export function createNavigationBridge(
                 onUpdate({ ...popstateUpdate, inTransition: true });
               });
             }
-            // SWR: If stale, trigger background revalidation
-            if (isStale) {
+            // SWR: If stale, trigger background revalidation. Nothing is
+            // above a boundary at the page's first segment.
+            if (isStale && boundaryAt !== 0) {
               debugLog("[Browser] Cache is stale, background revalidating...");
               // Background revalidation - don't await, just fire and forget.
               // When the entry's handles are incomplete (a deferred Meta was still
@@ -811,9 +845,7 @@ export function createNavigationBridge(
               // would stay the pre-resolution carry. handlesPending is set only for
               // the deferred-Meta-aborted case, so action/cross-tab SWR keeps the
               // cheap diff path.
-              const segmentIds = cached?.handlesPending
-                ? []
-                : cachedSegments.map((s) => s.id);
+              const segmentIds = cached?.handlesPending ? [] : heldIds;
 
               const tx = createNavigationTransaction(
                 store,
@@ -835,7 +867,7 @@ export function createNavigationBridge(
                   interceptSourceUrl,
                   cacheOnly: true,
                 }),
-                { type: "stale-revalidation", interceptSourceUrl },
+                { type: "stale-revalidation", interceptSourceUrl, boundary },
               )
                 .catch((error) => {
                   if (isBackgroundSuppressible(error)) return;
@@ -990,7 +1022,7 @@ export function createNavigationBridge(
 
       // Register cross-tab refresh callback with the store
       store.setCrossTabRefreshCallback(() => {
-        this.refresh();
+        this.refresh(true);
       });
 
       window.addEventListener("popstate", handlePopstate);

package/src/browser/navigation-client.ts

@@ -82,6 +82,7 @@ export function createNavigationClient(
         rewriteTarget,
         signal,
         staleRevalidation,
+        boundary,
         interceptSourceUrl,
         version,
         routerId,
@@ -114,6 +115,7 @@ export function createNavigationClient(
           segmentIds,
           emptySegments: "send",
           stale: staleRevalidation,
+          boundary,
           version,
           routerId,
           rewriteTarget,

package/src/browser/network-error-handler.ts

@@ -28,6 +28,9 @@ export function toNetworkError(
  * Render an error into the segment tree via the onUpdate subscriber so the
  * nearest error boundary catches it. Wrapped in startTransition; RenderErrorThrower
  * throws during render (async rejections do not reach boundaries on their own).
+ * Flagged inTransition like every tree handed over in a transition, so route
+ * state that arrives after it (the failed navigation's idle) waits for its
+ * commit (NavigationProvider's "anchor").
  */
 function emitErrorToBoundary(
   onUpdate: UpdateSubscriber,
@@ -43,6 +46,7 @@ function emitErrorToBoundary(
         segments: [],
         isError: true,
       },
+      inTransition: true,
     });
   });
 }

package/src/browser/partial-update.ts

@@ -14,7 +14,7 @@ export const addTransitionType: ((type: string) => void) | undefined =
   "addTransitionType" in React ? (React as any).addTransitionType : undefined;
 
 import type { RenderSegmentsOptions } from "../segment-system.js";
-import { reconcileSegments } from "./segment-reconciler.js";
+import { idsAboveBoundary, reconcileSegments } from "./segment-reconciler.js";
 import type { ReconcileActor } from "./segment-reconciler.js";
 import { Defer } from "./defer.js";
 import {
@@ -236,15 +236,28 @@ export type UpdateMode =
        * transition({ when }) sees kind "revalidate", not "replace".
        */
       refresh?: boolean;
+      /** The cross-tab refresh's held boundary (see `action`). */
+      boundary?: string;
+    }
+  | { type: "leave-intercept"; interceptSourceUrl?: string; boundary?: never }
+  | {
+      type: "stale-revalidation";
+      interceptSourceUrl?: string;
+      /** Back/Forward's held boundary (see `action`). */
+      boundary?: string;
     }
-  | { type: "leave-intercept"; interceptSourceUrl?: string }
-  | { type: "stale-revalidation"; interceptSourceUrl?: string }
   | {
       type: "action";
       interceptSourceUrl?: string;
       actionId?: string;
       /** The action's FormData and result, for transition({ when }) `action`. */
       action?: TransitionWhenActionInput;
+      /**
+       * An action's error boundary the page shows (actionBoundaryAt): the
+       * server renders above it, its cached segment stays, and the page
+       * holds only the ids above it.
+       */
+      boundary?: string;
     };
 
 /**
@@ -569,6 +582,7 @@ export function createPartialUpdater(
     const historyKeyAtStart = store.getHistoryKey();
 
     const interceptSourceUrl = mode.interceptSourceUrl;
+    const boundary = mode.boundary;
 
     let segments: string[];
     if (mode.type === "leave-intercept") {
@@ -690,6 +704,7 @@ export function createPartialUpdater(
         : store.getHistoryEntryMemory()?.rewriteTarget,
       staleRevalidation:
         mode.type === "stale-revalidation" || segments.length === 0,
+      boundary,
       version: getVersion(),
       routerId: store.getRouterId?.(),
     });
@@ -874,14 +889,14 @@ export function createPartialUpdater(
       // in place of each missing value, and this navigation fills them from
       // one fill request once it has committed the tree.
       let defers: Holes["defers"] | undefined;
-      let heldIds = matchedIds;
+      let heldIds = idsAboveBoundary(matchedIds, boundary);
       const placeholders = serverSegments.filter(isPlaceholder);
       if (placeholders.length > 0) {
         defers = armHoles(placeholders);
         // A placeholder is not held: every later request from this page
         // leaves its id out, so the server renders it.
         const deferredIds = new Set(placeholders.map((s) => s.id));
-        heldIds = matchedIds.filter((id) => !deferredIds.has(id));
+        heldIds = heldIds.filter((id) => !deferredIds.has(id));
       }
 
       const reconcile = () =>
@@ -895,7 +910,10 @@ export function createPartialUpdater(
         });
       let reconciled = reconcile();
 
-      const missing = missingIds(matchedIds, reconciled.segments);
+      // Not the ids at or below a held boundary: its loaders may never have
+      // reached the client (the route failed on its GET), and nothing renders
+      // them under the error.
+      const missing = missingIds(heldIds, reconciled.segments);
 
       if (missing.length > 0) {
         const missingCount = missing.length;
@@ -1119,6 +1137,15 @@ export function createPartialUpdater(
         }),
         ...(serverLocationState && { serverState: serverLocationState }),
       };
+      // A refetch that held an action's boundary commits only while the page
+      // on screen still shows it: a later commit there (an action's success)
+      // replaced it, and this response would put the error back.
+      if (
+        boundary &&
+        !entryOnScreen()?.includes(cachedSegs.find((s) => s.id === boundary)!)
+      ) {
+        return;
+      }
       const cachedHandleData = readCachedHandleData?.();
       const { scroll: navScroll } = tx.commit(
         heldIds,

package/src/browser/react/use-action.ts

@@ -1,13 +1,6 @@
 "use client";
 
-import {
-  useContext,
-  useState,
-  useEffect,
-  useRef,
-  useOptimistic,
-  startTransition,
-} from "react";
+import { useContext, useState, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
 import type { TrackedActionState } from "../types.js";
@@ -83,14 +76,19 @@ export type ServerActionFunction = ((...args: any[]) => Promise<any>) & {
  * Features:
  * - Tracks action lifecycle: idle → loading → streaming → idle
  * - Captures result/error locally (React handles cleanup)
- * - If multiple actions fire, tracks only the last one
+ * - If the same action fires several times, reports the latest call to
+ *   start. An earlier call that settles later changes nothing it reports;
+ *   a latest call that was aborted reports idle with nothing. One call at a
+ *   time, not one per argument: a reader filtering on `payload` cannot track
+ *   an earlier call once a later one starts.
  * - Supports selector pattern like useNavigation
  *
  * Matching behavior:
  * - **Function reference**: Uses full $$id for exact matching. This is precise
  *   and distinguishes between actions with the same name in different files.
  * - **String**: Matches by suffix (action name after #). This is convenient
- *   but may be ambiguous if multiple files export the same action name.
+ *   but may be ambiguous if multiple files export the same action name: it
+ *   follows the latest call of any action with that export name.
  *
  * @param action - Either a server action function or a string action name.
  *   - **Function**: Must be directly imported in the client component.
@@ -138,8 +136,10 @@ export function useAction<T>(
       ? getActionId(action)
       : "";
 
-  // Base state for useOptimistic
-  const [baseState, setBaseState] = useState<T | TrackedActionState>(() => {
+  // Set urgently from notifyAction's task, also while React holds a page: a
+  // transition of its own would take the held page's transition types (see
+  // useNavigation).
+  const [value, setValue] = useState<T | TrackedActionState>(() => {
     if (!ctx) {
       return selector ? selector(DEFAULT_ACTION_STATE) : DEFAULT_ACTION_STATE;
     }
@@ -149,11 +149,8 @@ export function useAction<T>(
       : ctx.eventController.getActionState(actionId);
     return selector ? selector(state) : state;
   });
-  const prevSelected = useRef(baseState);
-  prevSelected.current = baseState;
-  const [optimisticState, setOptimisticState] = useOptimistic<
-    T | TrackedActionState
-  >(null!);
+  const prevSelected = useRef(value);
+  prevSelected.current = value;
 
   // Ref keeps the latest selector for subscription callbacks without
   // re-subscribing on every render. Selector changes themselves are not
@@ -166,41 +163,20 @@ export function useAction<T>(
   useEffect(() => {
     if (!ctx) return;
 
+    const sync = (state: TrackedActionState) => {
+      const selected = selectorRef.current ? selectorRef.current(state) : state;
+      if (!shallowEqual(selected, prevSelected.current)) {
+        prevSelected.current = selected;
+        setValue(selected);
+      }
+    };
     // Sync current state for the (possibly new) actionId so that switching
     // actions on an idle page doesn't leave stale data from the old action.
-    const currentState = ctx.eventController.getActionState(actionId);
-    const currentSelected = selectorRef.current
-      ? selectorRef.current(currentState)
-      : currentState;
-    if (!shallowEqual(currentSelected, prevSelected.current)) {
-      prevSelected.current = currentSelected;
-      setBaseState(currentSelected);
-    }
-
-    // Subscribe to action-specific updates
-    const unsubscribe = ctx.eventController.subscribeToAction(
-      actionId,
-      (state) => {
-        const selectedState = selectorRef.current
-          ? selectorRef.current(state)
-          : state;
-
-        if (!shallowEqual(selectedState, prevSelected.current)) {
-          prevSelected.current = selectedState;
-          setBaseState(selectedState);
-          startTransition(() => {
-            setOptimisticState(selectedState);
-          });
-        }
-      },
-    );
-
-    return () => {
-      unsubscribe();
-    };
+    sync(ctx.eventController.getActionState(actionId));
+    return ctx.eventController.subscribeToAction(actionId, sync);
   }, [actionId]);
 
-  return (optimisticState ?? baseState) as T | TrackedActionState;
+  return value;
 }
 
 export type { TrackedActionState };