@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/client/navigation-root.tsx

@@ -0,0 +1,236 @@
+/**
+ * NavigationRoot — the component the router renders the page through.
+ *
+ * It is stateless. The router owns the displayed tree and drives React with
+ * `root.render(<NavigationRoot rendered={{ element, publish }} />)` inside a
+ * synchronous `startTransition` (see `client/react-root.ts`). A transition
+ * update keeps the committed tree on screen while the incoming one resolves,
+ * instead of replacing it with a Suspense fallback — the reason this
+ * component exists (TIM-1306).
+ *
+ * It used to hold the tree in `useState` and register `setState` closures
+ * into module globals during render so the router could reach into it, with a
+ * second set of stand-in closures for the window before a root existed
+ * (TIM-600). Inverting that — router calls React, not the reverse — deleted
+ * all of it (TIM-1431). Next.js's `use-action-queue.ts` says it wants this
+ * shape and cannot have it because it must decode Flight during render;
+ * timber decodes in `router-pipeline.ts`, so nothing stands in the way.
+ *
+ * What this component does own is **the commit-time publish**: a navigation's
+ * state (segment cache, address bar, history stack, pathname) is published
+ * from a layout effect keyed on the tree object, so the event that puts a
+ * route on screen is the event that makes it current (TIM-1301). Props work
+ * for that exactly as state did.
+ *
+ * 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, useLayoutEffect, useRef, type ReactNode } from 'react';
+import { TopLoader, type TopLoaderConfig } from './top-loader.tsx';
+
+// ─── Rendered Tree ──────────────────────────────────────────────
+
+/**
+ * The tree the router has handed to React, 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. Every `render` builds a
+ * fresh one, which is what keys that effect: a tree is published once, however
+ * many times React re-runs the effect for it.
+ */
+export interface RenderedTree {
+  element: ReactNode;
+  /**
+   * 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. Runs when React commits
+   * `element`, never before (TIM-1301). Null for a render that has nothing to
+   * publish on commit (hydration, the shallow search re-wrap).
+   */
+  publish: (() => void) | null;
+}
+
+/**
+ * Hand a tree to React in a transition. `publish` runs when React commits it.
+ *
+ * Every path that puts a page on screen goes through one of these — a
+ * navigation, a revalidation, a popstate replay, a shallow search re-wrap —
+ * and it is always a synchronous `startTransition` around `root.render`.
+ * The production one is `createReactRoot().render`.
+ *
+ * `types` are the view transition types this render animates as
+ * (design/37-navigation-api.md §"Transition types"). They are added with
+ * `addTransitionType` inside that same `startTransition`, and nowhere else:
+ * React queues types per root and hands them to the next transition-only
+ * commit, so a type added in any other scope describes whichever tree commits
+ * next rather than this one (TIM-1463, TIM-1471). Empty for the shallow search
+ * re-wrap, which re-renders the displayed page rather than changing it.
+ */
+export type NavigationRender = (
+  element: ReactNode,
+  publish: (() => void) | null,
+  types: readonly string[]
+) => void;
+
+// ─── 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>;
+
+// ─── Component ───────────────────────────────────────────────────
+
+/**
+ * Root component the router renders the page through.
+ *
+ * Renders the TopLoader alongside the tree it is given. Neither adds a DOM
+ * element on the hydration path, so the tree matches the server HTML.
+ *
+ * Rendered only by `createReactRoot` (client/react-root.ts): hydration passes
+ * `{ element, publish: null }`, and every later render is a synchronous
+ * `startTransition(() => root.render(...))` with a fresh `rendered` object.
+ */
+export function NavigationRoot({
+  rendered,
+  topLoaderConfig,
+}: {
+  rendered: RenderedTree;
+  topLoaderConfig?: TopLoaderConfig;
+}): ReactNode {
+  // 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, StrictMode's
+  // double-invoke — 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]);
+
+  // ─── 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 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 2 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
+  );
+}

package/src/client/navigation-transition.ts

