@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/browser/react/NavigationProvider.tsx

@@ -29,6 +29,13 @@ 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
@@ -64,20 +71,117 @@ async function processHandles(
     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) {
     // Check if user navigated away before each update.
     // 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(
+      debugLog(
         "[NavigationProvider] Stopping handle processing - user navigated away",
       );
       return;
     }
 
     yieldCount++;
-    eventController.setHandleData(handleData, matched, isPartial, resolvedIds);
+
+    // 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; the owned-write folds probe + write into one scan.
+      store.updateCacheHandleDataIfOwned(
+        historyKey,
+        eventController.getHandleState().data,
+        myInstance,
+        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).
+    store.updateCacheHandleDataIfOwned(
+      historyKey,
+      previousSnapshot,
+      myInstance,
+      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);
+    store.updateCacheHandleDataIfOwned(
+      historyKey,
+      eventController.getHandleState().data,
+      myInstance,
+      false,
+      false,
+    );
   }
 
   // Check again before final updates
@@ -95,8 +199,9 @@ async function processHandles(
   // 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);
   }
@@ -157,11 +262,21 @@ export interface NavigationProviderProps {
   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.
+   * 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;
 }
 
 /**
@@ -196,6 +311,7 @@ export function NavigationProvider({
   version,
   basename,
   appShellRef,
+  nonce,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -218,8 +334,9 @@ export function NavigationProvider({
   }, []);
 
   // 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.
+  // 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 });
@@ -246,91 +363,13 @@ export function NavigationProvider({
     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;
-
-    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();
-      }
-    }
-
-    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);
-    }
-
-    // Activity events that reset the idle timer
-    const activityEvents = [
-      "mousemove",
-      "keydown",
-      "touchstart",
-      "scroll",
-    ] as const;
-    const activityOptions: AddEventListenerOptions = { passive: true };
-
-    for (const event of activityEvents) {
-      document.addEventListener(event, resetIdleTimer, activityOptions);
-    }
-
-    resetIdleTimer();
-
-    return () => {
-      clearTimeout(idleTimer);
-      clearTimeout(debounceTimer);
-      detachWarmupListeners();
-      for (const event of activityEvents) {
-        document.removeEventListener(event, resetIdleTimer);
-      }
-    };
+    return startConnectionWarmup();
   }, [warmupEnabled]);
 
   // Cancel non-matching prefetches when navigation starts.
@@ -426,7 +465,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
@@ -436,10 +476,10 @@ export function NavigationProvider({
   let content = <RootErrorBoundary>{root}</RootErrorBoundary>;
 
   // 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.
+  // 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}>
@@ -450,9 +490,10 @@ 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.
+  // client — CSP nonces are a server-side HTML concern — unless a test
+  // harness seeded one via the `nonce` prop.
   content = (
-    <NonceContext.Provider value={undefined}>{content}</NonceContext.Provider>
+    <NonceContext.Provider value={nonce}>{content}</NonceContext.Provider>
   );
 
   return (

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/filter-segment-order.ts

@@ -46,10 +46,25 @@ export function filterSegmentOrder(matched: string[]): string[] {
     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;
 }
+
+/**
+ * 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));
+}

package/src/browser/react/index.ts

@@ -1,55 +1,4 @@
-// React exports for browser navigation
-
-// Hook with Zustand-style selectors
-export { useNavigation } from "./use-navigation.js";
-
-// Router actions hook (stable reference, no re-renders)
-export { useRouter } from "./use-router.js";
-
-// URL hooks
-export { usePathname } from "./use-pathname.js";
-export { useSearchParams } from "./use-search-params.js";
-export { useParams } from "./use-params.js";
-
-// Action state tracking hook
-export { useAction, type TrackedActionState } from "./use-action.js";
-
-// Segments state hook
-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,
-  type ClientCacheControls,
-} from "./use-client-cache.js";
-
-// Provider
 export {
   NavigationProvider,
   type NavigationProviderProps,
 } from "./NavigationProvider.js";
-
-// Context (for advanced usage)
-export {
-  NavigationStoreContext,
-  type NavigationStoreContextValue,
-} from "./context.js";
-
-// Link component
-export { Link, type LinkProps, type PrefetchStrategy } from "./Link.js";
-
-// Link status hook
-export { useLinkStatus, type LinkStatus } from "./use-link-status.js";
-
-// Scroll restoration
-export {
-  ScrollRestoration,
-  useScrollRestoration,
-  type ScrollRestorationProps,
-} from "./ScrollRestoration.js";

package/src/browser/react/location-state-shared.ts

@@ -1,8 +1,3 @@
-/**
- * Shared location state utilities - works in both RSC and client contexts
- * No "use client" directive so it can be imported from RSC
- */
-
 import type { ReactElement } from "react";
 
 /**
@@ -26,16 +21,8 @@ export interface LocationStateOptions {
 
 type LocationStateUnsafeFn = (...args: never[]) => unknown;
 
-// Broadest constructor signature (`abstract` covers both abstract and concrete
-// classes). A class passed as state has a `new` signature, not a call signature,
-// so it slips past LocationStateUnsafeFn; at runtime the lazy-getter path
-// (`typeof value === "function"`) then mistakes it for a getter and throws.
 type LocationStateUnsafeCtor = abstract new (...args: never[]) => unknown;
 
-// `unknown` cannot be verified serializable, so it is rejected (callers must
-// supply a concrete type). `any` deliberately defeats type checking and is NOT
-// guardable — it is assignable to the branded error too, so the check always
-// passes; it remains an explicit escape hatch.
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type IsUnknown<T> =
   IsAny<T> extends true ? false : unknown extends T ? true : false;
@@ -268,7 +255,14 @@ export function createLocationState<TState>(
         );
       }
       const key = getKey();
-      const current = window.history.state ?? {};
+      // history.state may be a non-null primitive (string/number/boolean) if
+      // non-Rango code called pushState/replaceState with one. `?? {}` only
+      // catches null/undefined, so spreading a primitive would yield indexed
+      // char/no keys and corrupt history.state. Coerce any non-object to a fresh
+      // dict — mirrors the delete() guard.
+      const existing = window.history.state;
+      const current =
+        existing !== null && typeof existing === "object" ? existing : {};
       window.history.replaceState(
         { ...current, [key]: value },
         "",
@@ -288,7 +282,12 @@ export function createLocationState<TState>(
       }
       const key = getKey();
       const current = window.history.state;
-      if (current == null || !(key in current)) return;
+      // history.state may be a non-null primitive (string/number/boolean) if
+      // non-Rango code called pushState/replaceState with one. `key in
+      // <primitive>` throws, so require an object before the `in` check; a
+      // primitive carries no slots, so deletion is a no-op.
+      if (current === null || typeof current !== "object" || !(key in current))
+        return;
       const next = { ...current };
       delete next[key];
       window.history.replaceState(next, "", window.location.href);

package/src/browser/react/location-state.ts

@@ -3,7 +3,6 @@
 import { useState, useEffect, useRef } from "react";
 import type { LocationStateDefinition } from "./location-state-shared.js";
 
-// Re-export shared utilities and types
 export {
   createLocationState,
   isLocationStateEntry,

package/src/browser/react/use-action.ts

@@ -24,32 +24,24 @@ const DEFAULT_ACTION_STATE: TrackedActionState = {
   result: null,
 };
 
-/**
- * Normalize action ID - returns the ID as-is
- *
- * Server actions have IDs like "hash#actionName" or "src/actions.ts#actionName".
- * When using function references, we use the full ID for exact matching.
- * When using strings, the event controller supports suffix matching
- * (e.g., "addToCart" matches "hash#addToCart").
- */
-function normalizeActionId(actionId: string): string {
-  return actionId;
-}
-
 /**
  * Extract action ID from a server action function or string.
  *
  * Actions passed as props from server components lose their metadata
  * during RSC serialization - use a string action name instead.
+ *
+ * The extracted $$id (e.g. "hash#actionName" or "src/actions.ts#actionName")
+ * is returned as-is. Suffix-vs-exact matching against this ID happens
+ * downstream in the event controller, not here.
  */
-export function getActionId(action: ServerActionFunction | string): string {
+function getActionId(action: ServerActionFunction | string): string {
   invariant(
     typeof action === "function" || typeof action === "string",
     `useAction: action must be a function or string, got ${typeof action}`,
   );
   const actionId = (action as any)?.$$id;
   if (actionId) {
-    return normalizeActionId(actionId);
+    return actionId;
   }
 
   // If action is a string, use it directly
@@ -162,7 +154,6 @@ export function useAction<T>(
   });
   const prevSelected = useRef(baseState);
   prevSelected.current = baseState;
-  // useOptimistic allows immediate updates during transitions/actions
   const [optimisticState, setOptimisticState] = useOptimistic<
     T | TrackedActionState
   >(null!);

package/src/browser/react/use-handle.ts

@@ -43,7 +43,6 @@ export function useHandle<T, A, S>(
 ): Rango.FlightSerialize<A> | S {
   const ctx = useContext(NavigationStoreContext);
 
-  // Initial state from context event controller, or empty fallback without provider.
   const [value, setValue] = useState<Rango.FlightSerialize<A> | S>(() => {
     if (!ctx) {
       const collected = collectHandleData(
@@ -54,7 +53,6 @@ export function useHandle<T, A, S>(
       return selector ? selector(collected) : collected;
     }
 
-    // On client, use event controller state
     const state = ctx.eventController.getHandleState();
     const collected = collectHandleData(
       handle,
@@ -65,15 +63,12 @@ export function useHandle<T, A, S>(
   });
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
 
-  // Track previous value for shallow comparison
   const prevValueRef = useRef(value);
   prevValueRef.current = value;
 
-  // Ref keeps the latest selector without re-subscribing on every render.
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
-  // Subscribe to handle data changes (client only)
   useEffect(() => {
     if (!ctx) return;
 

package/src/browser/react/use-href.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useCallback } from "react";
 import { href, type ValidPaths } from "../../href-client.js";
 import { useMount } from "./use-mount.js";
 
@@ -36,5 +37,11 @@ import { useMount } from "./use-mount.js";
  */
 export function useHref(): (path: `/${string}`) => string {
   const mount = useMount();
-  return (path: `/${string}`) => href(path as ValidPaths, mount);
+  // Memoize on `mount` (stable within a route) so the returned function is
+  // referentially stable across re-renders — a consumer can safely pass it as a
+  // dependency or a prop to a memoized child without forcing re-renders.
+  return useCallback(
+    (path: `/${string}`) => href(path as ValidPaths, mount),
+    [mount],
+  );
 }