@rangojs/router 0.17.0 → 0.19.0

package/src/browser/cookie-name.ts

@@ -14,6 +14,29 @@
 /** Default prefix when `stateCookiePrefix` is unset or empty after sanitization. */
 export const DEFAULT_STATE_COOKIE_PREFIX = "rango-state";
 
+/**
+ * The fresh-reads cookie: the state cookie PREFIX plus this suffix
+ * (`rango-state-fresh` by default). A response whose request ran
+ * updateTag()/revalidateTag() sets it (HttpOnly, SameSite=Lax, Path=/,
+ * Max-Age = the stores' longest memo staleness), and the same user's requests
+ * carrying it skip the stores' isolate memos (src/cache/isolate-tag-memo.ts).
+ * Keyed by prefix, not by router, so a mutation through one router also
+ * reaches the memos another router on the host reads (they often share a
+ * store); a router with its own `stateCookiePrefix` gets its own cookie.
+ */
+const FRESH_READS_COOKIE_SUFFIX = "-fresh";
+
+/**
+ * The fresh-reads cookie name for a router's resolved state cookie name
+ * (`{prefix}_{routerId}`; the prefix never contains `_`, see
+ * router/state-cookie-name.ts).
+ */
+export function freshReadsCookieName(stateCookieName: string): string {
+  const cut = stateCookieName.indexOf("_");
+  const prefix = cut < 0 ? stateCookieName : stateCookieName.slice(0, cut);
+  return `${prefix}${FRESH_READS_COOKIE_SUFFIX}`;
+}
+
 /** Internal response header carrying the keepClientCache() directive. */
 export const KEEP_CACHE_HEADER = "x-rango-keep-cache";
 

