@rangojs/router 0.27.0 → 0.28.0

package/src/browser/history-state.ts

@@ -9,6 +9,7 @@ import {
   resolveLocationStateEntries,
   stampLocationState,
 } from "./react/location-state-shared.js";
+import { WIRE } from "../wire-params.js";
 
 /**
  * Check if state is from typed LocationStateEntry[] (has __rsc_ls_ keys)
@@ -137,16 +138,9 @@ 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).
+ * Drop the forced-MISS marker (`WIRE.shellMiss`, rsc/shell-serve.ts) 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
@@ -154,8 +148,8 @@ export const SHELL_MISS_MARKER: string = "_rsc_shell";
  */
 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);
+  if (!url.searchParams.has(WIRE.shellMiss)) return;
+  url.searchParams.delete(WIRE.shellMiss);
   window.history.replaceState(window.history.state, "", url.href);
 }
 

package/src/browser/navigation-bridge.ts

@@ -273,15 +273,18 @@ export function createNavigationBridge(
         targetUrl.pathname === new URL(window.location.href).pathname
       ) {
         // Preserve intercept context from the current history entry so that
-        // popstate uses the correct cache key (:intercept suffix) and restores
-        // the right full-page vs modal semantics.
+        // popstate uses the same cache key and restores the right full-page
+        // vs intercept semantics.
         const currentHistoryState = window.history.state;
         const isIntercept = currentHistoryState?.intercept === true;
         const interceptSourceUrl = isIntercept
           ? currentHistoryState?.sourceUrl
           : undefined;
 
-        const historyKey = generateHistoryKey(url, { intercept: isIntercept });
+        const historyKey = generateHistoryKey(url, {
+          intercept: isIntercept,
+          interceptSource: interceptSourceUrl,
+        });
 
         // Copy current segments to the new history key so back/forward restores instantly.
         // The array itself, not a clone: getPageHistoryKeys reads a shared
@@ -405,12 +408,6 @@ export function createNavigationBridge(
         });
       }
 
-      // Also check if there's an intercept cache entry for this URL
-      // If so, this URL CAN be intercepted, and we shouldn't use the non-intercept cache
-      // because the navigation might result in an intercept (depending on source URL)
-      const interceptHistoryKey = generateHistoryKey(url, { intercept: true });
-      const hasInterceptCache = store.hasHistoryCache(interceptHistoryKey);
-
       // Skip cached SWR for:
       // 1. intercept caches - interception depends on source page context
       // 2. routes that CAN be intercepted - we don't know if this navigation will intercept
