@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/src/browser/prefetch/policy.ts

@@ -0,0 +1,42 @@
+/**
+ * Prefetch Policy
+ *
+ * Determines whether speculative prefetching should run for the current user.
+ * Honors browser reduced-data preferences when available.
+ */
+
+type NavigatorWithConnection = Navigator & {
+  connection?: {
+    saveData?: boolean;
+  };
+};
+
+/**
+ * Evaluate on every call so runtime changes to Save-Data or
+ * prefers-reduced-data are respected immediately.
+ */
+export function shouldPrefetch(): boolean {
+  if (typeof window === "undefined") return false;
+
+  const nav =
+    typeof navigator !== "undefined"
+      ? (navigator as NavigatorWithConnection)
+      : undefined;
+
+  if (nav?.connection?.saveData) return false;
+
+  if (typeof window.matchMedia === "function") {
+    try {
+      if (window.matchMedia("(prefers-reduced-data: reduce)").matches) {
+        return false;
+      }
+    } catch {
+      // Ignore unsupported query errors and allow prefetch.
+    }
+  }
+
+  return true;
+}
+
+/** No-op, kept for test compatibility. */
+export function resetPrefetchPolicy(): void {}

package/src/browser/{prefetch-queue.ts → prefetch/queue.ts}

@@ -28,8 +28,12 @@ function startExecution(
   executing.add(key);
   abortController ??= new AbortController();
   execute(abortController.signal).finally(() => {
-    active--;
-    executing.delete(key);
+    // Only decrement if this key wasn't already cleared by cancelAllPrefetches.
+    // Without this guard, cancelled tasks' .finally() would underflow active
+    // below zero, breaking the MAX_CONCURRENT guarantee.
+    if (executing.delete(key)) {
+      active--;
+    }
     drain();
   });
 }
@@ -76,6 +80,9 @@ export function cancelAllPrefetches(): void {
 
   queue.length = 0;
   queued.clear();
+  // Clear executing before resetting active. In-flight .finally() callbacks
+  // check executing.delete(key) — if the key is gone, they skip decrementing,
+  // so active settles at 0 without underflow.
   executing.clear();
-  // active count resets naturally as aborted fetches settle in .finally()
+  active = 0;
 }

package/src/browser/react/Link.tsx

@@ -31,11 +31,11 @@ export type LinkState =
   | LocationStateEntry[]
   | StateOrGetter<Record<string, unknown>>;
 
-import { prefetchDirect, prefetchQueued } from "../prefetch-fetch.js";
+import { prefetchDirect, prefetchQueued } from "../prefetch/fetch.js";
 import {
   observeForPrefetch,
   unobserveForPrefetch,
-} from "../prefetch-observer.js";
+} from "../prefetch/observer.js";
 
 // Touch device detection for hybrid strategy.
 // Checked once at module load (Link.tsx is "use client", runs only in browser).
@@ -235,31 +235,34 @@ export const Link: ForwardRefExoticComponent<
         return;
       }
 
+      // No navigation context (outside provider): fall back to native navigation.
+      if (!ctx?.navigate) {
+        return;
+      }
+
       // Prevent default and use SPA navigation
       e.preventDefault();
       // Stop propagation to prevent link-interceptor from also handling this
       e.stopPropagation();
 
-      if (ctx?.navigate) {
-        const currentState = stateRef.current;
-        let resolvedState: unknown;
-
-        if (
-          Array.isArray(currentState) &&
-          currentState.length > 0 &&
-          isLocationStateEntry(currentState[0])
-        ) {
-          resolvedState = resolveLocationStateEntries(
-            currentState as LocationStateEntry[],
-          );
-        } else if (typeof currentState === "function") {
-          resolvedState = currentState();
-        } else if (currentState != null) {
-          resolvedState = currentState;
-        }
-
-        ctx.navigate(to, { replace, scroll, state: resolvedState });
+      const currentState = stateRef.current;
+      let resolvedState: unknown;
+
+      if (
+        Array.isArray(currentState) &&
+        currentState.length > 0 &&
+        isLocationStateEntry(currentState[0])
+      ) {
+        resolvedState = resolveLocationStateEntries(
+          currentState as LocationStateEntry[],
+        );
+      } else if (typeof currentState === "function") {
+        resolvedState = currentState();
+      } else if (currentState != null) {
+        resolvedState = currentState;
       }
+
+      ctx.navigate(to, { replace, scroll, state: resolvedState });
     },
     [to, isExternal, reloadDocument, replace, scroll, ctx, onClick],
   );
