@rangojs/router 0.28.0 → 0.30.0

package/skills/hooks/navigation.md

@@ -12,10 +12,11 @@ function NavIndicator() {
   const nav = useNavigation();
 
   // State properties
-  nav.state; // 'idle' | 'loading'
-  nav.isStreaming; // boolean — RSC data is still streaming
-  nav.location; // Current URL
-  nav.pendingUrl; // Target URL during navigation (or null)
+  nav.state; // 'idle' | 'loading' — loading during a navigation AND a server action
+  nav.isNavigating; // boolean — a navigation is in flight (false during an action)
+  nav.isStreaming; // boolean — RSC data is still streaming (navigation or action)
+  nav.location; // The page on screen, until the next page shows
+  nav.pendingUrl; // The page being fetched (or null)
 
   return nav.state === "loading" ? <Spinner /> : null;
 }
@@ -27,6 +28,22 @@ function IsLoading() {
 }
 ```
 
+#### Navigation versus server action
+
+`state` is `"loading"` while a navigation is in flight and also while a server
+action runs. That is deliberate: something on this screen is loading, so a
+spinner or a progress bar has a signal for an action too. When a bar should
+show for navigations only, read `isNavigating`: true from the start of a
+navigation until its commit, false during an action (where `state` is still
+`"loading"`). `isStreaming` covers the action's response as well as a
+navigation's.
+
+| Event           | `state`     | `isNavigating` | `isStreaming`                |
+| --------------- | ----------- | -------------- | ---------------------------- |
+| a navigation    | `"loading"` | `true`         | true until the stream ends   |
+| a server action | `"loading"` | `false`        | true until the response ends |
+| neither         | `"idle"`    | `false`        | `false`                      |
+
 #### Pending UI, Back/Forward included
 
 A link click, `router.push()` and a Back/Forward that has to fetch its entry
@@ -40,19 +57,49 @@ on screen:
 | the page has not fully arrived yet             | `isStreaming`: true from the start of the request until the stream ends             |
 | which page is on screen while the request runs | `location`, or `usePathname()` / `useSearchParams()` (see [`./urls.md`](./urls.md)) |
 
-`pendingUrl` covers the network wait. Once the response has arrived a loader
+`pendingUrl` covers the network wait, and `useLinkStatus()` covers more: a
+link's `pending` stays `true` after `pendingUrl` turns `null`, while the
+response streams and React holds the page being left, until the destination
+commits (see [useLinkStatus()](#uselinkstatus)). For a spinner on the clicked
+link, read `useLinkStatus()`; `pendingUrl` names the URL only while the
+request is out.
+
+Once the response has arrived a loader
 may still be streaming, and React keeps the page being left on screen where a
 navigation holds its content (a same-route change, a `transition()` route,
 with or without a view transition). `state` stays `"loading"` through that
-part: for a navigation on its own, `"idle"` commits in the same commit as the
-destination's `useSearchParams()`, `usePathname()` and `useParams()`, so a
-component that reads both does not see the navigation finished on the URL it
-is leaving. A server action, or another navigation started and aborted,
-while React holds that page can still bring `"idle"` with the URL being left.
+part: `"idle"` commits with the destination's `useSearchParams()`,
+`usePathname()` and `useParams()`, so a component that reads both does not
+see the navigation finished on the URL it is leaving. That holds when a
+server action settles, or a newer navigation ends with no page (an external
+redirect, a reload), while React holds the page: `"idle"` waits for the page.
+A newer navigation that fails shows the error screen, and `"idle"` arrives
+with it. A newer click shows at once (`"loading"`, its `pendingUrl`), also
+while an action is in flight. After a server action, `"idle"` arrives with
+the action's revalidated content.
 `isStreaming` can outlast that commit (a loader still streaming below a
 boundary that already showed), so use it for a progress indicator that should
 last until the new page is complete.
 
+While React holds a page, every field follows one rule, whatever the reader
+reads (a selector, the full state): work that starts shows at once
+(`"loading"`, `isStreaming` and `isNavigating` turning `true`, a newer click's
+`pendingUrl`), and what settles waits for the page (`"idle"`, `false`, a
+`null` `pendingUrl`). So a progress bar that reads
+`useNavigation((n) => n.isStreaming)` stays up until the held page shows, even
+when the response stream ended earlier, and agrees with every other
+`useNavigation()` reader on the screen. A page that ends the hold urgently (a
+Back to a page without `transition()`, a link with `transition={false}`)
+shows with its own values in every `useNavigation()` reader, and with its URL
+in `usePathname()`, `useParams()`, `useSearchParams()` and `useSegments()`,
+also when it is the URL React was holding.
+
+The rule holds for readers mounted before the page was handed to React. A
+reader that mounts while the page is held (a menu opened during the wait)
+never saw the hand-over and reads the live values, the destination's `idle`
+and location, until the page shows. This is by design (#1046): its first
+render has no page of its own to wait for.
+
 On Back/Forward the address bar changes at once, before any of this: during
 the wait `window.location` is the entry being fetched, the same URL as
 `pendingUrl`, and `location` is the page on screen. A Back/Forward served
@@ -60,8 +107,28 @@ from the client's history cache restores its page in one commit and reports
 no pending state.
 
 `location` moves in that commit too. A component that first mounts while
-React holds the page being left reads the destination's `location` and URL
-hooks (issue #1046).
+React holds the page being left (a dropdown opened on the old page, a lazy
+component or a `<Suspense>` there that resolves during the hold) reads the
+destination's `state`, `location` and URL hooks, because each hook seeds its
+first value from the router's live state (issue #1046; by design). A menu
+opened while a click's page is held therefore highlights the destination
+link. Components already mounted keep the page on screen's values until the
+destination commits.
+
+A second click while React holds the first click's page works the same way:
+`"loading"` and the second click's `pendingUrl` show at once, and `location`
+stays the page on screen. It moves to the first click's page only if that
+page shows before the second one arrives; if the second page replaces it
+first, the first page never shows and its URL is never `location`.
+
+**One exception: inside an optimistic `clientUrls()` frame.** When a
+cross-route navigation shows the destination's `loading()` frame at the click,
+`usePathname()`, `useSearchParams()` and `useParams()` report the frame's
+destination (see [`./urls.md`](./urls.md)), but `useNavigation()` reports the
+real navigation: `state` is `"loading"` and `location` is the committed URL,
+the page that is still the router's. So `location` is "which page is
+committed", not always "which page the eye sees", and a status reader should
+sit in chrome that survives the swap (see `/client-urls`).
 
 ### useRouter()
 
@@ -187,13 +254,17 @@ const segments = useSegments();
 const part = segments.path[depth];
 ```
 
