@rangojs/router 0.28.0 → 0.30.0

package/dist/types/testing/render-route.d.ts

@@ -26,24 +26,30 @@
  *   - navigate() drives the navigation lifecycle as a click does:
  *     useNavigation() reads loading from the call and idle with the commit,
  *     and useLinkStatus().pending is true for a link to the destination until
- *     the commit is handed to React. A `transition` spec plus a pending
+ *     the commit, which React holds with it. A `transition` spec plus a pending
  *     Promise seeded via navigate(url, { loaders }) commits through
  *     production's commitInTransition (browser/partial-update.ts), which React
  *     holds: useNavigation() stays loading and the held reader's
  *     useLoader().isLoading reads true until the data lands. Without
  *     `transition` the commit is urgent (production's same-structure hold is
- *     not modeled). useAction().state stays idle: no action runs.
+ *     not modeled). navigate(url, { streamUntil }) gives the navigation a
+ *     response stream that stays open past the commit (isStreaming).
+ *     useAction().state stays idle: no action runs.
  *   - A spec's transition({ when }) decides every commit with production's
  *     browser decision: navigate() and useRouter().push model kind "push",
- *     useRouter().replace kind "replace", refresh() kind "revalidate".
- *     Back/forward, action and optimistic clientUrls() swap decisions are
- *     e2e territory.
+ *     useRouter().replace kind "replace", refresh() kind "revalidate", and a
+ *     back/forward that restores a page kind "pop". Action and optimistic
+ *     clientUrls() swap decisions are e2e territory.
  *   - Location state reaches readers the way it does in production:
  *     NavigationProvider holds the committed entry's state next to the
  *     payload, so a navigation whose loader the test holds keeps the entry
  *     being left on screen with its own state. A `popstate` event is a
- *     back/forward onto the entry history.state holds; the tree has one
- *     location, so no page is restored with it. A server action's state, a
+ *     back/forward onto the entry history.state holds. When it is the
+ *     mounted entry or one a navigate() wrote, history still holds the state
+ *     written there, and another page is on screen, its page is restored
+ *     from the history cache, with the handle values it had, as production's
+ *     restore is; otherwise the tree keeps its location. A stale entry's
+ *     revalidation, a restore that fetches, a server action's state, a
  *     redirect's and an intercept's are e2e territory.
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
@@ -361,8 +367,37 @@ export interface TestRouterHandle {
      * `handles`). They arrive on the response's handle stream, so `useHandle`
      * readers take them with the page's commit: while React holds the page,
      * readers keep the values of the page being left.
+     *
+     * `options.streamUntil` gives the navigation a response stream, as a real
+     * response has: it opens in a task after the call, before the commit (the
+     * response arrives, and `useNavigation().pendingUrl` clears), and stays open
+     * until the promise settles (a page that streams a tail past its commit:
+     * `isStreaming` reads true until then). Without it the navigation has no
+     * stream. A navigation that a newer one or a back/forward aborts before its
+     * response arrives opens none and commits nothing; one aborted after its
+     * response arrived stops counting as streaming at the abort, as in
+     * production, where its response streams on and is ignored.
+     *
+     * @example
+     * const tail = deferred();
+     * await router.navigate("/products/2", { streamUntil: tail.promise });
+     * // useNavigation(): idle, isStreaming true
+     * await act(async () => tail.resolve());
+     * // useNavigation(): idle, isStreaming false
+     *
+     * A navigation started while React holds a page shows its page once the
+     * call resolves, with or without act(). A `<Link>` click over a held page
+     * still goes inside `await act(async () => ...)` (docs/testing.md).
+     *
+     * @example
+     * await router.navigate("/products/2", { loaders: [[ProductLoader, next]] });
+     * // React holds /products/2
+     * await router.navigate("/products/3", { transition: false });
+     * // /products/3 is on screen
      */