@@ -281,6 +284,7 @@ export const Link: ForwardRefExoticComponent<
 
     let cancelled = false;
     let unsubIdle: (() => void) | undefined;
+    let observedElement: Element | null = null;
 
     const triggerPrefetch = () => {
       if (cancelled) return;
@@ -311,6 +315,7 @@ export const Link: ForwardRefExoticComponent<
     } else if (isViewport) {
       const element = internalRef.current;
       if (!element) return;
+      observedElement = element;
       observeForPrefetch(element, () => {
         scheduleWhenIdle(triggerPrefetch);
       });
@@ -319,8 +324,8 @@ export const Link: ForwardRefExoticComponent<
     return () => {
       cancelled = true;
       unsubIdle?.();
-      if (isViewport && internalRef.current) {
-        unobserveForPrefetch(internalRef.current);
+      if (isViewport && observedElement) {
+        unobserveForPrefetch(observedElement);
       }
     };
   }, [resolvedStrategy, to, isExternal, ctx]);

package/src/browser/react/NavigationProvider.tsx

@@ -22,8 +22,9 @@ 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 { cancelAllPrefetches } from "../prefetch/queue.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -370,6 +371,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/index.ts

@@ -15,14 +15,10 @@ export { useParams } from "./use-params.js";
 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 {

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

@@ -79,7 +79,7 @@ export function createLocationState<TState>(
   let _key: string | undefined;
 
   function getKey(): string {
-    if (!_key && process.env.NODE_ENV !== "production") {
+    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 " +

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

@@ -80,6 +80,8 @@ export function useLocationState<TArgs extends unknown[], TState>(
         } else {
           setState(val);
         }
+      } else {
+        setState(window.history.state?.state as TState | undefined);
       }
     };
 

package/src/browser/react/nonce-context.ts

@@ -0,0 +1,23 @@
+"use client";
+
+/**
+ * Context for CSP nonce propagation to client components during SSR.
+ *
+ * The SSR renderer wraps the tree with NonceContext.Provider so that
+ * client components (e.g. MetaTags) can apply nonces to inline scripts.
+ * On the browser side, no provider is needed — the default undefined
+ * is correct since CSP nonces are a server-side HTML concern.
+ */
+
+import { createContext, useContext, type Context } from "react";
+
+export const NonceContext: Context<string | undefined> = createContext<
+  string | undefined
+>(undefined);
+
+/**
+ * Read the CSP nonce during SSR. Returns undefined on the client.
+ */
+export function useNonce(): string | undefined {
+  return useContext(NonceContext);
+}

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

@@ -127,6 +127,11 @@ export type ServerActionFunction = ((...args: any[]) => Promise<any>) & {
  * const error = useAction(addToCart, state => state.error);
  * ```
  *
+ * @note The selector is expected to be stable for a given hook instance.
+ * This hook tracks one projection of one action. Changing selector semantics
+ * for the same action ID without a new action event is not a supported pattern;
+ * use separate useAction() subscriptions if you need different projections.
+ *
  * @note Actions passed as props from server components lose their metadata
  * during RSC serialization. Use a string action name or import directly.
  */
@@ -162,7 +167,10 @@ export function useAction<T>(
     T | TrackedActionState
   >(null!);
 
-  // Ref keeps the latest selector without re-subscribing on every render.
+  // Ref keeps the latest selector for subscription callbacks without
+  // re-subscribing on every render. Selector changes themselves are not
+  // treated as a reactive input; this hook expects a stable selector and
+  // represents one subscription/projection for one action.
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 

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

@@ -12,17 +12,8 @@ import type { Handle } from "../../handle.js";
 import { getCollectFn } from "../../handle.js";
 import type { HandleData } from "../types.js";
 import { NavigationStoreContext } from "./context.js";
-import { filterSegmentOrder } from "./filter-segment-order.js";
 import { shallowEqual } from "./shallow-equal.js";
 
-/**
- * SSR module-level state.
- * Populated by initHandleDataSync before React renders.
- * Used by useState initializer during SSR.
- */
-let ssrHandleData: HandleData = {};
-let ssrSegmentOrder: string[] = [];
-
 /**
  * Resolve the collect function for a handle.
  * Handle objects are plain { __brand, $$id } - collect is stored in the registry
@@ -76,18 +67,6 @@ function collectHandle<T, A>(
   return collect(segmentArrays);
 }
 
-/**
- * Initialize handle data synchronously for SSR.
- * Called before rendering to populate state for useState initializer.
- *
- * @param data - Handle data from RSC payload
- * @param matched - Segment order for reduction
- */
-export function initHandleDataSync(data: HandleData, matched?: string[]): void {
-  ssrHandleData = data;
-  ssrSegmentOrder = filterSegmentOrder(matched ?? []);
-}
-
 /**
  * Hook to access collected handle data.
  *
@@ -117,11 +96,10 @@ export function useHandle<T, A, S>(
 ): A | S {
   const ctx = useContext(NavigationStoreContext);
 
-  // Initial state from SSR module state or event controller
+  // Initial state from context event controller, or empty fallback without provider.
   const [value, setValue] = useState<A | S>(() => {
-    // During SSR, use module-level state
-    if (typeof document === "undefined" || !ctx) {
-      const collected = collectHandle(handle, ssrHandleData, ssrSegmentOrder);
+    if (!ctx) {
+      const collected = collectHandle(handle, {}, []);
       return selector ? selector(collected) : collected;
     }
 

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

@@ -3,7 +3,6 @@
 import { useContext, useState, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
-import { getSsrParams } from "./use-segments.js";
 
 /**
  * Hook to access the current route params.
@@ -31,9 +30,8 @@ export function useParams<T>(
   const ctx = useContext(NavigationStoreContext);
 
   const [value, setValue] = useState<T | Record<string, string>>(() => {
-    if (typeof document === "undefined" || !ctx) {
-      const ssrParams = getSsrParams();
-      return selector ? selector(ssrParams) : ssrParams;
+    if (!ctx) {
+      return selector ? selector({}) : {};
     }
     const params = ctx.eventController.getParams();
     return selector ? selector(params) : params;

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

@@ -2,7 +2,6 @@
 
 import { useContext, useState, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
-import { getSsrPathname } from "./use-segments.js";
 
 /**
  * Hook to access the current pathname.
@@ -20,8 +19,8 @@ export function usePathname(): string {
   const ctx = useContext(NavigationStoreContext);
 
   const [pathname, setPathname] = useState<string>(() => {
-    if (typeof document === "undefined" || !ctx) {
-      return getSsrPathname();
+    if (!ctx) {
+      return "/";
     }
     return (ctx.eventController.getState().location as URL).pathname;
   });

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

@@ -2,7 +2,7 @@
 
 import { useContext, useMemo } from "react";
 import { NavigationStoreContext } from "./context.js";
-import { prefetchDirect } from "../prefetch-fetch.js";
+import { prefetchDirect } from "../prefetch/fetch.js";
 import type { RouterInstance, RouterNavigateOptions } from "../types.js";
 
 /**

package/src/browser/react/use-search-params.ts

@@ -41,7 +41,8 @@ export function useSearchParams(): ReadonlyURLSearchParams {
       const nextSearch = location.searchParams.toString();
       if (nextSearch !== prevSearch.current) {
         prevSearch.current = nextSearch;
-        setSearchParams(location.searchParams);
+        // Create a snapshot so callers cannot mutate the source URLSearchParams
+        setSearchParams(new URLSearchParams(nextSearch));
       }
     };
 

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

@@ -2,7 +2,6 @@
 
 import { useContext, useState, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
-import { filterSegmentOrder } from "./filter-segment-order.js";
 import { shallowEqual } from "./shallow-equal.js";
 
 /**
@@ -17,47 +16,6 @@ export interface SegmentsState {
   location: URL;
 }
 
-/**
- * SSR module-level state.
- * Populated by initSegmentsSync before React renders.
- * Used by useState initializer during SSR.
- */
-let ssrSegmentOrder: string[] = [];
-let ssrPathname: string = "/";
-let ssrParams: Record<string, string> = {};
-
-/**
- * Initialize segments data synchronously for SSR.
- * Called before rendering to populate state for useState initializer.
- *
- * @param matched - Segment order from RSC metadata
- * @param pathname - Current pathname
- * @param params - Merged route params
- */
-export function initSegmentsSync(
-  matched?: string[],
-  pathname?: string,
-  params?: Record<string, string>,
-): void {
-  ssrSegmentOrder = filterSegmentOrder(matched ?? []);
-  ssrPathname = pathname ?? "/";
-  ssrParams = params ?? {};
-}
-
-/**
- * Get SSR params for use-params hook initialization.
- */
-export function getSsrParams(): Record<string, string> {
-  return ssrParams;
-}
-
-/**
- * Get SSR pathname for use-pathname hook initialization.
- */
-export function getSsrPathname(): string {
-  return ssrPathname;
-}
-
 /**
  * Parse pathname into path segments
  * /shop/products/123 → ["shop", "products", "123"]
@@ -80,18 +38,6 @@ function buildSegmentsState(
   };
 }
 
-/**
- * Build SSR state from module-level variables
- */
-function buildSsrState(): SegmentsState {
-  const location = new URL(ssrPathname, "http://localhost");
-  return {
-    path: parsePathname(ssrPathname),
-    segmentIds: ssrSegmentOrder,
-    location,
-  };
-}
-
 /**
  * Hook to access current route segments with optional selector for performance
  *
@@ -115,13 +61,14 @@ export function useSegments<T>(
 ): T | SegmentsState {
   const ctx = useContext(NavigationStoreContext);
 
-  // Build initial state from SSR module state or event controller.
-  // Inlined rather than calling recompute() because the segmentsCache
-  // ref is not yet initialized during the useState initializer.
+  // Build initial state from event controller when context exists.
+  // Inlined rather than calling recompute() because the segmentsCache ref
+  // is not yet initialized during the useState initializer.
   const [state, setState] = useState<T | SegmentsState>(() => {
-    if (typeof document === "undefined" || !ctx) {
-      const ssrState = buildSsrState();
-      return selector ? selector(ssrState) : ssrState;
+    if (!ctx) {
+      const fallbackLocation = new URL("/", "http://localhost");
+      const fallbackState = buildSegmentsState(fallbackLocation, []);
+      return selector ? selector(fallbackState) : fallbackState;
     }
     const location = ctx.eventController.getLocation();
     const handleState = ctx.eventController.getHandleState();

package/src/browser/response-adapter.ts

@@ -0,0 +1,73 @@
+import { validateRedirectOrigin } from "./validate-redirect-origin.js";
+
+type HeaderResult = { url: string } | "blocked" | null;
+
+/**
+ * Extract and validate an RSC response header URL (X-RSC-Reload, X-RSC-Redirect).
+ * Returns { url } if valid, "blocked" if present but invalid origin, null if absent.
+ */
+export function extractRscHeaderUrl(
+  response: Response,
+  header: string,
+): HeaderResult {
+  const raw = response.headers.get(header);
+  if (!raw) return null;
+  const url = validateRedirectOrigin(raw, window.location.origin);
+  return url ? { url } : "blocked";
+}
+
+/**
+ * Empty 200 response that won't choke Flight parsing.
+ * Used when a header URL is blocked by origin validation.
+ */
+export function emptyResponse(): Response {
+  return new Response(null, { status: 200 });
+}
+
+/**
+ * Tee a response body for RSC parsing and stream completion tracking.
+ * Returns a new Response with one branch; the other is consumed to detect
+ * end-of-stream, calling onComplete when done.
+ *
+ * If the response has no body, onComplete fires synchronously.
+ * If signal is provided, an abort cancels the tracking reader.
+ */
+export function teeWithCompletion(
+  response: Response,
+  onComplete: () => void,
+  signal?: AbortSignal,
+): Response {
+  if (!response.body) {
+    onComplete();
+    return response;
+  }
+
+  const [rscStream, trackingStream] = response.body.tee();
+
+  (async () => {
+    const reader = trackingStream.getReader();
+    const onAbort = signal ? reader.cancel.bind(reader) : undefined;
+    if (onAbort) signal!.addEventListener("abort", onAbort, { once: true });
+    try {
+      while (true) {
+        const { done } = await reader.read();
+        if (done) break;
+      }
+    } finally {
+      if (onAbort) signal!.removeEventListener("abort", onAbort);
+      reader.releaseLock();
+      onComplete();
+    }
+  })().catch((error) => {
+    if (!signal?.aborted) {
+      console.error("[Browser] Error reading tracking stream:", error);
+    }
+    onComplete();
+  });
+
+  return new Response(rscStream, {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+}