@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

package/src/browser/react/NavigationProvider.tsx

@@ -3,8 +3,10 @@
 import React, {
   useState,
   useEffect,
+  useLayoutEffect,
   useCallback,
   useMemo,
+  useRef,
   use,
   type ReactNode,
 } from "react";
@@ -14,7 +16,7 @@ import {
 } from "./context.js";
 import type {
   NavigationStore,
-  RscPayload,
+  NavigationUpdate,
   NavigateOptions,
   NavigationBridge,
 } from "../types.js";
@@ -22,7 +24,18 @@ import type { EventController } from "../event-controller.js";
 import { RootErrorBoundary } from "../../root-error-boundary.js";
 import type { HandleData } from "../types.js";
 import { ThemeProvider } from "../../theme/ThemeProvider.js";
+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";
+import { startConnectionWarmup } from "../connection-warmup.js";
+import { debugLog } from "../logging.js";
+import { cloneHandleData } from "../navigation-store.js";
+import {
+  deferredHandleNames,
+  resolveDeferredHandleValues,
+} from "../../handles/deferred-resolution.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -41,10 +54,35 @@ 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;
+
+  // 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
+  // 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();
+
+  // True while this nav still owns the live page: same history key AND the most
+  // recent commit is still ours (no newer nav has committed since).
+  const stillLive = (): boolean =>
+    historyKey === store.getHistoryKey() &&
+    myInstance === store.getNavInstance();
 
   let yieldCount = 0;
   for await (const handleData of handlesGenerator) {
@@ -52,14 +90,96 @@ async function processHandles(
     // This prevents handle data from cancelled navigations polluting
     // the current route's breadcrumbs (e.g., quick popstate after clicking a link).
     if (historyKey !== store.getHistoryKey()) {
-      console.log(
-        "[NavigationProvider] Stopping handle processing - user navigated away"
+      debugLog(
+        "[NavigationProvider] Stopping handle processing - user navigated away",
       );
       return;
     }
 
     yieldCount++;
-    eventController.setHandleData(handleData, matched, isPartial);
+
+    // Resolve-by-default: hold the previous resolved value until this yield's
+    // deferred (Promise) handle values settle, then apply the fully-resolved
+    // snapshot. The hold needs NO extra state — we simply do not touch the store
+    // until the values resolve, so useHandle keeps reading (and showing) the
+    // previous data. A yield with no deferred value applies synchronously.
+    const hasDeferred = deferredHandleNames(handleData).size > 0;
+
+    if (!hasDeferred) {
+      eventController.setHandleData(
+        handleData,
+        matched,
+        isPartial,
+        resolvedIds,
+      );
+      // Keep the cache fresh. The token guard stops a stale same-URL nav writing
+      // a newer entry.
+      if (store.getCacheEntryInstance(historyKey) === myInstance) {
+        store.updateCacheHandleData(
+          historyKey,
+          eventController.getHandleState().data,
+          false,
+        );
+      }
+      continue;
+    }
+
+    // The PREVIOUS (held) snapshot — captured before the await so the cache and
+    // the navigate-away merge below reflect what useHandle is still showing.
+    const previousSnapshot = cloneHandleData(
+      eventController.getHandleState().data,
+    );
+
+    // The route HAS changed even though the handle data is held, so update
+    // `routeSegmentIds` (what useSegments reads) now. This leaves `data` /
+    // `segmentOrder` (what useHandle collects over) untouched, so useHandle keeps
+    // holding its previous value while useSegments reflects the new route.
+    eventController.setRouteSegmentIds(matched ?? []);
+
+    // Deferred-pending: the new values are not applied yet (the previous value is
+    // held), so the cache entry must NOT be served as fresh on a popstate return.
+    // Mark it STALE + handlesPending (token-guarded), storing the PREVIOUS (held)
+    // snapshot. P1 fix: a deferred value is a SERVER-side promise streamed via
+    // Flight, so a navigate-away ABORTS the stream and the resolve below never
+    // settles. stale makes a popstate return revalidate; handlesPending makes that
+    // revalidation a FULL re-render (no client segment IDs) so the server
+    // re-streams the handles — a diff-only revalidation would omit the unchanged
+    // segments' handles and the deferred value would never land (see the
+    // segmentIds branch in navigation-bridge.ts).
+    if (store.getCacheEntryInstance(historyKey) === myInstance) {
+      store.updateCacheHandleData(historyKey, previousSnapshot, true, true);
+    }
+
+    // Resolve every deferred value (allSettled; rejected + nullish dropped, sync
+    // values pass through). Each stream yield is a full cumulative snapshot.
+    const resolved = await resolveDeferredHandleValues(handleData);
+
+    if (!stillLive()) {
+      // Navigated away (or a same-URL nav superseded us) while resolving. We do
+      // NOT write `resolved` into the entry. It is THIS yield's snapshot only (on a
+      // partial nav, just the re-resolved segments' buckets), and a correct write
+      // needs setHandleData's nested per-segment merge + matched/resolvedIds
+      // cleanup: HandleData is handleName -> segmentId -> entries[], so a
+      // handle-name-level spread would drop a shared layout bucket (e.g. a
+      // Breadcrumbs layout crumb under L0 when the route pushed under R0) and would
+      // mark stale previous-route buckets fresh. We cannot run that merge here
+      // without touching the now-different live page. Instead leave the entry as it
+      // was marked before the await — stale + handlesPending — so a popstate return
+      // revalidates with a full re-render and re-streams the handles. A newer nav
+      // owning the entry has already overwritten it; nothing to do either way.
+      continue;
+    }
+
+    // Still live: apply the fully-resolved snapshot and refresh the cache fresh.
+    eventController.setHandleData(resolved, matched, isPartial, resolvedIds);
+    if (store.getCacheEntryInstance(historyKey) === myInstance) {
+      store.updateCacheHandleData(
+        historyKey,
+        eventController.getHandleState().data,
+        false,
+        false,
+      );
+    }
   }
 
   // Check again before final updates
@@ -67,19 +187,19 @@ 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.
   // This fixes a race condition where commit() caches stale handleData before
   // the async handles processing completes.
-  // Only update if we're still on the same page (historyKey matches).
-  if (historyKey === store.getHistoryKey()) {
+  // Only update if we're still on the same page AND this is still the live nav
+  // (the token guard stops a stale same-URL nav writing a newer nav's state).
+  if (stillLive()) {
     const finalHandleData = eventController.getHandleState().data;
     store.updateCacheHandleData(historyKey, finalHandleData);
   }
@@ -100,9 +220,9 @@ export interface NavigationProviderProps {
   eventController: EventController;
 
   /**
-   * Initial RSC payload from server
+   * Initial rendered tree + metadata from server payload
    */
-  initialPayload: RscPayload;
+  initialPayload: NavigationUpdate;
 
   /**
    * Navigation bridge for handling navigation
@@ -126,6 +246,35 @@ export interface NavigationProviderProps {
    * When true, keeps TLS alive by sending HEAD requests after idle periods.
    */
   warmupEnabled?: boolean;
+
+  /**
+   * 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;
+
+  /**
+   * App-shell ref. When provided, the context's `basename` and `version` are
+   * read through it (live getters) so they don't close over a stale snapshot or
+   * invalidate the memoized context value. The shell is set once at init and is
+   * not swapped within a session — a cross-app navigation is a full document
+   * load (X-RSC-Reload), so the target app establishes its own shell on load.
+   */
+  appShellRef?: AppShellRef;
+
+  /**
+   * CSP nonce to expose via NonceContext. Production leaves this undefined — the
+   * browser has no nonce (it is a server-side HTML concern), and SSR provides the
+   * nonce through its own NonceContext.Provider. Test harnesses (renderRoute) set
+   * it to seed a nonce so components calling useNonce() can be exercised.
+   */
+  nonce?: string;
 }
 
 /**
@@ -157,6 +306,10 @@ export function NavigationProvider({
   themeConfig,
   initialTheme,
   warmupEnabled,
+  version,
+  basename,
+  appShellRef,
+  nonce,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -168,7 +321,7 @@ export function NavigationProvider({
     async (url: string, options?: NavigateOptions): Promise<void> => {
       await bridge.navigate(url, options);
     },
-    []
+    [],
   );
 
   /**
@@ -178,107 +331,101 @@ 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. Both are set once: a supplied appShellRef is seeded
+  // from the init payload (a cross-app navigation reloads, so it is not swapped
+  // in-session), and the standalone fallback wraps 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,
-    }),
-    []
-  );
+    } 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".
-  // On next interaction or visibility change, sends a HEAD request to warm TLS
-  // before the user actually clicks a link.
+  // Connection warmup: keep TLS alive after idle periods. After 60s of no
+  // interaction the connection is marked cold; the next pointer/touch
+  // interaction or visibility change warms TLS via a HEAD request before the
+  // user clicks a link. State machine lives in connection-warmup.ts.
   useEffect(() => {
     if (!warmupEnabled) return;
+    return startConnectionWarmup();
+  }, [warmupEnabled]);
 
-    const IDLE_TIMEOUT = 60_000;
-    const DEBOUNCE_DELAY = 150;
-
-    let idleTimer: ReturnType<typeof setTimeout> | undefined;
-    let debounceTimer: ReturnType<typeof setTimeout> | undefined;
-    let isCold = false;
-    let warmupListenersAttached = false;
-
-    function sendWarmup() {
-      isCold = false;
-      fetch("/?_rsc_warmup", { method: "HEAD" }).catch(() => {});
-    }
-
-    function triggerWarmup() {
-      if (!isCold) return;
-      clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(() => {
-        sendWarmup();
-        detachWarmupListeners();
-        resetIdleTimer();
-      }, DEBOUNCE_DELAY);
-    }
-
-    function onVisibilityChange() {
-      if (document.visibilityState === "visible" && isCold) {
-        triggerWarmup();
+  // Cancel non-matching prefetches when navigation starts.
+  // Frees connections so the navigation fetch isn't competing with
+  // speculative prefetches. The prefetch matching the navigation target
+  // is kept alive so it can be reused via consumeInflightPrefetch.
+  useEffect(() => {
+    let wasIdle = true;
+    const unsub = eventController.subscribe(() => {
+      const state = eventController.getState();
+      const isIdle = state.state === "idle" && !state.isStreaming;
+      if (wasIdle && !isIdle) {
+        cancelAllPrefetches(state.pendingUrl);
       }
-    }
-
-    function attachWarmupListeners() {
-      if (warmupListenersAttached) return;
-      warmupListenersAttached = true;
-      document.addEventListener("visibilitychange", onVisibilityChange);
-      document.addEventListener("mousemove", triggerWarmup, { once: true });
-      document.addEventListener("touchstart", triggerWarmup, { once: true });
-    }
-
-    function detachWarmupListeners() {
-      warmupListenersAttached = false;
-      document.removeEventListener("visibilitychange", onVisibilityChange);
-      document.removeEventListener("mousemove", triggerWarmup);
-      document.removeEventListener("touchstart", triggerWarmup);
-    }
-
-    function markCold() {
-      isCold = true;
-      attachWarmupListeners();
-    }
-
-    function resetIdleTimer() {
-      clearTimeout(idleTimer);
-      isCold = false;
-      idleTimer = setTimeout(markCold, IDLE_TIMEOUT);
-    }
+      wasIdle = isIdle;
+    });
+    return unsub;
+  }, [eventController]);
 
-    // Activity events that reset the idle timer
-    const activityEvents = ["mousemove", "keydown", "touchstart", "scroll"] as const;
-    const activityOptions: AddEventListenerOptions = { passive: true };
+  // Pending scroll action to apply after React commits
+  const pendingScrollRef = useRef<NavigationUpdate["scroll"]>(undefined);
 
-    for (const event of activityEvents) {
-      document.addEventListener(event, resetIdleTimer, activityOptions);
-    }
+  // Apply scroll after React commits the new content to the DOM
+  useLayoutEffect(() => {
+    const scrollAction = pendingScrollRef.current;
+    if (!scrollAction) return;
+    pendingScrollRef.current = undefined;
 
-    resetIdleTimer();
+    if (scrollAction.enabled === false) return;
 
-    return () => {
-      clearTimeout(idleTimer);
-      clearTimeout(debounceTimer);
-      detachWarmupListeners();
-      for (const event of activityEvents) {
-        document.removeEventListener(event, resetIdleTimer);
-      }
-    };
-  }, [warmupEnabled]);
+    handleNavigationEnd({
+      restore: scrollAction.restore,
+      scroll: scrollAction.enabled,
+      isStreaming: scrollAction.isStreaming,
+    });
+  });
 
   // Subscribe to UI updates (for re-rendering the tree)
   useEffect(() => {
     const unsubscribe = store.onUpdate((update) => {
+      // Capture scroll intent — it will be applied in useLayoutEffect
+      // after React commits this state update to the DOM.
+      // Always assign (even undefined) to clear stale scroll from prior navigations,
+      // so server actions or error updates don't accidentally replay old scroll.
+      pendingScrollRef.current = update.scroll;
+
       setPayload({
         root: update.root,
         metadata: update.metadata,
       });
 
+      // 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) {
         // Capture historyKey now - by the time async processing completes,
@@ -290,24 +437,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
+          console.error("[NavigationProvider] Error consuming handles:", err),
         );
       } 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,
         );
       }
     });
@@ -320,7 +463,8 @@ export function NavigationProvider({
     payload.root instanceof Promise ? use(payload.root) : payload.root;
 
   // Wrap content in RootErrorBoundary to catch:
-  // 1. Errors from NetworkErrorThrower (rendered during network failures)
+  // 1. Errors from RenderErrorThrower (network failures and unprocessable
+  //    navigation responses, routed here by the navigation bridge)
   // 2. Client component errors that occur before/outside the segment tree's error boundary
   // 3. Errors during promise resolution or navigation state updates
   // This acts as a safety net - the segment tree has its own RootErrorBoundary that
@@ -329,7 +473,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 persists for
+  // the session. It sits above the segment tree and is not remounted in-session;
+  // a cross-app navigation is a full document load (X-RSC-Reload), so the target
+  // app's theme config takes effect on its own load.
   if (themeConfig) {
     content = (
       <ThemeProvider config={themeConfig} initialTheme={initialTheme}>
@@ -338,6 +486,14 @@ export function NavigationProvider({
     );
   }
 
+  // Match SSR tree shape: NonceContext.Provider is always present so
+  // hydration sees the same component tree. Value is undefined on the
+  // client — CSP nonces are a server-side HTML concern — unless a test
+  // harness seeded one via the `nonce` prop.
+  content = (
+    <NonceContext.Provider value={nonce}>{content}</NonceContext.Provider>
+  );
+
   return (
     <NavigationStoreContext.Provider value={contextValue}>
       {content}

package/src/browser/react/ScrollRestoration.tsx

@@ -14,17 +14,21 @@ export interface ScrollRestorationProps {
    * Return location.pathname to restore scroll based on path
    * (useful for keeping scroll position on the same page).
    *
+   * Provide a stable reference: a module-level function or one wrapped in
+   * useCallback. The init effect re-runs when getKey's identity changes, and
+   * teardown clears in-memory scroll positions — a fresh inline arrow on every
+   * parent render would discard unpersisted positions mid-session.
+   *
    * @example
    * ```tsx
+   * // Stable module-level getKey (recommended)
+   * const byPathname = (location) => location.pathname;
+   *
    * // Restore based on pathname (same URL = same scroll)
-   * <ScrollRestoration
-   *   getKey={(location) => location.pathname}
-   * />
+   * <ScrollRestoration getKey={byPathname} />
    *
    * // Restore based on unique history entry (default)
-   * <ScrollRestoration
-   *   getKey={(location) => location.key}
-   * />
+   * // <ScrollRestoration /> — omit getKey to use location.key
    * ```
    */
   getKey?: (location: {

package/src/browser/react/context.ts

@@ -41,6 +41,17 @@ export interface NavigationStoreContextValue {
    * @returns Promise that resolves when refresh is complete
    */
   refresh: () => Promise<void>;
+
+  /**
+   * App version from the initial server payload.
+   */
+  version: string | undefined;
+
+  /**
+   * URL prefix for all routes (from createRouter({ basename })).
+   * Used by Link and useRouter() to auto-prefix app-local paths.
+   */
+  basename: string | undefined;
 }
 
 /**

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

@@ -0,0 +1,70 @@
+/**
+ * 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[] {
+  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);
+  }
+  for (const [parent, slots] of slotsByParent) {
+    if (!nonSlotSet.has(parent)) result.push(...slots);
+  }
+  return result;
+}
+
+/**
+ * Build the "layouts and routes only" id list for useSegments().segmentIds.
+ *
+ * Strips parallel slot ids (contain ".@") and loader sub-ids ("D" followed by
+ * a digit, e.g. "M0L0D1.user") without reordering. Distinct from
+ * filterSegmentOrder, which also reorders slots after their parent for handle
+ * collection.
+ *
+ * Shared by SSR (ssr/index.tsx) and the client event controller
+ * (event-controller.ts) so both produce identical output; if they diverge,
+ * useSegments().segmentIds rendered during SSR and after hydration disagree
+ * and React reports a hydration mismatch.
+ */
+export function filterRouteSegmentIds(matched: string[]): string[] {
+  return matched.filter((id) => !id.includes(".@") && !/D\d+\./.test(id));
+}