-    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders" | "handles"> & Pick<NavigateOptions, "state" | "replace" | "transition">): Promise<void>;
+    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders" | "handles"> & Pick<NavigateOptions, "state" | "replace" | "transition"> & {
+        streamUntil?: Promise<unknown>;
+    }): Promise<void>;
     /**
      * Re-render the current location, as router.refresh() does: a spec's
      * transition({ when }) decides it with kind "revalidate" (`to` is `from`).

package/dist/types/testing/serve-shell-request.d.ts

@@ -81,7 +81,13 @@ export interface ServeShellRequestOptions<TEnv = any> {
      * and segments take an action's revalidation defaults; it renders live, as
      * an action does, so neither the route cache nor the document cache answers
      * or stores it, and a `ppr` route's `replayStatus` is
-     * `{ outcome: "BYPASS", reason: "stale" }`.
+     * `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error
+     * segment of a thrown action's boundary the page at `from` shows
+     * (`_rsc_boundary`), as the follow-up 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`.
      */
     partial?: true | {
         from?: string;
@@ -91,6 +97,7 @@ export interface ServeShellRequestOptions<TEnv = any> {
         fill?: boolean;
         interceptSource?: string;
         stale?: boolean;
+        boundary?: string;
     };
     /**
      * POST this form as a submit before hydration: the no-JS request the

package/dist/types/types/error-types.d.ts

@@ -67,19 +67,38 @@ export interface OnErrorContext<TEnv = any> {
     actionId?: string;
     /** Environment/bindings (platform context) */
     env?: TEnv;
-    /** Duration from request start to error (milliseconds) */
+    /**
+     * Duration from request start to error (milliseconds). For a `background`
+     * error it counts from the start of the request that started the work, so
+     * it includes that response and any wait before the work ran.
+     */
     duration?: number;
     /**
      * Whether this is a partial/navigation request, on an error the segment
-     * walk catches (a handler that throws, a DSL loader that rejects): `true`
-     * for a navigation, unset for a document. An error in the background
-     * re-render of a `cache()` record (a stale HIT's refresh, the write of a
-     * navigation that kept a layout mounted) reports the request that started
-     * it. A streamed (`loading()`) handler's rejection does not carry it, in
-     * either render; the `routing` phase reports `false`.
+     * walk catches (a handler that throws, a streamed `loading()` handler that
+     * rejects, a DSL loader that rejects): `true` for a navigation, unset for a
+     * document. A `cache()` record's refresh or proactive write reports the
+     * request that started it; a PPR shell capture renders a document. The
+     * `routing` phase reports `false`.
      */
     isPartial?: boolean;
-    /** Whether an error boundary caught the error */
+    /**
+     * `true` when the error came from work whose output goes to a cache and
+     * never to the response of the request that started it: a stale `cache()`
+     * record's refresh, the write of a navigation that kept a layout mounted, a
+     * stale document cache entry's re-run, a PPR shell capture, or a stale
+     * `"use cache"` function's or cached loader's refresh, the work's own
+     * failure included. `request` and `url` are the starting request's (a
+     * shell capture's handler errors name the page it captures). A
+     * `router.prerender()` warm's own render is its request's: unset, while a
+     * shell capture it makes is `true`. Unset for every other error.
+     */
+    background?: boolean;
+    /**
+     * Whether an error boundary caught the error and its fallback reached the
+     * response. `false` on a `background` error: the failed render is never
+     * stored, so no visitor sees the fallback.
+     */
     handledByBoundary?: boolean;
     /** Stack trace (if available) */
     stack?: string;

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);
@@ -4485,13 +4491,13 @@ import {
   Component as Component3,
   createElement as createElement4,
   isValidElement as isValidElement2,
-  useContext as useContext17,
+  useContext as useContext18,
   useMemo as useMemo9,
   Suspense as Suspense2
 } from "react";
 
 // src/browser/react/use-handle.ts
