@rangojs/router 0.17.0 → 0.19.0

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.
  */

package/src/browser/react/Link.tsx

@@ -13,30 +13,23 @@ import React, {
 } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { LinkContext } from "./use-link-status.js";
-import type { NavigateOptions } from "../types.js";
+import type { HistoryState } from "../types.js";
 import {
   isHashOnlyNavigation,
   isPrefetchScopeDisabled,
   subscribeToPrefetchScopeChange,
 } from "../link-interceptor.js";
 import { subscribeToLocationChange } from "../event-controller.js";
-import {
-  isLocationStateEntry,
-  type LocationStateEntry,
-  resolveLocationStateEntries,
-} from "./location-state.js";
+import { isLocationStateDefinition } from "./location-state-shared.js";
 
-/**
- * State prop type for Link component.
- * - LocationStateEntry[]: Type-safe state entries via createLocationState()
- * - StateOrGetter: Plain state object or click-time getter function
- * - Record<string, unknown>: Plain state object passed to history.pushState
- */
 export type StateOrGetter<T = unknown> = T | (() => T);
 
-export type LinkState =
-  | LocationStateEntry[]
-  | StateOrGetter<Record<string, unknown>>;
+/**
+ * State prop type for Link component: the `router.push()` state type
+ * ({@link HistoryState}: `LocationStateEntry[]` from createLocationState(), or
+ * plain structured-clone-safe state), or a getter for it called at click time.
+ */
+export type LinkState = StateOrGetter<HistoryState>;
 
 import {
   prefetchDirect,
@@ -93,6 +86,14 @@ export interface LinkProps extends Omit<
    * @default true
    */
   revalidate?: boolean;
+  /**
+   * Set to `false` to present this navigation without a transition (urgent
+   * commit, `<ViewTransition>` classes `"none"`); no `transition({ when })`
+   * predicate is called. See `NavigateOptions.transition`.
+   *
+   * @default true
+   */
+  transition?: boolean;
   /**
    * Prefetch strategy for the link destination. When omitted, falls back to
    * the router-wide default (`createRouter({ defaultPrefetch })`: `"none"` in
@@ -118,8 +119,11 @@ export interface LinkProps extends Omit<
    * therefore serve the wrong diff to a navigation from a different
    * source.
    *
-   * Intercept responses are auto-scoped to the source via a server-side
-   * tag, so `":source"` is only needed for custom revalidation logic.
+   * A route an intercept targets is scoped to the source automatically
+   * (server-side `x-rsc-prefetch-scope: source`), whether or not the
+   * intercept applies from this page: the modal and the full page are
+   * both source-specific. Every other route stays shared, so `":source"`
+   * is only needed for custom revalidation logic.
    *
    * @example
    * ```tsx
@@ -226,6 +230,7 @@ export const Link: ForwardRefExoticComponent<
     scroll = true,
     reloadDocument = false,
     revalidate,
+    transition,
     prefetch,
     prefetchKey,
     state,
@@ -334,28 +339,26 @@ export const Link: ForwardRefExoticComponent<
       // Stop propagation to prevent link-interceptor from also handling this
       e.stopPropagation();
 
+      // Call a click-time getter; typed entries are resolved (and, in dev,
+      // checked) by the bridge's resolveNavigationState, like router.push().
+      // In dev an uncalled definition passes through to that check instead of
+      // being called as a getter.
       const currentState = stateRef.current;
-      let resolvedState: unknown;
-
-      if (
-        Array.isArray(currentState) &&
-        currentState.length > 0 &&
-        isLocationStateEntry(currentState[0])
-      ) {
-        resolvedState = resolveLocationStateEntries(
-          currentState as LocationStateEntry[],
-        );
-      } else if (typeof currentState === "function") {
-        resolvedState = currentState();
-      } else if (currentState != null) {
-        resolvedState = currentState;
-      }
+      const state =
+        typeof currentState === "function" &&
+        !(
+          process.env.NODE_ENV !== "production" &&
+          isLocationStateDefinition(currentState)
+        )
+          ? currentState()
+          : (currentState ?? undefined);
 
       ctx.navigate(resolvedTo, {
         replace,
         scroll,
-        state: resolvedState,
+        state,
         revalidate,
+        transition,
       });
     },
     [
@@ -365,6 +368,7 @@ export const Link: ForwardRefExoticComponent<
       replace,
       scroll,
       revalidate,
+      transition,
       ctx,
       onClick,
     ],
@@ -487,6 +491,7 @@ export const Link: ForwardRefExoticComponent<
       data-scroll={scroll === false ? "false" : undefined}
       data-replace={replace ? "true" : undefined}
       data-revalidate={revalidate === false ? "false" : undefined}
+      data-transition={transition === false ? "false" : undefined}
       {...props}
     >
       <LinkContext.Provider value={resolvedTo}>{children}</LinkContext.Provider>

package/src/browser/react/NavigationProvider.tsx

@@ -17,7 +17,7 @@ import {
 import type {
   NavigationStore,
   NavigationUpdate,
-  NavigateOptions,
+  NavigateOptionsInternal,
   NavigationBridge,
 } from "../types.js";
 import type { EventController } from "../event-controller.js";
@@ -320,7 +320,7 @@ export function NavigationProvider({
    * Navigate to a URL (delegates to bridge)
    */
   const navigate = useCallback(
-    async (url: string, options?: NavigateOptions): Promise<void> => {
+    async (url: string, options?: NavigateOptionsInternal): Promise<void> => {
       await bridge.navigate(url, options);
     },
     [],

package/src/browser/react/context.ts

@@ -1,7 +1,7 @@
 "use client";
 
 import { createContext, type Context } from "react";
-import type { NavigationStore, NavigateOptions } from "../types.js";
+import type { NavigationStore, NavigateOptionsInternal } from "../types.js";
 import type { EventController } from "../event-controller.js";
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 
@@ -34,7 +34,7 @@ export interface NavigationStoreContextValue {
    * @param options - Navigation options (replace, scroll)
    * @returns Promise that resolves when navigation is complete
    */
-  navigate: (url: string, options?: NavigateOptions) => Promise<void>;
+  navigate: (url: string, options?: NavigateOptionsInternal) => Promise<void>;
 
   /**
    * Refresh the current route