@rangojs/router 0.2.0 → 0.4.1

package/src/testing/render-route.tsx

@@ -38,7 +38,7 @@
  * (the segment chain is wrapped in a MountContext exactly as in production).
  */
 
-import type { ReactNode, ComponentType } from "react";
+import { useEffect, type ReactNode, type ComponentType } from "react";
 import type { RenderResult } from "@testing-library/react";
 import { renderSegments } from "../segment-system.js";
 import {
@@ -62,8 +62,14 @@ import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
 import { resolveThemeConfig } from "../theme/constants.js";
 import { isUnderTestRunner } from "../runtime-env.js";
+import { setupNavigationBridgeDelegatedPrefetch } from "../browser/navigation-bridge.js";
+import { resetAdaptiveStrategyForTesting } from "../browser/prefetch/default-strategy.js";
+import { resetPrefetchObserverForTesting } from "../browser/prefetch/observer.js";
+import type { PrefetchStrategy } from "../router/prefetch-default.js";
 
 const TEST_ORIGIN = "http://localhost";
+let activePrefetchRegistrations = 0;
+let pendingPrefetchReset: object | undefined;
 
 /**
  * Seed shape for `options.handle`, matching the handle wire format:
@@ -268,6 +274,14 @@ export interface RenderRouteOptions {
    * expect(getByTestId("nonce").textContent).toBe("test-nonce");
    */
   nonce?: string;
+  /**
+   * Router default prefetch strategy scoped to this rendered tree. This mirrors
+   * `createRouter({ defaultPrefetch })` for Links and eligible plain anchors
+   * inside `basename`. `data-prefetch="false"`/`"none"` opts out; `"true"`
+   * allows an application route with a common static-resource suffix but does
+   * not override a `"none"` default.
+   */
+  defaultPrefetch?: PrefetchStrategy;
 }
 
 /**
@@ -299,6 +313,41 @@ interface ResolvedMatch {
   pathname: string;
 }
 
+function DelegatedPrefetchRegistration({
+  bridge,
+}: {
+  bridge: NavigationBridge;
+}): null {
+  useEffect(() => {
+    const unregister = bridge.registerDelegatedPrefetch();
+    pendingPrefetchReset = undefined;
+    activePrefetchRegistrations++;
+    return () => {
+      try {
+        unregister();
+      } finally {
+        activePrefetchRegistrations--;
+        if (activePrefetchRegistrations === 0) {
+          const reset = {};
+          pendingPrefetchReset = reset;
+          queueMicrotask(() => {
+            if (
+              pendingPrefetchReset !== reset ||
+              activePrefetchRegistrations !== 0
+            ) {
+              return;
+            }
+            pendingPrefetchReset = undefined;
+            resetPrefetchObserverForTesting();
+            resetAdaptiveStrategyForTesting();
+          });
+        }
+      }
+    };
+  }, [bridge]);
+  return null;
+}
+
 function matchLeaf(
   pattern: string,
   pathname: string,
@@ -429,6 +478,7 @@ export async function renderRoute(
 
   const historyKey = generateHistoryKey(url.href);
   const mount = normalizeBasename(options.mount);
+  const basename = normalizeBasename(options.basename);
   // Fail loud on a request that cannot resolve the leaf route (a typo, or the
   // mount-prefixed-vs-relative confusion) instead of silently rendering empty
   // params (matchLeaf -> null -> {}). renderRoute paths are include-RELATIVE and
@@ -520,20 +570,31 @@ export async function renderRoute(
     });
   };
 
+  let prefetchRoot: HTMLElement | undefined;
   const bridge: NavigationBridge = {
     navigate: (target) => navigate(target),
     refresh: () => navigate(url.pathname + url.search),
     handlePopstate: async () => {},
     registerLinkInterception: () => () => {},
+    registerDelegatedPrefetch: () =>
+      setupNavigationBridgeDelegatedPrefetch(
+        store,
+        eventController,
+        () => undefined,
+        {
+          defaultPrefetch: options.defaultPrefetch,
+          root: prefetchRoot,
+          basename,
+        },
+      ),
     getVersion: () => undefined,
     updateVersion: () => {},
   };
 
-  const initialMetadata = makeMetadata(
-    url.pathname,
-    initialSegments,
-    initialMatch.params,
-  );
+  const initialMetadata = {
+    ...makeMetadata(url.pathname, initialSegments, initialMatch.params),
+    defaultPrefetch: options.defaultPrefetch,
+  };
   const initialTree = await renderSegments(initialSegments);
 
   // Wrap render in an awaited async act so a tree that suspends (async loaders,
@@ -542,19 +603,27 @@ export async function renderRoute(
   // suspended inside an act scope, but the act call was not awaited") and the
   // resolved content never reaches the asserted DOM.
   let result!: Awaited<ReturnType<typeof render>>;
+  const container = document.body.appendChild(document.createElement("div"));
+  prefetchRoot = container;
   await act(async () => {
     result = render(
-      <NavigationProvider
-        store={store}
-        eventController={eventController}
-        initialPayload={{ root: initialTree, metadata: initialMetadata }}
-        bridge={bridge}
-        basename={normalizeBasename(options.basename)}
-        themeConfig={
-          options.theme === undefined ? null : resolveThemeConfig(options.theme)
-        }
-        nonce={options.nonce}
-      />,
+      <>
+        <NavigationProvider
+          store={store}
+          eventController={eventController}
+          initialPayload={{ root: initialTree, metadata: initialMetadata }}
+          bridge={bridge}
+          basename={basename}
+          themeConfig={
+            options.theme === undefined
+              ? null
+              : resolveThemeConfig(options.theme)
+          }
+          nonce={options.nonce}
+        />
+        <DelegatedPrefetchRegistration bridge={bridge} />
+      </>,
+      { baseElement: document.body, container },
     );
   });
 

package/src/testing/shell-status.ts

@@ -29,6 +29,10 @@
  */
 
 import { sortedSearchString } from "../cache/cache-key-utils.js";
