@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/client/router.ts

@@ -1,220 +1,29 @@
-// Segment Router — manages client-side navigation and RSC payload fetching
+// Segment Router — the operations a client-side navigation can be.
+//
+// `navigate`, `refresh`, `handlePopState`, `prefetch` and `applyRevalidation`
+// live here; each is wiring over modules that own one concern apiece:
+//
+//   router-types.ts      — RouterDeps / RouterInstance / the option shapes
+//   router-lifecycle.ts  — ownership, supersede, pending store, handoff set
+//   router-pipeline.ts   — URL in, tree in React's hands
+//   router-effects.ts    — SPA exits, error recovery, post-paint scroll
+//   navigation-commit.ts — every write that makes a page "current"
+//
 // See design/19-client-navigation.md for the full architecture.
 
-import { SegmentCache, PrefetchCache, buildSegmentTree } from './segment-cache';
-import type { SegmentInfo } from './segment-cache';
+import { SegmentCache, PrefetchCache } from './segment-cache';
+import type { SegmentInfo } from '../shared/segment-info.js';
 import { HistoryStack } from './history';
-import { setCurrentParams } from './use-segment-params.js';
-import {
-  setNavigationState,
-  getNavigationState,
-  type NavigationState,
-} from './navigation-context.js';
-
-import {
-  fetchRscPayload,
-  RedirectError,
-  ServerErrorResponse,
-  VersionSkewError,
-  NonRscResponse,
-} from './rsc-fetch.js';
-import { setHardNavigating, supersedeNavigationTransitions } from './navigation-root.js';
-import type { FetchResult } from './rsc-fetch.js';
-
-// ─── Types ───────────────────────────────────────────────────────
-
-export interface NavigationOptions {
-  /** Set to false to prevent scroll-to-top on forward navigation */
-  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;
-  /**
-   * @internal The URL the user is navigating FROM, captured before the
-   * Navigation API commits the destination. Sent as X-Timber-URL for
-   * slot skip comparison on the server (TIM-1232).
-   */
-  _departingUrl?: string;
-}
-
-/**
- * Function that decodes an RSC Flight stream into a React element tree.
- * In production: createFromFetch from @vitejs/plugin-rsc/browser.
- * In tests: a mock that returns the raw payload.
- */
-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, navState: NavigationState) => void;
-
-/**
- * Platform dependencies injected for testability. In production these
- * map to browser APIs; in tests they're replaced with mocks.
- */
-export interface RouterDeps {
-  fetch: (url: string, init: RequestInit) => Promise<Response>;
-  pushState: (data: unknown, unused: string, url: string) => void;
-  replaceState: (data: unknown, unused: string, url: string) => void;
-  scrollTo: (x: number, y: number) => void;
-  getCurrentUrl: () => string;
-  getScrollY: () => number;
-  /** Decode RSC Flight stream into React elements. If not provided, raw response text is stored. */
-  decodeRsc?: RscDecoder;
-  /** Render decoded RSC tree into the DOM. If not provided, rendering is a no-op. */
-  renderRoot?: RootRenderer;
-  /**
-   * Schedule a callback after the next paint. In the browser, this is
-   * requestAnimationFrame + setTimeout(0) to run after React commits.
-   * In tests, this runs the callback synchronously.
-   */
-  afterPaint?: (callback: () => void) => void;
-  /**
-   * Run a navigation inside a React transition with optimistic pending URL.
-   * The pending URL shows immediately (useOptimistic urgent update) and
-   * reverts when the transition commits (atomic with the new tree).
-   *
-   * The `perform` callback receives a `wrapPayload` function to wrap the
-   * decoded RSC payload with NavigationProvider + NuqsAdapter before
-   * 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,
-        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;
+import { createNavigationCommitter } from './navigation-commit.js';
 
-  /**
-   * 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 {
-  /** Navigate to a new URL (forward navigation) */
-  navigate(url: string, options?: NavigationOptions): Promise<void>;
-  /** 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, externalSignal?: AbortSignal): Promise<void>;
-  /** Whether a navigation is currently in flight */
-  isPending(): boolean;
-  /** The URL currently being navigated to, or null if idle */
-  getPendingUrl(): string | null;
-  /** Subscribe to pending state changes */
-  onPendingChange(listener: (pending: boolean) => void): () => void;
-  /** Prefetch an RSC payload for a URL (used by Link hover) */
-  prefetch(url: string): void;
-  /**
-   * Apply a piggybacked revalidation payload from a server action response.
-   * 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): 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;
-
-  /** The segment cache (exposed for tests and <Link> prefetch) */
-  segmentCache: SegmentCache;
-  /** The prefetch cache (exposed for tests and <Link> prefetch) */
-  prefetchCache: PrefetchCache;
-  /** The history stack (exposed for tests) */
-  historyStack: HistoryStack;
-}
-
-/**
- * Check if an error is an abort error (connection closed / fetch aborted).
- * Browsers throw DOMException with name 'AbortError' when a fetch is aborted.
- */
-function isAbortError(error: unknown): boolean {
-  if (error instanceof DOMException && error.name === 'AbortError') return true;
-  if (error instanceof Error && error.name === 'AbortError') return true;
-  return false;
-}
+import { fetchRscPayload, NonRscResponse } from './rsc-fetch.js';
+import { readPayloadTree, readPublishedParams } from '../shared/payload-root.js';
+import { isClientStale } from './stale-client.js';
+import { createScrollEffects, createSpaExits, createNavigationRecovery } from './router-effects.js';
+import { createNavigationLifecycle } from './router-lifecycle.js';
+import { createNavigationPipeline, prefetchKeyFor } from './router-pipeline.js';
+import { recordSkew } from './router-skew.js';
+import type { NavigationOptions, RouterDeps, RouterInstance } from './router-types.js';
 
 // ─── Router Factory ──────────────────────────────────────────────
 
