@rangojs/router 0.22.1 → 0.23.0

package/src/browser/prefetch/fetch.ts

@@ -35,6 +35,7 @@ import { shouldPrefetch } from "./policy.js";
 import { debugLog, IS_BROWSER_DEBUG } from "../logging.js";
 import { teeWithCompletion, isForeignRouterId } from "../response-adapter.js";
 import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../../segment-fragments.js";
+import { PREFETCH_HEADER } from "../../prefetch-markers.js";
 import type { RscPayload } from "../types.js";
 
 /**
@@ -263,7 +264,7 @@ function executePrefetchFetch(
     headers: {
       "X-Rango-State": rangoState,
       "X-RSC-Router-Client-Path": window.location.href,
-      "X-Rango-Prefetch": "1",
+      [PREFETCH_HEADER]: "1",
       ...(isFragmentPassthroughEnabled() && {
         [SEGMENT_FRAGMENT_CAPABILITY_HEADER]: "1",
       }),

package/src/browser/react/NavigationProvider.tsx

@@ -22,6 +22,7 @@ import type {
   NavigationUpdate,
   NavigateOptionsInternal,
   NavigationBridge,
+  RscMetadata,
 } from "../types.js";
 import type { EventController } from "../event-controller.js";
 import { RootErrorBoundary } from "../../root-error-boundary.js";
@@ -211,6 +212,30 @@ async function processHandles(
   }
 }
 
+/**
+ * Read the handle stream of `metadata` into the event controller and the
+ * entry on screen. The provider's own call for every payload it is handed,
+ * and the one write for a response that hands React nothing (a fill,
+ * browser/partial-update.ts fillHoles).
+ */
+export function consumeHandles(
+  metadata: RscMetadata,
+  eventController: EventController,
+  store: NavigationStore,
+): void {
+  processHandles(metadata.handles!, {
+    eventController,
+    store,
+    matched: metadata.matched,
+    isPartial: metadata.isPartial,
+    resolvedIds: metadata.resolvedIds,
+    // Now: by the time the stream ends the user may be elsewhere.
+    historyKey: store.getHistoryKey(),
+  }).catch((err) =>
+    console.error("[NavigationProvider] Error consuming handles:", err),
+  );
+}
+
 /**
  * Props for NavigationProvider
  */
