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

package/src/client/router.ts

@@ -1,128 +1,36 @@
-// 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 `applyActionResult`
+// 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 { 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;
-}
-
-/**
- * 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 { SegmentCache, PrefetchCache } from './segment-cache.ts';
+import { HistoryStack } from './history.ts';
+import { createNavigationCommitter } from './navigation-commit.ts';
+
+import { fetchRscPayload, NonRscResponse } from './rsc-fetch.ts';
+import { readPayloadTree, readPublishedParams } from '../shared/payload-root.ts';
+import { isClientStale } from './stale-client.ts';
+import { createScrollEffects, createSpaExits, createNavigationRecovery } from './router-effects.ts';
+import { createNavigationLifecycle } from './router-lifecycle.ts';
+import { createNavigationPipeline, prefetchKeyFor } from './router-pipeline.ts';
+import { recordSkew } from './router-skew.ts';
+import type {
+  NavigationOptions,
+  NavigationTransitionType,
+  RefreshOptions,
+  RouterDeps,
+  RouterInstance,
+  TraverseDirection,
+} from './router-types.ts';
+import { createRenderOwner, type CommitOutcome } from './navigation-transition.ts';
 
 // ─── Router Factory ──────────────────────────────────────────────
 
@@ -134,360 +42,519 @@ 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,
-    });
-    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;
-  }
+  // 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,
+    committedSegmentInfo,
+    isSegmentReuseSuppressed,
+    restoreSegmentReuse,
+  } = 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 lifecycle = createNavigationLifecycle(deps);
+  const {
+    currentOwner,
+    createNavOwner,
+    runNavigation,
+    markHandedOff,
+    forgetOlderHandoffs,
+    isPending,
+    getPendingUrl,
+    onPendingChange,
+  } = lifecycle;
+
+  // Fetch → commit → hand to React. See router-pipeline.ts.
+  const { performNavigationFetch, renderViaTransition } = createNavigationPipeline({
+    deps,
+    prefetchCache,
+    currentStateTree,
+    prepareNavigation,
+    isSegmentReuseSuppressed,
+    restoreSegmentReuse,
+    markHandedOff,
+    forgetOlderHandoffs,
+  });
+
+  // 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({
+    currentOwner,
+    supersede: () => void createNavOwner('navigation'),
+  });
+
+  // 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({
+    currentOwner,
+    leaveSpaIfOwned,
+    // Hoisted — `navigate` is a function declaration below.
+    navigate: (url, types) => navigate(url, { replace: true, _renderTypes: types }),
+  });
 
   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;
+    // A push, a replace, and a server action redirect all move the user
+    // forward; the caller's own types ride beside it. A redirect this router
+    // follows keeps the types of the render it interrupted instead.
+    const types = options._renderTypes ?? [
+      'navigation-forward' satisfies NavigationTransitionType,
+      ...(options.transitionTypes ?? []),
+    ];
+
+    // 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 (owner) => {
+        // When Navigation API is active, initiate the navigation via
+        // navigation.navigate() BEFORE the fetch. Must happen after
+        // createNavOwner 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,
+            owner,
+            types,
+            () =>
+              performNavigationFetch(fetchUrl, {
+                replace,
+                commitUrl: url,
+                signal: owner.fetchAbort.signal,
+                skipHistory: effectiveSkipHistory,
+                departingUrl,
+              }),
+            options.onCommit
+          );
 
-      // 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, owner, url, departingUrl, types)) 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,
+    /** The view transition type the render adds. */
+    type: NavigationTransitionType,
+    opts: {
+      /** Omitted by refresh(): the server renders the complete payload. */
+      stateTree?: { segments: string[] };
+      /** Restored after paint when present — traversals only. */
+      scrollY?: number;
+      externalSignal?: AbortSignal;
+      /** Fires once when React commits, or when the navigation is abandoned. */
+      onCommit?: (outcome: CommitOutcome) => void;
+    } = {}
+  ): Promise<void> {
+    await runNavigation(
+      url,
+      async (owner) => {
+        try {
+          await renderViaTransition(
+            url,
+            owner,
+            [type],
+            async () => {
+              const result = await fetchRscPayload(
+                url,
+                deps,
+                opts.stateTree,
+                undefined,
+                owner.fetchAbort.signal
+              );
+              const params = await result.params;
+              const { navState, commit } = prepareNavigation(url, {
+                payload: result.payload,
+                params,
+                segmentInfo: result.segmentInfo,
+                skippedSegments: result.skippedSegments,
+              });
+              return { ...result, params, navState, commit };
+            },
+            opts.onCommit
+          );
+        } 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, owner, url, url, [type])) 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> {
+  async function refresh(options: RefreshOptions = {}): 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, options.transitionType ?? 'refresh', {
+      onCommit: options.onCommit,
+    });
+  }
 
