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

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

@@ -1,9 +1,10 @@
 /**
- * Hydration — pre-hydration sequence and React root creation.
+ * Hydration — pre-hydration sequence and hydrating the React root.
  *
  * Handles two paths:
- * 1. RSC payload available: hydrateRoot with NavigationProvider wrapping
- * 2. No RSC payload: deferred root creation via installDeferredNavigation
+ * 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)
  *
  * Pre-hydration ordering contract (MUST execute in this order):
  *   1. initRouter()          — creates the global router so useRouter()
@@ -21,22 +22,14 @@
  * See design/19-client-navigation.md §"NavigationContext"
  */
 
-import { createElement } from 'react';
-import { hydrateRoot, createRoot } from 'react-dom/client';
 import { getRouterOrNull } from '#client-internal';
-import { PayloadRoot } from '../params-context.ts';
-import {
-  NavigationProvider,
-  getNavigationState,
-  setNavigationState,
-} from '../navigation-context.ts';
-import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.ts';
-import { TimberNuqsAdapter } from '../nuqs-adapter.tsx';
+import { getNavigationState, setNavigationState } from '../navigation-context.ts';
 import { isPageUnloading } from '../unload-guard.ts';
-import { NavigationRoot, installDeferredNavigation } from '../navigation-root.tsx';
-import type { TopLoaderConfig } from '../top-loader.tsx';
+import { locationSearch } from '../location-search.ts';
+import type { ReactRootHost } from '../react-root.ts';
 
 import type { RscStreamResult } from './rsc-stream.ts';
+import type { RouterInitResult } from './router-init.ts';
 
 let showHydrationError: ((error: unknown) => void) | null = null;
 let isHydrationError: ((error: unknown) => boolean) | null = null;
