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

package/src/client/router.ts

@@ -1,128 +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 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 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;
-}
-
-/**
- * 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.
- */
-export type RootRenderer = (element: unknown) => 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;
-  /** 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
-   * 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
-   * TransitionRoot sets it as the new element.
-   *
-   * If not provided (tests), the router falls back to renderRoot.
-   */
-  navigateTransition?: (
-    pendingUrl: string,
-    perform: (wrapPayload: (payload: unknown) => unknown) => Promise<unknown>
-  ) => Promise<void>;
-}
-
-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): 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, headElements: HeadElement[] | null): 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) */
-  prefetchCache: PrefetchCache;
-  /** The history stack (exposed for tests) */
-  historyStack: HistoryStack;
-}
+import { createNavigationCommitter } from './navigation-commit.js';
 
-/**
- * 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 ──────────────────────────────────────────────
 
@@ -134,307 +35,291 @@ 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;
-  const pendingListeners = new Set<(pending: boolean) => void>();
-
-  function setPending(value: boolean, url?: string): void {
-    const newPendingUrl = value && url ? url : null;
-    if (pending === value && pendingUrl === newPendingUrl) return;
-    pending = value;
-    pendingUrl = newPendingUrl;
-    // Notify external store listeners (non-React consumers).
-    // React-facing pending state is handled by useOptimistic in
-    // TransitionRoot 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 (!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): void {
-    if (deps.renderRoot) {
-      deps.renderRoot(payload);
-    }
-  }
 
-  /**
-   * 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.
-   */
-  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);
-    }
-
-    // Cache segment elements from the (merged) payload for future merges
-    cacheSegmentElements(merged, segmentElementCache);
-
-    return merged;
-  }
-
-  /**
-   * 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.
-   */
-  function updateNavigationState(
-    params: Record<string, string | string[]> | null | undefined,
-    url: string
-  ): void {
-    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 });
-  }
-
-  /**
-   * 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.
-   */
-  async function renderViaTransition(
-    url: string,
-    perform: () => Promise<FetchResult>
-  ): Promise<HeadElement[] | null> {
-    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);
-      });
-      return headElements;
-    }
-    // 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,
+  // 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,
     });
-    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);
-    }
-  }
-
-  /** Run a callback after the next paint (after React commit). */
-  function afterPaint(callback: () => void): void {
-    if (deps.afterPaint) {
-      deps.afterPaint(callback);
-    } else {
-      callback();
-    }
-  }
 
-  /**
-   * 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> {
-    // 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,
-          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 current URL for intercepting route resolution (modal pattern).
-      const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
-      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);
-    }
-
-    // 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);
-    }
-
-    // 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);
-
-    // Update navigation state (params + pathname) before rendering.
-    updateNavigationState(result.params, url);
-
-    return result;
-  }
+  // 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;
     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);
+
+    // Use the pre-intercept departing URL when the Navigation API has already
+    // committed the destination (_departingUrl from navigation-api.ts). Otherwise
+    // capture it now — getCurrentUrl() is still the departing URL at this point
+    // for non-Navigation-API navigations (TIM-1232).
+    const departingUrl = options._departingUrl ?? deps.getCurrentUrl();
 
     // 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());
+    // 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());
+    }
 
-    setPending(true, url);
+    // 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);
+    }
 
-    try {
-      const headElements = await renderViaTransition(url, () =>
-        performNavigationFetch(url, { replace })
-      );
+    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;
+        }
 
-      // Update document.title and <meta> tags with the new page's metadata
-      applyHead(headElements);
+        try {
+          await renderViaTransition(fetchUrl, navAbort, () =>
+            performNavigationFetch(fetchUrl, {
+              replace,
+              commitUrl: url,
+              signal: navAbort.signal,
+              skipHistory: effectiveSkipHistory,
+              departingUrl,
+            })
+          );
 
-      // 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) {
+          // `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;
+        }
+      },
+      externalSignal
+    );
+  }
 
-      // 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);
+  /**
+   * 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;
         }
-        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);
-    }
+
+        if (opts.scrollY !== undefined) restoreScrollAfterPaint(opts.scrollY);
+      },
+      opts.externalSignal
+    );
   }
 
   async function refresh(): Promise<void> {
     const currentUrl = deps.getCurrentUrl();
 
-    setPending(true, currentUrl);
+    // 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);
+    }
 
-    try {
-      const headElements = 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;
-      });
+    await fetchCommitAndRender(currentUrl);
+  }
 
-      applyHead(headElements);
-    } finally {
-      setPending(false);
+  async function handlePopState(
+    url: string,
+    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);
     }
-  }
 
-  async function handlePopState(url: string, scrollY: number = 0): 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.
+          //
+          // 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,
+          });
+          commit();
+          renderPayload(entry.payload, navState, entry.params);
+          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 fetchCommitAndRender(url, {
+        stateTree: currentStateTree(),
+        scrollY,
+        externalSignal,
+      });
     }
   }
 
@@ -443,18 +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(url) !== undefined) return;
-    if (historyStack.has(url)) return;
+    if (prefetchCache.get(cacheKey) !== undefined) return;
+    if (historyStack.has(fetchUrl)) return;
 
     // Fire-and-forget fetch
-    const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
-    void fetchRscPayload(url, deps, stateTree).then(
+    void fetchRscPayload(fetchUrl, deps, stateTree, from).then(
       (result) => {
-        prefetchCache.set(url, 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);
       },
-      () => {
-        // Prefetch failure is non-fatal — navigation will fetch fresh
+      (error) => {
+        if (error instanceof NonRscResponse) {
+          prefetchCache.setNegative(cacheKey);
+          return;
+        }
+        // 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.
       }
     );
   }
@@ -463,29 +383,38 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     navigate,
     refresh,
     handlePopState,
-    isPending: () => pending,
-    getPendingUrl: () => pendingUrl,
-    onPendingChange(listener) {
-      pendingListeners.add(listener);
-      return () => pendingListeners.delete(listener);
-    },
+    isPending,
+    getPendingUrl,
+    onPendingChange,
     prefetch,
-    applyRevalidation(element: unknown, headElements: HeadElement[] | null): 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.
+    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 merged = mergeAndCachePayload(element, null);
-      historyStack.push(currentUrl, {
-        payload: merged,
-        headElements,
+      const tree = readPayloadTree(payloadRoot);
+      const params = readPublishedParams(payloadRoot);
+
+      // Preserve existing segmentInfo so away-and-back navigation replays
+      // with a correct segment cache (TIM-1037).
+      const existingEntry = historyStack.get(currentUrl);
+      // 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(merged);
-      applyHead(headElements);
+      commit();
+      renderPayload(tree, navState, params);
     },
     initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),
-    cacheElementTree: (element: unknown) => cacheSegmentElements(element, segmentElementCache),
     segmentCache,
     prefetchCache,
     historyStack,