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

package/src/client/browser-entry/hydrate.ts

@@ -6,20 +6,25 @@
  * 2. No RSC payload: deferred root creation via installDeferredNavigation
  *
  * Pre-hydration ordering contract (MUST execute in this order):
- *   1. initRouter()        — creates the global router so useRouter()
- *                            works during render
- *   2. setCurrentParams()  — populates params snapshot so
- *      + setNavigationState()  useSegmentParams() and usePathname()
- *                            return correct values during hydration
- *   3. hydrateRoot()       — synchronously executes component render
- *                            functions that depend on steps 1-2
+ *   1. initRouter()          — creates the global router so useRouter()
+ *                              works during render
+ *   2. setNavigationState()  — populates pathname/search so usePathname()
+ *                              returns correct values during hydration
+ *   3. hydrateRoot()         — synchronously executes component render
+ *                              functions that depend on steps 1-2
+ *
+ * Params are not part of this sequence. They arrive on the payload root and
+ * are published by `PayloadRoot` at the top of the tree, so
+ * `useSegmentParams()` is correct during hydration without anything having to
+ * run before it (TIM-1294, TIM-1297).
  *
  * See design/19-client-navigation.md §"NavigationContext"
  */
 
 import { createElement } from 'react';
 import { hydrateRoot, createRoot } from 'react-dom/client';
