@rangojs/router 0.20.0 → 0.22.0

package/src/browser/event-controller.ts

@@ -15,6 +15,11 @@ import {
   filterRouteSegmentIds,
 } from "./react/filter-segment-order.js";
 import { notifyListeners } from "./notify-listeners.js";
+import { cloneHandleData } from "./navigation-store.js";
+import {
+  locationStateSnapshot,
+  type LocationStateSnapshot,
+} from "./react/location-state-shared.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -137,6 +142,16 @@ export interface HandleState {
   routeSegmentIds: string[];
 }
 
+/**
+ * What the document's HTML was rendered with, kept for the hydration window
+ * (EventController.lockHydration).
+ */
+export interface HydrationSnapshot {
+  state: DerivedNavigationState;
+  params: Record<string, string>;
+  handles: HandleState;
+}
+
 /**
  * Result from starting a navigation
  * Implements Disposable for use with `using` keyword
@@ -224,7 +239,8 @@ export interface EventController {
   getActionState(actionId: string): TrackedActionState;
   getLocation(): NavigationLocation;
 
-  // Location updates (for popstate where navigation doesn't go through startNavigation)
+  // Location of a commit no transaction completes: a shallow navigation, a
+  // back/forward restored from the history cache, a back/forward that failed.
   setLocation(location: NavigationLocation): void;
 
   // Subscriptions
@@ -256,6 +272,31 @@ export interface EventController {
     resolvedIds?: string[],
   ): void;
   getHandleState(): HandleState;
+  /**
+   * Open the hydration window. Until releaseHydrationLock(), getHandleState()
+   * returns the state the document's HTML was rendered with, and handle writes
+   * (setHandleData, setRouteSegmentIds) wait in order. initBrowserApp opens it
+   * before hydrateRoot, once the document's handle snapshot is applied: a hook
+   * reading the handle state when its boundary hydrates, however late, reads
+   * what SSR rendered (issue #1035).
+   */
+  lockHydration(): void;
+  /**
+   * While the hydration window is open, the state the document's HTML was
+   * rendered with; undefined once it closes. A router hook's first render
+   * reads it: a component hydrating in a boundary that streamed in late
+   * renders what SSR rendered, even after a navigation or an action started.
+   * The hook's effect then catches up with the live state, and its
+   * subscription stays live, so pending UI is not held back.
+   */
+  getHydrationSnapshot(): HydrationSnapshot | undefined;
+  /**
+   * Close the hydration window: apply the writes that waited, in order, and
+   * notify handle subscribers. NavigationProvider calls it after the commit
+   * that made React hydrate every boundary still dehydrated (its barrier).
+   * Idempotent.
+   */
+  releaseHydrationLock(): void;
   /**
    * Update ONLY `routeSegmentIds` (what `useSegments` reads) from `matched`,
    * leaving `data` and `segmentOrder` (what `useHandle` collects over) untouched.
@@ -269,6 +310,21 @@ export interface EventController {
   setParams(params: Record<string, string>): void;
   getParams(): Record<string, string>;
 
+  /**
+   * Record the committed history entry's location state from `entryState`:
+   * the state object the commit pushed, restored or merged into the entry,
+   * so the entry and its readers have one source. Notifies nobody:
+   * NavigationProvider takes the snapshot with the entry's payload
+   * (LocationStateContext). `treeless` marks a commit no payload follows (a
+   * shallow navigation, a commit that keeps every segment, an action's
+   * state): the provider takes it with this commit's state notification, in
+   * the batch of the location.
+   */
+  commitLocationState(entryState: unknown, treeless?: boolean): void;
+  getLocationState(): LocationStateSnapshot;
+  /** True once after a `treeless` commit. */
+  takeTreelessLocationState(): boolean;
+
   // Direct state access for advanced use
   getCurrentNavigation(): NavigationEntry | null;
   getInflightActions(): Map<string, ActionEntry>;
