@timber-js/app 0.2.0-alpha.17 → 0.2.0-alpha.170

package/src/client/router.ts

@@ -4,11 +4,20 @@
 import { SegmentCache, PrefetchCache, buildSegmentTree } from './segment-cache';
 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';
+import { setCurrentParams } from './use-segment-params.js';
+import {
+  setNavigationState,
+  getNavigationState,
+  type NavigationState,
+} from './navigation-context.js';
+
+import {
+  fetchRscPayload,
+  RedirectError,
+  ServerErrorResponse,
+  VersionSkewError,
+} from './rsc-fetch.js';
+import { setHardNavigating, supersedeNavigationTransitions } from './navigation-root.js';
 import type { FetchResult } from './rsc-fetch.js';
 
 // ─── Types ───────────────────────────────────────────────────────
@@ -18,6 +27,19 @@ export interface NavigationOptions {
   scroll?: boolean;
   /** Use replaceState instead of pushState (replaces current history entry) */
   replace?: boolean;
+  /**
+   * @internal AbortSignal from the Navigation API's NavigateEvent.
+   * When provided, the signal is linked to the router's per-navigation
+   * AbortController so in-flight RSC fetches are cancelled when a new
+   * navigation starts.
+   */
+  _signal?: AbortSignal;
+  /**
+   * @internal Skip pushState/replaceState — the Navigation API has already
+   * updated the URL via event.intercept(). Used for external navigations
+   * intercepted by the navigate event handler.
+   */
+  _skipHistory?: boolean;
 }
 
 /**
@@ -31,8 +53,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
@@ -55,8 +81,6 @@ export interface RouterDeps {
    * In tests, this runs the callback synchronously.
    */
   afterPaint?: (callback: () => void) => void;