-import { useContext, useState, useEffect, useRef } from "react";
+import { useContext as useContext2, useState as useState2, useEffect as useEffect2, useRef as useRef2 } from "react";
 
 // src/missing-id-error.ts
 var SELF_FILES = /* @__PURE__ */ new Set([
@@ -4569,6 +4575,19 @@ var NavigationStoreContext = createContext(null);
 var LocationStateContext = createContext(void 0);
 var HydrationBarrierContext = createContext(0);
 
+// src/browser/react/use-route-state.ts
+import {
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState
+} from "react";
+var NO_ROUTE = {
+  location: new URL("/", "http://localhost"),
+  params: Object.freeze({})
+};
+
 // src/handles/meta.ts
 function isUnsetDescriptor(descriptor) {
   return typeof descriptor === "object" && descriptor !== null && "unset" in descriptor && typeof descriptor.unset === "string";
@@ -4698,18 +4717,18 @@ function collectMeta(segments) {
 var Meta = createHandle(collectMeta, "__rsc_router_meta__");
 
 // src/theme/theme-context.ts
-import { createContext as createContext2, useContext as useContext2 } from "react";
+import { createContext as createContext2, useContext as useContext3 } from "react";
 var ThemeContext = createContext2(null);
 
 // src/browser/react/nonce-context.ts
-import { createContext as createContext3, useContext as useContext3 } from "react";
+import { createContext as createContext3, useContext as useContext4 } from "react";
 var NonceContext = createContext3(void 0);
 
 // src/handles/MetaTags.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 
 // src/handles/Scripts.tsx
-import { useState as useState2 } from "react";
+import { useState as useState3 } from "react";
 
 // src/handles/script.ts
 function validateConfigDev(config) {
@@ -4763,7 +4782,7 @@ var Script = createHandle(collectScripts, "__rsc_router_script__");
 import { Fragment as Fragment2, jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 
 // src/browser/react/ScrollRestoration.tsx
-import { useEffect as useEffect2 } from "react";
+import { useEffect as useEffect3 } from "react";
 
 // src/browser/scroll-restoration.ts
 init_logging();
@@ -4777,12 +4796,12 @@ import { Component, Suspense, use as use2, useMemo as useMemo3 } from "react";
 
 // src/outlet-provider.tsx
 import {
-  useContext as useContext4,
+  useContext as useContext5,
   useMemo
 } from "react";
 
 // src/suspense-audit-react.tsx
-import { useEffect as useEffect3, useLayoutEffect, useRef as useRef2 } from "react";
+import { useEffect as useEffect4, useLayoutEffect as useLayoutEffect2, useRef as useRef3 } from "react";
 
 // src/suspense-audit.ts
 init_internal_debug();
@@ -4797,13 +4816,13 @@ import { jsx as jsx3 } from "react/jsx-runtime";
 import { createElement as createElement2 } from "react";
 
 // src/loader-redirect.tsx
-import { useEffect as useEffect4 } from "react";
+import { useEffect as useEffect5 } from "react";
 
 // src/browser/react/use-router.ts
-import { useContext as useContext6, useMemo as useMemo2 } from "react";
+import { useContext as useContext7, useMemo as useMemo2 } from "react";
 
 // src/browser/react/use-mount.ts
-import { useContext as useContext5 } from "react";
+import { useContext as useContext6 } from "react";
 
 // src/browser/react/mount-context.ts
 import {
@@ -4996,12 +5015,12 @@ import {
   startTransition,
   use as use3,
   useCallback,
-  useContext as useContext7,
-  useEffect as useEffect5,
+  useContext as useContext8,
+  useEffect as useEffect6,
   useMemo as useMemo4,
   useOptimistic,
-  useRef as useRef3,
-  useState as useState3
+  useRef as useRef4,
+  useState as useState4
 } from "react";
 
 // src/loader-store.ts
@@ -5163,45 +5182,23 @@ function insertSegments(node, segments, index, leafBase, paramNames) {
 }
 
 // src/browser/react/use-navigation.ts
-import {
-  useContext as useContext8,
-  useState as useState4,
-  useEffect as useEffect6,
-  useLayoutEffect as useLayoutEffect2,
-  startTransition as startTransition2,
-  useRef as useRef4
-} from "react";
+import { useContext as useContext9, useEffect as useEffect7, useRef as useRef5 } from "react";
 
 // src/browser/react/use-pathname.ts
-import { useContext as useContext9, useState as useState5, useEffect as useEffect7, useRef as useRef5 } from "react";
+import { useContext as useContext10 } from "react";
 
 // src/client-urls/optimistic-location.ts
 import { createContext as createContext6 } from "react";
 var OptimisticLocationContext = createContext6(null);
 
 // src/browser/react/use-search-params.ts
-import {
-  useCallback as useCallback2,
-  useContext as useContext10,
-  useEffect as useEffect8,
-  useMemo as useMemo5,
-  useRef as useRef6,
-  useState as useState6
-} from "react";
+import { useCallback as useCallback2, useContext as useContext11, useMemo as useMemo5 } from "react";
 
 // src/browser/react/use-params.ts
-import { useContext as useContext11, useState as useState7, useEffect as useEffect9, useRef as useRef7 } from "react";
-var EMPTY_PARAMS = Object.freeze({});
+import { useContext as useContext12 } from "react";
 
 // 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 useContext13, useState as useState5, useEffect as useEffect8, useRef as useRef6 } from "react";
 
 // src/browser/event-controller.ts
 init_notify_listeners();
@@ -5264,31 +5261,31 @@ function subscribeToLocationChange(eventController, listener) {
 }
 
 // src/browser/react/use-segments.ts
-import { useContext as useContext13, useEffect as useEffect11, useRef as useRef9 } from "react";
+import { useContext as useContext14, useEffect as useEffect9, useRef as useRef7 } from "react";
 
 // src/browser/react/NavigationProvider.tsx
 import {
-  useState as useState11,
-  useEffect as useEffect13,
+  useState as useState8,
+  useEffect as useEffect11,
   useLayoutEffect as useLayoutEffect4,
   useCallback as useCallback4,
   useMemo as useMemo7,
-  useRef as useRef11,
+  useRef as useRef9,
   use as use4,
-  startTransition as startTransition4
+  startTransition as startTransition2
 } from "react";
 
 // src/root-error-boundary.tsx
-import { Component as Component2, useState as useState9 } from "react";
+import { Component as Component2, useState as useState6 } from "react";
 import { jsx as jsx5, jsxs as jsxs3 } from "react/jsx-runtime";
 
 // src/theme/ThemeProvider.tsx
 import {
   useCallback as useCallback3,
-  useEffect as useEffect12,
+  useEffect as useEffect10,
   useLayoutEffect as useLayoutEffect3,
   useMemo as useMemo6,
-  useState as useState10
+  useState as useState7
 } from "react";
 
 // src/theme/constants.ts
@@ -5322,21 +5319,18 @@ import { jsx as jsx7 } from "react/jsx-runtime";
 import {
   forwardRef,
   useCallback as useCallback5,
-  useContext as useContext15,
-  useEffect as useEffect15,
+  useContext as useContext16,
+  useEffect as useEffect13,
   useMemo as useMemo8,
-  useRef as useRef13
+  useRef as useRef10
 } from "react";
 
 // src/browser/react/use-link-status.ts
 import {
   createContext as createContext7,
-  useContext as useContext14,
-  useState as useState12,
-  useEffect as useEffect14,
-  useRef as useRef12,
-  useOptimistic as useOptimistic3,
-  startTransition as startTransition5
+  useContext as useContext15,
+  useState as useState9,
+  useEffect as useEffect12
 } from "react";
 var LinkContext = createContext7(
   null
@@ -5537,14 +5531,14 @@ var Link = forwardRef(function Link2({
   onClick,
   ...props
 }, ref) {
-  const ctx = useContext15(NavigationStoreContext);
+  const ctx = useContext16(NavigationStoreContext);
   const isExternal = isExternalUrl(to, ctx?.origin);
   const resolvedTo = useMemo8(
     () => isExternal ? to : prefixBasename(to, ctx?.basename),
     [to, isExternal, ctx?.basename]
   );
   const configuredStrategy = prefetch ?? ctx?.defaultPrefetch ?? ENVIRONMENT_DEFAULT_PREFETCH;
-  const internalRef = useRef13(null);
+  const internalRef = useRef10(null);
   const setRef = useCallback5(
     (node) => {
       internalRef.current = node;
@@ -5556,7 +5550,7 @@ var Link = forwardRef(function Link2({
     },
     [ref]
   );
-  const stateRef = useRef13(state);
+  const stateRef = useRef10(state);
   stateRef.current = state;
   const handleClick = useCallback5(
     (e) => {
@@ -5613,7 +5607,7 @@ var Link = forwardRef(function Link2({
       );
     }
   }, [configuredStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
-  useEffect15(() => {
+  useEffect13(() => {
     if (isExternal || !ctx?.store) return;
     if (configuredStrategy !== "viewport" && configuredStrategy !== "render" && configuredStrategy !== "adaptive") {
       return;
@@ -5733,7 +5727,7 @@ var Breadcrumbs = createHandle(
 );
 
 // src/browser/react/location-state.ts
-import { useContext as useContext16, useEffect as useEffect16 } from "react";
+import { useContext as useContext17, useEffect as useEffect14 } from "react";
 
 // src/browser/react/use-href.tsx
 import { useCallback as useCallback6 } from "react";
@@ -5936,6 +5930,7 @@ var DERIVED_RENDER_BARRIER_DESCRIPTOR = {
   ...RENDER_BARRIER_DESCRIPTOR,
   enumerable: false
 };
+var backgroundWork = new AsyncLocalStorage6();
 
 // src/route-definition/redirect.ts
 init_redirect_origin();
@@ -5948,11 +5943,11 @@ import {
   useDeferredValue,
   useLayoutEffect as useLayoutEffect5,
   useMemo as useMemo10,
-  useState as useState13
+  useState as useState10
 } 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 +7141,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.28.0",
+  version: "0.30.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.30.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/client-urls/SKILL.md

@@ -450,16 +450,12 @@ function StockPanel() {
 }
 
 function SaveStock({ sku }: { sku: string }) {
+  // Kept until the next save starts.
   const { revalidationError } = useAction(saveStock);
-  const [stale, setStale] = useState(false);
-  // useAction resets to idle once the action has settled: keep the notice.
-  useEffect(() => {
-    if (revalidationError) setStale(true);
-  }, [revalidationError]);
   return (
     <form action={saveStock.bind(null, sku)}>
       <button>Save</button>
-      {stale && (
+      {revalidationError != null && (
         <p role="status">Saved. The stock count could not be refreshed.</p>
       )}
     </form>
@@ -734,8 +730,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,41 @@ 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.
+
+- Once the call settles, `state` is `idle` and the rest of its state
+  (`result`, `error`, `revalidationError`, `payload`, `actionId`) stays until
+  the same action is called again: through navigations and Back/Forward, and
+  in a component that mounts after the call settled. Every reader of the
+  same action (a function or a full id) reads the same call; a string reader
+  follows the latest call of any action with that export name. The next
+  call reads `loading` with none of them, then its own. A document load
+  starts with nothing.
+- 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
+  the other calls in flight when a call's response is an error boundary.
+- `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 +265,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.