@rangojs/router 0.0.0-experimental.78a48627 → 0.0.0-experimental.7dc955ec

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

@@ -10,7 +10,11 @@ import type { ReactNode } from "react";
 import { invariant } from "../../errors";
 import { revalidate } from "../loader-resolution.js";
 import { evaluateRevalidation } from "../revalidation.js";
-import type { EntryData } from "../../server/context";
+import {
+  getParallelEntries,
+  getParallelSlotEntries,
+  type EntryData,
+} from "../../server/context";
 import type {
   HandlerContext,
   InternalHandlerContext,
@@ -38,6 +42,7 @@ import {
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import { track } from "../../server/context.js";
+import { RSCRouterContext } from "../../server/context.js";
 
 // ---------------------------------------------------------------------------
 // Telemetry helpers
@@ -141,6 +146,12 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   const loaderEntries = entry.loader ?? [];
   if (loaderEntries.length === 0) return { segments: [], matchedIds: [] };
 
+  // DSL loaders are always fresh — temporarily clear cache scope
+  // so non-cacheable var reads are allowed inside loader functions.
+  const store = RSCRouterContext.getStore();
+  const savedCacheScope = store?.insideCacheScope;
+  if (store) store.insideCacheScope = false;
+
   const shortCode = shortCodeOverride ?? entry.shortCode;
 
   const loaderMeta = loaderEntries.map((loaderEntry, i) => ({
@@ -237,6 +248,9 @@ export async function resolveLoadersWithRevalidation<TEnv>(
     }),
   );
 
+  // Restore cache scope after all loader promises are kicked off
+  if (store) store.insideCacheScope = savedCacheScope;
+
   return { segments, matchedIds };
 }
 
@@ -258,26 +272,62 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
 ): Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }> {
   const allLoaderSegments: ResolvedSegment[] = [];
   const allMatchedIds: string[] = [];
+  const seenIds = new Set<string>();
+
+  async function collectEntryLoaders(
+    entry: EntryData,
+    belongsToRoute: boolean,
+    shortCodeOverride?: string,
+  ): Promise<void> {
+    // Skip if all loaders from this entry have already been resolved
+    // via a parent (e.g., cache boundary wrapping a layout with shared loaders).
+    const loaderEntries = entry.loader ?? [];
+    const sc = shortCodeOverride ?? entry.shortCode;
+    const allAlreadySeen =
+      loaderEntries.length > 0 &&
+      loaderEntries.every((le, i) =>
+        seenIds.has(`${sc}D${i}.${le.loader.$$id}`),
+      );
+    if (!allAlreadySeen) {
+      const { segments, matchedIds } = await resolveLoadersWithRevalidation(
+        entry,
+        context,
+        belongsToRoute,
+        clientSegmentIds,
+        prevParams,
+        request,
+        prevUrl,
+        nextUrl,
+        routeKey,
+        deps,
+        actionContext,
+        shortCodeOverride,
+        stale,
+      );
+      for (const seg of segments) {
+        if (!seenIds.has(seg.id)) {
+          seenIds.add(seg.id);
+          allLoaderSegments.push(seg);
+        }
+      }
+      allMatchedIds.push(...matchedIds);
+    }
+
+    const seenParallelEntryIds = new Set<string>();
+    for (const parallelEntry of getParallelEntries(entry.parallel)) {
+      if (seenParallelEntryIds.has(parallelEntry.id)) continue;
+      seenParallelEntryIds.add(parallelEntry.id);
+      await collectEntryLoaders(parallelEntry, belongsToRoute, entry.shortCode);
+    }
+
+    const childBelongsToRoute = belongsToRoute || entry.type === "route";
+    for (const layoutEntry of entry.layout) {
+      await collectEntryLoaders(layoutEntry, childBelongsToRoute);
+    }
+  }
 
   for (const entry of entries) {
-    const belongsToRoute = entry.type === "route";
-    const { segments, matchedIds } = await resolveLoadersWithRevalidation(
-      entry,
-      context,
-      belongsToRoute,
-      clientSegmentIds,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      routeKey,
-      deps,
-      actionContext,
-      undefined, // shortCodeOverride
-      stale,
-    );
-    allLoaderSegments.push(...segments);
-    allMatchedIds.push(...matchedIds);
+    await collectEntryLoaders(entry, entry.type === "route");
   }
 
   return { segments: allLoaderSegments, matchedIds: allMatchedIds };
@@ -301,22 +351,20 @@ export function buildEntryRevalidateMap(
     map.set(entry.shortCode, { entry, revalidate: entry.revalidate });
 
     if (entry.type !== "parallel") {
-      for (const parallelEntry of entry.parallel) {
-        if (parallelEntry.type === "parallel") {
-          const slots = Object.keys(parallelEntry.handler) as `@${string}`[];
-          for (const slot of slots) {
-            const parallelId = `${parallelEntry.shortCode}.${slot}`;
-            map.set(parallelId, {
-              entry: parallelEntry,
-              revalidate: parallelEntry.revalidate,
-            });
-          }
-        }
+      for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+        entry.parallel,
+      )) {
+        const parallelParentShortCode = parentShortCode ?? entry.shortCode;
+        const parallelId = `${parallelParentShortCode}.${slot}`;
+        map.set(parallelId, {
+          entry: parallelEntry,
+          revalidate: parallelEntry.revalidate,
+        });
       }
     }
 
     for (const layoutEntry of entry.layout) {
-      processEntry(layoutEntry);
+      processEntry(layoutEntry, entry.shortCode);
     }
   }
 
