@timber-js/app 0.2.0-alpha.6 → 0.2.0-alpha.61

package/src/client/link.tsx

@@ -18,10 +18,42 @@
 // - params and fully-resolved string href are mutually exclusive
 // - searchParams and inline query string are mutually exclusive
 
-import type { AnchorHTMLAttributes, ReactNode, MouseEvent as ReactMouseEvent } from 'react';
-import type { SearchParamsDefinition } from '#/search-params/create.js';
-import { LinkStatusProvider } from './link-status-provider.js';
+import {
+  useState,
+  useEffect,
+  useRef,
+  type AnchorHTMLAttributes,
+  type ReactNode,
+  type MouseEvent as ReactMouseEvent,
+} from 'react';
+import type { SearchParamsDefinition } from '../search-params/define.js';
+import { LinkStatusContext } from './use-link-status.js';
 import { getRouterOrNull } from './router-ref.js';
+import { getSsrData } from './ssr-data.js';
+import { mergePreservedSearchParams } from '../shared/merge-search-params.js';
+import {
+  setLinkForCurrentNavigation,
+  unmountLinkForCurrentNavigation,
+  IDLE_LINK_STATUS,
+  PENDING_LINK_STATUS,
+  type LinkPendingInstance,
+} from './link-pending-store.js';
+
+// ─── Current Search Params ────────────────────────────────────────
+
+/**
+ * Read the current URL's search string without requiring a React hook.
+ * On the client, reads window.location.search. During SSR, reads from
+ * the request context (getSsrData). Returns empty string if unavailable.
+ */
+function getCurrentSearch(): string {
+  if (typeof window !== 'undefined') return window.location.search;
+  const data = getSsrData();
+  if (!data) return '';
+  const sp = new URLSearchParams(data.searchParams);
+  const str = sp.toString();
+  return str ? `?${str}` : '';
+}
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -42,6 +74,20 @@ interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'h
    * Set to false for tabbed interfaces where content changes within a fixed layout.
    */
   scroll?: boolean;