@@ -222,418 +31,64 @@ 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();
-  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 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
-    // NavigationRoot via navigateTransition — not this function.
-    for (const listener of pendingListeners) {
-      listener(value);
-    }
-  }
-
-  /** 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) {
-      segmentCache.set('/', tree);
-    }
-  }
-
-  /** Render a decoded RSC payload into the DOM if a renderer is available. */
-  function renderPayload(payload: unknown, navState: NavigationState): void {
-    if (deps.renderRoot) {
-      deps.renderRoot(payload, navState);
-    }
-  }
-
-  /**
-   * 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 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();
-    }
-
-    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;
-  }
 
-  /**
-   * 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)) {
-          updates.set(info.segmentId ?? info.path, result.payload);
-          break;
-        }
-      }
-    }
-    return updates;
-  }
-
-  /**
-   * Update navigation state (params + pathname) for the next render.
-   *
-   * 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
-  ): NavigationState {
-    const resolvedParams = params ?? {};
-    // Module-level fallback for tests (no NavigationProvider) and SSR
-    setCurrentParams(resolvedParams);
-    // 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, 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 & { navState: NavigationState }>
-  ): Promise<void> {
-    if (deps.navigateTransition) {
-      await deps.navigateTransition(url, async (wrapPayload) => {
-        const result = await perform();
-
-        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;
-    }
-    // Fallback: no transition (tests, no React tree)
-    const result = await perform();
-    if (!isPartialNavigation(result.skippedSegments)) {
-      renderPayload(result.payload, result.navState);
-    }
-  }
-
-  /**
-   * Perform a hard navigation to a URL. When the target is same-document
-   * (same pathname+search, different hash), `location.href = url` is a
-   * hash change — no reload. Use `location.reload()` instead (TIM-1235).
-   *
-   * `fromUrl` is the departing URL captured before any pushState or
-   * Navigation API commit — deps.getCurrentUrl() is unreliable here
-   * because the URL may have already been updated.
-   */
-  function hardNavigate(url: string, fromUrl: string): void {
-    const current = new URL(fromUrl, window.location.origin);
-    const target = new URL(url, window.location.origin);
-    if (target.pathname === current.pathname && target.search === current.search) {
-      // Assign first to update the hash in the address bar, then reload
-      // to force a full page load. href alone is a no-op hash change.
-      window.location.href = url;
-      window.location.reload();
-    } else {
-      window.location.href = url;
-    }
-  }
-
-  /** Run a callback after the next paint (after React commit). */
-  function afterPaint(callback: () => void): void {
-    if (deps.afterPaint) {
-      deps.afterPaint(callback);
-    } else {
-      callback();
-    }
-  }
-
-  /**
-   * 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;
-      commitUrl?: string;
-      signal?: AbortSignal;
-      skipHistory?: boolean;
-      departingUrl?: string;
-    }
-  ): Promise<FetchResult & { navState: NavigationState }> {
-    // Check prefetch cache first. A negative entry means a prior prefetch
-    // determined this URL is not a route (non-RSC Content-Type). Hard-navigate
-    // immediately without a second fetch. See TIM-1231.
-    if (prefetchCache.isNegative(url)) {
-      prefetchCache.consume(url);
-      throw new NonRscResponse(url);
-    }
-
-    // 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,
-          decodePromise: null,
-          segmentInfo: prefetched.segmentInfo ?? null,
-          params: prefetched.params ?? null,
-          skippedSegments: prefetched.skippedSegments ?? null,
-        }
-      : undefined;
-
-    if (result === undefined) {
-      // Fetch RSC payload with state tree for partial rendering.
-      // Send departing URL (pre-navigation) for slot skip comparison.
-      // getCurrentUrl() can't be used here because the Navigation API
-      // may have already committed the destination URL (TIM-1232).
-      const stateTree = deps.clientSegmentCache ? segmentCache.serializeStateTree() : undefined;
-      const rawDepartingUrl = options.departingUrl ?? deps.getCurrentUrl();
-      const currentUrl = rawDepartingUrl.startsWith('http')
-        ? new URL(rawDepartingUrl).pathname
-        : new URL(rawDepartingUrl, 'http://localhost').pathname;
-      result = await fetchRscPayload(url, deps, stateTree, currentUrl, options.signal);
-    }
-
-    // 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);
-    }
-
-    // Resolve thenable payloads in the test path so popstate replay
-    // and renderPayload receive plain values (see resolveForFallback).
-    const payload = await resolveForFallback(result.payload);
-
-    // Atomically update all navigation state via commitNavigation.
-    // Partial navigations and slot-skip navigations store null payload —
-    // the RSC tree contains skip holes that can't be replayed standalone;
-    // popstate will fetch fresh.
-    const isPartial = isPartialNavigation(result.skippedSegments);
-    const hasSkippedSlots = result.segmentInfo?.some((s) => s.slot && s.skipped) ?? false;
-    const navState = commitNavigation(url, {
-      payload: isPartial || hasSkippedSlots ? null : payload,
-      params: result.params,
-      segmentInfo: result.segmentInfo,
+  // Every write that makes a page "current", and the read that reports the
+  // current page back to the server. See navigation-commit.ts.
+  const { prepareNavigation, currentStateTree, updateSegmentCache } = createNavigationCommitter({
+    segmentCache,
+    historyStack,
+    clientSegmentCache: () => deps.clientSegmentCache,
+  });
+
+  // Ownership of the router: who is navigating, whose fetch may be cut, and
+  // the pending store TopLoader subscribes to. See router-lifecycle.ts.
+  const {
+    currentNavAbort,
+    createNavAbort,
+    runNavigation,
+    markHandedOff,
+    forgetOlderHandoffs,
+    isPending,
+    getPendingUrl,
+    onPendingChange,
+  } = createNavigationLifecycle(deps);
+
+  // Fetch → commit → hand to React. See router-pipeline.ts.
+  const { performNavigationFetch, renderViaTransition, renderPayload, resolveForFallback } =
+    createNavigationPipeline({
+      deps,
+      prefetchCache,
+      currentStateTree,
+      prepareNavigation,
+      markHandedOff,
+      forgetOlderHandoffs,
     });
 
-    return { ...result, payload, navState };
-  }
+  // Post-paint scroll effects.
+  const { restoreScrollAfterPaint, scrollToHashAfterPaint } = createScrollEffects(deps);
+
+  // The only ways out of the SPA. Every failure branch that gives up on
+  // client-side navigation goes through one of these, so the "does this
+  // navigation still own the router?" question is asked once rather than
+  // per branch (TIM-1275, TIM-1276).
+  const { leaveSpaIfOwned, leaveSpaSuperseding } = createSpaExits({
+    currentNavAbort,
+    supersede: () => void createNavAbort(),
+  });
+
+  // Every way an RSC fetch can fail that the router answers rather than
+  // rethrows. Shared by navigate(), refresh(), and traversals so a path that
+  // grows a new branch grows it for all of them (TIM-1277).
+  const recoverFromNavigationError = createNavigationRecovery({
+    currentNavAbort,
+    leaveSpaIfOwned,
+    // Hoisted — `navigate` is a function declaration below.
+    navigate: (url) => navigate(url, { replace: true }),
+  });
 
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
     const scroll = options.scroll !== false;
@@ -667,6 +122,17 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       deps.replaceState({ timber: true, scrollY: currentScrollY }, '', deps.getCurrentUrl());
     }
 
+    // This bundle has been superseded. Every subsequent navigation is a full
+    // document load — it is the only way to get code that matches the server,
+    // and it is the recovery for a skew detected on an earlier navigation.
+    // Deliberately *not* a reload: recovery rides on navigations the user
+    // asked for, so a rollout that keeps serving mismatched builds costs one
+    // document load per click instead of a self-issued reload loop (TIM-1275).
+    // Scroll is saved above, so back-navigation still restores correctly.
+    if (isClientStale()) {
+      await leaveSpaSuperseding(url, departingUrl);
+    }
+
     let effectiveSkipHistory = skipHistory;
 
     await runNavigation(
@@ -684,7 +150,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         }
 
         try {
-          await renderViaTransition(fetchUrl, () =>
+          await renderViaTransition(fetchUrl, navAbort, () =>
             performNavigationFetch(fetchUrl, {
               replace,
               commitUrl: url,
@@ -694,9 +160,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
             })
           );
 
-          // 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) {
@@ -705,26 +168,12 @@ export function createRouter(deps: RouterDeps): RouterInstance {
             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);
-            hardNavigate(url, departingUrl);
-            await new Promise(() => {});
-          }
-          if (error instanceof NonRscResponse) {
-            setHardNavigating(true);
-            hardNavigate(url, departingUrl);
-            await new Promise(() => {});
-          }
+          // `url` is where the user asked to go and `departingUrl` is where
+          // they were: a failure here finishes the click as a full document
+          // load of the destination, fragment included (TIM-1234). Reloading
+          // instead would rebuild the page they were *leaving* and discard
+          // the click (TIM-1275).
+          if (await recoverFromNavigationError(error, navAbort, url, departingUrl)) return;
           throw error;
         }
       },
@@ -732,28 +181,81 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     );
   }
 
+  /**
+   * Fetch a URL's RSC payload, commit it, and render — the pipeline shared by
+   * refresh() and an uncached back/forward traversal. Both can be the path
+   * that discovers a version skew, and both recover the same way (TIM-1275).
+   *
+   * Not `performNavigationFetch`: neither caller consults the prefetch cache
+   * (there is no link to have hovered) and neither moves the address bar (the
+   * browser is already where it is going), so the fetch is a plain one.
+   */
+  async function fetchCommitAndRender(
+    url: string,
+    opts: {
+      /** Omitted by refresh(): the server renders the complete payload. */
+      stateTree?: { segments: string[] };
+      /** Restored after paint when present — traversals only. */
+      scrollY?: number;
+      externalSignal?: AbortSignal;
+    } = {}
+  ): Promise<void> {
+    await runNavigation(
+      url,
+      async (navAbort) => {
+        try {
+          await renderViaTransition(url, navAbort, async () => {
+            const result = await fetchRscPayload(
+              url,
+              deps,
+              opts.stateTree,
+              undefined,
+              navAbort.signal
+            );
+            const payload = await resolveForFallback(result.payload);
+            const params = await result.params;
+            const { navState, commit } = prepareNavigation(url, {
+              payload,
+              params,
+              segmentInfo: result.segmentInfo,
+              status: result.status,
+            });
+            return { ...result, payload, params, navState, commit };
+          });
+        } catch (error) {
+          // Neither path is a navigate(), and neither has a caller that
+          // handles a rejection — `refresh()` is `void`-called everywhere it
+          // is used, and nobody awaits a traversal at all. Without the same
+          // recovery `navigate()` gets, a 500 on Back left the user on the
+          // old document with an unhandled rejection in the console
+          // (TIM-1277).
+          //
+          // `url` is both the destination and the departure point: the
+          // browser has already traversed, and `refresh()` is by definition
+          // where it already is. So `hardNavigate()` takes its same-document
+          // branch and reloads rather than pushing an entry.
+          if (await recoverFromNavigationError(error, navAbort, url, url)) return;
+          throw error;
+        }
+
+        if (opts.scrollY !== undefined) restoreScrollAfterPaint(opts.scrollY);
+      },
+      opts.externalSignal
+    );
+  }
+
   async function refresh(): Promise<void> {
     const currentUrl = deps.getCurrentUrl();
 
-    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,
-          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 };
-      });
-    });
+    // A refresh on a stale client is a full document load of the current URL.
+    // Same rule as navigate(): the RSC fetch would only be answered with
+    // another reload signal, and this is caller-initiated, not spontaneous
+    // (TIM-1275).
+    if (isClientStale()) {
+      await leaveSpaSuperseding(currentUrl, currentUrl);
+    }
+
+    await fetchCommitAndRender(currentUrl);
   }
 
   async function handlePopState(
@@ -761,6 +263,18 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     scrollY: number = 0,
     externalSignal?: AbortSignal
   ): Promise<void> {
+    // A stale client hard-navigates on back/forward too — this path never
+    // reaches navigate(), so it needs the same check. `url` is where the
+    // browser has *already* traversed to, so leaveSpa's same-document
+    // branch reloads there rather than pushing a new entry (TIM-1275).
+    //
+    // This overrides the cached-payload replay below on purpose. Replaying
+    // would work — the payload was decoded by this bundle — but it would keep
+    // the user on superseded code for as long as they browse within history.
+    if (isClientStale()) {
+      await leaveSpaSuperseding(url, url);
+    }
+
     // 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.
@@ -779,13 +293,19 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           // 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, {
+          //
+          // Committed immediately: the replay is synchronous and its render
+          // goes out through `transitionRender`, so there is no in-flight
+          // window for a successor to supersede. `runNavigation` has already
+          // superseded whatever was in flight before it (TIM-1022).
+          const { navState, commit } = prepareNavigation(url, {
             payload: entry.payload,
             params: entry.params,
             segmentInfo: entry.segmentInfo,
             clearSegmentCacheOnEmpty: true,
           });
-          renderPayload(entry.payload, navState);
+          commit();
+          renderPayload(entry.payload, navState, entry.params);
           restoreScrollAfterPaint(scrollY);
         },
         externalSignal
