@rangojs/router 0.0.0-experimental.66 → 0.0.0-experimental.66cdebe3

package/src/browser/rsc-router.tsx

@@ -28,6 +28,7 @@ import {
   isInterceptSegment,
   splitInterceptSegments,
 } from "./intercept-utils.js";
+import { createAppShellRef } from "./app-shell.js";
 
 // Vite HMR types are provided by vite/client
 
@@ -114,6 +115,13 @@ export interface BrowserAppContext {
   warmupEnabled?: boolean;
   /** App version for prefetch version mismatch detection */
   version?: string;
+  /**
+   * Live app-shell ref. Cross-app navigations replace its contents so the
+   * NavigationProvider and renderSegments pick up the target app's
+   * rootLayout, basename, and version without consumer rerenders. Theme,
+   * warmup, and prefetch TTL are document-lifetime (see AppShell).
+   */
+  appShellRef?: import("./app-shell.js").AppShellRef;
 }
 
 // Module-level state for the initialized app
@@ -204,13 +212,23 @@ export async function initBrowserApp(
   // Create composable utilities
   const client = createNavigationClient(deps);
 
-  // Extract rootLayout and version from metadata for browser-side re-renders
-  const rootLayout = initialPayload.metadata?.rootLayout;
+  // Capture the per-router app-shell so cross-app navigations can replace
+  // it atomically. rootLayout, basename, and version live here and are
+  // read through the ref at call time rather than closed over. Theme,
+  // warmup, and prefetch TTL are deliberately excluded — they are
+  // document-lifetime and stay stable across smooth cross-app transitions.
   const version = initialPayload.metadata?.version;
+  const appShellRef = createAppShellRef({
+    routerId: initialPayload.metadata?.routerId,
+    rootLayout: initialPayload.metadata?.rootLayout,
+    basename: initialPayload.metadata?.basename,
+    version,
+  });
 
   // Initialize the localStorage state key for cache invalidation.
-  // Uses the build version so a new deploy automatically busts all cached prefetches.
-  initRangoState(version ?? "0");
+  // The build version busts cached prefetches on deploy; the routerId
+  // namespaces the key so sibling apps on the same origin don't collide.
+  initRangoState(version ?? "0", initialPayload.metadata?.routerId);
   setAppVersion(version);
 
   // Initialize the in-memory prefetch cache TTL from server config.
@@ -220,11 +238,17 @@ export async function initBrowserApp(
     initPrefetchCache(prefetchCacheTTL);
   }
 
-  // Create a bound renderSegments that includes rootLayout
+  // Create a bound renderSegments that reads rootLayout through the shell
+  // ref. On app switch the ref is updated before the tree re-renders, so
+  // the new app's Document (rootLayout) replaces the previous one.
   const renderSegments = (
     segments: ResolvedSegment[],
     options?: RenderSegmentsOptions,
-  ) => baseRenderSegments(segments, { ...options, rootLayout });
+  ) =>
+    baseRenderSegments(segments, {
+      ...options,
+      rootLayout: appShellRef.get().rootLayout,
+    });
 
   // Lazy reference for navigation bridge — the action bridge is created first
   // but may need to trigger SPA navigation for action redirects.
@@ -256,6 +280,7 @@ export async function initBrowserApp(
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
     version: version,
+    appShellRef,
   });
 
   // Connect action redirect → navigation bridge (now that both are initialized)
@@ -416,6 +441,7 @@ export async function initBrowserApp(
     initialTheme: effectiveInitialTheme,
     warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
     version,
+    appShellRef,
   };
   browserAppContext = context;
 
@@ -481,6 +507,7 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
     initialTheme,
     warmupEnabled,
     version,
+    appShellRef,
   } = getBrowserAppContext();
 
   // Signal that the React tree has hydrated. useEffect only fires after
@@ -501,6 +528,7 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
       warmupEnabled={warmupEnabled}
       version={version}
       basename={initialPayload.metadata?.basename}
+      appShellRef={appShellRef}
     />
   );
 }

package/src/browser/scroll-restoration.ts

@@ -10,15 +10,6 @@
 
 import { debugLog } from "./logging.js";
 