@@ -79,8 +72,10 @@ function queueOrShowHydrationError(error: unknown): void {
 interface HydrateOptions {
   /** RSC stream result (null if no inlined payload) */
   rscResult: RscStreamResult | null;
-  /** Runtime config from virtual:timber-config */
-  config: { topLoader?: TopLoaderConfig };
+  /** The router's React root — the one every navigation renders through. */
+  reactRoot: ReactRootHost;
+  /** The router's wrapper chain — see `RouterInitResult.renderTree`. */
+  renderTree: RouterInitResult['renderTree'];
 }
 
 /**
@@ -97,102 +92,57 @@ interface HydrateOptions {
 export function runPreHydration(): void {
   setNavigationState({
     pathname: window.location.pathname,
-    search: window.location.search,
+    search: locationSearch(),
   });
 }
 
 /**
- * Hydrate the React tree or set up deferred root creation.
+ * Hydrate the React tree when an RSC payload is available.
  *
- * When an RSC payload is available, wraps it with NavigationProvider +
- * TimberNuqsAdapter + NavigationRoot and calls hydrateRoot on the
- * document.
+ * 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), sets up deferred
- * navigation so the first client navigation creates the React root.
+ * 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 —
+ * `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, config }: HydrateOptions): void {
-  if (rscResult) {
-    const element = rscResult.element;
+export function hydrateApp({ rscResult, reactRoot, renderTree }: HydrateOptions): void {
+  if (!rscResult) return;
 
-    // Wrap with NavigationProvider (for atomic useParams/usePathname),
-    // TimberNuqsAdapter (for nuqs context), and NavigationRoot (for
-    // transition-based rendering during client navigation).
-    //
-    // NavigationRoot holds the element in React state and updates via
-    // startTransition, so React keeps old UI visible while new Suspense
-    // boundaries resolve during navigation. See design/05-streaming.md.
-    const navState = getNavigationState();
-    // 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 },
-      withNav
-    );
-    const wrapped = createElement(TimberNuqsAdapter, null, withUpdates);
-    const rootElement = createElement(NavigationRoot, {
-      initial: wrapped,
-      topLoaderConfig: config.topLoader,
-    });
+  // 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
+  // everything below it — losing the layout state partial navigation exists
+  // to preserve. Sharing the function makes that impossible by construction.
+  //
+  // `rscResult.params` 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 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'
-        );
-      }
+  if (process.env.NODE_ENV !== 'production') {
+    if (!getRouterOrNull()) {
+      throw new Error('[timber] hydrateRoot called before initRouter() — bootstrap order violated');
     }
-
-    hydrateRoot(document, rootElement, {
-      // 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);
-        }
-      },
-    });
-  } else {
-    // No RSC payload available — defer React root creation until the
-    // first client navigation (TIM-600).
-    //
-    // We must NOT call createRoot(document).render() here — that would
-    // take React ownership of the entire document and blank the SSR HTML.
-    // Instead, installDeferredNavigation sets up one-shot callbacks so
-    // the first navigateTransition/transitionRender call creates the root
-    // on `document` with the navigated content. After that initial render,
-    // NavigationRoot's real startTransition-based callbacks take over.
-    //
-    // This also fixes TIM-580 (navigation from SSR-only pages) because
-    // the deferred callbacks ensure NavigationRoot is mounted before the
-    // first navigation completes.
-    installDeferredNavigation((initial) => {
-      const rootElement = createElement(NavigationRoot, {
-        initial,
-        topLoaderConfig: config.topLoader,
-      });
-      const root = createRoot(document);
-      root.render(rootElement);
-    });
   }
+
+  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);
+      }
+    },
+  });
 }

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

@@ -7,7 +7,7 @@
  *   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 + hydrateRoot/createRoot
+ *   hydrate.ts          — pre-hydration sequence + hydrating the root
  *   post-hydration.ts   — history stack, segment cache, popstate, scroll
  *   hmr.ts              — dev-only HMR + error forwarding
  *   scroll.ts           — getScrollY helper
@@ -16,9 +16,10 @@
  *
  *   1. setupServerActions()      — register callServer (independent)
  *   2. createRscPayloadStream()  — decode inlined RSC payload
- *   3. createTimberRouter()      — create router + Navigation API
+ *   3. createReactRoot() +       — the root host the router renders through,
+ *      createTimberRouter()        then the router + Navigation API
  *   4. runPreHydration()         — set params + navigation state
- *   5. hydrateApp()              — hydrateRoot or deferred createRoot
+ *   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
@@ -41,6 +42,8 @@ import { initStaleClient } from '../stale-client.ts';
 import { setupServerActions } from './action-dispatch.ts';
 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 { setupPostHydration } from './post-hydration.ts';
@@ -79,8 +82,15 @@ function bootstrap(runtimeConfig: typeof config): void {
   // Step 2: Decode inlined RSC payload (may be null for JS-only clients)
   const rscResult = createRscPayloadStream();
 
-  // Step 3: Create router + Navigation API integration
-  const { router, navApiController } = createTimberRouter({
+  // Step 3: Create the React root host and the router that renders through
+  // it. The root itself is created lazily — by hydration below, or by the
+  // first navigation when there is no payload to hydrate (TIM-600).
+  const reactRoot = createReactRoot({
+    container: document,
+    topLoaderConfig: (runtimeConfig as { topLoader?: TopLoaderConfig }).topLoader,
+  });
+  const { router, navApiController, renderTree } = createTimberRouter({
+    render: reactRoot.render,
     initialElement: rscResult?.element ?? undefined,
     initialParams: rscResult?.params,
     clientSegmentCache:
@@ -91,7 +101,7 @@ function bootstrap(runtimeConfig: typeof config): void {
   runPreHydration();
 
   // Step 5: Hydrate or set up deferred root creation
-  hydrateApp({ rscResult, config: runtimeConfig });
+  hydrateApp({ rscResult, reactRoot, renderTree });
 
   // Step 6: Post-hydration wiring
   setupPostHydration({

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

@@ -16,6 +16,7 @@ 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;
@@ -54,7 +55,7 @@ export function setupPostHydration({
   // `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, {
+  router.historyStack.push(window.location.pathname + locationSearch(), {
     payload: initialElement,
     params: initialParams,
     segmentInfo: initialSegmentInfo,
@@ -94,7 +95,7 @@ export function setupPostHydration({
 
     const state = window.history.state;
     const scrollY = state && typeof state.scrollY === 'number' ? state.scrollY : 0;
-    void router.handlePopState(window.location.pathname + window.location.search, scrollY);
+    void router.handlePopState(window.location.pathname + locationSearch(), scrollY);
   });
 
   // Keep scroll position up to date as the user scrolls.

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

@@ -20,16 +20,26 @@ import {
   getNavigationState,
   setNavigationState,
 } from '../navigation-context.ts';
-import { transitionRender, navigateTransition } from '../navigation-root.tsx';
+import { navigateTransition } from '../navigation-transition.ts';
+import type { NavigationRender } from '../navigation-root.tsx';
 import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.ts';
+import { SlotContentCacheContext, type SlotContentCache } from '../slot-content-cache-context.ts';
 import {
   hasNavigationApi,
   setupNavigationApi,
   type NavigationApiController,
 } from '../navigation-api.ts';
 import { getScrollY, scrollToHashTarget } from './scroll.ts';
+import { locationSearch } from '../location-search.ts';
+import { stripRscCacheKey } from '../../shared/rsc-cache-key.ts';
 
 export interface RouterInitOptions {
+  /**
+   * The router's React root (`createReactRoot().render`). Every path that puts
+   * a page on screen renders through it — it is the synchronous transition
+   * 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;
@@ -39,6 +49,18 @@ export interface RouterInitOptions {
 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.
+   */
+  renderTree: (
+    tree: unknown,
+    navState: NavigationState,
+    params: ParamsSource
+  ) => React.ReactElement;
 }
 
 /**
@@ -48,7 +70,9 @@ export interface RouterInitResult {
  * the initial render (methods lazily resolve the router at invocation,
  * not render time, but initRouter must still run first).
  */
