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

package/src/browser/prefetch/queue.ts

@@ -108,10 +108,29 @@ export function enqueuePrefetch(
   scheduleDrain();
 }
 
+/**
+ * Normalize a URL-like string for keep-alive matching: parse against a
+ * placeholder origin and strip internal `_rsc_*` query params. 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`).
+ */
+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);
+    }
+    return u.pathname + u.search;
+  } catch {
+    return urlish;
+  }
+}
+
 /**
  * Cancel queued prefetches and abort in-flight ones that don't match
  * the current navigation target. If `keepUrl` is provided, the
- * executing prefetch whose key contains that URL is kept alive so
+ * executing prefetch whose key targets that URL is kept alive so
  * navigation can reuse its response via consumeInflightPrefetch.
  *
  * Called when a navigation starts via the NavigationProvider's
@@ -124,11 +143,23 @@ export function cancelAllPrefetches(keepUrl?: string | null): void {
   drainGeneration++;
 
   // Abort in-flight prefetches that aren't for the navigation target.
-  // Keys use format "sourceHref\0targetPathname+search" — match the
-  // target portion (after \0) against keepUrl.
+  // Key shapes (see prefetch/cache.ts buildPrefetchKey):
+  //   wildcard:      "rangoState\0/target?..."
+  //   source-scoped: "rangoState\0sourceHref\0/target?..."
+  // The target portion is always the final \0-delimited segment and
+  // includes internal `_rsc_*` params (from buildPrefetchUrl); keepUrl
+  // comes from NavigationProvider's pendingUrl which is the bare
+  // navigation target. Normalize both sides before comparing.
+  const normalizedKeep = keepUrl ? normalizeForMatch(keepUrl) : null;
   for (const [key, ac] of abortControllers) {
-    const target = key.split("\0")[1];
-    if (keepUrl && target && keepUrl.startsWith(target)) continue;
+    const lastNul = key.lastIndexOf("\0");
+    const target = lastNul >= 0 ? key.substring(lastNul + 1) : "";
+    if (
+      normalizedKeep &&
+      target &&
+      normalizeForMatch(target) === normalizedKeep
+    )
+      continue;
     ac.abort();
     abortControllers.delete(key);
     if (executing.delete(key)) {

package/src/browser/rango-state.ts

@@ -6,21 +6,37 @@
  * navigation requests. The server responds with `Vary: X-Rango-State`,
  * so the browser HTTP cache keys responses by (URL, X-Rango-State value).
  *
- * Format: `{buildVersion}:{invalidationTimestamp}`
+ * Value format: `{buildVersion}:{invalidationTimestamp}`
  * - Build version changes on deploy, busting all cached prefetches.
  * - Timestamp changes on server action invalidation.
  *
- * localStorage is cross-tab and survives page refresh, so:
- * - One tab's prefetch warms the cache for all tabs.
- * - Invalidation in one tab is picked up by other tabs on next fetch.
+ * Storage key is namespaced per routerId (`rango-state:{routerId}`) so
+ * tabs in different apps on the same origin do not collide. Two tabs in
+ * the same app share a key → one tab's invalidation is picked up by the
+ * other via the `storage` event. A smooth cross-app transition in this
+ * tab rebinds to the target app's key; other tabs still in the old app
+ * keep their own key intact.
+ *
+ * If no routerId is supplied, falls back to a single legacy key for
+ * backward compatibility (single-app deployments unaffected).
  */
 
-const STORAGE_KEY = "rango-state";
+const LEGACY_STORAGE_KEY = "rango-state";
+
+function buildStorageKey(routerId: string | undefined): string {
+  return routerId ? `${LEGACY_STORAGE_KEY}:${routerId}` : LEGACY_STORAGE_KEY;
+}
 
 // Module-level cache avoids hitting localStorage on every getRangoState() call.
 // Initialized from localStorage on first access or by initRangoState().
 let cachedState: string | null = null;
 