-/**
- * Defers a callback to the next animation frame.
- * Falls back to setTimeout(0) in environments without requestAnimationFrame.
- */
-const deferToNextPaint: (fn: () => void) => void =
-  typeof requestAnimationFrame === "function"
-    ? requestAnimationFrame
-    : (fn) => setTimeout(fn, 0);
-
 const SCROLL_STORAGE_KEY = "rsc-router-scroll-positions";
 
 /**
@@ -294,16 +285,69 @@ export function restoreScrollPosition(options?: {
     return true;
   }
 
-  // Not streaming — scroll after React commits and browser paints.
-  // startTransition defers the DOM commit, so scrolling synchronously
-  // would be overwritten when React replaces the content.
-  deferToNextPaint(() => {
+  // Defer the actual scrollTo to the next animation frame so the new
+  // tree's layout has been measured. Synchronous scrollTo from inside
+  // useLayoutEffect runs against an as-yet-unmeasured DOM and silently
+  // clamps savedY to the old (or zero) maxScroll — a tall destination
+  // restored from a short source then lands at Y=0 instead of the
+  // saved position.
+  //
+  // (scrollToTop / scrollToHash on forward navigations stay synchronous
+  // because Y=0 / a hash element are robust against unmeasured layout —
+  // they don't depend on the new tree's full scrollHeight, and sync
+  // scrolling lands before startViewTransition's snapshot capture.)
+  //
+  // If a view transition is in flight, scrollTo lands on the live DOM
+  // but the user sees the VT snapshot pseudos. When the VT finishes and
+  // pseudos are removed, the browser settles scrollY at whatever the
+  // pseudo-element layout left it at — often the new tree's max scroll
+  // — overwriting the restore. Detect active VT animations and re-apply
+  // scrollTo once they finish.
+  if (typeof requestAnimationFrame === "function") {
+    requestAnimationFrame(() => {
+      if (typeof window.scrollTo === "function") {
+        window.scrollTo(0, savedY);
+        debugLog("[Scroll] Restored position:", savedY, "for key:", key);
+      }
+      const vtAnimations = getActiveViewTransitionAnimations();
+      if (vtAnimations.length > 0) {
+        Promise.allSettled(vtAnimations.map((a) => a.finished))
+          .then(() => {
+            if (typeof window.scrollTo === "function") {
+              window.scrollTo(0, savedY);
+              debugLog("[Scroll] Re-applied position after VT settle:", savedY);
+            }
+          })
+          .catch(() => {
+            // Animations.finished can reject if the animation is canceled
+            // (e.g., the user starts another navigation). In that case
+            // the next nav's scroll handling takes over.
+          });
+      }
+    });
+  } else if (typeof window.scrollTo === "function") {
     window.scrollTo(0, savedY);
     debugLog("[Scroll] Restored position:", savedY, "for key:", key);
-  });
+  }
   return true;
 }
 
+/**
+ * Find any in-flight View Transition pseudo-element animations. Used to
+ * sequence scroll restoration after the transition settles, so VT
+ * pseudo-element teardown doesn't overwrite our scrollTo with the live
+ * DOM's post-transition scroll position.
+ */
+function getActiveViewTransitionAnimations(): Animation[] {
+  if (typeof document === "undefined") return [];
+  if (typeof document.getAnimations !== "function") return [];
+  return document.getAnimations().filter((a) => {
+    const effect = a.effect as KeyframeEffect | null;
+    const pseudo = effect?.pseudoElement;
+    return typeof pseudo === "string" && pseudo.startsWith("::view-transition");
+  });
+}
+
 /**
  * Handle hash link scrolling.
  * Scrolls to element with matching ID if hash is present.
@@ -332,6 +376,8 @@ export function scrollToHash(): boolean {
  * Scroll to top of page
  */
 export function scrollToTop(): void {
+  if (typeof window === "undefined") return;
+  if (typeof window.scrollTo !== "function") return;
   window.scrollTo(0, 0);
 }
 
