@rangojs/router 0.29.0 → 0.30.1

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/skills/testing/response-routes.md

@@ -82,14 +82,15 @@ describe("api routes via dispatch", () => {
 
 - trailing-slash redirects from the trie — a route with `trailingSlash: "never"` or `"always"` answers the other form with a 308 and the `Location` (query preserved). A route with no `trailingSlash` serves its URL with and without a trailing slash, with no redirect, as production does;
 - the open-redirect guard on browser-followed redirects (a cross-origin `Location` is rewritten to the basename root unless `redirect(url, { external: true })`);
-- content-negotiated routes (`Vary: Accept` appended);
+- content-negotiated routes whose winning route is a response route (`Vary: Accept` appended);
 - the reloads production answers inside the global middleware chain: a request whose `_rsc_v` names another deploy's document version (`setBuildVersions`, `./serve-shell-request.md`), and a `_rsc_partial` request whose `_rsc_rid` names another router (a cross-app navigation), get an `X-RSC-Reload` at the visitor's URL — on any route, a component route or an unmatched path included;
 - cached response routes (`cache({ ... })` around a `path.json` etc.): hit, SWR, and tag writes. The cache write is scheduled via `waitUntil` (a microtask in tests), so flush microtasks between the seeding `dispatch` and the one that asserts the hit;
 - `createRouter({ telemetry })` `request.start` / `request.end` / `request.error` events, all with one `requestId`, which a response route's `request.timeout` carries too (a rewritten pass's included), and `createRouter({ onError })` for cache-read/write failures.
 
 ## Caveats
 
-- Hitting a COMPONENT (RSC) route throws a clear directive error: `dispatch` is for response routes + redirects + 404 + content negotiation, plus the global + route-level middleware guard stack on RESPONSE routes — it never renders React. Use Flight primitives or e2e to exercise component rendering.
+- Hitting a COMPONENT (RSC) route throws a clear directive error: `dispatch` is for response routes + redirects + 404 + negotiation won by a response route, plus the global + route-level middleware guard stack on RESPONSE routes — it never renders React. Use Flight primitives or e2e to exercise component rendering.
+- On a content-negotiated URL, any `Accept` the page route wins throws the same error. Serve that request with `serveShellRequest(router, url, { headers: { accept } })` (`./serve-shell-request.md`): it runs the production handler and answers the HTML document or the Flight stream, with `Vary: Accept`.
 - A COMPONENT route's guard stack cannot run here. Assert it at e2e, or extract the middleware fn and unit-test it with `runMiddleware` (see `./middleware.md`).
 - JSON serialization is bare, applied in `response-route-handler.ts`: a `path.json` handler that returns a value is serialized verbatim (`JSON.stringify(value)`, status 200, `application/json`) — no envelope. Returning or throwing a `Response` (e.g. `Response.json(x)`) uses the same control-flow path. Any other thrown error takes the error's status (`RouterError.status`, else 500, or a non-200 status already set upstream in the request pipeline). On a `path.json` route the body is an RFC 9457 problem+json object `{ title, status, detail, code }` (`application/problem+json;charset=utf-8`), where `code` is the `RouterError.code`, else `"INTERNAL"`, and the `type` member is omitted. On text/html/xml/md routes the body is `text/plain`: the `RouterError` message, the error message in dev, or `"Internal Server Error"` in production. Assert the shape matching what your handler returns.
 - Setup: needs the preset (alias + virtual stubs) or a Vite-RSC env (see `./setup.md`); a bare router import throws on Vite virtuals.

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;
 }