+// The localStorage key this tab is currently bound to. Rebinds on
+// initRangoState (document boot) and setRangoStateLocal (smooth app
+// switch). The storage listener filters cross-tab events by this key so
+// events from tabs in a different app are ignored.
+let currentStorageKey: string = LEGACY_STORAGE_KEY;
+
 // Cross-tab sync: the `storage` event fires in OTHER tabs when one tab writes
 // to localStorage, keeping cachedState fresh without polling.
 let storageListenerAttached = false;
@@ -28,7 +44,10 @@ let storageListenerAttached = false;
 function attachStorageListener(): void {
   if (storageListenerAttached || typeof window === "undefined") return;
   window.addEventListener("storage", (e) => {
-    if (e.key !== STORAGE_KEY) return;
+    // Only react to events for this tab's current app namespace. Events
+    // under other routerId-scoped keys belong to other apps and must not
+    // clobber this tab's state.
+    if (e.key !== currentStorageKey) return;
     cachedState = e.newValue;
   });
   storageListenerAttached = true;
@@ -37,16 +56,22 @@ function attachStorageListener(): void {
 /**
  * Initialize the Rango state key in localStorage.
  * Called once at app startup with the build version from the server.
- * If localStorage already has a key with matching version prefix, keeps it
- * (preserves invalidation state across refresh). Otherwise writes a new key.
+ * The routerId scopes the storage key to this app; in multi-app setups
+ * each app owns its own `rango-state:{routerId}` key and cannot observe
+ * invalidations from sibling apps on the same origin.
+ *
+ * If localStorage already has a matching-version entry under the key,
+ * keeps it (preserves invalidation state across refresh). Otherwise
+ * writes a new value.
  */
-export function initRangoState(version: string): void {
+export function initRangoState(version: string, routerId?: string): void {
+  currentStorageKey = buildStorageKey(routerId);
   if (typeof window === "undefined") return;
 
   attachStorageListener();
 
   try {
-    const existing = localStorage.getItem(STORAGE_KEY);
+    const existing = localStorage.getItem(currentStorageKey);
     if (existing) {
       const colonIdx = existing.indexOf(":");
       if (colonIdx > 0) {
@@ -59,7 +84,7 @@ export function initRangoState(version: string): void {
     }
     // New version or first load
     const newState = `${version}:${Date.now()}`;
-    localStorage.setItem(STORAGE_KEY, newState);
+    localStorage.setItem(currentStorageKey, newState);
     cachedState = newState;
   } catch {
     // localStorage may be unavailable (private browsing in some browsers)
@@ -77,7 +102,7 @@ export function getRangoState(): string {
   if (typeof window === "undefined") return "0:0";
 
   try {
-    const stored = localStorage.getItem(STORAGE_KEY);
+    const stored = localStorage.getItem(currentStorageKey);
     if (stored) {
       cachedState = stored;
       return stored;
@@ -89,6 +114,21 @@ export function getRangoState(): string {
   return "0:0";
 }
 
+/**
+ * Update the in-memory rango-state to a new version WITHOUT writing
+ * localStorage. Intended for smooth cross-app transitions in this tab only:
+ * subsequent requests from this tab send the new token, but other tabs
+ * still in the previous app do not observe a storage event. Rebinds this
+ * tab's storage key to the target app's namespace (`rango-state:{routerId}`)
+ * so subsequent storage events only reflect the new app. On the next hard
+ * reload, initRangoState reconciles localStorage from the server's
+ * authoritative version.
+ */
+export function setRangoStateLocal(version: string, routerId?: string): void {
+  currentStorageKey = buildStorageKey(routerId);
+  cachedState = `${version}:${Date.now()}`;
+}
+
 /**
  * Invalidate the Rango state key. Called when server actions mutate data.
  * Updates the timestamp portion while keeping the version prefix.
@@ -105,7 +145,7 @@ export function invalidateRangoState(): void {
   if (typeof window === "undefined") return;
 
   try {
-    localStorage.setItem(STORAGE_KEY, newState);
+    localStorage.setItem(currentStorageKey, newState);
   } catch {
     // Silently handle localStorage errors
   }

package/src/browser/react/Link.tsx

@@ -97,6 +97,31 @@ export interface LinkProps extends Omit<
    * @default "none"
    */
   prefetch?: PrefetchStrategy;
+  /**
+   * Opt-in override for the prefetch cache scope.
+   *
+   * The default cache is source-agnostic: one shared entry per target,
+   * keyed on Rango state + target URL. This is correct for routes whose
+   * response shape doesn't depend on where the user navigates from.
+   *
+   * Set `":source"` when this Link's response would legitimately differ
+   * based on the source page — typically when the target route (or one
+   * of its layouts) uses a custom `revalidate()` handler that reads
+   * `currentUrl` / `currentParams`, and the wildcard entry would
+   * 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.
+   *
+   * @example
+   * ```tsx
+   * // Route uses a `revalidate()` that branches on currentUrl — opt in
+   * // so prefetches don't bleed across source pages.
+   * <Link to="/dashboard" prefetch="hover" prefetchKey=":source" />
+   * ```
+   */
+  prefetchKey?: ":source";
   /**
    * State to pass to history.pushState/replaceState.
    * Accessible via useLocationState() hook.
@@ -184,6 +209,7 @@ export const Link: ForwardRefExoticComponent<
     reloadDocument = false,
     revalidate,
     prefetch = "none",
+    prefetchKey,
     state,
     children,
     onClick,
@@ -320,9 +346,10 @@ export const Link: ForwardRefExoticComponent<
         segmentState.currentSegmentIds,
         getAppVersion(),
         ctx.store.getRouterId?.(),
+        prefetchKey,
       );
     }
-  }, [resolvedStrategy, resolvedTo, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   // Viewport/render prefetch: waits for idle before starting,
   // uses concurrency-limited queue to avoid flooding.
@@ -344,6 +371,7 @@ export const Link: ForwardRefExoticComponent<
         segmentState.currentSegmentIds,
         getAppVersion(),
         ctx.store.getRouterId?.(),
+        prefetchKey,
       );
     };
 
@@ -383,7 +411,7 @@ export const Link: ForwardRefExoticComponent<
         unobserveForPrefetch(observedElement);
       }
     };
-  }, [resolvedStrategy, resolvedTo, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   return (
     <a

package/src/browser/react/NavigationProvider.tsx

@@ -28,6 +28,7 @@ import { NonceContext } from "./nonce-context.js";
 import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
 import { cancelAllPrefetches } from "../prefetch/queue.js";
 import { handleNavigationEnd } from "../scroll-restoration.js";
+import { createAppShellRef, type AppShellRef } from "../app-shell.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -46,10 +47,22 @@ async function processHandles(
     store: NavigationStore;
     matched?: string[];
     isPartial?: boolean;
+    /** Server's `resolvedIds`: every segment re-resolved this request,
+     *  including null-component ones excluded from `diff`/`segments`.
+     *  Drives cleanup of stale handle buckets when a re-resolved segment
+     *  pushed nothing. */
+    resolvedIds?: string[];
     historyKey: string;
   },
 ): Promise<void> {
-  const { eventController, store, matched, isPartial, historyKey } = opts;
+  const {
+    eventController,
+    store,
+    matched,
+    isPartial,
+    resolvedIds,
+    historyKey,
+  } = opts;
 
   let yieldCount = 0;
   for await (const handleData of handlesGenerator) {
@@ -64,7 +77,7 @@ async function processHandles(
     }
 
     yieldCount++;
-    eventController.setHandleData(handleData, matched, isPartial);
+    eventController.setHandleData(handleData, matched, isPartial, resolvedIds);
   }
 
   // Check again before final updates
@@ -72,12 +85,11 @@ async function processHandles(
     return;
   }
 
-  // For partial updates where the generator yielded nothing (cached handlers),
-  // we still need to update the segment order to clean up stale handle data.
-  // This happens when navigating away from a route - the handlers for the new
-  // route might not push any breadcrumbs, but we still need to remove the old ones.
+  // For partial updates where the generator yielded nothing (every
+  // re-resolved handler pushed nothing), still call setHandleData so the
+  // cleanup pass can clear out stale buckets for those segments.
   if (yieldCount === 0 && matched) {
-    eventController.setHandleData({}, matched, true);
+    eventController.setHandleData({}, matched, true, resolvedIds);
   }
 
   // After handles processing completes, update the cache's handleData.
@@ -133,15 +145,23 @@ export interface NavigationProviderProps {
   warmupEnabled?: boolean;
 
   /**
-   * App version from server payload (stable, immutable).
-   * Forwarded to context for cache key building.
+   * App version from server payload.
+   * Used only as a fallback when `appShellRef` is not supplied.
    */
   version?: string;
 
   /**
    * URL prefix for all routes (from createRouter({ basename })).
+   * Used only as a fallback when `appShellRef` is not supplied.
    */
   basename?: string;
+
+  /**
+   * Live app-shell ref. When provided, the context's `basename` and `version`
+   * properties become live getters that track app-switch updates without
+   * invalidating the memoized context value.
+   */
+  appShellRef?: AppShellRef;
 }
 
 /**
@@ -175,6 +195,7 @@ export function NavigationProvider({
   warmupEnabled,
   version,
   basename,
+  appShellRef,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -196,18 +217,34 @@ export function NavigationProvider({
     await bridge.refresh();
   }, []);
 
-  // Context value is stable (store, eventController, navigate, refresh never change)
-  const contextValue = useMemo<NavigationStoreContextValue>(
-    () => ({
+  // basename/version are always read through a shell ref so the context value
+  // has a single shape: a supplied appShellRef stays live (app-switch updates
+  // it), the standalone fallback is a frozen ref over the mount-time props.
+  const fallbackShellRef = useRef<AppShellRef | null>(null);
+  if (!fallbackShellRef.current) {
+    fallbackShellRef.current = createAppShellRef({ basename, version });
+  }
+  const shellRef = appShellRef ?? fallbackShellRef.current;
+
+  const contextValue = useMemo<NavigationStoreContextValue>(() => {
+    const value = {
       store,
       eventController,
       navigate,
       refresh,
-      version,
-      basename,
-    }),
-    [],
-  );
+    } as NavigationStoreContextValue;
+    Object.defineProperty(value, "basename", {
+      configurable: true,
+      enumerable: true,
+      get: () => shellRef.get().basename,
+    });
+    Object.defineProperty(value, "version", {
+      configurable: true,
+      enumerable: true,
+      get: () => shellRef.get().version,
+    });
+    return value;
+  }, []);
 
   // Connection warmup: keep TLS alive after idle periods.
   // After 60s of no user interaction, marks connection as "cold".
@@ -345,8 +382,12 @@ export function NavigationProvider({
         metadata: update.metadata,
       });
 
-      // Update route params
-      eventController.setParams(update.metadata.params ?? {});
+      // Update route params. Only reset when the server actually sends a params
+      // map — an absent `params` field means "no change" (e.g., legacy action
+      // responses that omitted params). Explicit `{}` still clears correctly.
+      if (update.metadata.params !== undefined) {
+        eventController.setParams(update.metadata.params);
+      }
 
       // Update handle data progressively as it streams in
       if (update.metadata.handles) {
@@ -359,24 +400,20 @@ export function NavigationProvider({
           store,
           matched: update.metadata.matched,
           isPartial: update.metadata.isPartial,
+          resolvedIds: update.metadata.resolvedIds,
           historyKey,
         }).catch((err) =>
           console.error("[NavigationProvider] Error consuming handles:", err),
         );
-      } else if (update.metadata.cachedHandleData) {
-        // For back/forward navigation from cache, restore the cached handleData
-        // This restores breadcrumbs to the exact state they were when the page was cached
-        eventController.setHandleData(
-          update.metadata.cachedHandleData,
-          update.metadata.matched,
-          false, // full replace - restore entire cached state
-        );
       } else if (update.metadata.matched) {
-        // For cached navigations without handleData, update segmentOrder to clean up stale data
+        // cachedHandleData present -> full restore (back/forward); absent ->
+        // partial cleanup of segments no longer matched.
+        const cached = update.metadata.cachedHandleData;
         eventController.setHandleData(
-          {}, // Empty data - all existing data not in matched will be cleaned up
+          cached ?? {},
           update.metadata.matched,
-          true, // partial update - will clean up segments not in matched
+          cached === undefined,
+          cached === undefined ? update.metadata.resolvedIds : undefined,
         );
       }
     });
@@ -398,7 +435,11 @@ export function NavigationProvider({
   // Build the content tree
   let content = <RootErrorBoundary>{root}</RootErrorBoundary>;
 
-  // Wrap with ThemeProvider when theme is enabled
+  // Wrap with ThemeProvider when theme is enabled. The ThemeProvider is
+  // document-lifetime: its config comes from the initial load and does NOT
+  // swap on cross-app transitions, because the ThemeProvider sits above the
+  // segment tree and a smooth (no-reload) app switch cannot safely remount
+  // it. A new theme config only takes effect on a full document load.
   if (themeConfig) {
     content = (
       <ThemeProvider config={themeConfig} initialTheme={initialTheme}>

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

@@ -1,11 +1,55 @@
 /**
- * Filter segment IDs to only include routes and layouts.
- * Excludes parallels (contain .@) and loaders (contain D followed by digit).
+ * Build the handle-collection segment order from a raw `matched` list.
+ *
+ * Two responsibilities:
+ *
+ * 1. Drop loader sub-ids ("D" followed by a digit, e.g. "M0L0D1.user") —
+ *    loaders never push handles.
+ *
+ * 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
+ *    `[..., 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.
+ *
+ * Slot-id format is `<parentShortCode>.@<slotName>`; `parentShortCode` never
+ * contains ".@", so splitting at the first ".@" reliably yields the parent.
  */
 export function filterSegmentOrder(matched: string[]): string[] {
-  return matched.filter((id) => {
-    if (id.includes(".@")) return false;
-    if (/D\d+\./.test(id)) return false;
-    return true;
-  });
+  const slotsByParent = new Map<string, string[]>();
+  const nonSlots: string[] = [];
+  const nonSlotSet = new Set<string>();
+
+  for (const id of matched) {
+    if (/D\d+\./.test(id)) continue;
+    const slotIdx = id.indexOf(".@");
+    if (slotIdx >= 0) {
+      const parent = id.slice(0, slotIdx);
+      const list = slotsByParent.get(parent);
+      if (list) {
+        list.push(id);
+      } else {
+        slotsByParent.set(parent, [id]);
+      }
+    } else {
+      nonSlots.push(id);
+      nonSlotSet.add(id);
+    }
+  }
+
+  const result: string[] = [];
+  for (const id of nonSlots) {
+    result.push(id);
+    const slots = slotsByParent.get(id);
+    if (slots) result.push(...slots);
+  }
+  // Defensive: any slot whose parent is missing from the filtered list still
+  // gets included rather than silently dropped. Shouldn't happen in practice.
+  for (const [parent, slots] of slotsByParent) {
+    if (!nonSlotSet.has(parent)) result.push(...slots);
+  }
+  return result;
 }

package/src/browser/react/index.ts

@@ -20,6 +20,9 @@ export { useSegments, type SegmentsState } from "./use-segments.js";
 // Handle data hook
 export { useHandle } from "./use-handle.js";
 
+// Mount-aware reverse hook
+export { useReverse } from "./use-reverse.js";
+
 // Client cache controls hook
 export {
   useClientCache,