@rangojs/router 0.21.0 → 0.22.0

package/src/browser/react/Link.tsx

@@ -7,7 +7,6 @@ import React, {
   useEffect,
   useMemo,
   useRef,
-  useSyncExternalStore,
   type ForwardRefExoticComponent,
   type RefAttributes,
 } from "react";
@@ -20,7 +19,6 @@ import {
   subscribeToPrefetchScopeChange,
 } from "../link-interceptor.js";
 import { subscribeToLocationChange } from "../event-controller.js";
-import { subscribeToNothing } from "./subscribe-to-nothing.js";
 import { isLocationStateDefinition } from "./location-state-shared.js";
 
 export type StateOrGetter<T = unknown> = T | (() => T);
@@ -39,7 +37,7 @@ import {
 } from "../prefetch/loader.js";
 import { observeForPrefetch } from "../prefetch/observer.js";
 import {
-  getDefaultPrefetchStrategy,
+  ENVIRONMENT_DEFAULT_PREFETCH,
   resolveAdaptiveStrategy,
   subscribeToAdaptiveStrategyChange,
 } from "../prefetch/default-strategy.js";
@@ -240,19 +238,11 @@ export const Link: ForwardRefExoticComponent<
   ref,
 ) {
   const ctx = useContext(NavigationStoreContext);
-  // Origin from the store location — the same both-sides source
-  // useSearchParams seeds from (SSR: the live request's URL; browser:
-  // window.location), so data-external agrees across hydration. Origin is
-  // immutable per document, so the inline getState() read cannot tear.
-  // window is the provider-less browser fallback (tests, portals outside
-  // the app root); provider-less SSR has no origin and keeps links internal.
-  const storeLocation = ctx?.eventController.getState().location as
-    | URL
-    | undefined;
-  const origin =
-    storeLocation?.origin ??
-    (typeof window !== "undefined" ? window.location.origin : undefined);
-  const isExternal = isExternalUrl(to, origin);
+  // The document's origin from the router store, the same on both sides
+  // (SSR: the live request's URL; browser: the store location), so
+  // data-external agrees across hydration. Without a provider there is no
+  // store and no origin: links stay internal.
+  const isExternal = isExternalUrl(to, ctx?.origin);
 
   // Auto-prefix with basename for app-local paths.
   // Skip if external, already prefixed, or not a root-relative path.
@@ -264,19 +254,11 @@ export const Link: ForwardRefExoticComponent<
     return to === "/" ? bn : bn + to;
   }, [to, isExternal, ctx?.basename]);
 
-  // No explicit `prefetch` prop: fall back to the router-wide default
-  // (server-resolved, applied at browser init — before hydration, so this
-  // render-time read never races the metadata). Adaptive reads the current
-  // input capability rather than a module-load snapshot.
+  // No explicit `prefetch` prop: fall back to the router-wide default from
+  // the router store. Adaptive is resolved against the input capability when a
+  // prefetch is armed or triggered, never during render.
   const configuredStrategy =
-    prefetch ?? ctx?.defaultPrefetch ?? getDefaultPrefetchStrategy();
-  const resolvedStrategy = useSyncExternalStore(
-    configuredStrategy === "adaptive"
-      ? subscribeToAdaptiveStrategyChange
-      : subscribeToNothing,
-    () => resolveAdaptiveStrategy(configuredStrategy),
-    () => (configuredStrategy === "adaptive" ? "hover" : configuredStrategy),
-  );
+    prefetch ?? ctx?.defaultPrefetch ?? ENVIRONMENT_DEFAULT_PREFETCH;
 
   // Internal ref for viewport observation; merge with forwarded ref
   const internalRef = useRef<HTMLAnchorElement | null>(null);