-export function createTimberRouter(options?: RouterInitOptions): RouterInitResult {
+export function createTimberRouter(options: RouterInitOptions): RouterInitResult {
+  const { render } = options;
+
   // Feature-detect Navigation API. When available, the navigate event
   // replaces popstate for back/forward and catches external navigations.
   // See design/19-client-navigation.md §"Navigation API Integration"
@@ -60,27 +84,35 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
   // 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;
+  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);
+  let currentParams: ParamsSource = options.initialParams ?? readPublishedParams(undefined);
+
+  // The slot content the client has committed, by segmentPath. Owned here so
+  // there is exactly one per router (never a module or globalThis singleton —
+  // SegmentOutlet also executes during SSR, where a process-wide Map would be
+  // shared across requests). Read by SegmentOutlet in render, written by it
+  // at commit only. See client/slot-content-cache-context.ts (TIM-1423).
+  const slotContentCache: SlotContentCache = new Map();
 
   /**
    * 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).
+   * Every render path goes through here — hydration (`hydrate.ts`) receives
+   * this function and builds its root with it, 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
@@ -105,7 +137,12 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
       { value: segmentUpdates ?? EMPTY_SEGMENT_UPDATES },
       withNav
     );
-    return createElement(TimberNuqsAdapter, null, withUpdates);
+    const withSlotCache = createElement(
+      SlotContentCacheContext.Provider,
+      { value: slotContentCache },
+      withUpdates
+    );
+    return createElement(TimberNuqsAdapter, null, withSlotCache);
   }
 
   /**
@@ -145,11 +182,11 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
    *   the patched pushState/replaceState returns).
    *
    * Bails when search is unchanged (scroll saves, no-ops, dual-fire).
-   * Re-wraps currentPayload with updated NavigationProvider and commits
-   * via transitionRender (startTransition — non-blocking).
+   * Re-wraps currentPayload with updated NavigationProvider and hands it to
+   * React through the root's `render` (startTransition — non-blocking).
    */
   function syncShallowSearch(search?: string): void {
-    const currentSearch = search ?? window.location.search;
+    const currentSearch = search != null ? stripRscCacheKey(search) : locationSearch();
     const navState = getNavigationState();
     if (currentSearch === navState.search) return;
     if (!currentPayload) return;
@@ -167,7 +204,7 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
     setNavigationState(newNavState);
 
     publishTree(currentPayload, currentParams);
-    transitionRender(renderTree(currentPayload, newNavState, currentParams));
+    render(renderTree(currentPayload, newNavState, currentParams), null);
   }
 
   window.history.pushState = function (
@@ -222,7 +259,7 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
         (el as HTMLElement).scrollTop = y;
       }
     },