+  /**
+   * Preserve search params from the current URL across navigation.
+   *
+   * - `true` — preserve ALL current search params (target params take precedence)
+   * - `string[]` — preserve only the named params (e.g. `['private', 'token']`)
+   *
+   * Useful for route-group gating where a search param (e.g. `?private=access`)
+   * must persist across internal navigations. The target href's own search params
+   * always take precedence over preserved ones.
+   *
+   * During SSR, reads search params from the request context. On the client,
+   * reads from the current URL and updates reactively when the URL changes.
+   */
+  preserveSearchParams?: true | string[];
   /**
    * Called before client-side navigation commits. Call `e.preventDefault()`
    * to cancel the default navigation — the caller is then responsible for
@@ -61,7 +107,7 @@ interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'h
  */
 export interface LinkPropsWithHref extends LinkBaseProps {
   href: string;
-  params?: never;
+  segmentParams?: never;
   /**
    * Typed search params — serialized via the route's SearchParamsDefinition.
    * Mutually exclusive with an inline query string in href.
@@ -73,9 +119,9 @@ export interface LinkPropsWithHref extends LinkBaseProps {
 }
 
 /**
- * Link with a route pattern + params for interpolation.
- * e.g. <Link href="/products/[id]" params={{ id: "123" }}>
- *      <Link href="/products/[id]" params={{ id: 123 }}>
+ * Link with a route pattern + segmentParams for interpolation.
+ * e.g. <Link href="/products/[id]" segmentParams={{ id: "123" }}>
+ *      <Link href="/products/[id]" segmentParams={{ id: 123 }}>
  */
 export interface LinkPropsWithParams extends LinkBaseProps {
   /** Route pattern with dynamic segments (e.g. "/products/[id]") */
@@ -85,7 +131,7 @@ export interface LinkPropsWithParams extends LinkBaseProps {
    * Single dynamic segments accept string | number (numbers are stringified).
    * Catch-all segments accept string[].
    */
-  params: Record<string, string | number | string[]>;
+  segmentParams: Record<string, string | number | string[]>;
   /**
    * Typed search params — serialized via the route's SearchParamsDefinition.
    */
@@ -303,22 +349,66 @@ function shouldInterceptClick(
  * its own click handling.
  *
  * Supports typed routes via codegen overloads. At runtime:
- * - `params` prop interpolates dynamic segments in the href pattern
+ * - `segmentParams` prop interpolates dynamic segments in the href pattern
  * - `searchParams` prop serializes query parameters via a SearchParamsDefinition
  */
 export function Link({
   href,
   prefetch,
   scroll,
-  params,
+  segmentParams,
   searchParams,
+  preserveSearchParams,
   onNavigate,
   onClick: userOnClick,
   onMouseEnter: userOnMouseEnter,
   children,
   ...rest
 }: LinkProps) {
-  const { href: resolvedHref } = buildLinkProps({ href, params, searchParams });
+  const { href: baseHref } = buildLinkProps({ href, params: segmentParams, searchParams });
+
+  // ─── Per-link pending state (useState) ────────────────────────
+  // Each Link has its own pending state. Only the clicked link's
+  // setter is invoked during navigation — zero other links re-render.
+  //
+  // Eager show: click handler calls setLinkStatus(PENDING) directly (urgent).
+  // Atomic clear: TransitionRoot calls resetLinkPending(navId) inside
+  // startTransition — batched with the new tree commit.
+  //
+  // See design/19-client-navigation.md §"Per-Link Pending State"
+  const [linkStatus, setLinkStatus] = useState(IDLE_LINK_STATUS);
+
+  // Build the link instance ref for the pending store.
+  // The ref is stable across renders — we update the setter on each
+  // render to keep it current.
+  const linkInstanceRef = useRef<LinkPendingInstance | null>(null);
+  if (!linkInstanceRef.current) {
+    linkInstanceRef.current = { setLinkStatus };
+  } else {
+    linkInstanceRef.current.setLinkStatus = setLinkStatus;
+  }
+
+  // Clean up if this link unmounts while it's the current navigation link.
+  // Prevents calling setOptimistic on an unmounted component.
+  useEffect(() => {
+    const instance = linkInstanceRef.current;
+    return () => {
+      if (instance) {
+        unmountLinkForCurrentNavigation(instance);
+      }
+    };
+  }, []);
+
+  // Preserve search params from the current URL when requested.
+  // useSearchParams() works during both SSR (reads from request context)
+  // and on the client (reads from window.location, reactive to URL changes).
+  // We read current search params directly to avoid unconditional hook calls.
+  // On the client, window.location.search is always current; during SSR,
+  // getSsrData() provides the request's search params.
+  const resolvedHref = preserveSearchParams
+    ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+    : baseHref;
+
   const internal = isInternalHref(resolvedHref);
 
   // ─── Click handler ───────────────────────────────────────────
@@ -335,7 +425,11 @@ export function Link({
         // Call onNavigate if provided — allows caller to cancel
         if (onNavigate) {
           let prevented = false;
-          onNavigate({ preventDefault: () => { prevented = true; } });
+          onNavigate({
+            preventDefault: () => {
+              prevented = true;
+            },
+          });
           if (prevented) {
             event.preventDefault();
             return;
@@ -347,24 +441,45 @@ export function Link({
 
         event.preventDefault();
         const shouldScroll = scroll !== false;
-        void router.navigate(resolvedHref, { scroll: shouldScroll });
+
+        // Re-merge preserved search params at click time to pick up any
+        // URL changes since render (e.g. from other navigations or pushState).
+        const navHref = preserveSearchParams
+          ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+          : resolvedHref;
+
+        // Eagerly show pending state on this link (urgent update, immediate).
+        // Only this Link re-renders — all other Links are unaffected.
+        setLinkStatus(PENDING_LINK_STATUS);
+
+        // Register this link in the pending store so TransitionRoot can
+        // reset it to IDLE inside startTransition (atomic with new tree).
+        // Also resets any previous pending link to IDLE.
+        setLinkForCurrentNavigation(linkInstanceRef.current);
+
+        void router.navigate(navHref, { scroll: shouldScroll });
       }
     : userOnClick; // External links — just pass through user's onClick
 
   // ─── Hover prefetch ──────────────────────────────────────────
-  const handleMouseEnter = internal && prefetch
-    ? (event: ReactMouseEvent<HTMLAnchorElement>) => {
-        userOnMouseEnter?.(event);
-        const router = getRouterOrNull();
-        if (router) {
-          router.prefetch(resolvedHref);
+  const handleMouseEnter =
+    internal && prefetch
+      ? (event: ReactMouseEvent<HTMLAnchorElement>) => {
+          userOnMouseEnter?.(event);
+          const router = getRouterOrNull();
+          if (router) {
+            // Re-merge preserved search params at hover time for fresh prefetch URL
+            const prefetchHref = preserveSearchParams
+              ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+              : resolvedHref;
+            router.prefetch(prefetchHref);
+          }
         }
-      }
-    : userOnMouseEnter;
+      : userOnMouseEnter;
 
   return (
     <a {...rest} href={resolvedHref} onClick={handleClick} onMouseEnter={handleMouseEnter}>
-      <LinkStatusProvider href={resolvedHref}>{children}</LinkStatusProvider>
+      <LinkStatusContext.Provider value={linkStatus}>{children}</LinkStatusContext.Provider>
     </a>
   );
 }

package/src/client/navigation-context.ts

@@ -5,7 +5,7 @@
  *
  * Holds the current route params and pathname, updated atomically
  * with the RSC tree on each navigation. This replaces the previous
- * useSyncExternalStore approach for useParams() and usePathname(),
+ * useSyncExternalStore approach for useSegmentParams() and usePathname(),
  * which suffered from a timing gap: the new tree could commit before
  * the external store re-renders fired, causing a frame where both
  * old and new active states were visible simultaneously.
@@ -63,7 +63,7 @@ export interface NavigationState {
  * variables) because the ESM bundler can duplicate this module across
  * chunks. Module-level variables would create separate instances per
  * chunk — the provider in TransitionRoot (index chunk) would use
- * context A while the consumer in LinkStatusProvider (shared chunk)
+ * context A while the consumer in useNavigationPending (shared chunk)
  * reads from context B. globalThis guarantees a single instance.
  *
  * See design/27-chunking-strategy.md §"Singleton Safety"
@@ -90,7 +90,7 @@ function getOrCreateContext(): React.Context<NavigationState | null> | undefined
 /**
  * Read the navigation context. Returns null during SSR (no provider)
  * or in the RSC environment (no context available).
- * Internal — used by useParams() and usePathname().
+ * Internal — used by useSegmentParams() and usePathname().
  */
 export function useNavigationContext(): NavigationState | null {
   const ctx = getOrCreateContext();
@@ -168,8 +168,9 @@ export function getNavigationState(): NavigationState {
 
 /**
  * Separate context for the in-flight navigation URL. Provided by
- * TransitionRoot (urgent useState), consumed by LinkStatusProvider
- * and useNavigationPending.
+ * TransitionRoot (urgent useState), consumed by useNavigationPending
+ * and TopLoader. Per-link pending state uses useOptimistic instead
+ * (see link-pending-store.ts).
  *
  * Uses globalThis via Symbol.for for the same reason as NavigationContext
  * above — the bundler may duplicate this module across chunks, and module-

package/src/client/router.ts

@@ -6,13 +6,18 @@ import type { SegmentInfo } from './segment-cache';
 import { HistoryStack } from './history';
 import type { HeadElement } from './head';
 import { setCurrentParams } from './use-params.js';
-import { setNavigationState } from './navigation-context.js';
 import {
-  SegmentElementCache,
-  cacheSegmentElements,
-  mergeSegmentTree,
-} from './segment-merger.js';
-import { fetchRscPayload, RedirectError } from './rsc-fetch.js';
+  setNavigationState,
+  getNavigationState,
+  type NavigationState,
+} from './navigation-context.js';
+import { SegmentElementCache, cacheSegmentElements, mergeSegmentTree } from './segment-merger.js';
+import {
+  fetchRscPayload,
+  RedirectError,
+  ServerErrorResponse,
+  VersionSkewError,
+} from './rsc-fetch.js';
 import type { FetchResult } from './rsc-fetch.js';
 
 // ─── Types ───────────────────────────────────────────────────────
@@ -35,8 +40,12 @@ export type RscDecoder = (fetchPromise: Promise<Response>) => unknown;
  * Function that renders a decoded RSC element tree into the DOM.
  * In production: reactRoot.render(element).
  * In tests: a no-op or mock.
+ *
+ * Receives the current NavigationState explicitly — no temporal
+ * coupling with setNavigationState/getNavigationState. The renderer
+ * wraps the element in NavigationProvider with this state.
  */
-export type RootRenderer = (element: unknown) => void;
+export type RootRenderer = (element: unknown, navState: NavigationState) => void;
 
 /**
  * Platform dependencies injected for testability. In production these
@@ -68,13 +77,17 @@ export interface RouterDeps {
    *
    * The `perform` callback receives a `wrapPayload` function to wrap the
    * decoded RSC payload with NavigationProvider + NuqsAdapter before
-   * TransitionRoot sets it as the new element.
+   * TransitionRoot sets it as the new element. The `wrapPayload` function
+   * receives the NavigationState explicitly — no temporal coupling with
+   * getNavigationState().
    *
    * If not provided (tests), the router falls back to renderRoot.
    */
   navigateTransition?: (
     pendingUrl: string,
-    perform: (wrapPayload: (payload: unknown) => unknown) => Promise<unknown>
+    perform: (
+      wrapPayload: (payload: unknown, navState: NavigationState) => unknown
+    ) => Promise<unknown>
   ) => Promise<void>;
 }
 
@@ -134,21 +147,40 @@ function isAbortError(error: unknown): boolean {
  * Create a router instance. In production, called once at app hydration
  * with real browser APIs. In tests, called with mock dependencies.
  */
+/**
+ * Router navigation phase — discriminated union replacing scattered
+ * `pending` + `pendingUrl` boolean flags.
+ *
+ * - `idle`: No navigation in flight. The committed params/pathname
+ *   are current.
+ * - `navigating`: A fetch or render is in progress. `targetUrl` is
+ *   the destination being navigated to.
+ */
+export type RouterPhase = { phase: 'idle' } | { phase: 'navigating'; targetUrl: string };
+
 export function createRouter(deps: RouterDeps): RouterInstance {
   const segmentCache = new SegmentCache();
   const prefetchCache = new PrefetchCache();
   const historyStack = new HistoryStack();
   const segmentElementCache = new SegmentElementCache();
 
-  let pending = false;
-  let pendingUrl: string | null = null;
+  let routerPhase: RouterPhase = { phase: 'idle' };
   const pendingListeners = new Set<(pending: boolean) => void>();
 
   function setPending(value: boolean, url?: string): void {
-    const newPendingUrl = value && url ? url : null;
-    if (pending === value && pendingUrl === newPendingUrl) return;
-    pending = value;
-    pendingUrl = newPendingUrl;
+    const next: RouterPhase =
+      value && url ? { phase: 'navigating', targetUrl: url } : { phase: 'idle' };
+    // Skip no-op updates
+    if (
+      routerPhase.phase === next.phase &&
+      (routerPhase.phase === 'idle' ||
+        (routerPhase.phase === 'navigating' &&
+          next.phase === 'navigating' &&
+          routerPhase.targetUrl === next.targetUrl))
+    ) {
+      return;
+    }
+    routerPhase = next;
     // Notify external store listeners (non-React consumers).
     // React-facing pending state is handled by useOptimistic in
     // TransitionRoot via navigateTransition — not this function.
@@ -167,9 +199,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   }
 
   /** Render a decoded RSC payload into the DOM if a renderer is available. */
-  function renderPayload(payload: unknown): void {
+  function renderPayload(payload: unknown, navState: NavigationState): void {
     if (deps.renderRoot) {
-      deps.renderRoot(payload);
+      deps.renderRoot(payload, navState);
     }
   }
 
@@ -198,32 +230,34 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   /**
    * Update navigation state (params + pathname) for the next render.
    *
-   * Sets both the module-level fallback (for tests and SSR) and the
-   * navigation context state (read by renderRoot to wrap the element
-   * in NavigationProvider). The context update is atomic with the tree
-   * render — both are passed to reactRoot.render() in the same call.
+   * Sets the module-level fallback (for tests and SSR) and the
+   * globalThis bridge, then returns the NavigationState so callers
+   * can pass it explicitly to renderRoot/wrapPayload — eliminating
+   * temporal coupling with getNavigationState().
    */
   function updateNavigationState(
     params: Record<string, string | string[]> | null | undefined,
     url: string
-  ): void {
+  ): NavigationState {
     const resolvedParams = params ?? {};
     // Module-level fallback for tests (no NavigationProvider) and SSR
     setCurrentParams(resolvedParams);
-    // Navigation context — read by renderRoot to wrap the RSC element
+    // globalThis bridge — kept for backward compat
     const pathname = url.startsWith('http') ? new URL(url).pathname : url.split('?')[0] || '/';
-    setNavigationState({ params: resolvedParams, pathname });
+    const navState: NavigationState = { params: resolvedParams, pathname };
+    setNavigationState(navState);
+    return navState;
   }
 
   /**
    * Render a payload via navigateTransition (production) or renderRoot (tests).
-   * The perform callback should fetch data, update state, and return the payload.
-   * In production, the entire callback runs inside a React transition with
-   * useOptimistic for the pending URL. In tests, the payload is rendered directly.
+   * The perform callback should fetch data, update state, and return the
+   * FetchResult plus the NavigationState (so it can be passed explicitly
+   * to wrapPayload/renderRoot without temporal coupling).
    */
   async function renderViaTransition(
     url: string,
-    perform: () => Promise<FetchResult>
+    perform: () => Promise<FetchResult & { navState: NavigationState }>
   ): Promise<HeadElement[] | null> {
     if (deps.navigateTransition) {
       let headElements: HeadElement[] | null = null;
@@ -239,7 +273,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           headElements: result.headElements,
           params: result.params,
         });
-        return wrapPayload(merged);
+        // Pass navState explicitly — wrapPayload wraps element in
+        // NavigationProvider with this state, no getNavigationState() needed.
+        return wrapPayload(merged, result.navState);
       });
       return headElements;
     }
@@ -253,7 +289,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       headElements: result.headElements,
       params: result.params,
     });
-    renderPayload(merged);
+    renderPayload(merged, result.navState);
     return result.headElements;
   }
 
@@ -273,6 +309,17 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
   }
 
+  /**
+   * Schedule scroll restoration after the next paint and fire the
+   * scroll-restored event. Used by navigate, popstate, and refresh.
+   */
+  function restoreScrollAfterPaint(scrollY: number): void {
+    afterPaint(() => {
+      deps.scrollTo(0, scrollY);
+      window.dispatchEvent(new Event('timber:scroll-restored'));
+    });
+  }
+
   /**
    * Core navigation logic shared between the transition and fallback paths.
    * Fetches the RSC payload, updates all state, and returns the result.
@@ -280,7 +327,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   async function performNavigationFetch(
     url: string,
     options: { replace: boolean }
-  ): Promise<FetchResult> {
+  ): Promise<FetchResult & { navState: NavigationState }> {
     // Check prefetch cache first. PrefetchResult has optional segmentInfo/params
     // fields — normalize to null for FetchResult compatibility.
     const prefetched = prefetchCache.consume(url);
@@ -320,10 +367,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     // Update the segment cache with the new route's segment tree.
     updateSegmentCache(result.segmentInfo);
 
-    // Update navigation state (params + pathname) before rendering.
-    updateNavigationState(result.params, url);
+    // Update navigation state and capture it for explicit passing.
+    const navState = updateNavigationState(result.params, url);
 
-    return result;
+    return { ...result, navState };
   }
 
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
@@ -354,21 +401,31 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Scroll-to-top on forward navigation, or restore captured position
       // for scroll={false}. React's render() on the document root can reset
       // scroll during DOM reconciliation, so all scroll must be actively managed.
-      afterPaint(() => {
-        if (scroll) {
-          deps.scrollTo(0, 0);
-        } else {
-          deps.scrollTo(0, currentScrollY);
-        }
-        window.dispatchEvent(new Event('timber:scroll-restored'));
-      });
+      restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
     } catch (error) {
+      // Version skew — server has been redeployed. Trigger full page reload
+      // so the browser fetches the new bundle. See TIM-446.
+      if (error instanceof VersionSkewError) {
+        // Import triggerStaleReload dynamically to avoid circular deps
+        // and keep the reload logic centralized with its loop guard.
+        const { triggerStaleReload } = await import('./stale-reload.js');
+        triggerStaleReload();
+        // Return a never-resolving promise — page is reloading.
+        return new Promise(() => {}) as never;
+      }
       // Server-side redirect during RSC fetch → soft router navigation.
       if (error instanceof RedirectError) {
         setPending(false);
         await navigate(error.redirectUrl, { replace: true });
         return;
       }
+      // Server 5xx error — hard-navigate so the server renders the
+      // error page as HTML. See design/10-error-handling.md
+      // §"Error Page Rendering for Client Navigation".
+      if (error instanceof ServerErrorResponse) {
+        window.location.href = error.url;
+        return new Promise(() => {}) as never;
+      }
       // Abort errors are not application errors — swallow silently.
       if (isAbortError(error)) return;
       throw error;
@@ -388,8 +445,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         const result = await fetchRscPayload(currentUrl, deps);
         // History push handled by renderViaTransition (stores merged payload)
         updateSegmentCache(result.segmentInfo);
-        updateNavigationState(result.params, currentUrl);
-        return result;
+        const navState = updateNavigationState(result.params, currentUrl);
+        return { ...result, navState };
       });
 
       applyHead(headElements);
@@ -406,13 +463,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
     if (entry && entry.payload !== null) {
       // Replay cached payload — no server roundtrip
-      updateNavigationState(entry.params, url);
-      renderPayload(entry.payload);
+      const navState = updateNavigationState(entry.params, url);
+      renderPayload(entry.payload, navState);
       applyHead(entry.headElements);
-      afterPaint(() => {
-        deps.scrollTo(0, scrollY);
-        window.dispatchEvent(new Event('timber:scroll-restored'));
-      });
+      restoreScrollAfterPaint(scrollY);
     } else {
       // No cached payload — fetch from server.
       // This happens when navigating back to the initial SSR'd page
@@ -421,19 +475,18 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       setPending(true, url);
       try {
         const headElements = await renderViaTransition(url, async () => {
-          const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
+          const stateTree = segmentCache.serializeStateTree(
+            segmentElementCache.getMergeablePaths()
+          );
           const result = await fetchRscPayload(url, deps, stateTree);
           updateSegmentCache(result.segmentInfo);
-          updateNavigationState(result.params, url);
+          const navState = updateNavigationState(result.params, url);
           // History push handled by renderViaTransition (stores merged payload)
-          return result;
+          return { ...result, navState };
         });
 
         applyHead(headElements);
-        afterPaint(() => {
-          deps.scrollTo(0, scrollY);
-          window.dispatchEvent(new Event('timber:scroll-restored'));
-        });
+        restoreScrollAfterPaint(scrollY);
       } finally {
         setPending(false);
       }
@@ -465,8 +518,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     navigate,
     refresh,
     handlePopState,
-    isPending: () => pending,
-    getPendingUrl: () => pendingUrl,
+    isPending: () => routerPhase.phase === 'navigating',
+    getPendingUrl: () => (routerPhase.phase === 'navigating' ? routerPhase.targetUrl : null),
     onPendingChange(listener) {
       pendingListeners.add(listener);
       return () => pendingListeners.delete(listener);
@@ -483,7 +536,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         payload: merged,
         headElements,
       });
-      renderPayload(merged);
+      // Revalidation doesn't change params/pathname — preserve current state.
+      // DO NOT call updateNavigationState(null, ...) here: that normalizes
+      // params to {}, clearing dynamic route params on every action response.
+      const navState = getNavigationState();
+      renderPayload(merged, navState);
       applyHead(headElements);
     },
     initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),