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

package/src/client/router-lifecycle.ts

@@ -0,0 +1,288 @@
+/**
+ * Navigation Lifecycle — who owns the router, and when a fetch may be cut.
+ *
+ * One navigation at a time owns the router. This module holds that ownership
+ * (`currentNavAbort`), the rule for taking it (`createNavAbort` supersedes),
+ * the wrapper every navigation runs inside (`runNavigation`), the set of
+ * navigations whose trees are on screen and therefore unabortable
+ * (`handedOffNavAborts`), and the pending store that `TopLoader` and
+ * `usePendingNavigation()` subscribe to.
+ *
+ * These belong together because every one of them is a read or a write of
+ * "which navigation is the user waiting for?" — the question `router.ts` used
+ * to answer in four places. Split out of `router.ts` for the same reason
+ * `router-effects.ts` was (design/18-build-system.md §"No file >500 lines").
+ *
+ * See design/19-client-navigation.md §"How Pending State Works".
+ */
+
+import { supersedeNavigationTransitions } from './navigation-root.js';
+import type { RouterPhase } from './router-types.js';
+
+/** The subset of `RouterDeps` the navigation lifecycle needs. */
+export interface NavigationLifecycleDeps {
+  /**
+   * Signal that a router-initiated navigation has completed. Resolves the
+   * deferred promise that ties the browser's native loading state to the
+   * navigation lifecycle.
+   */
+  completeRouterNavigation?: () => void;
+}
+
+export interface NavigationLifecycle {
+  /** The controller that owns the router right now, or null when idle. */
+  currentNavAbort: () => AbortController | null;
+  /**
+   * Take ownership of the router, superseding whatever held it. See the
+   * implementation for the three parts of superseding.
+   */
+  createNavAbort: (externalSignal?: AbortSignal) => AbortController;
+  /**
+   * Run `fn` inside the abort/pending/cleanup lifecycle. AbortErrors are
+   * swallowed (not application errors); all other errors propagate.
+   */
+  runNavigation: (
+    url: string,
+    fn: (navAbort: AbortController) => Promise<void>,
+    externalSignal?: AbortSignal
+  ) => Promise<void>;
+  /**
+   * Record that `owner`'s payload has reached React, so its stream is no
+   * longer cuttable. No-op when `owner` no longer owns the router.
+   */
+  markHandedOff: (owner: AbortController) => void;
+  /** React has committed `owner`'s tree — every earlier handoff is off screen. */
+  forgetOlderHandoffs: (owner: AbortController) => 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;
+}
+
+/**
+ * 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;
+}
+
+export function createNavigationLifecycle(deps: NavigationLifecycleDeps): NavigationLifecycle {
+  // 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;
+
+  let routerPhase: RouterPhase = { phase: 'idle' };
+  const pendingListeners = new Set<(pending: boolean) => void>();
+
+  /**
+   * The controllers of navigations whose trees have been HANDED TO REACT.
+   *
+   * Its response may still be streaming: a destination reveals as soon as
+   * React can render it, so the tree on screen routinely has Suspense
+   * boundaries still waiting on later Flight rows. Aborting that response
+   * rejects those rows, and the rejection surfaces through the tree into
+   * whatever error boundary the app has — replacing the page the user is
+   * looking at with an error state, while the successor navigation is still
+   * in flight (codex on #1004).
+   *
+   * So such a navigation's stream is allowed to finish. It is finite and
+   * already in flight; the alternative is a visible error on the page being
+   * departed from. Cancelling is still correct for a navigation whose payload
+   * never reached React at all, which is the case the abort was written for.
+   *
+   * **Handed over, not committed.** This is set when the tree is given to
+   * React, not when React commits it. Marking on commit is a whole React
+   * commit phase too late: the notification would be `NavigationRoot`'s
+   * layout effect, and React runs *descendant* layout effects first — so a
+   * destination that navigates from its own mount layout effect (a redirect
+   * guard) runs before the mark and its just-committed stream gets torn out
+   * from under it. `tests/navigation-supersede.test.ts` already pins that
+   * ordering, and there is no earlier hook short of an extra sibling fiber,
+   * which would shift every `useId` in the payload (see `server/ssr-wrappers`).
+   *
+   * Handing over is the right moment on its own terms, not merely a safe
+   * over-approximation: from the instant React holds the tree it may commit
+   * it without asking, so there is no later point at which "not on screen"
+   * is still knowable from out here. The residue is that a navigation
+   * superseded in the window between handover and commit keeps streaming a
+   * payload nobody sees — bandwidth on a finite response, against a visible
+   * error page the other way (codex on #1004, second round).
+   *
+   * A SET, not a single slot. Between a successor's handover and its commit
+   * React is still showing the previous tree — that is what the transition
+   * buys — so the previous navigation's stream is still feeding the screen and
+   * must stay unabortable. Entries are dropped when a later tree actually
+   * commits (`forgetOlderHandoffs`), which is the moment the trees they fed
+   * are gone. A single slot made a legitimate handover steal protection from
+   * a stream still on screen, and let a superseded navigation overwrite the
+   * winner's entry outright.
+   */
+  const handedOffNavAborts = new Set<AbortController>();
+
+  /**
+   * Cancel a navigation's RSC fetch — unless its tree is the one on screen.
+   *
+   * THE only place a navigation controller is aborted. Every path that gives
+   * up on a navigation calls this, so the "is this tree displayed?" question
+   * is asked once rather than at each site (the same reason `createSpaExits`
+   * exists for the SPA exits). A new abort path is a call to this, not a copy
+   * of `controller.abort()`.
+   *
+   * See `handedOffNavAborts` for why such a navigation keeps its stream.
+   */
+  function abortUnlessHandedOff(controller: AbortController): void {
+    if (handedOffNavAborts.has(controller)) return;
+    controller.abort();
+  }
+
+  /**
+   * 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 — UNLESS its tree is the one on
+   *    screen, in which case tearing the stream down would error the page the
+   *    user is currently looking at. See `handedOffNavAborts`.
+   * 2. Invalidate its render transition so a response that already
+   *    arrived can't commit a stale tree (NavigationRoot's transId guard).
+   *    This happens either way, so skipping the abort cannot let a stale tree
+   *    displace the successor.
+   * 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) {
+      abortUnlessHandedOff(currentNavAbort);
+      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.
+    //
+    // This is a second, independent way a navigation dies, and it fires for
+    // the same reason as the branch above: the browser aborts a
+    // NavigateEvent's signal when that navigation is superseded. So it needs
+    // the same guard — without it, an intercepted push/replace or traversal
+    // whose tree is already on screen still loses its stream, and the guard
+    // above only appears to work because plain `router.navigate()` carries no
+    // external signal (codex on #1004).
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        abortUnlessHandedOff(controller);
+      } else {
+        externalSignal.addEventListener('abort', () => abortUnlessHandedOff(controller), {
+          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 subscribers. This is the ONLY pending representation — React and
+    // non-React consumers alike read it, React ones through
+    // `usePendingNavigation()`'s `useSyncExternalStore` (TIM-1307).
+    for (const listener of pendingListeners) {
+      listener(value);
+    }
+  }
+
+  /**
+   * 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?.();
+      }
+    }
+  }
+
+  return {
+    currentNavAbort: () => currentNavAbort,
+    createNavAbort,
+    runNavigation,
+
+    // Guarded on still owning the router. A superseded navigation can still
+    // reach here: a prefetch hit answers from `prefetchCache`, whose payload
+    // was fetched under the PREFETCH's controller, so aborting this
+    // navigation's controller does not stop it and `perform()` runs to
+    // completion. `navigateTransition`'s stale-transition check happens after
+    // `perform()` returns, so without this the loser would claim ownership
+    // moments before being discarded — and the next navigation would then
+    // abort the winner's still-streaming response, erroring the visible tree
+    // (codex on #1004).
+    markHandedOff(owner: AbortController): void {
+      if (currentNavAbort !== owner) return;
+      handedOffNavAborts.add(owner);
+    },
+
+    // React has committed THIS tree, so every earlier one is unmounted and
+    // their streams no longer feed anything on screen. Forget them — they are
+    // left to finish on their own rather than aborted, since by here they are
+    // nearly done anyway and the point of the set is never to cut a stream
+    // that might still be feeding the screen.
+    //
+    // Pruning on commit rather than at handover is deliberate: between a
+    // successor's handover and its commit, React is still showing the
+    // PREVIOUS tree (that is what the transition buys), so the previous
+    // navigation's stream is still live on screen and must stay unabortable.
+    forgetOlderHandoffs(owner: AbortController): void {
+      for (const controller of handedOffNavAborts) {
+        if (controller !== owner) handedOffNavAborts.delete(controller);
+      }
+    },
+
+    isPending: () => routerPhase.phase === 'navigating',
+    getPendingUrl: () => (routerPhase.phase === 'navigating' ? routerPhase.targetUrl : null),
+    onPendingChange(listener) {
+      pendingListeners.add(listener);
+      return () => pendingListeners.delete(listener);
+    },
+  };
+}

package/src/client/router-pipeline.ts

@@ -0,0 +1,393 @@
+/**
+ * Navigation Pipeline — URL in, tree in React's hands.
+ *
+ * Everything between "the user asked for this URL" and "React is holding the
+ * destination's tree": consult the prefetch cache or fetch, prepare the commit
+ * that makes the page current, and hand the result over inside a transition.
+ *
+ * `router.ts` keeps the *operations* — `navigate`, `refresh`, `handlePopState`,
+ * `prefetch`, `applyRevalidation` — and each of them is a call into here. The
+ * split is the same one `router-effects.ts` and `router-lifecycle.ts` made
+ * (design/18-build-system.md §"No file >500 lines").
+ *
+ * See design/19-client-navigation.md §"Partial Rendering" and §"Prefetching".
+ */
+
+import { fetchRscPayload, NonRscResponse } from './rsc-fetch.js';
+import type { FetchResult } from './rsc-fetch.js';
+import { readPublishedParams, type ParamsSource } from '../shared/payload-root.js';
+import type { PrefetchCache, PrefetchKey } from './segment-cache.js';
+import { prefetchScopeOf } from './segment-cache.js';
+import type { StateTree } from '../shared/segment-info.js';
+import type { NavigationState } from './navigation-context.js';
+import type { NavigationCommitter } from './navigation-commit.js';
+import type { RouterDeps } from './router-types.js';
+import { recordSkew } from './router-skew.js';
+
+/** A fetched payload plus the state update that makes it the current page. */
+export type NavigationPayload = FetchResult & {
+  navState: NavigationState;
+  commit: () => void;
+};
+
+/** Options for a single `performNavigationFetch` call. */
+export interface NavigationFetchOptions {
+  replace: boolean;
+  commitUrl?: string;
+  signal?: AbortSignal;
+  skipHistory?: boolean;
+  departingUrl?: string;
+}
+
+export interface NavigationPipelineDeps extends Pick<
+  NavigationCommitter,
+  'prepareNavigation' | 'currentStateTree'
+> {
+  deps: RouterDeps;
+  prefetchCache: PrefetchCache;
+  /** Record that this navigation's tree reached React (router-lifecycle.ts). */
+  markHandedOff: (owner: AbortController) => void;
+  /** React committed this navigation's tree (router-lifecycle.ts). */
+  forgetOlderHandoffs: (owner: AbortController) => void;
+}
+
+export interface NavigationPipeline {
+  /** Fetch (or replay a prefetch), then stage the commit. */
+  performNavigationFetch: (
+    url: string,
+    options: NavigationFetchOptions
+  ) => Promise<NavigationPayload>;
+  /** Hand a payload to React inside a transition, or render it directly in tests. */
+  renderViaTransition: (
+    url: string,
+    owner: AbortController,
+    perform: () => Promise<NavigationPayload>
+  ) => Promise<void>;
+  /** Render a decoded payload into the DOM if a renderer is available. */
+  renderPayload: (payload: unknown, navState: NavigationState, params: ParamsSource) => void;
+  /** Resolve thenable payloads on the fallback (test) path. */
+  resolveForFallback: (payload: unknown) => Promise<unknown>;
+}
+
+/**
+ * Normalize a departing URL to the pathname the server is told about.
+ *
+ * This is the value sent as `X-Timber-URL` *and* the source half of the
+ * prefetch cache key — one function so a prefetch and the click that consumes
+ * it can never disagree about what "where we came from" means (TIM-1265). The
+ * query is dropped deliberately: it would land in the `_rsc` digest, which is
+ * logged (TIM-1268), and nothing downstream reads it — slot-skip resolution
+ * and interception scope both compare pathnames.
+ *
+ * Absolute inputs parse against the base and ignore it, so one call handles
+ * both `location.href` and a bare pathname.
+ */
+export function departingPathname(raw: string): string {
+  return new URL(raw, 'http://localhost').pathname;
+}
+
+/**
+ * The prefetch cache key for a destination.
+ *
+ * Both halves of the cache are keyed through here — the hover that writes an
+ * entry (`router.ts`'s `prefetch()`) and the click that consumes it
+ * (`performNavigationFetch` below) — so the two cannot disagree about what
+ * identifies a payload. That is the whole point of the key: `from` scopes it
+ * to the page the link was on (TIM-1265) and `scope` to the tree that was
+ * mounted (TIM-1282), and an entry written under one reading of either would
+ * simply never be found under the other, silently costing every prefetch.
+ *
+ * `departingPathname` is applied here rather than by callers for the same
+ * reason: it is also what goes out as `X-Timber-URL`, so the key and the
+ * request describe the same departure point.
+ */
+export function prefetchKeyFor(
+  url: string,
+  departingUrl: string,
+  stateTree: StateTree | undefined
+): PrefetchKey {
+  return { url, from: departingPathname(departingUrl), scope: prefetchScopeOf(stateTree) };
+}
+
+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;
+}
+
+/**
+ * Inspect a decode rejection for version skew before handing the promise on,
+ * without changing what the consumer sees.
+ *
+ * The decode rejects independently of the fetch, and not every consumer
+ * awaits it — NavigationRoot drops it outright when the transition has been
+ * superseded. A stale client reference arriving that way is still evidence
+ * the bundle is superseded, so record it here where every consumer is fed
+ * from, rather than at each place that might drop it (TIM-1275).
+ */
+function observeSkew(decodePromise: Promise<void> | null): Promise<void> | null {
+  decodePromise?.catch((error: unknown) => void recordSkew(error));
+  return decodePromise;
+}
+
+export function createNavigationPipeline({
+  deps,
+  prefetchCache,
+  currentStateTree,
+  prepareNavigation,
+  markHandedOff,
+  forgetOlderHandoffs,
+}: NavigationPipelineDeps): NavigationPipeline {
+  /** Render a decoded RSC payload into the DOM if a renderer is available. */
+  function renderPayload(payload: unknown, navState: NavigationState, params: ParamsSource): void {
+    if (deps.renderRoot) {
+      deps.renderRoot(payload, navState, params);
+    }
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * Render a payload via navigateTransition (production) or renderRoot (tests).
+   * The perform callback should fetch data, prepare the commit, and return the
+   * FetchResult plus the NavigationState and the commit thunk.
+   *
+   * The thunk is handed *through* to NavigationRoot rather than called here:
+   * state management (segmentCache, navState, historyStack) has to happen on
+   * the far side of the supersession check, which only NavigationRoot can
+   * make (TIM-1301). The fallback path below has no transition to be
+   * superseded by, so it commits directly.
+   */
+  async function renderViaTransition(
+    url: string,
+    owner: AbortController,
+    perform: () => Promise<NavigationPayload>
+  ): Promise<void> {
+    // Record that THIS navigation's payload has reached React, at the moment
+    // the tree is built and handed back for `navigateTransition` to give to
+    // React — NOT on commit, which is a whole commit phase too late. See
+    // `handedOffNavAborts` in router-lifecycle.ts.
+    const handOff = (): void => markHandedOff(owner);
+
+    // Drop the earlier handoffs once React has committed this tree — the
+    // trees they were feeding are gone. Wrapped around the commit thunk so it
+    // runs on React's commit and not at handover; see `forgetOlderHandoffs`.
+    const commitAndForget = (commit: () => void) => (): void => {
+      forgetOlderHandoffs(owner);
+      commit();
+    };
+
+    if (deps.navigateTransition) {
+      await deps.navigateTransition(url, async (wrapPayload) => {
+        const result = await perform();
+        // Await the payload's *root row* — the same thing React would suspend
+        // on to render the tree, and the first thing Flight emits. The
+        // previous UI stays on screen while this resolves: nothing has been
+        // handed to React yet, and when it is, NavigationRoot hands it over
+        // inside a transition so a tree that is still streaming does not
+        // displace the departing page (TIM-1306).
+        //
+        // Reading them here rather than with `use()` above the tree is what
+        // keeps a decode failure contained: `result.params` never rejects, so
+        // the rejection reaches React only through the tree, inside whatever
+        // error boundary the app put around it (TIM-1297).
+        const params = await result.params;
+
+        if (isPartialNavigation(result.skippedSegments)) {
+          const segmentUpdates = buildSegmentUpdates(result);
+
+          // Re-wrap the CURRENT element with new context values.
+          // SegmentOutlets read updates from SegmentUpdateContext;
+          // NavigationProvider gets the new pathname; the params published
+          // above the retained tree are the *incoming* route's.
+          const element = wrapPayload(
+            deps._getCurrentPayload?.() ?? result.payload,
+            result.navState,
+            params,
+            segmentUpdates
+          );
+          handOff();
+          return {
+            element,
+            decodePromise: observeSkew(result.decodePromise),
+            commit: commitAndForget(result.commit),
+          };
+        }
+
+        // Full navigation — empty updates, render the new tree.
+        const element = wrapPayload(result.payload, result.navState, params);
+        handOff();
+        return {
+          element,
+          decodePromise: observeSkew(result.decodePromise),
+          commit: commitAndForget(result.commit),
+        };
+      });
+      return;
+    }
+    // Fallback: no transition (tests, no React tree)
+    const result = await perform();
+    handOff();
+    commitAndForget(result.commit)();
+    if (!isPartialNavigation(result.skippedSegments)) {
+      renderPayload(result.payload, result.navState, await result.params);
+    }
+  }
+
+  /**
+   * 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: NavigationFetchOptions
+  ): Promise<NavigationPayload> {
+    // Both halves of the key are sampled here, before the prefetch cache is
+    // consulted, and both are reused for the request itself:
+    //
+    // - the departing page, because an entry fetched from somewhere else
+    //   answers a different question (TIM-1265). `getCurrentUrl()` can't be
+    //   read any later either — the Navigation API may have already committed
+    //   the destination URL (TIM-1232).
+    // - the mounted tree, so the entry this navigation looks up is keyed by
+    //   the same scope the fetch would have been issued with (TIM-1282).
+    //
+    // `currentUrl` is read back off the key rather than computed beside it, so
+    // the pathname sent as X-Timber-URL is the one the lookup used.
+    const stateTree = currentStateTree();
+    const cacheKey = prefetchKeyFor(url, options.departingUrl ?? deps.getCurrentUrl(), stateTree);
+    const currentUrl = cacheKey.from;
+
+    // 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(cacheKey)) {
+      prefetchCache.consume(cacheKey);
+      throw new NonRscResponse(url);
+    }
+
+    // PrefetchResult has optional segmentInfo/params fields — normalize
+    // to null for FetchResult compatibility.
+    const prefetched = prefetchCache.consume(cacheKey);
+    let result: FetchResult | undefined = prefetched
+      ? {
+          payload: prefetched.payload,
+          // A prefetch that predates this field (or the negative-entry
+          // sentinel) publishes nothing rather than the previous route's.
+          params: prefetched.params ?? readPublishedParams(undefined),
+          // Carry the prefetch's stream completion through. It may still be
+          // decoding, and a stale client reference arriving after the click
+          // must reach *this* navigation's recovery rather than dying with
+          // the prefetch that started it (TIM-1275).
+          decodePromise: prefetched.decodePromise ?? null,
+          segmentInfo: prefetched.segmentInfo ?? null,
+          skippedSegments: prefetched.skippedSegments ?? null,
+          // Entries written before this field carried it are treated as
+          // cacheable, which is what they were before a deny could be one.
+          status: prefetched.status ?? 200,
+        }
+      : undefined;
+
+    if (result === undefined) {
+      // Fetch RSC payload with state tree for partial rendering.
+      // Send departing URL (pre-navigation) for slot skip comparison.
+      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).
+    //
+    // Deferred with the rest of the commit: the address bar is navigation
+    // state like the segment cache and the history stack, and a superseded
+    // navigation must not move it either. That guarantee used to hold only
+    // because the superseded fetch was aborted before it got here — a
+    // response that won the race anyway re-pushed the abandoned URL
+    // (TIM-1022's failure mode, made unconditional by TIM-1301).
+    const commitHistoryUrl = (): void => {
+      if (options.skipHistory) return;
+      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);
+    const params = await result.params;
+
+    // Prepare the atomic navigation-state update. It is published by the
+    // caller once this navigation is known to have won (TIM-1301).
+    // 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, commit } = prepareNavigation(url, {
+      payload: isPartial || hasSkippedSlots ? null : payload,
+      params,
+      segmentInfo: result.segmentInfo,
+      status: result.status,
+    });
+
+    return {
+      ...result,
+      payload,
+      params,
+      navState,
+      commit: () => {
+        commitHistoryUrl();
+        commit();
+        // Notify nuqs (and any other listener) that the URL is now the
+        // destination's. It travels *inside* the commit rather than after
+        // the navigation resolves because the listener answers it by reading
+        // `window.location.search`, and the commit is what moves it — the
+        // publish happens on React's commit of the tree, which can land after
+        // the navigation promise settles (TIM-1301, codex on #998).
+        window.dispatchEvent(new Event('timber:navigation-end'));
+      },
+    };
+  }
+
+  return { performNavigationFetch, renderViaTransition, renderPayload, resolveForFallback };
+}