@rangojs/router 0.0.0-experimental.125 → 0.0.0-experimental.126

package/src/router/segment-resolution/revalidation.ts

@@ -14,6 +14,7 @@ import {
   getParallelEntries,
   getParallelSlotEntries,
   type EntryData,
+  type ParallelEntryData,
 } from "../../server/context";
 import type {
   HandlerContext,
@@ -386,6 +387,97 @@ export function buildEntryRevalidateMap(
   return map;
 }
 
+/**
+ * Resolve the component for a single parallel slot on the revalidation path.
+ * Pure component resolution shared verbatim by
+ * resolveParallelSegmentsWithRevalidation and the orphan-inlined loop in
+ * resolveOrphanLayoutWithRevalidation: try the static slot cache, else run the
+ * slot handler (pinning _currentSegmentId to the slot id so handle pushes land
+ * in the slot's own bucket, and wrapping a streamed handler). Returns the
+ * resolved component and whether the handler actually ran. Does NOT touch the
+ * revalidate-default policy (the caller decides shouldResolve, including the
+ * orphan-vs-main defaultOverride divergence) or loader-resolution ordering.
+ */
+async function resolveParallelSlotComponent<TEnv>(args: {
+  shouldResolve: boolean;
+  parallelEntry: ParallelEntryData;
+  slot: string;
+  parallelId: string;
+  handler:
+    | ((ctx: HandlerContext<any, TEnv>) => ReactNode | Promise<ReactNode>)
+    | ReactNode
+    | undefined;
+  context: HandlerContext<any, TEnv>;
+  deps: SegmentResolutionDeps<TEnv>;
+  routeKey: string;
+  params: Record<string, string>;
+}): Promise<{ component: ReactNode | undefined; handlerRan: boolean }> {
+  const {
+    shouldResolve,
+    parallelEntry,
+    slot,
+    parallelId,
+    handler,
+    context,
+    deps,
+    routeKey,
+    params,
+  } = args;
+
+  let component: ReactNode | undefined;
+  let handlerRan = false;
+  if (shouldResolve) {
+    component = await tryStaticSlot(parallelEntry, slot, parallelId);
+    // tryStaticSlot returning a value means the static cache supplied the
+    // component — handler did NOT run. handlerRan stays false.
+  }
+  if (component === undefined) {
+    const hasLoadingFallback =
+      parallelEntry.loading !== undefined && parallelEntry.loading !== false;
+    if (!shouldResolve) {
+      component = null;
+    } else if (handler === undefined) {
+      // Handler evicted (production static slot) but static lookup missed.
+      // Nothing to render — use null so the client keeps its cached version.
+      component = null;
+    } else {
+      // Slot-keyed pushes — slot owns its own bucket, parent layout owns its
+      // own. On slot-only revalidations the partial merge updates only the
+      // slot's bucket; the parent's bucket stays intact.
+      (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+        parallelId;
+      handlerRan = true;
+      if (hasLoadingFallback) {
+        const result =
+          typeof handler === "function" ? handler(context) : handler;
+        if (result instanceof Promise) {
+          warnOnStreamedResponse(result, parallelId);
+          const tracked = deps.trackHandler(result, {
+            segmentId: parallelId,
+            segmentType: "parallel",
+          });
+          observeStreamedHandler(
+            tracked,
+            parallelId,
+            "parallel",
+            context.pathname,
+            routeKey,
+            params,
+          );
+          component = tracked as ReactNode;
+        } else {
+          component = result as ReactNode;
+        }
+      } else {
+        component =
+          typeof handler === "function" ? await handler(context) : handler;
+      }
+    }
+  }
+
+  return { component, handlerRan };
+}
+
 /**
  * Resolve parallel segments with revalidation.
  */
@@ -403,9 +495,30 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
   stale?: boolean,
+  options?: {
+    /**
+     * Seed for an unknown parent-chain slot (slot not in clientSegmentIds) when
+     * there are no deciding revalidate fns. "type-derived" (default, main path):
+     * `belongsToRoute || isNewParent`. "force-render" (orphan path): always
+     * `true` — orphan parallels always belong to the route and must render
+     * unless the user opts out via revalidate(); the #482 blank-parent-chain-
+     * slot guard.
+     */
+    parentChainDefault?: "type-derived" | "force-render";
+    /**
+     * When a slot's loaders are resolved relative to the slot segment push.
+     * "after" (default, main path) pushes the slot segment first; "before"
+     * (orphan path) resolves loaders first. This only changes the
+     * segments/matchedIds emission ORDER (the client reconciler is insensitive
+     * to it: loader sub-ids are filtered out and slots are re-grouped by parent).
+     */
+    loaderOrder?: "after" | "before";
+  },
 ): Promise<SegmentRevalidationResult> {
   const segments: ResolvedSegment[] = [];
   const matchedIds: string[] = [];
+  const parentChainDefault = options?.parentChainDefault ?? "type-derived";
+  const loaderOrder = options?.loaderOrder ?? "after";
 
   const resolvedParallelEntries = new Set<string>();
   for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
@@ -430,6 +543,34 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
 
     const isFullRefetch = clientSegmentIds.size === 0;
     const isNewParent = !clientSegmentIds.has(entry.shortCode);
+
+    // A slot's loaders (never cached) are deduped per parallel entry and
+    // emitted either before or after the slot segment per loaderOrder.
+    const resolveSlotLoaders = async () => {
+      if (resolvedParallelEntries.has(parallelEntry.id)) return;
+      const loaderResult = await resolveLoadersWithRevalidation(
+        parallelEntry,
+        context,
+        belongsToRoute,
+        clientSegmentIds,
+        prevParams,
+        request,
+        prevUrl,
+        nextUrl,
+        routeKey,
+        deps,
+        actionContext,
+        entry.shortCode,
+        stale,
+      );
+      segments.push(...loaderResult.segments);
+      matchedIds.push(...loaderResult.matchedIds);
+      resolvedParallelEntries.add(parallelEntry.id);
+    };
+
+    if (loaderOrder === "before") {
+      await resolveSlotLoaders();
+    }
     // Always announce the slot in matchedIds — it's unconditionally appended
     // to `segments` below, and a segment present in segments but missing from
     // matched lets the client prune it (then it's missing from clientSegmentIds
@@ -449,7 +590,10 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       // soft chain seeds with the right "new segment" / "parent-chain" value.
       let defaultOverride: { value: boolean; reason: string } | undefined;
       if (!clientSegmentIds.has(parallelId)) {
-        const value = belongsToRoute || isNewParent;
+        const value =
+          parentChainDefault === "force-render"
+            ? true
+            : belongsToRoute || isNewParent;
         defaultOverride = {
           value,
           reason: value ? "new-segment" : "skip-parent-chain",
@@ -497,56 +641,17 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       shouldResolve,
     );
 
-    let component: ReactNode | undefined;
-    let handlerRan = false;
-    if (shouldResolve) {
-      component = await tryStaticSlot(parallelEntry, slot, parallelId);
-      // tryStaticSlot returning a value means the static cache supplied the
-      // component — handler did NOT run. handlerRan stays false.
-    }
-    if (component === undefined) {
-      const hasLoadingFallback =
-        parallelEntry.loading !== undefined && parallelEntry.loading !== false;
-      if (!shouldResolve) {
-        component = null;
-      } else if (handler === undefined) {
-        // Handler evicted (production static slot) but static lookup missed.
-        // Nothing to render — use null so the client keeps its cached version.
-        component = null;
-      } else {
-        // Slot-keyed pushes — slot owns its own bucket, parent layout owns
-        // its own. On slot-only revalidations the partial merge updates only
-        // the slot's bucket; the parent's bucket stays intact.
-        (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
-          parallelId;
-        handlerRan = true;
-        if (hasLoadingFallback) {
-          const result =
-            typeof handler === "function" ? handler(context) : handler;
-          if (result instanceof Promise) {
-            warnOnStreamedResponse(result, parallelId);
-            const tracked = deps.trackHandler(result, {
-              segmentId: parallelId,
-              segmentType: "parallel",
-            });
-            observeStreamedHandler(
-              tracked,
-              parallelId,
-              "parallel",
-              context.pathname,
-              routeKey,
-              params,
-            );
-            component = tracked as ReactNode;
-          } else {
-            component = result as ReactNode;
-          }
-        } else {
-          component =
-            typeof handler === "function" ? await handler(context) : handler;
-        }
-      }
-    }
+    const { component, handlerRan } = await resolveParallelSlotComponent({
+      shouldResolve,
+      parallelEntry,
+      slot,
+      parallelId,
+      handler,
+      context,
+      deps,
+      routeKey,
+      params,
+    });
 
     segments.push({
       id: parallelId,
@@ -569,28 +674,9 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
         : {}),
     });
 
-    if (resolvedParallelEntries.has(parallelEntry.id)) {
-      continue;
+    if (loaderOrder === "after") {
+      await resolveSlotLoaders();
     }
-
-    const loaderResult = await resolveLoadersWithRevalidation(
-      parallelEntry,
-      context,
-      belongsToRoute,
-      clientSegmentIds,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      routeKey,
-      deps,
-      actionContext,
-      entry.shortCode,
-      stale,
-    );
-    segments.push(...loaderResult.segments);
-    matchedIds.push(...loaderResult.matchedIds);
-    resolvedParallelEntries.add(parallelEntry.id);
   }
 
   return { segments, matchedIds };
@@ -798,7 +884,6 @@ export async function resolveSegmentWithRevalidation<TEnv>(
   request: Request,
   prevUrl: URL,
   nextUrl: URL,
-  loaderPromises: Map<string, Promise<any>>,
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
   stale?: boolean,
@@ -1113,174 +1198,33 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
 
-  const resolvedParallelEntries = new Set<string>();
-  for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
-    orphan.parallel,
-  )) {
-    invariant(
-      parallelEntry.type === "parallel",
-      `Expected parallel entry, got: ${parallelEntry.type}`,
-    );
-
-    if (!resolvedParallelEntries.has(parallelEntry.id)) {
-      // shortCodeOverride must match the parent layout, not the parallel entry.
-      const loaderResult = await resolveLoadersWithRevalidation(
-        parallelEntry,
-        context,
-        belongsToRoute,
-        clientSegmentIds,
-        prevParams,
-        request,
-        prevUrl,
-        nextUrl,
-        routeKey,
-        deps,
-        actionContext,
-        orphan.shortCode,
-        stale,
-      );
-      segments.push(...loaderResult.segments);
-      matchedIds.push(...loaderResult.matchedIds);
-      resolvedParallelEntries.add(parallelEntry.id);
-    }
-
-    const slots = parallelEntry.handler as Record<
-      `@${string}`,
-      | ((ctx: HandlerContext<any, TEnv>) => ReactNode | Promise<ReactNode>)
-      | ReactNode
-    >;
-    // Handler may be undefined in production after static handler eviction.
-    const handler = slots[slot];
-
-    // Use orphan.shortCode (the parent layout) to match the SSR path
-    // (resolveParallelEntry receives parentShortCode = orphan.shortCode).
-    // Using parallelEntry.shortCode would generate IDs the client doesn't know about.
-    const parallelId = `${orphan.shortCode}.${slot}`;
-    matchedIds.push(parallelId);
-
-    const isFullRefetch = clientSegmentIds.size === 0;
-    let shouldResolve: boolean;
-    if (isFullRefetch) {
-      // Same load-bearing rationale as the main parallel path: full refetch
-      // means the client has nothing to fall back to, so the slot must render.
-      traceFullRefetchedParallelSlot(parallelId, belongsToRoute);
-      shouldResolve = true;
-    } else {
-      // When slot is unknown to the client, seed the soft chain with `true`
-      // (orphan parallels always belong to the route — we want them rendered
-      // unless the user explicitly opts out via revalidate()).
-      const defaultOverride = clientSegmentIds.has(parallelId)
-        ? undefined
-        : { value: true, reason: "new-segment" };
-
-      const dummySegment: ResolvedSegment = {
-        id: parallelId,
-        namespace: parallelEntry.id,
-        type: "parallel",
-        index: 0,
-        component: null as any,
-        params,
-        slot,
-        belongsToRoute,
-        parallelName: `${parallelEntry.id}.${slot}`,
-        ...(parallelEntry.mountPath
-          ? { mountPath: parallelEntry.mountPath }
-          : {}),
-      };
-
-      shouldResolve = await evaluateRevalidation({
-        segment: dummySegment,
-        prevParams,
-        getPrevSegment: null,
-        request,
-        prevUrl,
-        nextUrl,
-        revalidations: parallelEntry.revalidate.map((fn, i) => ({
-          name: `revalidate${i}`,
-          fn,
-        })),
-        routeKey,
-        context,
-        actionContext,
-        stale,
-        traceSource: "parallel",
-        defaultOverride,
-      });
-    }
-    emitRevalidationDecision(
-      parallelId,
-      context.pathname,
-      routeKey,
-      shouldResolve,
-    );
-
-    let component: ReactNode | undefined;
-    let handlerRan = false;
-    if (shouldResolve) {
-      component = await tryStaticSlot(parallelEntry, slot, parallelId);
-    }
-    if (component === undefined) {
-      const hasLoadingFallback =
-        parallelEntry.loading !== undefined && parallelEntry.loading !== false;
-      if (!shouldResolve) {
-        component = null;
-      } else if (handler === undefined) {
-        // Handler evicted (production static slot) but static lookup missed.
-        component = null;
-      } else {
-        // Slot-keyed pushes — see resolveParallelSegmentsWithRevalidation.
-        (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
-          parallelId;
-        handlerRan = true;
-        if (hasLoadingFallback) {
-          const result =
-            typeof handler === "function" ? handler(context) : handler;
-          if (result instanceof Promise) {
-            warnOnStreamedResponse(result, parallelId);
-            const tracked = deps.trackHandler(result, {
-              segmentId: parallelId,
-              segmentType: "parallel",
-            });
-            observeStreamedHandler(
-              tracked,
-              parallelId,
-              "parallel",
-              context.pathname,
-              routeKey,
-              params,
-            );
-            component = tracked as ReactNode;
-          } else {
-            component = result as ReactNode;
-          }
-        } else {
-          component =
-            typeof handler === "function" ? await handler(context) : handler;
-        }
-      }
-    }
-
-    segments.push({
-      id: parallelId,
-      namespace: parallelEntry.id,
-      type: "parallel",
-      index: 0,
-      component,
-      loading: parallelEntry.loading === false ? null : parallelEntry.loading,
-      transition: applyViewTransitionDefault(
-        parallelEntry.transition,
-        deps.viewTransitionDefault,
-      ),
-      params,
-      slot,
-      _handlerRan: handlerRan,
-      belongsToRoute,
-      parallelName: `${parallelEntry.id}.${slot}`,
-      ...(parallelEntry.mountPath
-        ? { mountPath: parallelEntry.mountPath }
-        : {}),
-    });
-  }
+  // Resolve the orphan layout's parallel slots through the shared main-path
+  // helper. The orphan policy is carried by explicit args, byte-for-byte:
+  //   - parentChainDefault "force-render": an unknown parent-chain slot seeds
+  //     `true` (orphan parallels always belong to the route — the #482 guard),
+  //     where the main path would seed `belongsToRoute || isNewParent`.
+  //   - loaderOrder "before": a slot's loaders are emitted before the slot
+  //     segment, matching the prior inlined order.
+  // `entry.shortCode` inside the helper is `orphan.shortCode` (orphan is passed
+  // as `entry`), so the parallel ids + loader shortCodeOverride are unchanged.
+  const parallelResult = await resolveParallelSegmentsWithRevalidation(
+    orphan,
+    params,
+    context,
+    belongsToRoute,
+    clientSegmentIds,
+    prevParams,
+    request,
+    prevUrl,
+    nextUrl,
+    routeKey,
+    deps,
+    actionContext,
+    stale,
+    { parentChainDefault: "force-render", loaderOrder: "before" },
+  );
+  segments.push(...parallelResult.segments);
+  matchedIds.push(...parallelResult.matchedIds);
 
   return { segments, matchedIds };
 }
@@ -1298,7 +1242,6 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
   request: Request,
   prevUrl: URL,
   nextUrl: URL,
-  loaderPromises: Map<string, Promise<any>>,
   actionContext: ActionContext | undefined,
   interceptResult: { intercept: any; entry: EntryData } | null,
   localRouteName: string,
@@ -1350,7 +1293,6 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
           request,
           prevUrl,
           nextUrl,
-          loaderPromises,
           deps,
           actionContext,
           stale,

package/src/router/segment-wrappers.ts

@@ -68,7 +68,6 @@ export interface SegmentWrappers<TEnv = any> {
     request: Request,
     prevUrl: URL,
     nextUrl: URL,
-    loaderPromises: Map<string, Promise<any>>,
     actionContext:
       | {
           actionId?: string;
@@ -192,7 +191,6 @@ export function createSegmentWrappers<TEnv = any>(
     request: Request,
     prevUrl: URL,
     nextUrl: URL,
-    loaderPromises: Map<string, Promise<any>>,
     actionContext:
       | {
           actionId?: string;
@@ -216,7 +214,6 @@ export function createSegmentWrappers<TEnv = any>(
       request,
       prevUrl,
       nextUrl,
-      loaderPromises,
       actionContext,
       interceptResult,
       localRouteName,

package/src/router/trie-matching.ts

@@ -15,10 +15,6 @@ export interface TrieMatchResult {
   sp: string;
   /** Matched route params */
   params: Record<string, string>;
-  /** Optional param names declared on the route. Absent params are omitted
-   * from `params` (read as `undefined`), matching the
-   * `ExtractParams<"/:locale?/...">` type. */
-  optionalParams?: string[];
   /** Redirect target if trailing slash requires it */
   redirectTo?: string;
   /** Route has pre-rendered data available */
@@ -182,6 +178,9 @@ function walkTrie(
   }
 
   if (node.xp) {
+    // node.xp keys are pre-sorted longest-suffix-first at build time
+    // (route-trie.ts sortSuffixParams), so the first match is the most specific
+    // suffix: `/app.min.js` matches `:file.min.js` before `:file.js`.
     for (const suffix in node.xp) {
       if (segment.endsWith(suffix) && segment.length > suffix.length) {
         const paramValue = segment.slice(0, -suffix.length);
@@ -274,7 +273,6 @@ function validateAndBuild(
     params,
   };
 
-  if (leaf.op) result.optionalParams = leaf.op;
   if (redirectTo) result.redirectTo = redirectTo;
   if (leaf.pr) result.pr = true;
   if (leaf.pt) result.pt = true;

package/src/router.ts

@@ -1,9 +1,6 @@
 import { type ReactNode } from "react";
 import { createCacheScope } from "./cache/cache-scope.js";
-import {
-  setCacheProfiles,
-  resolveCacheProfiles,
-} from "./cache/profile-registry.js";
+import { resolveCacheProfiles } from "./cache/profile-registry.js";
 import { isCachedFunction } from "./cache/taint.js";
 import { assertClientComponent } from "./component-utils.js";
 import { DefaultDocument } from "./components/DefaultDocument.js";
@@ -181,11 +178,10 @@ export function createRouter<TEnv = any>(
   // Resolve telemetry sink (no-op when not configured)
   const telemetry = resolveSink(telemetrySink);
 
-  // Resolve cache profiles: merge user config with guaranteed default profile.
-  // This resolved map is both stored on the router (for per-request context)
-  // and written to the global registry (for DSL-time cache("profileName")).
+  // Resolve cache profiles: merge user config with the guaranteed default
+  // profile. This resolved map is threaded onto each request context; the
+  // "use cache: <profile>" runtime path reads it request-scoped.
   const resolvedCacheProfiles = resolveCacheProfiles(cacheProfilesOption);
-  setCacheProfiles(resolvedCacheProfiles);
 
   // Source file: prefer Vite-injected path (zero cost), fall back to
   // stack trace parsing for non-Vite environments (e.g. tests).
@@ -355,7 +351,6 @@ export function createRouter<TEnv = any>(
       regex,
       paramNames,
       handler,
-      mountPrefix,
     });
   }
 

package/src/rsc/handler-context.ts

@@ -31,6 +31,7 @@ export interface HandlerContext<TEnv = unknown> {
   createRedirectFlightResponse: (
     redirectUrl: string,
     locationState?: Record<string, unknown>,
+    external?: boolean,
   ) => Response;
 
   /**

package/src/rsc/handler.ts

@@ -31,6 +31,7 @@ import {
   interceptRedirectForPartial,
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
+import { guardOutgoingRedirect } from "./redirect-guard.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 import {
   handleResponseRoute,
@@ -292,12 +293,13 @@ export function createRSCHandler<
   function createRedirectFlightResponse(
     redirectUrl: string,
     locationState?: Record<string, unknown>,
+    external?: boolean,
   ): Response {
     const redirectPayload: RscPayload = {
       metadata: {
         pathname: redirectUrl,
         segments: [],
-        redirect: { url: redirectUrl },
+        redirect: { url: redirectUrl, ...(external && { external: true }) },
         ...(locationState && { locationState }),
       },
     };
@@ -570,7 +572,12 @@ export function createRSCHandler<
         response.headers.set("Server-Timing", fullTiming);
       }
 
-      return response;
+      // Single open-redirect chokepoint: every response (PE, full-page,
+      // middleware short-circuit, response-route) funnels through here, so
+      // guarding browser-followed (3xx) redirects once covers them all and any
+      // future redirect exit. Soft SPA/Flight redirects are 200/204 and pass
+      // through untouched (validated client-side instead).
+      return guardOutgoingRedirect(response, url.origin, router.basename);
     });
   };