@@ -375,8 +357,9 @@ export const Link: ForwardRefExoticComponent<
 
   const handleMouseEnter = useCallback(() => {
     const element = internalRef.current;
+    const strategy = resolveAdaptiveStrategy(configuredStrategy);
     if (
-      (resolvedStrategy === "hover" || resolvedStrategy === "viewport") &&
+      (strategy === "hover" || strategy === "viewport") &&
       !isExternal &&
       ctx?.store &&
       (!element ||
@@ -395,17 +378,26 @@ export const Link: ForwardRefExoticComponent<
         prefetchKey,
       );
     }
-  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
+  }, [configuredStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   // Viewport/render prefetch: waits for idle before starting,
   // uses concurrency-limited queue to avoid flooding.
   useEffect(() => {
     if (isExternal || !ctx?.store) return;
-    const isViewport = resolvedStrategy === "viewport";
-    const isRender = resolvedStrategy === "render";
-    if (!isViewport && !isRender) return;
+    if (
+      configuredStrategy !== "viewport" &&
+      configuredStrategy !== "render" &&
+      configuredStrategy !== "adaptive"
+    ) {
+      return;
+    }
 
     const armPrefetch = (): (() => void) => {
+      const strategy = resolveAdaptiveStrategy(configuredStrategy);
+      const isViewport = strategy === "viewport";
+      const isRender = strategy === "render";
+      if (!isViewport && !isRender) return () => {};
+
       const element = internalRef.current;
       if (
         element &&
@@ -457,27 +449,30 @@ export const Link: ForwardRefExoticComponent<
     };
 
     let disarmPrefetch = armPrefetch();
+    const rearm = () => {
+      disarmPrefetch();
+      disarmPrefetch = armPrefetch();
+    };
     const element = internalRef.current;
     const unsubscribeScope = element
-      ? subscribeToPrefetchScopeChange(element, () => {
-          disarmPrefetch();
-          disarmPrefetch = armPrefetch();
-        })
+      ? subscribeToPrefetchScopeChange(element, rearm)
       : undefined;
     const unsubscribeLocation = subscribeToLocationChange(
       ctx.eventController,
-      () => {
-        disarmPrefetch();
-        disarmPrefetch = armPrefetch();
-      },
+      rearm,
     );
+    const unsubscribeAdaptive =
+      configuredStrategy === "adaptive"
+        ? subscribeToAdaptiveStrategyChange(rearm)
+        : undefined;
 
     return () => {
       unsubscribeScope?.();
       unsubscribeLocation();
+      unsubscribeAdaptive?.();
       disarmPrefetch();
     };
-  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
+  }, [configuredStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   return (
     <a

package/src/browser/react/NavigationProvider.tsx

@@ -8,9 +8,11 @@ import React, {
   useMemo,
   useRef,
   use,
+  startTransition,
   type ReactNode,
 } from "react";
 import {
+  HydrationBarrierContext,
   LocationStateContext,
   NavigationStoreContext,
   type NavigationStoreContextValue,
@@ -37,6 +39,7 @@ import {
   deferredHandleNames,
   resolveDeferredHandleValues,
 } from "../../handles/deferred-resolution.js";
+import { auditTreeUpdate } from "../../suspense-audit.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -278,6 +281,18 @@ export interface NavigationProviderProps {
    * it to seed a nonce so components calling useNonce() can be exercised.
    */
   nonce?: string;
+
+  /**
+   * The document this provider hydrates (initBrowserApp; renderRoute with
+   * `hydrate: true`), whose store EventController.lockHydration locked.
+   * `settled` resolves once the stream has ended and React has revealed every
+   * boundary. Until then location state is `undefined`, as SSR rendered it;
+   * then one transition gives the entry's state and changes
+   * HydrationBarrierContext, and the store is released after that commit. A
+   * navigation committed earlier releases the store before its update.
+   * Absent for a provider mounted on the client.
+   */
+  hydration?: { settled: Promise<void> };
 }
 
 /**
@@ -313,14 +328,18 @@ export function NavigationProvider({
   basename,
   appShellRef,
   nonce,
+  hydration,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
   // The location state of the entry `payload` renders (LocationStateContext).
   // Only ever set next to setPayload, or for a commit that has no payload.
-  const [locationState, setLocationState] = useState(
-    eventController.getLocationState,
+  const [locationState, setLocationState] = useState(() =>
+    hydration ? undefined : eventController.getLocationState(),
   );
+  // HydrationBarrierContext's value; see NavigationProviderProps.hydration.
+  const [hydrationBarrier, setHydrationBarrier] = useState(0);
+  const hydrationOpen = useRef(hydration !== undefined);
 
   /**
    * Navigate to a URL (delegates to bridge)
@@ -356,6 +375,8 @@ export function NavigationProvider({
       navigate,
       refresh,
       defaultPrefetch: initialPayload.metadata.defaultPrefetch,
+      // Fixed for the document: read once, with the stable value.
+      origin: (eventController.getState().location as URL | undefined)?.origin,
     } as NavigationStoreContextValue;
     Object.defineProperty(value, "basename", {
       configurable: true,
@@ -379,6 +400,32 @@ export function NavigationProvider({
     return startConnectionWarmup();
   }, [warmupEnabled]);
 
+  // The document has been revealed: one transition gives the entry's location
+  // state and moves the barrier, so React hydrates every boundary still
+  // dehydrated before it commits.
+  useEffect(() => {
+    if (!hydration) return;
+    let cancelled = false;
+    void hydration.settled.then(() => {
+      if (cancelled || !hydrationOpen.current) return;
+      startTransition(() => {
+        setLocationState(eventController.getLocationState());
+        setHydrationBarrier((n) => n + 1);
+      });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // After the barrier's commit no boundary under this provider is dehydrated:
+  // release the store, and its handle writes reach their readers.
+  useEffect(() => {
+    if (hydrationBarrier === 0) return;
+    hydrationOpen.current = false;
+    eventController.releaseHydrationLock();
+  }, [hydrationBarrier]);
+
   // A commit no payload follows (a shallow navigation, a commit that keeps
   // every segment, merged server-set state): the tree on screen is already
   // the entry's, so its state is taken with the commit's notification.
@@ -430,12 +477,23 @@ export function NavigationProvider({
   // Subscribe to UI updates (for re-rendering the tree)
   useEffect(() => {
     const unsubscribe = store.onUpdate((update) => {
+      if (process.env.NODE_ENV !== "production") auditTreeUpdate(update.root);
       // Capture scroll intent — it will be applied in useLayoutEffect
       // after React commits this state update to the DOM.
       // Always assign (even undefined) to clear stale scroll from prior navigations,
       // so server actions or error updates don't accidentally replay old scroll.
       pendingScrollRef.current = update.scroll;
 
+      // Committed before the document finished hydrating: end the window
+      // first, so the page this update mounts reads the live store. A
+      // boundary of the document still dehydrated then hydrates against the
+      // live store; where that differs from its HTML, React reports the
+      // mismatch and renders the boundary on the client.
+      if (hydrationOpen.current) {
+        hydrationOpen.current = false;
+        eventController.releaseHydrationLock();
+      }
+
       setPayload({
         root: update.root,
         metadata: update.metadata,
@@ -529,7 +587,9 @@ export function NavigationProvider({
   return (
     <NavigationStoreContext.Provider value={contextValue}>
       <LocationStateContext.Provider value={locationState}>
-        {content}
+        <HydrationBarrierContext.Provider value={hydrationBarrier}>
+          {content}
+        </HydrationBarrierContext.Provider>
       </LocationStateContext.Provider>
     </NavigationStoreContext.Provider>
   );

package/src/browser/react/context.ts

@@ -57,6 +57,13 @@ export interface NavigationStoreContextValue {
 
   /** Router default from this instance's initial payload. */
   defaultPrefetch?: PrefetchStrategy;
+
+  /**
+   * The document's origin, fixed for its lifetime. Link compares absolute
+   * hrefs against it (data-external) and useLinkStatus resolves link targets
+   * with it.
+   */
+  origin: string | undefined;
 }
 
 /**
@@ -79,3 +86,13 @@ export const NavigationStoreContext: Context<NavigationStoreContextValue | null>
  */
 export const LocationStateContext: Context<LocationStateSnapshot> =
   createContext<LocationStateSnapshot>(undefined);
+
+/**
+ * Read by no component. NavigationProvider changes its value in a transition so
+ * that React hydrates every boundary still dehydrated beneath it before that
+ * commit: React hydrates a dehydrated boundary first when a provider above it
+ * changes, and nothing re-renders for a value nobody reads. See
+ * NavigationProviderProps.hydration.
+ */
+export const HydrationBarrierContext: Context<number> =
+  createContext<number>(0);

package/src/browser/react/location-state.ts

@@ -1,7 +1,6 @@
 "use client";
 
-import { useContext, useEffect, useSyncExternalStore } from "react";
-import { subscribeToNothing } from "./subscribe-to-nothing.js";
+import { useContext, useEffect } from "react";
 import { LocationStateContext } from "./context.js";
 import { OptimisticLocationContext } from "../../client-urls/optimistic-location.js";
 import {
@@ -19,15 +18,6 @@ export {
   type LocationStateOptions,
 } from "./location-state-shared.js";
 
-/**
- * Server and hydration renders must match the SSR output (`undefined`).
- * React then re-renders with `getSnapshot`, including a reader whose Suspense
- * boundary hydrates after the root has set `data-hydrated`.
- */
-function getServerSnapshot(): undefined {
-  return undefined;
-}
-
 /**
  * Hook to read the location state of the history entry on screen
  *
@@ -73,16 +63,12 @@ export function useLocationState<TArgs extends unknown[], TState>(
   // Typed state: the slot under its key. Plain state: the `state` slot.
   // Inside an optimistically rendered clientUrls() destination the provider
   // still holds the entry being left: read the entry the navigation will push.
-  const shown = (optimistic ? readableLocationState(optimistic) : entry)?.[
+  // While the document hydrates, the provider holds `undefined`, what SSR
+  // rendered, and gives the entry's state once every boundary has hydrated
+  // (NavigationProvider's hydration barrier, issue #992).
+  const state = (optimistic ? readableLocationState(optimistic) : entry)?.[
     key || "state"
   ] as TState | undefined;
-  // useSyncExternalStore only for its server snapshot: no other hook tells a
-  // hydrating render from a client one.
-  const state = useSyncExternalStore<TState | undefined>(
-    subscribeToNothing,
-    () => shown,
-    getServerSnapshot,
-  );
 
   // Flash: removed from history.state after paint, so a reload or a return to
   // the entry does not show it again. The provider's snapshot keeps it, so it

package/src/browser/react/use-action.ts

@@ -149,7 +149,10 @@ export function useAction<T>(
     if (!ctx) {
       return selector ? selector(DEFAULT_ACTION_STATE) : DEFAULT_ACTION_STATE;
     }
-    const state = ctx.eventController.getActionState(actionId);
+    // The document renders no action in flight.
+    const state = ctx.eventController.getHydrationSnapshot()
+      ? DEFAULT_ACTION_STATE
+      : ctx.eventController.getActionState(actionId);
     return selector ? selector(state) : state;
   });
   const prevSelected = useRef(baseState);

package/src/browser/react/use-handle.ts

@@ -6,7 +6,6 @@ import {
   useEffect,
   useRef,
   useOptimistic,
-  useSyncExternalStore,
   startTransition,
 } from "react";
 import type { Handle } from "../../handle.js";
@@ -14,9 +13,6 @@ import { collectHandleData } from "../../handle.js";
 import type { HandleData } from "../types.js";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
-import { subscribeToNothing } from "./subscribe-to-nothing.js";
-
-const noHydrationState = (): undefined => undefined;
 
 /**
  * Hook to access collected handle data.
@@ -47,21 +43,6 @@ export function useHandle<T, A, S>(
 ): Rango.FlightSerialize<A> | S {
   const ctx = useContext(NavigationStoreContext);
 
-  // useSyncExternalStore only for its server snapshot, as useLocationState
-  // (#992): no other hook tells a hydrating render from a client one. A
-  // hydrating render gets the handle state the document's HTML was rendered
-  // with (EventController.getHydrationHandleState), whenever its boundary
-  // hydrates; the mount effect below moves it on to the live state. That
-  // state is undefined while the live state is still it, and the client
-  // snapshot is always undefined: a reader that hydrated before anything
-  // arrived late is not rendered again, and to React the store never
-  // changes (issue #1035).
-  const hydrationState = useSyncExternalStore(
-    subscribeToNothing,
-    noHydrationState,
-    () => ctx?.eventController.getHydrationHandleState(),
-  );
-
   const [value, setValue] = useState<Rango.FlightSerialize<A> | S>(() => {
     if (!ctx) {
       const collected = collectHandleData(
@@ -72,7 +53,10 @@ export function useHandle<T, A, S>(
       return selector ? selector(collected) : collected;
     }
 
-    const state = hydrationState ?? ctx.eventController.getHandleState();
+    // Until every boundary has hydrated the store returns the state the
+    // document's HTML was rendered with (EventController.lockHydration), so a
+    // reader hydrating late reads what SSR rendered (issue #1035).
+    const state = ctx.eventController.getHandleState();
     const collected = collectHandleData(
       handle,
       state.data,

package/src/browser/react/use-link-status.ts

@@ -82,14 +82,15 @@ export function useLinkStatus(): LinkStatus {
   const linkTo = useContext(LinkContext);
   const ctx = useContext(NavigationStoreContext);
 
-  const origin =
-    typeof window !== "undefined" ? window.location.origin : "http://localhost";
+  const origin = ctx?.origin ?? "http://localhost";
 
   const [basePending, setBasePending] = useState<boolean>(() => {
     if (!ctx || linkTo === null) {
       return false;
     }
-    const state = ctx.eventController.getState();
+    const state =
+      ctx.eventController.getHydrationSnapshot()?.state ??
+      ctx.eventController.getState();
     return isPendingFor(linkTo, state.pendingUrl, origin);
   });
 

package/src/browser/react/use-navigation.ts

@@ -47,7 +47,10 @@ export function useNavigation<T>(
   }
 
   const [baseValue, setBaseValue] = useState<T | PublicNavigationState>(() => {
-    const publicState = toPublicState(ctx.eventController.getState());
+    const publicState = toPublicState(
+      ctx.eventController.getHydrationSnapshot()?.state ??
+        ctx.eventController.getState(),
+    );
     return selector ? selector(publicState) : publicState;
   });
   const prevState = useRef(baseValue);

package/src/browser/react/use-params.ts

@@ -49,7 +49,10 @@ export function useParams<T>(
   const optimistic = useContext(OptimisticLocationContext);
 
   const [value, setValue] = useState<T | Record<string, string>>(() => {
-    const params = ctx ? ctx.eventController.getParams() : EMPTY_PARAMS;
+    const params = ctx
+      ? (ctx.eventController.getHydrationSnapshot()?.params ??
+        ctx.eventController.getParams())
+      : EMPTY_PARAMS;
     return selector ? selector(params) : params;
   });
 

package/src/browser/react/use-pathname.ts

@@ -26,7 +26,10 @@ export function usePathname(): string {
     if (!ctx) {
       return "/";
     }
-    return (ctx.eventController.getState().location as URL).pathname;
+    const state =
+      ctx.eventController.getHydrationSnapshot()?.state ??
+      ctx.eventController.getState();
+    return (state.location as URL).pathname;
   });
 
   const prevPathname = useRef(pathname);

package/src/browser/react/use-search-params.ts

@@ -119,9 +119,11 @@ export function useSearchParams(): [ReadonlyURLSearchParams, SetSearchParams] {
   // (no provider) seeds empty.
   const [searchParams, setSearchParamsState] =
     useState<ReadonlyURLSearchParams>(() => {
-      const location = ctx?.eventController.getState().location as
-        | URL
-        | undefined;
+      const state = ctx
+        ? (ctx.eventController.getHydrationSnapshot()?.state ??
+          ctx.eventController.getState())
+        : undefined;
+      const location = state?.location as URL | undefined;
       return new URLSearchParams(location?.searchParams);
     });
 

package/src/browser/react/use-segments.ts

@@ -64,16 +64,22 @@ export function useSegments<T>(
 ): T | SegmentsState {
   const ctx = useContext(NavigationStoreContext);
 
-  // Build initial state from event controller when context exists.
-  // Inlined rather than calling recompute() because the segmentsCache ref
-  // is not yet initialized during the useState initializer.
+  // The selector is applied when the store changes, never during render, as in
+  // useNavigation and useAction: the hook renders its own state only. A new
+  // selector identity is not a reactive input; it applies from the next store
+  // change.
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
   const [state, setState] = useState<T | SegmentsState>(() => {
     if (!ctx) {
       const fallbackLocation = new URL("/", "http://localhost");
       const fallbackState = buildSegmentsState(fallbackLocation, []);
       return selector ? selector(fallbackState) : fallbackState;
     }
-    const location = ctx.eventController.getLocation();
+    const location =
+      ctx.eventController.getHydrationSnapshot()?.state.location ??
+      ctx.eventController.getLocation();
     const handleState = ctx.eventController.getHandleState();
     const segmentsState = buildSegmentsState(
       location as URL,
@@ -83,69 +89,45 @@ export function useSegments<T>(
   });
 
   const prevState = useRef(state);
-  const selectorRef = useRef(selector);
-  selectorRef.current = selector;
-
-  const prevSelectorIdentity = useRef(selector);
-
-  const segmentsCache = useRef<{
-    location: URL;
-    routeSegmentIds: string[];
-    state: SegmentsState;
-  } | null>(null);
-
-  function recompute(
-    sel: ((state: SegmentsState) => T) | undefined,
-  ): T | SegmentsState {
-    const location = ctx!.eventController.getLocation();
-    const handleState = ctx!.eventController.getHandleState();
 
-    const cache = segmentsCache.current;
-    let segmentsState: SegmentsState;
-    if (
-      cache &&
-      cache.location === location &&
-      cache.routeSegmentIds === handleState.routeSegmentIds
-    ) {
-      segmentsState = cache.state;
-    } else {
-      segmentsState = buildSegmentsState(
-        location as URL,
-        handleState.routeSegmentIds,
-      );
-      segmentsCache.current = {
-        location: location as URL,
-        routeSegmentIds: handleState.routeSegmentIds,
-        state: segmentsState,
-      };
-    }
-    return sel ? sel(segmentsState) : segmentsState;
-  }
-
-  if (ctx && selector !== prevSelectorIdentity.current) {
-    prevSelectorIdentity.current = selector;
-    const nextSelected = recompute(selector);
-    if (!shallowEqual(nextSelected, prevState.current)) {
-      prevState.current = nextSelected;
-      setState(nextSelected);
-    }
-  }
-
-  // Subscribe to store changes. The eager block above handles selector
-  // changes and SSR drift, so no initial updateState() call is needed.
   useEffect(() => {
     if (!ctx) {
       return;
     }
 
+    // Reused while the location and route segments are unchanged, so a
+    // selector returning part of it keeps the same references.
+    let cache: {
+      location: URL;
+      routeSegmentIds: string[];
+      state: SegmentsState;
+    } | null = null;
+
     const updateState = () => {
-      const nextSelected = recompute(selectorRef.current);
+      const location = ctx.eventController.getLocation() as URL;
+      const { routeSegmentIds } = ctx.eventController.getHandleState();
+      if (
+        !cache ||
+        cache.location !== location ||
+        cache.routeSegmentIds !== routeSegmentIds
+      ) {
+        cache = {
+          location,
+          routeSegmentIds,
+          state: buildSegmentsState(location, routeSegmentIds),
+        };
+      }
+      const sel = selectorRef.current;
+      const nextSelected = sel ? sel(cache.state) : cache.state;
       if (!shallowEqual(nextSelected, prevState.current)) {
         prevState.current = nextSelected;
         setState(nextSelected);
       }
     };
 
+    // Catch up with a change between the seeding render and this effect.
+    updateState();
+
     const unsubscribeNav = ctx.eventController.subscribe(updateState);
     const unsubscribeHandles =
       ctx.eventController.subscribeToHandles(updateState);