-  /** Apply resolved head elements (title, meta tags) to the DOM after navigation. */
-  applyHead?: (elements: HeadElement[]) => void;
   /**
    * Run a navigation inside a React transition with optimistic pending URL.
    * The pending URL shows immediately (useOptimistic urgent update) and
@@ -64,14 +88,80 @@ 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.
+   * NavigationRoot 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,
+        segmentUpdates?: Map<string, unknown>
+      ) => unknown
+    ) => Promise<{ element: unknown; decodePromise: Promise<void> | null }>
   ) => Promise<void>;
+
+  /**
+   * Whether the Navigation API is active and handling traversals.
+   * When true, the popstate handler is a no-op — the Navigation API's
+   * navigate event covers back/forward button presses.
+   */
+  navigationApiActive?: boolean;
+
+  /**
+   * Called around pushState/replaceState to set a flag that prevents
+   * the Navigation API's navigate listener from double-handling
+   * router-initiated navigations.
+   */
+  setRouterNavigating?: (value: boolean) => void;
+
+  /**
+   * Save scroll position via the Navigation API's per-entry state.
+   * When provided, used instead of history.replaceState for scroll storage.
+   */
+  saveNavigationEntryScroll?: (scrollY: number) => void;
+
+  /**
+   * Signal that a router-initiated navigation has completed. Resolves the
+   * deferred promise that ties the browser's native loading state to the
+   * navigation lifecycle. Called in the finally block of navigate/refresh,
+   * aligned with when the TopLoader's pendingUrl clears.
+   */
+  completeRouterNavigation?: () => void;
+
+  /**
+   * Get the current unwrapped RSC payload element. Used for partial
+   * navigation: the router re-wraps the same element with new
+   * NavigationProvider context so mounted SegmentOutlets are preserved.
+   */
+  _getCurrentPayload?: () => unknown;
+
+  /**
+   * Initiate a navigation via the Navigation API (`navigation.navigate()`).
+   * Fires the navigate event BEFORE committing the URL, allowing Chrome
+   * to show its native loading indicator. Falls back to pushState when
+   * unavailable.
+   */
+  navigationNavigate?: (url: string, replace: boolean) => void;
+
+  /**
+   * Scroll the element matching a URL #fragment into view. Returns true
+   * when a matching element was found and scrolled. When absent or false,
+   * the router falls back to scroll-to-top on forward navigation — same
+   * as a full page load with an unknown fragment landing at the top.
+   */
+  scrollToHash?: (hash: string) => boolean;
+
+  /**
+   * Whether the client segment cache is enabled. When false (the default),
+   * the router does not send X-Timber-State-Tree headers and does not
+   * populate the segment cache. Every navigation gets a full RSC payload.
+   */
+  clientSegmentCache?: boolean;
 }
 
 export interface RouterInstance {
@@ -80,7 +170,7 @@ export interface RouterInstance {
   /** Full re-render of the current URL — no state tree sent */
   refresh(): Promise<void>;
   /** Handle a popstate event (back/forward button). scrollY is read from history.state. */
-  handlePopState(url: string, scrollY?: number): Promise<void>;
+  handlePopState(url: string, scrollY?: number, externalSignal?: AbortSignal): Promise<void>;
   /** Whether a navigation is currently in flight */
   isPending(): boolean;
   /** The URL currently being navigated to, or null if idle */
@@ -94,18 +184,13 @@ export interface RouterInstance {
    * Renders the element tree and updates head elements without a server fetch.
    * See design/08-forms-and-actions.md §"Single-Roundtrip Revalidation".
    */
-  applyRevalidation(element: unknown, headElements: HeadElement[] | null): void;
+  applyRevalidation(element: unknown): void;
   /**
    * Populate the segment cache from server-provided segment metadata.
    * Called on initial hydration with segment info embedded in the HTML.
    */
   initSegmentCache(segments: SegmentInfo[]): void;
-  /**
-   * Cache segment elements from a decoded RSC element tree.
-   * Called on initial hydration to populate the element cache so the
-   * first client navigation can use partial payloads.
-   */
-  cacheElementTree(element: unknown): void;
+
   /** The segment cache (exposed for tests and <Link> prefetch) */
   segmentCache: SegmentCache;
   /** The prefetch cache (exposed for tests and <Link> prefetch) */
@@ -130,24 +215,83 @@ 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>();
 
+  // AbortController for the current in-flight navigation.
+  // When a new navigation starts, the previous controller is aborted,
+  // cancelling any in-progress RSC fetch. This provides automatic
+  // cancellation of stale fetches regardless of Navigation API support.
+  let currentNavAbort: AbortController | null = null;
+
+  /**
+   * Create a new AbortController for a navigation, superseding any
+   * previous in-flight navigation. Optionally links to an external
+   * signal (e.g., from the Navigation API's NavigateEvent.signal).
+   *
+   * Superseding is one operation with three parts:
+   * 1. Abort the previous navigation's fetch.
+   * 2. Invalidate its render transition so a response that already
+   *    arrived can't commit a stale tree (NavigationRoot's transId guard).
+   * 3. Resolve its Navigation API deferred — the superseded navigation's
+   *    finally block is staleness-guarded (see TIM-1034) and no longer
+   *    cleans up after itself, so the browser's native loading state for
+   *    the dead navigation is cleared here.
+   */
+  function createNavAbort(externalSignal?: AbortSignal): AbortController {
+    if (currentNavAbort) {
+      currentNavAbort.abort();
+      supersedeNavigationTransitions();
+      deps.completeRouterNavigation?.();
+    }
+    const controller = new AbortController();
+    currentNavAbort = controller;
+
+    // If an external signal is provided (e.g., Navigation API),
+    // forward its abort to our controller.
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        controller.abort();
+      } else {
+        externalSignal.addEventListener('abort', () => controller.abort(), { once: true });
+      }
+    }
+
+    return controller;
+  }
+
   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.
+    // NavigationRoot via navigateTransition — not this function.
     for (const listener of pendingListeners) {
       listener(value);
     }
@@ -155,6 +299,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   /** Update the segment cache from server-provided segment metadata. */
   function updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void {
+    if (!deps.clientSegmentCache) return;
     if (!segmentInfo || segmentInfo.length === 0) return;
     const tree = buildSegmentTree(segmentInfo);
     if (tree) {
@@ -163,100 +308,184 @@ 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);
     }
   }
 
   /**
-   * Merge a partial RSC payload with cached segment elements if segments
-   * were skipped, then cache segments from the (merged) payload.
-   * Returns the merged payload ready for rendering.
+   * Atomically update all navigation-owned state for a new page. Every
+   * code path that changes the "current page" must go through this
+   * function — making "forgot a field" impossible by construction.
+   *
+   * The three operations:
+   * 1. Segment cache — update from server-provided segment metadata
+   * 2. Navigation state — params + pathname for useSegmentParams/usePathname
+   * 3. History stack — store the payload for instant back/forward replay
    */