@@ -795,27 +315,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // 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.
-      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
-      );
+      await fetchCommitAndRender(url, {
+        stateTree: currentStateTree(),
+        scrollY,
+        externalSignal,
+      });
     }
   }
 
@@ -824,28 +328,53 @@ export function createRouter(deps: RouterDeps): RouterInstance {
    * Called on hover of <Link prefetch> elements.
    */
   function prefetch(url: string): void {
+    // A stale client hard-navigates on every navigation, so a prefetched RSC
+    // payload could never be consumed — and the fetch would be answered with
+    // another reload signal anyway (TIM-1275).
+    if (isClientStale()) return;
+
     // 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);
 
+    // The page the link is on. Sent as X-Timber-URL so the prefetched payload
+    // is the one the click would have produced — an intercepting link hovered
+    // from /gallery must prefetch the modal, not the full page — and stored
+    // under the same source so only a click departing from here consumes it
+    // (TIM-1265). The key is built by the pipeline, which is also what builds
+    // the one the click looks up with, so the two cannot disagree.
+    const stateTree = currentStateTree();
+    const cacheKey = prefetchKeyFor(fetchUrl, deps.getCurrentUrl(), stateTree);
+    const from = cacheKey.from;
+
     // Don't prefetch if already cached
-    if (prefetchCache.get(fetchUrl) !== undefined) return;
+    if (prefetchCache.get(cacheKey) !== undefined) return;
     if (historyStack.has(fetchUrl)) return;
 
     // Fire-and-forget fetch
-    const stateTree = deps.clientSegmentCache ? segmentCache.serializeStateTree() : undefined;
-    void fetchRscPayload(fetchUrl, deps, stateTree).then(
+    void fetchRscPayload(fetchUrl, deps, stateTree, from).then(
       (result) => {
-        result.decodePromise?.catch(() => {});
-        prefetchCache.set(fetchUrl, result);
+        // The decode rejects separately from the fetch, so the stale shapes
+        // reach us here rather than in the rejection handler below — swallowing
+        // it wholesale threw away the same evidence (TIM-1275).
+        result.decodePromise?.catch((error: unknown) => void recordSkew(error));
+        prefetchCache.set(cacheKey, result);
       },
       (error) => {
         if (error instanceof NonRscResponse) {
-          prefetchCache.setNegative(fetchUrl);
+          prefetchCache.setNegative(cacheKey);
           return;
         }
-        // Prefetch failure is non-fatal — navigation will fetch fresh
+        // A prefetch can be the first thing to learn we are stale — during a
+        // rollout it may reach the new deployment while the click that
+        // follows reaches the old one and completes as an ordinary SPA
+        // navigation, throwing the evidence away. Record it, but never
+        // recover from here: nobody navigated, and a page load triggered by
+        // a hover is exactly the unasked-for reload this design removed. The
+        // next click takes the document-load path (TIM-1275).
+        recordSkew(error);
+        // Any other prefetch failure is non-fatal — navigation fetches fresh.
       }
     );
   }
@@ -854,29 +383,36 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     navigate,
     refresh,
     handlePopState,
-    isPending: () => routerPhase.phase === 'navigating',
-    getPendingUrl: () => (routerPhase.phase === 'navigating' ? routerPhase.targetUrl : null),
-    onPendingChange(listener) {
-      pendingListeners.add(listener);
-      return () => pendingListeners.delete(listener);
-    },
+    isPending,
+    getPendingUrl,
+    onPendingChange,
     prefetch,
-    applyRevalidation(element: unknown): void {
-      // Render the piggybacked element tree from a server action response.
-      // Updates the current history entry with the fresh payload —
-      // same as refresh() but without a server fetch.
+    applyRevalidation(payloadRoot: unknown): void {
+      // Render the piggybacked payload from a server action response. Updates
+      // the current history entry with the fresh payload — same as refresh()
+      // but without a server fetch.
+      //
+      // The revalidation renderer builds its tree through the same
+      // `withPublishedParams` every route payload goes through, so it is a
+      // payload root and carries its own params. It is already decoded by the
+      // time it reaches here (action-dispatch awaits the Flight response), so
+      // the split is synchronous.
       const currentUrl = deps.getCurrentUrl();
+      const tree = readPayloadTree(payloadRoot);
+      const params = readPublishedParams(payloadRoot);
 
       // 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 {}.
+      // with a correct segment cache (TIM-1037).
       const existingEntry = historyStack.get(currentUrl);
-      const navState = commitNavigation(currentUrl, {
-        payload: element,
-        params: getNavigationState().params,
+      // Synchronous, like the popstate replay: there is no fetch to be
+      // superseded, and the payload is already decoded.
+      const { navState, commit } = prepareNavigation(currentUrl, {
+        payload: tree,
+        params,
         segmentInfo: existingEntry?.segmentInfo,
       });
-      renderPayload(element, navState);
+      commit();
+      renderPayload(tree, navState, params);
     },
     initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),
     segmentCache,