@@ -348,7 +396,10 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
   const segments: ResolvedSegment[] = [];
   const matchedIds: string[] = [];
 
-  for (const parallelEntry of entry.parallel) {
+  const resolvedParallelEntries = new Set<string>();
+  for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+    entry.parallel,
+  )) {
     invariant(
       parallelEntry.type === "parallel",
       `Expected parallel entry, got: ${parallelEntry.type}`,
@@ -359,141 +410,61 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       | ((ctx: HandlerContext<any, TEnv>) => ReactNode | Promise<ReactNode>)
       | ReactNode
     >;
+    // In production, static handler bodies are evicted and the slot value
+    // may be undefined. The static store holds the pre-rendered component.
+    // We defer the handler check until after tryStaticSlot.
+    const handler = slots[slot];
+
+    const parallelId = `${entry.shortCode}.${slot}`;
+
+    const isFullRefetch = clientSegmentIds.size === 0;
+    const isNewParent = !clientSegmentIds.has(entry.shortCode);
+    if (
+      isFullRefetch ||
+      clientSegmentIds.has(parallelId) ||
+      belongsToRoute ||
+      isNewParent
+    ) {
+      matchedIds.push(parallelId);
+    }
 
-    for (const [slot, handler] of Object.entries(slots)) {
-      const parallelId = `${entry.shortCode}.${slot}`;
-
-      const isFullRefetch = clientSegmentIds.size === 0;
-      // When the parent layout is new (not in client's segment set),
-      // all its parallel children must be resolved and tracked.
-      // Without this, navigating to a new layout with parallels
-      // (e.g., BlogLayout with @sidebar) from a different route
-      // would silently drop those parallel segments.
-      const isNewParent = !clientSegmentIds.has(entry.shortCode);
-      if (
-        isFullRefetch ||
-        clientSegmentIds.has(parallelId) ||
-        belongsToRoute ||
-        isNewParent
-      ) {
-        matchedIds.push(parallelId);
-      }
-
-      const shouldResolve = await (async () => {
-        if (isFullRefetch) {
-          if (isTraceActive()) {
-            pushRevalidationTraceEntry({
-              segmentId: parallelId,
-              segmentType: "parallel",
-              belongsToRoute,
-              source: "parallel",
-              defaultShouldRevalidate: true,
-              finalShouldRevalidate: true,
-              reason: "full-refetch",
-            });
-          }
-          return true;
-        }
-        if (!clientSegmentIds.has(parallelId)) {
-          const result = belongsToRoute || isNewParent;
-          if (isTraceActive()) {
-            pushRevalidationTraceEntry({
-              segmentId: parallelId,
-              segmentType: "parallel",
-              belongsToRoute,
-              source: "parallel",
-              defaultShouldRevalidate: result,
-              finalShouldRevalidate: result,
-              reason: result ? "new-segment" : "skip-parent-chain",
-            });
-          }
-          return result;
+    const shouldResolve = await (async () => {
+      if (isFullRefetch) {
+        if (isTraceActive()) {
+          pushRevalidationTraceEntry({
+            segmentId: parallelId,
+            segmentType: "parallel",
+            belongsToRoute,
+            source: "parallel",
+            defaultShouldRevalidate: true,
+            finalShouldRevalidate: true,
+            reason: "full-refetch",
+          });
         }
-
-        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 }
-            : {}),
-        };
-
-        return 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",
-        });
-      })();
-      emitRevalidationDecision(
-        parallelId,
-        context.pathname,
-        routeKey,
-        shouldResolve,
-      );
-
-      let component: ReactNode | undefined;
-      if (shouldResolve) {
-        component = await tryStaticSlot(parallelEntry, slot, parallelId);
+        return true;
       }
-      if (component === undefined) {
-        const hasLoadingFallback =
-          parallelEntry.loading !== undefined &&
-          parallelEntry.loading !== false;
-        if (!shouldResolve) {
-          component = null;
-        } else if (hasLoadingFallback) {
-          const result =
-            typeof handler === "function" ? handler(context) : handler;
-          if (result instanceof Promise) {
-            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;
+      if (!clientSegmentIds.has(parallelId)) {
+        const result = belongsToRoute || isNewParent;
+        if (isTraceActive()) {
+          pushRevalidationTraceEntry({
+            segmentId: parallelId,
+            segmentType: "parallel",
+            belongsToRoute,
+            source: "parallel",
+            defaultShouldRevalidate: result,
+            finalShouldRevalidate: result,
+            reason: result ? "new-segment" : "skip-parent-chain",
+          });
         }
+        return result;
       }
 
-      segments.push({
+      const dummySegment: ResolvedSegment = {
         id: parallelId,
         namespace: parallelEntry.id,
         type: "parallel",
         index: 0,
-        component,
-        loading: parallelEntry.loading === false ? null : parallelEntry.loading,
-        transition: parallelEntry.transition,
+        component: null as any,
         params,
         slot,
         belongsToRoute,
@@ -501,28 +472,111 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
         ...(parallelEntry.mountPath
           ? { mountPath: parallelEntry.mountPath }
           : {}),
-      });
-    }
+      };
 
-    if (!parallelEntry.loading) {
-      const loaderResult = await resolveLoadersWithRevalidation(
-        parallelEntry,
-        context,
-        belongsToRoute,
-        clientSegmentIds,
+      return await evaluateRevalidation({
+        segment: dummySegment,
         prevParams,
+        getPrevSegment: null,
         request,
         prevUrl,
         nextUrl,
+        revalidations: parallelEntry.revalidate.map((fn, i) => ({
+          name: `revalidate${i}`,
+          fn,
+        })),
         routeKey,
-        deps,
+        context,
         actionContext,
-        entry.shortCode,
         stale,
-      );
-      segments.push(...loaderResult.segments);
-      matchedIds.push(...loaderResult.matchedIds);
+        traceSource: "parallel",
+      });
+    })();
+    emitRevalidationDecision(
+      parallelId,
+      context.pathname,
+      routeKey,
+      shouldResolve,
+    );
+
+    let component: ReactNode | undefined;
+    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.
+        // Nothing to render — use null so the client keeps its cached version.
+        component = null;
+      } else if (hasLoadingFallback) {
+        const result =
+          typeof handler === "function" ? handler(context) : handler;
+        if (result instanceof Promise) {
+          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: parallelEntry.transition,
+      params,
+      slot,
+      belongsToRoute,
+      parallelName: `${parallelEntry.id}.${slot}`,
+      ...(parallelEntry.mountPath
+        ? { mountPath: parallelEntry.mountPath }
+        : {}),
+    });
+
+    if (resolvedParallelEntries.has(parallelEntry.id)) {
+      continue;
+    }
+
+    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 };
@@ -678,10 +732,12 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
     () => null,
   );
 
