@rangojs/router 0.29.0 → 0.30.0

package/dist/bin/rango.js

@@ -1644,7 +1644,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@rangojs/router",
-      version: "0.29.0",
+      version: "0.30.0",
       description: "Django-inspired RSC router with composable URL patterns",
       keywords: [
         "react",

package/dist/types/browser/react/use-action.d.ts

@@ -13,11 +13,12 @@ export type ServerActionFunction = ((...args: any[]) => Promise<any>) & {
  * tracks the state of individual server action invocations.
  *
  * Uses the event controller for reactive state management.
- * State is derived from the inflight actions tracked by the controller.
+ * State is derived from the calls the controller tracks: those in flight,
+ * and each action's last settled call.
  *
  * Features:
  * - Tracks action lifecycle: idle → loading → streaming → idle
- * - Captures result/error locally (React handles cleanup)
+ * - Keeps the settled call's state until the action is called again.
  * - If the same action fires several times, reports the latest call to
  *   start. An earlier call that settles later changes nothing it reports;
  *   a latest call that was aborted reports idle with nothing. One call at a

package/dist/types/browser/react/use-handle.d.ts

@@ -39,6 +39,7 @@ export declare function useHandle<T, A, S>(handle: Handle<T, A>, selector: (data
  * location commit with their page.
  *
  * A value shallow-equal to the last one sets nothing, so a reader renders only
- * when its value moves.
+ * when its value moves. A release is compared with what React committed, as in
+ * useRouteState.
  */
 export declare function useCommitAnchoredState<T>(init: () => T, waitForRelease?: boolean): [T, (value: T, signal?: RouteStateSignal) => void];

package/dist/types/browser/react/use-route-state.d.ts

@@ -0,0 +1,45 @@
+import type { RouteStateSignal } from "../event-controller.js";
+/**
+ * The value a reader rendered in React's last commit of it, written by its
+ * layout effect. A page's release runs in the provider's layout effect, after
+ * every reader's (children first), so it reads the commit that brings the
+ * page.
+ */
+export declare function useCommitted<T>(value: T): {
+    readonly current: T;
+};
+/**
+ * Sets a route-state reader's value. `next` maps the value React ends on once
+ * every set so far commits (`latest`) to the reader's value; `rebase` sets
+ * `next` itself, so React recomputes it on whatever base it renders. The value
+ * must not be a function.
+ */
+export type RouteStateSetter<T> = (next: (base: T) => T, signal?: RouteStateSignal, rebase?: boolean) => void;
+/**
+ * Route state a reader sets as the router store notifies it, in the lane of
+ * the notification that carries it. A notification equal to `latest` sets
+ * nothing, so a reader renders only when its value moves.
+ *
+ * A release is compared with what React committed, not with `latest`: while
+ * React holds a page, its set is not on screen, and an urgent page that ends
+ * the hold brings an equal value. A release that finds every set committed
+ * with its value sets nothing.
+ */
+export declare function useRouteState<T>(init: () => T, same: (a: T, b: T) => boolean): [T, RouteStateSetter<T>];
+/** The route a URL hook reads. */
+export interface UrlRoute {
+    location: URL;
+    params: Record<string, string>;
+}
+/**
+ * A URL hook's value (usePathname, useParams, useSearchParams): `read` of the
+ * route, seeded from the hydration snapshot while the document hydrates, then
+ * set as the store notifies it and at a page's release (useRouteState). The
+ * release rides the handle channel. `read` applies when the store changes,
+ * never in a later render: a new one takes effect from the next change.
+ *
+ * A read equal to the value it is set over keeps that value, so an object
+ * reader changes identity once per value: a release that ends a hold sets the
+ * held page's object, which React's render of the held lane keeps.
+ */
+export declare function useUrlValue<T>(read: (route: UrlRoute) => T, same: (a: T, b: T) => boolean): T;

package/dist/types/browser/types.d.ts

@@ -231,7 +231,11 @@ export type ActionLifecycleState = "idle" | "loading" | "streaming";
  * @internal This type is an implementation detail and may change without notice.
  */
 export interface TrackedActionState {
-    /** Current lifecycle state of the action */
+    /**
+     * Current lifecycle state of the action. Once the call settles it is
+     * "idle" and the rest of the call's state is kept until the action's next
+     * call.
+     */
     state: ActionLifecycleState;
     /** Server action function ID (e.g., "addToCart") */
     actionId: string | null;
@@ -239,12 +243,12 @@ export interface TrackedActionState {
     payload: unknown[] | FormData | null;
     /** Error if action failed */
     error: unknown | null;
-    /** Result data from the action (preserved after completion) */
+    /** Result data from the action */
     result: unknown | null;
     /**
      * The error of a loader that threw while it re-ran after this successful
-     * action (the first, when several did). The loader also throws at its
-     * useLoader read, where the nearest error boundary catches it.
+     * action (the first, when several did). The loader also throws at its useLoader read, where the nearest
+     * error boundary catches it.
      */
     revalidationError: unknown | null;
 }

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

@@ -385,15 +385,15 @@ export interface TestRouterHandle {
      * await act(async () => tail.resolve());
      * // useNavigation(): idle, isStreaming false
      *
-     * A navigation started while React holds a page goes inside
-     * `await act(async () => ...)`. Its first update makes React retry the held
-     * page, which suspends again; a synchronous act() scope drops that retry
-     * and React renders no later update of the same priority.
+     * 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 act(async () => {
-     *   await router.navigate("/products/3", { transition: false });
-     * });
+     * 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"> & {
         streamUntil?: Promise<unknown>;

package/dist/vite/index.js

@@ -4491,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([
@@ -4575,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";
@@ -4704,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) {
@@ -4769,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();
@@ -4783,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();
@@ -4803,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 {
@@ -5002,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
@@ -5169,37 +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,
-  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 } 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();
@@ -5262,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 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
@@ -5320,18 +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 useRef12
+  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
+  useContext as useContext15,
+  useState as useState9,
+  useEffect as useEffect12
 } from "react";
 var LinkContext = createContext7(
   null
@@ -5532,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 = useRef12(null);
+  const internalRef = useRef10(null);
   const setRef = useCallback5(
     (node) => {
       internalRef.current = node;
@@ -5551,7 +5550,7 @@ var Link = forwardRef(function Link2({
     },
     [ref]
   );
-  const stateRef = useRef12(state);
+  const stateRef = useRef10(state);
   stateRef.current = state;
   const handleClick = useCallback5(
     (e) => {
@@ -5608,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;
@@ -5728,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";
@@ -5944,7 +5943,7 @@ import {
   useDeferredValue,
   useLayoutEffect as useLayoutEffect5,
   useMemo as useMemo10,
-  useState as useState13
+  useState as useState10
 } from "react";
 
 // src/client-urls/navigation.ts
@@ -7142,7 +7141,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.29.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.29.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>

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

@@ -196,6 +196,14 @@ 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: 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
@@ -203,8 +211,7 @@ last one to start.
   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.
+  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:

package/skills/hooks/navigation.md

@@ -90,9 +90,9 @@ reads (a selector, the full state): work that starts shows at once
 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.
+shows with its own values in every `useNavigation()` reader, and with its URL
+in `usePathname()`, `useParams()`, `useSearchParams()` and `useSegments()`,
+also when it is the URL React was holding.
 
 The rule holds for readers mounted before the page was handed to React. A
 reader that mounts while the page is held (a menu opened during the wait)

package/skills/hooks/urls.md

@@ -123,6 +123,7 @@ click or `router.push()`.
 | Back/Forward, entry fetched again                 | when the fetched page commits; until then the page being left is on screen |
 | a Back/Forward whose fetch fails                  | with the error boundary: they report the entry the browser is on           |
 | `router.push(url, { revalidate: false })`         | at once: nothing is fetched and the page stays                             |
+| `transition={false}` over a held page             | with that page's first screen, also on the URL React was holding           |
 | inside an optimistic `clientUrls()` destination   | at the click, for that branch only (see `/client-urls`)                    |
 
 **A newer click that fails while a page is held.** Click a link, and while

package/skills/testing/client-components.md

@@ -406,7 +406,7 @@ it("dims the held price while the next product streams", async () => {
 | `useAction().state`                                                                            | Stays `idle`: navigate() runs no action. e2e.                                                                                                                                                                        |
 | `useHandle()` on a held navigation, `navigate(url, { handles, loaders })`                      | Modeled: `handles` arrive on the response's handle stream, so readers keep the page being left's values while React holds the page and take the new ones with its commit.                                            |
 | `useNavigation().isStreaming` past the commit, `navigate(url, { streamUntil })`                | Modeled: the stream opens a task after the call (`pendingUrl` clears) and ends when the promise settles or a newer navigation aborts it; settle it inside `await act(async () => ...)`.                              |
-| A navigation started while React holds a page (a newer click, a `transition: false` commit)    | Call it inside `await act(async () => { ... })`: its first update makes React retry the held page, and a synchronous `act()` drops that retry, so a later urgent commit never renders.                               |
+| A navigation started while React holds a page (a newer click, a `transition: false` commit)    | `await router.navigate(...)` shows its page, with or without `act()`. A `<Link>` click goes inside `await act(async () => { ... })`: `fireEvent`'s synchronous `act()` drops React's retry of the held page.         |
 | A back/forward restored from the history cache (`pop`)                                         | Modeled for the mounted entry and one a navigate() wrote: the page and its handle values come back, decided by `transition({ when })` as kind `"pop"`. A stale entry's revalidation and a restore that fetches: e2e. |
 
 - Per-navigation seeds merge over the render-time `loaders`/`loaderData` for THAT navigation only; a later `navigate()` without `loaders` falls back to the render-time data.

package/src/browser/event-controller.ts

@@ -542,6 +542,28 @@ export function createEventController(
   let unsettledNavigation: NavigationEntry | null = null;
 
   const inflightActions = new Map<string, ActionEntry>();
+  // Each action id's last settled call, which useAction reports until the
+  // action's next call starts (startAction deletes it). A call moves here
+  // when doSettle's cleanup takes it out of inflightActions. A trimmed
+  // snapshot, so no abort controller outlives the call. abortAllActions leaves
+  // settled calls: they persist through navigations until the action's next
+  // call.
+  type TrackedCall = Pick<
+    ActionEntry,
+    | "actionId"
+    | "phase"
+    | "payload"
+    | "result"
+    | "error"
+    | "revalidationError"
+    | "supersededBy"
+  >;
+  const settledActions = new Map<string, TrackedCall>();
+
+  function* trackedCalls(): Generator<TrackedCall> {
+    yield* inflightActions.values();
+    yield* settledActions.values();
+  }
 
   let location: NavigationLocation =
     config?.initialLocation ??
@@ -713,15 +735,17 @@ export function createEventController(
   }
 
   function getActionState(actionId: string): TrackedActionState {
-    // Nothing inflight — skip building/scanning the list and return the shared
-    // idle snapshot (the same reference use-action falls back to).
-    if (inflightActions.size === 0) return DEFAULT_ACTION_STATE;
+    // No call tracked: the shared idle snapshot (the same reference use-action
+    // falls back to).
+    if (inflightActions.size === 0 && settledActions.size === 0) {
+      return DEFAULT_ACTION_STATE;
+    }
 
-    // The latest call this reader matches, or none once a later call left the
-    // map: an earlier call still running is never reported again.
+    // The latest call this reader matches, in flight or settled, or none once
+    // a later call was aborted: an earlier call is never reported again.
     const byName = !actionId.includes("#");
-    let entry: ActionEntry | undefined;
-    for (const a of inflightActions.values()) {
+    let entry: TrackedCall | undefined;
+    for (const a of trackedCalls()) {
       if (
         matchesActionId(actionId, a.actionId) &&
         (byName ? !a.supersededBy : a.supersededBy !== "id")
@@ -907,9 +931,9 @@ export function createEventController(
     // after that point is strictly ordered behind the prior action's server
     // execution, and there is no skipped render or order uncertainty for
     // consolidation to repair. Completed entries still linger in the map for
-    // the 100ms doSettle window (useAction reads) and, on a slow connection,
-    // while the Flight stream drains its EOF after complete(). Counting them
-    // latched hadAnyConcurrentActions for back-to-back sequential actions,
+    // the 100ms doSettle window and, on a slow connection, while the Flight
+    // stream drains its EOF after complete(). Counting them latched
+    // hadAnyConcurrentActions for back-to-back sequential actions,
     // which made the LAST action classify as consolidation-needed; the
     // consolidation refetch omits every concurrently-revalidated segment id
     // from _rsc_segments, so the server re-ran gated loaders as "new-segment"
@@ -922,13 +946,15 @@ export function createEventController(
     }
 
     // useAction reports the latest call. Every earlier call that a reader of
-    // this one also matches is hidden from that reader for good, so it never
-    // shows again after this call settles and leaves the map: a call of the
-    // same action from every reader, a call of another action with the same
-    // export name from readers that match by name (matchesActionId).
+    // this one also matches, in flight or settled, is hidden from that reader
+    // for good, so it never shows again, also once this call is aborted: a
+    // call of the same action from every reader, a call of another action
+    // with the same export name from readers that match by name
+    // (matchesActionId). So at most one call matches a reader (getActionState).
     const hash = actionId.lastIndexOf("#");
     const name = hash === -1 ? null : actionId.slice(hash + 1);
-    for (const a of inflightActions.values()) {
+    settledActions.delete(actionId);
+    for (const a of trackedCalls()) {
       if (a.actionId === actionId) a.supersededBy = "id";
       else if (name !== null && matchesActionId(name, a.actionId)) {
         a.supersededBy ??= "name";
@@ -978,9 +1004,20 @@ export function createEventController(
       if (settled) return;
       settled = true;
 
-      // Cleanup after brief delay (allow useAction to read result)
       setTimeout(() => {
-        inflightActions.delete(id);
+        // The action's last settled call until its next call starts, unless
+        // that call already started.
+        if (inflightActions.delete(id) && entry.supersededBy !== "id") {
+          settledActions.set(actionId, {
+            actionId: entry.actionId,
+            phase: entry.phase,
+            payload: entry.payload,
+            result: entry.result,
+            error: entry.error,
+            revalidationError: entry.revalidationError,
+            supersededBy: entry.supersededBy,
+          });
+        }
         // Free this cohort's arbitration once its last action has settled, so
         // a long-running action elsewhere cannot pin keys from a drained entry.
         releaseCohort();

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

@@ -71,11 +71,12 @@ export type ServerActionFunction = ((...args: any[]) => Promise<any>) & {
  * tracks the state of individual server action invocations.
  *
  * Uses the event controller for reactive state management.
- * State is derived from the inflight actions tracked by the controller.
+ * State is derived from the calls the controller tracks: those in flight,
+ * and each action's last settled call.
  *
  * Features:
  * - Tracks action lifecycle: idle → loading → streaming → idle
- * - Captures result/error locally (React handles cleanup)
+ * - Keeps the settled call's state until the action is called again.
  * - If the same action fires several times, reports the latest call to
  *   start. An earlier call that settles later changes nothing it reports;
  *   a latest call that was aborted reports idle with nothing. One call at a

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

@@ -6,6 +6,7 @@ import { collectHandleData } from "../../handle.js";
 import type { HandleData } from "../types.js";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
+import { useCommitted } from "./use-route-state.js";
 import type { RouteStateSignal } from "../event-controller.js";
 
 /**
@@ -86,7 +87,8 @@ export function useHandle<T, A, S>(
  * location commit with their page.
  *
  * A value shallow-equal to the last one sets nothing, so a reader renders only
- * when its value moves.
+ * when its value moves. A release is compared with what React committed, as in
+ * useRouteState.
  */
 export function useCommitAnchoredState<T>(
   init: () => T,
@@ -99,12 +101,15 @@ export function useCommitAnchoredState<T>(
   const ref = useRef<{ last: T; held?: boolean; waiting?: boolean }>({
     last: value,
   });
+  const committed = useCommitted(value);
   const [set] = useState(() => (next: T, signal?: RouteStateSignal): void => {
     const r = ref.current;
     if (signal) r.waiting = signal === "anchor";
     if (!shallowEqual(next, r.last)) {
       r.last = next;
       r.held = true;
+    } else if (signal === "release" && r.last !== committed.current) {
+      r.held = true;
     }
     if (!r.held || (r.waiting && (waitForRelease || signal !== "anchor")))
       return;

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

@@ -1,14 +1,9 @@
 "use client";
 
-import {
-  useContext,
-  useState,
-  useEffect,
-  useLayoutEffect,
-  useRef,
-} from "react";
+import { useContext, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
+import { useRouteState } from "./use-route-state.js";
 import type { PublicNavigationState } from "../types.js";
 import type {
   DerivedNavigationState,
@@ -74,7 +69,11 @@ export function useNavigation<T>(
     throw new Error("useNavigation must be used within NavigationProvider");
   }
 
-  const [snapshot, setSnapshot] = useState<Snapshot<T | PublicNavigationState>>(
+  // A release is compared with the state React renders it on
+  // (useRouteState). The anchor is compared with the last set, as an
+  // ordinary notification is: it sets inside its page's transition, which
+  // renders every set so far.
+  const [snapshot, set] = useRouteState<Snapshot<T | PublicNavigationState>>(
     () => {
       const state = toPublicState(
         ctx.eventController.getHydrationSnapshot()?.state ??
@@ -82,13 +81,8 @@ export function useNavigation<T>(
       );
       return { state, value: selector ? selector(state) : state };
     },
+    (a, b) => shallowEqual(a.value, b.value),
   );
-  // What React ends on once every set so far commits, and what it committed.
-  const latest = useRef(snapshot);
-  const committed = useRef(snapshot);
-  useLayoutEffect(() => {
-    committed.current = snapshot;
-  });
 
   // Store selector in a ref so the subscription callback always uses the
   // latest selector without re-subscribing on every render (inline functions
@@ -118,34 +112,14 @@ export function useNavigation<T>(
       const moved = live.location !== location;
       location = live.location;
       const held = pageHeld && !signal;
-      const next = (
-        base: Snapshot<T | PublicNavigationState>,
-      ): Snapshot<T | PublicNavigationState> => {
-        const state = held ? hold(base.state, live, moved) : live;
-        return { state, value: select(state) };
-      };
-      const target = next(latest.current);
-      // A release is compared with the state React renders it on, not
-      // `latest`: an urgent page can end the hold before React commits the
-      // anchor's set. An anchor sets inside its page's transition, which
-      // renders every set so far, so `latest` is that state. A release that
-      // finds every set committed with its value sets nothing: the updater
-      // would render the reader again only to bail out.
-      if (signal === "release") {
-        if (
-          latest.current === committed.current &&
-          shallowEqual(target.value, latest.current.value)
-        )
-          return;
-        latest.current = target;
-        setSnapshot((prev) =>
-          shallowEqual(prev.value, target.value) ? prev : target,
-        );
-        return;
-      }
-      if (shallowEqual(target.value, latest.current.value)) return;
-      latest.current = target;
-      setSnapshot(held ? next : target);
+      set(
+        (base) => {
+          const state = held ? hold(base.state, live, moved) : live;
+          return { state, value: select(state) };
+        },
+        signal,
+        held,
+      );
     };
 
     // Catch-up: re-read state synchronously on mount before subscribing, so a

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

@@ -1,12 +1,10 @@
 "use client";
 
-import { useContext, useState, useEffect, useRef } from "react";
-import { NavigationStoreContext } from "./context.js";
+import { useContext } from "react";
 import { shallowEqual } from "./shallow-equal.js";
+import { useUrlValue } from "./use-route-state.js";
 import { OptimisticLocationContext } from "../../client-urls/optimistic-location.js";
 
-const EMPTY_PARAMS: Record<string, string> = Object.freeze({});
-
 /**
  * Hook to access the current route params.
  *
@@ -45,38 +43,11 @@ export function useParams<T>(
 export function useParams<T>(
   selector?: (params: Record<string, string | undefined>) => T,
 ): T | Record<string, string | undefined> {
-  const ctx = useContext(NavigationStoreContext);
   const optimistic = useContext(OptimisticLocationContext);
-
-  const [value, setValue] = useState<T | Record<string, string>>(() => {
-    const params = ctx
-      ? (ctx.eventController.getHydrationSnapshot()?.params ??
-        ctx.eventController.getParams())
-      : EMPTY_PARAMS;
-    return selector ? selector(params) : params;
-  });
-
-  const prevValue = useRef(value);
-  const selectorRef = useRef(selector);
-  selectorRef.current = selector;
-
-  useEffect(() => {
-    if (!ctx) return;
-
-    const update = () => {
-      const params = ctx.eventController.getParams();
-      const next = selectorRef.current ? selectorRef.current(params) : params;
-
-      if (!shallowEqual(next, prevValue.current)) {
-        prevValue.current = next;
-        setValue(next);
-      }
-    };
-
-    update();
-
-    return ctx.eventController.subscribe(update);
-  }, []);
+  const value = useUrlValue<T | Record<string, string>>(
+    ({ params }) => (selector ? selector(params) : params),
+    shallowEqual,
+  );
 
   if (optimistic) {
     return selector ? selector(optimistic.params) : optimistic.params;

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

@@ -1,7 +1,7 @@
 "use client";
 
-import { useContext, useState, useEffect, useRef } from "react";
-import { NavigationStoreContext } from "./context.js";
+import { useContext } from "react";
+import { useUrlValue } from "./use-route-state.js";
 import { OptimisticLocationContext } from "../../client-urls/optimistic-location.js";
 
 /**
@@ -19,36 +19,7 @@ import { OptimisticLocationContext } from "../../client-urls/optimistic-location
  * ```
  */
 export function usePathname(): string {
-  const ctx = useContext(NavigationStoreContext);
   const optimistic = useContext(OptimisticLocationContext);
-
-  const [pathname, setPathname] = useState<string>(() => {
-    if (!ctx) {
-      return "/";
-    }
-    const state =
-      ctx.eventController.getHydrationSnapshot()?.state ??
-      ctx.eventController.getState();
-    return (state.location as URL).pathname;
-  });
-
-  const prevPathname = useRef(pathname);
-
-  useEffect(() => {
-    if (!ctx) return;
-
-    const update = () => {
-      const next = (ctx.eventController.getState().location as URL).pathname;
-      if (next !== prevPathname.current) {
-        prevPathname.current = next;
-        setPathname(next);
-      }
-    };
-
-    update();
-
-    return ctx.eventController.subscribe(update);
-  }, []);
-
+  const pathname = useUrlValue((route) => route.location.pathname, Object.is);
   return optimistic ? optimistic.pathname : pathname;
 }

package/src/browser/react/use-route-state.ts

@@ -0,0 +1,141 @@
+"use client";
+
+import {
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import { NavigationStoreContext } from "./context.js";
+import type { EventController, RouteStateSignal } from "../event-controller.js";
+
+/**
+ * The value a reader rendered in React's last commit of it, written by its
+ * layout effect. A page's release runs in the provider's layout effect, after
+ * every reader's (children first), so it reads the commit that brings the
+ * page.
+ */
+export function useCommitted<T>(value: T): { readonly current: T } {
+  const committed = useRef(value);
+  useLayoutEffect(() => {
+    committed.current = value;
+  }, [value]);
+  return committed;
+}
+
+/**
+ * Sets a route-state reader's value. `next` maps the value React ends on once
+ * every set so far commits (`latest`) to the reader's value; `rebase` sets
+ * `next` itself, so React recomputes it on whatever base it renders. The value
+ * must not be a function.
+ */
+export type RouteStateSetter<T> = (
+  next: (base: T) => T,
+  signal?: RouteStateSignal,
+  rebase?: boolean,
+) => void;
+
+/**
+ * Route state a reader sets as the router store notifies it, in the lane of
+ * the notification that carries it. A notification equal to `latest` sets
+ * nothing, so a reader renders only when its value moves.
+ *
+ * A release is compared with what React committed, not with `latest`: while
+ * React holds a page, its set is not on screen, and an urgent page that ends
+ * the hold brings an equal value. A release that finds every set committed
+ * with its value sets nothing.
+ */
+export function useRouteState<T>(
+  init: () => T,
+  same: (a: T, b: T) => boolean,
+): [T, RouteStateSetter<T>] {
+  const [value, setValue] = useState(init);
+  const latest = useRef(value);
+  const committed = useCommitted(value);
+  const [set] = useState(
+    (): RouteStateSetter<T> => (next, signal, rebase) => {
+      const target = next(latest.current);
+      if (signal === "release") {
+        if (
+          latest.current === committed.current &&
+          same(target, latest.current)
+        )
+          return;
+        latest.current = target;
+        setValue((prev) => (same(prev, target) ? prev : target));
+        return;
+      }
+      if (same(target, latest.current)) return;
+      latest.current = target;
+      setValue(rebase ? next : target);
+    },
+  );
+  return [value, set];
+}
+
+/** The route a URL hook reads. */
+export interface UrlRoute {
+  location: URL;
+  params: Record<string, string>;
+}
+
+const NO_ROUTE: UrlRoute = {
+  location: new URL("/", "http://localhost"),
+  params: Object.freeze({}) as Record<string, string>,
+};
+
+const routeOf = (controller: EventController): UrlRoute => ({
+  location: controller.getState().location,
+  params: controller.getParams(),
+});
+
+/**
+ * A URL hook's value (usePathname, useParams, useSearchParams): `read` of the
+ * route, seeded from the hydration snapshot while the document hydrates, then
+ * set as the store notifies it and at a page's release (useRouteState). The
+ * release rides the handle channel. `read` applies when the store changes,
+ * never in a later render: a new one takes effect from the next change.
+ *
+ * A read equal to the value it is set over keeps that value, so an object
+ * reader changes identity once per value: a release that ends a hold sets the
+ * held page's object, which React's render of the held lane keeps.
+ */
+export function useUrlValue<T>(
+  read: (route: UrlRoute) => T,
+  same: (a: T, b: T) => boolean,
+): T {
+  const ctx = useContext(NavigationStoreContext);
+  const [value, set] = useRouteState(() => {
+    if (!ctx) return read(NO_ROUTE);
+    const hydration = ctx.eventController.getHydrationSnapshot();
+    return read(
+      hydration
+        ? { location: hydration.state.location, params: hydration.params }
+        : routeOf(ctx.eventController),
+    );
+  }, same);
+  const readRef = useRef(read);
+  readRef.current = read;
+
+  useEffect(() => {
+    if (!ctx) return;
+    const controller = ctx.eventController;
+    const update = (signal?: RouteStateSignal): void => {
+      const next = readRef.current(routeOf(controller));
+      set((base) => (same(next, base) ? base : next), signal);
+    };
+    // Catch up with a change between the seeding render and this effect.
+    update();
+    const unsubscribe = controller.subscribe(update);
+    const unsubscribeRelease = controller.subscribeToHandles((signal) => {
+      if (signal === "release") update(signal);
+    });
+    return () => {
+      unsubscribe();
+      unsubscribeRelease();
+    };
+  }, []);
+
+  return value;
+}

package/src/browser/react/use-search-params.ts

@@ -1,14 +1,8 @@
 "use client";
 
-import {
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
+import { useCallback, useContext, useMemo } from "react";
 import { NavigationStoreContext } from "./context.js";
+import { useUrlValue } from "./use-route-state.js";
 import type { ReadonlyURLSearchParams } from "../types.js";
 import { OptimisticLocationContext } from "../../client-urls/optimistic-location.js";
 
@@ -113,38 +107,11 @@ export function useSearchParams(): [ReadonlyURLSearchParams, SetSearchParams] {
   const ctx = useContext(NavigationStoreContext);
   const optimistic = useContext(OptimisticLocationContext);
 
-  // Seed from the store location on BOTH sides (mirrors usePathname): the
-  // SSR store carries the live request's search, the browser store carries
-  // window.location — same URL, so the hydration renders agree. No ctx
-  // (no provider) seeds empty.
-  const [searchParams, setSearchParamsState] =
-    useState<ReadonlyURLSearchParams>(() => {
-      const state = ctx
-        ? (ctx.eventController.getHydrationSnapshot()?.state ??
-          ctx.eventController.getState())
-        : undefined;
-      const location = state?.location as URL | undefined;
-      return new URLSearchParams(location?.searchParams);
-    });
-
-  const prevSearch = useRef(searchParams.toString());
-
-  useEffect(() => {
-    if (!ctx) return;
-
-    const update = () => {
-      const location = ctx.eventController.getState().location as URL;
-      const nextSearch = location.searchParams.toString();
-      if (nextSearch !== prevSearch.current) {
-        prevSearch.current = nextSearch;
-        setSearchParamsState(new URLSearchParams(nextSearch));
-      }
-    };
-
-    update();
-
-    return ctx.eventController.subscribe(update);
-  }, []);
+  // A new object only when the string changes.
+  const searchParams = useUrlValue<ReadonlyURLSearchParams>(
+    (route) => new URLSearchParams(route.location.searchParams),
+    (a, b) => a.toString() === b.toString(),
+  );
 
   // Reads the committed location at CALL time (not the render closure), so a
   // functional init always merges against fresh params even when the caller's

package/src/browser/types.ts

@@ -253,7 +253,11 @@ export type ActionLifecycleState = "idle" | "loading" | "streaming";
  * @internal This type is an implementation detail and may change without notice.
  */
 export interface TrackedActionState {
-  /** Current lifecycle state of the action */
+  /**
+   * Current lifecycle state of the action. Once the call settles it is
+   * "idle" and the rest of the call's state is kept until the action's next
+   * call.
+   */
   state: ActionLifecycleState;
 
   /** Server action function ID (e.g., "addToCart") */
@@ -265,13 +269,13 @@ export interface TrackedActionState {
   /** Error if action failed */
   error: unknown | null;
 
-  /** Result data from the action (preserved after completion) */
+  /** Result data from the action */
   result: unknown | null;
 
   /**
    * The error of a loader that threw while it re-ran after this successful
-   * action (the first, when several did). The loader also throws at its
-   * useLoader read, where the nearest error boundary catches it.
+   * action (the first, when several did). The loader also throws at its useLoader read, where the nearest
+   * error boundary catches it.
    */
   revalidationError: unknown | null;
 }

package/src/testing/render-route.tsx

@@ -475,15 +475,15 @@ export interface TestRouterHandle {
    * await act(async () => tail.resolve());
    * // useNavigation(): idle, isStreaming false
    *
-   * A navigation started while React holds a page goes inside
-   * `await act(async () => ...)`. Its first update makes React retry the held
-   * page, which suspends again; a synchronous act() scope drops that retry
-   * and React renders no later update of the same priority.
+   * 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 act(async () => {
-   *   await router.navigate("/products/3", { transition: false });
-   * });
+   * 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,
@@ -914,9 +914,10 @@ export async function renderRoute(
     const handle = eventController.startNavigation(
       new URL(target, TEST_ORIGIN).href,
     );
-    // Synchronous, in the caller's task: a <Link> click's own act() scope
-    // takes it, and no act() of the caller's can overlap it.
-    act(() => eventController.flushRouteState());
+    // Runs in the caller's task, so a <Link> click's own act() takes it.
+    // Awaited: React retries a held page with this update, and an unawaited
+    // act() drops that suspended retry for good.
+    await act(() => eventController.flushRouteState());
     try {
       const streamUntil = navOptions?.streamUntil;
       if (streamUntil) {
@@ -927,18 +928,19 @@ export async function renderRoute(
         });
         if (handle.signal.aborted) return;
         const stream = handle.startStreaming();
-        act(() => eventController.flushRouteState());
+        await act(() => eventController.flushRouteState());
         // A navigation that is left stops counting as streaming at the abort
         // (partial-update.ts endStream); the abort's notification goes out
         // with the newer navigation's.
         handle.signal.addEventListener("abort", () => stream.end(), {
           once: true,
         });
-        const end = (): void =>
-          act(() => {
+        const end = async (): Promise<void> => {
+          await act(() => {
             stream.end();
             eventController.flushRouteState();
           });
+        };
         void streamUntil.then(end, end);
       }
       await commitNavigation(handle, target, navOptions);