-    getCurrentUrl: () => window.location.pathname + window.location.search,
+    getCurrentUrl: () => window.location.pathname + locationSearch(),
     getScrollY,
     scrollToHash: scrollToHashTarget,
 
@@ -230,8 +267,8 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
       return createFromFetch(fetchPromise);
     },
 
-    // Render decoded RSC tree via NavigationRoot's state-based mechanism.
-    // Used for non-navigation renders (popstate cached replay, applyRevalidation).
+    // Render a decoded RSC tree through the router's React root. Used for
+    // non-navigation renders (popstate cached replay, applyRevalidation).
     // Wraps with NavigationProvider + TimberNuqsAdapter.
     //
     // For navigation renders (navigate, refresh, popstate-with-fetch),
@@ -240,24 +277,38 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
     //
     // navState is passed explicitly by the router — no temporal coupling
     // with getNavigationState().
-    renderRoot: (element: unknown, navState: NavigationState, params: ParamsSource) => {
+    renderRoot: (
+      element: unknown,
+      navState: NavigationState,
+      params: ParamsSource,
+      commit: () => void
+    ) => {
       // 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));
+      // 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-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).
+    // 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
+    // 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: (url: string, perform) => {
-      return navigateTransition(url, async () => {
+    //
+    // `_url` names the pending URL the router already published to its own
+    // pending store before calling here; the transition has no use for it.
+    navigateTransition: (_url: string, perform) => {
+      return navigateTransition(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
@@ -287,7 +338,7 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
             commit();
           },
         };
-      });
+      }, render);
     },
 
     _getCurrentPayload: () => currentPayload,
@@ -338,5 +389,5 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
     deps.navigationNavigate = (url, replace) => navApiController!.navigate(url, replace);
   }
 
-  return { router, navApiController };
+  return { router, navApiController, renderTree };
 }

package/src/client/global-context.ts

@@ -0,0 +1,31 @@
+/**
+ * createGlobalContext — a React context with a process-wide singleton identity.
+ *
+ * SINGLETON GUARANTEE: Uses globalThis + Symbol.for — same pattern as
+ * NavigationContext. The RSC client bundler can duplicate a module across
+ * chunks (browser-entry graph + client-reference graph). With ESM output,
+ * each chunk gets its own module scope — a bare createContext at module
+ * level would create separate instances per chunk. globalThis guarantees a
+ * single instance regardless of duplication.
+ *
+ * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
+ */
+
+'use client';
+
+import React from 'react';
+
+export function createGlobalContext<T>(key: string, defaultValue: T): React.Context<T> {
+  const g = globalThis as Record<symbol, unknown>;
+  const sym = Symbol.for(key);
+  const existing = g[sym] as React.Context<T> | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext === 'function') {
+    const ctx = React.createContext<T>(defaultValue);
+    g[sym] = ctx;
+    return ctx;
+  }
+  // RSC environment — createContext not available. Return a dummy that
+  // won't be used (the consumers only render on the client / during SSR).
+  return undefined as unknown as React.Context<T>;
+}

package/src/client/internal.ts

@@ -39,8 +39,7 @@ export type { SegmentInfo, StateTree } from '../shared/segment-info.ts';
 export { HistoryStack } from './history.ts';
 export type { HistoryEntry } from './history.ts';
 
-// ── Params (internal setter + raw hooks) ─────────────────────────────────
-export { setCurrentParams, setCurrentSlotParams } from './use-segment-params.ts';
+// ── Params (raw hooks) ───────────────────────────────────────────────────
 export { useSearchParams } from './use-search-params.ts';
 
 // ── Navigation context ───────────────────────────────────────────────────