@@ -460,9 +516,16 @@ export function createEventController(
   let handleData: HandleData = {};
   let handleSegmentOrder: string[] = [];
   let routeSegmentIds: string[] = [];
+  // The hydration window (lockHydration): what the document's HTML was
+  // rendered with, and the handle writes waiting for its release.
+  let hydrationSnapshot: HydrationSnapshot | undefined;
+  let writesAfterHydration: (() => void)[] = [];
 
   let routeParams: Record<string, string> = {};
 
+  let locationState: LocationStateSnapshot;
+  let treelessLocationState = false;
+
   const stateListeners = new Set<StateListener>();
   const actionListeners = new Map<string, Set<ActionStateListener>>();
   const handleListeners = new Set<HandleListener>();
@@ -985,6 +1048,12 @@ export function createEventController(
     isPartial?: boolean,
     resolvedIds?: string[],
   ): void {
+    if (hydrationSnapshot) {
+      writesAfterHydration.push(() =>
+        setHandleData(data, matched, isPartial, resolvedIds),
+      );
+      return;
+    }
     const rawMatched = matched ?? [];
     const newSegmentOrder = filterSegmentOrder(rawMatched);
     // Separate list for useSegments(): "layouts and routes only" — strip
@@ -992,7 +1061,10 @@ export function createEventController(
     const newRouteSegmentIds = filterRouteSegmentIds(rawMatched);
 
     if (isPartial && newSegmentOrder.length > 0) {
-      // Partial update: merge new data with existing
+      // Partial update: merge new data with existing, into a copy of the
+      // containers. The object a reader was handed is never written to: a
+      // history entry restored from the store's cache can be that object.
+      handleData = cloneHandleData(handleData);
       for (const handleName of Object.keys(data)) {
         if (!handleData[handleName]) {
           handleData[handleName] = {};
@@ -1029,6 +1101,7 @@ export function createEventController(
   }
 
   function getHandleState(): HandleState {
+    if (hydrationSnapshot) return hydrationSnapshot.handles;
     return {
       data: handleData,
       segmentOrder: handleSegmentOrder,
@@ -1036,7 +1109,29 @@ export function createEventController(
     };
   }
 
+  function lockHydration(): void {
+    if (hydrationSnapshot) return;
+    hydrationSnapshot = {
+      state: getState(),
+      params: routeParams,
+      handles: getHandleState(),
+    };
+  }
+
+  function releaseHydrationLock(): void {
+    if (!hydrationSnapshot) return;
+    hydrationSnapshot = undefined;
+    const writes = writesAfterHydration;
+    writesAfterHydration = [];
+    for (const write of writes) write();
+    notifyHandles.flush();
+  }
+
   function setRouteSegmentIds(matched: string[]): void {
+    if (hydrationSnapshot) {
+      writesAfterHydration.push(() => setRouteSegmentIds(matched));
+      return;
+    }
     const next = filterRouteSegmentIds(matched);
     if (
       next.length === routeSegmentIds.length &&
@@ -1094,6 +1189,20 @@ export function createEventController(
     return routeParams;
   }
 
+  function commitLocationState(entryState: unknown, treeless?: boolean): void {
+    locationState = locationStateSnapshot(entryState, locationState);
+    if (treeless) {
+      treelessLocationState = true;
+      notify();
+    }
+  }
+
+  function takeTreelessLocationState(): boolean {
+    const taken = treelessLocationState;
+    treelessLocationState = false;
+    return taken;
+  }
+
   // ========================================================================
   // Return Controller
   // ========================================================================
@@ -1116,12 +1225,20 @@ export function createEventController(
     // Handles
     setHandleData,
     getHandleState,
+    lockHydration,
+    getHydrationSnapshot: () => hydrationSnapshot,
+    releaseHydrationLock,
     setRouteSegmentIds,
 
     // Params
     setParams,
     getParams,
 
+    // Location state
+    commitLocationState,
+    getLocationState: () => locationState,
+    takeTreelessLocationState,
+
     // Subscriptions
     subscribe,
     subscribeToAction,

package/src/browser/history-state.ts

@@ -1,9 +1,13 @@
 import {
+  addLocationState,
+  CLEAR_ON_RELOAD_KEY_SUFFIX,
   isLocationStateDefinition,
   isLocationStateEntry,
+  isLocationStateKey,
   peekLocationStateKey,
   replaceCurrentHistoryState,
   resolveLocationStateEntries,
+  stampLocationState,
 } from "./react/location-state-shared.js";
 
 /**
@@ -13,7 +17,7 @@ function isTypedLocationState(
   state: unknown,
 ): state is Record<string, unknown> {
   if (state === null || typeof state !== "object") return false;
-  return Object.keys(state).some((key) => key.startsWith("__rsc_ls_"));
+  return Object.keys(state).some(isLocationStateKey);
 }
 
 /**
@@ -100,16 +104,15 @@ export function buildHistoryState(
     Object.assign(result, serverState);
   }
 
+  if (hasLocationState(result)) stampLocationState(result);
+
   return Object.keys(result).length > 0 ? result : null;
 }
 
 /** Check if a history state object contains location state keys. */
 export function hasLocationState(state: unknown): boolean {
   if (!state || typeof state !== "object") return false;
-  return (
-    "state" in state ||
-    Object.keys(state).some((k) => k.startsWith("__rsc_ls_"))
-  );
+  return "state" in state || Object.keys(state).some(isLocationStateKey);
 }
 
 /**
@@ -157,19 +160,38 @@ export function stripShellMissMarker(): void {
 }
 
 /**
- * Merge server-set location state into the current history entry.
- * Replaces the current history state and dispatches notification event
- * so useLocationState hooks re-read from history.state.
+ * Remove the `clearOnReload` slots of the entry a document load starts on:
+ * the server rendered this document without them. One pass before hydration
+ * (initBrowserApp; renderRoute's `hydrate` mode), so no reader needs to know
+ * the page began as a document load, and a slot nobody reads is removed too.
+ * No server-set state exists yet to lose: a document response carries none
+ * (rsc-rendering.ts attaches it to partial payloads only).
+ *
+ * A slot is recognised by its key alone (the `~r` suffix): at start-up the
+ * module that defines it may not be loaded.
+ */
+export function clearLocationStateOnDocumentLoad(): void {
+  const state: unknown = window.history.state;
+  if (state === null || typeof state !== "object") return;
+  let next: Record<string, unknown> | undefined;
+  for (const key in state) {
+    if (isLocationStateKey(key) && key.endsWith(CLEAR_ON_RELOAD_KEY_SUFFIX)) {
+      next ??= { ...state };
+      delete next[key];
+    }
+  }
+  if (next) window.history.replaceState(next, "");
+}
+
+/**
+ * Merge server-set location state into the current history entry and return
+ * the entry state written. Readers see it when the caller commits it
+ * (EventController.commitLocationState).
  */
 export function mergeLocationState(
   locationState: Record<string, unknown>,
-): void {
-  const merged = {
-    ...window.history.state,
-    ...locationState,
-  };
-  replaceCurrentHistoryState(merged);
-  if (Object.keys(locationState).some((k) => k.startsWith("__rsc_ls_"))) {
-    window.dispatchEvent(new Event("__rsc_locationstate"));
-  }
+): Record<string, unknown> {
+  const entryState = addLocationState(window.history.state, locationState);
+  replaceCurrentHistoryState(entryState);
+  return entryState;
 }

package/src/browser/link-interceptor.ts

@@ -4,7 +4,7 @@ import {
   type EventController,
 } from "./event-controller.js";
 import {
-  getDefaultPrefetchStrategy,
+  ENVIRONMENT_DEFAULT_PREFETCH,
   resolveAdaptiveStrategy,
   subscribeToAdaptiveStrategyChange,
 } from "./prefetch/default-strategy.js";
@@ -383,7 +383,7 @@ export function setupDelegatedLinkPrefetch(
   options: DelegatedPrefetchOptions,
 ): () => void {
   const defaultStrategy =
-    options.defaultPrefetch ?? getDefaultPrefetchStrategy();
+    options.defaultPrefetch ?? ENVIRONMENT_DEFAULT_PREFETCH;
   if (defaultStrategy === "none") return () => {};
 
   const basename = canonicalizeBasenamePathname(options.basename);

package/src/browser/navigation-bridge.ts

@@ -14,11 +14,7 @@ import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
-import {
-  buildHistoryState,
-  hasLocationState,
-  pushHistoryWithIdx,
-} from "./history-state.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -39,7 +35,10 @@ import {
   shouldStartViewTransition,
 } from "./partial-update.js";
 import { decideCommitGatedOff, mergeSegmentParams } from "./transition-when.js";
-import { generateHistoryKey } from "./navigation-store.js";
+import {
+  generateHistoryKey,
+  liveHandleDataForCache,
+} from "./navigation-store.js";
 import type { EventController } from "./event-controller.js";
 import { isInterceptOnlyCache } from "./intercept-utils.js";
 import {
@@ -58,6 +57,7 @@ import {
 } from "./prefetch/loader.js";
 import type { PrefetchStrategy } from "../router/prefetch-default.js";
 import { beginClientUrlNavigation } from "../client-urls/navigation.js";
+import { auditTreeCause } from "../suspense-audit.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -66,6 +66,9 @@ if (typeof Symbol.dispose === "undefined") {
 
 export { createNavigationTransaction };
 
+// Mirrors the redirect-chain limit browsers apply to document navigations.
+const MAX_REDIRECT_HOPS = 20;
+
 /**
  * Extended configuration for navigation bridge with event controller
  */
@@ -153,6 +156,45 @@ export function createNavigationBridge(
     getVersion: () => version,
   });
 
+  /**
+   * Re-navigates to a server redirect target, counting hops so a target that
+   * redirects back ends in the error boundary instead of looping.
+   */
+  async function followServerRedirect(
+    self: {
+      navigate: (
+        url: string,
+        options?: NavigateOptionsInternal,
+      ) => Promise<void>;
+    },
+    error: ServerRedirect,
+    url: string,
+    hops: number,
+    options: { replace?: boolean; transition?: boolean },
+  ): Promise<void> {
+    const redirectUrl = validateRedirectOrigin(
+      error.url,
+      window.location.origin,
+    );
+    if (!redirectUrl) {
+      return;
+    }
+    if (hops >= MAX_REDIRECT_HOPS) {
+      const loopError = new Error(
+        `[rango] Server redirect loop: stopped after following ${hops} redirects, at ${url}`,
+      );
+      console.error(loopError.message);
+      emitNavigationError(onUpdate, loopError, url);
+      return;
+    }
+    return self.navigate(redirectUrl, {
+      state: error.state,
+      ...options,
+      _skipCache: true,
+      _redirectHops: hops + 1,
+    });
+  }
+
   return {
     /**
      * Navigate to a URL
@@ -209,7 +251,11 @@ export function createNavigationBridge(
         const currentKey = store.getHistoryKey();
         const currentCache = store.getCachedSegments(currentKey);
         if (currentCache?.segments) {
-          const currentHandleData = eventController.getHandleState().data;
+          const currentHandleData = liveHandleDataForCache(
+            eventController,
+            store,
+            currentKey,
+          );
           store.cacheSegmentsForHistory(
             historyKey,
             currentCache.segments,
@@ -220,8 +266,6 @@ export function createNavigationBridge(
         // Save current scroll position before changing URL
         handleNavigationStart();
 
-        // Snapshot old state before pushState/replaceState overwrites it
-        const oldState = window.history.state;
         const shallowRouteName = store.getHistoryEntryMemory()?.routeName;
 
         // Update browser URL (carry intercept context into history state)
@@ -239,11 +283,8 @@ export function createNavigationBridge(
         ensureHistoryKey();
         // Same route, new entry (transition({ when }) back/forward source).
         store.rememberDisplayedEntry(shallowRouteName);
-
-        // Notify useLocationState() hooks when state changes
-        if (hasLocationState(oldState) || hasLocationState(historyState)) {
-          window.dispatchEvent(new Event("__rsc_locationstate"));
-        }
+        // Treeless: readers take the entry's state with setLocation below.
+        eventController.commitLocationState(historyState, true);
 
         // Update store history key so future navigations reference the right cache
         store.setHistoryKey(historyKey);
@@ -292,7 +333,11 @@ export function createNavigationBridge(
       const sourceHistoryKey = store.getHistoryKey();
       const sourceCached = store.getCachedSegments(sourceHistoryKey);
       if (sourceCached?.segments && sourceCached.segments.length > 0) {
-        const currentHandleData = eventController.getHandleState().data;
+        const currentHandleData = liveHandleDataForCache(
+          eventController,
+          store,
+          sourceHistoryKey,
+        );
         store.updateCacheHandleData(sourceHistoryKey, currentHandleData);
       }
 
@@ -357,6 +402,8 @@ export function createNavigationBridge(
       const clientUrlPresentation = beginClientUrlNavigation(
         targetUrl,
         tx.handle.signal,
+        // The entry the commit will push, without what the server adds.
+        () => buildHistoryState(resolvedState),
         transitionOptOut
           ? () => true
           : (destination) =>
@@ -378,7 +425,7 @@ export function createNavigationBridge(
                       url: targetUrl,
                       params: { ...params, ...destination.params },
                       routeName: destination.routeName,
-                      state: buildHistoryState(resolvedState),
+                      state: destination.state,
                     };
                   },
                   extra: destination.when,
@@ -420,29 +467,12 @@ export function createNavigationBridge(
               },
         );
       } catch (error) {
-        // Server-side redirect with location state: the current transaction's
-        // cleanup resets loading state. Re-navigate to the redirect
-        // target carrying the server-set state into history.pushState.
-        if (error instanceof ServerRedirect) {
-          const redirectUrl = validateRedirectOrigin(
-            error.url,
-            window.location.origin,
-          );
-          if (!redirectUrl) {
-            return;
-          }
-          return this.navigate(redirectUrl, {
-            state: error.state,
-            replace: options?.replace,
-            transition: options?.transition,
-            _skipCache: true,
-          } as NavigateOptionsInternal);
-        }
-
         // Aborted, or superseded by a newer navigation. A superseded nav may
         // reject with a non-AbortError (e.g. a Flight decode that fails after its
         // signal was aborted), so check the signal too -- otherwise we would
-        // render a boundary that clobbers the newer navigation's content.
+        // render a boundary that clobbers the newer navigation's content. Before
+        // the redirect branch: a superseded nav must not follow its redirect
+        // over the navigation that replaced it.
         if (
           (error instanceof DOMException && error.name === "AbortError") ||
           tx.handle.signal.aborted
@@ -451,6 +481,19 @@ export function createNavigationBridge(
           return;
         }
 
+        // Server-side redirect with location state: the current transaction's
+        // cleanup resets loading state. Re-navigate to the redirect
+        // target carrying the server-set state into history.pushState.
+        if (error instanceof ServerRedirect) {
+          return followServerRedirect(
+            this,
+            error,
+            url,
+            options?._redirectHops ?? 0,
+            { replace: options?.replace, transition: options?.transition },
+          );
+        }
+
         const networkError = toNetworkError(error, {
           url,
           operation: "navigation",
@@ -578,9 +621,6 @@ export function createNavigationBridge(
         historyKey,
       );
 
-      // Update location in event controller
-      eventController.setLocation(new URL(url));
-
       // If this is an intercept, restore the intercept context
       if (isIntercept && interceptSourceUrl) {
         store.setInterceptSourceUrl(interceptSourceUrl);
@@ -648,9 +688,16 @@ export function createNavigationBridge(
             transitionGatedOff: gatedOff,
           });
           store.rememberDisplayedEntry();
-          // Set params on event controller before onUpdate so both location
-          // and params are current when the debounced notify() fires.
+          // The restored entry's location and params, set before onUpdate so
+          // the hooks take both in the batch that renders its tree. Not at
+          // the popstate event: the page being left is on screen until here
+          // (#1031). A restore that has to fetch gets its location from
+          // tx.commit() instead (navigation-transaction.ts).
+          eventController.setLocation(new URL(url));
           eventController.setParams(cachedParams);
+          // The entry this handler found at the event, which the cached tree
+          // was built for: history may have moved during the render above.
+          eventController.commitLocationState(historyState);
 
           const popstateUpdate = {
             root,
@@ -673,6 +720,7 @@ export function createNavigationBridge(
             !isIntercept &&
             !isLeavingIntercept &&
             shouldStartViewTransition(cachedSegments, gatedOff);
+          if (process.env.NODE_ENV !== "production") auditTreeCause("popstate");
           if (hasTransition) {
             startTransition(() => {
               if (addTransitionType) {
@@ -783,6 +831,21 @@ export function createNavigationBridge(
           return;
         }
 
+        // The browser is already on the entry that redirected. Replacing makes
+        // that entry the redirect target, so Back from the target reaches the
+        // entry before it; a push would leave the redirecting entry in history
+        // and Back would hit the redirect again. Before setLocation below, or
+        // the hooks would report the redirecting URL first.
+        if (error instanceof ServerRedirect) {
+          return followServerRedirect(this, error, url, 0, { replace: true });
+        }
+
+        // tx.commit() never ran, so the location is still the page being
+        // left. The error boundary below replaces that page, and history is
+        // already on the entry that failed: the hooks report that entry, in
+        // the boundary's batch.
+        eventController.setLocation(new URL(url));
+
         const networkError = toNetworkError(error, {
           url,
           operation: "navigation",

package/src/browser/navigation-store.ts

@@ -8,7 +8,9 @@ import type {
   ResolvedSegment,
   HandleData,
 } from "./types.js";
+import type { EventController } from "./event-controller.js";
 import { clearPrefetchCache } from "./prefetch/cache.js";
+import { LoaderStore } from "../loader-store.js";
 import {
   adoptRangoState,
   getRangoState,
@@ -73,6 +75,28 @@ export function cloneHandleData(handleData: HandleData): HandleData {
   return cloned;
 }
 
+/**
+ * Handle data to write into the history cache for the page on screen. During
+ * the hydration window getHandleState() is the document snapshot while late
+ * pushes sit queued in the controller (they are already in the cache entry,
+ * written by rsc-router), so writing the snapshot back would drop them; the
+ * entry's own data is the live view then.
+ */
+export function liveHandleDataForCache(
+  eventController: Pick<
+    EventController,
+    "getHandleState" | "getHydrationSnapshot"
+  >,
+  store: Pick<NavigationStore, "getCachedSegments">,
+  historyKey: string,
+): HandleData {
+  if (eventController.getHydrationSnapshot()) {
+    const cached = store.getCachedSegments(historyKey)?.handleData;
+    if (cached) return cached;
+  }
+  return eventController.getHandleState().data;
+}
+
 // BroadcastChannel for cross-tab cache invalidation
 const CACHE_INVALIDATION_CHANNEL = "rsc-router-cache-invalidation";
 
@@ -390,6 +414,8 @@ export function createNavigationStore(
   }
 
   const store: NavigationStore = {
+    loaders: new LoaderStore(),
+
     // ========================================================================
     // Internal Segment State (for bridges)
     // ========================================================================