@rangojs/router 0.20.0 → 0.22.0

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,
@@ -13,7 +16,6 @@ import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
 import {
   buildHistoryState,
-  hasLocationState,
   mergeLocationState,
   pushHistoryWithIdx,
 } from "./history-state.js";
@@ -59,6 +61,11 @@ interface CommitOptions {
    * partial updater reuses it instead of deciding again.
    */
   transitionGatedOff?: boolean;
+  /**
+   * No payload follows this commit: every segment is kept and the tree on
+   * screen stays (EventController.commitLocationState).
+   */
+  treeless?: boolean;
 }
 
 /**
@@ -81,6 +88,8 @@ interface BoundCommitOverrides {
   serverState?: Record<string, unknown>;
   /** The committed route's name (payload metadata), remembered per history entry. */
   routeName?: string;
+  /** No payload follows this commit (CommitOptions.treeless). */
+  treeless?: boolean;
 }
 
 /**
@@ -174,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) {
@@ -187,10 +200,13 @@ export function createNavigationTransaction(
     }
 
     if (traversal) {
-      if (serverState && Object.keys(serverState).length > 0) {
-        mergeLocationState(serverState);
-      }
+      // The entry as history restored it, plus what the server adds.
+      const entryState: unknown =
+        serverState && Object.keys(serverState).length > 0
+          ? mergeLocationState(serverState)
+          : window.history.state;
       store.rememberDisplayedEntry(opts.routeName);
+      eventController.commitLocationState(entryState, opts.treeless);
       handle.complete(parsedUrl);
       debugLog("[Browser] Traversal committed, historyKey:", historyKey);
       return { scroll };
@@ -202,15 +218,10 @@ export function createNavigationTransaction(
       serverState,
     );
 
-    const oldState = window.history.state;
-
     pushHistoryWithIdx(historyState, url, replace ?? false);
     ensureHistoryKey();
     store.rememberDisplayedEntry(opts.routeName);
-
-    if (hasLocationState(oldState) || hasLocationState(historyState)) {
-      window.dispatchEvent(new Event("__rsc_locationstate"));
-    }
+    eventController.commitLocationState(historyState, opts.treeless);
 
     handle.complete(parsedUrl);
 
@@ -269,6 +280,7 @@ export function createNavigationTransaction(
             cacheOnly,
             serverState,
             routeName: overrides?.routeName ?? opts.routeName,
+            treeless: overrides?.treeless,
           });
         },
       };

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,
@@ -42,7 +42,9 @@ import {
   type TransitionWhenActionInput,
 } from "./transition-when.js";
 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,
@@ -69,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)
@@ -78,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);
     }
@@ -225,8 +235,14 @@ export function createPartialUpdater(
       segments = segmentIds ?? segmentState.currentSegmentIds;
     }
 
+    // The page the client is on, which the server diffs the target against.
+    // tx.currentUrl is window.location when the transaction was created: on
+    // a back/forward the popstate event had already moved it to the target,
+    // and a server told the target is also the source revalidates nothing on
+    // the same route, so the page being left stayed on screen (#1030). The
+    // store's URL is the committed entry's until tx.commit().
     const previousUrl =
-      mode.type === "leave-intercept"
+      mode.type === "leave-intercept" || (tx.traversal && !interceptSourceUrl)
         ? segmentState.currentUrl || tx.currentUrl
         : interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
 
@@ -279,7 +295,7 @@ export function createPartialUpdater(
             params: metadata.params ?? mergeSegmentParams(segmentsToCommit),
             routeName: metadata.routeName,
             state: tx.traversal
-              ? { ...window.history.state, ...metadata.locationState }
+              ? addLocationState(window.history.state, metadata.locationState)
               : buildHistoryState(tx.state, undefined, metadata.locationState),
           }),
           action:
@@ -457,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);
           }
@@ -484,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,
@@ -499,6 +525,7 @@ export function createPartialUpdater(
         );
         tx.commit(matchedIds, existingSegments, {
           routeName: payload.metadata.routeName,
+          treeless: true,
         });
         debugLog("[Browser] Navigation complete (no re-render)");
         return;
@@ -710,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,
@@ -722,6 +753,7 @@ export function createPartialUpdater(
         );
       } else if (hasTransition) {
         commitInTransition(
+          store.loaders,
           onUpdate,
           reconciled.mainSegments,
           update,
@@ -756,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,
@@ -764,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);
       }
 
@@ -814,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
@@ -828,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,
@@ -839,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);

package/src/browser/rango-state.ts

@@ -7,7 +7,9 @@
  * cache keys responses by (URL, X-Rango-State value).
  *
  * Value format: `{buildVersion}:{invalidationTimestamp}`
- * - Build version changes on deploy, busting all cached prefetches at boot.
+ * - Build version: the router's document version. It changes when a deploy
+ *   changes the router's server code or the client assets, busting all cached
+ *   prefetches at boot; a deploy that changes neither keeps them.
  * - Timestamp rotates on invalidation (server action, invalidateClientCache).
  *
  * Storage is a session cookie named by the server-resolved name passed to

package/src/browser/react/Link.tsx

@@ -7,7 +7,6 @@ import React, {
   useEffect,
   useMemo,
   useRef,
-  useSyncExternalStore,
   type ForwardRefExoticComponent,
   type RefAttributes,
 } from "react";
@@ -38,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";
@@ -51,8 +50,6 @@ import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 export type { PrefetchStrategy } from "../../router/prefetch-default.js";
 export { resolveAdaptiveStrategy } from "../prefetch/default-strategy.js";
 
-const IGNORE_STRATEGY_CHANGES = (_listener: () => void) => () => {};
-
 /**
  * Link component props
  */
@@ -241,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.
@@ -265,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
-      : IGNORE_STRATEGY_CHANGES,
-    () => 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);
@@ -376,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 ||
@@ -396,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 &&
@@ -458,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