package/src/client/link.tsx

@@ -38,6 +38,8 @@ import { getRouterOrNull } from './router-ref.ts';
 import { getSsrData } from './ssr-data.ts';
 import { mergePreservedSearchParams } from '../shared/merge-search-params.ts';
 import { getLinkCodec } from '../params/codec-registry.ts';
+import { locationSearch } from './location-search.ts';
+import { stripRscCacheKey } from '../shared/rsc-cache-key.ts';
 import type { LinkStatus } from './use-link-status.ts';
 
 const LINK_PENDING: LinkStatus = { isPending: true };
@@ -47,16 +49,15 @@ const LINK_IDLE: LinkStatus = { isPending: false };
 
 /**
  * Read the current URL's search string without requiring a React hook.
- * On the client, reads window.location.search. During SSR, reads from
- * the request context (getSsrData). Returns empty string if unavailable.
+ * On the client, reads window.location.search. During SSR, reads the raw
+ * query string from the request context (getSsrData) — the same `''` or
+ * `?…` shape, preserving repeated keys (`?tag=a&tag=b`) so the
+ * server-rendered href matches what the hydrated client rebuilds from the
+ * address bar (TIM-1428). Returns empty string if unavailable.
  */
 function getCurrentSearch(): string {
-  if (typeof window !== 'undefined') return window.location.search;
-  const data = getSsrData();
-  if (!data) return '';
-  const sp = new URLSearchParams(data.searchParams);
-  const str = sp.toString();
-  return str ? `?${str}` : '';
+  if (typeof window !== 'undefined') return locationSearch();
+  return getSsrData()?.search ?? '';
 }
 
 // ─── Types ───────────────────────────────────────────────────────
@@ -483,7 +484,7 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
   // 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
+  // while it is open — including the router's `root.render` of `NavigationRoot`, 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
@@ -498,7 +499,7 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
   // `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. The clear wraps in `startTransition` so it lands
-  // on the same React lane as `NavigationRoot`'s `setRendered` — without it,
+  // on the same React lane as the router's `root.render` — without it,
   // the clear is an urgent update that paints before the transition commits,
   // and destinations with pending Suspense boundaries flash idle for one frame
   // while the old page is still showing (TIM-1418). The callback is
@@ -515,11 +516,10 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
   const linkStatus = isPending ? LINK_PENDING : LINK_IDLE;
 
   // Preserve search params from the current URL when requested.
-  // useSearchParams() works during both SSR (reads from request context)
-  // and on the client (reads from window.location, reactive to URL changes).
-  // We read current search params directly to avoid unconditional hook calls.
-  // On the client, window.location.search is always current; during SSR,
-  // getSsrData() provides the request's search params.
+  // Read via getCurrentSearch() rather than a hook, to avoid an
+  // unconditional hook call for a prop most links don't pass. On the
+  // client, window.location.search is always current; during SSR,
+  // getSsrData() provides the request's raw query string.
   const internal = isInternalHref(baseHref);
 
   // Only preserve search params for internal links — leaking current
@@ -565,7 +565,7 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
 
         if (
           resolved.pathname === window.location.pathname &&
-          resolved.search === window.location.search &&
+          stripRscCacheKey(resolved.search) === locationSearch() &&
           resolved.hash
         ) {
           return;
@@ -577,7 +577,7 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
         // Keep the #fragment — the router commits it to the address bar and
         // scrolls to the matching element after render. The hash is stripped
         // from the RSC fetch URL inside the router (TIM-1035).
-        const absoluteHref = resolved.pathname + resolved.search + resolved.hash;
+        const absoluteHref = resolved.pathname + stripRscCacheKey(resolved.search) + resolved.hash;
 
         const seq = ++clickSeq.current;
         const settle = () => {
@@ -615,7 +615,7 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
               ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
               : resolvedHref;
             const resolved = new URL(prefetchHref, window.location.href);
-            router.prefetch(resolved.pathname + resolved.search);
+            router.prefetch(resolved.pathname + stripRscCacheKey(resolved.search));
           }
         }
       : userOnMouseEnter;