-  function mergeAndCachePayload(
-    payload: unknown,
-    skippedSegments: string[] | null | undefined
-  ): unknown {
-    let merged = payload;
-
-    // If segments were skipped, merge the partial payload with cached segments
-    if (skippedSegments && skippedSegments.length > 0) {
-      merged = mergeSegmentTree(payload, skippedSegments, segmentElementCache);
+  function commitNavigation(
+    url: string,
+    opts: {
+      payload: unknown;
+      params?: Record<string, string | string[]> | null;
+      segmentInfo?: SegmentInfo[] | null;
+      /** When true, clear the segment cache if segmentInfo is empty
+       *  (popstate replay for entries without layout metadata). */
+      clearSegmentCacheOnEmpty?: boolean;
+    }
+  ): NavigationState {
+    if (opts.segmentInfo && opts.segmentInfo.length > 0) {
+      updateSegmentCache(opts.segmentInfo);
+    } else if (opts.clearSegmentCacheOnEmpty) {
+      segmentCache.clear();
     }
 
-    // Cache segment elements from the (merged) payload for future merges
-    cacheSegmentElements(merged, segmentElementCache);
+    const navState = updateNavigationState(opts.params, url);
+
+    historyStack.push(url, {
+      payload: opts.payload,
+      params: navState.params,
+      segmentInfo: opts.segmentInfo,
+    });
+
+    return navState;
+  }
+
+  /**
+   * Wrap a navigation in the standard abort/pending/cleanup lifecycle.
+   * Consolidates the createNavAbort + setPending + staleness-guarded
+   * finally that was duplicated across navigate, refresh, and both
+   * handlePopState paths. AbortErrors are swallowed (not application
+   * errors); all other errors propagate to the caller.
+   */
+  async function runNavigation(
+    url: string,
+    fn: (navAbort: AbortController) => Promise<void>,
+    externalSignal?: AbortSignal
+  ): Promise<void> {
+    const navAbort = createNavAbort(externalSignal);
+    setPending(true, url);
+    try {
+      await fn(navAbort);
+    } catch (error) {
+      if (isAbortError(error)) return;
+      throw error;
+    } finally {
+      if (currentNavAbort === navAbort) {
+        currentNavAbort = null;
+        setPending(false);
+        deps.completeRouterNavigation?.();
+      }
+    }
+  }
+
+  /**
+   * Resolve thenable payloads in the test/fallback path (no navigateTransition).
+   * In production, React handles thenables from createFromFetch directly via
+   * Suspense. In tests, renderRoot is a plain mock that expects resolved values.
+   */
+  async function resolveForFallback(payload: unknown): Promise<unknown> {
+    if (
+      !deps.navigateTransition &&
+      payload != null &&
+      typeof payload === 'object' &&
+      'then' in payload
+    ) {
+      return await (payload as PromiseLike<unknown>);
+    }
+    return payload;
+  }
+
+  function isPartialNavigation(skippedSegments: string[] | null | undefined): boolean {
+    return skippedSegments != null && skippedSegments.length > 0;
+  }
 
-    return merged;
+  /**
+   * Build a segment updates map for partial navigation. Identifies the
+   * first non-skipped segment and maps it to the payload content.
+   */
+  function buildSegmentUpdates(result: FetchResult): Map<string, unknown> {
+    const skipped = new Set(result.skippedSegments!);
+    const segmentInfo = result.segmentInfo;
+    const updates = new Map<string, unknown>();
+    if (segmentInfo) {
+      for (const info of segmentInfo) {
+        if (!skipped.has(info.segmentId ?? info.path)) {
+          // Use segmentId (outlet key) when available — route groups
+          // use a disambiguated key like "/(marketing)" instead of "/".
+          updates.set(info.segmentId ?? info.path, result.payload);
+          break;
+        }
+      }
+    }
+    return updates;
   }
 
   /**
    * 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
-    const pathname = url.startsWith('http') ? new URL(url).pathname : url.split('?')[0] || '/';
-    setNavigationState({ params: resolvedParams, pathname });
+    // globalThis bridge — kept for backward compat
+    const parsed = new URL(url, 'http://localhost');
+    const pathname = parsed.pathname || '/';
+    const search = parsed.search;
+    const navState: NavigationState = { params: resolvedParams, pathname, search };
+    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, call commitNavigation, and return
+   * the FetchResult plus the NavigationState.
+   *
+   * State management (segmentCache, navState, historyStack) is handled by
+   * commitNavigation inside perform — this function only handles rendering.
    */
   async function renderViaTransition(
     url: string,
-    perform: () => Promise<FetchResult>
-  ): Promise<HeadElement[] | null> {
+    perform: () => Promise<FetchResult & { navState: NavigationState }>
+  ): Promise<void> {
     if (deps.navigateTransition) {
-      let headElements: HeadElement[] | null = null;
       await deps.navigateTransition(url, async (wrapPayload) => {
         const result = await perform();
-        headElements = result.headElements;
-        // Merge partial payload with cached segments before wrapping
-        const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
-        // Store the MERGED payload in history — not the partial pre-merge tree.
-        // This ensures handlePopState replays the complete tree on back/forward.
-        historyStack.push(url, {
-          payload: merged,
-          headElements: result.headElements,
-          params: result.params,
-        });
-        return wrapPayload(merged);
+
+        if (isPartialNavigation(result.skippedSegments)) {
+          const segmentUpdates = buildSegmentUpdates(result);
+
+          // Re-wrap the CURRENT element with new context values.
+          // SegmentOutlets read updates from SegmentUpdateContext;
+          // NavigationProvider gets new params/pathname.
+          const element = wrapPayload(
+            deps._getCurrentPayload?.() ?? result.payload,
+            result.navState,
+            segmentUpdates
+          );
+          return { element, decodePromise: result.decodePromise };
+        }
+
+        // Full navigation — empty updates, render the new tree.
+        const element = wrapPayload(result.payload, result.navState);
+        return { element, decodePromise: result.decodePromise };
       });
-      return headElements;
+      return;
     }
     // Fallback: no transition (tests, no React tree)
     const result = await perform();
-    // Merge partial payload with cached segments before rendering
-    const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
-    // Store merged payload in history
-    historyStack.push(url, {
-      payload: merged,
-      headElements: result.headElements,
-      params: result.params,
-    });
-    renderPayload(merged);
-    return result.headElements;
-  }
-
-  /** Apply head elements (title, meta tags) to the DOM if available. */
-  function applyHead(elements: HeadElement[] | null | undefined): void {
-    if (elements && deps.applyHead) {
-      deps.applyHead(elements);
+    if (!isPartialNavigation(result.skippedSegments)) {
+      renderPayload(result.payload, result.navState);
     }
   }
 
@@ -269,21 +498,47 @@ 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'));
+    });
+  }
+
+  /**
+   * Scroll to the element matching the URL #fragment after paint, falling
+   * back to scroll-to-top when no element matches (matching full-page-load
+   * behavior for an unknown fragment). Used by forward navigation to a
+   * hash-bearing URL (TIM-1035).
+   */
+  function scrollToHashAfterPaint(hash: string): void {
+    afterPaint(() => {
+      if (deps.scrollToHash?.(hash) !== true) {
+        deps.scrollTo(0, 0);
+      }
+      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.
    */
   async function performNavigationFetch(
     url: string,
-    options: { replace: boolean }
-  ): Promise<FetchResult> {
+    options: { replace: boolean; commitUrl?: string; signal?: AbortSignal; skipHistory?: boolean }
+  ): 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);
     let result: FetchResult | undefined = prefetched
       ? {
           payload: prefetched.payload,
-          headElements: prefetched.headElements,
+          decodePromise: null,
           segmentInfo: prefetched.segmentInfo ?? null,
           params: prefetched.params ?? null,
           skippedSegments: prefetched.skippedSegments ?? null,
@@ -293,148 +548,217 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     if (result === undefined) {
       // Fetch RSC payload with state tree for partial rendering.
       // Send current URL for intercepting route resolution (modal pattern).
-      const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
+      const stateTree = deps.clientSegmentCache ? segmentCache.serializeStateTree() : undefined;
       const rawCurrentUrl = deps.getCurrentUrl();
       const currentUrl = rawCurrentUrl.startsWith('http')
         ? new URL(rawCurrentUrl).pathname
         : new URL(rawCurrentUrl, 'http://localhost').pathname;
-      result = await fetchRscPayload(url, deps, stateTree, currentUrl);
+      result = await fetchRscPayload(url, deps, stateTree, currentUrl, options.signal);
     }
 
-    // Update the browser history — replace mode overwrites the current entry
-    if (options.replace) {
-      deps.replaceState({ timber: true, scrollY: 0 }, '', url);
-    } else {
-      deps.pushState({ timber: true, scrollY: 0 }, '', url);
+    // Update the browser history — skip when the Navigation API has already
+    // updated the URL via event.intercept() (external navigations).
+    // The committed URL keeps the #fragment (commitUrl) even though the
+    // fetch/history-stack URL is hash-less (TIM-1035).
+    if (!options.skipHistory) {
+      const commitUrl = options.commitUrl ?? url;
+      // Set the router-navigating flag so the Navigation API's navigate
+      // listener doesn't double-intercept this pushState/replaceState.
+      deps.setRouterNavigating?.(true);
+      if (options.replace) {
+        deps.replaceState({ timber: true, scrollY: 0 }, '', commitUrl);
+      } else {
+        deps.pushState({ timber: true, scrollY: 0 }, '', commitUrl);
+      }
+      deps.setRouterNavigating?.(false);
     }
 
-    // NOTE: History push is deferred — the merged payload (after segment
-    // merging in renderViaTransition) is stored by the caller, not here.
-    // Storing result.payload here would record the partial (pre-merge)
-    // RSC tree, causing handlePopState to replay an incomplete tree.
-
-    // Update the segment cache with the new route's segment tree.
-    updateSegmentCache(result.segmentInfo);
+    // Resolve thenable payloads in the test path so popstate replay
+    // and renderPayload receive plain values (see resolveForFallback).
+    const payload = await resolveForFallback(result.payload);
 
-    // Update navigation state (params + pathname) before rendering.
-    updateNavigationState(result.params, url);
+    // Atomically update all navigation state via commitNavigation.
+    // Partial navigations store null payload — the partial RSC tree
+    // can't be replayed standalone; popstate will fetch fresh.
+    const isPartial = isPartialNavigation(result.skippedSegments);
+    const navState = commitNavigation(url, {
+      payload: isPartial ? null : payload,
+      params: result.params,
+      segmentInfo: result.segmentInfo,
+    });
 
-    return result;
+    return { ...result, payload, navState };
   }
 
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
     const scroll = options.scroll !== false;
     const replace = options.replace === true;
+    const externalSignal = options._signal as AbortSignal | undefined;
+    const skipHistory = options._skipHistory === true;
+
+    // Split the #fragment off the navigation URL (TIM-1035). The full URL
+    // (with hash) is committed to the address bar; the hash-less URL is used
+    // for the RSC fetch (fragments are client-only — keeping it would also
+    // swallow the ?_rsc cache-bust param into the fragment) and for
+    // history-stack/prefetch keys (popstate lookups use pathname + search).
+    const hashIndex = url.indexOf('#');
+    const hash = hashIndex === -1 ? '' : url.slice(hashIndex);
+    const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
 
     // Capture the departing page's scroll position for scroll={false} preservation.
     const currentScrollY = deps.getScrollY();
 
-    // Save the departing page's scroll position in history.state before
-    // pushing a new entry. This ensures back/forward navigation can restore
-    // the correct scroll position from the browser's per-entry state.
-    deps.replaceState({ timber: true, scrollY: currentScrollY }, '', deps.getCurrentUrl());
-
-    setPending(true, url);
-
-    try {
-      const headElements = await renderViaTransition(url, () =>
-        performNavigationFetch(url, { replace })
-      );
+    // Save the departing page's scroll position — use Navigation API entry
+    // state when available, otherwise fall back to history.state.
+    if (deps.saveNavigationEntryScroll) {
+      deps.saveNavigationEntryScroll(currentScrollY);
+    } else {
+      deps.replaceState({ timber: true, scrollY: currentScrollY }, '', deps.getCurrentUrl());
+    }
 
-      // Update document.title and <meta> tags with the new page's metadata
-      applyHead(headElements);
+    let effectiveSkipHistory = skipHistory;
+
+    await runNavigation(
+      url,
+      async (navAbort) => {
+        // When Navigation API is active, initiate the navigation via
+        // navigation.navigate() BEFORE the fetch. Must happen after
+        // createNavAbort supersedes the previous navigation (done by
+        // runNavigation) so the old deferred is resolved first.
+        if (!effectiveSkipHistory && deps.navigationNavigate) {
+          deps.setRouterNavigating?.(true);
+          deps.navigationNavigate(url, replace);
+          deps.setRouterNavigating?.(false);
+          effectiveSkipHistory = true;
+        }
 
-      // Notify nuqs adapter (and any other listeners) that navigation completed.
-      window.dispatchEvent(new Event('timber:navigation-end'));
+        try {
+          await renderViaTransition(fetchUrl, () =>
+            performNavigationFetch(fetchUrl, {
+              replace,
+              commitUrl: url,
+              signal: navAbort.signal,
+              skipHistory: effectiveSkipHistory,
+            })
+          );
 
-      // 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);
+          // Notify nuqs adapter (and any other listeners) that navigation completed.
+          window.dispatchEvent(new Event('timber:navigation-end'));
+
+          // Scroll-to-top on forward navigation, scroll to the #fragment target
+          // when the URL has one, or restore captured position for scroll={false}.
+          if (scroll && hash) {
+            scrollToHashAfterPaint(hash);
+          } else {
+            restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
+          }
+        } catch (error) {
+          if (error instanceof VersionSkewError) {
+            setHardNavigating(true);
+            window.location.reload();
+            await new Promise(() => {});
+          }
+          if (error instanceof RedirectError) {
+            if (currentNavAbort !== navAbort) return;
+            await navigate(error.redirectUrl, { replace: true });
+            return;
+          }
+          if (error instanceof ServerErrorResponse) {
+            setHardNavigating(true);
+            window.location.href = error.url;
+            await new Promise(() => {});
+          }
+          throw error;
         }
-        window.dispatchEvent(new Event('timber:scroll-restored'));
-      });
-    } catch (error) {
-      // Server-side redirect during RSC fetch → soft router navigation.
-      if (error instanceof RedirectError) {
-        setPending(false);
-        await navigate(error.redirectUrl, { replace: true });
-        return;
-      }
-      // Abort errors are not application errors — swallow silently.
-      if (isAbortError(error)) return;
-      throw error;
-    } finally {
-      setPending(false);
-    }
+      },
+      externalSignal
+    );
   }
 
   async function refresh(): Promise<void> {
     const currentUrl = deps.getCurrentUrl();
 
-    setPending(true, currentUrl);
-
-    try {
-      const headElements = await renderViaTransition(currentUrl, async () => {
+    await runNavigation(currentUrl, async (navAbort) => {
+      await renderViaTransition(currentUrl, async () => {
         // No state tree sent — server renders the complete RSC payload
-        const result = await fetchRscPayload(currentUrl, deps);
-        // History push handled by renderViaTransition (stores merged payload)
-        updateSegmentCache(result.segmentInfo);
-        updateNavigationState(result.params, currentUrl);
-        return result;
+        const result = await fetchRscPayload(
+          currentUrl,
+          deps,
+          undefined,
+          undefined,
+          navAbort.signal
+        );
+        const payload = await resolveForFallback(result.payload);
+        const navState = commitNavigation(currentUrl, {
+          payload,
+          params: result.params,
+          segmentInfo: result.segmentInfo,
+        });
+        return { ...result, payload, navState };
       });
-
-      applyHead(headElements);
-    } finally {
-      setPending(false);
-    }
+    });
   }
 
-  async function handlePopState(url: string, scrollY: number = 0): Promise<void> {
+  async function handlePopState(
+    url: string,
+    scrollY: number = 0,
+    externalSignal?: AbortSignal
+  ): Promise<void> {
     // Scroll position is read from history.state by the caller (browser-entry.ts)
     // and passed in. This is more reliable than tracking scroll per-URL in memory
     // because the browser maintains per-entry state even with duplicate URLs.
     const entry = historyStack.get(url);
 
     if (entry && entry.payload !== null) {
-      // Replay cached payload — no server roundtrip
-      updateNavigationState(entry.params, url);
-      renderPayload(entry.payload);
-      applyHead(entry.headElements);
-      afterPaint(() => {
-        deps.scrollTo(0, scrollY);
-        window.dispatchEvent(new Event('timber:scroll-restored'));
-      });
+      // Replay cached payload — no server roundtrip.
+      //
+      // runNavigation supersedes any in-flight forward navigation (TIM-1022):
+      // aborts its fetch and invalidates its render transition so the stale
+      // forward payload can't commit over this replay. The replay itself is
+      // synchronous — the fn resolves immediately.
+      await runNavigation(
+        url,
+        async () => {
+          // clearSegmentCacheOnEmpty: popstate to an entry without layout
+          // metadata (e.g., initial SSR page) clears the cache so the next
+          // forward navigation gets a full render.
+          const navState = commitNavigation(url, {
+            payload: entry.payload,
+            params: entry.params,
+            segmentInfo: entry.segmentInfo,
+            clearSegmentCacheOnEmpty: true,
+          });
+          renderPayload(entry.payload, navState);
+          restoreScrollAfterPaint(scrollY);
+        },
+        externalSignal
+      );
     } else {
       // No cached payload — fetch from server.
       // This happens when navigating back to the initial SSR'd page
       // (its payload is null since it was rendered via SSR, not RSC fetch)
       // or when the entry doesn't exist at all.
-      setPending(true, url);
-      try {
-        const headElements = await renderViaTransition(url, async () => {
-          const stateTree = segmentCache.serializeStateTree(
-            segmentElementCache.getMergeablePaths()
-          );
-          const result = await fetchRscPayload(url, deps, stateTree);
-          updateSegmentCache(result.segmentInfo);
-          updateNavigationState(result.params, url);
-          // History push handled by renderViaTransition (stores merged payload)
-          return result;
-        });
-
-        applyHead(headElements);
-        afterPaint(() => {
-          deps.scrollTo(0, scrollY);
-          window.dispatchEvent(new Event('timber:scroll-restored'));
-        });
-      } finally {
-        setPending(false);
-      }
+      await runNavigation(
+        url,
+        async (navAbort) => {
+          await renderViaTransition(url, async () => {
+            const stateTree = deps.clientSegmentCache
+              ? segmentCache.serializeStateTree()
+              : undefined;
+            const result = await fetchRscPayload(url, deps, stateTree, undefined, navAbort.signal);
+            const payload = await resolveForFallback(result.payload);
+            const navState = commitNavigation(url, {
+              payload,
+              params: result.params,
+              segmentInfo: result.segmentInfo,
+            });
+            return { ...result, payload, navState };
+          });
+
+          restoreScrollAfterPaint(scrollY);
+        },
+        externalSignal
+      );
     }
   }
 
@@ -443,15 +767,21 @@ export function createRouter(deps: RouterDeps): RouterInstance {
    * Called on hover of <Link prefetch> elements.
    */
   function prefetch(url: string): void {
+    // Strip fragment — it's client-only and would swallow the _rsc cache-bust
+    // param into the hash. The hash-less key also matches navigate()'s fetchUrl.
+    const hashIndex = url.indexOf('#');
+    const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
+
     // Don't prefetch if already cached
-    if (prefetchCache.get(url) !== undefined) return;
-    if (historyStack.has(url)) return;
+    if (prefetchCache.get(fetchUrl) !== undefined) return;
+    if (historyStack.has(fetchUrl)) return;
 
     // Fire-and-forget fetch
-    const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
-    void fetchRscPayload(url, deps, stateTree).then(
+    const stateTree = deps.clientSegmentCache ? segmentCache.serializeStateTree() : undefined;
+    void fetchRscPayload(fetchUrl, deps, stateTree).then(
       (result) => {
-        prefetchCache.set(url, result);
+        result.decodePromise?.catch(() => {});
+        prefetchCache.set(fetchUrl, result);
       },
       () => {
         // Prefetch failure is non-fatal — navigation will fetch fresh
@@ -463,29 +793,31 @@ 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);
     },
     prefetch,
-    applyRevalidation(element: unknown, headElements: HeadElement[] | null): void {
+    applyRevalidation(element: unknown): void {
       // Render the piggybacked element tree from a server action response.
-      // Updates the current history entry with the fresh payload and applies
-      // head elements — same as refresh() but without a server fetch.
-      // Cache segment elements for future partial merges.
+      // Updates the current history entry with the fresh payload —
+      // same as refresh() but without a server fetch.
       const currentUrl = deps.getCurrentUrl();
-      const merged = mergeAndCachePayload(element, null);
-      historyStack.push(currentUrl, {
-        payload: merged,
-        headElements,
+
+      // Preserve existing segmentInfo so away-and-back navigation replays
+      // with a correct segment cache (TIM-1037). Preserve current params
+      // so dynamic route params aren't cleared to {}.
+      const existingEntry = historyStack.get(currentUrl);
+      const navState = commitNavigation(currentUrl, {
+        payload: element,
+        params: getNavigationState().params,
+        segmentInfo: existingEntry?.segmentInfo,
       });
-      renderPayload(merged);
-      applyHead(headElements);
+      renderPayload(element, navState);
     },
     initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),
-    cacheElementTree: (element: unknown) => cacheSegmentElements(element, segmentElementCache),
     segmentCache,
     prefetchCache,
     historyStack,