-import { getRouterOrNull, setCurrentParams } from '#client-internal';
+import { getRouterOrNull } from '#client-internal';
+import { PayloadRoot } from '../params-context.js';
 import {
   NavigationProvider,
   getNavigationState,
@@ -79,26 +84,21 @@ interface HydrateOptions {
 }
 
 /**
- * Run the pre-hydration sequence: read server-embedded params and
- * set navigation state. Must be called AFTER initRouter().
+ * Run the pre-hydration sequence: set navigation state from the address bar.
+ * Must be called AFTER initRouter().
+ *
+ * Params are no longer seeded here. They used to arrive on two inline scripts
+ * that had to execute before `hydrateRoot()`, because hydration synchronously
+ * renders components that read them. They now ride the payload root, and the
+ * provider that publishes them renders before its own descendants — so the
+ * ordering the step existed to guarantee is now a property of the tree rather
+ * than of the bootstrap sequence (TIM-1294, TIM-1297).
  */
 export function runPreHydration(): void {
-  const earlyParams = (self as unknown as Record<string, unknown>).__timber_params;
-  if (earlyParams && typeof earlyParams === 'object') {
-    setCurrentParams(earlyParams as Record<string, string | string[]>);
-    setNavigationState({
-      params: earlyParams as Record<string, string | string[]>,
-      pathname: window.location.pathname,
-      search: window.location.search,
-    });
-    delete (self as unknown as Record<string, unknown>).__timber_params;
-  } else {
-    setNavigationState({
-      params: {},
-      pathname: window.location.pathname,
-      search: window.location.search,
-    });
-  }
+  setNavigationState({
+    pathname: window.location.pathname,
+    search: window.location.search,
+  });
 }
 
 /**
@@ -123,11 +123,22 @@ export function hydrateApp({ rscResult, config }: HydrateOptions): void {
     // startTransition, so React keeps old UI visible while new Suspense
     // boundaries resolve during navigation. See design/05-streaming.md.
     const navState = getNavigationState();
-    const withNav = createElement(
-      NavigationProvider,
-      { value: navState },
+    // The same chain `renderTree()` in router-init.ts builds on every
+    // navigation, in the same order. It has to be: an element type that is
+    // present here and absent on the first navigation (or the reverse)
+    // changes the type at that position, and React remounts everything below
+    // it — losing the layout state partial navigation exists to preserve.
+    //
+    // `source` is the payload's params promise, not a resolved record: the
+    // inlined Flight stream is still arriving and hydration cannot wait for
+    // it. PayloadRoot suspends on it exactly where React was going to suspend
+    // on `element` (TIM-1297).
+    const withParams = createElement(
+      PayloadRoot,
+      { source: rscResult.params },
       element as React.ReactNode
     );
+    const withNav = createElement(NavigationProvider, { value: navState }, withParams);
     const withUpdates = createElement(
       SegmentUpdateContext.Provider,
       { value: EMPTY_SEGMENT_UPDATES },

package/src/client/browser-entry/index.ts

@@ -40,11 +40,13 @@ import schemaCodecs from 'virtual:timber-schema';
 import { setLinkCodecs } from '../../params/codec-registry.js';
 setLinkCodecs(schemaCodecs);
 
-import { setClientDeploymentId, setStaticMode } from '../rsc-fetch.js';
+import { setClientDeploymentId, setStaticMode, setBasePath } from '../rsc-fetch.js';
+import { initStaleClient } from '../stale-client.js';
 
 import { setupServerActions } from './action-dispatch.js';
 import { createRscPayloadStream } from './rsc-stream.js';
 import { createTimberRouter } from './router-init.js';
+import { readPublishedParams } from '../../shared/payload-root.js';
 import { runPreHydration, hydrateApp } from './hydrate.js';
 import { setupPostHydration } from './post-hydration.js';
 import { setupHmr } from './hmr.js';
@@ -63,6 +65,16 @@ function bootstrap(runtimeConfig: typeof config): void {
     setClientDeploymentId(deploymentId);
   }
 
+  // Reactive skew recovery for failures that never reach the router —
+  // lazily imported client components, preloaded stylesheets. No-ops when
+  // there is no deployment ID, i.e. in dev (TIM-1260).
+  initStaleClient(deploymentId);
+
+  // Deployment base path (Vite's resolved `base`). Must be set before any
+  // RSC fetch — under a non-root base the payloads live below the prefix
+  // like every other emitted file (TIM-1261).
+  setBasePath((runtimeConfig as Record<string, unknown>).base as string | undefined);
+
   // Static mode: fetch _rsc/*.rsc files instead of route URLs with
   // Accept headers. Static hosts ignore Accept headers (TIM-1243).
   if ((runtimeConfig as Record<string, unknown>).output === 'static') {
@@ -75,6 +87,7 @@ function bootstrap(runtimeConfig: typeof config): void {
   // Step 3: Create router + Navigation API integration
   const { router, navApiController } = createTimberRouter({
     initialElement: rscResult?.element ?? undefined,
+    initialParams: rscResult?.params,
     clientSegmentCache:
       ((runtimeConfig as Record<string, unknown>).clientSegmentCache as boolean) ?? false,
   });
@@ -90,6 +103,7 @@ function bootstrap(runtimeConfig: typeof config): void {
     router,
     navApiController,
     initialElement: rscResult?.element ?? null,
+    initialParams: rscResult?.params ?? readPublishedParams(undefined),
   });
 
   // Step 7: HMR (dev-only, no-op in production)

package/src/client/browser-entry/post-hydration.ts

@@ -15,12 +15,15 @@ import type { RouterInstance } from '#client-internal';
 import { getNavigationState } from '../navigation-context.js';
 import type { NavigationApiController } from '../navigation-api.js';
 import { getScrollY } from './scroll.js';
+import type { ParamsSource } from '../../shared/payload-root.js';
 
 interface PostHydrationOptions {
   router: RouterInstance;
   navApiController: NavigationApiController | null;
   /** Decoded RSC element from initial SSR (null if no RSC payload) */
   initialElement: unknown;
+  /** The params that payload published, from the same decode. */
+  initialParams: ParamsSource;
 }
 
 /**
@@ -30,20 +33,14 @@ export function setupPostHydration({
   router,
   navApiController,
   initialElement,
+  initialParams,
 }: PostHydrationOptions): void {
-  // Store the initial page in the history stack so back-button works
-  // after the first navigation. We store the decoded RSC element so
-  // back navigation can replay it instantly without a server fetch.
-  // Params were captured from the server-embedded __timber_params by
-  // runPreHydration() — without them on the entry, the cached replay on
-  // back-navigation would normalize params to {} and wipe every
-  // useSegmentParams() consumer on the initial page (TIM-1037).
   // Populate the segment cache from server-embedded segment metadata.
   // This enables state tree diffing from the very first client navigation.
   // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
   const timberSegments = (self as unknown as Record<string, unknown>).__timber_segments;
   const initialSegmentInfo = Array.isArray(timberSegments)
-    ? (timberSegments as import('../segment-cache').SegmentInfo[])
+    ? (timberSegments as import('../../shared/segment-info.js').SegmentInfo[])
     : null;
   if (initialSegmentInfo) {
     router.initSegmentCache(initialSegmentInfo);
@@ -53,9 +50,13 @@ export function setupPostHydration({
   // Store the initial page in the history stack so back-button works
   // after the first navigation. Include segmentInfo so the segment
   // cache is restored correctly on popstate cached replay.
+  // Replaying this entry on a Back re-renders `initialElement` and republishes
+  // `initialParams`. Both came out of one split of one decoded payload root
+  // (rsc-stream.ts), so the entry cannot replay with another route's params —
+  // which is what a separately-seeded copy used to do (TIM-1037, TIM-1285).
   router.historyStack.push(window.location.pathname + window.location.search, {
     payload: initialElement,
-    params: getNavigationState().params,
+    params: initialParams,
     segmentInfo: initialSegmentInfo,
   });
 

package/src/client/browser-entry/router-init.ts

@@ -9,6 +9,8 @@
 
 import { createElement } from 'react';
 import { createFromFetch } from '../../rsc-runtime/browser.js';
+import { PayloadRoot } from '../params-context.js';
+import { readPublishedParams, type ParamsSource } from '../../shared/payload-root.js';
 import { createRouter, setGlobalRouter } from '#client-internal';
 import type { RouterDeps, RouterInstance } from '#client-internal';
 import type { NavigationState } from '#client-internal';
@@ -29,6 +31,8 @@ import { getScrollY, scrollToHashTarget } from './scroll.js';
 
 export interface RouterInitOptions {
   initialElement?: unknown;
+  /** The params the hydration payload published, beside `initialElement`. */
+  initialParams?: ParamsSource;
   clientSegmentCache?: boolean;
 }
 