@@ -288,8 +313,11 @@ export interface NavigationProviderProps {
    * `settled` resolves once the stream has ended and React has revealed every
    * boundary. Until then location state is `undefined`, as SSR rendered it;
    * then one transition gives the entry's state and changes
-   * HydrationBarrierContext, and the store is released after that commit. A
-   * navigation committed earlier releases the store before its update.
+   * HydrationBarrierContext, and the store is released after that commit
+   * (handle data lands in that release notification). A navigation committed
+   * earlier releases the store before its update, for the whole hold when the
+   * navigation is held: an old-page boundary hydrating meanwhile reads
+   * the destination's values and can mismatch.
    * Absent for a provider mounted on the client.
    */
   hydration?: { settled: Promise<void> };
@@ -368,6 +396,11 @@ export function NavigationProvider({
   }
   const shellRef = appShellRef ?? fallbackShellRef.current;
 
+  // Fixed for the document: read once on mount.
+  const [origin] = useState(
+    () => (eventController.getState().location as URL | undefined)?.origin,
+  );
+
   const contextValue = useMemo<NavigationStoreContextValue>(() => {
     const value = {
       store,
@@ -375,8 +408,7 @@ export function NavigationProvider({
       navigate,
       refresh,
       defaultPrefetch: initialPayload.metadata.defaultPrefetch,
-      // Fixed for the document: read once, with the stable value.
-      origin: (eventController.getState().location as URL | undefined)?.origin,
+      origin,
     } as NavigationStoreContextValue;
     Object.defineProperty(value, "basename", {
       configurable: true,
@@ -456,7 +488,7 @@ export function NavigationProvider({
     return unsub;
   }, [eventController]);
 
-  // Pending scroll action to apply after React commits
+  // The last navigation's scroll decision, until React commits its update.
   const pendingScrollRef = useRef<NavigationUpdate["scroll"]>(undefined);
 
   // Apply scroll after React commits the new content to the DOM
@@ -478,11 +510,14 @@ export function NavigationProvider({
   useEffect(() => {
     const unsubscribe = store.onUpdate((update) => {
       if (process.env.NODE_ENV !== "production") auditTreeUpdate(update.root);
-      // 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;
+      // Scroll belongs to the navigation transaction: only an update that
+      // carries one's decision sets the pending action, and the layout effect
+      // above consumes it once, after the commit that follows. An update with
+      // no decision (server action, error, prefetch: false fill) leaves a
+      // pending one alone. React can hold a navigation's commit, and whatever
+      // lands meanwhile must not cost the navigation its scroll. Nothing
+      // stale is replayed: every update commits, and that commit consumes.
+      if (update.scroll) pendingScrollRef.current = update.scroll;
 
       // Committed before the document finished hydrating: end the window
       // first, so the page this update mounts reads the live store. A
@@ -494,10 +529,7 @@ export function NavigationProvider({
         eventController.releaseHydrationLock();
       }
 
-      setPayload({
-        root: update.root,
-        metadata: update.metadata,
-      });
+      setPayload({ root: update.root, metadata: update.metadata });
       // The state of the entry this payload renders, as its commit recorded
       // it: one update, so one lane, so one React commit with the tree.
       setLocationState(eventController.getLocationState());
@@ -511,20 +543,7 @@ export function NavigationProvider({
 
       // Update handle data progressively as it streams in
       if (update.metadata.handles) {
-        // Capture historyKey now - by the time async processing completes,
-        // the user might have navigated elsewhere
-        const historyKey = store.getHistoryKey();
-
-        processHandles(update.metadata.handles, {
-          eventController,
-          store,
-          matched: update.metadata.matched,
-          isPartial: update.metadata.isPartial,
-          resolvedIds: update.metadata.resolvedIds,
-          historyKey,
-        }).catch((err) =>
-          console.error("[NavigationProvider] Error consuming handles:", err),
-        );
+        consumeHandles(update.metadata, eventController, store);
       } else if (update.metadata.matched) {
         // cachedHandleData present -> full restore (back/forward); absent ->
         // partial cleanup of segments no longer matched.

package/src/browser/react/filter-segment-order.ts

@@ -1,3 +1,14 @@
+/**
+ * A loader sub-id carries a `D${index}.` marker ("M0L0D1.user"). Non-global,
+ * so `.test` and `.replace` are stateless.
+ */
+export const LOADER_SEGMENT_ID: RegExp = /D\d+\./;
+
+/** True for a loader sub-id ("M0L0D1.user"), false for a layout/route/slot id. */
+export function isLoaderSegmentId(id: string): boolean {
+  return LOADER_SEGMENT_ID.test(id);
+}
+
 /**
  * Build the handle-collection segment order from a raw `matched` list.
  *
@@ -24,7 +35,7 @@ export function filterSegmentOrder(matched: string[]): string[] {
   const nonSlotSet = new Set<string>();
 
   for (const id of matched) {
-    if (/D\d+\./.test(id)) continue;
+    if (isLoaderSegmentId(id)) continue;
     const slotIdx = id.indexOf(".@");
     if (slotIdx >= 0) {
       const parent = id.slice(0, slotIdx);
@@ -66,5 +77,5 @@ export function filterSegmentOrder(matched: string[]): string[] {
  * and React reports a hydration mismatch.
  */
 export function filterRouteSegmentIds(matched: string[]): string[] {
-  return matched.filter((id) => !id.includes(".@") && !/D\d+\./.test(id));
+  return matched.filter((id) => !id.includes(".@") && !isLoaderSegmentId(id));
 }

package/src/browser/response-adapter.ts

@@ -26,6 +26,26 @@ export function extractRscHeaderUrl(
   return url ? { url } : "blocked";
 }
 
+/**
+ * Run `request` with a signal that `signal` aborts until the request settles,
+ * and only until then. A response that has arrived streams to its end:
+ * aborting a Flight body mid-read rejects every chunk a mounted tree may be
+ * reading. Aborted, the request rejects with `signal.reason`.
+ */
+export function abortUntilResponse<T>(
+  signal: AbortSignal | undefined,
+  request: (signal: AbortSignal | undefined) => Promise<T>,
+): Promise<T> {
+  if (!signal) return request(undefined);
+  const controller = new AbortController();
+  const cancel = (): void => controller.abort(signal.reason);
+  if (signal.aborted) cancel();
+  else signal.addEventListener("abort", cancel, { once: true });
+  return request(controller.signal).finally(() =>
+    signal.removeEventListener("abort", cancel),
+  );
+}
+
 /**
  * Empty 200 response that won't choke Flight parsing.
  * Used when a header URL is blocked by origin validation.

package/src/browser/rsc-router.tsx

@@ -11,6 +11,7 @@ import {
 import { createEventController } from "./event-controller.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 import { validateRedirectOrigin } from "./validate-redirect-origin.js";
+import { awaitDocumentRevealed } from "./document-revealed.js";
 import { createNavigationClient } from "./navigation-client.js";
 import { createServerActionBridge } from "./server-action-bridge.js";
 import { createNavigationBridge } from "./navigation-bridge.js";
@@ -331,14 +332,23 @@ export async function initBrowserApp(
             // deferred values here exactly like the nav lane's processHandles
             // does before applying.
             const lateData = await resolveDeferredHandleValues(rawLateData);
-            bootLog("handles: late push applied", {
+            // Live store only while the document's page is on screen: a full
+            // replace with its `matched` would overwrite another page's handles.
+            const pageKeys = store.getPageHistoryKeys(initialHistoryKey);
+            const onScreen = pageKeys.includes(store.getHistoryKey());
+            bootLog("handles: late push", {
               segments: Object.keys(lateData),
+              onScreen,
             });
-            eventController.setHandleData(
-              lateData,
-              initialPayload.metadata?.matched,
-            );
-            store.updateCacheHandleData(initialHistoryKey, lateData);
+            if (onScreen) {
+              eventController.setHandleData(
+                lateData,
+                initialPayload.metadata?.matched,
+              );
+            }
+            for (const key of pageKeys) {
+              store.updateCacheHandleData(key, lateData);
+            }
           }
         } catch (err) {
           console.error("[rsc-router] Error consuming late handles:", err);
@@ -641,28 +651,7 @@ export async function initBrowserApp(
     linkInterceptionEnabled: linkInterception,
     version,
     appShellRef,
-    documentRevealed: new Promise<void>((resolve) => {
-      // Parsing ends with the stream, but React reveals a streamed boundary
-      // in batches up to 300 ms later (Fizz's $RC marks it `$~` and reveals
-      // it from a timer), so the boundary is still pending at
-      // DOMContentLoaded. A transition then would make React client-render
-      // it over its server HTML.
-      const start = (): void => {
-        // A reveal rewrites the same comment's data, or React removes the
-        // node; a boundary nested in revealed content joins the document
-        // only then, so resolve only once a full walk finds none.
-        let pending = unrevealedBoundaries();
-        const check = (): void => {
-          pending = pending.filter(isUnrevealed);
-          if (pending.length === 0) pending = unrevealedBoundaries();
-          if (pending.length > 0) requestAnimationFrame(check);
-          else resolve();
-        };
-        check();
-      };
-      if (document.readyState !== "loading") start();
-      else document.addEventListener("DOMContentLoaded", start, { once: true });
-    }),
+    documentRevealed: awaitDocumentRevealed(),
   };
   browserAppContext = context;
 
@@ -670,23 +659,6 @@ export async function initBrowserApp(
   return context;
 }
 
-/**
- * A Suspense boundary of the document React has not revealed yet: Fizz marks
- * one `$?` while its content streams and `$~` once its reveal is queued.
- */
-function isUnrevealed(node: Comment): boolean {
-  return node.isConnected && (node.data === "$?" || node.data === "$~");
-}
-
-function unrevealedBoundaries(): Comment[] {
-  const found: Comment[] = [];
-  const walker = document.createTreeWalker(document, NodeFilter.SHOW_COMMENT);
-  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
-    if (isUnrevealed(node as Comment)) found.push(node as Comment);
-  }
-  return found;
-}
-
 // Once-flag so the hydration-commit boot log fires a single time (StrictMode
 // re-runs the root effect; the second flush is not a second hydration).
 let hydrationCommitLogged = false;

package/src/browser/server-action-bridge.ts

@@ -26,8 +26,8 @@ import {
   startBrowserTransaction,
 } from "./logging.js";
 import {
+  validatePayloadRedirect,
   validateRedirectOrigin,
-  validateExternalRedirect,
 } from "./validate-redirect-origin.js";
 import {
   extractRscHeaderUrl,
@@ -40,13 +40,11 @@ import { mergeLocationState } from "./history-state.js";
 import { stampLocationState } from "./react/location-state-shared.js";
 import { classifyActionOutcome } from "./action-coordinator.js";
 import { getAppVersion } from "./app-version.js";
-import { collectClientRevalidationDecisions } from "../client-urls/navigation.js";
 import {
   decideCommitGatedOff,
   findActionFormData,
   type TransitionWhenActionInput,
 } from "./transition-when.js";
-import { CLIENT_REVALIDATION_HEADER } from "../client-urls/revalidation-protocol.js";
 import { auditTreeCause } from "../suspense-audit.js";
 
 // Polyfill Symbol.dispose/asyncDispose for Safari and older browsers
@@ -335,39 +333,12 @@ export function createServerActionBridge(
       const onHandleAbort = () => fetchAbort.abort();
       handle.signal.addEventListener("abort", onHandleAbort, { once: true });
 
-      // Client-run per-loader revalidation for the action follow-up render:
-      // run the held clientUrls route's revalidate() predicates with the
-      // action context and ship their decisions. Fails soft to null (locked
-      // server defaults).
-      let clientRevalidation: string | null = null;
-      try {
-        const actionPageUrl = new URL(
-          segmentState.currentUrl,
-          window.location.origin,
-        );
-        clientRevalidation = collectClientRevalidationDecisions({
-          currentUrl: actionPageUrl,
-          nextUrl: actionPageUrl,
-          // Decisions ride the action POST itself — the server evaluates it
-          // with actionContext, so the locked default is the action default.
-          actionRequest: true,
-          isAction: true,
-          actionId: id,
-          stale: false,
-        });
-      } catch {
-        clientRevalidation = null;
-      }
-
       // Send action request with stream tracking
       const responsePromise = fetch(url, {
         method: "POST",
         headers: {
           "rsc-action": id,
           "X-RSC-Router-Client-Path": segmentState.currentUrl,
-          ...(clientRevalidation && {
-            [CLIENT_REVALIDATION_HEADER]: clientRevalidation,
-          }),
           ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
           ...(interceptSourceUrl && {
             "X-RSC-Router-Intercept-Source": interceptSourceUrl,
@@ -518,41 +489,26 @@ export function createServerActionBridge(
       // Check handle.signal.aborted to avoid redirecting from a stale action
       // when the user has already navigated away.
       if (metadata?.redirect && !handle.signal.aborted) {
-        // Explicit off-host redirect (redirect(url, { external: true })):
-        // hard-navigate, but still scheme-validate (http/https only). external
-        // waives the same-origin check, NOT scheme safety, so a forged payload
-        // carrying a javascript:/data: URL cannot script via location.assign.
-        if (metadata.redirect.external) {
-          const externalUrl = validateExternalRedirect(
-            metadata.redirect.url,
-            window.location.origin,
+        // An explicit off-host redirect is a hard navigation, still
+        // scheme-validated: a forged payload carrying a javascript:/data: URL
+        // cannot script via location.assign (validatePayloadRedirect).
+        const { redirect } = metadata;
+        const target = validatePayloadRedirect(redirect);
+        handle.complete(returnValue?.data);
+        if (!target) {
+          log(
+            redirect.external
+              ? "blocked external action redirect payload"
+              : "blocked action redirect payload",
+            { url: redirect.url },
           );
-          if (!externalUrl) {
-            log("blocked external action redirect payload", {
-              url: metadata.redirect.url,
-            });
-            handle.complete(returnValue?.data);
-            return returnValue?.data;
-          }
-          log("external action redirect", { url: externalUrl });
-          handle.complete(returnValue?.data);
-          window.location.assign(externalUrl);
-          return returnValue?.data;
+        } else if (redirect.external) {
+          log("external action redirect", { url: target });
+          window.location.assign(target);
+        } else {
+          log("action redirect", { url: target });
+          await dispatchRedirect(target, metadata.locationState);
         }
-        const redirectUrl = validateRedirectOrigin(
-          metadata.redirect.url,
-          window.location.origin,
-        );
-        if (!redirectUrl) {
-          log("blocked action redirect payload", {
-            url: metadata.redirect.url,
-          });
-          handle.complete(returnValue?.data);
-          return returnValue?.data;
-        }
-        log("action redirect", { url: redirectUrl });
-        handle.complete(returnValue?.data);
-        await dispatchRedirect(redirectUrl, metadata.locationState);
         return returnValue?.data;
       }
 

package/src/browser/types.ts

@@ -308,7 +308,12 @@ export interface HistoryEntryMemory {
 export interface NavigationUpdate {
   root: ReactNode | Promise<ReactNode>;
   metadata: RscMetadata;
-  /** Scroll behavior to apply after React commits this update */
+  /**
+   * The scroll decision of the navigation transaction this update commits,
+   * applied after React commits it. Absent on every update that is not a
+   * navigation's (server action, error, `prefetch: false` fill): such an
+   * update says nothing about scroll, and leaves a pending decision alone.
+   */
   scroll?: {
     /** For back/forward: restore saved position */
     restore?: boolean;
@@ -637,6 +642,12 @@ export interface NavigationStore {
     stale?: boolean,
     handlesPending?: boolean,
   ): void;
+  /**
+   * The history keys whose entries show the page `historyKey`'s entry shows:
+   * that entry and the copies a shallow navigation made of it, which share its
+   * segments array. `[historyKey]` when it has no entry.
+   */
+  getPageHistoryKeys(historyKey: string): string[];
   markHistoryCacheStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
@@ -671,13 +682,6 @@ export interface FetchPartialOptions {
   signal?: AbortSignal;
   /** If true, this is a stale cache revalidation request - server should force revalidators */
   staleRevalidation?: boolean;
-  /**
-   * Encoded client-run per-loader revalidation decisions
-   * (clientUrls revalidate() predicates executed in the browser); sent as
-   * X-Rango-Client-Reval and honored only by materialized client-urls loader
-   * stubs. Null/absent = locked server defaults.
-   */
-  clientRevalidation?: string | null;
   interceptSourceUrl?: string;
   /** RSC version for cache invalidation detection */
   version?: string;
@@ -685,6 +689,12 @@ export interface FetchPartialOptions {
   routerId?: string;
   /** If true, this is an HMR refetch - server should invalidate manifest cache */
   hmr?: boolean;
+  /**
+   * The fill request of an adopted prefetch that carried deferred segments
+   * (`prefetch: false`): marked `_rsc_fill`, never answered from or written
+   * to a prefetch cache or the HTTP cache, and it cancels no prefetch.
+   */
+  fill?: boolean;
 }
 
 /**
@@ -785,7 +795,7 @@ export type { ResolvedSegment };
 
 /**
  * Token for tracking an active stream.
- * Call end() when the stream completes.
+ * Call end() when the stream completes. Only the first call counts.
  */
 export interface StreamingToken {
   end(): void;

package/src/browser/validate-redirect-origin.ts

@@ -54,3 +54,19 @@ export function validateExternalRedirect(
   }
   return resolved;
 }
+
+/**
+ * The target of a redirect a Flight payload carries (`metadata.redirect`), or
+ * null when the client refuses it. An explicit off-host one
+ * (`redirect(url, { external: true })`) is scheme-validated only:
+ * `external` waives the same-origin check the app opted out of, not scheme
+ * safety. Every other one must stay on this origin.
+ */
+export function validatePayloadRedirect(redirect: {
+  url: string;
+  external?: boolean;
+}): string | null {
+  return redirect.external
+    ? validateExternalRedirect(redirect.url, window.location.origin)
+    : validateRedirectOrigin(redirect.url, window.location.origin);
+}

package/src/build/generate-route-types.ts

@@ -13,6 +13,7 @@ export {
   type ScanFilter,
   createScanFilter,
   findTsFiles,
+  isInSkippedScanDir,
 } from "./route-types/scan-filter.js";
 export {
   writePerModuleRouteTypes,

package/src/build/route-types/router-processing.ts

@@ -14,7 +14,7 @@ import {
 } from "node:path";
 import ts from "typescript";
 import { generateRouteTypesSource } from "./codegen.js";
-import type { ScanFilter } from "./scan-filter.js";
+import { isUniversallySkippedScanDir, type ScanFilter } from "./scan-filter.js";
 import { firstCodeMatchIndex } from "./source-scan.js";
 import {
   resolveImportedVariable,
@@ -58,12 +58,9 @@ function isRoutableSourceFile(name: string): boolean {
 
 function isExcludedScanDir(name: string): boolean {
   return (
-    name === "node_modules" ||
-    name === "dist" ||
-    name === "coverage" ||
+    isUniversallySkippedScanDir(name) ||
     name === "__tests__" ||
-    name === "__mocks__" ||
-    name.startsWith(".")
+    name === "__mocks__"
   );
 }
 

package/src/build/route-types/scan-filter.ts

@@ -1,4 +1,4 @@
-import { join, relative } from "node:path";
+import { isAbsolute, join, relative } from "node:path";
 import { readdirSync } from "node:fs";
 // @ts-ignore -- picomatch ships no .d.ts; types are trivial
 import picomatch from "picomatch";
@@ -44,8 +44,40 @@ export function createScanFilter(
 }
 
 /**
- * Recursively find .ts/.tsx files under a directory, skipping node_modules
- * and .gen. files.
+ * Directory names no discovery scan enters: findTsFiles() and the router scans
+ * (findRouterFiles/findHostRouterFiles, router-processing.ts) all build their
+ * skip rule on this, so a file below one is never discovered. Dot-directories
+ * cover a nested git worktree, a tool cache, or a test's working copy of
+ * another app.
+ */
+export function isUniversallySkippedScanDir(name: string): boolean {
+  return (
+    name === "node_modules" ||
+    name === "dist" ||
+    name === "coverage" ||
+    name.startsWith(".")
+  );
+}
+
+/**
+ * Whether a file under `root` sits in a directory every discovery scan skips
+ * (isUniversallySkippedScanDir). The dev route-file watcher uses it to ignore
+ * files discovery would never find. A path outside `root` is false.
+ */
+export function isInSkippedScanDir(
+  root: string,
+  absolutePath: string,
+): boolean {
+  const rel = relative(root, absolutePath);
+  if (isAbsolute(rel)) return false;
+  const dirs = rel.split(/[\\/]/).slice(0, -1);
+  if (dirs[0] === "..") return false;
+  return dirs.some(isUniversallySkippedScanDir);
+}
+
+/**
+ * Recursively find .ts/.tsx files under a directory, skipping the directories
+ * isUniversallySkippedScanDir() names, `build`, and .gen. files.
  */
 export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
   const results: string[] = [];
@@ -61,14 +93,9 @@ export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (
-        entry.name === "node_modules" ||
-        entry.name.startsWith(".") ||
-        entry.name === "dist" ||
-        entry.name === "build" ||
-        entry.name === "coverage"
-      )
+      if (isUniversallySkippedScanDir(entry.name) || entry.name === "build") {
         continue;
+      }
       results.push(...findTsFiles(fullPath, filter));
     } else if (
       (entry.name.endsWith(".ts") ||