+import {
+  compileSearchParamsFilter,
+  type CacheSearchParams,
+} from "../cache/search-params-filter.js";
 
 /** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
 export const SHELL_STATUS_HEADER: string = "x-rango-shell";
@@ -45,6 +49,10 @@ const PPR_REPLAY_BYPASS_REASONS = [
   "nonce",
   "store-unavailable",
   "passive-read-unsupported",
+  "no-navigation-context",
+  "prerender-store",
+  "intercept",
+  "cache-disabled",
   "read-error",
   "no-entry",
   "invalid-version",
@@ -53,6 +61,7 @@ const PPR_REPLAY_BYPASS_REASONS = [
   "transition-when",
   "no-segment-snapshot",
   "snapshot-miss",
+  "explicit-cache-hit",
   "stale-build-entry",
 ] as const;
 
@@ -74,12 +83,20 @@ export type ShellStatusTarget = Response | { headers: Headers };
  * module (it pulls React). A parity test pins the two implementations.
  *
  * Accepts a `URL` or an absolute/relative request URL string (relative strings
- * resolve against `http://localhost`).
+ * resolve against `http://localhost`). Pass the router's `cache.searchParams`
+ * config as `searchParams` when the app under test sets one — the production
+ * key applies it, so the expected key must too.
  */
-export function shellCacheKey(url: URL | string): string {
+export function shellCacheKey(
+  url: URL | string,
+  searchParams?: CacheSearchParams,
+): string {
   const resolved =
     typeof url === "string" ? new URL(url, "http://localhost") : url;
-  const sorted = sortedSearchString(resolved.searchParams);
+  const sorted = sortedSearchString(
+    resolved.searchParams,
+    compileSearchParamsFilter(searchParams),
+  );
   const searchSuffix = sorted ? `?${sorted}` : "";
   return `${resolved.host}${resolved.pathname}${searchSuffix}:shell`;
 }

package/src/vite/plugin-types.ts

@@ -267,7 +267,7 @@ export interface RangoCloudflareOptions extends RangoBaseOptions {
  * `.vc-config.json` (and `config.json` for `functionName`).
  */
 export interface VercelPresetOptions {
-  /** Node runtime for the function. @default "nodejs22.x" */
+  /** Node runtime for the function. @default "nodejs24.x" */
   runtime?: string;
   /** Max execution time in seconds. @default 30 */
   maxDuration?: number;

package/src/vite/plugins/vercel-output.ts

@@ -99,7 +99,7 @@ export function assertVercelNodeRuntime(runtime: string | undefined): void {
     throw new Error(
       `[rango] preset "vercel": runtime "${runtime}" is not supported. ` +
         `This preset emits a Node serverless function; use a "nodejs*" runtime ` +
-        `(default "nodejs22.x"). The Edge runtime is not supported.`,
+        `(default "nodejs24.x"). The Edge runtime is not supported.`,
     );
   }
 }
@@ -125,7 +125,7 @@ export function buildVercelVcConfig(
   vercel: VercelPresetOptions,
 ): Record<string, unknown> {
   const vcConfig: Record<string, unknown> = {
-    runtime: vercel.runtime ?? "nodejs22.x",
+    runtime: vercel.runtime ?? "nodejs24.x",
     handler: "index.mjs",
     launcherType: "Nodejs",
     shouldAddHelpers: false,