@@ -58,6 +62,63 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
   // very first client navigation (before any wrapPayload call).
   let currentPayload: unknown = options?.initialElement ?? null;
 
+  // The params `currentPayload` is displayed with. Tracked beside it because
+  // the two render paths that do NOT receive a payload — a shallow search
+  // update and any re-wrap of the current tree — must republish the same
+  // record rather than dropping it. They are written together, in one place
+  // (`renderTree`), so they cannot come apart.
+  let currentParams: ParamsSource = options?.initialParams ?? readPublishedParams(undefined);
+
+  /**
+   * Build the client's wrapper chain around a tree. **The only place it is
+   * built.**
+   *
+   * Every render path goes through here — hydration builds the same chain in
+   * `hydrate.ts` against this shape, and a navigation, a shallow search
+   * update, a popstate replay and a revalidation all call this. That matters
+   * beyond tidiness: an element type present on one render and absent on the
+   * next changes the type at that position, so React unmounts and remounts
+   * everything below it, destroying the layout state partial navigation
+   * exists to preserve (caught by tests/e2e/segment-merge-navigation.test.ts
+   * when the params wrapper was conditional).
+   *
+   * `PayloadRoot` is *above* `currentPayload`, which on a partial navigation
+   * is the retained tree. That position is the whole design: it is the only
+   * provider a reader in a skipped layout can resolve to (TIM-1297).
+   *
+   * Pure — building the element does not make it the displayed one. Every
+   * caller pairs this with `publishTree` at the point the tree is actually
+   * handed to React, because a navigation builds its element before it is
+   * known to have won and a superseded one must leave `currentPayload`
+   * describing the route still on screen (TIM-1301).
+   */
+  function renderTree(
+    tree: unknown,
+    navState: NavigationState,
+    params: ParamsSource,
+    segmentUpdates?: Map<string, React.ReactNode>
+  ): React.ReactElement {
+    const withParams = createElement(PayloadRoot, { source: params }, tree as React.ReactNode);
+    const withNav = createElement(NavigationProvider, { value: navState }, withParams);
+    const withUpdates = createElement(
+      SegmentUpdateContext.Provider,
+      { value: segmentUpdates ?? EMPTY_SEGMENT_UPDATES },
+      withNav
+    );
+    return createElement(TimberNuqsAdapter, null, withUpdates);
+  }
+
+  /**
+   * Record the tree the client is now displaying, and the params published
+   * over it. Written together — the two paths that re-wrap without a fresh
+   * payload (a shallow search update, a partial navigation) read them back as
+   * a pair and would otherwise restore one route's tree with another's params.
+   */
+  function publishTree(tree: unknown, params: ParamsSource): void {
+    currentPayload = tree;
+    currentParams = params;
+  }
+
   // ─── History API Patch ──────────────────────────────────────────
   // Patch pushState/replaceState to detect external URL changes (nuqs
   // shallow updates, replaceUrl, third-party libraries). When the router
