@rangojs/router 0.21.0 → 0.22.0

package/src/browser/navigation-bridge.ts

@@ -35,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 {
@@ -54,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") {
@@ -62,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
  */
@@ -149,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
@@ -205,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,
@@ -283,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);
       }
 
@@ -413,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
@@ -444,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",
@@ -670,6 +720,7 @@ export function createNavigationBridge(
             !isIntercept &&
             !isLeavingIntercept &&
             shouldStartViewTransition(cachedSegments, gatedOff);
+          if (process.env.NODE_ENV !== "production") auditTreeCause("popstate");
           if (hasTransition) {
             startTransition(() => {
               if (addTransitionType) {
@@ -786,18 +837,7 @@ export function createNavigationBridge(
         // and Back would hit the redirect again. Before setLocation below, or
         // the hooks would report the redirecting URL first.
         if (error instanceof ServerRedirect) {
-          const redirectUrl = validateRedirectOrigin(
-            error.url,
-            window.location.origin,
-          );
-          if (!redirectUrl) {
-            return;
-          }
-          return this.navigate(redirectUrl, {
-            state: error.state,
-            replace: true,
-            _skipCache: true,
-          } as NavigateOptionsInternal);
+          return followServerRedirect(this, error, url, 0, { replace: true });
         }
 
         // tx.commit() never ran, so the location is still the page being

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)
     // ========================================================================

package/src/browser/navigation-transaction.ts

@@ -4,7 +4,10 @@ import type {
   ResolvedSegment,
   StreamingToken,
 } from "./types.js";
-import { generateHistoryKey } from "./navigation-store.js";
+import {
+  generateHistoryKey,
+  liveHandleDataForCache,
+} from "./navigation-store.js";
 import {
   handleNavigationStart,
   ensureHistoryKey,
@@ -180,7 +183,11 @@ export function createNavigationTransaction(
 
     store.setHistoryKey(historyKey);
 
-    const currentHandleData = eventController.getHandleState().data;
+    // storeOnly re-caches the page on screen (an action refetch), which can
+    // commit with no tree and so never release the hydration window.
+    const currentHandleData = storeOnly
+      ? liveHandleDataForCache(eventController, store, historyKey)
+      : eventController.getHandleState().data;
     store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
 
     if (storeOnly) {

package/src/browser/network-error-handler.ts

@@ -2,6 +2,7 @@ import { NetworkError, isNetworkError } from "../errors.js";
 import { RenderErrorThrower } from "../render-error-thrower.js";
 import type { UpdateSubscriber } from "./types.js";
 import { createElement, startTransition } from "react";
+import { auditTreeCause } from "../suspense-audit.js";
 
 /**
  * Convert an unknown error to a NetworkError, or return null if not network-related.
@@ -33,6 +34,7 @@ function emitErrorToBoundary(
   error: unknown,
   pathname: string,
 ): void {
+  if (process.env.NODE_ENV !== "production") auditTreeCause("error");
   startTransition(() => {
     onUpdate({
       root: createElement(RenderErrorThrower, { error }),

package/src/browser/partial-update.ts

@@ -31,7 +31,7 @@ import {
 } from "./validate-redirect-origin.js";
 import type { NavigationUpdate } from "./types.js";
 import { OPTIMISTIC_COMMIT_TRANSITION_TYPE } from "./optimistic-commit.js";
-import { loaderStore } from "../loader-store.js";
+import type { LoaderStore } from "../loader-store.js";
 import {
   collectClientRevalidationDecisions,
   setActiveInterceptTargets,
@@ -44,6 +44,7 @@ import {
 import { buildHistoryState } from "./history-state.js";
 import { addLocationState } from "./react/location-state-shared.js";
 import type { TransitionWhenKind } from "../types/segments.js";
+import { auditTreeCause, type TreeUpdateCause } from "../suspense-audit.js";
 
 function toScrollPayload(
   scroll: boolean | undefined,
@@ -70,6 +71,13 @@ export function shouldStartViewTransition(
   return !hasIntercept && hasTransition;
 }
 
+// Dev only (suspense-audit.ts I6): what this updater's commit is.
+function treeCause(mode: UpdateMode, traversal?: boolean): TreeUpdateCause {
+  if (mode.type === "action") return "action";
+  if (mode.type === "stale-revalidation") return "stale-revalidation";
+  return traversal ? "popstate" : "navigation";
+}
+
 /**
  * Transition commit. Every held commit announces the loader streams the
  * committed tree is still receiving (loader-store.ts announcePendingStreams)
@@ -79,13 +87,14 @@ export function shouldStartViewTransition(
  * its fallback. Also used by renderRoute's navigate() (testing/render-route.tsx).
  */
 export function commitInTransition(
+  loaders: LoaderStore,
   onUpdate: UpdateSubscriber,
   segments: readonly ResolvedSegment[],
   update: NavigationUpdate,
   transitionTypes: readonly string[],
 ): void {
   startTransition(() => {
-    loaderStore.announcePendingStreams(segments);
+    loaders.announcePendingStreams(segments);
     if (addTransitionType) {
       for (const type of transitionTypes) addTransitionType(type);
     }
@@ -464,10 +473,17 @@ export function createPartialUpdater(
             scroll: toScrollPayload(commitScroll),
           };
 
+          if (process.env.NODE_ENV !== "production") {
+            auditTreeCause(treeCause(mode, tx.traversal));
+          }
           if (shouldStartViewTransition(existingSegments, cachedGatedOff)) {
-            commitInTransition(onUpdate, existingSegments, cachedUpdate, [
-              "navigation",
-            ]);
+            commitInTransition(
+              store.loaders,
+              onUpdate,
+              existingSegments,
+              cachedUpdate,
+              ["navigation"],
+            );
           } else {
             onUpdate(cachedUpdate);
           }
@@ -491,6 +507,9 @@ export function createPartialUpdater(
             { routeName: payload.metadata.routeName },
           );
 
+          if (process.env.NODE_ENV !== "production") {
+            auditTreeCause(treeCause(mode, tx.traversal));
+          }
           onUpdate({
             root: newTree,
             metadata: payload.metadata,
@@ -718,11 +737,15 @@ export function createPartialUpdater(
         metadata: payload.metadata!,
         scroll: scrollPayload,
       };
+      if (process.env.NODE_ENV !== "production") {
+        auditTreeCause(treeCause(mode, tx.traversal));
+      }
       if (
         !gatedOff &&
         (mode.type === "action" || mode.type === "stale-revalidation")
       ) {
         commitInTransition(
+          store.loaders,
           onUpdate,
           reconciled.mainSegments,
           update,
@@ -730,6 +753,7 @@ export function createPartialUpdater(
         );
       } else if (hasTransition) {
         commitInTransition(
+          store.loaders,
           onUpdate,
           reconciled.mainSegments,
           update,
@@ -764,6 +788,7 @@ export function createPartialUpdater(
         // segment reconciles in place (clientGroup key), so a read that still
         // suspends must hold the presented content, not flash a fallback.
         commitInTransition(
+          store.loaders,
           onUpdate,
           reconciled.mainSegments,
           update,
@@ -772,12 +797,13 @@ export function createPartialUpdater(
       } else {
         // Cold/partially-prefetched nav that mounts NEW segments, or any
         // commit transition({ when }) gated off (navigation, action refetch,
-        // stale revalidation): normal commit so fallbacks stream
-        // like a first load and the click has visible feedback. A gated-off
-        // segment keeps its key, so its loading() fallback comes from its
-        // boundary re-suspending on this urgent commit, not from a remount
-        // (#995). Explicit transition() routes keep the content-hold via the
-        // hasTransition branch above (the opt-in).
+        // stale revalidation): normal, unanimated commit. A segment with work
+        // still pending shows its loading() fallback like a first load; one
+        // whose data is already in hand shows none. A gated-off segment keeps
+        // its key, so a fallback comes from its boundary suspending on pending
+        // work in this urgent commit, not from a remount (#995). Explicit
+        // transition() routes keep the content-hold via the hasTransition
+        // branch above (the opt-in).
         onUpdate(update);
       }
 
@@ -822,6 +848,9 @@ export function createPartialUpdater(
         scroll: fullScrollPayload,
       };
 
+      if (process.env.NODE_ENV !== "production") {
+        auditTreeCause(treeCause(mode, tx.traversal));
+      }
       if (mode.type === "stale-revalidation") {
         await rawStreamComplete;
         // Mirror the partial branch's history-key staleness guard (above): the
@@ -836,9 +865,13 @@ export function createPartialUpdater(
           );
           return;
         }
+        if (process.env.NODE_ENV !== "production") {
+          auditTreeCause("stale-revalidation");
+        }
         if (fullGatedOff) onUpdate(fullUpdate);
         else {
           commitInTransition(
+            store.loaders,
             onUpdate,
             segments,
             fullUpdate,
@@ -847,13 +880,16 @@ export function createPartialUpdater(
         }
       } else if (mode.type === "action" && !fullGatedOff) {
         commitInTransition(
+          store.loaders,
           onUpdate,
           segments,
           fullUpdate,
           fullHasTransition ? ["action"] : [],
         );
       } else if (fullHasTransition) {
-        commitInTransition(onUpdate, segments, fullUpdate, ["navigation"]);
+        commitInTransition(store.loaders, onUpdate, segments, fullUpdate, [
+          "navigation",
+        ]);
       } else {
         onUpdate(fullUpdate);
       }

package/src/browser/prefetch/default-strategy.ts

@@ -2,68 +2,48 @@
  * Router-wide default prefetch strategy (client seat).
  *
  * The server resolves `createRouter({ defaultPrefetch })` once at router init
- * (router/prefetch-default.ts) and ships it in initial payload metadata; the
- * browser entry applies it here before hydration — same lifecycle as
- * `initPrefetchCache` / `setPrefetchConcurrency`. Every `<Link>` without an
- * explicit `prefetch` prop and every eligible intercepted plain anchor that has
- * not opted out with `data-prefetch="false"` or `data-prefetch="none"` uses it.
- * Containers use the same `false`/`none` vocabulary via
- * `data-prefetch-scope`.
- *
- * The module initial value must equal the server resolver's environment default:
- * `"none"` in development and `"viewport"` in production. During SSR this
- * module is never initialized from metadata, so keeping both seats aligned also
- * gives metadata-less payloads the documented behavior.
+ * (router/prefetch-default.ts) and ships it in initial payload metadata. The
+ * router store carries it to its readers: `<Link>` reads
+ * `NavigationStoreContext.defaultPrefetch`, and delegated plain anchors get it
+ * from the navigation bridge. Every `<Link>` without an explicit `prefetch`
+ * prop and every eligible intercepted plain anchor that has not opted out with
+ * `data-prefetch="false"` or `data-prefetch="none"` uses it. Containers use the
+ * same `false`/`none` vocabulary via `data-prefetch-scope`.
  */
 
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 
-let hoverNoneQuery: MediaQueryList | null = null;
-
-// Mirrors DEFAULT_PREFETCH_STRATEGY without pulling router-layer code into the
-// client bundle. NODE_ENV is folded by the app build.
-let defaultStrategy: PrefetchStrategy =
+/**
+ * The default for a payload without `defaultPrefetch`: the server resolver's
+ * environment default (`"none"` in development, `"viewport"` in production),
+ * mirrored without pulling router-layer code into the client bundle. NODE_ENV
+ * is folded by the app build.
+ */
+export const ENVIRONMENT_DEFAULT_PREFETCH: PrefetchStrategy =
   process.env.NODE_ENV === "production" ? "viewport" : "none";
 
-function getHoverNoneQuery(): MediaQueryList | null {
-  if (typeof window === "undefined") return null;
-  if (!hoverNoneQuery) {
-    hoverNoneQuery = window.matchMedia("(hover: none)");
-  }
-  return hoverNoneQuery;
-}
-
-/** Reset module state between tests that replace browser media globals. */
-export function resetAdaptiveStrategyForTesting(): void {
-  hoverNoneQuery = null;
+function hoverNoneQuery(): MediaQueryList | null {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function")
+    return null;
+  return window.matchMedia("(hover: none)");
 }
 
 /**
- * Apply the server-resolved default strategy. Called once at browser app init
- * from payload metadata; also used by tests to reset state.
+ * Resolve adaptive to the strategy for the current input capability. Called
+ * when a prefetch is armed or triggered, never during render.
  */
-export function setDefaultPrefetchStrategy(strategy: PrefetchStrategy): void {
-  defaultStrategy = strategy;
-}
-
-/** Current default strategy for Links and delegated plain anchors. */
-export function getDefaultPrefetchStrategy(): PrefetchStrategy {
-  return defaultStrategy;
-}
-
-/** Resolve adaptive to the strategy for the current input capability. */
 export function resolveAdaptiveStrategy(
   strategy: PrefetchStrategy,
 ): PrefetchStrategy {
   if (strategy !== "adaptive") return strategy;
-  return getHoverNoneQuery()?.matches ? "viewport" : "hover";
+  return hoverNoneQuery()?.matches ? "viewport" : "hover";
 }
 
 /** Subscribe to changes in the input capability used by adaptive prefetch. */
 export function subscribeToAdaptiveStrategyChange(
   listener: () => void,
 ): () => void {
-  const query = getHoverNoneQuery();
+  const query = hoverNoneQuery();
   if (!query) return () => {};
   if (typeof query.addEventListener === "function") {
     query.addEventListener("change", listener);