@@ -420,10 +417,12 @@ export function createNavigationBridge(
       const hasUsableCache =
         isRestorable(cachedSegments) &&
         !isInterceptOnlyCache(cachedSegments) &&
-        !hasInterceptCache &&
         !isLeavingIntercept &&
         !cached?.stale &&
-        !options?._skipCache;
+        !options?._skipCache &&
+        // A cached intercept entry for this URL (from any source page) means
+        // the navigation might intercept, depending on the source URL.
+        !store.hasInterceptCache(historyKey);
 
       // Forward navigations always await fetchPartialUpdate before rendering,
       // so useNavigation should always report "loading". skipLoadingState is
@@ -664,8 +663,10 @@ export function createNavigationBridge(
       const isLeavingIntercept =
         !isIntercept && currentInterceptSource !== null;
 
-      // Compute history key from URL (with intercept suffix if applicable)
-      const historyKey = generateHistoryKey(url, { intercept: isIntercept });
+      const historyKey = generateHistoryKey(url, {
+        intercept: isIntercept,
+        interceptSource: interceptSourceUrl,
+      });
 
       debugLog(
         "[Browser] Popstate -",

package/src/browser/navigation-client.ts

@@ -38,7 +38,7 @@ import {
   type DecodedPrefetch,
 } from "./prefetch/cache.js";
 import { cancelAllPrefetches } from "./prefetch/loader.js";
-import { FILL_PARAM, STALE_PARAM } from "../prefetch-markers.js";
+import { writePartialParams } from "./wire-protocol.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -103,30 +103,23 @@ export function createNavigationClient(
       }
 
       // Build fetch URL with partial rendering params (used for both
-      // cache key lookup and actual fetch if cache misses)
-      const fetchUrl = new URL(targetUrl, window.location.origin);
-      fetchUrl.searchParams.set("_rsc_partial", "true");
-      fetchUrl.searchParams.set("_rsc_segments", segmentIds.join(","));
-      if (staleRevalidation) {
-        fetchUrl.searchParams.set(STALE_PARAM, "true");
-      }
-      if (version) {
-        fetchUrl.searchParams.set("_rsc_v", version);
-      }
-      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.
-      if (fill) {
-        fetchUrl.searchParams.set(FILL_PARAM, "1");
-      }
+      // cache key lookup and actual fetch if cache misses). The page left's
+      // rewrite target (#1144) is in both prefetch keys, like the params
+      // around it. The fill is 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.
+      const fetchUrl = writePartialParams(
+        new URL(targetUrl, window.location.origin),
+        {
+          segmentIds,
+          emptySegments: "send",
+          stale: staleRevalidation,
+          version,
+          routerId,
+          rewriteTarget,
+          fill,
+        },
+      );
 
       // If the lazy prefetch runtime has not loaded yet, prevent a deferred
       // speculative request from starting after this navigation misses the

package/src/browser/navigation-store.ts

@@ -34,7 +34,7 @@ const HISTORY_ENTRY_MEMORY_SIZE = 200;
 // stale=true means the data may be outdated and should be revalidated on access.
 // navInstance is the monotonic nav-instance token (see navInstance below): it
 // identifies the per-commit visit that owns this entry. generateHistoryKey is
-// URL-only, so A->B->A reuses the same key; the token lets a late async
+// the URL (plus the source page for an intercept), so A->B->A reuses the key; the token lets a late async
 // resolution tell its own visit's entry apart from a newer same-URL visit's, so
 // a stale nav can never clobber a fresher one.
 // handlesPending=true means the entry's handle data is INCOMPLETE (a deferred
@@ -124,36 +124,35 @@ function getCacheInvalidationChannel(): BroadcastChannel | null {
  * Options for generating a history key
  */
 export interface HistoryKeyOptions {
-  /** If true, append :intercept suffix to differentiate intercept entries */
+  /** Key an intercept entry (apart from the plain entry for the URL). */
   intercept?: boolean;
+  /** The page the intercept was opened over (history.state.sourceUrl). */
+  interceptSource?: string;
+}
+
+function urlKey(url: string): string {
+  const parsed = new URL(url, "http://localhost");
+  return parsed.pathname + parsed.search;
 }
 
 /**
- * Generate a cache key from a URL.
- * Uses pathname + search (query params) directly as the key.
- * Hash fragments (#) are excluded since they don't affect server data.
+ * Generate a cache key from a URL: pathname + search. Hash fragments (#) are
+ * excluded since they don't affect server data.
  *
- * For intercept routes, append `:intercept` suffix to cache them separately
- * from non-intercept versions of the same URL.
+ * An intercept entry is keyed `<url>:intercept:<source>`: its cached tree
+ * includes the page under the intercept. hasInterceptCache relies on the
+ * `:intercept:` separator.
  */
 export function generateHistoryKey(
   url?: string,
   options?: HistoryKeyOptions,
 ): string {
-  if (!url) {
-    url = typeof window !== "undefined" ? window.location.href : "/";
-  }
-
-  // Parse URL and use only pathname + search (exclude hash fragment)
-  const parsed = new URL(url, "http://localhost");
-  let key = parsed.pathname + parsed.search;
-
-  // Append intercept suffix for separate caching
-  if (options?.intercept) {
-    key += ":intercept";
-  }
-
-  return key;
+  const key = urlKey(
+    url || (typeof window !== "undefined" ? window.location.href : "/"),
+  );
+  if (!options?.intercept) return key;
+  const source = options.interceptSource;
+  return `${key}:intercept:${source ? urlKey(source) : ""}`;
 }
 
 /**
@@ -258,7 +257,8 @@ export function createNavigationStore(
 
   // Monotonic nav-instance token. Bumped each time a cache entry is created or
   // replaced in cacheSegmentsForHistory (i.e. once per commit). Because
-  // generateHistoryKey is URL-only, two visits to the same URL share a key; this
+  // generateHistoryKey is the URL (plus the source page for an intercept), two
+  // visits to the same URL share a key; this
   // token gives each visit a distinct identity so a late async handle resolution
   // can tell whether it still owns the live page / the target cache entry, and
   // never overwrite a newer same-URL visit's state.
@@ -580,11 +580,9 @@ export function createNavigationStore(
       };
     },
 
-    /**
-     * Check if segments are cached for a history entry
-     */
-    hasHistoryCache(historyKey: string): boolean {
-      return historyCache.some(([key]) => key === historyKey);
+    hasInterceptCache(historyKey: string): boolean {
+      const prefix = `${historyKey}:intercept:`;
+      return historyCache.some(([key]) => key.startsWith(prefix));
     },
 
     /**

package/src/browser/navigation-transaction.ts

@@ -180,7 +180,10 @@ export function createNavigationTransaction(
 
     const parsedUrl = new URL(url, window.location.origin);
 
-    const historyKey = generateHistoryKey(url, { intercept });
+    const historyKey = generateHistoryKey(url, {
+      intercept,
+      interceptSource: interceptSourceUrl,
+    });
 
     if (cacheOnly) {
       const currentHandleData = eventController.getHandleState().data;

package/src/browser/prefetch/cache.ts

@@ -43,6 +43,7 @@ import { abortAllPrefetches } from "./loader.js";
 import { notifyPrefetchCacheInvalidated } from "./invalidation.js";
 import { invalidateRangoState } from "../rango-state.js";
 import type { RscPayload } from "../types.js";
+import { WIRE } from "../../wire-params.js";
 
 /**
  * A prefetch that has been fetched AND eagerly decoded. Storing the decoded
@@ -190,7 +191,7 @@ let generation = 0;
  */
 export function buildPrefetchKey(prefix: string, targetUrl: URL): string {
   const normalizedTarget = new URL(targetUrl);
-  normalizedTarget.searchParams.delete("_rsc_segments");
+  normalizedTarget.searchParams.delete(WIRE.segments);
   return prefix + "\0" + normalizedTarget.pathname + normalizedTarget.search;
 }
 

package/src/browser/prefetch/fetch.ts

@@ -38,6 +38,7 @@ import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../../segment-fragments.js";
 import { PREFETCH_HEADER } from "../../prefetch-markers.js";
 import type { RscPayload } from "../types.js";
 import { getRegisteredStore } from "../navigation-store-handle.js";
+import { writePartialParams } from "../wire-protocol.js";
 
 /**
  * Decoder injected at app startup (see setPrefetchDecoder). This is
@@ -153,24 +154,15 @@ function buildPrefetchUrl(
   if (targetUrl.origin !== window.location.origin) {
     return null;
   }
-  targetUrl.searchParams.set("_rsc_partial", "true");
-  if (segmentIds.length > 0) {
-    targetUrl.searchParams.set("_rsc_segments", segmentIds.join(","));
-  }
-  if (version) {
-    targetUrl.searchParams.set("_rsc_v", version);
-  }
-  if (routerId) {
-    targetUrl.searchParams.set("_rsc_rid", routerId);
-  }
   // The page's rewrite target, so the server diffs against the route that
   // rendered it, as for the navigation.
-  const rewriteTarget =
-    getRegisteredStore()?.getHistoryEntryMemory()?.rewriteTarget;
-  if (rewriteTarget) {
-    targetUrl.searchParams.set("_rsc_rt", rewriteTarget);
-  }
-  return targetUrl;
+  return writePartialParams(targetUrl, {
+    segmentIds,
+    emptySegments: "omit",
+    version,
+    routerId,
+    rewriteTarget: getRegisteredStore()?.getHistoryEntryMemory()?.rewriteTarget,
+  });
 }
 
 /**

package/src/browser/prefetch/queue.ts

@@ -15,6 +15,7 @@
  */
 
 import { wait, waitForIdle, waitForViewportImages } from "./resource-ready.js";
+import { WIRE_PREFIX } from "../../wire-params.js";
 
 // Max prefetches executing at once. Mirrors DEFAULT_PREFETCH_CONCURRENCY
 // (router/prefetch-limits.ts); kept as a local literal so the client bundle
@@ -128,16 +129,15 @@ export function enqueuePrefetch(
 
 /**
  * Normalize a URL-like string for keep-alive matching: parse against a
- * placeholder origin and strip internal `_rsc_*` query params. Returns
+ * placeholder origin and strip every `WIRE_PREFIX` query param. Returns
  * `pathname + search` so comparisons ignore hash and the internal params
- * that prefetch appends to targets (`_rsc_partial`, `_rsc_segments`,
- * `_rsc_v`, `_rsc_rid`, `_rsc_stale`).
+ * that prefetch appends to targets.
  */
 function normalizeForMatch(urlish: string): string {
   try {
     const u = new URL(urlish, "http://placeholder");
     for (const k of [...u.searchParams.keys()]) {
-      if (k.startsWith("_rsc_")) u.searchParams.delete(k);
+      if (k.startsWith(WIRE_PREFIX)) u.searchParams.delete(k);
     }
     return u.pathname + u.search;
   } catch {

package/src/browser/react/NavigationProvider.tsx

@@ -78,7 +78,8 @@ async function processHandles(
 
   // This nav's instance token, captured before any await — processHandles runs
   // right after its own commit, so this is that commit's token. generateHistoryKey
-  // is URL-only, so an A->B->A revisit reuses the key; the token lets a late
+  // is the URL (plus the source page for an intercept), so an A->B->A revisit
+  // reuses the key; the token lets a late
   // resolution tell its own visit apart from a newer same-URL visit, so a stale
   // nav can never clobber a fresher one's live state or cache (P1).
   const myInstance = store.getNavInstance();

package/src/browser/react/filter-segment-order.ts

@@ -33,8 +33,8 @@ export function loaderParentId(id: string): string {
  * 2. Place each parallel slot id (contains ".@") immediately after its
  *    parent layout/route id. Raw segment-resolution emission order does NOT
  *    guarantee this: route-mounted parallels are resolved/pushed BEFORE the
- *    route handler's segment is appended (see fresh.ts:resolveSegment for
- *    routes, and revalidation.ts ~915-919), so matched can read
+ *    route handler's segment is appended (see resolveSegment in
+ *    segment-resolution/revalidation.ts), so matched can read
  *    `[..., R0.@panel, R0]`. collectHandleData consumes segmentOrder verbatim
  *    with later-wins semantics, so without normalization the route handler's
  *    Meta would override the slot's more-specific Meta — backwards.

package/src/browser/rsc-router.tsx

@@ -614,6 +614,7 @@ export async function initBrowserApp(
 
             const historyKey = generateHistoryKey(window.location.href, {
               intercept: responseIsIntercept,
+              interceptSource: interceptSourceUrl ?? undefined,
             });
             store.setHistoryKey(historyKey);
             const currentHandleData = liveHandleDataForCache(

package/src/browser/segment-reconciler.ts

@@ -46,6 +46,60 @@ export interface ReconcileResult {
   interceptSegments: ResolvedSegment[];
 }
 
+/**
+ * A segment the server sent over its cached copy, keeping the cached
+ * structural properties so the React tree keeps its shape. Changing them
+ * between renders alters the element nesting (with/without
+ * RouteContentWrapper, MountContextProvider, etc.), which remounts components
+ * and destroys useActionState.
+ */
+function mergeCached(
+  fromServer: ResolvedSegment,
+  fromCache: ResolvedSegment,
+  actor: ReconcileActor,
+): ResolvedSegment {
+  let merged = fromServer;
+
+  // When server returns component: null for a layout segment, it means
+  // "this segment doesn't need re-rendering" - preserve the cached component
+  // to maintain the outlet chain and prevent React tree changes
+  if (
+    fromServer.component === null &&
+    fromServer.type === "layout" &&
+    fromCache.component != null
+  ) {
+    merged = { ...merged, component: fromCache.component };
+  }
+
+  // Loading preservation is actor-aware:
+  // - action/stale-revalidation: always preserve cached value to prevent
+  //   tree remount (even when cached is undefined, to avoid adding a
+  //   Suspense boundary that wasn't there before)
+  // - navigation: only when cached is defined (building a new tree)
+  if (
+    fromServer.loading !== fromCache.loading &&
+    (actor !== "navigation" || fromCache.loading !== undefined)
+  ) {
+    merged = { ...merged, loading: fromCache.loading };
+  }
+
+  // mountPath: SSR segments may lack mountPath while revalidated segments
+  // include it. The conditional MountContextProvider wrapper changes tree depth.
+  if (fromServer.mountPath !== fromCache.mountPath) {
+    merged = { ...merged, mountPath: fromCache.mountPath };
+  }
+
+  // Dev-mode assertion: warn if the merged result still differs from cache
+  // in tree-structural properties. This catches bugs where the merge code
+  // above fails to preserve a value it should have.
+  assertSegmentStructure(
+    fromCache,
+    merged,
+    actor === "action" ? "action-bridge" : "partial-update",
+  );
+  return merged;
+}
+
 /**
  * Single source of truth for merging server segments with cached segments.
  *
@@ -70,7 +124,6 @@ export interface ReconcileResult {
  */
 export function reconcileSegments(input: ReconcileInput): ReconcileResult {
   const { actor, matched, diff, insertMissingDiff } = input;
-  const context = actor === "action" ? "action-bridge" : "partial-update";
 
   // Build lookup maps from arrays
   const serverSegments = new Map<string, ResolvedSegment>();
@@ -111,59 +164,13 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
 
       if (fromServer) {
         const inDiff = diffSet.has(segId);
-        // Preserve cached structural properties to maintain consistent React tree.
-        // Changing these between renders alters the element nesting
-        // (with/without RouteContentWrapper, MountContextProvider, etc.),
-        // causing React to remount components and destroy useActionState.
         if (fromCache) {
-          let merged = fromServer;
-
-          // When server returns component: null for a layout segment, it means
-          // "this segment doesn't need re-rendering" - preserve the cached component
-          // to maintain the outlet chain and prevent React tree changes
-          if (
-            fromServer.component === null &&
-            fromServer.type === "layout" &&
-            fromCache.component != null
-          ) {
-            merged = { ...merged, component: fromCache.component };
-          }
-
-          // Loading preservation is actor-aware:
-          // - action/stale-revalidation: always preserve cached value to prevent
-          //   tree remount (even when cached is undefined, to avoid adding a
-          //   Suspense boundary that wasn't there before)
-          // - navigation: only when cached is defined (building a new tree)
-          if (actor !== "navigation") {
-            if (fromServer.loading !== fromCache.loading) {
-              merged = { ...merged, loading: fromCache.loading };
-            }
-          } else {
-            if (
-              fromCache.loading !== undefined &&
-              fromServer.loading !== fromCache.loading
-            ) {
-              merged = { ...merged, loading: fromCache.loading };
-            }
-          }
-
-          // mountPath: SSR segments may lack mountPath while revalidated segments
-          // include it. The conditional MountContextProvider wrapper changes tree depth.
-          if (fromServer.mountPath !== fromCache.mountPath) {
-            merged = { ...merged, mountPath: fromCache.mountPath };
-          }
-
-          // Dev-mode assertion: warn if the merged result still differs from cache
-          // in tree-structural properties. This catches bugs where the merge code
-          // above fails to preserve a value it should have.
-          assertSegmentStructure(fromCache, merged, context);
-
           if (IS_BROWSER_DEBUG) {
             debugLog(
               `[reconcile] ${segId}: SERVER+CACHE merge (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, component=${fromServer.component === null ? "null→cached" : "server"})`,
             );
           }
-          return merged;
+          return mergeCached(fromServer, fromCache, actor);
         }
         if (IS_BROWSER_DEBUG) {
           debugLog(
@@ -221,11 +228,13 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
 }
 
 /**
- * Reconcile error segments with cached segments.
+ * Reconcile an error-boundary response with cached segments.
  *
- * For error responses, the server returns the error boundary segment.
- * This function overlays error segments onto the full cached tree,
- * preserving sibling layouts that aren't in the error parent chain.
+ * The server returns the error boundary segment and, above it, what the
+ * action's revalidation re-ran (rsc/server-action.ts). This function overlays
+ * them onto the full cached tree, preserving sibling layouts that aren't in
+ * the error parent chain. The error segment replaces its cached copy; every
+ * other segment merges as an action's does (mergeCached).
  */
 export function reconcileErrorSegments(
   cachedSegments: ResolvedSegment[],
@@ -236,7 +245,11 @@ export function reconcileErrorSegments(
 
   const segments = cachedSegments.map((cached) => {
     const fromServer = errorMap.get(cached.id);
-    return fromServer || cached;
+    return !fromServer
+      ? cached
+      : fromServer.type === "error"
+        ? fromServer
+        : mergeCached(fromServer, cached, "action");
   });
 
   const { main, intercept } = splitInterceptSegments(segments);