@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

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

@@ -1,20 +1,20 @@
 /**
- * Hydration — pre-hydration sequence and hydrating the React root.
+ * Hydration — making the server-rendered page current and hydrating the
+ * React root with it.
  *
  * Handles two paths:
  * 1. RSC payload available: hydrate the router's React root with the payload
- * 2. No RSC payload: nothing — the root is created by the first render
- *    (client/react-root.ts)
+ * 2. No RSC payload: nothing to hydrate — the root is created by the first
+ *    render (client/react-root.ts) — but the page is still made current
  *
- * Pre-hydration ordering contract (MUST execute in this order):
- *   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
+ * Either way the page becomes current through `RouterInstance.hydrate`, the
+ * same prepare-and-commit every navigation uses, committed before the tree
+ * is handed to React. The one ordering left is that the router exists
+ * before `hydrateRoot()`, so `useRouter()` works during render. Pathname
+ * and search reach the tree as props of its NavigationProvider, from the
+ * router's prepared navState — there is no store to seed first (TIM-1541).
  *
- * Params are not part of this sequence. They arrive on the payload root and
+ * Params are not part of this sequence either. 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).
@@ -22,11 +22,10 @@
  * See design/19-client-navigation.md §"NavigationContext"
  */
 
-import { getRouterOrNull } from '#client-internal';
-import { getNavigationState, setNavigationState } from '../navigation-context.ts';
 import { isPageUnloading } from '../unload-guard.ts';
-import { locationSearch } from '../location-search.ts';
 import type { ReactRootHost } from '../react-root.ts';
+import { readPublishedParams } from '../../shared/payload-root.ts';
+import type { SegmentInfo } from '../../shared/segment-info.ts';
 
 import type { RscStreamResult } from './rsc-stream.ts';
 import type { RouterInitResult } from './router-init.ts';
@@ -74,45 +73,39 @@ interface HydrateOptions {
   rscResult: RscStreamResult | null;
   /** The router's React root — the one every navigation renders through. */
   reactRoot: ReactRootHost;
-  /** The router's wrapper chain — see `RouterInitResult.renderTree`. */
-  renderTree: RouterInitResult['renderTree'];
+  /** Makes the page current and builds its tree — see `RouterInitResult.hydrate`. */
+  hydrate: RouterInitResult['hydrate'];
 }
 
 /**
- * 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).
+ * Take the segment metadata the server embedded in the document
+ * (`self.__timber_segments`), and remove it. It describes the chain the
+ * server rendered, so the first client navigation can send a state tree.
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header".
  */
