@rangojs/router 0.0.0-experimental.d7eeaa75 → 0.0.0-experimental.dacec167

package/src/browser/navigation-client.ts

@@ -15,10 +15,12 @@ import { getRangoState } from "./rango-state.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
+  handleReloadHeader,
   teeWithCompletion,
 } from "./response-adapter.js";
 import {
   buildPrefetchKey,
+  buildSourceKey,
   consumeInflightPrefetch,
   consumePrefetch,
 } from "./prefetch/cache.js";
@@ -30,8 +32,10 @@ import {
  * deserializing the response using the RSC runtime.
  *
  * Checks the in-memory prefetch cache before making a network request.
- * The cache key is source-dependent (includes the previous URL) so
- * prefetch responses match the exact diff the server would produce.
+ * Tries the source-scoped key first (populated when the server tagged
+ * the response as source-sensitive via `X-RSC-Prefetch-Scope: source`)
+ * and falls back to the Rango-state-keyed wildcard slot used for the
+ * common source-agnostic case.
  *
  * @param deps - RSC browser dependencies (createFromFetch)
  * @returns NavigationClient instance
@@ -93,18 +97,42 @@ export function createNavigationClient(
         fetchUrl.searchParams.set("_rsc_rid", routerId);
       }
 
-      // Check completed in-memory prefetch cache before making a network request.
-      // The cache key includes the source URL (previousUrl) because the
-      // server's diff response depends on the source page context.
+      // 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.
+      // 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
       // fresh modules), and intercept contexts (source-dependent responses).
-      //
       const canUsePrefetch = !staleRevalidation && !hmr && !interceptSourceUrl;
-      const cacheKey = buildPrefetchKey(previousUrl, fetchUrl);
-      const cachedResponse = canUsePrefetch ? consumePrefetch(cacheKey) : null;
-      const inflightResponsePromise = canUsePrefetch
-        ? consumeInflightPrefetch(cacheKey)
-        : null;
+      const rangoState = getRangoState();
+      const wildcardKey = buildPrefetchKey(rangoState, fetchUrl);
+      const cacheKey = buildSourceKey(rangoState, previousUrl, fetchUrl);
+
+      let cachedResponse: Response | null = null;
+      let hitKey: string | null = null;
+      if (canUsePrefetch) {
+        cachedResponse = consumePrefetch(cacheKey);
+        if (cachedResponse) {
+          hitKey = cacheKey;
+        } else {
+          cachedResponse = consumePrefetch(wildcardKey);
+          if (cachedResponse) hitKey = wildcardKey;
+        }
+      }
+
+      let inflightResponsePromise: Promise<Response | null> | null = null;
+      if (canUsePrefetch && !cachedResponse) {
+        inflightResponsePromise = consumeInflightPrefetch(cacheKey);
+        if (inflightResponsePromise) {
+          hitKey = cacheKey;
+        } else {
+          inflightResponsePromise = consumeInflightPrefetch(wildcardKey);
+          if (inflightResponsePromise) hitKey = wildcardKey;
+        }
+      }
       // Track when the stream completes
       let resolveStreamComplete: () => void;
       const streamComplete = new Promise<void>((resolve) => {
@@ -121,21 +149,17 @@ export function createNavigationClient(
         source: string,
       ): Response | Promise<Response> => {
         // Version mismatch — server wants a full page reload
-        const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
-        if (reload === "blocked") {
-          resolveStreamComplete();
-          return emptyResponse();
-        }
-        if (reload) {
-          if (tx) {
-            browserDebugLog(tx, `version mismatch, reloading (${source})`, {
-              reloadUrl: reload.url,
-            });
-          }
-          window.location.href = reload.url;
-          // Block further processing — page is reloading
-          return new Promise<Response>(() => {});
-        }
+        const reloadResult = handleReloadHeader(response, {
+          onBlocked: resolveStreamComplete,
+          onReload: (url) => {
+            if (tx) {
+              browserDebugLog(tx, `version mismatch, reloading (${source})`, {
+                reloadUrl: url,
+              });
+            }
+          },
+        });
+        if (reloadResult) return reloadResult;
 
         // Server-side redirect without state: the server returned 204 with
         // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
@@ -197,7 +221,10 @@ export function createNavigationClient(
 
       if (cachedResponse) {
         if (tx) {
-          browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
+          browserDebugLog(tx, "prefetch cache hit", {
+            key: hitKey,
+            wildcard: hitKey === wildcardKey,
+          });
         }
         responsePromise = Promise.resolve(cachedResponse).then((response) => {
           const validated = validateRscHeaders(response, "prefetch cache");
@@ -214,8 +241,12 @@ export function createNavigationClient(
         });
       } else if (inflightResponsePromise) {
         if (tx) {
-          browserDebugLog(tx, "reusing inflight prefetch", { key: cacheKey });
+          browserDebugLog(tx, "reusing inflight prefetch", {
+            key: hitKey,
+            wildcard: hitKey === wildcardKey,
+          });
         }
+        const adoptedViaWildcard = hitKey === wildcardKey;
         responsePromise = inflightResponsePromise.then(async (response) => {
           if (!response) {
             if (tx) {
@@ -224,6 +255,23 @@ export function createNavigationClient(
             return doFreshFetch();
           }
 
+          // Cross-source safety: an inflight promise adopted via the
+          // wildcard key may turn out to be source-scoped (server emitted
+          // `X-RSC-Prefetch-Scope: source`), which means it was built for
+          // a different source page. Discard and refetch.
+          if (
+            adoptedViaWildcard &&
+            response.headers.get("x-rsc-prefetch-scope") === "source"
+          ) {
+            if (tx) {
+              browserDebugLog(
+                tx,
+                "wildcard inflight turned out source-scoped, refetching",
+              );
+            }
+            return doFreshFetch();
+          }
+
           const validated = validateRscHeaders(response, "inflight prefetch");
           if (validated instanceof Promise) return validated;
 

package/src/browser/navigation-store.ts

@@ -12,7 +12,10 @@ import type {
   ActionStateListener,
   HandleData,
 } from "./types.js";
-import { clearPrefetchCache } from "./prefetch/cache.js";
+import {
+  clearPrefetchCache,
+  clearPrefetchCacheLocal,
+} from "./prefetch/cache.js";
 
 /**
  * Default action state (idle with no payload)
@@ -280,18 +283,17 @@ export function createNavigationStore(
   /**
    * Create a debounced function that batches rapid calls
    */
+  // A non-keyed notifier is the keyed one restricted to a single constant key;
+  // its own keyed instance means the "" key never collides with action keys.
   function createDebouncedNotifier<T extends (...args: any[]) => void>(
     fn: T,
     ms: number = 20,
   ): T {
-    let timeout: ReturnType<typeof setTimeout> | null = null;
-    return ((...args: Parameters<T>) => {
-      if (timeout !== null) clearTimeout(timeout);
-      timeout = setTimeout(() => {
-        timeout = null;
-        fn(...args);
-      }, ms);
-    }) as T;
+    const keyed = createKeyedDebouncedNotifier(
+      (_key: string, ...args: any[]) => fn(...args),
+      ms,
+    );
+    return ((...args: Parameters<T>) => keyed("", ...args)) as T;
   }
 
   /**
@@ -335,6 +337,18 @@ export function createNavigationStore(
     clearPrefetchCache();
   }
 
+  /**
+   * Drop this tab's navigation + prefetch caches without broadcasting or
+   * rotating shared state. Used when the local session changes in a way that
+   * doesn't affect other tabs — e.g. this tab crosses into a different app
+   * via a cross-router navigation. Other tabs in the old app keep their
+   * caches and their X-Rango-State token.
+   */
+  function clearCacheInternalLocal(): void {
+    historyCache.length = 0;
+    clearPrefetchCacheLocal();
+  }
+
   /**
    * Mark all cache entries as stale (internal - does not broadcast)
    */
@@ -668,6 +682,15 @@ export function createNavigationStore(
       clearCacheAndBroadcast();
     },
 
+    /**
+     * Drop this tab's navigation + prefetch caches locally without
+     * broadcasting or rotating shared state. Intended for cross-app
+     * transitions where the session state diverges for this tab only.
+     */
+    clearHistoryCacheLocal(): void {
+      clearCacheInternalLocal();
+    },
+
     /**
      * Mark cache as stale and broadcast to other tabs
      * Called after server actions - allows SWR pattern for popstate

package/src/browser/navigation-transaction.ts

@@ -11,7 +11,7 @@ import {
 } from "./scroll-restoration.js";
 import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
-import { buildHistoryState } from "./history-state.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 
 // Re-export for consumers that import from navigation-transaction
 export { resolveNavigationState } from "./history-state.js";
@@ -186,12 +186,8 @@ export function createNavigationTransaction(
     // Used to detect when location state is being cleared.
     const oldState = window.history.state;
 
-    // Update browser URL
-    if (replace) {
-      window.history.replaceState(historyState, "", url);
-    } else {
-      window.history.pushState(historyState, "", url);
-    }
+    // Update browser URL (stamps history.state.idx for back() first-entry detection)
+    pushHistoryWithIdx(historyState, url, replace ?? false);
     // Ensure new history entry has a scroll restoration key
     ensureHistoryKey();
 
@@ -240,30 +236,16 @@ export function createNavigationTransaction(
           segments: ResolvedSegment[],
           overrides?: BoundCommitOverrides,
         ) => {
-          // Allow overrides to disable scroll (e.g., for intercepts)
-          const finalScroll =
-            overrides?.scroll !== undefined ? overrides.scroll : opts.scroll;
-          // Allow overrides to force replace (e.g., for intercepts)
-          const finalReplace =
-            overrides?.replace !== undefined ? overrides.replace : opts.replace;
-          // Intercept info: overrides take precedence, fallback to opts
-          const intercept =
-            overrides?.intercept !== undefined
-              ? overrides.intercept
-              : opts.intercept;
+          const finalScroll = overrides?.scroll ?? opts.scroll;
+          const finalReplace = overrides?.replace ?? opts.replace;
+          const intercept = overrides?.intercept ?? opts.intercept;
           const interceptSourceUrl =
-            overrides?.interceptSourceUrl !== undefined
-              ? overrides.interceptSourceUrl
-              : opts.interceptSourceUrl;
-          // Cache-only mode: overrides take precedence, fallback to opts
-          const cacheOnly =
-            overrides?.cacheOnly !== undefined
-              ? overrides.cacheOnly
-              : opts.cacheOnly;
-          // User state: overrides take precedence, fallback to opts
+            overrides?.interceptSourceUrl ?? opts.interceptSourceUrl;
+          const cacheOnly = overrides?.cacheOnly ?? opts.cacheOnly;
+          // state is `unknown` (null is meaningful) so `??` would wrongly drop a
+          // null override; serverState always comes from overrides, never opts.
           const state =
             overrides?.state !== undefined ? overrides.state : opts.state;
-          // Server-set location state: only from overrides (set by partial-update)
           const serverState = overrides?.serverState;
           return commit({
             ...opts,

package/src/browser/partial-update.ts

@@ -14,7 +14,10 @@ const addTransitionType: ((type: string) => void) | undefined =
 import type { RenderSegmentsOptions } from "../segment-system.js";
 import { reconcileSegments } from "./segment-reconciler.js";
 import type { ReconcileActor } from "./segment-reconciler.js";
-import { hasActiveIntercept as hasActiveInterceptSlots } from "./intercept-utils.js";
+import {
+  hasActiveIntercept as hasActiveInterceptSlots,
+  isInterceptSegment,
+} from "./intercept-utils.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
 import { ServerRedirect } from "../errors.js";
 import { debugLog } from "./logging.js";
@@ -28,6 +31,23 @@ function toScrollPayload(
   return { enabled: scroll !== false ? scroll : false };
 }
 
+/**
+ * Whether to wrap an update in startViewTransition.
+ *
+ * Intercept-driven updates only mutate the parallel slot — the main outlet
+ * shows the same content — so transitions on the underlying main segments
+ * shouldn't fire (otherwise their elements get hoisted above the modal).
+ */
+function shouldStartViewTransition(segments: ResolvedSegment[]): boolean {
+  let hasIntercept = false;
+  let hasTransition = false;
+  for (const s of segments) {
+    if (isInterceptSegment(s)) hasIntercept = true;
+    else if (s.transition) hasTransition = true;
+  }
+  return !hasIntercept && hasTransition;
+}
+
 /**
  * Configuration for creating a partial updater
  */
@@ -41,6 +61,13 @@ export interface PartialUpdateConfig {
   ) => Promise<ReactNode> | ReactNode;
   /** RSC version getter — returns the current version (may change after HMR) */
   getVersion?: () => string | undefined;
+  /**
+   * Replace the active app-shell when a cross-app navigation is detected.
+   * Called before the full-update tree replacement renders, so the new
+   * payload's rootLayout, basename, and version are picked up. Theme,
+   * warmup, and prefetch TTL are not part of the shell — see AppShell.
+   */
+  applyAppShell?: (next: import("./app-shell.js").AppShell) => void;
 }
 
 /**
@@ -76,7 +103,7 @@ export type UpdateMode =
       /** Source URL for intercept restore (popstate cache miss) */
       interceptSourceUrl?: string;
     }
-  | { type: "leave-intercept" }
+  | { type: "leave-intercept"; interceptSourceUrl?: string }
   | { type: "stale-revalidation"; interceptSourceUrl?: string }
   | { type: "action"; interceptSourceUrl?: string };
 
@@ -110,6 +137,7 @@ export function createPartialUpdater(
     onUpdate,
     renderSegments,
     getVersion = () => undefined,
+    applyAppShell,
   } = config;
 
   /**
@@ -141,13 +169,7 @@ export function createPartialUpdater(
     // Capture history key at start for stale revalidation consistency check
     const historyKeyAtStart = store.getHistoryKey();
 
-    // Derive interceptSourceUrl from modes that carry it
-    const interceptSourceUrl =
-      mode.type === "stale-revalidation" ||
-      mode.type === "action" ||
-      mode.type === "navigate"
-        ? mode.interceptSourceUrl
-        : undefined;
+    const interceptSourceUrl = mode.interceptSourceUrl;
 
     // When leaving intercept, filter out intercept-specific segments
     let segments: string[];
@@ -167,9 +189,16 @@ export function createPartialUpdater(
       segments = segmentIds ?? segmentState.currentSegmentIds;
     }
 
-    // For intercept revalidation, use the intercept source URL as previousUrl
+    // For intercept revalidation, use the intercept source URL as previousUrl.
+    // For leave-intercept, tx.currentUrl captures window.location.href at tx
+    // creation, which on popstate is already the destination URL and would
+    // tell the server "from == to". segmentState.currentUrl still points at
+    // the URL the cached segments render (the intercept URL), which is the
+    // correct "from" for the server's diff computation.
     const previousUrl =
-      interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
+      mode.type === "leave-intercept"
+        ? segmentState.currentUrl || tx.currentUrl
+        : interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
 
     debugLog(`\n[Browser] >>> NAVIGATION`);
     debugLog(`[Browser] From: ${previousUrl}`);
@@ -183,11 +212,14 @@ export function createPartialUpdater(
     // When navigating with targetCacheSegments, use those for consistency.
     // Otherwise fall back to current page's segments (for same-route revalidation).
     const targetCache =
-      mode.type === "navigate" ? mode.targetCacheSegments : undefined;
-    const cachedSegs =
-      targetCache && targetCache.length > 0
-        ? targetCache
-        : getCurrentCachedSegments();
+      mode.type === "navigate" && mode.targetCacheSegments?.length
+        ? mode.targetCacheSegments
+        : undefined;
+    const cachedSegs = targetCache ?? getCurrentCachedSegments();
+    const cachedSegsSource = targetCache ? "history-cache" : "current-page";
+    debugLog(
+      `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
+    );
 
     // Fetch partial payload (no abort signal - RSC doesn't support it well)
     let fetchResult: Awaited<ReturnType<NavigationClient["fetchPartial"]>>;
@@ -216,7 +248,12 @@ export function createPartialUpdater(
     // Detect app switch: if routerId changed, the navigation crossed into
     // a different router (e.g., via host router path mount). Downgrade
     // partial to full so the entire tree is replaced without reconciliation
-    // against stale segments from the previous app.
+    // against stale segments from the previous app, and replace the app
+    // shell (rootLayout, basename, version) so the target app's document
+    // and router config take effect instead of remaining captured from the
+    // initial load. Theme, warmup, and prefetch TTL are intentionally
+    // document-lifetime (see AppShell doc); a new document navigation
+    // applies them.
     if (payload.metadata?.routerId) {
       const prevRouterId = store.getRouterId?.();
       if (prevRouterId && prevRouterId !== payload.metadata.routerId) {
@@ -224,6 +261,12 @@ export function createPartialUpdater(
           `[Browser] App switch detected (${prevRouterId} → ${payload.metadata.routerId}), forcing full update`,
         );
         payload.metadata.isPartial = false;
+        applyAppShell?.({
+          routerId: payload.metadata.routerId,
+          rootLayout: payload.metadata.rootLayout,
+          basename: payload.metadata.basename,
+          version: payload.metadata.version,
+        });
       }
       store.setRouterId?.(payload.metadata.routerId);
     }
@@ -267,7 +310,7 @@ export function createPartialUpdater(
           .filter(Boolean) as ResolvedSegment[];
 
         // When navigating with cached segments to a different route, render them.
-        if (mode.type === "navigate" && targetCache && targetCache.length > 0) {
+        if (mode.type === "navigate" && targetCache) {
           debugLog(
             "[Browser] No diff but navigating with cached segments - rendering target route",
           );
@@ -307,10 +350,7 @@ export function createPartialUpdater(
             scroll: toScrollPayload(commitScroll),
           };
 
-          const cachedHasTransition = existingSegments.some(
-            (s) => s.transition,
-          );
-          if (cachedHasTransition) {
+          if (shouldStartViewTransition(existingSegments)) {
             startTransition(() => {
               if (addTransitionType) {
                 addTransitionType("navigation");
@@ -496,7 +536,7 @@ export function createPartialUpdater(
 
       // Emit update to trigger React render.
       // Scroll info is included so NavigationProvider applies it after React commits.
-      const hasTransition = reconciled.mainSegments.some((s) => s.transition);
+      const hasTransition = shouldStartViewTransition(reconciled.segments);
       const scrollPayload = toScrollPayload(navScroll);
 
       if (mode.type === "action" || mode.type === "stale-revalidation") {
@@ -558,9 +598,7 @@ export function createPartialUpdater(
           })
         : tx.commit(segmentIds, segments);
 
-      const fullHasTransition = segments.some(
-        (s: ResolvedSegment) => s.transition,
-      );
+      const fullHasTransition = shouldStartViewTransition(segments);
       const fullScrollPayload = toScrollPayload(fullScroll);
 
       if (mode.type === "stale-revalidation") {