@rangojs/router 0.18.0 → 0.19.0

package/src/browser/navigation-store.ts

@@ -1,4 +1,5 @@
 import type {
+  HistoryEntryMemory,
   NavigationLocation,
   SegmentState,
   NavigationStore,
@@ -13,10 +14,18 @@ import {
   getRangoState,
   getRangoStateCookieName,
 } from "./rango-state.js";
+import { getHistoryStateKey } from "./scroll-restoration.js";
+import { setCurrentHistoryStateListener } from "./react/location-state-shared.js";
 
 // Maximum number of history entries to cache (URLs visited)
 const HISTORY_CACHE_SIZE = 20;
 
+// Bound on remembered history entries (transition({ when }) sources), matching
+// scroll-restoration's MAX_SCROLL_ENTRIES: deep enough for any realistic
+// back/forward run, bounded for long sessions. An evicted entry reads as
+// unknown (undefined route name and state), never guessed.
+const HISTORY_ENTRY_MEMORY_SIZE = 200;
+
 // Cache entry:
 //   [url-key, segments, stale, handleData?, routerId?, navInstance?, handlesPending?]
 // stale=true means the data may be outdated and should be revalidated on access.
@@ -233,6 +242,11 @@ export function createNavigationStore(
   // Current history key (set on navigation, stored in history.state)
   let currentHistoryKey = config?.initialHistoryKey || generateHistoryKey();
 
+  // Per-history-entry memory (rememberDisplayedEntry), keyed by the entry's
+  // history.state.key — unique per entry, unlike the URL-derived history key.
+  const entryMemory = new Map<string, HistoryEntryMemory>();
+  let displayedEntryKey: string | undefined;
+
   // Store initial segments if provided (not stale)
   if (config?.initialHistoryKey && config?.initialSegments) {
     historyCache.push([
@@ -375,7 +389,7 @@ export function createNavigationStore(
     }
   }
 
-  return {
+  const store: NavigationStore = {
     // ========================================================================
     // Internal Segment State (for bridges)
     // ========================================================================
@@ -426,6 +440,27 @@ export function createNavigationStore(
       currentHistoryKey = key;
     },
 
+    rememberDisplayedEntry(routeName?: string): void {
+      if (typeof window === "undefined") return;
+      const key = getHistoryStateKey();
+      const previous = entryMemory.get(key);
+      entryMemory.delete(key);
+      entryMemory.set(key, {
+        routeName: routeName ?? previous?.routeName,
+        state: window.history.state,
+      });
+      if (entryMemory.size > HISTORY_ENTRY_MEMORY_SIZE) {
+        const oldest = entryMemory.keys().next().value;
+        if (oldest !== undefined) entryMemory.delete(oldest);
+      }
+      displayedEntryKey = key;
+    },
+
+    getHistoryEntryMemory(entryKey?: string): HistoryEntryMemory | undefined {
+      const key = entryKey ?? displayedEntryKey;
+      return key === undefined ? undefined : entryMemory.get(key);
+    },
+
     /**
      * Current nav-instance token: the instance of the most recently committed
      * navigation (the value last written by cacheSegmentsForHistory). A late
@@ -682,4 +717,11 @@ export function createNavigationStore(
       });
     },
   };
+
+  // Writes to the displayed entry after its commit (Def.write()/delete(), a
+  // flash read, merged server state) refresh its memory.
+  if (typeof window !== "undefined") {
+    setCurrentHistoryStateListener(() => store.rememberDisplayedEntry());
+  }
+  return store;
 }

package/src/browser/navigation-transaction.ts

@@ -1,5 +1,5 @@
 import type {
-  NavigateOptions,
+  NavigateOptionsInternal,
   NavigationStore,
   ResolvedSegment,
   StreamingToken,
@@ -13,21 +13,13 @@ import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
 import {
   buildHistoryState,
+  hasLocationState,
   mergeLocationState,
   pushHistoryWithIdx,
 } from "./history-state.js";
 
 export { resolveNavigationState } from "./history-state.js";
 
-/** Check if a history state object contains location state keys. */
-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_"))
-  );
-}
-
 if (typeof Symbol.dispose === "undefined") {
   (Symbol as any).dispose = Symbol("Symbol.dispose");
 }
@@ -59,6 +51,14 @@ 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;
+  /**
+   * transition({ when }) decision already made at this navigation's first
+   * presentation (the optimistic clientUrls() swap). Not a commit input: the
+   * partial updater reuses it instead of deciding again.
+   */
+  transitionGatedOff?: boolean;
 }
 
 /**
@@ -79,6 +79,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;
 }
 
 /**
@@ -86,6 +88,14 @@ interface BoundCommitOverrides {
  */
 export interface BoundTransaction {
   readonly currentUrl: string;
+  /** Bound `replace` option (history replace instead of push). */
+  readonly replace?: boolean;
+  /** Bound `traversal` option: a back/forward navigation. */
+  readonly traversal?: boolean;
+  /** Bound user state (resolved), pushed with the entry at commit. */
+  readonly state?: unknown;
+  /** Bound `transitionGatedOff`: the decision made at first presentation. */
+  readonly transitionGatedOff?: boolean;
   /** Start streaming and get a token to end it when the stream completes */
   startStreaming(): StreamingToken;
   /** Commit the navigation. Returns the effective scroll option for the caller to handle. */
@@ -117,7 +127,7 @@ export function createNavigationTransaction(
   store: NavigationStore,
   eventController: EventController,
   url: string,
-  options?: NavigateOptions & { skipLoadingState?: boolean },
+  options?: NavigateOptionsInternal & { skipLoadingState?: boolean },
 ): NavigationTransaction {
   let committed = false;
   const currentUrl = window.location.href;
@@ -168,6 +178,9 @@ export function createNavigationTransaction(
     store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
 
     if (storeOnly) {
+      // Same entry (an action refetch): refresh its state, keep its name
+      // unless the payload names it.
+      store.rememberDisplayedEntry(opts.routeName);
       debugLog("[Browser] Store updated (action)");
       handle.complete(parsedUrl);
       return { scroll: false };
@@ -177,6 +190,7 @@ export function createNavigationTransaction(
       if (serverState && Object.keys(serverState).length > 0) {
         mergeLocationState(serverState);
       }
+      store.rememberDisplayedEntry(opts.routeName);
       handle.complete(parsedUrl);
       debugLog("[Browser] Traversal committed, historyKey:", historyKey);
       return { scroll };
@@ -192,6 +206,7 @@ export function createNavigationTransaction(
 
     pushHistoryWithIdx(historyState, url, replace ?? false);
     ensureHistoryKey();
+    store.rememberDisplayedEntry(opts.routeName);
 
     if (hasLocationState(oldState) || hasLocationState(historyState)) {
       window.dispatchEvent(new Event("__rsc_locationstate"));
@@ -219,6 +234,10 @@ export function createNavigationTransaction(
         get currentUrl() {
           return currentUrl;
         },
+        replace: opts.replace,
+        traversal: opts.traversal,
+        state: opts.state,
+        transitionGatedOff: opts.transitionGatedOff,
         startStreaming() {
           return handle.startStreaming();
         },
@@ -249,6 +268,7 @@ export function createNavigationTransaction(
             interceptSourceUrl,
             cacheOnly,
             serverState,
+            routeName: overrides?.routeName ?? opts.routeName,
           });
         },
       };

package/src/browser/partial-update.ts

@@ -36,6 +36,13 @@ import {
   collectClientRevalidationDecisions,
   setActiveInterceptTargets,
 } from "../client-urls/navigation.js";
+import {
+  decideCommitGatedOff,
+  mergeSegmentParams,
+  type TransitionWhenActionInput,
+} from "./transition-when.js";
+import { buildHistoryState } from "./history-state.js";
+import type { TransitionWhenKind } from "../types/segments.js";
 
 function toScrollPayload(
   scroll: boolean | undefined,
@@ -43,9 +50,16 @@ function toScrollPayload(
   return { enabled: scroll !== false ? scroll : false };
 }
 
+/**
+ * Hold/animate decision for a commit: a non-intercept segment carries a
+ * transition, no intercept is presented, and this navigation's
+ * transition({ when }) decision did not gate it off.
+ */
 export function shouldStartViewTransition(
-  segments: ResolvedSegment[],
+  segments: readonly ResolvedSegment[],
+  transitionGatedOff: boolean = false,
 ): boolean {
+  if (transitionGatedOff) return false;
   let hasIntercept = false;
   let hasTransition = false;
   for (const s of segments) {
@@ -107,6 +121,8 @@ export interface CommitOverrides {
   interceptSourceUrl?: string;
   /** 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;
 }
 
 /**
@@ -132,10 +148,21 @@ export type UpdateMode =
        * boundaries do not animate the identical repaint.
        */
       optimisticPresented?: boolean;
+      /**
+       * A router.refresh() (or cross-tab refresh) of the current URL:
+       * transition({ when }) sees kind "revalidate", not "replace".
+       */
+      refresh?: boolean;
     }
   | { type: "leave-intercept"; interceptSourceUrl?: string }
   | { type: "stale-revalidation"; interceptSourceUrl?: string }
-  | { type: "action"; interceptSourceUrl?: string; actionId?: string };
+  | {
+      type: "action";
+      interceptSourceUrl?: string;
+      actionId?: string;
+      /** The action's FormData and result, for transition({ when }) `action`. */
+      action?: TransitionWhenActionInput;
+    };
 
 /**
  * Type for the fetchPartialUpdate function
@@ -213,6 +240,54 @@ export function createPartialUpdater(
       }
     }
 
+    // transition({ when }). Every decision below runs before tx.commit()
+    // moves the store, so `from` is still the location being left:
+    // segmentState.currentUrl is the committed URL even on a popstate cache
+    // miss, where tx.currentUrl and window.location already point at the
+    // target.
+    const whenKind: TransitionWhenKind =
+      mode.type === "action"
+        ? "action"
+        : mode.type === "stale-revalidation" ||
+            (mode.type === "navigate" && mode.refresh)
+          ? "revalidate"
+          : tx.traversal
+            ? "pop"
+            : tx.replace
+              ? "replace"
+              : "push";
+    // Decide once per navigation (browser/transition-when.ts): reuse the
+    // decision the optimistic clientUrls() swap made; otherwise decide over
+    // every segment this commit presents, kept or re-sent (#989). The
+    // destination state is what the commit will leave on the entry.
+    const decideGatedOff = (
+      segmentsToCommit: readonly ResolvedSegment[],
+      metadata: {
+        params?: Record<string, string>;
+        routeName?: string;
+        locationState?: Record<string, unknown>;
+      },
+    ): boolean =>
+      tx.transitionGatedOff ??
+      // A stale revalidation the user navigated away from is discarded after
+      // the render (history-key check below): its predicate must not run.
+      ((mode.type === "stale-revalidation" &&
+        store.getHistoryKey() !== historyKeyAtStart) ||
+        decideCommitGatedOff(store, segmentsToCommit, whenKind, {
+          to: () => ({
+            url,
+            params: metadata.params ?? mergeSegmentParams(segmentsToCommit),
+            routeName: metadata.routeName,
+            state: tx.traversal
+              ? { ...window.history.state, ...metadata.locationState }
+              : buildHistoryState(tx.state, undefined, metadata.locationState),
+          }),
+          action:
+            mode.type === "action"
+              ? { ...mode.action, id: mode.actionId }
+              : undefined,
+        }));
+
     const targetCache =
       mode.type === "navigate" && mode.targetCacheSegments?.length
         ? mode.targetCacheSegments
@@ -349,13 +424,19 @@ export function createPartialUpdater(
             "[Browser] No diff but navigating with cached segments - rendering target route",
           );
 
+          const cachedGatedOff = decideGatedOff(
+            existingSegments,
+            payload.metadata,
+          );
           const newTree = await renderSegments(existingSegments, {
             forceAwait: true,
+            transitionGatedOff: cachedGatedOff,
           });
 
           const { scroll: commitScroll } = tx.commit(
             matchedIds,
             existingSegments,
+            { routeName: payload.metadata.routeName },
           );
 
           if (mode.targetCacheHandleData) {
@@ -376,7 +457,7 @@ export function createPartialUpdater(
             scroll: toScrollPayload(commitScroll),
           };
 
-          if (shouldStartViewTransition(existingSegments)) {
+          if (shouldStartViewTransition(existingSegments, cachedGatedOff)) {
             commitInTransition(onUpdate, existingSegments, cachedUpdate, [
               "navigation",
             ]);
@@ -400,6 +481,7 @@ export function createPartialUpdater(
           const { scroll: leaveScroll } = tx.commit(
             matchedIds,
             existingSegments,
+            { routeName: payload.metadata.routeName },
           );
 
           onUpdate({
@@ -415,7 +497,9 @@ export function createPartialUpdater(
         debugLog(
           "[Browser] No changes - all revalidations returned false, keeping existing UI",
         );
-        tx.commit(matchedIds, existingSegments);
+        tx.commit(matchedIds, existingSegments, {
+          routeName: payload.metadata.routeName,
+        });
         debugLog("[Browser] Navigation complete (no re-render)");
         return;
       }
@@ -477,7 +561,13 @@ export function createPartialUpdater(
         return;
       }
 
+      // Decide before the tree is built: on a gated-off commit every segment
+      // keeps its <ViewTransition> with "none" classes, so the decision must
+      // reach renderSegments. The response carries no decision, so a reused
+      // prefetch is decided against the real source.
+      const gatedOff = decideGatedOff(reconciled.segments, payload.metadata);
       const renderOptions = {
+        transitionGatedOff: gatedOff,
         isAction: mode.type === "action",
         // forceAwait unwraps the ROUTER loader promises during render so they
         // land without a loading()/fallback frame. A fully-prefetched nav has
@@ -557,16 +647,15 @@ export function createPartialUpdater(
 
       const allSegmentIds = matchedIds;
       const serverLocationState = payload.metadata?.locationState;
-      const overrides: CommitOverrides | undefined = isInterceptResponse
-        ? {
-            scroll: false,
-            intercept: true,
-            interceptSourceUrl: effectiveInterceptSource,
-            ...(serverLocationState && { serverState: serverLocationState }),
-          }
-        : serverLocationState
-          ? { serverState: serverLocationState }
-          : undefined;
+      const overrides: CommitOverrides = {
+        routeName: payload.metadata?.routeName,
+        ...(isInterceptResponse && {
+          scroll: false,
+          intercept: true,
+          interceptSourceUrl: effectiveInterceptSource,
+        }),
+        ...(serverLocationState && { serverState: serverLocationState }),
+      };
       const { scroll: navScroll } = tx.commit(
         allSegmentIds,
         reconciled.segments,
@@ -585,7 +674,10 @@ export function createPartialUpdater(
 
       debugLog("[partial-update] updating document");
 
-      const hasTransition = shouldStartViewTransition(reconciled.segments);
+      const hasTransition = shouldStartViewTransition(
+        reconciled.segments,
+        gatedOff,
+      );
       const optimisticPresented =
         mode.type === "navigate" && mode.optimisticPresented === true;
       // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. Reports which reconciled
@@ -600,6 +692,7 @@ export function createPartialUpdater(
           withTransition: reconciled.segments
             .filter((s) => s.transition)
             .map((s) => s.id),
+          transitionGatedOff: gatedOff,
           all: reconciled.segments.map((s) => s.id),
         });
       }
@@ -617,7 +710,10 @@ export function createPartialUpdater(
         metadata: payload.metadata!,
         scroll: scrollPayload,
       };
-      if (mode.type === "action" || mode.type === "stale-revalidation") {
+      if (
+        !gatedOff &&
+        (mode.type === "action" || mode.type === "stale-revalidation")
+      ) {
         commitInTransition(
           onUpdate,
           reconciled.mainSegments,
@@ -633,7 +729,10 @@ export function createPartialUpdater(
             ? ["navigation", OPTIMISTIC_COMMIT_TRANSITION_TYPE]
             : ["navigation"],
         );
-      } else if (fullyPrefetched || isSameStructureNav || optimisticPresented) {
+      } else if (
+        !gatedOff &&
+        (fullyPrefetched || isSameStructureNav || optimisticPresented)
+      ) {
         // Content-hold commit, two triggers. Fully-prefetched nav: the payload
         // is fully resolved (forceAwait above), so the transition commits
         // synchronously — no fallback flash. Same-structure nav: the re-run
@@ -663,10 +762,14 @@ export function createPartialUpdater(
           optimisticPresented ? [OPTIMISTIC_COMMIT_TRANSITION_TYPE] : [],
         );
       } else {
-        // Cold/partially-prefetched nav that mounts NEW segments: normal
-        // commit so fallbacks stream like a first load and the click has
-        // visible feedback. Explicit transition() routes keep the
-        // content-hold via the hasTransition branch above (the opt-in).
+        // 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).
         onUpdate(update);
       }
 
@@ -684,7 +787,10 @@ export function createPartialUpdater(
 
       const segmentIds = segments.map((s: ResolvedSegment) => s.id);
 
-      const newTree = await renderSegments(segments);
+      const fullGatedOff = decideGatedOff(segments, payload.metadata ?? {});
+      const newTree = await renderSegments(segments, {
+        transitionGatedOff: fullGatedOff,
+      });
 
       if (signal?.aborted) {
         debugLog("[Browser] Ignoring stale navigation (aborted before commit)");
@@ -692,13 +798,15 @@ export function createPartialUpdater(
       }
 
       const fullUpdateServerState = payload.metadata?.locationState;
-      const { scroll: fullScroll } = fullUpdateServerState
-        ? tx.commit(segmentIds, segments, {
-            serverState: fullUpdateServerState,
-          })
-        : tx.commit(segmentIds, segments);
+      const { scroll: fullScroll } = tx.commit(segmentIds, segments, {
+        routeName: payload.metadata?.routeName,
+        ...(fullUpdateServerState && { serverState: fullUpdateServerState }),
+      });
 
-      const fullHasTransition = shouldStartViewTransition(segments);
+      const fullHasTransition = shouldStartViewTransition(
+        segments,
+        fullGatedOff,
+      );
       const fullScrollPayload = toScrollPayload(fullScroll);
       const fullUpdate: NavigationUpdate = {
         root: newTree,
@@ -720,13 +828,16 @@ export function createPartialUpdater(
           );
           return;
         }
-        commitInTransition(
-          onUpdate,
-          segments,
-          fullUpdate,
-          fullHasTransition ? ["action"] : [],
-        );
-      } else if (mode.type === "action") {
+        if (fullGatedOff) onUpdate(fullUpdate);
+        else {
+          commitInTransition(
+            onUpdate,
+            segments,
+            fullUpdate,
+            fullHasTransition ? ["action"] : [],
+          );
+        }
+      } else if (mode.type === "action" && !fullGatedOff) {
         commitInTransition(
           onUpdate,
           segments,

package/src/browser/prefetch/cache.ts

@@ -15,11 +15,11 @@
  * - Source-scoped: built by `buildSourceKey(rangoState, sourceHref, target)`
  *   — shape `rangoState\0sourceHref\0/target?...`. Embeds the Rango state
  *   (so rotation invalidates source-scoped entries too), the source href, and
- *   the exact source segment tree. Populated when the
- *   server tags a response with `X-RSC-Prefetch-Scope: source` (intercept
- *   modals etc.), OR when a Link opts in with `prefetchKey=":source"` — in
- *   both cases so source-sensitive responses cannot bleed into navigations
- *   from other pages.
+ *   the exact source segment tree. Populated when the server tags a
+ *   response with `X-RSC-Prefetch-Scope: source` (a route an intercept
+ *   targets, matched or not), OR when a Link opts in with
+ *   `prefetchKey=":source"` — in both cases so source-sensitive responses
+ *   cannot bleed into navigations from other pages.
  *
  * Also tracks in-flight prefetch promises. Each promise resolves to the
  * decoded prefetch entry (or null), letting navigation adopt a
@@ -172,7 +172,7 @@ let generation = 0;
  *   rotation invalidates source-scoped entries alongside wildcard ones,
  *   plus the source page href so the key is unique per originating page.
  *   Populated either when the server tags a response with
- *   `X-RSC-Prefetch-Scope: source` (intercept modals, etc.) or when a
+ *   `X-RSC-Prefetch-Scope: source` (a route an intercept targets) or when a
  *   Link opts in via `prefetchKey=":source"`.
  *
  * Source-scoped keys retain `_rsc_segments` because their exact source tree is

package/src/browser/prefetch/fetch.ts

@@ -189,8 +189,8 @@ function buildPrefetchUrl(
  * - Otherwise: dual inflight registration under both `wildcardKey` and
  *   `sourceKey` so same-source navigations adopt directly via their own
  *   source key. Storage key is chosen at response time from the
- *   `X-RSC-Prefetch-Scope` header — `"source"` → `sourceKey` (intercept
- *   modals etc.), anything else → `wildcardKey`. The entry records its scope
+ *   `X-RSC-Prefetch-Scope` header — `"source"` → `sourceKey` (a route an
+ *   intercept targets), anything else → `wildcardKey`. The entry records its scope
  *   so cross-source navigations that adopted via `wildcardKey` can bail out
  *   in `navigation-client.ts` when the adopted entry turns out source-scoped.
  */