@rangojs/router 0.4.0 → 0.4.2

package/src/browser/react/Link.tsx

@@ -7,13 +7,19 @@ import React, {
   useEffect,
   useMemo,
   useRef,
+  useSyncExternalStore,
   type ForwardRefExoticComponent,
   type RefAttributes,
 } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { LinkContext } from "./use-link-status.js";
 import type { NavigateOptions } from "../types.js";
-import { isHashOnlyNavigation } from "../link-interceptor.js";
+import {
+  isHashOnlyNavigation,
+  isPrefetchScopeDisabled,
+  subscribeToPrefetchScopeChange,
+} from "../link-interceptor.js";
+import { subscribeToLocationChange } from "../event-controller.js";
 import {
   isLocationStateEntry,
   type LocationStateEntry,
@@ -33,55 +39,26 @@ export type LinkState =
   | StateOrGetter<Record<string, unknown>>;
 
 import {
-  observeForPrefetch,
   prefetchDirect,
   prefetchQueued,
+  schedulePrefetchWhenRouterIdle,
 } from "../prefetch/loader.js";
-import { getDefaultPrefetchStrategy } from "../prefetch/default-strategy.js";
+import { observeForPrefetch } from "../prefetch/observer.js";
+import {
+  getDefaultPrefetchStrategy,
+  resolveAdaptiveStrategy,
+  subscribeToAdaptiveStrategyChange,
+} from "../prefetch/default-strategy.js";
 import { getAppVersion } from "../app-version.js";
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 
-// The (hover: none) MediaQueryList, created lazily on first client read and
-// reused across every Link render. matchMedia allocates and registers a live
-// query object; a fresh one per render (Link renders can be very frequent) is
-// wasteful when the same object's `.matches` is already live. Left null on the
-// server (no window).
-let hoverNoneQuery: MediaQueryList | null = null;
-
-/**
- * Read current touch/no-hover capability from the cached MediaQueryList. The
- * `.matches` read is live, so `prefetch="adaptive"` still reacts to
- * input-capability changes on hybrid devices (touch laptops, tablets gaining or
- * losing a pointer) and after SSR -> hydrate. The SSR guard returns a stable
- * `false` (pointer/hover default) so the resolved strategy doesn't drift on the
- * server vs the first client render.
- */
-function isTouchDevice(): boolean {
-  if (typeof window === "undefined") return false;
-  if (!hoverNoneQuery) {
-    hoverNoneQuery = window.matchMedia("(hover: none)");
-  }
-  return hoverNoneQuery.matches;
-}
-
 // The PrefetchStrategy union is defined in router/prefetch-default.ts (both
 // the server-side option resolver and this client seat consume it); re-export
 // so the public `PrefetchStrategy` import path via client.tsx is unchanged.
 export type { PrefetchStrategy } from "../../router/prefetch-default.js";
+export { resolveAdaptiveStrategy } from "../prefetch/default-strategy.js";
 
-/**
- * Resolve a prefetch strategy, expanding "adaptive" to the concrete strategy
- * for the CURRENT input capability: "viewport" on touch (no-hover) devices,
- * "hover" on pointer devices. Non-adaptive strategies pass through unchanged.
- * Reads touch capability live (not a module-load snapshot) so the result
- * tracks input-capability changes.
- */
-export function resolveAdaptiveStrategy(
-  prefetch: PrefetchStrategy,
-): PrefetchStrategy {
-  if (prefetch !== "adaptive") return prefetch;
-  return isTouchDevice() ? "viewport" : "hover";
-}
+const IGNORE_STRATEGY_CHANGES = (_listener: () => void) => () => {};
 
 /**
  * Link component props
@@ -120,7 +97,9 @@ export interface LinkProps extends Omit<
    * Prefetch strategy for the link destination. When omitted, falls back to
    * the router-wide default (`createRouter({ defaultPrefetch })`: `"none"` in
    * development, `"viewport"` in production). An explicit value always wins
-   * over the router default, including `"none"` to opt a single Link out.
+   * over the router default, including `"none"` to opt a single Link out. An
+   * ancestor with `data-prefetch-scope="false"` or `"none"` remains a hard
+   * subtree opt-out.
    *
    * @default the router's environment-aware `defaultPrefetch`
    */
@@ -260,12 +239,16 @@ export const Link: ForwardRefExoticComponent<
 
   // No explicit `prefetch` prop: fall back to the router-wide default
   // (server-resolved, applied at browser init — before hydration, so this
-  // render-time read never races the metadata). Then resolve adaptive:
-  // viewport on touch devices, hover on pointer devices. isTouchDevice() is
-  // read here (per render), not from a module-load snapshot, so a device
-  // whose input capability changes resolves to the current value.
-  const resolvedStrategy = resolveAdaptiveStrategy(
-    prefetch ?? getDefaultPrefetchStrategy(),
+  // render-time read never races the metadata). Adaptive reads the current
+  // input capability rather than a module-load snapshot.
+  const configuredStrategy =
+    prefetch ?? ctx?.defaultPrefetch ?? getDefaultPrefetchStrategy();
+  const resolvedStrategy = useSyncExternalStore(
+    configuredStrategy === "adaptive"
+      ? subscribeToAdaptiveStrategyChange
+      : IGNORE_STRATEGY_CHANGES,
+    () => resolveAdaptiveStrategy(configuredStrategy),
+    () => (configuredStrategy === "adaptive" ? "hover" : configuredStrategy),
   );
 
   // Internal ref for viewport observation; merge with forwarded ref
@@ -365,10 +348,13 @@ export const Link: ForwardRefExoticComponent<
   );
 
   const handleMouseEnter = useCallback(() => {
+    const element = internalRef.current;
     if (
       (resolvedStrategy === "hover" || resolvedStrategy === "viewport") &&
       !isExternal &&
-      ctx?.store
+      ctx?.store &&
+      (!element ||
+        (!isHashOnlyNavigation(element) && !isPrefetchScopeDisabled(element)))
     ) {
       // For "hover", this is the primary prefetch trigger.
       // For "viewport", this upgrades/prioritizes a potentially queued
@@ -393,54 +379,77 @@ export const Link: ForwardRefExoticComponent<
     const isRender = resolvedStrategy === "render";
     if (!isViewport && !isRender) return;
 
-    let cancelled = false;
-    let unsubIdle: (() => void) | undefined;
-    let stopObserving: (() => void) | undefined;
+    const armPrefetch = (): (() => void) => {
+      const element = internalRef.current;
+      if (
+        element &&
+        (isHashOnlyNavigation(element) || isPrefetchScopeDisabled(element))
+      ) {
+        return () => {};
+      }
 
-    const triggerPrefetch = () => {
-      if (cancelled) return;
-      const segmentState = ctx.store.getSegmentState();
-      prefetchQueued(
-        resolvedTo,
-        segmentState.currentSegmentIds,
-        getAppVersion(),
-        ctx.store.getRouterId?.(),
-        prefetchKey,
-      );
-    };
+      let cancelled = false;
+      let unsubIdle: (() => void) | undefined;
+      let stopObserving: (() => void) | undefined;
+
+      const triggerPrefetch = () => {
+        if (cancelled) return;
+        const currentElement = internalRef.current;
+        if (currentElement && isPrefetchScopeDisabled(currentElement)) return;
+        const segmentState = ctx.store.getSegmentState();
+        prefetchQueued(
+          resolvedTo,
+          segmentState.currentSegmentIds,
+          getAppVersion(),
+          ctx.store.getRouterId?.(),
+          prefetchKey,
+        );
+      };
 
-    // Schedule prefetch only when the app is idle (no navigation/streaming).
-    // This avoids competing with hydration and active navigation fetches.
-    const scheduleWhenIdle = (callback: () => void) => {
-      const state = ctx.eventController.getState();
-      if (state.state === "idle" && !state.isStreaming) {
-        callback();
-        return;
-      }
-      const unsub = ctx.eventController.subscribe(() => {
-        const s = ctx.eventController.getState();
-        if (s.state === "idle" && !s.isStreaming) {
-          unsub();
-          callback();
+      if (isRender) {
+        unsubIdle = schedulePrefetchWhenRouterIdle(
+          ctx.eventController,
+          triggerPrefetch,
+        );
+      } else {
+        const viewportElement = internalRef.current;
+        if (viewportElement) {
+          stopObserving = observeForPrefetch(viewportElement, () => {
+            unsubIdle = schedulePrefetchWhenRouterIdle(
+              ctx.eventController,
+              triggerPrefetch,
+            );
+          });
         }
-      });
-      unsubIdle = unsub;
+      }
+
+      return () => {
+        cancelled = true;
+        unsubIdle?.();
+        stopObserving?.();
+      };
     };
 
-    if (isRender) {
-      scheduleWhenIdle(triggerPrefetch);
-    } else if (isViewport) {
-      const element = internalRef.current;
-      if (!element) return;
-      stopObserving = observeForPrefetch(element, () => {
-        scheduleWhenIdle(triggerPrefetch);
-      });
-    }
+    let disarmPrefetch = armPrefetch();
+    const element = internalRef.current;
+    const unsubscribeScope = element
+      ? subscribeToPrefetchScopeChange(element, () => {
+          disarmPrefetch();
+          disarmPrefetch = armPrefetch();
+        })
+      : undefined;
+    const unsubscribeLocation = subscribeToLocationChange(
+      ctx.eventController,
+      () => {
+        disarmPrefetch();
+        disarmPrefetch = armPrefetch();
+      },
+    );
 
     return () => {
-      cancelled = true;
-      unsubIdle?.();
-      stopObserving?.();
+      unsubscribeScope?.();
+      unsubscribeLocation();
+      disarmPrefetch();
     };
   }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 

package/src/browser/react/NavigationProvider.tsx

@@ -349,6 +349,7 @@ export function NavigationProvider({
       eventController,
       navigate,
       refresh,
+      defaultPrefetch: initialPayload.metadata.defaultPrefetch,
     } as NavigationStoreContextValue;
     Object.defineProperty(value, "basename", {
       configurable: true,

package/src/browser/react/context.ts

@@ -3,6 +3,7 @@
 import { createContext, type Context } from "react";
 import type { NavigationStore, NavigateOptions } from "../types.js";
 import type { EventController } from "../event-controller.js";
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 
 /**
  * Navigation context value provided by NavigationProvider
@@ -52,6 +53,9 @@ export interface NavigationStoreContextValue {
    * Used by Link and useRouter() to auto-prefix app-local paths.
    */
   basename: string | undefined;
+
+  /** Router default from this instance's initial payload. */
+  defaultPrefetch?: PrefetchStrategy;
 }
 
 /**

package/src/browser/rsc-router.tsx

@@ -22,7 +22,7 @@ import type {
 } from "./types.js";
 import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
-import { expandSegmentFragments } from "../segment-fragments.js";
+import { expandPayloadFragments } from "../segment-fragments.js";
 import { initRangoState } from "./rango-state.js";
 import { registerNavigationStore } from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
@@ -68,8 +68,11 @@ export interface InitBrowserAppOptions {
 
   /**
    * Enable global link interception for SPA navigation.
-   * When enabled, clicks on same-origin anchor elements are intercepted
-   * and handled via client-side navigation instead of full page loads.
+   * When enabled, clicks on eligible same-origin HTML anchor elements are intercepted
+   * and handled via client-side navigation instead of full page loads. Plain
+   * anchors inside the router basename also follow its default prefetch strategy
+   * after hydration. `data-prefetch="false"`/`"none"` opts out; `"true"` allows
+   * an application route with a common static-resource suffix.
    *
    * Links rendered with the Link component handle their own navigation
    * regardless of this setting.
@@ -124,6 +127,8 @@ export interface BrowserAppContext {
   warmupEnabled?: boolean;
   /** Whether the hydrated tree should be wrapped in React.StrictMode */
   strictMode?: boolean;
+  /** Whether plain-anchor click interception and delegated prefetch are enabled */
+  linkInterceptionEnabled?: boolean;
   /** App version for prefetch version mismatch detection */
   version?: string;
   /**
@@ -172,9 +177,7 @@ export async function initBrowserApp(
   // renderSegments, history cache). Non-HIT payloads have no envelopes and pay
   // one field scan. The SSR resume pass ran the same expansion (ssr-root.tsx),
   // so the hydrated tree matches the server-rendered one by construction.
-  await expandSegmentFragments(initialPayload.metadata?.segments, (stream) =>
-    deps.createFromReadableStream(stream),
-  );
+  await expandPayloadFragments(initialPayload, deps.createFromReadableStream);
 
   // Extract themeConfig and initialTheme from payload if not explicitly provided
   // This allows virtual entries to work without importing the router
@@ -196,6 +199,12 @@ export async function initBrowserApp(
   }
   const initialHistoryKey = generateHistoryKey(window.location.href);
 
+  // Resolve the state namespace before the store installs its BroadcastChannel
+  // listener. A streaming handle payload can delay hydration below; leaving the
+  // default name active during that wait would discard this router's messages.
+  const version = initialPayload.metadata?.version;
+  initRangoState(version ?? "0", initialPayload.metadata?.stateCookieName);
+
   // Create navigation store with history-based caching
   const store = createNavigationStore({
     initialLocation: window.location,
@@ -271,7 +280,6 @@ export async function initBrowserApp(
   // It is set once from the initial payload and 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.
-  const version = initialPayload.metadata?.version;
   const appShellRef = createAppShellRef({
     routerId: initialPayload.metadata?.routerId,
     rootLayout: initialPayload.metadata?.rootLayout,
@@ -279,11 +287,6 @@ export async function initBrowserApp(
     version,
   });
 
-  // Initialize the rango state cookie for cache invalidation. The build version
-  // busts cached prefetches on deploy; the server-resolved cookie name
-  // namespaces the cookie so sibling apps on the same origin don't collide
-  // (falls back to the bare default prefix if metadata lacks the name).
-  initRangoState(version ?? "0", initialPayload.metadata?.stateCookieName);
   setAppVersion(version);
 
   // Initialize the in-memory prefetch cache (TTL + max size) and the prefetch
@@ -307,8 +310,16 @@ export async function initBrowserApp(
   }
 
   // Wire the RSC decoder so prefetches decode eagerly and warm the route's
-  // client chunks (same createFromFetch the navigation client uses).
-  setPrefetchDecoder((response) => deps.createFromFetch<RscPayload>(response));
+  // client chunks (same createFromFetch the navigation client uses). Fragment
+  // envelopes (#700) expand BEFORE the decoded payload enters the prefetch
+  // cache, so cached entries only ever resolve to expanded segments; a
+  // fragment-decode failure rejects the entry's payload and rides the cache's
+  // existing eviction path.
+  setPrefetchDecoder(async (response) => {
+    const payload = await deps.createFromFetch<RscPayload>(response);
+    await expandPayloadFragments(payload, deps.createFromReadableStream);
+    return payload;
+  });
 
   // Create a bound renderSegments that reads rootLayout through the shell ref.
   // The shell is set once at init and not swapped within a session (a cross-app
@@ -359,6 +370,8 @@ export async function initBrowserApp(
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
     version: version,
+    defaultPrefetch,
+    basename: initialPayload.metadata?.basename,
   });
 
   // Connect action redirect → navigation bridge (now that both are initialized)
@@ -541,6 +554,7 @@ export async function initBrowserApp(
     initialTheme: effectiveInitialTheme,
     warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
     strictMode: initialPayload.metadata?.strictMode ?? true,
+    linkInterceptionEnabled: linkInterception,
     version,
     appShellRef,
   };
@@ -614,6 +628,7 @@ export function Rango(_props: RangoProps): React.ReactElement {
     warmupEnabled,
     version,
     appShellRef,
+    linkInterceptionEnabled,
   } = getBrowserAppContext();
 
   // Signal that the React tree has hydrated. useEffect only fires after
@@ -621,11 +636,15 @@ export function Rango(_props: RangoProps): React.ReactElement {
   // that does not depend on React internals like __reactFiber.
   React.useEffect(() => {
     document.documentElement.dataset.hydrated = "";
+    const cleanupPrefetch = linkInterceptionEnabled
+      ? bridge.registerDelegatedPrefetch()
+      : undefined;
     if (IS_BROWSER_DEBUG && !hydrationCommitLogged) {
       hydrationCommitLogged = true;
       bootLog("hydration commit (root effect flushed)");
     }
-  }, []);
+    return cleanupPrefetch;
+  }, [bridge, linkInterceptionEnabled]);
 
   return (
     <NavigationProvider

package/src/browser/types.ts

@@ -613,6 +613,7 @@ export interface NavigationBridge {
   refresh(): Promise<void>;
   handlePopstate(): Promise<void>;
   registerLinkInterception(): () => void;
+  registerDelegatedPrefetch(): () => void;
   /** Current RSC version (live, reflects the latest updateVersion). */
   getVersion(): string | undefined;
   /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */

package/src/cache/cache-key-utils.ts

@@ -7,6 +7,7 @@
  */
 
 import { encodeKV } from "../encode-kv.js";
+import type { SearchParamsFilter } from "./search-params-filter.js";
 
 /**
  * Reserved URL query params that the router owns and must never key the cache
@@ -34,12 +35,22 @@ function isReservedSearchParam(key: string): boolean {
  * Build a sorted, deterministic query string from URLSearchParams,
  * excluding the router's reserved params (see isReservedSearchParam).
  *
- * Returns empty string when no user-facing params exist.
+ * `filter` is the compiled `cache.searchParams` config (search-params-filter.ts),
+ * applied AFTER the reserved-param exclusion and BEFORE the sort, so reserved
+ * params can never be re-included (`include: ["__no_cache"]` is a no-op) and
+ * surviving params stay order-insensitive. `undefined` means no filtering --
+ * that path must stay byte-identical to the pre-filter format (cacheKeyBase
+ * output is byte-stable by contract).
+ *
+ * Returns empty string when no user-facing params survive.
  */
-export function sortedSearchString(searchParams: URLSearchParams): string {
+export function sortedSearchString(
+  searchParams: URLSearchParams,
+  filter?: SearchParamsFilter,
+): string {
   const pairs: [string, string][] = [];
   for (const [k, v] of searchParams) {
-    if (!isReservedSearchParam(k)) {
+    if (!isReservedSearchParam(k) && (filter === undefined || filter(k))) {
       pairs.push([k, v]);
     }
   }
@@ -77,9 +88,12 @@ export function cacheKeyBase(
   pathname: string,
   searchParams?: URLSearchParams,
   params?: Record<string, string>,
+  filter?: SearchParamsFilter,
 ): string {
   const paramStr = sortedRouteParams(params);
-  const searchStr = searchParams ? sortedSearchString(searchParams) : "";
+  const searchStr = searchParams
+    ? sortedSearchString(searchParams, filter)
+    : "";
 
   let key = `${host}${pathname}`;
   if (paramStr) key += `:${paramStr}`;

package/src/cache/cache-runtime.ts

@@ -302,9 +302,14 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           if (ctx._responseType) {
             keyArgs.push(ctx._responseType);
           }
-          // Include user-facing search params (exclude internal _rsc*/__ params)
+          // Include user-facing search params (exclude internal _rsc*/__
+          // params, plus the request's cache.searchParams filter -- same
+          // normalization as the URL-keyed tiers).
           if (ctx.searchParams instanceof URLSearchParams) {
-            const normalized = sortedSearchString(ctx.searchParams);
+            const normalized = sortedSearchString(
+              ctx.searchParams,
+              requestCtx?._searchParamsFilter,
+            );
             if (normalized) {
               keyArgs.push(normalized);
             }