@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/client/navigation-root.tsx

@@ -0,0 +1,580 @@
+/**
+ * NavigationRoot — Wrapper component for transition-based rendering.
+ *
+ * Solves the "new boundary has no old content" problem for client-side
+ * navigation. When React renders a completely new Suspense boundary via
+ * root.render(), it shows the fallback immediately — root.render() is
+ * always an urgent update regardless of startTransition.
+ *
+ * NavigationRoot holds the current element in React state. Navigation
+ * updates call startTransition(() => setState(newElement)), which IS
+ * a transition update. React keeps the old committed tree visible while
+ * the new tree resolves, instead of hiding it behind a Suspense fallback.
+ *
+ * The navigation's async work runs OUTSIDE the transition scope and every
+ * state update it schedules gets its own synchronous `startTransition` — a
+ * transition scope does not survive an `await`, and an async callback that
+ * returns a thenable defers the commit past the promise callers await. See
+ * the long comment on `_navigateTransition` (TIM-1306).
+ *
+ * This component holds no pending state. The `TopLoader` it renders and the
+ * public `usePendingNavigation()` both subscribe to the router's external
+ * pending store; NavigationRoot's own `pendingUrl` was a second, unread
+ * representation of the same fact and is gone (TIM-1307).
+ *
+ * Hard navigation guard: When a hard navigation is triggered (500 error,
+ * version skew), the component throws an unresolved thenable AFTER all
+ * hooks to suspend forever — preventing React from rendering children
+ * during page teardown. The throw must come after hooks to satisfy
+ * React's rules (same hook count every render) while still preventing
+ * child renders that could hit hook count mismatches in components
+ * whose positions shift during teardown. This pattern is borrowed from
+ * Next.js (app-router.tsx pushRef.mpaNavigation — also after hooks).
+ *
+ * See design/05-streaming.md §"deferSuspenseFor"
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+
+import {
+  createElement,
+  Fragment,
+  startTransition,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import { TopLoader, type TopLoaderConfig } from './top-loader.js';
+
+// ─── Transition Result ──────────────────────────────────────────
+
+/**
+ * What a navigation's `perform()` hands back to the transition.
+ *
+ * Declared once and shared by every layer that passes it along — the router's
+ * `RouterDeps.navigateTransition` imports it too — so a field cannot be added
+ * to the producer and dropped by the adapter in between. `E` is the element
+ * type: `ReactNode` here, `unknown` in the router, which never touches it.
+ */
+export interface TransitionResult<E = ReactNode> {
+  /** The wrapped tree to render. */
+  element: E;
+  /** Resolves when the Flight stream finishes decoding, or null. */
+  decodePromise: Promise<void> | null;
+  /**
+   * Publishes the navigation's state — segment cache, pathname, address bar,
+   * history stack, and the client's record of the mounted tree — and
+   * announces it to listeners outside React.
+   *
+   * Run when React commits this tree, not when the tree is handed over: a
+   * tree React is still waiting on, or one a later navigation replaces first,
+   * has been given to React without being on screen. A superseded navigation
+   * never runs it and leaves every one of those consumers describing the
+   * route still on screen (TIM-1301).
+   */
+  commit: () => void;
+}
+
+/**
+ * The tree NavigationRoot holds in state, and the state publish that belongs
+ * to it. They travel as one object so React's commit of the tree is the event
+ * that publishes — see the effect in NavigationRoot.
+ */
+interface RenderedTree {
+  element: ReactNode;
+  publish: (() => void) | null;
+}
+
+// ─── Navigation Transition Counter ──────────────────────────────
+// Monotonically increasing counter that increments each time
+// navigateTransition() is called. Used to detect stale transitions:
+// if a newer transition started while the current one's perform()
+// was in flight, the current transition is stale and should reject.
+//
+// Separate from the link-pending navId (which only increments on
+// link clicks). This counter covers all navigation types: link clicks,
+// programmatic navigate(), refresh(), and handlePopState().
+//
+// Uses globalThis for singleton guarantee across chunks — same pattern
+// as NavigationContext and the link pending store.
+
+const NAV_TRANSITION_KEY = Symbol.for('__timber_nav_transition_counter');
+
+/**
+ * `waiters` are woken on every bump so an in-flight navigation can stop
+ * waiting on its own payload the moment it is superseded — see
+ * `settleOnDecodeOrSupersession`.
+ */
+interface TransitionCounter {
+  id: number;
+  waiters: Set<() => void>;
+}
+
+function getTransitionCounter(): TransitionCounter {
+  const g = globalThis as Record<symbol, unknown>;
+  const existing = g[NAV_TRANSITION_KEY] as Partial<TransitionCounter> | undefined;
+  if (!existing) {
+    const created: TransitionCounter = { id: 0, waiters: new Set() };
+    g[NAV_TRANSITION_KEY] = created;
+    return created;
+  }
+  // A duplicated copy of this module may have created the singleton before
+  // `waiters` existed. The object is shared across chunks, so fill it in
+  // rather than replacing it — replacing would strand the other copy's id.
+  existing.waiters ??= new Set();
+  return existing as TransitionCounter;
+}
+
+/** Bump the counter and wake everything waiting on an older transition. */
+function bumpTransitionCounter(): number {
+  const counter = getTransitionCounter();
+  counter.id += 1;
+  for (const wake of [...counter.waiters]) wake();
+  return counter.id;
+}
+
+/**
+ * Invalidate all in-flight navigation transitions. Any navigateTransition()
+ * call whose perform() has not yet committed will reject with AbortError
+ * instead of committing its element.
+ *
+ * Called by the router when a render supersedes in-flight navigations
+ * WITHOUT going through navigateTransition() — the cached popstate replay
+ * renders via transitionRender(), which doesn't bump the counter, so a
+ * stale forward navigation's setElement would otherwise pass the
+ * `counter.id !== transId` guard and commit the forward page over the
+ * replayed back page (TIM-1022).
+ */
+export function supersedeNavigationTransitions(): void {
+  bumpTransitionCounter();
+}
+
+/**
+ * Wait for the payload to finish decoding, OR for this transition to be
+ * superseded — whichever happens first.
+ *
+ * A superseded navigation must stop waiting on its own stream. The stream is
+ * deliberately NOT aborted once its tree has been handed to React (the tree
+ * may be on screen with boundaries still feeding from it — see
+ * `handedOffNavAbort` in `client/router.ts`), so there is nothing left to make
+ * `decodePromise` settle promptly. Awaiting it bare would keep the loser's
+ * `router.navigate()` promise pending for the rest of the stream — and
+ * forever if it stalls — which is what `<Link>`'s `isPending` is timed
+ * against, so the losing link would sit spinning while the winner loaded
+ * (codex on #1004).
+ *
+ * A decode *failure* still propagates: it is a real error for this
+ * navigation, and the caller's recovery is timed against it.
+ */
+function settleOnDecodeOrSupersession(
+  decodePromise: Promise<void>,
+  counter: TransitionCounter,
+  transId: number
+): Promise<void> {
+  if (counter.id !== transId) return Promise.resolve();
+  return new Promise<void>((resolve, reject) => {
+    const stopWaiting = (): void => {
+      counter.waiters.delete(wake);
+    };
+    const wake = (): void => {
+      if (counter.id !== transId) {
+        stopWaiting();
+        resolve();
+      }
+    };
+    counter.waiters.add(wake);
+    decodePromise.then(
+      () => {
+        stopWaiting();
+        resolve();
+      },
+      (error: unknown) => {
+        stopWaiting();
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    );
+  });
+}
+
+// ─── Hard Navigation Guard ──────────────────────────────────────
+
+/**
+ * Module-level flag indicating a hard (MPA) navigation is in progress.
+ *
+ * When true:
+ * - NavigationRoot throws an unresolved thenable to suspend forever,
+ *   preventing React from rendering children during page teardown
+ *   (avoids "Rendered more hooks" crashes).
+ * - The Navigation API handler skips interception, letting the browser
+ *   perform a full page load (prevents infinite loops where
+ *   window.location.href → navigate event → router.navigate → 500 →
+ *   window.location.href → ...).
+ *
+ * Uses globalThis for singleton guarantee across chunks (same pattern
+ * as NavigationContext). See design/19-client-navigation.md §"Singleton
+ * Guarantee via globalThis".
+ */
+const HARD_NAV_KEY = Symbol.for('__timber_hard_navigating');
+
+function getHardNavStore(): { value: boolean } {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[HARD_NAV_KEY]) {
+    g[HARD_NAV_KEY] = { value: false };
+  }
+  return g[HARD_NAV_KEY] as { value: boolean };
+}
+
+/**
+ * Set the hard-navigating flag. Call this BEFORE setting
+ * window.location.href or window.location.reload() to prevent:
+ * 1. React from rendering children during page teardown
+ * 2. Navigation API from intercepting the hard navigation
+ */
+export function setHardNavigating(value: boolean): void {
+  getHardNavStore().value = value;
+}
+
+/**
+ * Check if a hard navigation is in progress.
+ * Used by NavigationRoot (throw unresolvedThenable) and by the
+ * Navigation API handler (skip interception).
+ */
+export function isHardNavigating(): boolean {
+  return getHardNavStore().value;
+}
+
+/**
+ * A thenable that never resolves. When thrown during React render,
+ * it causes the component to suspend forever — React keeps the
+ * old committed tree visible and never attempts to render children.
+ *
+ * This is the same pattern Next.js uses in app-router.tsx for MPA
+ * navigations (pushRef.mpaNavigation → throw unresolvedThenable).
+ */
+// for React's Suspense mechanism. Same pattern as Next.js's unresolvedThenable.
+// eslint-disable-next-line unicorn/no-thenable -- Intentionally a never-resolving thenable
+const unresolvedThenable = { then() {} } as PromiseLike<never>;
+
+// ─── Module-level functions ──────────────────────────────────────
+
+/**
+ * Module-level reference to the state setter wrapped in startTransition.
+ * Used for non-navigation renders (applyRevalidation, popstate replay).
+ */
+let _transitionRender: ((element: ReactNode) => void) | null = null;
+
+/**
+ * Module-level reference to the navigation transition function.
+ *
+ * Runs the fetch OUTSIDE any transition scope and wraps only the state update
+ * that hands the resulting tree to React — describing this as "a full
+ * navigation in a single startTransition" is the shape TIM-1306 removed.
+ */
+let _navigateTransition:
+  | ((url: string, perform: () => Promise<TransitionResult>) => Promise<void>)
+  | null = null;
+
+// ─── Component ───────────────────────────────────────────────────
+
+/**
+ * Root wrapper component that enables transition-based rendering.
+ *
+ * Renders the TopLoader alongside the tree it holds in state. Neither adds a
+ * DOM element on the hydration path, so the tree matches the server HTML.
+ *
+ * Usage in browser-entry.ts:
+ *   const rootEl = createElement(NavigationRoot, { initial: wrapped });
+ *   reactRoot = hydrateRoot(document, rootEl);
+ *
+ * Subsequent navigations:
+ *   navigateTransition(url, async () => { fetch; return wrappedElement; });
+ *
+ * Non-navigation renders:
+ *   transitionRender(newWrappedElement);
+ */
+export function NavigationRoot({
+  initial,
+  topLoaderConfig,
+}: {
+  initial: ReactNode;
+  topLoaderConfig?: TopLoaderConfig;
+}): ReactNode {
+  const [rendered, setRendered] = useState<RenderedTree>({ element: initial, publish: null });
+
+  // Publish the navigation's state when React commits its tree — not when the
+  // tree is handed over. A tree React is still waiting on, or one a later
+  // navigation replaces before React renders it, has been *given* to React
+  // without being on screen; publishing then describes a route the user never
+  // saw, which is the defect this ordering exists to prevent (TIM-1301).
+  //
+  // A **layout** effect, so the publish lands before the browser paints and,
+  // more importantly, before every descendant's passive effect. A destination
+  // component that navigates from a mount effect — a redirect guard, a
+  // `refresh()` on mount — would otherwise start its navigation while the
+  // segment cache, address bar and pathname still described the departing
+  // route, and send an X-Timber-State-Tree for a tree that is no longer
+  // mounted (codex on #998).
+  //
+  // Descendant *layout* effects still run first: React runs layout effects
+  // child-before-parent, and the only way to precede them would be a fiber
+  // rendered as an earlier sibling of the payload. That is not free here —
+  // `server/ssr-wrappers.tsx` mirrors this component's fiber shape so `useId`
+  // agrees across hydration, and an extra sibling shifts every id in the
+  // payload subtree. A layout effect that navigates on mount is the price.
+  //
+  // Keyed on the tree object rather than on the effect run. A publish moves
+  // the address bar, which is not idempotent, so any second invocation for the
+  // same tree — an effect re-run React is entitled to perform — must be a
+  // no-op rather than a second history entry.
+  const publishedRef = useRef<RenderedTree | null>(null);
+  useLayoutEffect(() => {
+    if (publishedRef.current === rendered) return;
+    publishedRef.current = rendered;
+    rendered.publish?.();
+  }, [rendered]);
+
+  // NOTE: We use standalone `startTransition` (imported from 'react'),
+  // NOT `useTransition`. The `useTransition` hook's `startTransition`
+  // is tied to a single fiber and tracks one async callback at a time.
+  // When two navigations overlap (click slow-page, then click dashboard),
+  // calling useTransition's startTransition twice with concurrent async
+  // callbacks corrupts React's internal hook tracking — causing
+  // "Rendered more hooks than during the previous render."
+  //
+  // Standalone `startTransition` creates independent transition lanes
+  // for each call, so concurrent navigations don't interfere. We don't
+  // need useTransition's `isPending` — pending state lives in the router's
+  // external store, which TopLoader and usePendingNavigation() subscribe to.
+  //
+  // This matches the Next.js pattern (TIM-625): "No useTransition in
+  // the router at all — only standalone startTransition."
+
+  // Non-navigation render (revalidation, popstate cached replay).
+  // Non-navigation render (revalidation, popstate cached replay). Both publish
+  // synchronously in the router before calling this — neither has an in-flight
+  // window in which it could be superseded — so there is nothing to publish
+  // on commit.
+  _transitionRender = (newElement: ReactNode) => {
+    startTransition(() => {
+      setRendered({ element: newElement, publish: null });
+    });
+  };
+
+  // Full navigation transition.
+  //
+  // The async work runs OUTSIDE any transition scope, and each state update is
+  // its own synchronous `startTransition`. Two React behaviours force that
+  // shape; both were measured on React 19.2.7 (tests/navigation-transition-
+  // suspense.test.ts pins the observable half).
+  //
+  // 1. A transition scope does not survive an `await`. `startTransition`
+  //    restores the previous scope in its `finally`, which for an async
+  //    callback runs when that callback RETURNS — i.e. at its first `await`.
+  //    So an update scheduled past an await inside `startTransition(async …)`
+  //    is an ordinary urgent update:
+  //
+  //      startTransition(() => setEl(x))                     -> 'HOME' held
+  //      startTransition(async () => { await p; setEl(x) })  -> fallback shown
+  //
+  //    Left uncorrected, every navigation whose new tree suspends replaces the
+  //    visible page with a Suspense fallback — the exact thing this component
+  //    exists to prevent (TIM-1306). React documents the caveat under
+  //    `startTransition`: updates after an await need their own transition.
+  //
+  // 2. Re-wrapping *inside* the async callback is not enough. Returning a
+  //    thenable from `startTransition` hands it to `ReactSharedInternals.S`,
+  //    which calls react-dom's `entangleAsyncAction`. That opens an action
+  //    scope: `currentEntangledLane` collects EVERY transition update
+  //    scheduled while the scope is open — including one from a nested,
+  //    fully synchronous `startTransition` — and rendering that lane throws
+  //    `currentEntangledActionThenable`, suspending until the action settles.
+  //    Which is after the promise `navigateTransition` hands back, so a caller
+  //    that awaits a navigation and then reads the DOM sees the departing
+  //    page, and the TIM-1301 publish (a layout effect on the commit) is just
+  //    as late. (Not `ReactSharedInternals.asyncTransitions` — that counter is
+  //    write-only in 19.2.7.)
+  //
+  // No async action is created here, so every navigation commits as soon as
+  // React can render its destination — where TIM-1301 put it. That
+  // now holds for ALL of them. It used not to hold for `<Link>`, which wrapped
+  // `router.navigate()` in its own `useTransition`: that action scope
+  // entangled this component's updates just the same, so a Link navigation
+  // committed only once the payload had finished decoding, and with it
+  // `pushState`, the segment cache and `timber:navigation-end`. Link now calls
+  // `router.navigate()` outside any transition and tracks its own `isPending`
+  // with a plain `useState` (TIM-1307).
+  //
+  // Nothing here may reopen an action scope: no `startTransition` callback in
+  // this path may return a thenable, and no caller may invoke this from inside
+  // a React action scope. That is a rule about `startTransition`, not about
+  // `perform` — `perform` is async by contract and is awaited OUTSIDE any
+  // transition scope, which is exactly why it is safe.
+  //
+  // Standalone `startTransition` rather than `useTransition`'s is still
+  // deliberate — see the TIM-625 note above; each navigation needs an
+  // independent lane.
+  //
+  // `url` is unused: it named the pending state this component used to hold,
+  // and the router already publishes the same URL to its own pending store
+  // before calling here. It stays in the signature because the router's
+  // `RouterDeps.navigateTransition` adapter passes it and the argument reads
+  // at the call site.
+  _navigateTransition = (_url: string, perform: () => Promise<TransitionResult>) => {
+    // Increment the transition counter SYNCHRONOUSLY (before any await). Each
+    // call gets a unique transId; the counter is the same globalThis
+    // singleton, so a newer call always has a higher id.
+    const counter = getTransitionCounter();
+    const transId = bumpTransitionCounter();
+
+    const superseded = () => new DOMException('Navigation superseded', 'AbortError');
+
+    return (async () => {
+      const { element, decodePromise, commit } = await perform();
+      if (counter.id !== transId) {
+        decodePromise?.catch(() => {});
+        throw superseded();
+      }
+      // Hand the tree over with its commit attached. The effect above runs
+      // it if and when React commits this tree, so a navigation that is
+      // superseded while its payload streams publishes nothing (TIM-1301).
+      //
+      // This is THE update that must not hide the departing page (TIM-1306).
+      startTransition(() => {
+        setRendered({ element, publish: commit });
+      });
+      // React may commit the tree before this settles — that is the point:
+      // the destination reveals as React is able to render it
+      // rather than waiting for the whole Flight stream. The await is here so
+      // the promise this function hands back still means "the payload is
+      // decoded", which is what the router's scroll restoration, the
+      // Navigation API deferred and `<Link>`'s `isPending` are timed against.
+      //
+      // ...unless this navigation loses first, in which case it stops waiting
+      // on a stream that is no longer its business. See
+      // `settleOnDecodeOrSupersession`.
+      if (decodePromise) await settleOnDecodeOrSupersession(decodePromise, counter, transId);
+      if (counter.id !== transId) throw superseded();
+    })();
+  };
+
+  // ─── Hard navigation guard ─────────────────────────────────
+  // When a hard navigation is in progress (500 error, version skew),
+  // suspend forever to prevent React from rendering children during
+  // page teardown. This avoids "Rendered more hooks" crashes in
+  // CHILD components whose hook counts may shift during teardown.
+  //
+  // CRITICAL: This throw MUST come AFTER all hooks (the useState,
+  // useRef and useLayoutEffect above). React requires the same hooks
+  // to run on every render. If we threw before hooks, React would see
+  // 0 hooks on the re-render vs 3 on the initial render — triggering
+  // the exact "Rendered more hooks" error we're trying to prevent.
+  //
+  // By placing it after hooks but before the return, all hooks
+  // satisfy React's rules, but the thrown thenable prevents any
+  // children from rendering. Same pattern as Next.js app-router.tsx
+  // (pushRef.mpaNavigation — also placed after all hooks).
+  if (isHardNavigating()) {
+    throw unresolvedThenable;
+  }
+
+  // Inject TopLoader alongside the element tree. It subscribes to the router's
+  // pending store itself, so it takes no props from here beyond its config,
+  // and only it re-renders when a navigation starts or ends. Rendered only
+  // when not explicitly disabled via config.
+  //
+  // This Fragment is a FORK — two children — so it advances React's tree
+  // context and shifts every `useId` below it. `server/ssr-wrappers.tsx`
+  // mirrors it for exactly that reason; a single-child wrapper would not need
+  // a mirror. See tests/ssr-wrapper-parity.test.ts.
+  const showTopLoader = topLoaderConfig?.enabled !== false;
+  if (!showTopLoader) return rendered.element;
+  return createElement(
+    Fragment,
+    null,
+    createElement(TopLoader, { config: topLoaderConfig }),
+    rendered.element
+  );
+}
+
+// ─── Public API ──────────────────────────────────────────────────
+
+/**
+ * Trigger a transition render for non-navigation updates.
+ * React keeps the old committed tree visible while any new Suspense
+ * boundaries in the update resolve.
+ *
+ * Used for: applyRevalidation, popstate replay with cached payload.
+ */
+export function transitionRender(element: ReactNode): void {
+  if (_transitionRender) {
+    _transitionRender(element);
+  }
+}
+
+/**
+ * Run a full navigation, handing its tree to React in a transition.
+ *
+ * The `perform` callback fetches the RSC payload, updates router state, and
+ * returns the wrapped React element. `perform` is async by contract and runs
+ * OUTSIDE any transition scope — only the `setRendered` that hands its result
+ * over is wrapped, in a synchronous `startTransition`.
+ *
+ * Do not call this from inside a React action scope, and never let a
+ * `startTransition` callback in this path return a thenable: either opens an
+ * action scope that entangles the update and defers the commit until the
+ * action settles (TIM-1306, TIM-1307).
+ *
+ * Returns a Promise that resolves when the async work completes — the payload
+ * is fetched, decoded, and handed to React. It does **not** wait for React to
+ * commit the tree, so the state that publishes on that commit (address bar,
+ * segment cache, history entry, pathname) may still be a beat behind when it
+ * resolves. Anything that needs the destination to be current should listen
+ * for `timber:navigation-end`, which is dispatched by the publish itself.
+ *
+ * Awaiting the publish here was tried and rejected: it makes the promise
+ * depend on a React commit, which never arrives if the root unmounts
+ * mid-navigation, and deadlocks any caller that awaits a navigation inside
+ * `act()`.
+ *
+ * Used for: navigate(), refresh(), popstate with fetch.
+ */
+export function navigateTransition(
+  url: string,
+  perform: () => Promise<TransitionResult>
+): Promise<void> {
+  if (_navigateTransition) {
+    return _navigateTransition(url, perform);
+  }
+  // Fallback: no NavigationRoot mounted (shouldn't happen in production).
+  // Nothing can supersede a transition that does not exist, so the commit
+  // runs unconditionally.
+  return perform().then((result) => result.commit());
+}
+
+/**
+ * Install one-shot deferred callbacks for the no-RSC bootstrap path (TIM-600).
+ *
+ * When there's no RSC payload, we can't create a React root immediately —
+ * `createRoot(document).render(...)` would blank the SSR HTML. Instead,
+ * this sets up `_transitionRender` and `_navigateTransition` so that the
+ * first client navigation triggers root creation via `createAndMount`.
+ *
+ * After `createAndMount` runs, NavigationRoot renders and overwrites these
+ * callbacks with its real `startTransition`-based implementations.
+ */
+export function installDeferredNavigation(createAndMount: (initial: ReactNode) => void): void {
+  let mounted = false;
+  const mountOnce = (element: ReactNode) => {
+    if (mounted) return;
+    mounted = true;
+    createAndMount(element);
+  };
+  _transitionRender = (element: ReactNode) => {
+    mountOnce(element);
+  };
+  _navigateTransition = async (_url: string, perform: () => Promise<TransitionResult>) => {
+    const { element, commit } = await perform();
+    commit();
+    mountOnce(element);
+  };
+}