@@ -93,25 +154,20 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
     if (currentSearch === navState.search) return;
     if (!currentPayload) return;
 
+    // A shallow search update does not re-render the tree from the server, so
+    // the params are unchanged — but they are the client's to publish now, and
+    // this path rebuilds the whole chain. Republishing `currentParams` is what
+    // keeps a `?q=` change from silently clearing the route's params
+    // (TIM-1285's failure mode, on a path that used to be exempt from it
+    // because the record lived inside the payload).
     const newNavState: NavigationState = {
-      params: navState.params,
       pathname: navState.pathname,
       search: currentSearch,
     };
     setNavigationState(newNavState);
 
-    const withNav = createElement(
-      NavigationProvider,
-      { value: newNavState },
-      currentPayload as React.ReactNode
-    );
-    const withUpdates = createElement(
-      SegmentUpdateContext.Provider,
-      { value: EMPTY_SEGMENT_UPDATES },
-      withNav
-    );
-    const wrapped = createElement(TimberNuqsAdapter, null, withUpdates);
-    transitionRender(wrapped);
+    publishTree(currentPayload, currentParams);
+    transitionRender(renderTree(currentPayload, newNavState, currentParams));
   }
 
   window.history.pushState = function (
@@ -179,58 +235,58 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
     // Wraps with NavigationProvider + TimberNuqsAdapter.
     //
     // For navigation renders (navigate, refresh, popstate-with-fetch),
-    // navigateTransition is used instead — it wraps the entire navigation
-    // in a React transition with useOptimistic for the pending URL.
+    // navigateTransition is used instead — it hands the destination tree to
+    // React in a transition so the departing page stays visible.
     //
     // navState is passed explicitly by the router — no temporal coupling
     // with getNavigationState().
-    renderRoot: (element: unknown, navState: NavigationState) => {
-      currentPayload = element;
-      const withNav = createElement(
-        NavigationProvider,
-        { value: navState },
-        element as React.ReactNode
-      );
-      const withUpdates = createElement(
-        SegmentUpdateContext.Provider,
-        { value: EMPTY_SEGMENT_UPDATES },
-        withNav
-      );
-      const wrapped = createElement(TimberNuqsAdapter, null, withUpdates);
-      transitionRender(wrapped);
+    renderRoot: (element: unknown, navState: NavigationState, params: ParamsSource) => {
+      // These paths render what is already decided (a replay, a
+      // revalidation), so publishing here is the commit.
+      publishTree(element, params);
+      transitionRender(renderTree(element, navState, params));
     },
 
-    // Run a navigation inside a React transition with optimistic pending URL.
-    // The entire fetch + state update runs inside startTransition. useOptimistic
-    // shows the pending URL immediately and reverts to null when the transition
-    // commits (atomic with the new tree + params).
+    // Hand a navigation's tree to React in a transition (navigation-root.tsx).
+    // The fetch runs outside any transition scope; only the state update that
+    // hands the tree over is wrapped, and in a synchronous `startTransition`.
+    // Do NOT make this callback's caller an async React action — see the
+    // entanglement note in `navigateTransition` (TIM-1306, TIM-1307).
     //
     // The perform callback receives a wrapPayload function that wraps the
     // decoded RSC payload with NavigationProvider + NuqsAdapter. navState
     // is passed explicitly by the router — no getNavigationState() needed.
-    navigateTransition: (pendingUrl: string, perform) => {
-      return navigateTransition(pendingUrl, async () => {
-        const { element, decodePromise } = await perform(
+    navigateTransition: (url: string, perform) => {
+      return navigateTransition(url, async () => {
+        // What wrapPayload built, held until the transition wins. The client's
+        // record of the displayed tree is navigation state like any other, so
+        // it rides the same commit as the segment cache rather than being
+        // written as a side effect of building the element (TIM-1301).
+        let displayed: { tree: unknown; params: ParamsSource } | null = null;
+        const { element, decodePromise, commit } = await perform(
           (
             rawPayload: unknown,
             navState: NavigationState,
+            params: ParamsSource,
             segmentUpdates?: Map<string, unknown>
           ) => {
-            currentPayload = rawPayload;
-            const withNav = createElement(
-              NavigationProvider,
-              { value: navState },
-              rawPayload as React.ReactNode
-            );
-            const withUpdates = createElement(
-              SegmentUpdateContext.Provider,
-              { value: (segmentUpdates ?? EMPTY_SEGMENT_UPDATES) as Map<string, React.ReactNode> },
-              withNav
+            displayed = { tree: rawPayload, params };
+            return renderTree(
+              rawPayload,
+              navState,
+              params,
+              segmentUpdates as Map<string, React.ReactNode> | undefined
             );
-            return createElement(TimberNuqsAdapter, null, withUpdates);
           }
         );
-        return { element: element as React.ReactNode, decodePromise };
+        return {
+          element: element as React.ReactNode,
+          decodePromise,
+          commit: () => {
+            if (displayed) publishTree(displayed.tree, displayed.params);
+            commit();
+          },
+        };
       });
     },
 

package/src/client/browser-entry/rsc-stream.ts

@@ -13,12 +13,20 @@
 
 import { createFromReadableStream } from '../../rsc-runtime/browser.js';
 import { isPageUnloading } from '../unload-guard.js';
+import { splitPayloadRoot, type PublishedParams } from '../../shared/payload-root.js';
 
 type FlightSegment = [isBootstrap: 0] | [isData: 1, data: string];
 
 export interface RscStreamResult {
   /** The decoded RSC element (thenable/lazy — resolved by React during render) */
   element: unknown;
+  /**
+   * The params the same payload published beside that tree. A promise: the
+   * inlined Flight stream is still arriving when this runs, and hydration must
+   * not wait for it. `PayloadRoot` suspends on it at the position React was
+   * going to suspend on `element` anyway (TIM-1297).
+   */
+  params: Promise<PublishedParams>;
 }
 
 /**
@@ -152,6 +160,7 @@ export function createRscPayloadStream(): RscStreamResult | null {
     queueMicrotask(onDOMContentLoaded);
   }
 
-  const element = createFromReadableStream(rscPayload);
-  return { element };
+  const { tree, params } = splitPayloadRoot(createFromReadableStream(rscPayload));
+  // The stream is a thenable, so the split is asynchronous on both halves.
+  return { element: tree, params: params as Promise<PublishedParams> };
 }

package/src/client/error-boundary.tsx

@@ -21,20 +21,12 @@
 import { Component, createElement, type ReactNode } from 'react';
 import { getSsrData } from './ssr-data.js';
 import { getRouterOrNull } from './router-ref.js';
-
-// ─── Page Unload Detection ───────────────────────────────────────────────────
-// Track whether the page is being unloaded (user refreshed or navigated away).
-// When this is true, error boundaries suppress activation — the error is from
-// the aborted connection, not an application error.
-let _isUnloading = false;
-if (typeof window !== 'undefined') {
-  window.addEventListener('beforeunload', () => {
-    _isUnloading = true;
-  });
-  window.addEventListener('pagehide', () => {
-    _isUnloading = true;
-  });
-}
+import { markStaleFromError } from './stale-client.js';
+// Page unload detection: when the page is being torn down, error boundaries
+// suppress activation — the error is from the aborted connection, not the
+// application. unload-guard.ts is the single owner of that state; this module
+// used to keep its own copy, which drifted (TIM-1260).
+import { isPageUnloading } from './unload-guard.js';
 
 // ─── Digest Types ────────────────────────────────────────────────────────────
 
@@ -124,13 +116,26 @@ export class TimberErrorBoundary extends Component<
     // The aborted connection causes React's streaming hydration to error,
     // but the page is about to be replaced — showing an error boundary
     // would be a jarring flash for the user.
-    if (_isUnloading) {
+    if (isPageUnloading()) {
       return { hasError: false, error: null };
     }
 
     return { hasError: true, error };
   }
 
+  componentDidCatch(error: Error): void {
+    // A stale bundle most often surfaces here rather than as a rejected
+    // navigation: a client reference missing from this build's manifest, or
+    // a lazily-imported chunk the CDN no longer has, thrown during render.
+    //
+    // Recording it is all that happens — this boundary still renders its
+    // fallback, and the recovery is the user's next navigation, which the
+    // router turns into a full document load. Reloading from here would be a
+    // page load the user did not ask for, on a page that may be mid-rollout
+    // and would come back just as stale (TIM-1275).
+    markStaleFromError(error);
+  }
+
   componentDidUpdate(prevProps: TimberErrorBoundaryProps): void {
     // Reset error state when children change (e.g. client-side navigation).
     // Without this, navigating from one error page to another keeps the

package/src/client/history.ts

@@ -1,7 +1,8 @@
 // History Stack — stores RSC payloads by URL for instant back/forward navigation
 // See design/19-client-navigation.md § History Stack
 
-import type { SegmentInfo } from './segment-cache';
+import type { ParamsSource } from '../shared/payload-root.js';
+import type { SegmentInfo } from '../shared/segment-info.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -9,12 +10,18 @@ export interface HistoryEntry {
   /** The complete segment tree payload at the time of navigation */
   payload: unknown;
   /**
-   * Route params for this page (for useSegmentParams). Every entry that can
-   * be replayed must carry them — the initial SSR entry gets them from the
-   * server-embedded __timber_params, navigation entries from X-Timber-Params,
-   * and revalidation overwrites preserve the current state (TIM-1037).
+   * The params that payload published. Replaying the tree republishes them,
+   * because the client owns the provider now and reads it from here
+   * (TIM-1297).
+   *
+   * Stored beside the tree but never *produced* beside it: both come out of
+   * one `splitPayloadRoot` on one decoded root and travel together through
+   * `prepareNavigation`, the only producer of an entry. That is the property
+   * that matters — when they were derived from separate channels, a replay
+   * could restore one route's tree with another route's params (TIM-1037,
+   * TIM-1285).
    */
-  params?: Record<string, string | string[]> | null;
+  params: ParamsSource;
   /**
    * Segment metadata for this page's route. Restored into the segment cache
    * on popstate cached replay so the next forward navigation computes a

package/src/client/internal.ts

@@ -19,7 +19,7 @@ export type {
   RouterPhase,
   RscDecoder,
   RootRenderer,
-} from './router.js';
+} from './router-types.js';
 export { getRouter, getRouterOrNull, setGlobalRouter } from './router-ref.js';
 
 // ── SSR bridge ───────────────────────────────────────────────────────────
@@ -32,14 +32,15 @@ export type { SegmentContextValue } from './segment-context.js';
 
 // ── Segment cache ────────────────────────────────────────────────────────
 export { SegmentCache, PrefetchCache } from './segment-cache.js';
-export type { SegmentNode, StateTree } from './segment-cache.js';
+export type { SegmentNode, PrefetchKey } from './segment-cache.js';
+export type { SegmentInfo, StateTree } from '../shared/segment-info.js';
 
 // ── History ──────────────────────────────────────────────────────────────
 export { HistoryStack } from './history.js';
 export type { HistoryEntry } from './history.js';
 
 // ── Params (internal setter + raw hooks) ─────────────────────────────────
-export { setCurrentParams } from './use-segment-params.js';
+export { setCurrentParams, setCurrentSlotParams } from './use-segment-params.js';
 export { useSearchParams } from './use-search-params.js';
 
 // ── Navigation context ───────────────────────────────────────────────────

package/src/client/link.tsx

@@ -19,7 +19,8 @@
 // - searchParams and inline query string are mutually exclusive
 
 import {
-  useTransition,
+  useRef,
+  useState,
   type AnchorHTMLAttributes,
   type ReactNode,
   type MouseEvent as ReactMouseEvent,
@@ -472,11 +473,38 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
   const { href: baseHref } = buildLinkProps({ href, params: segmentParams, searchParams });
 
   // ─── Per-link pending state ─────────────────────────────────────────
-  // Each Link owns a useTransition. On click, it wraps
-  // router.navigate() in startTransition — only this Link re-renders
-  // for isPending, zero siblings touched. The transition tracks the
-  // full navigation lifecycle (fetch + render + commit).
-  const [isPending, startTransition] = useTransition();
+  // Local `useState`, deliberately NOT `useTransition` (TIM-1307).
+  //
+  // Either shape keeps the re-render local — the state lives on this Link's
+  // own fiber, so no sibling link is touched. The difference is what wrapping
+  // `router.navigate()` in a transition does to the REST of the app: returning
+  // a thenable from `startTransition` hands it to `ReactSharedInternals.S`,
+  // which calls react-dom's `entangleAsyncAction`. That opens an action scope
+  // whose `currentEntangledLane` collects every transition update scheduled
+  // while it is open — including `NavigationRoot`'s `setRendered`, which is a
+  // fully synchronous `startTransition` in a different component — and
+  // rendering that lane suspends on `currentEntangledActionThenable` until the
+  // action settles. `navigateTransition` awaits `decodePromise`, so a Link
+  // navigation used to commit only after the whole Flight stream had decoded,
+  // while `useRouter().push()` committed as soon as React could render it.
+  //
+  // Two commit-timing regimes, and the slower one was the dominant path: no
+  // streaming reveal, and the TIM-1301 publish (address bar, segment cache,
+  // `timber:navigation-end`) waited for full decode. Not opening an action
+  // scope is what collapses them into one.
+  //
+  // `isPending` runs from the click until `router.navigate()` settles, which
+  // is after `decodePromise` — the same lifecycle the router's pending store
+  // and the TopLoader use.
+  //
+  // `clickSeq` exists because a superseded navigation RESOLVES rather than
+  // rejecting: `runNavigation` swallows AbortErrors. So clicking the same link
+  // twice in quick succession settles the first promise while the second is
+  // still in flight, and an unguarded clear would report idle mid-navigation.
+  // Only the newest click for this link may clear its flag. Written on click
+  // and nowhere else, so there is no reset for a settle handler to race.
+  const [isPending, setIsPending] = useState(false);
+  const clickSeq = useRef(0);
   const linkStatus = isPending ? LINK_PENDING : LINK_IDLE;
 
   // Preserve search params from the current URL when requested.
@@ -544,8 +572,27 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
         // from the RSC fetch URL inside the router (TIM-1035).
         const absoluteHref = resolved.pathname + resolved.search + resolved.hash;
 
-        startTransition(async () => {
-          await router.navigate(absoluteHref, { scroll: shouldScroll });
+        const seq = ++clickSeq.current;
+        const settle = () => {
+          if (clickSeq.current === seq) setIsPending(false);
+        };
+        setIsPending(true);
+        router.navigate(absoluteHref, { scroll: shouldScroll }).then(settle, (error: unknown) => {
+          settle();
+          // Rethrow, so a navigation error that the router did not already
+          // recover from surfaces as an unhandled rejection — the same
+          // regime as `useRouter().push()`'s `void router.navigate(...)`.
+          //
+          // It used to reach the nearest error boundary instead: React
+          // re-throws a rejected async action during render (measured on
+          // 19.2.7). That replaced the departing page with the app's error
+          // UI, which contradicts what every other failure path here
+          // promises — a navigation that fails leaves the user on the page
+          // they were already looking at (TIM-1306). Recoverable failures
+          // never get here anyway; `runNavigation` swallows AbortErrors and
+          // `recoverFromNavigationError` turns a failed fetch into a full
+          // document load.
+          throw error;
         });
       }
     : userOnClick; // External links — just pass through user's onClick