@rangojs/router 0.24.4 → 0.25.0

package/src/browser/navigation-bridge.ts

@@ -9,8 +9,8 @@ import { isPlaceholder } from "../types/segments.js";
 import { setAppVersion } from "./app-version.js";
 import { isActionFenceActive } from "./action-fence.js";
 import { getRangoState } from "./rango-state.js";
-import * as React from "react";
 import { startTransition } from "react";
+import { flushSync } from "react-dom";
 import {
   createNavigationTransaction,
   resolveNavigationState,
@@ -29,15 +29,12 @@ import {
   ensureHistoryKey,
 } from "./scroll-restoration.js";
 
-// addTransitionType is only available in React experimental
-const addTransitionType: ((type: string) => void) | undefined =
-  "addTransitionType" in React ? (React as any).addTransitionType : undefined;
-
 import {
   setupDelegatedLinkPrefetch,
   setupLinkInterception,
 } from "./link-interceptor.js";
 import {
+  addTransitionType,
   createPartialUpdater,
   shouldStartViewTransition,
 } from "./partial-update.js";
@@ -168,6 +165,8 @@ export function createNavigationBridge(
     basename,
   } = config;
   let version = config.version;
+  // The latest back/forward: an earlier one's deferred restore yields to it.
+  let popGeneration = 0;
 
   // Create shared partial updater
   const fetchPartialUpdate = createPartialUpdater({
@@ -188,7 +187,8 @@ export function createNavigationBridge(
       handles: (metadata) => {
         if (metadata.handles) consumeHandles(metadata, eventController, store);
       },
-      flush: eventController.flushRouteState,
+      // Committed before the page is handed over (PartialUpdateConfig.fill).
+      flush: () => flushSync(eventController.flushRouteState),
     },
   });
 
@@ -304,7 +304,7 @@ export function createNavigationBridge(
         // Save current scroll position before changing URL
         handleNavigationStart();
 
-        const shallowRouteName = store.getHistoryEntryMemory()?.routeName;
+        const shallowShown = store.getHistoryEntryMemory();
 
         // Update browser URL (carry intercept context into history state)
         const historyState = buildHistoryState(
@@ -320,7 +320,7 @@ export function createNavigationBridge(
         // Ensure new history entry has a scroll restoration key
         ensureHistoryKey();
         // Same route, new entry (transition({ when }) back/forward source).
-        store.rememberDisplayedEntry(shallowRouteName);
+        store.rememberDisplayedEntry(shallowShown);
         // Treeless: readers take the entry's state with setLocation below.
         eventController.commitLocationState(historyState, true);
 
@@ -628,7 +628,8 @@ export function createNavigationBridge(
      * Handle browser back/forward navigation
      * Uses cached segments when available for instant restoration
      */
-    async handlePopstate(): Promise<void> {
+    async handlePopstate(event?: PopStateEvent): Promise<void> {
+      const generation = ++popGeneration;
       // Abort any pending navigation to prevent race conditions, and the
       // fill of the page being left (prefetch: false), which its committed
       // navigation still owns.
@@ -738,18 +739,6 @@ export function createNavigationBridge(
             forceAwait: true,
             transitionGatedOff: gatedOff,
           });
-          store.rememberDisplayedEntry();
-          // 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,
             metadata: {
@@ -771,68 +760,106 @@ export function createNavigationBridge(
             !isIntercept &&
             !isLeavingIntercept &&
             shouldStartViewTransition(cachedSegments, gatedOff);
-          if (process.env.NODE_ENV !== "production") auditTreeCause("popstate");
-          if (hasTransition) {
-            startTransition(() => {
-              if (addTransitionType) {
-                addTransitionType("navigation-back");
-              }
-              onUpdate(popstateUpdate);
-            });
-          } else {
-            onUpdate(popstateUpdate);
-          }
-
-          // SWR: If stale, trigger background revalidation
-          if (isStale) {
-            debugLog("[Browser] Cache is stale, background revalidating...");
-            // Background revalidation - don't await, just fire and forget.
-            // When the entry's handles are incomplete (a deferred Meta was still
-            // pending when the user navigated away — see handlesPending), send NO
-            // segment IDs so the server returns a FULL re-render with the handle
-            // stream. A normal stale revalidation sends the cached IDs and the
-            // server returns a diff-only payload that omits unchanged segments'
-            // handles, so a deferred Meta would never re-stream and the title
-            // would stay the pre-resolution carry. handlesPending is set only for
-            // the deferred-Meta-aborted case, so action/cross-tab SWR keeps the
-            // cheap diff path.
-            const segmentIds = cached?.handlesPending
-              ? []
-              : cachedSegments.map((s) => s.id);
-
-            const tx = createNavigationTransaction(
-              store,
-              eventController,
-              url,
-              { skipLoadingState: true, replace: true },
-            );
+          // Not when the browser animated the swipe itself, nor when it
+          // restores this entry's scroll itself ("auto": no
+          // <Html.ScrollRestoration>), which it does right after the event,
+          // on whatever page is then on screen.
+          const animate =
+            hasTransition &&
+            !event?.hasUAVisualTransition &&
+            window.history.scrollRestoration === "manual";
+          const commit = (): void => {
+            // A later back/forward, or a navigation that committed first
+            // (a shallow one from an app's popstate listener), owns the
+            // screen now.
+            if (
+              generation !== popGeneration ||
+              store.getHistoryKey() !== historyKey
+            ) {
+              return;
+            }
+            store.rememberDisplayedEntry();
+            // The restored entry's location and params, set here 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, #1164). 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.
+            eventController.commitLocationState(historyState);
+            if (process.env.NODE_ENV !== "production") {
+              auditTreeCause("popstate");
+            }
+            if (!hasTransition) onUpdate(popstateUpdate);
+            else {
+              startTransition(() => {
+                if (animate) {
+                  addTransitionType?.("pop");
+                  addTransitionType?.("navigation-back");
+                }
+                onUpdate({ ...popstateUpdate, inTransition: true });
+              });
+            }
+            // SWR: If stale, trigger background revalidation
+            if (isStale) {
+              debugLog("[Browser] Cache is stale, background revalidating...");
+              // Background revalidation - don't await, just fire and forget.
+              // When the entry's handles are incomplete (a deferred Meta was still
+              // pending when the user navigated away — see handlesPending), send NO
+              // segment IDs so the server returns a FULL re-render with the handle
+              // stream. A normal stale revalidation sends the cached IDs and the
+              // server returns a diff-only payload that omits unchanged segments'
+              // handles, so a deferred Meta would never re-stream and the title
+              // would stay the pre-resolution carry. handlesPending is set only for
+              // the deferred-Meta-aborted case, so action/cross-tab SWR keeps the
+              // cheap diff path.
+              const segmentIds = cached?.handlesPending
+                ? []
+                : cachedSegments.map((s) => s.id);
+
+              const tx = createNavigationTransaction(
+                store,
+                eventController,
+                url,
+                { skipLoadingState: true, replace: true },
+              );
 
-            fetchPartialUpdate(
-              url,
-              segmentIds,
-              false,
-              tx.handle.signal,
-              tx.with({
+              fetchPartialUpdate(
                 url,
-                replace: true,
-                scroll: false,
-                intercept: isIntercept,
-                interceptSourceUrl,
-                cacheOnly: true,
-              }),
-              { type: "stale-revalidation", interceptSourceUrl },
-            )
-              .catch((error) => {
-                if (isBackgroundSuppressible(error)) return;
-                console.error(
-                  "[Browser] Background revalidation failed:",
-                  error,
-                );
-              })
-              .finally(() => {
-                tx[Symbol.dispose]();
-              });
-          }
+                segmentIds,
+                false,
+                tx.handle.signal,
+                tx.with({
+                  url,
+                  replace: true,
+                  scroll: false,
+                  intercept: isIntercept,
+                  interceptSourceUrl,
+                  cacheOnly: true,
+                }),
+                { type: "stale-revalidation", interceptSourceUrl },
+              )
+                .catch((error) => {
+                  if (isBackgroundSuppressible(error)) return;
+                  console.error(
+                    "[Browser] Background revalidation failed:",
+                    error,
+                  );
+                })
+                .finally(() => {
+                  tx[Symbol.dispose]();
+                });
+            }
+          };
+          // React commits a transition started while window.event is the
+          // popstate event synchronously, with no view transition, and leaves
+          // its types queued for the next transition commit (react-dom
+          // shouldAttemptEagerTransition). An animated restore commits on the
+          // next task: the page being left stays on screen one task longer.
+          if (animate) setTimeout(commit, 0);
+          else commit();
           return;
         } catch (error) {
           console.warn(
@@ -898,8 +925,9 @@ export function createNavigationBridge(
         // 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.
+        // the boundary's batch, and scroll restoration tracks it as shown.
         eventController.setLocation(new URL(url));
+        ensureHistoryKey();
 
         const networkError = toNetworkError(error, {
           url,
@@ -932,8 +960,8 @@ export function createNavigationBridge(
         this.navigate(url, options);
       });
 
-      const handlePopstate = () => {
-        this.handlePopstate();
+      const handlePopstate = (event: PopStateEvent) => {
+        this.handlePopstate(event);
       };
 
       // When the browser restores a page from bfcache (back-forward cache),

package/src/browser/navigation-client.ts

@@ -79,6 +79,7 @@ export function createNavigationClient(
         targetUrl,
         segmentIds,
         previousUrl,
+        rewriteTarget,
         signal,
         staleRevalidation,
         interceptSourceUrl,
@@ -115,6 +116,11 @@ export function createNavigationClient(
       if (routerId) {
         fetchUrl.searchParams.set("_rsc_rid", routerId);
       }
+      // The page left's rewrite target (#1144), in both prefetch keys like
+      // the params above: buildPrefetchUrl sets it in the same place.
+      if (rewriteTarget) {
+        fetchUrl.searchParams.set("_rsc_rt", rewriteTarget);
+      }
       // A param, not a header: the document cache decides from the raw URL
       // (cache/document-cache.ts), and it keeps the fill out of every
       // prefetch key below.
@@ -317,18 +323,15 @@ export function createNavigationClient(
       // so only a fully-warmed prefetch commits in a transition (no fallback flash).
       let fullyPrefetched = false;
 
-      if (cachedEntry) {
+      // The prefetch entry this navigation serves.
+      let adopted = cachedEntry;
+      if (adopted) {
         if (tx) {
           browserDebugLog(tx, "prefetch cache hit (warm)", {
             key: hitKey,
             wildcard: hitKey === wildcardKey,
           });
         }
-        payloadPromise = cachedEntry.payload;
-        streamCompletePromise = cachedEntry.streamComplete;
-        // Only a hit whose stream already fully drained is "fully prefetched";
-        // a still-streaming hit must keep streaming its fallbacks like a cold load.
-        fullyPrefetched = cachedEntry.complete;
       } else if (inflightEntryPromise) {
         if (tx) {
           browserDebugLog(tx, "reusing inflight prefetch", {
@@ -342,8 +345,6 @@ export function createNavigationClient(
           if (tx) {
             browserDebugLog(tx, "inflight prefetch unavailable, refetching");
           }
-          ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
-            freshResult());
         } else if (adoptedViaWildcard && entry.scope === "source") {
           // A wildcard-adopted inflight that turned out source-scoped was
           // built for a different source page. Discard and refetch.
@@ -353,15 +354,19 @@ export function createNavigationClient(
               "wildcard inflight turned out source-scoped, refetching",
             );
           }
-          ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
-            freshResult());
         } else {
-          payloadPromise = entry.payload;
-          streamCompletePromise = entry.streamComplete;
-          // Adopted inflight is normally still streaming (false), but read the
-          // flag in case it completed between publish and adoption.
-          fullyPrefetched = entry.complete;
+          adopted = entry;
         }
+      }
+      if (adopted) {
+        // The click owns the stream from here on (DecodedPrefetch.stallTimer).
+        clearTimeout(adopted.stallTimer);
+        payloadPromise = adopted.payload;
+        streamCompletePromise = adopted.streamComplete;
+        // Only an entry whose stream already fully drained is "fully
+        // prefetched"; a still-streaming one keeps streaming its fallbacks like
+        // a cold load.
+        fullyPrefetched = adopted.complete;
       } else {
         ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
           freshResult());

package/src/browser/navigation-store.ts

@@ -7,6 +7,7 @@ import type {
   UpdateSubscriber,
   ResolvedSegment,
   HandleData,
+  ShownEntry,
 } from "./types.js";
 import type { EventController } from "./event-controller.js";
 import { clearPrefetchCache } from "./prefetch/cache.js";
@@ -466,13 +467,14 @@ export function createNavigationStore(
       currentHistoryKey = key;
     },
 
-    rememberDisplayedEntry(routeName?: string): void {
+    rememberDisplayedEntry(shown?: ShownEntry): void {
       if (typeof window === "undefined") return;
       const key = getHistoryStateKey();
       const previous = entryMemory.get(key);
       entryMemory.delete(key);
       entryMemory.set(key, {
-        routeName: routeName ?? previous?.routeName,
+        routeName: shown?.routeName ?? previous?.routeName,
+        rewriteTarget: (shown ?? previous)?.rewriteTarget,
         state: window.history.state,
       });
       if (entryMemory.size > HISTORY_ENTRY_MEMORY_SIZE) {

package/src/browser/navigation-transaction.ts

@@ -2,6 +2,7 @@ import type {
   NavigateOptionsInternal,
   NavigationStore,
   ResolvedSegment,
+  ShownEntry,
   StreamingToken,
 } from "./types.js";
 import {
@@ -53,8 +54,8 @@ interface CommitOptions {
    * merged in. The page left was saved by handleTraversalStart.
    */
   traversal?: boolean;
-  /** The committed route's name (payload metadata), remembered per history entry. */
-  routeName?: string;
+  /** The payload's metadata: its route name and rewrite target, remembered per history entry. */
+  metadata?: ShownEntry;
   /**
    * transition({ when }) decision already made at this navigation's first
    * presentation (the optimistic clientUrls() swap). Not a commit input: the
@@ -86,8 +87,8 @@ interface BoundCommitOverrides {
   cacheOnly?: boolean;
   /** Server-set location state to merge into history.pushState */
   serverState?: Record<string, unknown>;
-  /** The committed route's name (payload metadata), remembered per history entry. */
-  routeName?: string;
+  /** The payload's metadata: its route name and rewrite target, remembered per history entry. */
+  metadata?: ShownEntry;
   /** No payload follows this commit (CommitOptions.treeless). */
   treeless?: boolean;
 }
@@ -210,7 +211,7 @@ export function createNavigationTransaction(
     if (storeOnly) {
       // Same entry (an action refetch): refresh its state, keep its name
       // unless the payload names it.
-      store.rememberDisplayedEntry(opts.routeName);
+      store.rememberDisplayedEntry(opts.metadata);
       debugLog("[Browser] Store updated (action)");
       handle.complete(parsedUrl);
       return {};
@@ -222,7 +223,7 @@ export function createNavigationTransaction(
         serverState && Object.keys(serverState).length > 0
           ? mergeLocationState(serverState)
           : window.history.state;
-      store.rememberDisplayedEntry(opts.routeName);
+      store.rememberDisplayedEntry(opts.metadata);
       eventController.commitLocationState(entryState, opts.treeless);
       handle.complete(parsedUrl);
       debugLog("[Browser] Traversal committed, historyKey:", historyKey);
@@ -237,7 +238,7 @@ export function createNavigationTransaction(
 
     pushHistoryWithIdx(historyState, url, replace ?? false);
     ensureHistoryKey();
-    store.rememberDisplayedEntry(opts.routeName);
+    store.rememberDisplayedEntry(opts.metadata);
     eventController.commitLocationState(historyState, opts.treeless);
 
     handle.complete(parsedUrl);
@@ -296,7 +297,7 @@ export function createNavigationTransaction(
             interceptSourceUrl,
             cacheOnly,
             serverState,
-            routeName: overrides?.routeName ?? opts.routeName,
+            metadata: overrides?.metadata ?? opts.metadata,
             treeless: overrides?.treeless,
           });
         },