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

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

package/src/client/navigation-api.ts

@@ -97,8 +97,8 @@ export interface NavigationApiController {
   /**
    * Resolve the deferred promise created by setRouterNavigating(true),
    * clearing the browser's native loading state. Call this when the
-   * navigation fully completes — aligned with when the TopLoader's
-   * pendingUrl clears (same finally block in router.navigate).
+   * navigation fully completes — the same finally block in router.navigate
+   * that clears the router's pending store.
    */
   completeRouterNavigation: () => void;
 
@@ -147,7 +147,7 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
   // setRouterNavigating(true) is called, resolved by completeRouterNavigation().
   // The navigate event handler intercepts with this promise so the browser's
   // native loading state (tab spinner) stays active until the navigation
-  // completes — aligned with TopLoader's pendingUrl lifecycle.
+  // completes — the same lifecycle the TopLoader is driven by.
   let routerNavDeferred: { promise: Promise<void>; resolve: () => void } | null = null;
 
   function handleNavigate(event: NavigateEvent): void {

package/src/client/navigation-commit.ts

@@ -0,0 +1,174 @@
+/**
+ * What it means for a page to be "current" on the client.
+ *
+ * One module owns every write that makes a navigation's destination the
+ * current page, and the read that describes the current page back to the
+ * server. Keeping them together is the point: `X-Timber-State-Tree` is
+ * derived from the segment cache, so the thing that publishes and the thing
+ * that reports have to agree about when a page becomes current.
+ *
+ * See design/19-client-navigation.md §"State Update Invariants".
+ */
+
+import { buildSegmentTree, type SegmentCache } from './segment-cache.js';
+import type { HistoryStack } from './history.js';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.js';
+import type { ParamsSource } from '../shared/payload-root.js';
+import { setNavigationState, type NavigationState } from './navigation-context.js';
+
+/** Everything a commit needs to describe the page it makes current. */
+export interface NavigationCommitInput {
+  payload: unknown;
+  /** The params that payload published — replayed with it on popstate. */
+  params: ParamsSource;
+  /**
+   * The rendered chain's metadata, or null/undefined when this commit
+   * carries none at all — a revalidation payload, or a history entry
+   * stored before the channel existed.
+   *
+   * An empty *array* is a different statement from an absent one: the
+   * server rendered a route with no layout-bearing segments (a layoutless
+   * app — the missing-root-layout check is a warning, not an error), so
+   * the correct tree is the empty one. Collapsing the two left the
+   * departing route's tree in place, which `treePaths` then reported as
+   * mounted — enough to select an intercepting rewrite whose slot is not
+   * on screen (TIM-1282).
+   */
+  segmentInfo?: SegmentInfo[] | null;
+  /** When true, clear the segment cache if segmentInfo is absent
+   *  (popstate replay for entries without layout metadata). */
+  clearSegmentCacheOnEmpty?: boolean;
+}
+
+/**
+ * A navigation's destination, split into what a render needs and what a
+ * commit publishes.
+ */
+export interface PreparedNavigation {
+  /** The state the incoming tree renders with. Pure — safe before winning. */
+  navState: NavigationState;
+  /** Publishes the destination. Call only once the render has won. */
+  commit: () => void;
+}
+
+export interface NavigationCommitter {
+  prepareNavigation(url: string, opts: NavigationCommitInput): PreparedNavigation;
+  currentStateTree(): StateTree | undefined;
+  updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void;
+}
+
+/**
+ * Derive the navigation state (pathname + search) a URL renders with.
+ *
+ * Pure: publishing it — the module-level fallback for tests and SSR, and the
+ * globalThis bridge — is `prepareNavigation`'s commit, which runs only once
+ * the render is known to have won (TIM-1301). Callers pass the returned value
+ * explicitly to renderRoot/wrapPayload, so a render never depends on the
+ * publish having happened first.
+ */
+export function deriveNavigationState(url: string): NavigationState {
+  // Params are not part of it. They travel with the payload and are published
+  // by the one client-owned `ParamsProvider` as the new tree renders, which is
+  // also what clears the previous route's — a route with no params of its own
+  // still publishes an empty record (TIM-1294/TIM-1297, and the clearing
+  // requirement from TIM-1285).
+  const parsed = new URL(url, 'http://localhost');
+  return { pathname: parsed.pathname || '/', search: parsed.search };
+}
+
+export function createNavigationCommitter(deps: {
+  segmentCache: SegmentCache;
+  historyStack: HistoryStack;
+  /** Read at call time — the router's `clientSegmentCache` opt-in. */
+  clientSegmentCache: () => boolean | undefined;
+}): NavigationCommitter {
+  const { segmentCache, historyStack } = deps;
+
+  /**
+   * Update the segment cache from server-provided segment metadata.
+   *
+   * Runs whether or not `clientSegmentCache` is enabled: the tree is also
+   * where the mounted tree paths come from, and those cross on every
+   * navigation. What the flag gates is which parts get serialized — see
+   * `currentStateTree`.
+   */
+  function updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void {
+    if (!segmentInfo || segmentInfo.length === 0) return;
+    const tree = buildSegmentTree(segmentInfo);
+    if (tree) {
+      segmentCache.set('/', tree);
+    }
+  }
+
+  return {
+    updateSegmentCache,
+
+    /**
+     * The X-Timber-State-Tree to send with the next RSC request.
+     *
+     * Two different things travel on one header. `segments`/`slots` are the
+     * caching opt-in and are omitted unless `clientSegmentCache` is on.
+     * `treePaths` is how the server learns which route is actually mounted,
+     * which stops being derivable from the address bar as soon as a modal is
+     * open — so it crosses regardless (TIM-1282). Undefined when there is
+     * nothing to say, so a no-op header never enters the `_rsc` cache key.
+     *
+     * Reads what the last *committed* navigation published, so a superseded
+     * navigation's destination can never end up describing the mounted tree
+     * (TIM-1301).
+     */
+    currentStateTree(): StateTree | undefined {
+      const tree = segmentCache.serializeStateTree();
+      if (deps.clientSegmentCache()) return tree;
+      return tree.treePaths ? { segments: [], treePaths: tree.treePaths } : undefined;
+    },
+
+    /**
+     * Prepare all navigation-owned state for a new page — without publishing
+     * any of it. Every code path that changes the "current page" must go
+     * through this function, which is what makes "forgot a field" impossible
+     * by construction.
+     *
+     * Returns the destination's `NavigationState`, which is a pure function of
+     * the URL and is what the incoming tree is *rendered* with, plus a
+     * `commit` thunk that performs the writes that make a page current:
+     * 1. Segment cache — update from server-provided segment metadata
+     * 2. Navigation state — pathname/search for usePathname/useSearchParams
+     * 3. History stack — store the payload for instant back/forward replay
+     *
+     * Nothing is written until `commit()` runs, and on a transitioned
+     * navigation it runs only once the transition is known to have won — see
+     * `renderViaTransition` and `NavigationRoot`. A navigation superseded
+     * while its payload was in flight never calls it, so the cache, the
+     * pathname the client reports and the history stack all keep describing
+     * the route still on screen (TIM-1301).
+     *
+     * Callers with state of their own to publish — the address bar, the
+     * client's record of the mounted tree — wrap this thunk rather than
+     * commit beside it, so there stays exactly one moment at which a page
+     * becomes current.
+     */
+    prepareNavigation(url: string, opts: NavigationCommitInput): PreparedNavigation {
+      const navState = deriveNavigationState(url);
+
+      return {
+        navState,
+        commit() {
+          if (opts.segmentInfo && opts.segmentInfo.length > 0) {
+            updateSegmentCache(opts.segmentInfo);
+          } else if (opts.segmentInfo?.length === 0 || opts.clearSegmentCacheOnEmpty) {
+            segmentCache.clear();
+          }
+
+          setNavigationState(navState);
+
+          historyStack.push(url, {
+            payload: opts.payload,
+            params: opts.params,
+            segmentInfo: opts.segmentInfo,
+          });
+        },
+      };
+    },
+  };
+}