@@ -0,0 +1,337 @@
+/**
+ * Navigation transition — the router-level hand-off of a navigation's tree to
+ * React, and the supersession that governs it.
+ *
+ * `navigateTransition` runs a navigation's fetch OUTSIDE any transition scope
+ * and hands the resulting tree to React through a `NavigationRender`, which
+ * is a synchronous `startTransition` around `root.render` (client/react-root.ts).
+ * 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(() => render(x))                     -> 'HOME' held
+ *      startTransition(async () => { await p; render(x) })  -> fallback shown
+ *
+ *    Left uncorrected, every navigation whose new tree suspends replaces the
+ *    visible page with a Suspense fallback — the exact thing NavigationRoot
+ *    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 holds for
+ * ALL of them. It used not to hold for `<Link>`, which wrapped
+ * `router.navigate()` in its own `useTransition`: that action scope entangled
+ * the root'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 deliberate:
+ * the hook's is tied to a single fiber and tracks one async callback at a
+ * time, and two overlapping navigations through it corrupted React's hook
+ * tracking ("Rendered more hooks than during the previous render"). Each
+ * navigation needs an independent lane. This matches the Next.js pattern
+ * (TIM-625): "No useTransition in the router at all — only standalone
+ * startTransition."
+ *
+ * See design/19-client-navigation.md §"How Pending State Works"
+ */
+
+import type { ReactNode } from 'react';
+import type { NavigationRender } from './navigation-root.tsx';
+
+// ─── 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;
+}
+
+/** What happened to this navigation's tree. */
+export type CommitOutcome = 'committed' | 'superseded' | 'failed';
+
+// ─── RenderOwner ────────────────────────────────────────────────
+
+/**
+ * A per-render identity that replaces the transition counter, the
+ * `handedOffNavAborts` set, and the `AbortController`-as-owner pattern.
+ *
+ * The navigation lifecycle holds one slot (`current: RenderOwner | null`).
+ * All supersession is "take the slot":
+ *
+ *   - Navigation takes unconditionally (previous owner gets settled + aborted
+ *     if !handedOff).
+ *   - Revalidation takes only if empty (epoch check).
+ *   - Handover gate before root.render checks `current === owner`.
+ *   - `settle()` is called from NavigationRoot publish (committed), slot
+ *     takeover (superseded), or rejection (failed).
+ *
+ * `settle()` records the outcome and resolves `displaced` for non-committed
+ * outcomes. The `outcome` field is first-wins with one exception:
+ * `settle('superseded')` overrides a prior `'committed'`, because a
+ * committed-but-still-decoding navigation can be displaced by a successor
+ * and the post-decode check must throw rather than letting the old
+ * navigation continue.
+ *
+ * TIM-1481: replaces counter + waiters + bumpTransitionCounter +
+ * supersedeNavigationTransitions + handedOffNavAborts + globalThis singleton.
+ */
+export interface RenderOwner {
+  readonly kind: 'navigation' | 'revalidation';
+  readonly fetchAbort: AbortController;
+  handedOff: boolean;
+  /** Sync read for the post-perform() check. null until settled. */
+  outcome: CommitOutcome | null;
+  /**
+   * Resolves when this owner is displaced — a successor supersedes it or it
+   * fails. Does NOT resolve on commit: a committed navigation still waits
+   * for its decode to finish. Used to stop waiting on a decode that is no
+   * longer this navigation's business.
+   */
+  readonly displaced: Promise<void>;
+  /**
+   * Record this owner's outcome and, for non-committed outcomes, resolve
+   * `displaced`. First-wins with one exception: `settle('superseded')`
+   * overrides a prior `'committed'`.
+   */
+  settle: (outcome: CommitOutcome) => void;
+}
+
+/**
+ * Create a fresh RenderOwner. Exported so tests that call
+ * `navigateTransition` directly can construct one without a router.
+ */
+export function createRenderOwner(kind: 'navigation' | 'revalidation'): RenderOwner {
+  let resolveDisplaced!: () => void;
+  const displaced = new Promise<void>((r) => {
+    resolveDisplaced = r;
+  });
+
+  const owner: RenderOwner = {
+    kind,
+    fetchAbort: new AbortController(),
+    handedOff: false,
+    outcome: null,
+    displaced,
+    settle(outcome: CommitOutcome): void {
+      if (owner.outcome === null) {
+        owner.outcome = outcome;
+      } else if (outcome === 'superseded' && owner.outcome === 'committed') {
+        // A committed-but-still-decoding navigation can be displaced by a
+        // successor. Override so the post-decode check throws AbortError
+        // rather than letting the old navigation continue with scroll
+        // restoration while a newer navigation is active.
+        owner.outcome = 'superseded';
+      }
+      // Resolve `displaced` for any non-committed outcome, even if the
+      // outcome field was already set. A committed-but-still-decoding
+      // navigation must be woken when a successor supersedes it — the old
+      // counter-based waiter did this because the counter bumped regardless
+      // of commit state. A commit does NOT resolve displaced: that would
+      // end the decode wait early, clearing pending state before the Flight
+      // stream finishes.
+      if (outcome !== 'committed') {
+        resolveDisplaced();
+      }
+    },
+  };
+  return owner;
+}
+
+// ─── navigateTransition ─────────────────────────────────────────
+
+/**
+ * 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 `render` that hands its result over
+ * is wrapped, in a synchronous `startTransition` (see the module comment).
+ *
+ * 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()`.
+ *
+ * Rejects with an `AbortError` when a newer transition started while this
+ * one's `perform()` was in flight — the stale tree is never handed to React
+ * and its `commit` never runs (TIM-629, TIM-1301).
+ *
+ * `onCommit` is the caller's hook on the *commit*, which the returned promise
+ * deliberately does not wait for. It runs exactly once: when React commits
+ * this navigation's tree, or — so nothing waits on a commit that will never
+ * come — when the navigation is abandoned instead: superseded by a newer
+ * transition (before or after its tree was handed to React) or failed. It is
+ * how `<Link>` keeps `isPending` up until the destination is on screen
+ * without scheduling anything against React's lanes (TIM-1418).
+ *
+ * `types` are the view transition types `render` adds beside the tree
+ * (design/37-navigation-api.md §"Transition types"). They are fixed before
+ * `perform` runs — what a render animates as is decided by the operation that
+ * started it, not by what the fetch returns.
+ *
+ * `owner` is the `RenderOwner` for this render (TIM-1481). Supersession is
+ * detected via `owner.outcome` (sync) and `owner.displaced` (async).
+ * No module-level state; no globalThis singleton.
+ *
+ * Used for: navigate(), refresh(), popstate with fetch.
+ */
+export function navigateTransition(
+  owner: RenderOwner,
+  perform: () => Promise<TransitionResult>,
+  render: NavigationRender,
+  types: readonly string[],
+  onCommit?: (outcome: CommitOutcome) => void
+): Promise<void> {
+  const superseded = () => new DOMException('Navigation superseded', 'AbortError');
+
+  // `onCommit`, exactly once, on whichever comes first: the commit, a
+  // supersession, or a failure.
+  let commitSettled = onCommit === undefined;
+  const settleCommit = (outcome: CommitOutcome): void => {
+    if (commitSettled) return;
+    commitSettled = true;
+    onCommit?.(outcome);
+  };
+
+  // Watch for displacement from outside (a successor taking the slot).
+  if (!commitSettled) {
+    void owner.displaced.then(() => {
+      if (owner.outcome === 'superseded') settleCommit('superseded');
+    });
+  }
+
+  return (async () => {
+    try {
+      const { element, decodePromise, commit } = await perform();
+      if (owner.outcome !== null) {
+        decodePromise?.catch(() => {});
+        throw superseded();
+      }
+      // Hand the tree over with its commit attached. NavigationRoot 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);
+      // `render` is the synchronous transition around `root.render`.
+      render(
+        element,
+        () => {
+          try {
+            commit();
+          } finally {
+            settleCommit('committed');
+          }
+        },
+        types
+      );
+      // 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.
+      if (decodePromise) {
+        await settleOnDecodeOrDisplacement(decodePromise, owner);
+      }
+      if (owner.outcome !== null && owner.outcome !== 'committed') {
+        throw superseded();
+      }
+    } catch (error) {
+      settleCommit('failed');
+      throw error;
+    }
+  })();
+}
+
+/**
+ * Wait for the payload to finish decoding, OR for this owner to be
+ * displaced — 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
+ * `RenderOwner.handedOff`), 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 settleOnDecodeOrDisplacement(
+  decodePromise: Promise<void>,
+  owner: RenderOwner
+): Promise<void> {
+  // Only bail early for displacement (superseded/failed), not for commit.
+  // A committed tree still needs to wait for its decode to finish — pending
+  // state and the Link indicator are timed against it.
+  if (owner.outcome !== null && owner.outcome !== 'committed') {
+    return Promise.resolve();
+  }
+  return Promise.race([decodePromise, owner.displaced]);
+}

package/src/client/nuqs-adapter.tsx

@@ -19,7 +19,9 @@ import {
   type unstable_AdapterInterface as AdapterInterface,
   type unstable_AdapterOptions as AdapterOptions,
 } from 'nuqs/adapters/custom';
-import { getRouter } from './router-ref.js';
+import { getRouter } from './router-ref.ts';
+import { getNavigationApi } from './navigation-api.ts';
+import { locationSearch } from './location-search.ts';
 
 // ─── Adapter Hook ─────────────────────────────────────────────────
 
@@ -31,15 +33,13 @@ import { getRouter } from './router-ref.js';
  *   (used by nuqs for selective re-rendering)
  */
 function useTimberAdapter(_watchKeys: string[]): AdapterInterface {
-  const [searchParams, setSearchParams] = useState(
-    () => new URLSearchParams(window.location.search)
-  );
+  const [searchParams, setSearchParams] = useState(() => new URLSearchParams(locationSearch()));
 
   // Sync search params on popstate (back/forward) and after
   // timber navigations that change the URL.
   useEffect(() => {
     function sync() {
-      setSearchParams(new URLSearchParams(window.location.search));
+      setSearchParams(new URLSearchParams(locationSearch()));
     }
 
     window.addEventListener('popstate', sync);
@@ -59,9 +59,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));
@@ -84,7 +96,7 @@ function useTimberAdapter(_watchKeys: string[]): AdapterInterface {
   return {
     searchParams,
     updateUrl,
-    getSearchParamsSnapshot: () => new URLSearchParams(window.location.search),
+    getSearchParamsSnapshot: () => new URLSearchParams(locationSearch()),
   };
 }