-      applyHead(headElements);
-    } finally {
-      setPending(false);
+  async function handlePopState(
+    url: string,
+    scrollY: number = 0,
+    externalSignal?: AbortSignal,
+    direction: TraverseDirection = 'navigation-traverse'
+  ): 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 (owner) => {
+          // 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.
+          //
+          // No fetch to be superseded — `runNavigation` has already superseded
+          // whatever was in flight before it (TIM-1022) — but the render still
+          // goes out through a transition React may hold (a replayed tree can
+          // suspend), so the publish rides that commit rather than running
+          // here. Publishing first would advertise the replayed route's slot
+          // keys while the slot content cache still describes the departing
+          // one (TIM-1423, codex on #1108).
+          //
+          // Routed through renderViaTransition so the replay gets the same
+          // lifecycle every other render has — handoff tracking, commit-on-
+          // commit, forgetOlderHandoffs — rather than a hand-rolled publish
+          // that misses one of them (TIM-1478). The perform resolves
+          // immediately: there is no fetch, and the cached payload is
+          // already decoded.
+          await renderViaTransition(url, owner, [direction], async () => {
+            const { navState, commit } = prepareNavigation(url, {
+              payload: entry.payload,
+              params: entry.params,
+              segmentInfo: entry.segmentInfo,
+              clearSegmentCacheOnEmpty: true,
+            });
+            return {
+              payload: entry.payload,
+              params: entry.params,
+              navState,
+              commit,
+              decodePromise: null,
+              segmentInfo: entry.segmentInfo ?? null,
+              skippedSegments: null,
+            };
+          });
+          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, direction, {
+        stateTree: currentStateTree(),
+        scrollY,
+        externalSignal,
+      });
     }
   }
 
   /**
    * Prefetch an RSC payload for a URL and store it in the prefetch cache.
    * Called on hover of <Link prefetch> elements.
+   *
+   * Concurrent hovers and a click during the round-trip coalesce via the
+   * singleflight inside PrefetchCache (TIM-1438).
    */
   function prefetch(url: string): void {
-    // Don't prefetch if already cached
-    if (prefetchCache.get(url) !== undefined) return;
-    if (historyStack.has(url)) return;
-
-    // Fire-and-forget fetch
-    const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
-    void fetchRscPayload(url, deps, stateTree).then(
-      (result) => {
-        prefetchCache.set(url, result);
-      },
-      () => {
-        // Prefetch failure is non-fatal — navigation will fetch fresh
-      }
-    );
+    // 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 (ready or negative)
+    if (prefetchCache.has(cacheKey)) return;
+
+    // Fire-and-forget. Concurrent hovers coalesce in the singleflight;
+    // a click during the round-trip joins the same flight via
+    // fetchOrCoalesce in performNavigationFetch (TIM-1438).
+    void prefetchCache
+      .fetchOrCoalesce(
+        cacheKey,
+        (signal) => fetchRscPayload(fetchUrl, deps, stateTree, from, signal),
+        (err) => err instanceof NonRscResponse
+      )
+      .then(
+        (outcome) => {
+          if (outcome.kind === 'ready') {
+            // 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).
+            outcome.result.decodePromise?.catch((error: unknown) => void recordSkew(error));
+          }
+        },
+        (error) => {
+          // 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);
+        }
+      );
   }
 
   return {
     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.
+    epoch: () => lifecycle.epoch(),
+    isEpochCurrent: (epoch) => lifecycle.isEpochCurrent(epoch),
+
+    async applyActionResult(epoch, tree) {
+      if (!lifecycle.isEpochCurrent(epoch)) return false;
+      if (tree === undefined) {
+        // Await through the commit so the next queued action captures a
+        // current epoch — refresh() alone resolves before React commits
+        // on the History API fallback (codex on #1125). The outcome
+        // distinguishes a committed refresh from one superseded by a
+        // navigation the user started while the refresh was in flight
+        // (TIM-1477).
+        let outcomeResolve!: (o: CommitOutcome) => void;
+        const outcomePromise = new Promise<CommitOutcome>((r) => (outcomeResolve = r));
+        const [, outcome] = await Promise.all([
+          refresh({ transitionType: 'revalidate', onCommit: outcomeResolve }).catch(() => {}),
+          outcomePromise,
+        ]);
+        return outcome === 'committed';
+      }
+      // Render the piggybacked payload from a server action response.
+      // Routed through renderViaTransition so the piggybacked tree gets
+      // the same commit lifecycle every other render has (TIM-1478).
+      // The perform resolves immediately — the payload is already in hand.
       const currentUrl = deps.getCurrentUrl();
-      const merged = mergeAndCachePayload(element, null);
-      historyStack.push(currentUrl, {
-        payload: merged,
-        headElements,
+      const payloadTree = readPayloadTree(tree);
+      const params = readPublishedParams(tree);
+      // The response carries no segment metadata; the page it re-renders is
+      // the one the last commit made current, and the committer kept that
+      // page's. Not a history-stack lookup by `currentUrl`: the stack is keyed
+      // by the spelling `navigate()` was given, which need not be
+      // `window.location`'s (TIM-1541).
+      const segmentInfo = committedSegmentInfo();
+
+      let outcomeResolve!: (o: CommitOutcome) => void;
+      const outcomePromise = new Promise<CommitOutcome>((r) => (outcomeResolve = r));
+      // Place in the lifecycle's slot so a concurrent navigation supersedes
+      // this owner. The epoch check above ensures the slot is idle. Don't use
+      // createNavOwner — that bumps navigationSeq, which is reserved for
+      // navigations (the epoch test pins this: TIM-1474).
+      const owner = createRenderOwner('revalidation');
+      lifecycle.placeRevalidationOwner(owner);
+      const [, outcome] = await Promise.all([
+        renderViaTransition(
+          currentUrl,
+          owner,
+          ['revalidate' satisfies NavigationTransitionType],
+          async () => {
+            const { navState, commit } = prepareNavigation(currentUrl, {
+              payload: payloadTree,
+              params,
+              segmentInfo,
+            });
+            return {
+              payload: payloadTree,
+              params,
+              navState,
+              commit,
+              decodePromise: null,
+              segmentInfo,
+              skippedSegments: null,
+            };
+          },
+          outcomeResolve
+        ).catch(() => {}),
+        outcomePromise,
+      ]);
+      return outcome === 'committed';
+    },
+    runWhenIdle: (task: () => void) => lifecycle.runWhenIdle(task),
+    settleHandoffs: () => lifecycle.settleHandoffs(),
+    suppressSegmentReuse(): void {
+      // TIM-1466: uses invalidateReuse() instead of clear() to preserve
+      // treePaths for interception scoping — a modal mounted on the current
+      // tree must still be navigable (codex on #1167).
+      segmentCache.invalidateReuse();
+    },
+    evictStaleCaches(): void {
+      prefetchCache.clearReady();
+      historyStack.clear();
+    },
+    hydrate(page) {
+      // Where hydration seeds the current page: the same prepare-and-commit
+      // every navigation goes through, so the segment cache, the committed
+      // segment metadata and the history entry are written by one commit
+      // rather than by bootstrap reaching into each (TIM-1541). Committed
+      // here, at once — see `RouterInstance.hydrate` for why not on React's
+      // hydration commit.
+      //
+      // Replaying this entry on a Back re-renders `payload` and republishes
+      // `params`. Both came out of one split of one decoded payload root
+      // (rsc-stream.ts), so the entry cannot replay with another route's
+      // params (TIM-1037, TIM-1285).
+      const { navState, commit } = prepareNavigation(deps.getCurrentUrl(), {
+        payload: page.payload,
+        params: page.params,
+        segmentInfo: page.segmentInfo,
       });
-      renderPayload(merged);
-      applyHead(headElements);
+      commit();
+      return navState;
     },
-    initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),
-    cacheElementTree: (element: unknown) => cacheSegmentElements(element, segmentElementCache),
     segmentCache,
     prefetchCache,
-    historyStack,
   };
 }