-export function runPreHydration(): void {
-  setNavigationState({
-    pathname: window.location.pathname,
-    search: locationSearch(),
-  });
+function takeEmbeddedSegmentInfo(): SegmentInfo[] | null {
+  const embedded: unknown = Reflect.get(self, '__timber_segments');
+  Reflect.deleteProperty(self, '__timber_segments');
+  return Array.isArray(embedded) ? embedded : null;
 }
 
 /**
- * Hydrate the React tree when an RSC payload is available.
+ * Make the server-rendered page current, and hydrate the React tree with it
+ * when an RSC payload is available.
  *
  * Wraps the payload with the router's chain (NavigationProvider,
  * TimberNuqsAdapter, the slot content cache, ...) and hydrates the router's
  * React root with it, on the document.
  *
- * When no RSC payload is available (JS-only client) there is nothing to
- * hydrate and nothing to do: the root must not be created at bootstrap —
+ * When no RSC payload is available (JS-only client) the page is committed
+ * at once and there is nothing to hydrate: the root must not be created at
+ * bootstrap —
  * `createRoot(document).render()` would take React ownership of the entire
  * document and blank the SSR HTML — so the router's first render, i.e. the
  * first navigation or revalidation, creates it with the tree it renders
  * (`createReactRoot`, TIM-600 / TIM-580).
  */
-export function hydrateApp({ rscResult, reactRoot, renderTree }: HydrateOptions): void {
-  if (!rscResult) return;
-
+export function hydrateApp({ rscResult, reactRoot, hydrate }: HydrateOptions): void {
   // The chain is the router's own `renderTree`, not a copy: 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
@@ -123,26 +116,28 @@ export function hydrateApp({ rscResult, reactRoot, renderTree }: HydrateOptions)
   // 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 wrapped = renderTree(rscResult.element, getNavigationState(), rscResult.params);
-
-  if (process.env.NODE_ENV !== 'production') {
-    if (!getRouterOrNull()) {
-      throw new Error('[timber] hydrateRoot called before initRouter() — bootstrap order violated');
-    }
-  }
-
-  reactRoot.hydrate(wrapped, {
-    // Suppress recoverable hydration errors from deny/error signals
-    // inside Suspense boundaries. The server already handled these
-    // (wrapStreamWithErrorHandling closes the stream cleanly after
-    // the shell is flushed). React replays the error during hydration
-    // but the server HTML is already correct — no recovery needed.
-    onRecoverableError(error: unknown) {
-      if (isPageUnloading()) return;
-      if (process.env.NODE_ENV === 'development') {
-        queueOrShowHydrationError(error);
-        console.debug('[timber] Hydration recoverable error:', error);
-      }
-    },
-  });
+  const page = {
+    payload: rscResult?.element ?? null,
+    params: rscResult?.params ?? readPublishedParams(undefined),
+    segmentInfo: takeEmbeddedSegmentInfo(),
+  };
+  //
+  // `hydrate` comes from the router's own init, so the router exists by
+  // construction when the tree it builds renders.
+  hydrate(page, (element) =>
+    reactRoot.hydrate(element, {
+      // Suppress recoverable hydration errors from deny/error signals
+      // inside Suspense boundaries. The server already handled these
+      // (wrapStreamWithErrorHandling closes the stream cleanly after
+      // the shell is flushed). React replays the error during hydration
+      // but the server HTML is already correct — no recovery needed.
+      onRecoverableError(error: unknown) {
+        if (isPageUnloading()) return;
+        if (process.env.NODE_ENV === 'development') {
+          queueOrShowHydrationError(error);
+          console.debug('[timber] Hydration recoverable error:', error);
+        }
+      },
+    })
+  );
 }

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

@@ -7,8 +7,8 @@
  *   action-dispatch.ts  — server action callServer callback
  *   rsc-stream.ts       — __timber_f chunk handling + ReadableStream
  *   router-init.ts      — createRouter + Navigation API setup
- *   hydrate.ts          — pre-hydration sequence + hydrating the root
- *   post-hydration.ts   — history stack, segment cache, popstate, scroll
+ *   hydrate.ts          — makes the server page current + hydrates the root
+ *   post-hydration.ts   — popstate, scroll
  *   hmr.ts              — dev-only HMR + error forwarding
  *   scroll.ts           — getScrollY helper
  *
@@ -18,11 +18,11 @@
  *   2. createRscPayloadStream()  — decode inlined RSC payload
  *   3. createReactRoot() +       — the root host the router renders through,
  *      createTimberRouter()        then the router + Navigation API
- *   4. runPreHydration()         — set params + navigation state
- *   5. hydrateApp()              — hydrate the root (no-op without a payload)
- *   6. setupPostHydration()      — history stack, popstate, scroll
- *   7. setupHmr()                — dev-only HMR wiring
- *   8. timber-ready signal       — E2E test readiness indicator
+ *   4. hydrateApp()              — make the page current through the router,
+ *                                   hydrate the root (no root without a payload)
+ *   5. setupPostHydration()      — popstate, scroll
+ *   6. setupHmr()                — dev-only HMR wiring
+ *   7. timber-ready signal       — E2E test readiness indicator
  *
  * Design docs: 18-build-system.md §"Entry Files", 19-client-navigation.md
  */
@@ -44,8 +44,7 @@ import { createRscPayloadStream } from './rsc-stream.ts';
 import { createTimberRouter } from './router-init.ts';
 import { createReactRoot } from '../react-root.ts';
 import type { TopLoaderConfig } from '../top-loader.tsx';
-import { readPublishedParams } from '../../shared/payload-root.ts';
-import { runPreHydration, hydrateApp } from './hydrate.ts';
+import { hydrateApp } from './hydrate.ts';
 import { setupPostHydration } from './post-hydration.ts';
 import { setupHmr } from './hmr.ts';
 
@@ -53,7 +52,7 @@ import { setupHmr } from './hmr.ts';
 
 setupServerActions();
 
-// ─── 2–7. Bootstrap ─────────────────────────────────────────────
+// ─── 2–6. Bootstrap ─────────────────────────────────────────────
 
 function bootstrap(runtimeConfig: typeof config): void {
   // Initialize deployment ID for version skew detection (TIM-446).
@@ -89,35 +88,25 @@ function bootstrap(runtimeConfig: typeof config): void {
     container: document,
     topLoaderConfig: (runtimeConfig as { topLoader?: TopLoaderConfig }).topLoader,
   });
-  const { router, navApiController, renderTree } = createTimberRouter({
+  const { router, navApiController, hydrate } = createTimberRouter({
     render: reactRoot.render,
-    initialElement: rscResult?.element ?? undefined,
-    initialParams: rscResult?.params,
     clientSegmentCache:
       ((runtimeConfig as Record<string, unknown>).clientSegmentCache as boolean) ?? false,
   });
 
-  // Step 4: Pre-hydration — set params + navigation state (MUST run after router init)
-  runPreHydration();
+  // Step 4: Make the page current and hydrate (no root without a payload)
+  hydrateApp({ rscResult, reactRoot, hydrate });
 
-  // Step 5: Hydrate or set up deferred root creation
-  hydrateApp({ rscResult, reactRoot, renderTree });
+  // Step 5: Post-hydration wiring
+  setupPostHydration({ router, navApiController });
 
-  // Step 6: Post-hydration wiring
-  setupPostHydration({
-    router,
-    navApiController,
-    initialElement: rscResult?.element ?? null,
-    initialParams: rscResult?.params ?? readPublishedParams(undefined),
-  });
-
-  // Step 7: HMR (dev-only, no-op in production)
+  // Step 6: HMR (dev-only, no-op in production)
   setupHmr(router);
 }
 
 bootstrap(config);
 
-// ─── 8. Ready Signal ────────────────────────────────────────────
+// ─── 7. Ready Signal ────────────────────────────────────────────
 
 // Signal that the client runtime has been initialized.
 // Used by E2E tests to wait for hydration before interacting.

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

@@ -1,66 +1,32 @@
 /**
- * Post-Hydration Wiring — history stack, segment cache, popstate, scroll.
+ * Post-Hydration Wiring — popstate and scroll.
  *
  * Sets up everything that needs to happen after the React root exists:
- * - Stores initial page in history stack for instant back navigation
  * - Initializes scroll state for the initial entry
- * - Populates segment cache from server-embedded metadata
  * - Registers popstate handler for back/forward navigation
  * - Sets up debounced scroll position saving
  *
+ * The initial page's history entry and segment cache are not written here:
+ * they are the router's, and hydration makes the page current through
+ * `RouterInstance.hydrate` like any other commit (TIM-1541).
+ *
  * See design/19-client-navigation.md §"History Stack"
  */
 
 import type { RouterInstance } from '#client-internal';
-import { getNavigationState } from '../navigation-context.ts';
 import type { NavigationApiController } from '../navigation-api.ts';
 import { getScrollY } from './scroll.ts';
-import type { ParamsSource } from '../../shared/payload-root.ts';
 import { locationSearch } from '../location-search.ts';
 
 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;
 }
 
 /**
  * Wire up post-hydration event handlers and state.
  */
-export function setupPostHydration({
-  router,
-  navApiController,
-  initialElement,
-  initialParams,
-}: PostHydrationOptions): void {
-  // 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('../../shared/segment-info.ts').SegmentInfo[])
-    : null;
-  if (initialSegmentInfo) {
-    router.initSegmentCache(initialSegmentInfo);
-    delete (self as unknown as Record<string, unknown>).__timber_segments;
-  }
-
-  // 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 + locationSearch(), {
-    payload: initialElement,
-    params: initialParams,
-    segmentInfo: initialSegmentInfo,
-  });
-
+export function setupPostHydration({ router, navApiController }: PostHydrationOptions): void {
   // Leave scrollRestoration = 'auto' so the browser natively restores
   // scroll on reload, tab restore, and back-from-external-page — cases
   // JS cannot reliably cover because 'manual' persists on the session

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

@@ -10,16 +10,13 @@
 import { createElement } from 'react';
 import { createFromFetch } from '../../rsc-runtime/browser.ts';
 import { PayloadRoot } from '../params-context.ts';
-import { readPublishedParams, type ParamsSource } from '../../shared/payload-root.ts';
+import type { ParamsSource } from '../../shared/payload-root.ts';
 import { createRouter, setGlobalRouter } from '#client-internal';
 import type { RouterDeps, RouterInstance } from '#client-internal';
 import type { NavigationState } from '#client-internal';
+import type { HydrationPage } from '../router-types.ts';
 import { TimberNuqsAdapter } from '../nuqs-adapter.tsx';
-import {
-  NavigationProvider,
-  getNavigationState,
-  setNavigationState,
-} from '../navigation-context.ts';
+import { NavigationProvider } from '../navigation-context.ts';
 import { navigateTransition, type RenderOwner } from '../navigation-transition.ts';
 import type { NavigationRender } from '../navigation-root.tsx';
 import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.ts';
@@ -40,9 +37,6 @@ export interface RouterInitOptions {
    * around `root.render`, and the `publish` it takes runs on React's commit.
    */
   render: NavigationRender;
-  initialElement?: unknown;
-  /** The params the hydration payload published, beside `initialElement`. */
-  initialParams?: ParamsSource;
   clientSegmentCache?: boolean;
 }
 
@@ -50,17 +44,12 @@ export interface RouterInitResult {
   router: RouterInstance;
   navApiController: NavigationApiController | null;
   /**
-   * The client's wrapper chain around a tree — the one every navigation
-   * renders through. Hydration builds its root with this too, so the
-   * hydrated tree and the first navigated tree cannot differ in shape
-   * (a type present on one and absent on the other remounts everything
-   * below it) and share the router's slot content cache.
+   * Make the server-rendered page current and hand its tree to React
+   * hydration. `hydrateRoot` receives the tree, built by the same
+   * `renderTree` every navigation renders through. With no payload there is
+   * no tree to hydrate and `hydrateRoot` is not called.
    */
-  renderTree: (
-    tree: unknown,
-    navState: NavigationState,
-    params: ParamsSource
-  ) => React.ReactElement;
+  hydrate: (page: HydrationPage, hydrateRoot: (element: React.ReactElement) => void) => void;
 }
 
 /**
@@ -78,20 +67,23 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
   // See design/19-client-navigation.md §"Navigation API Integration"
   const useNavApi = hasNavigationApi();
 
-  // Track the current unwrapped RSC payload. On partial navigation, the
-  // router re-wraps this same element with new NavigationProvider context
-  // so mounted SegmentOutlets are preserved (they pick up changes via
-  // SegmentUpdateContext, not from new children props).
-  // Initialized from the hydration element so partial nav works on the
-  // 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);
+  /**
+   * The tree on screen, with the params published over it and the location
+   * it renders — the client's one record of the displayed page. Null until
+   * a page with a payload is on screen (a document hydrated without one).
+   *
+   * The unwrapped tree is kept because a partial navigation re-wraps this
+   * same element with new context so mounted SegmentOutlets are preserved
+   * (they pick up changes via SegmentUpdateContext, not from new children
+   * props). The params and location are kept beside it because the render
+   * paths that do NOT receive a payload — a shallow search update, a partial
+   * navigation — must republish them rather than drop them.
+   *
+   * The location used to live in a separate `globalThis` store as well,
+   * written by the router's commit, by hydration and by the shallow search
+   * path, and read back here. It was a second record of this one (TIM-1541).
+   */
+  let displayed: { tree: unknown; params: ParamsSource; navState: NavigationState } | null = null;
 
   // The slot content the client has committed, by segmentPath. Owned here so
   // there is exactly one per router (never a module or globalThis singleton —
@@ -114,14 +106,14 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
    * tests/e2e/segment-merge-navigation.test.ts when the params wrapper was
    * conditional).
    *
-   * `PayloadRoot` is *above* `currentPayload`, which on a partial navigation
+   * `PayloadRoot` is *above* the displayed tree, 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`
+   * known to have won and a superseded one must leave the displayed record
    * describing the route still on screen (TIM-1301).
    */
   function renderTree(
@@ -146,14 +138,14 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
   }
 
   /**
-   * 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.
+   * Record the tree the client is now displaying, the params published over
+   * it and the location it renders. Written together — the paths that re-wrap
+   * without a fresh payload (a shallow search update, a partial navigation)
+   * read them back as one and would otherwise restore one route's tree with
+   * another's params or pathname.
    */
-  function publishTree(tree: unknown, params: ParamsSource): void {
-    currentPayload = tree;
-    currentParams = params;
+  function publishTree(tree: unknown, params: ParamsSource, navState: NavigationState): void {
+    displayed = { tree, params, navState };
   }
 
   // Late-bound: syncShallowSearch is defined before createRouter, but only
@@ -187,26 +179,25 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
    *   the patched pushState/replaceState returns).
    *
    * Bails when search is unchanged (scroll saves, no-ops, dual-fire).
-   * Re-wraps currentPayload with updated NavigationProvider and hands it to
+   * Re-wraps the displayed tree with updated NavigationProvider and hands it to
    * React through the root's `render` (startTransition — non-blocking).
    */
   function syncShallowSearch(search?: string): void {
+    if (!displayed) return;
     const currentSearch = search != null ? stripRscCacheKey(search) : locationSearch();
-    const navState = getNavigationState();
-    if (currentSearch === navState.search) return;
-    if (!currentPayload) return;
+    if (currentSearch === displayed.navState.search) 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
+    // this path rebuilds the whole chain. Republishing `displayed.params` 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 { tree, params } = displayed;
     const newNavState: NavigationState = {
-      pathname: navState.pathname,
+      pathname: displayed.navState.pathname,
       search: currentSearch,
     };
-    setNavigationState(newNavState);
 
     // A shallow search update displaces whatever React is rendering. If a
     // handed-off tree is still suspended (e.g. a cached popstate replay whose
@@ -223,8 +214,8 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
     // (TIM-1480).
     queueMicrotask(() => router?.settleHandoffs());
 
-    publishTree(currentPayload, currentParams);
-    render(renderTree(currentPayload, newNavState, currentParams), null);
+    publishTree(tree, params, newNavState);
+    render(renderTree(tree, newNavState, params), null);
   }
 
   window.history.pushState = function (
@@ -287,33 +278,6 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
       return createFromFetch(fetchPromise);
     },
 
-    // Render a decoded RSC tree through the router's React root. Used for
-    // non-navigation renders (popstate cached replay, applyActionResult).
-    // Wraps with NavigationProvider + TimberNuqsAdapter.
-    //
-    // For navigation renders (navigate, refresh, popstate-with-fetch),
-    // 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,
-      params: ParamsSource,
-      commit: () => void
-    ) => {
-      // These paths render what is already decided (a replay, a
-      // revalidation), but "decided" is not "on screen": the tree goes out in
-      // a transition React may hold. The publish — the router's and this
-      // module's record of the displayed tree — runs when React commits it,
-      // the same way a navigation's does (TIM-1301, TIM-1423).
-      render(renderTree(element, navState, params), () => {
-        publishTree(element, params);
-        commit();
-      });
-    },
-
     // Hand a navigation's tree to React in a transition
     // (navigation-transition.ts). The fetch runs outside any transition
     // scope; only the render that hands the tree over is wrapped, and in a
@@ -323,7 +287,10 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
     //
     // 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.
+    // is passed explicitly by the router.
+    //
+    // Every render the router makes comes through here — navigations,
+    // refreshes, traversals (fetched or replayed) and revalidations.
     //
     // `_url` names the pending URL the router already published to its own
     // pending store before calling here; the transition has no use for it.
@@ -335,7 +302,8 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
           // 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;
+          let built: { tree: unknown; params: ParamsSource; navState: NavigationState } | null =
+            null;
           const { element, decodePromise, commit } = await perform(
             (
               rawPayload: unknown,
@@ -343,7 +311,7 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
               params: ParamsSource,
               segmentUpdates?: Map<string, unknown>
             ) => {
-              displayed = { tree: rawPayload, params };
+              built = { tree: rawPayload, params, navState };
               return renderTree(
                 rawPayload,
                 navState,
@@ -356,7 +324,7 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
             element: element as React.ReactNode,
             decodePromise,
             commit: () => {
-              if (displayed) publishTree(displayed.tree, displayed.params);
+              if (built) publishTree(built.tree, built.params, built.navState);
               commit();
             },
           };
@@ -366,7 +334,7 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
       );
     },
 
-    _getCurrentPayload: () => currentPayload,
+    _getCurrentPayload: () => displayed?.tree ?? null,
 
     // Schedule a callback after the next paint so scroll operations
     // happen after React commits the new content to the DOM.
@@ -414,5 +382,19 @@ export function createTimberRouter(options: RouterInitOptions): RouterInitResult
     deps.navigationNavigate = (url, replace) => navApiController!.navigate(url, replace);
   }
 
-  return { router, navApiController, renderTree };
+  /**
+   * See `RouterInitResult.hydrate`.
+   *
+   * Everything is recorded at handover, not on hydration's commit: the
+   * server's HTML for this tree is already what the user is looking at, and
+   * React may never commit the hydration render — see `RouterInstance.hydrate`.
+   */
+  const hydrate: RouterInitResult['hydrate'] = (page, hydrateRoot) => {
+    const navState = router.hydrate(page);
+    if (page.payload == null) return;
+    publishTree(page.payload, page.params, navState);
+    hydrateRoot(renderTree(page.payload, navState, page.params));
+  };
+
+  return { router, navApiController, hydrate };
 }