@timber-js/app 0.2.0-alpha.196 → 0.2.0-alpha.198

package/src/client/navigation-transition.ts

@@ -0,0 +1,278 @@
+/**
+ * Navigation transition — the router-level hand-off of a navigation's tree to
+ * React, and the supersession that governs it.
+ *
+ * `navigateTransition` runs a navigation's fetch OUTSIDE any transition scope
+ * and hands the resulting tree to React through a `NavigationRender`, which
+ * is a synchronous `startTransition` around `root.render` (client/react-root.ts).
+ * Two React behaviours force that shape; both were measured on React 19.2.7
+ * (tests/navigation-transition-suspense.test.ts pins the observable half).
+ *
+ * 1. A transition scope does not survive an `await`. `startTransition`
+ *    restores the previous scope in its `finally`, which for an async
+ *    callback runs when that callback RETURNS — i.e. at its first `await`.
+ *    So an update scheduled past an await inside `startTransition(async …)`
+ *    is an ordinary urgent update:
+ *
+ *      startTransition(() => render(x))                     -> 'HOME' held
+ *      startTransition(async () => { await p; render(x) })  -> fallback shown
+ *
+ *    Left uncorrected, every navigation whose new tree suspends replaces the
+ *    visible page with a Suspense fallback — the exact thing NavigationRoot
+ *    exists to prevent (TIM-1306). React documents the caveat under
+ *    `startTransition`: updates after an await need their own transition.
+ *
+ * 2. Re-wrapping *inside* the async callback is not enough. Returning a
+ *    thenable from `startTransition` hands it to `ReactSharedInternals.S`,
+ *    which calls react-dom's `entangleAsyncAction`. That opens an action
+ *    scope: `currentEntangledLane` collects EVERY transition update
+ *    scheduled while the scope is open — including one from a nested,
+ *    fully synchronous `startTransition` — and rendering that lane throws
+ *    `currentEntangledActionThenable`, suspending until the action settles.
+ *    Which is after the promise `navigateTransition` hands back, so a caller
+ *    that awaits a navigation and then reads the DOM sees the departing
+ *    page, and the TIM-1301 publish (a layout effect on the commit) is just
+ *    as late. (Not `ReactSharedInternals.asyncTransitions` — that counter is
+ *    write-only in 19.2.7.)
+ *
+ * No async action is created here, so every navigation commits as soon as
+ * React can render its destination — where TIM-1301 put it. That holds for
+ * ALL of them. It used not to hold for `<Link>`, which wrapped
+ * `router.navigate()` in its own `useTransition`: that action scope entangled
+ * the root's updates just the same, so a Link navigation committed only once
+ * the payload had finished decoding, and with it `pushState`, the segment
+ * cache and `timber:navigation-end`. Link now calls `router.navigate()`
+ * outside any transition and tracks its own `isPending` with a plain
+ * `useState` (TIM-1307).
+ *
+ * Nothing here may reopen an action scope: no `startTransition` callback in
+ * this path may return a thenable, and no caller may invoke this from inside
+ * a React action scope. That is a rule about `startTransition`, not about
+ * `perform` — `perform` is async by contract and is awaited OUTSIDE any
+ * transition scope, which is exactly why it is safe.
+ *
+ * Standalone `startTransition` rather than `useTransition`'s is deliberate:
+ * the hook's is tied to a single fiber and tracks one async callback at a
+ * time, and two overlapping navigations through it corrupted React's hook
+ * tracking ("Rendered more hooks than during the previous render"). Each
+ * navigation needs an independent lane. This matches the Next.js pattern
+ * (TIM-625): "No useTransition in the router at all — only standalone
+ * startTransition."
+ *
+ * See design/19-client-navigation.md §"How Pending State Works"
+ */
+
+import type { ReactNode } from 'react';
+import type { NavigationRender } from './navigation-root.tsx';
+
+// ─── Transition Result ──────────────────────────────────────────
+
+/**
+ * What a navigation's `perform()` hands back to the transition.
+ *
+ * Declared once and shared by every layer that passes it along — the router's
+ * `RouterDeps.navigateTransition` imports it too — so a field cannot be added
+ * to the producer and dropped by the adapter in between. `E` is the element
+ * type: `ReactNode` here, `unknown` in the router, which never touches it.
+ */
+export interface TransitionResult<E = ReactNode> {
+  /** The wrapped tree to render. */
+  element: E;
+  /** Resolves when the Flight stream finishes decoding, or null. */
+  decodePromise: Promise<void> | null;
+  /**
+   * Publishes the navigation's state — segment cache, pathname, address bar,
+   * history stack, and the client's record of the mounted tree — and
+   * announces it to listeners outside React.
+   *
+   * Run when React commits this tree, not when the tree is handed over: a
+   * tree React is still waiting on, or one a later navigation replaces first,
+   * has been given to React without being on screen. A superseded navigation
+   * never runs it and leaves every one of those consumers describing the
+   * route still on screen (TIM-1301).
+   */
+  commit: () => void;
+}
+
+// ─── Navigation Transition Counter ──────────────────────────────
+// Monotonically increasing counter that increments each time
+// navigateTransition() is called. Used to detect stale transitions:
+// if a newer transition started while the current one's perform()
+// was in flight, the current transition is stale and should reject.
+//
+// Separate from the link-pending navId (which only increments on
+// link clicks). This counter covers all navigation types: link clicks,
+// programmatic navigate(), refresh(), and handlePopState().
+//
+// Uses globalThis for singleton guarantee across chunks — same pattern
+// as NavigationContext and the link pending store.
+
+const NAV_TRANSITION_KEY = Symbol.for('__timber_nav_transition_counter');
+
+/**
+ * `waiters` are woken on every bump so an in-flight navigation can stop
+ * waiting on its own payload the moment it is superseded — see
+ * `settleOnDecodeOrSupersession`.
+ */
+interface TransitionCounter {
+  id: number;
+  waiters: Set<() => void>;
+}
+
+function getTransitionCounter(): TransitionCounter {
+  const g = globalThis as Record<symbol, unknown>;
+  const existing = g[NAV_TRANSITION_KEY] as Partial<TransitionCounter> | undefined;
+  if (!existing) {
+    const created: TransitionCounter = { id: 0, waiters: new Set() };
+    g[NAV_TRANSITION_KEY] = created;
+    return created;
+  }
+  // A duplicated copy of this module may have created the singleton before
+  // `waiters` existed. The object is shared across chunks, so fill it in
+  // rather than replacing it — replacing would strand the other copy's id.
+  existing.waiters ??= new Set();
+  return existing as TransitionCounter;
+}
+
+/** Bump the counter and wake everything waiting on an older transition. */
+function bumpTransitionCounter(): number {
+  const counter = getTransitionCounter();
+  counter.id += 1;
+  for (const wake of [...counter.waiters]) wake();
+  return counter.id;
+}
+
+/**
+ * Invalidate all in-flight navigation transitions. Any navigateTransition()
+ * call whose perform() has not yet committed will reject with AbortError
+ * instead of committing its element.
+ *
+ * Called by the router when a render supersedes in-flight navigations
+ * WITHOUT going through navigateTransition() — the cached popstate replay
+ * renders directly, which doesn't bump the counter, so a stale forward
+ * navigation's render would otherwise pass the `counter.id !== transId`
+ * guard and commit the forward page over the replayed back page (TIM-1022).
+ */
+export function supersedeNavigationTransitions(): void {
+  bumpTransitionCounter();
+}
+
+/**
+ * Wait for the payload to finish decoding, OR for this transition to be
+ * superseded — whichever happens first.
+ *
+ * A superseded navigation must stop waiting on its own stream. The stream is
+ * deliberately NOT aborted once its tree has been handed to React (the tree
+ * may be on screen with boundaries still feeding from it — see
+ * `handedOffNavAbort` in `client/router-lifecycle.ts`), so there is nothing
+ * left to make `decodePromise` settle promptly. Awaiting it bare would keep
+ * the loser's `router.navigate()` promise pending for the rest of the stream
+ * — and forever if it stalls — which is what `<Link>`'s `isPending` is timed
+ * against, so the losing link would sit spinning while the winner loaded
+ * (codex on #1004).
+ *
+ * A decode *failure* still propagates: it is a real error for this
+ * navigation, and the caller's recovery is timed against it.
+ */
+function settleOnDecodeOrSupersession(
+  decodePromise: Promise<void>,
+  counter: TransitionCounter,
+  transId: number
+): Promise<void> {
+  if (counter.id !== transId) return Promise.resolve();
+  return new Promise<void>((resolve, reject) => {
+    const stopWaiting = (): void => {
+      counter.waiters.delete(wake);
+    };
+    const wake = (): void => {
+      if (counter.id !== transId) {
+        stopWaiting();
+        resolve();
+      }
+    };
+    counter.waiters.add(wake);
+    decodePromise.then(
+      () => {
+        stopWaiting();
+        resolve();
+      },
+      (error: unknown) => {
+        stopWaiting();
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    );
+  });
+}
+
+// ─── navigateTransition ─────────────────────────────────────────
+
+/**
+ * Run a full navigation, handing its tree to React in a transition.
+ *
+ * The `perform` callback fetches the RSC payload, updates router state, and
+ * returns the wrapped React element. `perform` is async by contract and runs
+ * OUTSIDE any transition scope — only the `render` that hands its result over
+ * is wrapped, in a synchronous `startTransition` (see the module comment).
+ *
+ * Do not call this from inside a React action scope, and never let a
+ * `startTransition` callback in this path return a thenable: either opens an
+ * action scope that entangles the update and defers the commit until the
+ * action settles (TIM-1306, TIM-1307).
+ *
+ * Returns a Promise that resolves when the async work completes — the payload
+ * is fetched, decoded, and handed to React. It does **not** wait for React to
+ * commit the tree, so the state that publishes on that commit (address bar,
+ * segment cache, history entry, pathname) may still be a beat behind when it
+ * resolves. Anything that needs the destination to be current should listen
+ * for `timber:navigation-end`, which is dispatched by the publish itself.
+ *
+ * Awaiting the publish here was tried and rejected: it makes the promise
+ * depend on a React commit, which never arrives if the root unmounts
+ * mid-navigation, and deadlocks any caller that awaits a navigation inside
+ * `act()`.
+ *
+ * Rejects with an `AbortError` when a newer transition started while this
+ * one's `perform()` was in flight — the stale tree is never handed to React
+ * and its `commit` never runs (TIM-629, TIM-1301).
+ *
+ * Used for: navigate(), refresh(), popstate with fetch.
+ */
+export function navigateTransition(
+  perform: () => Promise<TransitionResult>,
+  render: NavigationRender
+): Promise<void> {
+  // Increment the transition counter SYNCHRONOUSLY (before any await). Each
+  // call gets a unique transId; the counter is the same globalThis
+  // singleton, so a newer call always has a higher id.
+  const counter = getTransitionCounter();
+  const transId = bumpTransitionCounter();
+
+  const superseded = () => new DOMException('Navigation superseded', 'AbortError');
+
+  return (async () => {
+    const { element, decodePromise, commit } = await perform();
+    if (counter.id !== transId) {
+      decodePromise?.catch(() => {});
+      throw superseded();
+    }
+    // Hand the tree over with its commit attached. NavigationRoot runs it if
+    // and when React commits this tree, so a navigation that is superseded
+    // while its payload streams publishes nothing (TIM-1301).
+    //
+    // This is THE update that must not hide the departing page (TIM-1306);
+    // `render` is the synchronous transition around `root.render`.
+    render(element, commit);
+    // React may commit the tree before this settles — that is the point:
+    // the destination reveals as React is able to render it
+    // rather than waiting for the whole Flight stream. The await is here so
+    // the promise this function hands back still means "the payload is
+    // decoded", which is what the router's scroll restoration, the
+    // Navigation API deferred and `<Link>`'s `isPending` are timed against.
+    //
+    // ...unless this navigation loses first, in which case it stops waiting
+    // on a stream that is no longer its business. See
+    // `settleOnDecodeOrSupersession`.
+    if (decodePromise) await settleOnDecodeOrSupersession(decodePromise, counter, transId);
+    if (counter.id !== transId) throw superseded();
+  })();
+}

package/src/client/nuqs-adapter.tsx

@@ -21,6 +21,7 @@ import {
 } from 'nuqs/adapters/custom';
 import { getRouter } from './router-ref.ts';
 import { getNavigationApi } from './navigation-api.ts';
+import { locationSearch } from './location-search.ts';
 
 // ─── Adapter Hook ─────────────────────────────────────────────────
 
@@ -32,15 +33,13 @@ import { getNavigationApi } from './navigation-api.ts';
  *   (used by nuqs for selective re-rendering)
  */
 function useTimberAdapter(_watchKeys: string[]): AdapterInterface {
-  const [searchParams, setSearchParams] = useState(
-    () => new URLSearchParams(window.location.search)
-  );
+  const [searchParams, setSearchParams] = useState(() => new URLSearchParams(locationSearch()));
 
   // Sync search params on popstate (back/forward) and after
   // timber navigations that change the URL.
   useEffect(() => {
     function sync() {
-      setSearchParams(new URLSearchParams(window.location.search));
+      setSearchParams(new URLSearchParams(locationSearch()));
     }
 
     window.addEventListener('popstate', sync);
@@ -97,7 +96,7 @@ function useTimberAdapter(_watchKeys: string[]): AdapterInterface {
   return {
     searchParams,
     updateUrl,
-    getSearchParamsSnapshot: () => new URLSearchParams(window.location.search),
+    getSearchParamsSnapshot: () => new URLSearchParams(locationSearch()),
   };
 }
 

package/src/client/params-context.ts

@@ -31,7 +31,6 @@
 'use client';
 
 import React, { createElement, useMemo, use } from 'react';
-import { _setCurrentParams, _setCurrentSlotParams } from './state.ts';
 import { toNullProtoRecord, type CoercedParams } from '../shared/param-value.ts';
 import { readPublishedParams, type PublishedParams } from '../shared/payload-root.ts';
 import type { SlotParamsRecord } from '../shared/slot-params.ts';
@@ -53,7 +52,9 @@ export type ParamsContextValue = PublishedParams;
  * `useParamsContext()` arrives through the client-reference graph with the
  * app's own components. A duplicate would put the provider on instance A and
  * every reader on instance B, so `useContext` returns `null` and every
- * `useSegmentParams()` call silently falls back to the module snapshot.
+ * `useSegmentParams()` call throws the outside-the-timber-app-tree error
+ * even though the provider is mounted (the module-snapshot fallback it once
+ * silently landed on was deleted in TIM-1425).
  *
  * This module was the one client context without the guard — harmless while
  * the provider travelled inside the payload, in the same graph as its readers,
@@ -90,11 +91,10 @@ function getOrCreateContext(): React.Context<ParamsContextValue | null> {
 const ParamsContext = getOrCreateContext();
 
 /**
- * Read the params provided by the tree. Returns null when no provider is
- * above the caller — a component rendered outside a timber route, a
- * `useSegmentParams()` call from outside React entirely, or any component
- * during SSR (where the params reach the hook through the ALS-backed SSR data
- * context instead, and there is no client-owned tree to hold a provider).
+ * Read the params provided by the tree. Returns null only when no provider
+ * is above the caller — a component rendered outside a timber route. During
+ * SSR the wrapper chain mounts `PayloadRoot` too (TIM-1424), so both sides
+ * resolve through this context.
  */
 export function useParamsContext(): ParamsContextValue | null {
   return React.useContext(ParamsContext);
@@ -115,13 +115,12 @@ interface ParamsProviderProps {
  * the tree would shadow this one for the region below it, which is precisely
  * the defect TIM-1297 fixed.
  *
- * The module-level snapshot in `state.ts` is written during render rather
- * than in an effect. It is the fallback path for `useSegmentParams()` called
- * outside a component (tests, module scope), and an effect would leave that
- * path reading the *previous* route's params for the whole commit — the
- * window in which a navigation's components actually run. Writing during
- * render is safe here because the value is derived entirely from props: a
- * double-invoked render in StrictMode writes the same record twice.
+ * This used to also write a module-level snapshot during render, as the
+ * fallback for `useSegmentParams()` called outside a component. That tier is
+ * gone (TIM-1425) — the provider is unconditional on every render path,
+ * browser and SSR alike, so the hook reads context or throws. Removing the
+ * write also removes render-phase shared mutation from the SSR environment,
+ * where concurrent requests rendered through this component.
  */
 function ParamsProvider({ params, slotParams, children }: ParamsProviderProps) {
   // Restore the null prototype the wire could not carry. Flight rejects a
@@ -139,10 +138,6 @@ function ParamsProvider({ params, slotParams, children }: ParamsProviderProps) {
     [params, slotParams]
   );
 
-  // Keep the out-of-component fallback in step with the tree being rendered.
-  _setCurrentParams(value.params);
-  _setCurrentSlotParams(value.slotParams);
-
   return createElement(ParamsContext.Provider, { value }, children);
 }
 

package/src/client/react-root.ts

@@ -0,0 +1,72 @@
+/**
+ * React root host — the one React root the router renders the page through.
+ *
+ * The router owns the displayed tree and drives React: every render is
+ * `startTransition(() => root.render(<NavigationRoot rendered={…} />))`,
+ * synchronous, with a fresh `rendered` object whose `publish` NavigationRoot
+ * runs when React commits that tree (TIM-1301, TIM-1431).
+ *
+ * The root itself is created lazily. On the RSC-payload path `hydrate()`
+ * creates it by hydrating the server HTML. On the JS-only path (no inlined
+ * payload, TIM-600) nothing may create it at bootstrap — `createRoot(document)`
+ * followed by a render would take React ownership of the document and blank
+ * the SSR HTML — so the first `render()` (the first navigation, or a
+ * revalidation after a server action) creates it with the tree it renders.
+ * That first render carries no placeholder, and a fresh root with nothing
+ * committed leaves the container alone until it can commit, so the SSR HTML
+ * stays until the destination is ready (TIM-580).
+ *
+ * `container` is `document` in production; tests pass an element.
+ */
+
+import { createElement, startTransition, type ReactNode } from 'react';
+import { createRoot, hydrateRoot, type HydrationOptions, type Root } from 'react-dom/client';
+import { NavigationRoot, type NavigationRender, type RenderedTree } from './navigation-root.tsx';
+import type { TopLoaderConfig } from './top-loader.tsx';
+
+export interface ReactRootHost {
+  /**
+   * Hydrate the server HTML with `element` as the initial tree. Nothing is
+   * published on that commit — the address bar, pathname and history already
+   * describe the page the server sent.
+   */
+  hydrate(element: ReactNode, options?: HydrationOptions): void;
+  /**
+   * Hand a tree to React in a synchronous transition; `publish` runs when
+   * React commits it. Creates the root on first use.
+   */
+  render: NavigationRender;
+  /** Tear the root down (tests). */
+  unmount(): void;
+}
+
+export function createReactRoot(options: {
+  container: Document | Element;
+  topLoaderConfig?: TopLoaderConfig;
+}): ReactRootHost {
+  const { container, topLoaderConfig } = options;
+  let root: Root | null = null;
+
+  const rootElement = (rendered: RenderedTree) =>
+    createElement(NavigationRoot, { rendered, topLoaderConfig });
+
+  return {
+    hydrate(element, hydrationOptions) {
+      root = hydrateRoot(container, rootElement({ element, publish: null }), hydrationOptions);
+    },
+    render(element, publish) {
+      const target = (root ??= createRoot(container));
+      // Synchronous, and returns nothing: an async callback would drop the
+      // transition scope at its first await, and a returned thenable would
+      // open an action scope that holds the commit until it settles
+      // (TIM-1306, TIM-1307 — see client/navigation-transition.ts).
+      startTransition(() => {
+        target.render(rootElement({ element, publish }));
+      });
+    },
+    unmount() {
+      root?.unmount();
+      root = null;
+    },
+  };
+}

package/src/client/router-lifecycle.ts

@@ -16,7 +16,7 @@
  * See design/19-client-navigation.md §"How Pending State Works".
  */
 
-import { supersedeNavigationTransitions } from './navigation-root.tsx';
+import { supersedeNavigationTransitions } from './navigation-transition.ts';
 import type { RouterPhase } from './router-types.ts';
 
 /** The subset of `RouterDeps` the navigation lifecycle needs. */

package/src/client/router-pipeline.ts

@@ -16,13 +16,31 @@
 import { fetchRscPayload, NonRscResponse } from './rsc-fetch.ts';
 import type { FetchResult } from './rsc-fetch.ts';
 import { readPublishedParams, type ParamsSource } from '../shared/payload-root.ts';
-import type { PrefetchCache, PrefetchKey } from './segment-cache.ts';
+import type { PrefetchCache, PrefetchKey, FlightOutcome } from './segment-cache.ts';
 import { prefetchScopeOf } from './segment-cache.ts';
 import type { StateTree } from '../shared/segment-info.ts';
 import type { NavigationState } from './navigation-context.ts';
-import type { NavigationCommitter } from './navigation-commit.ts';
+import { isPartialNavigation, type NavigationCommitter } from './navigation-commit.ts';
 import type { RouterDeps } from './router-types.ts';
 import { recordSkew } from './router-skew.ts';
+import { SingleflightTimeoutError } from '../cache/singleflight.ts';
+
+/**
+ * Race a promise against an abort signal. The promise continues regardless —
+ * only the *await* gives up. Used so a click superseded by a newer navigation
+ * stops waiting for a shared prefetch flight without aborting the flight
+ * itself (TIM-1438).
+ */
+function raceAbort<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(signal.reason);
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) => {
+      signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+    }),
+  ]);
+}
 
 /** A fetched payload plus the state update that makes it the current page. */
 export type NavigationPayload = FetchResult & {
@@ -64,7 +82,12 @@ export interface NavigationPipeline {
     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;
+  renderPayload: (
+    payload: unknown,
+    navState: NavigationState,
+    params: ParamsSource,
+    commit: () => void
+  ) => void;
   /** Resolve thenable payloads on the fallback (test) path. */
   resolveForFallback: (payload: unknown) => Promise<unknown>;
 }
@@ -109,10 +132,6 @@ export function prefetchKeyFor(
   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.
@@ -155,10 +174,21 @@ export function createNavigationPipeline({
   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 {
+  /**
+   * Render a decoded RSC payload into the DOM, publishing `commit` when the
+   * tree is current. The renderer owns that moment (see `RootRenderer`);
+   * with no renderer there is no tree to wait for, so it publishes now.
+   */
+  function renderPayload(
+    payload: unknown,
+    navState: NavigationState,
+    params: ParamsSource,
+    commit: () => void
+  ): void {
     if (deps.renderRoot) {
-      deps.renderRoot(payload, navState, params);
+      deps.renderRoot(payload, navState, params, commit);
+    } else {
+      commit();
     }
   }
 
@@ -260,9 +290,11 @@ export function createNavigationPipeline({
     // 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);
+    const commit = commitAndForget(result.commit);
+    if (isPartialNavigation(result.skippedSegments)) {
+      commit();
+    } else {
+      renderPayload(result.payload, result.navState, await result.params, commit);
     }
   }
 
@@ -320,9 +352,52 @@ export function createNavigationPipeline({
         }
       : undefined;
 
+    // If a hover prefetch is in-flight, join it instead of issuing a
+    // duplicate (TIM-1438). The click races its await against its own signal
+    // so a superseded navigation gives up immediately — the shared flight
+    // continues for other consumers. On flight failure (network error,
+    // singleflight timeout), fall through to a fresh fetch — the failed
+    // hover should not block a click that might succeed.
+    if (result === undefined) {
+      const inflight = prefetchCache.joinInflight(cacheKey);
+      if (inflight) {
+        try {
+          const outcome = await raceAbort(inflight, options.signal);
+          if (outcome.kind === 'non-route') {
+            throw new NonRscResponse(url);
+          }
+          // Consume the ready entry so a second click re-fetches
+          prefetchCache.consume(cacheKey);
+          result = {
+            payload: outcome.result.payload,
+            params: outcome.result.params ?? readPublishedParams(undefined),
+            decodePromise: outcome.result.decodePromise ?? null,
+            segmentInfo: outcome.result.segmentInfo ?? null,
+            skippedSegments: outcome.result.skippedSegments ?? null,
+            status: outcome.result.status ?? 200,
+          };
+        } catch (error) {
+          // Supersession aborts propagate — don't retry a cancelled navigation
+          if (error instanceof DOMException && error.name === 'AbortError') throw error;
+          if (options.signal?.aborted) throw options.signal.reason;
+          // Retriable failures fall through to a fresh fetch: singleflight
+          // timeout (hover hung) and transport TypeError (transient network
+          // error). Framework control-flow errors — NonRscResponse,
+          // VersionSkewError, RedirectError, ServerErrorResponse — are
+          // definitive server answers and must reach navigate's recovery.
+          if (error instanceof SingleflightTimeoutError || error instanceof TypeError) {
+            // fall through to fresh fetch below
+          } else {
+            throw error;
+          }
+        }
+      }
+    }
+
     if (result === undefined) {
-      // Fetch RSC payload with state tree for partial rendering.
-      // Send departing URL (pre-navigation) for slot skip comparison.
+      // No in-flight hover prefetch, or the joined flight failed — fetch
+      // directly with the navigation's signal so superseded navigations
+      // abort immediately.
       result = await fetchRscPayload(url, deps, stateTree, currentUrl, options.signal);
     }
 
@@ -357,17 +432,16 @@ export function createNavigationPipeline({
     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;
+    // caller once this navigation is known to have won (TIM-1301). Whether
+    // the payload is stored for replay — not when it has skip holes — is
+    // `prepareNavigation`'s decision, made from `skippedSegments` and
+    // `segmentInfo` (TIM-1432).
     const { navState, commit } = prepareNavigation(url, {
-      payload: isPartial || hasSkippedSlots ? null : payload,
+      payload,
       params,
       segmentInfo: result.segmentInfo,
       status: result.status,
+      skippedSegments: result.skippedSegments,
     });
 
     return {

package/src/client/router-types.ts

@@ -14,7 +14,7 @@ import type { ParamsSource } from '../shared/payload-root.ts';
 import type { SegmentInfo } from '../shared/segment-info.ts';
 import type { SegmentCache, PrefetchCache } from './segment-cache.ts';
 import type { HistoryStack } from './history.ts';
-import type { TransitionResult } from './navigation-root.tsx';
+import type { TransitionResult } from './navigation-transition.ts';
 
 export interface NavigationOptions {
   /** Set to false to prevent scroll-to-top on forward navigation */
@@ -61,7 +61,17 @@ export type RscDecoder = (fetchPromise: Promise<Response>) => unknown;
 export type RootRenderer = (
   element: unknown,
   navState: NavigationState,
-  params: ParamsSource
+  params: ParamsSource,
+  /**
+   * Publishes the state that makes this tree the current page (segment
+   * cache, pathname, history stack, address bar). The renderer runs it when
+   * the tree is on screen — in production from React's commit of the tree
+   * (`NavigationRoot`'s layout effect), a test double synchronously. It is not run before
+   * handing the tree over: a replay or revalidation whose tree suspends is
+   * given to React without being on screen, and publishing then advertises
+   * slot content keys the slot content cache has not recorded (TIM-1423).
+   */
+  commit: () => void
 ) => void;
 
 /**