package/src/client/nuqs-adapter.tsx

@@ -20,6 +20,7 @@ import {
   type unstable_AdapterOptions as AdapterOptions,
 } from 'nuqs/adapters/custom';
 import { getRouter } from './router-ref.js';
+import { getNavigationApi } from './navigation-api.js';
 
 // ─── Adapter Hook ─────────────────────────────────────────────────
 
@@ -59,9 +60,21 @@ function useTimberAdapter(_watchKeys: string[]): AdapterInterface {
 
       if (options.shallow) {
         // Shallow: update URL only, no server roundtrip.
-        const method =
-          options.history === 'push' ? window.history.pushState : window.history.replaceState;
-        method.call(window.history, window.history.state, '', url.toString());
+        // When Navigation API is available, use navigation.navigate() with
+        // info: { shallow: true } so the navigate event handler knows to
+        // skip interception. Without this, the navigate event fired by
+        // history.pushState/replaceState would trigger a full RSC fetch.
+        const nav = getNavigationApi();
+        if (nav) {
+          nav.navigate(url.toString(), {
+            history: options.history === 'push' ? 'push' : 'replace',
+            info: { shallow: true },
+          });
+        } else {
+          const method =
+            options.history === 'push' ? window.history.pushState : window.history.replaceState;
+          method.call(window.history, window.history.state, '', url.toString());
+        }
 
         // Update local state to reflect the new URL
         setSearchParams(new URLSearchParams(url.search));