@rangojs/router 0.27.0 → 0.29.0

package/package.json

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

package/skills/cache-guide/SKILL.md

@@ -320,11 +320,14 @@ domains, and the router id keeps two routers on one store apart when both
 serve the same host and path (see `/host-router`, "Shared cache store"); the search part is sorted, excludes the router's internal params, and
 honors `createRouter({ cache: { searchParams } })`.
 
-A custom `key` function replaces the whole default key (e.g., to key by user role
-or locale); it also bypasses the store's `keyGenerator` and the search-param
-filter. It runs once per request and may read `cookies()`. Its result is
-stored namespaced (`key:` plus its URI encoding), so no value it returns, raw
-request input included, names another route's record. A nested `cache()`
+A custom `key` function replaces the URL part of the default key (e.g., to
+key by user role or locale), not the request type: document loads, client
+navigations and intercept navigations still keep their own records, and the
+key decides which requests of one type share a record. It also bypasses the
+store's `keyGenerator` and the search-param filter. It runs once per request
+and may read `cookies()`. Its result is stored namespaced (`key:` plus its URI
+encoding, then the request type), so no value it returns, raw request input
+included, names another route's record. A nested `cache()`
 keys its records within the enclosing `key()` partition (`/caching` → "Keys
 nest"). Normalize the result to the values you serve: each distinct value is
 a record. On a `ppr` route, `key()` (and a store `keyGenerator` that returns

package/skills/caching/SKILL.md

@@ -102,7 +102,9 @@ tainted objects" below).
 
 Handle pushes follow the same split. Handler pushes (`ctx.use(Meta)`,
 `ctx.use(Breadcrumbs)`, custom handles) are stored with the segments and
-replayed on a hit. Pushes from a `loader()` body are not stored: the loader
+replayed on a hit. On a navigation the hit replays them only for the segments
+it sends: a layout the browser keeps keeps its values on screen, as on an
+uncached navigation. Pushes from a `loader()` body are not stored: the loader
 re-runs on the hit and pushes again, so each value appears once. A loader that
 runs only because a cached handler awaited it with `ctx.use(Loader)` does not
 re-run on a hit, so its pushes are stored with the handler's.
@@ -154,7 +156,7 @@ cache(
     swr: 300, // seconds a stale entry is served while it refreshes.
     //           Default: store.defaults.swr, else no SWR window
     tags: ["blog"], // or (ctx) => string[]; see "Tag-Based Invalidation"
-    key: (ctx) => `blog:${ctx.pathname}`, // replaces the default key entirely
+    key: (ctx) => `blog:${ctx.pathname}`, // replaces the URL part of the default key
     condition: (ctx) => !ctx.request.headers.has("x-preview"), // false = bypass
     store: blogStore, // per-boundary store; see "Custom Cache Store"
   },
@@ -164,15 +166,26 @@ cache(
 );
 ```
 
-- **Default key**: `{doc|partial|intercept}:{routerId}@{host}{pathname}[:params][?search]`
-  — document requests, client navigations, and intercept navigations are cached
-  separately, and so are two routers that share a store (see `/host-router`,
-  "Shared cache store"). The search part honors `cache.searchParams` (below).
-- **`key`** is a full override: it bypasses the default key, the store's
-  `keyGenerator`, and the search-param filter. The result is stored
-  namespaced (`key:` plus its URI encoding), so whatever it returns, request
-  input included, never names another route's default-keyed record or a
-  nested partition's. A nested `cache()` keys its records within that
+- **Default key**: `{doc|partial|intercept:<intercept>}:{routerId}@{host}{pathname}[:params][?search]`
+  — under this key, document requests, client navigations, and intercept
+  navigations are cached separately, each intercept that targets the route
+  apart (`<intercept>` names the one the navigation selected), and so are two
+  routers that share a store (see `/host-router`, "Shared cache store"). The
+  search part honors `cache.searchParams` (below).
+- **`key`** replaces the URL part of the default key (host, path, params,
+  search): it bypasses those, the store's `keyGenerator`, and the
+  search-param filter. The request kind stays: document requests, client
+  navigations and each intercept navigation keep their own record under one
+  `key()` result, so `key()` decides which requests of one kind share a
+  record (a `key()` that ignores `:id` shares one document record across
+  ids), never that a document request reads a navigation's record (which
+  keeps the fallback of a `loading(..., { ssr: false })` that a document
+  leaves out) or an intercept's. The
+  result is stored namespaced (`key:` plus its URI encoding, then the kind:
+  `tier:gold` is `key:tier%3Agold|doc` for a document request and
+  `key:tier%3Agold|partial` for a navigation), so whatever it returns,
+  request input included, never names another route's default-keyed record
+  or a nested partition's. A nested `cache()` keys its records within that
   partition (see "Keys nest" under "Nested Cache Boundaries"). On a `ppr`
   route the same key (or, without one, the store's `keyGenerator`)
   partitions the PPR shell: each partition captures and serves its own shell
@@ -532,7 +545,7 @@ const router = createRouter({
   baked-shell manifest gate (a URL whose only params are excluded ones now
   matches the prerendered shell), and `"use cache"` ctx key normalization.
 - **`cache({ key })` override wins**: a custom key bypasses the filter along
-  with the rest of default key generation.
+  with the rest of the default key's URL part.
 - **The footgun**: excluding a param promises the rendered output does not
   depend on it. If it does, the first variant is cached and served to everyone.
   That is why the default is `"all"`.
@@ -725,7 +738,9 @@ default, shared by every router on the host with that prefix; `HttpOnly`,
 `SameSite=Lax`, `Path=/`, `Secure` on https, `Max-Age` 11 s with KV and 3 s
 without at the defaults: the longest memo staleness plus 1 s). It is strictly
 functional: its value is `1`, it identifies no one, and it only sends that
-browser's reads past the memos. The same user's requests that carry it skip
+browser's reads past the memos. A stale entry's background refresh (`cache()`,
+`"use cache"`, a cached loader, the document cache) sets none: no visitor made
+that invalidation. The same user's requests that carry it skip
 both memos on every isolate, so a mutating user never sees a memoized shell or
 marker from before their write. What they read past the memos is the store's
 own consistency. `VercelCacheStore`: `expireTag` is global (about 300 ms), so
@@ -1084,7 +1099,8 @@ cache({ ttl: 300, key: (ctx) => `tier:${tier(ctx)}` }, () => [
       path("/faq", FaqPage, { name: "faq" }),
     ]),
 
-    // Its own key() composes with the outer one ("key:tier%3Agold|key:v%3Ab")
+    // Its own key() composes with the outer one, then the request kind
+    // ("key:tier%3Agold|key:v%3Ab|doc")
     cache(
       { ttl: 60, key: (ctx) => `v:${ctx.searchParams.get("v") ?? "a"}` },
       () => [path("/plans", PlansPage, { name: "plans" })],
@@ -1099,10 +1115,10 @@ results first, outermost first:
 
 | Boundary the route sits in                    | Record key                                                                                                                                                   |
 | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| a single keyed `cache()`                      | Its `key()` result, namespaced (`tier:gold` is stored as `key:tier%3Agold`)                                                                                  |
+| a single keyed `cache()`                      | Its `key()` result, namespaced, then the request kind (`tier:gold` is stored as `key:tier%3Agold\|doc` for a document request)                               |
 | `cache({ ttl })`, no `key`, under a keyed one | The chain's `key()` results, then this boundary's default key (its store's `keyGenerator` result, else the default key), encoded                             |
-| `cache({ key })` under a keyed one            | The chain's `key()` results                                                                                                                                  |
-| deeper nesting                                | Composes the same way; only the innermost boundary's missing `key` adds its default key                                                                      |
+| `cache({ key })` under a keyed one            | The chain's `key()` results, then the request kind                                                                                                           |
+| deeper nesting                                | Composes the same way; the innermost boundary adds its default key without a `key` of its own, its request kind with one                                     |
 | under a `cache({ store })` on another store   | Also that store's `keyGenerator` result, one part per store: empty for a store that returns the default key while another's differs, none when all return it |
 | `cache(false)`                                | No caching, as before; a `cache()` re-enabled below it stays in the partition                                                                                |
 | no `key` anywhere                             | The default key, or the store's `keyGenerator` result, as before                                                                                             |
@@ -1134,7 +1150,10 @@ results first, outermost first:
   empty result there fails key resolution, so the request renders uncached,
   and the router warns once naming the store. On the same store the inner
   boundary's own default key already carries it (or its own `key()`
-  overrides it).
+  overrides it). Keep the default key in the result
+  (`` `${locale}:${defaultKey}` ``): its prefix is the request kind, and a
+  result without it gives a document request, a navigation and each
+  intercept navigation one record.
 - A response route's entry (`path.json()` and the other response routes) is
   keyed the same way, behind a `response:` prefix. A `ppr` route's shell is
   partitioned by the chain's `key()` results, namespaced the same way, since

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/document-cache/SKILL.md

@@ -161,6 +161,16 @@ short-circuits the middleware's downstream pipeline; global middleware that
 wraps it can still run. Route middleware, handlers, and loaders below it do not.
 An external CDN hit is different: the function never runs at all.
 
+The background revalidation re-runs that downstream pipeline for the stale
+entry. Its cookies, and the headers its route handlers and the middleware
+after the cache write, go on its own response, never on the visitor's `STALE`
+response; middleware ahead of the cache gets the `STALE` response from
+`next()`, and its writes after `next()` land there. It
+starts from what middleware ahead of the cache wrote to the response before
+`next()`, as a `MISS` does, and its response is stored by the rules below:
+its headers are kept, and a cookie it sets keeps the refreshed page out of the
+cache.
+
 ## Cache Status Header
 
 Response includes `x-document-cache-status`:
@@ -215,7 +225,9 @@ suffixes are still appended.
   everyone). That includes a response whose request called
   `updateTag()`/`revalidateTag()` on a store that keeps per-isolate memos
   (`CFCacheStore`, `VercelCacheStore`): it carries the fresh-reads cookie
-  (`rango-state-fresh` by default), so it is not stored.
+  (`rango-state-fresh` by default), so it is not stored. A stale entry's
+  background re-run sets no fresh-reads cookie (no visitor made that
+  invalidation), so its invalidation does not keep the refreshed page out.
 - Non-200 responses
 - A 200 whose render reported an error: a component that threw after the
   response started streaming, such as an async server component whose fetch

package/skills/handler-use/SKILL.md

@@ -368,7 +368,7 @@ Per-slot merge order is **handler.use → shared use → slot-local use**. Slot-
 
 Other things to keep in mind about `loading()`:
 
-- Any `loading()` (regardless of source) makes the segment a streaming unit. A handler that includes `loading()` in its `.use` opts every mount site into streaming by default. To opt back out, pass `loading(false)` at the mount site (`loading === false` handling in [segment-resolution/fresh.ts](../../src/router/segment-resolution/fresh.ts)) — use the slot descriptor form for parallel slots so the opt-out doesn't broadcast.
+- Any `loading()` (regardless of source) makes the segment a streaming unit. A handler that includes `loading()` in its `.use` opts every mount site into streaming by default. To opt back out, pass `loading(false)` at the mount site (`loading === false` handling in [segment-resolution/revalidation.ts](../../src/router/segment-resolution/revalidation.ts)) — use the slot descriptor form for parallel slots so the opt-out doesn't broadcast.
 
 Rule of thumb: only put `loading()` in `handler.use` if you genuinely want every mount site to stream by default. Use the slot descriptor's `use` for any per-slot intent at a `parallel()` call.
 

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
@@ -370,9 +376,14 @@ below), and `cache()` onto the target route.
 
 To cache a modal, put `cache()` on the target route (or a layout above it).
 An intercept navigation is cached under that scope with its own `intercept:`
-key, so it never collides with the full-page render of the same URL. For
-finer control, use `"use cache"` in the intercept handler, or cache the
-intercept's loader: `loader(ProductLoader, () => [cache()])`.
+key, so it never collides with the full-page render of the same URL. The key
+names the intercept the navigation selected, so two intercepts that target one
+route with different `when()` conditions each keep their own record. Both
+hold under a `cache({ key })` too: the `key()` replaces the URL part of the
+key, never the request kind, so a document request and a plain navigation
+never read an intercept's record (see `/caching`). For finer control, use
+`"use cache"` in the intercept handler, or cache the intercept's loader:
+`loader(ProductLoader, () => [cache()])`.
 
 ## Errors in an Intercept
 
@@ -463,7 +474,9 @@ contract and direction-aware examples.
 ## Interaction with Prerender
 
 When the target route of an intercept uses `Prerender`, the intercept handler is
-also resolved at build time and stored alongside the main pre-rendered segments.
+also resolved at build time and stored in an intercept variant next to the
+route's own pre-rendered page. The variant holds what an intercept navigation
+renders: the layouts above the route and the intercept, not the route's page.
 This means intercept navigations to pre-rendered routes are served from the
 prerender store without executing handler code at runtime.
 
@@ -496,13 +509,16 @@ Build-time behavior:
 - The intercept handler (`<ProductModal />`) is resolved with BuildContext
 - Result is stored under the key `"detail/paramHash/i"` (intercept variant)
 - `when` config conditions are skipped at build time (all intercepts pre-rendered unconditionally)
-- `when` is still evaluated at runtime by the intercept-resolution middleware
+- `when` is still evaluated at runtime by the intercept-resolution middleware,
+  and a navigation shows only the intercept it selected
+- Two intercepts on one layout that fill the same slot are not pre-rendered:
+  they render live
 
 Runtime behavior:
 
-- Intercept navigation: prerender store serves the `/i` variant (frozen handler + fresh loaders)
+- Intercept navigation: prerender store serves the `/i` variant (frozen handler + fresh loaders). A layout the client holds (`ShopLayout`) stays as it is on screen, as on a live intercept, unless its `revalidate()` asks for it
 - Direct navigation: prerender store serves the main variant (full page)
-- If no intercept prerender entry exists, falls through to live intercept resolution
+- If no intercept prerender entry exists, or it lacks the selected intercept, falls through to live intercept resolution
 
 Loaders inside the intercept always run fresh at request time, same as regular
 pre-rendered routes.

package/skills/middleware/SKILL.md

@@ -319,6 +319,24 @@ export const timing: Middleware = async (ctx, next) => {
 };
 ```
 
+A middleware may answer without waiting for its `next()`, as a timeout
+fallback does. The middleware ahead then see its `Response` after `next()`
+and write on it. The abandoned render keeps running and builds its own
+response, which nothing serves.
+
+```typescript
+export const renderTimeout: Middleware = (ctx, next) =>
+  Promise.race([
+    next(),
+    new Promise<Response>((resolve) =>
+      setTimeout(
+        () => resolve(new Response("Try again", { status: 503 })),
+        2000,
+      ),
+    ),
+  ]);
+```
+
 ### Typed context variables in middleware
 
 Use `createVar<T>()` for type-safe data sharing between middleware and handlers: