@rangojs/router 0.0.0-experimental.9 → 0.0.0-experimental.90

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,11 @@ 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 type { AppShellRef } from "../app-shell.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -42,7 +48,7 @@ async function processHandles(
     matched?: string[];
     isPartial?: boolean;
     historyKey: string;
-  }
+  },
 ): Promise<void> {
   const { eventController, store, matched, isPartial, historyKey } = opts;
 
@@ -53,7 +59,7 @@ async function processHandles(
     // 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"
+        "[NavigationProvider] Stopping handle processing - user navigated away",
       );
       return;
     }
@@ -100,9 +106,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 +132,25 @@ 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;
+
+  /**
+   * 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;
 }
 
 /**
@@ -157,6 +182,9 @@ export function NavigationProvider({
   themeConfig,
   initialTheme,
   warmupEnabled,
+  version,
+  basename,
+  appShellRef,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -168,7 +196,7 @@ export function NavigationProvider({
     async (url: string, options?: NavigateOptions): Promise<void> => {
       await bridge.navigate(url, options);
     },
-    []
+    [],
   );
 
   /**
@@ -178,16 +206,39 @@ export function NavigationProvider({
     await bridge.refresh();
   }, []);
 
-  // Context value is stable (store, eventController, navigate, refresh never change)
-  const contextValue = useMemo<NavigationStoreContextValue>(
-    () => ({
+  // Context value is stable (store, eventController, navigate, refresh never
+  // change). When an appShellRef is supplied, `basename` and `version` are
+  // installed as live getters so app-switch transitions (which update the ref)
+  // propagate to consumers without forcing a tree-wide rerender.
+  const contextValue = useMemo<NavigationStoreContextValue>(() => {
+    if (appShellRef) {
+      const value = {
+        store,
+        eventController,
+        navigate,
+        refresh,
+      } as NavigationStoreContextValue;
+      Object.defineProperty(value, "basename", {
+        configurable: true,
+        enumerable: true,
+        get: () => appShellRef.get().basename,
+      });
+      Object.defineProperty(value, "version", {
+        configurable: true,
+        enumerable: true,
+        get: () => appShellRef.get().version,
+      });
+      return value;
+    }
+    return {
       store,
       eventController,
       navigate,
       refresh,
-    }),
-    []
-  );
+      version,
+      basename,
+    };
+  }, []);
 
   // Connection warmup: keep TLS alive after idle periods.
   // After 60s of no user interaction, marks connection as "cold".
@@ -252,7 +303,12 @@ export function NavigationProvider({
     }
 
     // Activity events that reset the idle timer
-    const activityEvents = ["mousemove", "keydown", "touchstart", "scroll"] as const;
+    const activityEvents = [
+      "mousemove",
+      "keydown",
+      "touchstart",
+      "scroll",
+    ] as const;
     const activityOptions: AddEventListenerOptions = { passive: true };
 
     for (const event of activityEvents) {
@@ -271,14 +327,62 @@ export function NavigationProvider({
     };
   }, [warmupEnabled]);
 
+  // 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);
+      }
+      wasIdle = isIdle;
+    });
+    return unsub;
+  }, [eventController]);
+
+  // Pending scroll action to apply after React commits
+  const pendingScrollRef = useRef<NavigationUpdate["scroll"]>(undefined);
+
+  // Apply scroll after React commits the new content to the DOM
+  useLayoutEffect(() => {
+    const scrollAction = pendingScrollRef.current;
+    if (!scrollAction) return;
+    pendingScrollRef.current = undefined;
+
+    if (scrollAction.enabled === false) return;
+
+    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,
@@ -292,7 +396,7 @@ export function NavigationProvider({
           isPartial: update.metadata.isPartial,
           historyKey,
         }).catch((err) =>
-          console.error("[NavigationProvider] Error consuming handles:", err)
+          console.error("[NavigationProvider] Error consuming handles:", err),
         );
       } else if (update.metadata.cachedHandleData) {
         // For back/forward navigation from cache, restore the cached handleData
@@ -300,14 +404,14 @@ export function NavigationProvider({
         eventController.setHandleData(
           update.metadata.cachedHandleData,
           update.metadata.matched,
-          false // full replace - restore entire cached state
+          false, // full replace - restore entire cached state
         );
       } else if (update.metadata.matched) {
         // For cached navigations without handleData, update segmentOrder to clean up stale data
         eventController.setHandleData(
           {}, // Empty data - all existing data not in matched will be cleaned up
           update.metadata.matched,
-          true // partial update - will clean up segments not in matched
+          true, // partial update - will clean up segments not in matched
         );
       }
     });
@@ -329,7 +433,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}>
@@ -338,6 +446,13 @@ 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.
+  content = (
+    <NonceContext.Provider value={undefined}>{content}</NonceContext.Provider>
+  );
+
   return (
     <NavigationStoreContext.Provider value={contextValue}>
       {content}

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,11 @@
+/**
+ * Filter segment IDs to only include routes and layouts.
+ * Excludes parallels (contain .@) and loaders (contain D followed by digit).
+ */
+export function filterSegmentOrder(matched: string[]): string[] {
+  return matched.filter((id) => {
+    if (id.includes(".@")) return false;
+    if (/D\d+\./.test(id)) return false;
+    return true;
+  });
+}

package/src/browser/react/index.ts

@@ -1,20 +1,24 @@
 // React exports for browser navigation
 
 // Hook with Zustand-style selectors
-export {
-  useNavigation,
-  type NavigationMethods,
-  type NavigationValue,
-} from "./use-navigation.js";
+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, initSegmentsSync, type SegmentsState } from "./use-segments.js";
+export { useSegments, type SegmentsState } from "./use-segments.js";
 
 // Handle data hook
-export { useHandle, initHandleDataSync } from "./use-handle.js";
+export { useHandle } from "./use-handle.js";
 
 // Client cache controls hook
 export {
@@ -35,11 +39,7 @@ export {
 } from "./context.js";
 
 // Link component
-export {
-  Link,
-  type LinkProps,
-  type PrefetchStrategy,
-} from "./Link.js";
+export { Link, type LinkProps, type PrefetchStrategy } from "./Link.js";
 
 // Link status hook
 export { useLinkStatus, type LinkStatus } from "./use-link-status.js";

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

@@ -4,11 +4,22 @@
  */
 
 /**
- * Internal entry representing a state value with its unique key
+ * Internal entry representing a state value with its unique key.
+ * When __rsc_ls_lazy is true, __rsc_ls_value holds a getter function
+ * that is called at navigation time (not at entry creation time).
  */
 export interface LocationStateEntry {
   readonly __rsc_ls_key: string;
   readonly __rsc_ls_value: unknown;
+  readonly __rsc_ls_lazy?: boolean;
+}
+
+/**
+ * Options for createLocationState
+ */
+export interface LocationStateOptions {
+  /** When true, the state is cleared from history after first read (flash message pattern) */
+  flash?: boolean;
 }
 
 /**
@@ -19,84 +30,113 @@ export interface LocationStateEntry {
  */
 export interface LocationStateDefinition<TArgs extends unknown[], TState> {
   (...args: TArgs): LocationStateEntry;
-  readonly __rsc_ls_key: string;
+  /** Injected by Vite plugin - do not set manually */
+  __rsc_ls_key: string;
+  /** Whether this state auto-clears after first read */
+  readonly __rsc_ls_flash: boolean;
+  /** Read the current value from history.state (client-side only, undefined during SSR) */
+  read(): TState | undefined;
 }
 
-// Track used keys to detect duplicates in development
-const usedKeys = new Set<string>();
-
 /**
  * Create a type-safe location state definition
  *
- * The key is auto-generated by the Vite exposeLocationStateId plugin based on
- * file path and export name. No manual key required.
+ * The key is auto-injected by the Vite exposeInternalIds plugin as a property
+ * based on file path and export name. No manual key required.
  *
- * @param key Auto-injected by Vite plugin, do not provide manually
+ * @param options Optional configuration
  * @returns A typed state definition for use with Link and useLocationState
  *
  * @example
  * ```typescript
- * // Define typed state (key auto-generated from file + export)
+ * // Persistent state (survives back/forward)
  * export const ProductState = createLocationState<{ name: string; price: number }>();
  *
- * // Use in Link - state is captured at click time
- * <Link to="/product/123" state={[ProductState({ name: product.name, price: product.price })]}>
- *   View Product
- * </Link>
+ * // Flash state (cleared after first read)
+ * export const FlashMessage = createLocationState<{ text: string }>({ flash: true });
  *
- * // Multiple states
- * <Link to="/checkout" state={[ProductState(productData), CartState(cartData)]}>
- *   Checkout
- * </Link>
+ * // Use in Link
+ * <Link to="/product/123" state={[ProductState({ name: "Widget", price: 9.99 })]}>
  *
- * // For lazy evaluation (click-time), pass a getter
- * <Link to="/product" state={[ProductState(() => ({ name: product.name }))]}>
+ * // Just-in-time typed state (getter called at click time, not render time).
+ * // Must be in a client component — the getter function can't cross the RSC boundary.
+ * <Link
+ *   to="/product/123"
+ *   state={[ProductState(() => ({ name: product.name, price: product.price }))]}
+ * >
  *
- * // Read with type safety
- * const productState = useLocationState(ProductState);
- * // productState: { name: string; price: number } | undefined
+ * // Read with hook (reactive)
+ * const product = useLocationState(ProductState);
+ *
+ * // Read without hook (snapshot, client-side only)
+ * const snap = ProductState.read();
  * ```
  */
 export function createLocationState<TState>(
-  key?: string
+  options?: LocationStateOptions,
 ): LocationStateDefinition<[TState | (() => TState)], TState> {
-  if (!key && process.env.NODE_ENV !== "production") {
-    console.warn(
-      "[rsc-router] createLocationState is missing a key. " +
-        "Make sure the exposeLocationStateId Vite plugin is enabled and " +
-        "the state is exported with: export const MyState = createLocationState(...)"
-    );
-  }
-  const fullKey = `__rsc_ls_${key}`;
+  const flash = options?.flash ?? false;
+  let _key: string | undefined;
 
-  // Warn about duplicate keys in development
-  if (process.env.NODE_ENV !== "production" && usedKeys.has(fullKey)) {
-    console.warn(
-      `[rsc-router] Duplicate location state key "${key}". ` +
-        `Each createLocationState call should have a unique key.`
-    );
+  function getKey(): string {
+    if (!_key && process.env.NODE_ENV === "development") {
+      throw new Error(
+        "[rsc-router] createLocationState key not set. " +
+          "Make sure the exposeInternalIds Vite plugin is enabled and " +
+          "the state is exported with: export const MyState = createLocationState(...)",
+      );
+    }
+    return _key!;
   }
-  usedKeys.add(fullKey);
 
-  const definition = Object.assign(
-    (stateOrGetter: TState | (() => TState)): LocationStateEntry => ({
-      __rsc_ls_key: fullKey,
-      // Resolve getter immediately - lazy evaluation happens via Link's stateRef pattern
-      __rsc_ls_value:
-        typeof stateOrGetter === "function"
-          ? (stateOrGetter as () => TState)()
-          : stateOrGetter,
-    }),
-    { __rsc_ls_key: fullKey }
-  );
+  const fn = (stateOrGetter: TState | (() => TState)): LocationStateEntry => {
+    if (typeof stateOrGetter === "function") {
+      // Store getter as-is; resolved at navigation time by resolveLocationStateEntries()
+      return {
+        __rsc_ls_key: getKey(),
+        __rsc_ls_value: stateOrGetter,
+        __rsc_ls_lazy: true,
+      };
+    }
+    return {
+      __rsc_ls_key: getKey(),
+      __rsc_ls_value: stateOrGetter,
+    };
+  };
+
+  // Use defineProperty for __rsc_ls_key to avoid Object.assign evaluating
+  // the getter during construction (before the Vite plugin sets the key).
+  Object.defineProperty(fn, "__rsc_ls_key", {
+    get: () => getKey(),
+    set: (k: string) => {
+      _key = k;
+    },
+    enumerable: true,
+    configurable: true,
+  });
+
+  Object.defineProperty(fn, "__rsc_ls_flash", {
+    value: flash,
+    enumerable: true,
+  });
+
+  Object.defineProperty(fn, "read", {
+    value: (): TState | undefined => {
+      if (typeof window === "undefined") return undefined;
+      return window.history.state?.[getKey()] as TState | undefined;
+    },
+    enumerable: true,
+  });
 
-  return definition as LocationStateDefinition<[TState | (() => TState)], TState>;
+  return fn as LocationStateDefinition<[TState | (() => TState)], TState>;
 }
 
 /**
  * Check if a value is a LocationStateEntry
  */
-export function isLocationStateEntry(value: unknown): value is LocationStateEntry {
+export function isLocationStateEntry(
+  value: unknown,
+): value is LocationStateEntry {
   return (
     value !== null &&
     typeof value === "object" &&
@@ -110,11 +150,13 @@ export function isLocationStateEntry(value: unknown): value is LocationStateEntr
  * Resolve state entries into a flat object for history.state
  */
 export function resolveLocationStateEntries(
-  entries: LocationStateEntry[]
+  entries: LocationStateEntry[],
 ): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   for (const entry of entries) {
-    result[entry.__rsc_ls_key] = entry.__rsc_ls_value;
+    result[entry.__rsc_ls_key] = entry.__rsc_ls_lazy
+      ? (entry.__rsc_ls_value as () => unknown)()
+      : entry.__rsc_ls_value;
   }
   return result;
 }

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

@@ -10,53 +10,98 @@ export {
   resolveLocationStateEntries,
   type LocationStateEntry,
   type LocationStateDefinition,
+  type LocationStateOptions,
 } from "./location-state-shared.js";
 
 /**
  * Hook to read location state from history.state
  *
+ * Behavior depends on the definition:
+ * - Normal state: persists across navigations, reactive to popstate
+ * - Flash state (created with { flash: true }): read once, cleared after paint
+ *
  * Overloaded:
  * - With definition: Returns typed state from the specific key
- * - With type param only: Returns legacy state from history.state.state (backwards compat)
+ * - With type param only: Returns plain state from history.state.state
  *
  * @example
  * ```typescript
- * // Typed access with definition (recommended)
- * const ProductState = createLocationState<{ name: string }>("product");
+ * // Persistent state
+ * const ProductState = createLocationState<{ name: string }>();
  * const state = useLocationState(ProductState);
- * // state: { name: string } | undefined
  *
- * // Legacy typed access (backwards compatible)
- * const legacyState = useLocationState<{ from?: string }>();
+ * // Flash state (auto-clears after paint)
+ * const FlashMsg = createLocationState<{ text: string }>({ flash: true });
+ * const flash = useLocationState(FlashMsg);
+ *
+ * // Plain state access (reads from history.state.state)
+ * const state = useLocationState<{ from?: string }>();
  * ```
  */
 export function useLocationState<TArgs extends unknown[], TState>(
-  definition: LocationStateDefinition<TArgs, TState>
+  definition: LocationStateDefinition<TArgs, TState>,
 ): TState | undefined;
 export function useLocationState<T = unknown>(): T | undefined;
 export function useLocationState<TArgs extends unknown[], TState>(
-  definition?: LocationStateDefinition<TArgs, TState>
+  definition?: LocationStateDefinition<TArgs, TState>,
 ): TState | undefined {
+  const key = definition?.__rsc_ls_key;
+  const isFlash = definition?.__rsc_ls_flash ?? false;
+
   const [state, setState] = useState<TState | undefined>(() => {
     if (typeof window === "undefined") return undefined;
-    if (definition) {
-      return window.history.state?.[definition.__rsc_ls_key] as TState | undefined;
+    if (key) {
+      return window.history.state?.[key] as TState | undefined;
     }
-    // Legacy: return history.state.state for backwards compatibility
+    // Plain state: stored under history.state.state
     return window.history.state?.state as TState | undefined;
   });
 
+  // Subscribe to popstate and programmatic state changes
   useEffect(() => {
     const handlePopstate = () => {
-      if (definition) {
-        setState(window.history.state?.[definition.__rsc_ls_key] as TState | undefined);
+      if (key) {
+        setState(window.history.state?.[key] as TState | undefined);
       } else {
         setState(window.history.state?.state as TState | undefined);
       }
     };
+
+    // Handle programmatic state changes (same-page navigation with
+    // ctx.setLocationState where components don't remount)
+    const handleLocationState = () => {
+      if (key) {
+        const val = window.history.state?.[key] as TState | undefined;
+        if (isFlash) {
+          // For flash state, only update if there's a new value
+          if (val !== undefined) {
+            setState(val);
+          }
+        } else {
+          setState(val);
+        }
+      } else {
+        setState(window.history.state?.state as TState | undefined);
+      }
+    };
+
     window.addEventListener("popstate", handlePopstate);
-    return () => window.removeEventListener("popstate", handlePopstate);
-  }, [definition]);
+    window.addEventListener("__rsc_locationstate", handleLocationState);
+    return () => {
+      window.removeEventListener("popstate", handlePopstate);
+      window.removeEventListener("__rsc_locationstate", handleLocationState);
+    };
+  }, [key, isFlash]);
+
+  // Flash: clear from history.state after paint so subsequent navigations don't see it.
+  // Depends on `state` so it re-runs when state is set via the event listener.
+  useEffect(() => {
+    if (isFlash && key && state !== undefined) {
+      const cleaned = { ...window.history.state };
+      delete cleaned[key];
+      window.history.replaceState(cleaned, "", window.location.href);
+    }
+  }, [isFlash, key, state]);
 
   return state;
 }