@timber-js/app 0.2.0-alpha.34 → 0.2.0-alpha.35

package/src/client/browser-entry.ts

@@ -47,6 +47,7 @@ import {
   NavigationProvider,
   getNavigationState,
   setNavigationState,
+  type NavigationState,
 } from './navigation-context.js';
 import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.js';
 // browser-links.ts removed — Link components own their click/hover handlers directly.
@@ -54,9 +55,16 @@ import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.
 import { TransitionRoot, transitionRender, navigateTransition } from './transition-root.js';
 import {
   isStaleClientReference,
+  isChunkLoadError,
   triggerStaleReload,
   clearStaleReloadFlag,
 } from './stale-reload.js';
+import {
+  setClientDeploymentId,
+  getClientDeploymentId,
+  DEPLOYMENT_ID_HEADER,
+  RELOAD_HEADER,
+} from './rsc-fetch.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -85,14 +93,28 @@ setServerCallback(async (id: string, args: unknown[]) => {
   let hasRedirect = false;
   let headElementsJson: string | null = null;
 
+  // Build action request headers. Include deployment ID for version
+  // skew detection (TIM-446) — the server rejects stale actions gracefully.
+  const actionHeaders: Record<string, string> = {
+    'Accept': 'text/x-component',
+    'x-rsc-action': id,
+  };
+  const actionDeploymentId = getClientDeploymentId();
+  if (actionDeploymentId) {
+    actionHeaders[DEPLOYMENT_ID_HEADER] = actionDeploymentId;
+  }
+
   const response = fetch(window.location.href, {
     method: 'POST',
-    headers: {
-      'Accept': 'text/x-component',
-      'x-rsc-action': id,
-    },
+    headers: actionHeaders,
     body,
   }).then((res) => {
+    // Version skew detection (TIM-446): if the server signals a reload,
+    // trigger a full page load to pick up the new deployment.
+    if (res.headers.get(RELOAD_HEADER) === '1') {
+      window.location.reload();
+      throw new Error('Version skew detected — reloading page');
+    }
     hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
     hasRedirect = res.headers.get('X-Timber-Redirect') != null;
     headElementsJson = res.headers.get('X-Timber-Head');
@@ -183,6 +205,13 @@ function getScrollY(): number {
 function bootstrap(runtimeConfig: typeof config): void {
   const _config = runtimeConfig;
 
+  // Initialize deployment ID for version skew detection (TIM-446).
+  // In dev mode this is null — skew checks are skipped.
+  const deploymentId = (_config as Record<string, unknown>).deploymentId as string | null;
+  if (deploymentId) {
+    setClientDeploymentId(deploymentId);
+  }
+
   // Take manual control of scroll restoration. Even though segment tree
   // merging preserves shared layout DOM via cloneElement (so React doesn't
   // reset scroll on those elements), the root-level reactRoot.render() with
@@ -319,7 +348,7 @@ function bootstrap(runtimeConfig: typeof config): void {
 
     // ── Initialize navigation state BEFORE hydration ───────────────────
     // Read server-embedded params and set navigation state so that
-    // useParams() and usePathname() return correct values during hydration.
+    // useSegmentParams() and usePathname() return correct values during hydration.
     // This must happen before hydrateRoot so the NavigationProvider
     // wrapping the element has the right values on the initial render.
     const earlyParams = (self as unknown as Record<string, unknown>).__timber_params;
@@ -443,8 +472,10 @@ function bootstrap(runtimeConfig: typeof config): void {
       // For navigation renders (navigate, refresh, popstate-with-fetch),
       // navigateTransition is used instead — it wraps the entire navigation
       // in a React transition with useOptimistic for the pending URL.
-      renderRoot: (element: unknown) => {
-        const navState = getNavigationState();
+      //
+      // navState is passed explicitly by the router — no temporal coupling
+      // with getNavigationState().
+      renderRoot: (element: unknown, navState: NavigationState) => {
         const withNav = createElement(
           NavigationProvider,
           { value: navState },
@@ -460,13 +491,11 @@ function bootstrap(runtimeConfig: typeof config): void {
       // commits (atomic with the new tree + params).
       //
       // The perform callback receives a wrapPayload function that wraps the
-      // decoded RSC payload with NavigationProvider + NuqsAdapter — this must
-      // happen inside the transition so the NavigationProvider reads the
-      // UPDATED navigation state (set by the router inside perform).
+      // decoded RSC payload with NavigationProvider + NuqsAdapter. navState
+      // is passed explicitly by the router — no getNavigationState() needed.
       navigateTransition: (pendingUrl: string, perform) => {
         return navigateTransition(pendingUrl, async () => {
-          const payload = await perform((rawPayload: unknown) => {
-            const navState = getNavigationState();
+          const payload = await perform((rawPayload: unknown, navState: NavigationState) => {
             const withNav = createElement(
               NavigationProvider,
               { value: navState },
@@ -626,8 +655,21 @@ clearStaleReloadFlag();
 // If the payload references a module ID from a newer deployment, the error
 // surfaces as an unhandled rejection during React's render/hydration cycle.
 // This handler catches those errors and triggers a full page reload.
+//
+// Also catches chunk load failures (dynamic import of missing assets after
+// a deployment) — these surface as "Failed to fetch dynamically imported module"
+// or "Loading chunk <name> failed" errors. See TIM-446.
 window.addEventListener('unhandledrejection', (event) => {
-  if (isStaleClientReference(event.reason)) {
+  if (isStaleClientReference(event.reason) || isChunkLoadError(event.reason)) {
+    event.preventDefault();
+    triggerStaleReload();
+  }
+});
+
+// Also catch synchronous errors from chunk loads (some browsers throw
+// TypeError synchronously instead of via unhandled rejection).
+window.addEventListener('error', (event) => {
+  if (isChunkLoadError(event.error)) {
     event.preventDefault();
     triggerStaleReload();
   }

package/src/client/error-boundary.tsx

@@ -65,7 +65,16 @@ type ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;
 
 export interface TimberErrorBoundaryProps {
   /** The component to render when an error is caught. */
-  fallbackComponent: (...args: unknown[]) => ReactNode;
+  fallbackComponent?: (...args: unknown[]) => ReactNode;
+  /**
+   * Pre-rendered fallback element. Used for MDX status files which are server
+   * components and cannot be passed as function props across the RSC→client
+   * boundary. When set, rendered directly instead of calling fallbackComponent.
+   *
+   * See design/10-error-handling.md §"Status-Code File Variants" — MDX status
+   * files are server components by default (zero client JS).
+   */
+  fallbackElement?: ReactNode;
   /**
    * Status code filter. If set, only catches errors matching this status.
    * 400 = any 4xx, 500 = any 5xx, specific number = exact match.
@@ -162,6 +171,14 @@ export class TimberErrorBoundary extends Component<
       }
     }
 
+    // Pre-rendered fallback element (MDX status files) — render directly.
+    // MDX components are server components that cannot be passed as function
+    // props across the RSC→client boundary. Instead, they are pre-rendered
+    // as elements in the RSC environment and passed here as fallbackElement.
+    if (this.props.fallbackElement != null) {
+      return this.props.fallbackElement;
+    }
+
     // Render the fallback component with the right props shape.
     if (parsed?.type === 'deny') {
       return createElement(this.props.fallbackComponent as never, {

package/src/client/index.ts

@@ -12,6 +12,7 @@ export type {
   RouterInstance,
   NavigationOptions,
   RouterDeps,
+  RouterPhase,
   RscDecoder,
   RootRenderer,
 } from './router';
@@ -42,7 +43,7 @@ export { useActionState, useFormAction, useFormErrors } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
 
 // Params
-export { useParams, setCurrentParams } from './use-params';
+export { useSegmentParams, setCurrentParams } from './use-params';
 
 // Navigation context (framework-internal, used by browser-entry for atomic updates)
 export { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context';
@@ -55,6 +56,13 @@ export { useQueryStates, bindUseQueryStates } from './use-query-states';
 export { useCookie } from './use-cookie';
 export type { ClientCookieOptions, CookieSetter } from './use-cookie';
 
+// Register the client cookie module with defineCookie's lazy reference.
+// This runs at module load time in the client/SSR environment, wiring up
+// the useCookie hook without a top-level import in define-cookie.ts.
+import * as _useCookieMod from './use-cookie.js';
+import { _registerUseCookieModule } from '#/cookies/define-cookie.js';
+_registerUseCookieModule(_useCookieMod);
+
 // SSR data (framework-internal, used by ssr-entry to provide request data to hooks)
 export { setSsrData, clearSsrData, getSsrData } from './ssr-data';
 export type { SsrData } from './ssr-data';

package/src/client/link.tsx

@@ -19,7 +19,7 @@
 // - 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 type { SearchParamsDefinition } from '#/search-params/define.js';
 import { LinkStatusProvider } from './link-status-provider.js';
 import { getRouterOrNull } from './router-ref.js';
 
@@ -61,7 +61,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 +73,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 +85,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,14 +303,14 @@ 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,
   onNavigate,
   onClick: userOnClick,
@@ -318,7 +318,7 @@ export function Link({
   children,
   ...rest
 }: LinkProps) {
-  const { href: resolvedHref } = buildLinkProps({ href, params, searchParams });
+  const { href: resolvedHref } = buildLinkProps({ href, params: segmentParams, searchParams });
   const internal = isInternalHref(resolvedHref);
 
   // ─── Click handler ───────────────────────────────────────────

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.
@@ -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();

package/src/client/router.ts

@@ -6,9 +6,13 @@ 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 {
+  setNavigationState,
+  getNavigationState,
+  type NavigationState,
+} from './navigation-context.js';
 import { SegmentElementCache, cacheSegmentElements, mergeSegmentTree } from './segment-merger.js';
-import { fetchRscPayload, RedirectError } from './rsc-fetch.js';
+import { fetchRscPayload, RedirectError, VersionSkewError } from './rsc-fetch.js';
 import type { FetchResult } from './rsc-fetch.js';
 
 // ─── Types ───────────────────────────────────────────────────────
@@ -31,8 +35,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
@@ -64,13 +72,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>;
 }
 
@@ -130,21 +142,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.
@@ -163,9 +194,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);
     }
   }
 
@@ -194,32 +225,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;
@@ -235,7 +268,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;
     }
@@ -249,7 +284,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       headElements: result.headElements,
       params: result.params,
     });
-    renderPayload(merged);
+    renderPayload(merged, result.navState);
     return result.headElements;
   }
 
@@ -269,6 +304,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.
@@ -276,7 +322,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);
@@ -316,10 +362,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> {
@@ -350,15 +396,18 @@ 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);
@@ -384,8 +433,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);
@@ -402,13 +451,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
@@ -422,16 +468,13 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           );
           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);
       }
@@ -463,8 +506,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);
@@ -481,7 +524,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),