+  // Normalize void handlers (undefined) to null so the reconciler's
+  // component === null checks work consistently for both void and explicit null.
   const resolvedComponent =
     component && typeof component === "object" && "content" in component
-      ? (component as { content: ReactNode }).content
-      : component;
+      ? ((component as { content: ReactNode }).content ?? null)
+      : (component ?? null);
 
   const segment: ResolvedSegment = {
     id: entry.shortCode,
@@ -997,143 +1053,72 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
 
-  for (const parallelEntry of orphan.parallel) {
+  const resolvedParallelEntries = new Set<string>();
+  for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+    orphan.parallel,
+  )) {
     invariant(
       parallelEntry.type === "parallel",
       `Expected parallel entry, got: ${parallelEntry.type}`,
     );
 
-    const loaderResult = await resolveLoadersWithRevalidation(
-      parallelEntry,
-      context,
-      belongsToRoute,
-      clientSegmentIds,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      routeKey,
-      deps,
-      actionContext,
-      undefined,
-      stale,
-    );
-    segments.push(...loaderResult.segments);
-    matchedIds.push(...loaderResult.matchedIds);
+    if (!resolvedParallelEntries.has(parallelEntry.id)) {
+      const loaderResult = await resolveLoadersWithRevalidation(
+        parallelEntry,
+        context,
+        belongsToRoute,
+        clientSegmentIds,
+        prevParams,
+        request,
+        prevUrl,
+        nextUrl,
+        routeKey,
+        deps,
+        actionContext,
+        undefined,
+        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];
 
-    for (const [slot, handler] of Object.entries(slots)) {
-      // 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);
+    // 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 shouldResolve = await (async () => {
-        if (!clientSegmentIds.has(parallelId)) {
-          if (isTraceActive()) {
-            pushRevalidationTraceEntry({
-              segmentId: parallelId,
-              segmentType: "parallel",
-              belongsToRoute,
-              source: "parallel",
-              defaultShouldRevalidate: true,
-              finalShouldRevalidate: true,
-              reason: "new-segment",
-            });
-          }
-          return true;
-        }
-
-        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 }
-            : {}),
-        };
-
-        return 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",
-        });
-      })();
-      emitRevalidationDecision(
-        parallelId,
-        context.pathname,
-        routeKey,
-        shouldResolve,
-      );
-
-      let component: ReactNode | undefined;
-      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 (hasLoadingFallback) {
-          const result =
-            typeof handler === "function" ? handler(context) : handler;
-          if (result instanceof Promise) {
-            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 shouldResolve = await (async () => {
+      if (!clientSegmentIds.has(parallelId)) {
+        if (isTraceActive()) {
+          pushRevalidationTraceEntry({
+            segmentId: parallelId,
+            segmentType: "parallel",
+            belongsToRoute,
+            source: "parallel",
+            defaultShouldRevalidate: true,
+            finalShouldRevalidate: true,
+            reason: "new-segment",
+          });
         }
+        return true;
       }
 
-      segments.push({
+      const dummySegment: ResolvedSegment = {
         id: parallelId,
         namespace: parallelEntry.id,
         type: "parallel",
         index: 0,
-        component,
-        loading: parallelEntry.loading === false ? null : parallelEntry.loading,
-        transition: parallelEntry.transition,
+        component: null as any,
         params,
         slot,
         belongsToRoute,
@@ -1141,8 +1126,87 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         ...(parallelEntry.mountPath
           ? { mountPath: parallelEntry.mountPath }
           : {}),
+      };
+
+      return 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",
       });
+    })();
+    emitRevalidationDecision(
+      parallelId,
+      context.pathname,
+      routeKey,
+      shouldResolve,
+    );
+
+    let component: ReactNode | undefined;
+    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 if (hasLoadingFallback) {
+        const result =
+          typeof handler === "function" ? handler(context) : handler;
+        if (result instanceof Promise) {
+          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: parallelEntry.transition,
+      params,
+      slot,
+      belongsToRoute,
+      parallelName: `${parallelEntry.id}.${slot}`,
+      ...(parallelEntry.mountPath
+        ? { mountPath: parallelEntry.mountPath }
+        : {}),
+    });
   }
 
   return { segments, matchedIds };
@@ -1194,6 +1258,10 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     }
 
     const nonParallelEntry = entry as Exclude<EntryData, { type: "parallel" }>;
+    if (entry.type === "cache") {
+      const store = RSCRouterContext.getStore();
+      if (store) store.insideCacheScope = true;
+    }
     const doneEntry = track(`segment:${entry.id}`, 1);
     const resolved = await resolveWithErrorBoundary(
       nonParallelEntry,