package/src/browser/event-controller.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 import type {
   NavigationLocation,
-  NavigateOptions,
+  NavigateOptionsInternal,
   TrackedActionState,
   ActionLifecycleState,
   InflightAction,
@@ -46,7 +46,7 @@ export interface NavigationEntry {
   abort: AbortController;
   phase: NavigationPhase;
   startedAt: number;
-  options?: NavigateOptions & { skipLoadingState?: boolean };
+  options?: NavigateOptionsInternal & { skipLoadingState?: boolean };
 }
 
 /**
@@ -206,7 +206,7 @@ export interface EventController {
   // Navigation operations
   startNavigation(
     url: string,
-    options?: NavigateOptions & { skipLoadingState?: boolean },
+    options?: NavigateOptionsInternal & { skipLoadingState?: boolean },
   ): NavigationHandle;
   abortNavigation(): void;
 
@@ -632,7 +632,7 @@ export function createEventController(
 
   function startNavigation(
     url: string,
-    options?: NavigateOptions & { skipLoadingState?: boolean },
+    options?: NavigateOptionsInternal & { skipLoadingState?: boolean },
   ): NavigationHandle {
     // Cancel existing navigation (switchMap semantics)
     if (currentNavigation) {

package/src/browser/history-state.ts

@@ -1,5 +1,8 @@
 import {
+  isLocationStateDefinition,
   isLocationStateEntry,
+  peekLocationStateKey,
+  replaceCurrentHistoryState,
   resolveLocationStateEntries,
 } from "./react/location-state-shared.js";
 
@@ -13,10 +16,49 @@ function isTypedLocationState(
   return Object.keys(state).some((key) => key.startsWith("__rsc_ls_"));
 }
 
+/**
+ * Dev-only guard for the state mistakes `HistoryState` rejects at compile
+ * time, for untyped callers: a typed entry without its array (its `__rsc_ls_*`
+ * fields would be spread onto history.state, so useLocationState reads
+ * undefined), an uncalled definition (pushState throws DataCloneError), and an
+ * array mixing entries with plain values (only `state[0]` picks the format, so
+ * the rest land under history.state["undefined"] or are never read).
+ */
+function assertNavigationState(state: unknown): void {
+  if (isLocationStateEntry(state)) {
+    throw new Error(
+      `[rango] navigation state is a single location-state entry (key "${state.__rsc_ls_key}"). ` +
+        "Wrap it in an array: { state: [MyState(value)] }. " +
+        "Without the array, useLocationState(MyState) reads undefined.",
+    );
+  }
+  const definition = (Array.isArray(state) ? state : [state]).find(
+    isLocationStateDefinition,
+  );
+  if (definition) {
+    throw new Error(
+      `[rango] navigation state contains a location-state definition (key "${peekLocationStateKey(definition) ?? "unset"}") instead of an entry. ` +
+        "Call it with the value: { state: [MyState(value)] }, not [MyState].",
+    );
+  }
+  if (Array.isArray(state) && state.some(isLocationStateEntry)) {
+    const index = state.findIndex((item) => !isLocationStateEntry(item));
+    if (index !== -1) {
+      throw new Error(
+        `[rango] navigation state mixes location-state entries with other values (index ${index}). ` +
+          "Pass only entries ({ state: [MyState(value), Other(value)] }); plain state cannot sit next to typed entries.",
+      );
+    }
+  }
+}
+
 /**
  * Resolve navigation state - handles both LocationStateEntry[] and plain formats
  */
 export function resolveNavigationState(state: unknown): unknown {
+  if (process.env.NODE_ENV !== "production") {
+    assertNavigationState(state);
+  }
   if (
     Array.isArray(state) &&
     state.length > 0 &&
@@ -61,6 +103,15 @@ export function buildHistoryState(
   return Object.keys(result).length > 0 ? result : null;
 }
 
+/** Check if a history state object contains location state keys. */
+export 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_"))
+  );
+}
+
 /**
  * Stamp an `idx` on the next history entry's state and call push/replaceState.
  * Push increments the current idx; replace keeps it. Initial entry idx is 0.
@@ -82,6 +133,29 @@ export function pushHistoryWithIdx(
   }
 }
 
+/**
+ * The forced-MISS reload marker (`SHELL_MISS_PARAM` in rsc/shell-serve.ts,
+ * which the browser bundle must not import): a degraded PPR shell HIT
+ * reloads the page with it, and the server renders a marked request like a
+ * cache miss.
+ */
+export const SHELL_MISS_MARKER: string = "_rsc_shell";
+
+/**
+ * Drop the forced-MISS marker from the address bar at boot, keeping the
+ * history entry's state (initBrowserApp calls it before any location read).
+ * Left in place, a refresh or a shared link would stay off the shell and the
+ * app's search params would carry it. The server strips the same marker from
+ * the request before rendering (shell-serve.ts withoutShellMissMarker), so
+ * the page was rendered for the clean URL and the hydrating client agrees.
+ */
+export function stripShellMissMarker(): void {
+  const url = new URL(window.location.href);
+  if (!url.searchParams.has(SHELL_MISS_MARKER)) return;
+  url.searchParams.delete(SHELL_MISS_MARKER);
+  window.history.replaceState(window.history.state, "", url.href);
+}
+
 /**
  * Merge server-set location state into the current history entry.
  * Replaces the current history state and dispatches notification event
@@ -94,7 +168,7 @@ export function mergeLocationState(
     ...window.history.state,
     ...locationState,
   };
-  window.history.replaceState(merged, "", window.location.href);
+  replaceCurrentHistoryState(merged);
   if (Object.keys(locationState).some((k) => k.startsWith("__rsc_ls_"))) {
     window.dispatchEvent(new Event("__rsc_locationstate"));
   }

package/src/browser/link-interceptor.ts

@@ -334,6 +334,7 @@ export function setupLinkInterception(
     const scrollAttr = link.getAttribute("data-scroll");
     const replaceAttr = link.getAttribute("data-replace");
     const revalidateAttr = link.getAttribute("data-revalidate");
+    const transitionAttr = link.getAttribute("data-transition");
 
     const navigateOptions: NavigateOptions = {};
     if (scrollAttr === "false") {
@@ -345,6 +346,9 @@ export function setupLinkInterception(
     if (revalidateAttr === "false") {
       navigateOptions.revalidate = false;
     }
+    if (transitionAttr === "false") {
+      navigateOptions.transition = false;
+    }
 
     onNavigate(href, navigateOptions);
   };

package/src/browser/navigation-bridge.ts

@@ -14,7 +14,11 @@ import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
-import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
+import {
+  buildHistoryState,
+  hasLocationState,
+  pushHistoryWithIdx,
+} from "./history-state.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -30,7 +34,11 @@ import {
   setupDelegatedLinkPrefetch,
   setupLinkInterception,
 } from "./link-interceptor.js";
-import { createPartialUpdater } from "./partial-update.js";
+import {
+  createPartialUpdater,
+  shouldStartViewTransition,
+} from "./partial-update.js";
+import { decideCommitGatedOff, mergeSegmentParams } from "./transition-when.js";
 import { generateHistoryKey } from "./navigation-store.js";
 import type { EventController } from "./event-controller.js";
 import { isInterceptOnlyCache } from "./intercept-utils.js";
@@ -214,6 +222,7 @@ export function createNavigationBridge(
 
         // Snapshot old state before pushState/replaceState overwrites it
         const oldState = window.history.state;
+        const shallowRouteName = store.getHistoryEntryMemory()?.routeName;
 
         // Update browser URL (carry intercept context into history state)
         const historyState = buildHistoryState(
@@ -228,18 +237,11 @@ 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);
 
         // Notify useLocationState() hooks when state changes
-        const hasOldState =
-          oldState &&
-          typeof oldState === "object" &&
-          ("state" in oldState ||
-            Object.keys(oldState).some((k) => k.startsWith("__rsc_ls_")));
-        const hasNewState =
-          historyState &&
-          ("state" in historyState ||
-            Object.keys(historyState).some((k) => k.startsWith("__rsc_ls_")));
-        if (hasOldState || hasNewState) {
+        if (hasLocationState(oldState) || hasLocationState(historyState)) {
           window.dispatchEvent(new Event("__rsc_locationstate"));
         }
 
@@ -344,9 +346,44 @@ export function createNavigationBridge(
         state: resolvedState,
         skipLoadingState: false,
       });
+      // A cross-route clientUrls() navigation presents its destination
+      // optimistically at once: transition({ when }) decides THERE (the first
+      // presentation), over the destination route's predicate and those of
+      // the segments the navigation keeps (everything outside the group's
+      // route segment), and the canonical commit reuses the decision.
+      // `transition: false` gates the navigation off without calling any
+      // predicate, on both the optimistic swap and the canonical commit.
+      const transitionOptOut = options?.transition === false;
       const clientUrlPresentation = beginClientUrlNavigation(
         targetUrl,
         tx.handle.signal,
+        transitionOptOut
+          ? () => true
+          : (destination) =>
+              decideCommitGatedOff(
+                store,
+                (
+                  store.getCachedSegments(store.getHistoryKey())?.segments ?? []
+                ).filter((segment) => segment.clientGroup === undefined),
+                options?.replace ? "replace" : "push",
+                {
+                  to: (from) => {
+                    // Mount (include prefix) params carry over; the origin
+                    // route's own params do not.
+                    const params = { ...from.params };
+                    for (const name of destination.originLocalParamNames) {
+                      delete params[name];
+                    }
+                    return {
+                      url: targetUrl,
+                      params: { ...params, ...destination.params },
+                      routeName: destination.routeName,
+                      state: buildHistoryState(resolvedState),
+                    };
+                  },
+                  extra: destination.when,
+                },
+              ),
       );
 
       // REVALIDATE: Fetch fresh data from server
@@ -365,6 +402,9 @@ export function createNavigationBridge(
             replace: options?.replace,
             scroll: options?.scroll,
             state: resolvedState,
+            transitionGatedOff: transitionOptOut
+              ? true
+              : clientUrlPresentation?.transitionGatedOff,
           }),
           isLeavingIntercept
             ? { type: "leave-intercept" as const }
@@ -394,6 +434,7 @@ export function createNavigationBridge(
           return this.navigate(redirectUrl, {
             state: error.state,
             replace: options?.replace,
+            transition: options?.transition,
             _skipCache: true,
           } as NavigateOptionsInternal);
         }
@@ -457,6 +498,7 @@ export function createNavigationBridge(
           false,
           tx.handle.signal,
           tx.with({ url: window.location.href, replace: true, scroll: false }),
+          { type: "navigate", refresh: true },
         );
       } catch (error) {
         // Aborted or superseded: bail without rendering a boundary (see navigate()).
@@ -567,6 +609,26 @@ export function createNavigationBridge(
       const isStale = (cached?.stale ?? false) || isActionFenceActive();
 
       if (cachedSegments && cachedSegments.length > 0) {
+        // transition({ when }) decides the restore (kind "pop") against the
+        // entry being left, so before the store moves to the restored entry.
+        // The decision the entry was committed with is not reused: it was
+        // made for a different source. A restore that opens or closes an
+        // intercept never holds or animates (hasTransition below), so it is
+        // not decided, like every intercept commit.
+        const cachedParams = mergeSegmentParams(cachedSegments);
+        const gatedOff =
+          !isIntercept &&
+          !isLeavingIntercept &&
+          decideCommitGatedOff(store, cachedSegments, "pop", {
+            to: () => ({
+              url,
+              params: cachedParams,
+              routeName: store.getHistoryEntryMemory(historyState?.key)
+                ?.routeName,
+              state: historyState,
+            }),
+          });
+
         // Update store to point to this history entry
         store.setHistoryKey(historyKey);
         store.setSegmentIds(cachedSegments.map((s) => s.id));
@@ -583,14 +645,11 @@ export function createNavigationBridge(
         try {
           const root = await renderSegments(cachedSegments, {
             forceAwait: true,
+            transitionGatedOff: gatedOff,
           });
-          // Merge params from cached segments for useParams restoration.
+          store.rememberDisplayedEntry();
           // Set params on event controller before onUpdate so both location
           // and params are current when the debounced notify() fires.
-          const cachedParams: Record<string, string> = {};
-          for (const s of cachedSegments) {
-            if (s.params) Object.assign(cachedParams, s.params);
-          }
           eventController.setParams(cachedParams);
 
           const popstateUpdate = {
@@ -613,7 +672,7 @@ export function createNavigationBridge(
           const hasTransition =
             !isIntercept &&
             !isLeavingIntercept &&
-            cachedSegments.some((s) => s.transition);
+            shouldStartViewTransition(cachedSegments, gatedOff);
           if (hasTransition) {
             startTransition(() => {
               if (addTransitionType) {

package/src/browser/navigation-client.ts

@@ -122,9 +122,10 @@ export function createNavigationClient(
 
       // Check completed in-memory prefetch cache before making a network
       // request. Try the source-scoped key first (populated when the server
-      // tagged the prefetch response as source-sensitive, e.g. intercepts,
-      // or when a Link opted in with `prefetchKey=":source"`), then fall
-      // back to the wildcard slot shared across source pages.
+      // tagged the prefetch response as source-sensitive, e.g. a route an
+      // intercept targets, or when a Link opted in with
+      // `prefetchKey=":source"`), then fall back to the wildcard slot shared
+      // across source pages.
       // Both keys embed the Rango state, so state rotation (deploy or
       // server-action invalidation) auto-invalidates both scopes.
       // Skip cache for stale revalidation (needs fresh data), HMR (needs

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,
           });
         },
       };