-Like `useHandle`, it commits with the page: while React holds the page being
-left, `useSegments()` keeps that page's path and segments.
+While React holds the page being left, `useSegments()` keeps that page's
+values. The new page's `path` and `location` commit with it, so its effects
+read them; `segmentIds` come with the page's handle data and can land right
+after its commit, as handle values do (see
+[handle-and-actions](./handle-and-actions.md#when-handle-values-change-by-design)).
 
 ### useLinkStatus()
 
 Track pending state inside a Link component. `pending` is `true` while a
-navigation to this link's `to` is in flight:
+navigation to the link's `to` is in flight, until the page it brings
+commits:
 
 ```tsx
 "use client";
@@ -210,3 +281,38 @@ function LoadingIndicator() {
   <LoadingIndicator />
 </Link>;
 ```
+
+The spinner ends in the commit that shows the destination: its `loading()`
+skeleton without `transition()`, or the page itself under `transition()`,
+where React holds the page being left until the new one is ready. Through a
+server redirect, the clicked link stays pending until the target page
+commits. A newer navigation and an abort end it at once, outside the narrow
+case below. A failure ends it with the error: a route's `errorBoundary()` commits like a page, and a
+failure the router shows at its root (a network error, a response it cannot
+read) replaces the page, links included.
+
+`pending` follows the same rule as `useNavigation()`: a change commits in the
+lane of the notification that carries it. The click's notification goes out
+a task after the click and commits urgently, so the spinner shows at once,
+and an abort or a newer click ends it the same way. The hook starts no
+transition of its own, so it never takes the page's transition types. A
+fully prefetched click whose page commits before that task shows no pending
+state: its page is already there.
+
+One narrow case is a known trade: when another flow's commit (a server
+action's) is handed to React in the same task as the click, before the
+click's notification goes out, the notification commits with that commit.
+If React holds it, the spinner, and `useNavigation()`'s `loading`, show when
+it lands; a newer click or an abort delivered that way ends an earlier
+spinner when it lands too.
+
+The two hooks answer different questions. `pending` is this link's
+navigation; `useNavigation()` is the router's, and its `"idle"` waits for any
+page or tree React holds. So a link whose navigation is aborted while React
+holds another flow's commit reads `pending: false` while `state` stays
+`"loading"` until that commit lands: the frame any link that is not the
+destination reads during a navigation.
+
+`pending` lasts longer than `useNavigation().pendingUrl`, which turns `null`
+when the response arrives. While the response streams, a link reads `pending`
+and `pendingUrl` is `null`.

package/skills/hooks/state.md

@@ -132,10 +132,12 @@ The URL hooks follow the same rule for a component that is mounted across the
 navigation: on back/forward too, `usePathname()` and `useSearchParams()`
 change with the page, not at the `popstate` event (see
 [`./urls.md`](./urls.md), "When the URL hooks change"). One difference
-remains (issue #1046): a component that first mounts in the page being left,
-after the response arrived and while React still holds the destination, reads
-its own entry's location state from `useLocationState` and the destination's
-URL and params from `usePathname()`, `useSearchParams()` and `useParams()`.
+is by design (issue #1046): a component that first mounts in the page being
+left, after the response arrived and while React still holds the destination,
+reads its own entry's location state from `useLocationState` and the
+destination's URL and params from `usePathname()`, `useSearchParams()` and
+`useParams()`. Components already on screen keep the page on screen's values
+until the destination commits.
 
 ### State on router.push() / router.replace()
 

package/skills/hooks/urls.md

@@ -123,8 +123,17 @@ click or `router.push()`.
 | Back/Forward, entry fetched again                 | when the fetched page commits; until then the page being left is on screen |
 | a Back/Forward whose fetch fails                  | with the error boundary: they report the entry the browser is on           |
 | `router.push(url, { revalidate: false })`         | at once: nothing is fetched and the page stays                             |
+| `transition={false}` over a held page             | with that page's first screen, also on the URL React was holding           |
 | inside an optimistic `clientUrls()` destination   | at the click, for that branch only (see `/client-urls`)                    |
 
+**A newer click that fails while a page is held.** Click a link, and while
+React holds the page being left (a `transition()` route, or a loader still
+streaming) click another whose request fails: the root error screen replaces
+the app, and the held page never shows. Under that screen `useNavigation()`
+reads `"idle"` with the first click's `location`, and no hook reader is on
+screen to see it. The hooks are not wrong, there is simply nobody left to read
+them; the error boundary's reset brings the app back.
+
 **The hooks can disagree with the address bar.** On Back/Forward the browser
 changes the URL and `history.state` before it tells the router. When the
 entry has to be fetched (it left the client's history cache, or the cache was
@@ -142,11 +151,14 @@ whole wait. A Back/Forward served from the history cache has no wait.
 `setSearchParams((prev) => ...)` builds on the same location: called during a
 pending Back/Forward, `prev` is the search of the page on screen.
 
-One gap (issue #1046): a component that first mounts in the page being left
-after the navigation's response has arrived, while React still holds the
-destination behind a loader or a `transition()`, reads the destination's URL
-and params from these hooks. Components that were already mounted are not
-affected. It applies to a push and to Back/Forward alike.
+A component that first mounts in the page being left after the navigation's
+response has arrived, while React still holds the destination behind a loader
+or a `transition()`, reads the destination's URL and params from these hooks
+(issue #1046; by design). Every router hook seeds its first value from the
+router's live state, so a menu opened while a click's page is held highlights
+the destination link. Components already on screen keep the values of the
+page on screen until the destination commits, and then every hook agrees. It
+applies to a push and to Back/Forward alike.
 
 ### useHref()
 

package/skills/intercept/SKILL.md

@@ -68,6 +68,7 @@ export const urlpatterns = urls(({ path, layout, intercept, loader, loading }) =
 | ----------------------------------------------------- | ---------------------------------------------------- |
 | Click link `/shop/product/abc`                        | `<ProductModal />` in `@modal`, background preserved |
 | Direct URL `/shop/product/abc`, or a reload           | Full `<ProductPage />` page                          |
+| `router.refresh()`, or another tab's action           | Full `<ProductPage />` page, as a reload             |
 | Back from the open intercept                          | The intercept closes; the source page stays          |
 | Back/Forward onto the intercept's entry               | The intercept over its source page                   |
 | The same, uncached, from a page other than the source | Full `<ProductPage />` page, as a document load      |
@@ -81,6 +82,11 @@ state like any document load, and the entry is a full page from then on. In
 dev, an edit that changes the app version clears the history cache, so the
 next Back/Forward onto an intercept entry takes that path.
 
+An intercept is a page in the middle of a navigation. A refresh reloads its
+URL, so `router.refresh()` with the intercept open, and the refresh another
+tab's action triggers, render the full page, as a document load does. The
+entry is a full page from then on.
+
 A server action on `/shop` that calls `redirect("/shop/product/abc")` opens the
 intercept too, and so does a link from `/shop` to a route that redirects
 there. The page under it is the browser's copy, as on a link click: it

package/skills/observability/SKILL.md

@@ -277,6 +277,36 @@ Events include `request.start/end/error`, `loader.start/end/error`,
 `handler.error`, `cache.decision`, `revalidation.decision`, `request.timeout`,
 and `request.origin-rejected`.
 
+## Errors reported to onError
+
+`createRouter({ onError })` sees every server error, including errors from
+work no visitor waits on. A stale `cache()` record, document cache entry, PPR
+shell, `"use cache"` function or cached loader is served stale and refreshed
+beside the request. That refresh's error carries `background: true`, with the
+starting request's `request` and `url`, and `handledByBoundary: false`: the
+failed render is not stored, so no one sees its fallback. The stale entry
+keeps serving.
+
+```typescript
+const router = createRouter({
+  onError: ({ error, phase, background, routeKey, duration }) => {
+    errorTracker.capture(error, {
+      // A failed refresh is not a failed page view.
+      level: background ? "warning" : "error",
+      tags: { phase, route: routeKey },
+      extra: { duration },
+    });
+  },
+});
+```
+
+`duration` is the time from the request's start to the error; for a
+`background` error, from the start of the request that started the refresh.
+`segmentId` and `segmentType` name the segment that threw: an intercept's or
+a parallel slot's error reports the slot (`segmentType: "parallel"`), an
+orphan layout's error the orphan layout, even when the owning layout's
+boundary renders the fallback.
+
 ## Debugging revalidation and stale data
 
 When stale UI or unexpected partial renders are the question, use all three

package/skills/server-actions/SKILL.md

@@ -569,6 +569,10 @@ A few details:
   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.
+- If a later action on that page threw into its `errorBoundary()`, the
+  revalidation keeps the boundary on screen: everything above it re-runs,
+  nothing at or below it. Under the router's default boundary at the root,
+  nothing runs. A link from the page re-runs what is at or below the boundary.
 - 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.
 
@@ -710,7 +714,10 @@ decides, so a cart count shows what the action wrote before it threw. A
 route's `errorBoundary()` replaces the route: its handler and loaders do not
 run. A layout's `errorBoundary()` replaces what the layout renders in its
 outlet: the layout's own loaders, slots and orphan layouts revalidate as on a
-success, and nothing inside the outlet runs. An action sent from an intercept
+success, and nothing inside the outlet runs. A link from the page re-runs
+what the boundary replaced and everything under it; under the router's
+default boundary at the root, the whole page. Back to the page later
+restores it and revalidates it, which replaces the boundary with the route. An action sent from an intercept
 gets the boundary alone.
 
 ```typescript

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)    | `await router.navigate(...)` shows its page, with or without `act()`. A `<Link>` click goes inside `await act(async () => { ... })`: `fireEvent`'s synchronous `act()` drops React's retry of the held page.         |
+| 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).
  *