@@ -374,20 +420,15 @@ export function handleNavigationEnd(options: {
     // Fall through to hash or top if no saved position
   }
 
-  // Defer hash and scroll-to-top to after React paints the new content,
-  // so the user doesn't see the current page jump before the new route appears.
-  deferToNextPaint(() => {
-    // Re-check: the deferred callback may fire after environment teardown
-    if (typeof window === "undefined") return;
-
-    // Try hash scrolling first
-    if (scrollToHash()) {
-      return;
-    }
-
-    // Default: scroll to top
-    scrollToTop();
-  });
+  // Sync hash scroll / scroll-to-top — see the long comment in
+  // restoreScrollPosition above. handleNavigationEnd runs from
+  // NavigationProvider's useLayoutEffect (post-commit, pre-paint) and from
+  // bridge sites that don't trigger a React commit, so a synchronous
+  // scrollTo is captured by the next paint / startViewTransition snapshot.
+  if (scrollToHash()) {
+    return;
+  }
+  scrollToTop();
 }
 
 /**

package/src/browser/segment-reconciler.ts

@@ -6,6 +6,7 @@ import {
 } from "./merge-segment-loaders.js";
 import { assertSegmentStructure } from "./segment-structure-assert.js";
 import { splitInterceptSegments } from "./intercept-utils.js";
+import { debugLog } from "./logging.js";
 
 /**
  * Determines the merging behavior for segment reconciliation.
@@ -85,14 +86,29 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
   const cachedSegments = new Map<string, ResolvedSegment>();
   input.cachedSegments.forEach((s) => cachedSegments.set(s.id, s));
 
+  const diffSet = new Set(diff);
+  debugLog(
+    `[reconcile] actor=${actor}, matched=${matched.length}, diff=${diff.length}`,
+  );
+  debugLog(
+    `[reconcile] server segments: ${[...serverSegments.keys()].join(", ")}`,
+  );
+  debugLog(
+    `[reconcile] cached segments: ${[...cachedSegments.keys()].join(", ")}`,
+  );
+
   const segments = matched
     .map((segId: string) => {
       const fromServer = serverSegments.get(segId);
       const fromCache = cachedSegments.get(segId);
 
       if (fromServer) {
+        const inDiff = diffSet.has(segId);
         // Merge partial loader data when server returns fewer loaders than cached
         if (shouldMergeLoaders && needsLoaderMerge(fromServer, fromCache)) {
+          debugLog(
+            `[reconcile] ${segId}: MERGE loaders (server partial, ${inDiff ? "in diff" : "not in diff"})`,
+          );
           return mergeSegmentLoaders(fromServer, fromCache);
         }
 
@@ -143,8 +159,14 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
           // above fails to preserve a value it should have.
           assertSegmentStructure(fromCache, merged, context);
 
+          debugLog(
+            `[reconcile] ${segId}: SERVER+CACHE merge (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, component=${fromServer.component === null ? "null→cached" : "server"})`,
+          );
           return merged;
         }
+        debugLog(
+          `[reconcile] ${segId}: SERVER only (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, no cache entry)`,
+        );
         return fromServer;
       }
 
@@ -158,20 +180,20 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
         return fromCache;
       }
 
-      // For non-action actors: cached segments the server decided not to re-render.
-      // - Preserve loading=false (suppressed boundary) to maintain tree structure
-      // - Preserve parallel segment loading so renderSegments can reconstruct
-      //   parallel-owned loader markers from the cached slot metadata
-      // - Clear other truthy loading values to prevent suspense on cached content
-      if (actor !== "action") {
-        if (fromCache.type === "parallel" && fromCache.loading !== undefined) {
-          return fromCache;
-        }
-        if (fromCache.loading !== undefined && fromCache.loading !== false) {
-          return { ...fromCache, loading: undefined };
-        }
-      }
-
+      debugLog(
+        `[reconcile] ${segId}: CACHE only (not from server, type=${fromCache.type}, component=${fromCache.component != null ? "yes" : "null"})`,
+      );
+
+      // Return the cached segment as-is, regardless of actor. We used to clear
+      // truthy `loading` here to prevent a stale Suspense fallback from
+      // committing against cached content, but that swapped the render tree
+      // from the LoaderBoundary branch to the plain OutletProvider branch
+      // inside renderSegments, causing React to unmount the entire chain
+      // (LoaderBoundary > Suspense > LoaderResolver > RouteContentWrapper >
+      // Suspender) every time the user opened an intercept or navigated back
+      // to a cached page. The flicker is now prevented by renderSegments'
+      // promise memoization keeping React's use() in "known fulfilled" state,
+      // so preserving `loading` keeps the element tree stable.
       return fromCache;
     })
     .filter(Boolean) as ResolvedSegment[];

package/src/browser/types.ts

@@ -39,6 +39,12 @@ export interface RscMetadata {
   isError?: boolean;
   matched?: string[];
   diff?: string[];
+  /**
+   * All segment ids re-resolved on the server, including null-component
+   * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
+   * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
+   */
+  resolvedIds?: string[];
   /** Merged route params from the matched route */
   params?: Record<string, string>;
   /**
@@ -427,6 +433,12 @@ export interface NavigationStore {
   markCacheAsStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
+  /**
+   * Clear this tab's nav + prefetch caches without broadcasting or rotating
+   * shared state. Intended for app-switch transitions that affect only this
+   * tab's session.
+   */
+  clearHistoryCacheLocal(): void;
   broadcastCacheInvalidation(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
@@ -542,6 +554,13 @@ export interface NavigationBridge {
   registerLinkInterception(): () => void;
   /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */
   updateVersion(newVersion: string): void;
+  /**
+   * Replace the active app-shell snapshot (rootLayout, basename, version)
+   * atomically. Used on cross-app navigations when the response's routerId
+   * indicates the user entered a different app. Theme, warmup, and prefetch
+   * TTL are document-lifetime and not part of the shell.
+   */
+  updateAppShell(next: import("./app-shell.js").AppShell): void;
 }
 
 /**

package/src/build/route-trie.ts

@@ -20,7 +20,8 @@ export interface TrieLeaf {
   sp: string;
   /** Ancestry shortCodes from root to route [M0L0, M0L0L0, M0L0L0R499] */
   a: string[];
-  /** Optional param names (absent params get empty string value) */
+  /** Optional param names declared on the route. Absent params are
+   * omitted from the matched params record (read as `undefined`). */
   op?: string[];
   /** Constraint validation: paramName -> allowed values */
   cv?: Record<string, string[]>;
@@ -98,8 +99,14 @@ export function buildRouteTrie(
 }
 
 /**
- * Insert a route into the trie, handling optional params by forking
- * the insertion path (one terminal without the param, one with).
+ * Insert a route into the trie. Optional params expand into two branches at
+ * registration time (skip-first, then present), so each terminal lives at the
+ * correct depth for its number of bound params and carries a branch-local
+ * `pa` listing only those names. The trie's single-slot `node.p` is reused
+ * across branches because matching ignores `node.p.n` — the leaf's `pa` is
+ * the source of truth for naming. Skip-first ordering lets `mergeLeaf`'s
+ * last-wins rule produce greedy-leftmost semantics for free at any shared
+ * terminal depth.
  */
 function insertRoute(
   node: TrieNode,
@@ -107,14 +114,13 @@ function insertRoute(
   index: number,
   leaf: Omit<TrieLeaf, "op" | "cv" | "pa">,
 ): void {
-  // Collect param names, optional param names, and constraints across all segments
-  const paramNames: string[] = [];
+  // op (full optional list) and cv (full constraint map) are route-level and
+  // identical on every terminal, so compute them once on the shared base.
   const optionalParams: string[] = [];
   const constraints: Record<string, string[]> = {};
 
   for (const seg of segments) {
     if (seg.type === "param") {
-      paramNames.push(seg.value);
       if (seg.optional) {
         optionalParams.push(seg.value);
       }
@@ -124,21 +130,15 @@ function insertRoute(
     }
   }
 
-  const fullLeaf: TrieLeaf = {
+  const leafBase: Omit<TrieLeaf, "pa"> = {
     ...leaf,
-    ...(paramNames.length > 0 ? { pa: paramNames } : {}),
     ...(optionalParams.length > 0 ? { op: optionalParams } : {}),
     ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
   };
 
-  insertSegments(node, segments, index, fullLeaf);
+  insertSegments(node, segments, index, leafBase, []);
 }
 
-/**
- * Recursively insert segments into the trie.
- * For optional params, we add a terminal at the current node (param absent)
- * AND continue inserting into the param child (param present).
- */
 /**
  * Extract ancestry map from a built trie by visiting all leaf nodes.
  * Returns { routeName: ancestryShortCodes[] } for every route in the trie.
@@ -218,15 +218,25 @@ function mergeLeaf(node: TrieNode, leaf: TrieLeaf): void {
   node.r = mergeLeaves(node.r, leaf);
 }
 
+function buildLeaf(
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
+): TrieLeaf {
+  return paramNames.length > 0
+    ? { ...leafBase, pa: [...paramNames] }
+    : { ...leafBase };
+}
+
 function insertSegments(
   node: TrieNode,
   segments: ParsedSegment[],
   index: number,
-  leaf: TrieLeaf,
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
 ): void {
-  // Base case: all segments consumed, add terminal
+  // Base case: all segments consumed, add terminal with branch-local pa
   if (index >= segments.length) {
-    mergeLeaf(node, leaf);
+    mergeLeaf(node, buildLeaf(leafBase, paramNames));
     return;
   }
 
@@ -235,12 +245,19 @@ function insertSegments(
   if (segment.type === "static") {
     if (!node.s) node.s = {};
     if (!node.s[segment.value]) node.s[segment.value] = {};
-    insertSegments(node.s[segment.value], segments, index + 1, leaf);
+    insertSegments(
+      node.s[segment.value],
+      segments,
+      index + 1,
+      leafBase,
+      paramNames,
+    );
   } else if (segment.type === "param") {
     if (segment.optional) {
-      // Optional param: add terminal at current node (param absent)
-      mergeLeaf(node, leaf);
-      // AND continue with param child (param present)
+      // SKIP first: continue at the same node without binding this name.
+      // Skip-first ordering means the present-branch's TAKE overwrites any
+      // shared terminal later, giving greedy-leftmost semantics.
+      insertSegments(node, segments, index + 1, leafBase, paramNames);
     }
     if (segment.suffix) {
       // Suffix param: keyed by suffix string (e.g., ".html")
@@ -248,16 +265,26 @@ function insertSegments(
       if (!node.xp[segment.suffix]) {
         node.xp[segment.suffix] = { n: segment.value, c: {} };
       }
-      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leaf);
+      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     } else {
       if (!node.p) {
         node.p = { n: segment.value, c: {} };
       }
-      insertSegments(node.p.c, segments, index + 1, leaf);
+      insertSegments(node.p.c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     }
   } else if (segment.type === "wildcard") {
-    // Wildcard consumes all remaining segments
-    const wildLeaf = { ...leaf, pn: "*" };
+    // Wildcard consumes all remaining segments. Carry any params bound before
+    // the wildcard in pa so they zip correctly against paramValues at match.
+    const wildLeaf: TrieLeaf & { pn: string } = {
+      ...buildLeaf(leafBase, paramNames),
+      pn: "*",
+    };
     const existing = node.w ? ({ ...node.w } as TrieLeaf) : undefined;
     const merged = mergeLeaves(existing, wildLeaf);
     node.w = merged as TrieLeaf & { pn: string };

package/src/cache/cf/cf-cache-store.ts

@@ -67,13 +67,11 @@ export const MAX_REVALIDATION_INTERVAL = 30;
 // Types
 // ============================================================================
 
-/**
- * Cloudflare Workers ExecutionContext (subset we need)
- */
-export interface ExecutionContext {
-  waitUntil(promise: Promise<any>): void;
-  passThroughOnException(): void;
-}
+// Re-exported from the canonical home so cf-cache-store consumers keep
+// importing `ExecutionContext` from this module without a second interface
+// drifting over time.
+export type { ExecutionContext } from "../../types/request-scope.js";
+import type { ExecutionContext } from "../../types/request-scope.js";
 
 /**
  * Minimal Cloudflare KV Namespace interface.

package/src/client.rsc.tsx

@@ -78,6 +78,9 @@ export {
 // Re-export useHref - it's a "use client" hook
 export { useHref } from "./browser/react/use-href.js";
 
+// Re-export useReverse - it's a "use client" hook
+export { useReverse } from "./browser/react/use-reverse.js";
+
 // Re-export useHandle - it's a "use client" hook
 export { useHandle } from "./browser/react/use-handle.js";