@rangojs/router 0.28.0 → 0.29.0

package/dist/types/wire-params.d.ts

@@ -19,6 +19,11 @@ export declare const WIRE: {
     readonly rewriteTarget: "_rsc_rt";
     /** A stale request: `true` (router/navigation-snapshot.ts). */
     readonly stale: "_rsc_stale";
+    /**
+     * The id of an action's error boundary on screen that a stale request
+     * holds: read only beside `stale` (router/navigation-snapshot.ts).
+     */
+    readonly boundary: "_rsc_boundary";
     /** A fill request (docs/design/prefetch-false.md): `1`. */
     readonly fill: "_rsc_fill";
     /** A loader fetch's loader id (rsc/loader-fetch.ts). */

package/dist/vite/index.js

@@ -298,6 +298,11 @@ var init_wire_params = __esm({
       rewriteTarget: "_rsc_rt",
       /** A stale request: `true` (router/navigation-snapshot.ts). */
       stale: "_rsc_stale",
+      /**
+       * The id of an action's error boundary on screen that a stale request
+       * holds: read only beside `stale` (router/navigation-snapshot.ts).
+       */
+      boundary: "_rsc_boundary",
       /** A fill request (docs/design/prefetch-false.md): `1`. */
       fill: "_rsc_fill",
       /** A loader fetch's loader id (rsc/loader-fetch.ts). */
@@ -723,6 +728,7 @@ function writePartialParams(url, init) {
     params.set(WIRE.segments, init.segmentIds.join(","));
   }
   if (init.stale) params.set(WIRE.stale, "true");
+  if (init.boundary) params.set(WIRE.boundary, init.boundary);
   if (init.version) params.set(WIRE.version, init.version);
   if (init.routerId) params.set(WIRE.routerId, init.routerId);
   if (init.rewriteTarget) params.set(WIRE.rewriteTarget, init.rewriteTarget);
@@ -5168,7 +5174,6 @@ import {
   useState as useState4,
   useEffect as useEffect6,
   useLayoutEffect as useLayoutEffect2,
-  startTransition as startTransition2,
   useRef as useRef4
 } from "react";
 
@@ -5194,14 +5199,7 @@ import { useContext as useContext11, useState as useState7, useEffect as useEffe
 var EMPTY_PARAMS = Object.freeze({});
 
 // src/browser/react/use-action.ts
-import {
-  useContext as useContext12,
-  useState as useState8,
-  useEffect as useEffect10,
-  useRef as useRef8,
-  useOptimistic as useOptimistic2,
-  startTransition as startTransition3
-} from "react";
+import { useContext as useContext12, useState as useState8, useEffect as useEffect10, useRef as useRef8 } from "react";
 
 // src/browser/event-controller.ts
 init_notify_listeners();
@@ -5275,7 +5273,7 @@ import {
   useMemo as useMemo7,
   useRef as useRef11,
   use as use4,
-  startTransition as startTransition4
+  startTransition as startTransition2
 } from "react";
 
 // src/root-error-boundary.tsx
@@ -5325,7 +5323,7 @@ import {
   useContext as useContext15,
   useEffect as useEffect15,
   useMemo as useMemo8,
-  useRef as useRef13
+  useRef as useRef12
 } from "react";
 
 // src/browser/react/use-link-status.ts
@@ -5333,10 +5331,7 @@ import {
   createContext as createContext7,
   useContext as useContext14,
   useState as useState12,
-  useEffect as useEffect14,
-  useRef as useRef12,
-  useOptimistic as useOptimistic3,
-  startTransition as startTransition5
+  useEffect as useEffect14
 } from "react";
 var LinkContext = createContext7(
   null
@@ -5544,7 +5539,7 @@ var Link = forwardRef(function Link2({
     [to, isExternal, ctx?.basename]
   );
   const configuredStrategy = prefetch ?? ctx?.defaultPrefetch ?? ENVIRONMENT_DEFAULT_PREFETCH;
-  const internalRef = useRef13(null);
+  const internalRef = useRef12(null);
   const setRef = useCallback5(
     (node) => {
       internalRef.current = node;
@@ -5556,7 +5551,7 @@ var Link = forwardRef(function Link2({
     },
     [ref]
   );
-  const stateRef = useRef13(state);
+  const stateRef = useRef12(state);
   stateRef.current = state;
   const handleClick = useCallback5(
     (e) => {
@@ -5936,6 +5931,7 @@ var DERIVED_RENDER_BARRIER_DESCRIPTOR = {
   ...RENDER_BARRIER_DESCRIPTOR,
   enumerable: false
 };
+var backgroundWork = new AsyncLocalStorage6();
 
 // src/route-definition/redirect.ts
 init_redirect_origin();
@@ -5952,7 +5948,7 @@ import {
 } from "react";
 
 // src/client-urls/navigation.ts
-import { startTransition as startTransition6 } from "react";
+import { startTransition as startTransition3 } from "react";
 
 // src/client-urls/client-root.tsx
 import { jsx as jsx11, jsxs as jsxs4 } from "react/jsx-runtime";
@@ -7146,7 +7142,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.28.0",
+  version: "0.29.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/client-urls/SKILL.md

@@ -734,8 +734,10 @@ a hard load of the target URL renders the full route.
   values during SSR (live request seeds the SSR store; on ppr routes the
   capture/resume renders seed the shell key's own sorted search — search is
   part of shell identity, so static-part reads are legal).
-  `useNavigation`/`useLinkStatus` report the canonical nav, but a reader
-  inside optimistically-swapped content (destination WITH `loading()`)
+  `useNavigation`/`useLinkStatus` report the canonical nav (while the frame
+  shows, `useNavigation()` is `state: "loading"` with `location` the
+  committed URL, even though the URL hooks already report the frame's
+  destination), but a reader inside optimistically-swapped content (destination WITH `loading()`)
   unmounts at click — put status readers in surviving chrome. Errors: wrap
   throwers in the client `ErrorBoundary`; `useFetchLoader` works unchanged
   (route-independent lane; `revalidate()` deliberately not consulted).

package/skills/hooks/SKILL.md

@@ -86,7 +86,7 @@ the one for your case.
 | `useHref()`               | Mount-aware href                                               | `(path) => string`                                                              |
 | `useMount()`              | Current include() mount path                                   | `string`                                                                        |
 | `useReverse()`            | Local reverse for imported routes                              | `(name, params?, search?) => string`                                            |
-| `useNavigation()`         | Reactive navigation state                                      | state, location, pendingUrl, isStreaming                                        |
+| `useNavigation()`         | Reactive navigation state                                      | state, location, pendingUrl, isNavigating, isStreaming                          |
 | `useRouter()`             | Stable router actions                                          | push, replace, refresh, prefetch, back, forward                                 |
 | `useSegments()`           | URL path & segment IDs                                         | path, segmentIds, location                                                      |
 | `useLinkStatus()`         | Link pending state                                             | { pending }                                                                     |

package/skills/hooks/data.md

@@ -14,7 +14,8 @@ function ProductPrice() {
 
   // data: T (guaranteed - throws if not in context)
   // isLoading: boolean (refetch/load() states + a held navigation replacing
-  //   this data — NOT the initial streamed read)
+  //   this data — NOT the initial streamed read, and NOT a server action
+  //   re-running the loader)
   // error: Error | null
 
   return <span>${data.price}</span>;
@@ -30,6 +31,12 @@ component renders, `data` is present. (On document loads a loader registered
 with `{ ssr: false }` is already settled at first paint, so its
 reads never suspend there — see `/loader`.)
 
+**`isLoading` covers navigations and `load()` only.** When a server action
+re-runs the loader (its revalidation), `isLoading` stays `false`: the action's
+own progress is `useAction()`'s `state`, or `useNavigation().state`, which is
+`"loading"` while an action runs. Read those for an action spinner and keep
+`isLoading` for "this data is being replaced by a navigation or refresh".
+
 **A held navigation flags the data it keeps on screen.** When a navigation
 keeps the current content visible while the loader re-runs (a `transition()`
 same-route nav, a same-structure search/filter nav), the reader that is still

package/skills/hooks/handle-and-actions.md

@@ -50,7 +50,7 @@ page's values over the page being left:
 | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Document load                                                                                                                              | The values the HTML was rendered from. `push(promise)` and `.defer()` are awaited during SSR, so the document ships the resolved value. On a `ppr` shell HIT that holds for the handlers' and the `ssr: false` loaders' pushes, which the shell baked; a live-lane loader's push arrives right after hydration (see `/ppr`). |
 | Navigation to a page that commits at once (a cold click that mounts new segments)                                                          | The destination's values, in the page's commit; the page's effects read them                                                                                                                                                                                                                                                 |
-| Navigation to a page React holds in a transition (`transition()`, same-route search change, fully prefetched click, a handler that awaits) | The page being left keeps its values; the destination's land in the commit right after the page, in the same task, before paint                                                                                                                                                                                              |
+| Navigation to a page React holds in a transition (`transition()`, same-route search change, fully prefetched click, a handler that awaits) | The page being left keeps its values; the destination's land right after the page's commit: without view transitions in the same task, before paint; with view transitions when the transition's `ready` resolves                                                                                                            |
 | `push(promise)` or `.defer()` on a client navigation                                                                                       | The previous value, then the new one when the promise resolves, possibly well after the page                                                                                                                                                                                                                                 |
 
 You never see a pending value, a blank, or the destination's title over the old
@@ -193,7 +193,34 @@ tracking actions called outside a `<form action={...}>` flow.
 ### useAction()
 
 Track the lifecycle of a server action, wherever on the page it was invoked.
-If the same action fires several times, the hook reports the latest call.
+If the same action fires several times, the hook reports the latest call: the
+last one to start.
+
+- When the latest call returns before an earlier one, the hook shows its
+  result. The earlier call settling afterwards changes nothing the hook
+  reports, a result or an error alike. That call still runs to its end: its
+  promise resolves or rejects for its caller, its revalidation re-renders the
+  page, and an error-boundary response replaces it.
+- A latest call that was aborted reports nothing: `idle`, with no result or
+  error. The hook does not fall back to an earlier call. The router aborts
+  calls in flight when another call's response is an error boundary, and on
+  Back/Forward into or out of an intercept.
+- `useNavigation()` stays `loading` while any call runs.
+
+Which calls count as the same action depends on what you pass:
+
+- A function, or a full id (`"src/actions/cart.ts#addToCart"`): that action
+  only.
+- A string name (`"addToCart"`): every action with that export name, in any
+  `"use server"` file. The hook follows the latest call among all of them.
+
+The hook tracks one call at a time, not one per argument. Every
+`AddToCartButton` below reads the same `useAction(addToCart)`, so each shows
+the latest call from any button, whatever its `productId`. A reader that
+filters on `payload` (`payload?.[0] === productId`) cannot track an earlier
+call once a later one starts: from then on the hook reports the later call
+only. For per-call state, keep it with the call: `useActionState` or
+`useTransition` in the component that makes it.
 
 ```tsx
 "use client";
@@ -231,6 +258,10 @@ const isLoading = useAction(addToCart, (s) => s.state === "loading");
 const isAdding = useAction("addToCart", (s) => s.state === "loading");
 ```
 
+Each state change commits urgently, so it shows at once, also while React
+holds a navigation's page. It starts no transition of its own, so it never
+takes that page's transition types.
+
 Pass an action imported directly into the client component, or its export
 name as a string. An action received as a prop from a server component has
 lost the metadata `useAction` needs and throws; use the string form there.

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. `usePathname()`
+can read the path of the page being left on that page's first screen, until
+React finishes the render of the page it held.
+
+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

@@ -125,6 +125,14 @@ click or `router.push()`.
 | `router.push(url, { revalidate: false })`         | at once: nothing is fetched and the page stays                             |
 | 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 +150,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