@rangojs/router 0.0.0-experimental.ce770c9a → 0.0.0-experimental.d5d3070a

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

@@ -14,6 +14,7 @@ import {
   getParallelEntries,
   getParallelSlotEntries,
   type EntryData,
+  type ParallelEntryData,
 } from "../../server/context";
 import type {
   HandlerContext,
@@ -34,54 +35,41 @@ import {
 import { resolveLoaderData } from "./loader-cache.js";
 import {
   handleHandlerResult,
+  warnOnStreamedResponse,
   tryStaticHandler,
   tryStaticSlot,
   resolveLayoutComponent,
   resolveWithErrorBoundary,
+  buildLoaderErrorContext,
 } from "./helpers.js";
+import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
-import { resolveSink, safeEmit } from "../telemetry.js";
-import { track } from "../../server/context.js";
-
-// ---------------------------------------------------------------------------
-// Telemetry helpers
-// ---------------------------------------------------------------------------
+import { observeEvent, observeHandler } from "../instrument.js";
+import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
+import {
+  track,
+  RangoContext,
+  runInsideLoaderScope,
+} from "../../server/context.js";
 
 /**
- * Attach a fire-and-forget rejection observer to a streamed handler promise.
- * Silently no-ops when called outside RouterContext (e.g. in unit tests).
+ * Trace a parallel slot that's being force-rendered on a full refetch (client
+ * has no cached state). User revalidate fns are bypassed in this case — see
+ * the call sites for the load-bearing rationale.
  */
-function observeStreamedHandler(
-  promise: Promise<ReactNode>,
-  segmentId: string,
-  segmentType: string,
-  pathname?: string,
-  routeKey?: string,
-  params?: Record<string, string>,
+function traceFullRefetchedParallelSlot(
+  parallelId: string,
+  belongsToRoute: boolean,
 ): void {
-  let routerCtx;
-  try {
-    routerCtx = getRouterContext();
-  } catch {
-    return;
-  }
-  if (!routerCtx?.telemetry) return;
-  const sink = resolveSink(routerCtx.telemetry);
-  const reqId = routerCtx.requestId;
-  promise.catch((err: unknown) => {
-    const errorObj = err instanceof Error ? err : new Error(String(err));
-    safeEmit(sink, {
-      type: "handler.error",
-      timestamp: performance.now(),
-      requestId: reqId,
-      segmentId,
-      segmentType,
-      error: errorObj,
-      handledByBoundary: true,
-      pathname,
-      routeKey,
-      params,
-    });
+  if (!isTraceActive()) return;
+  pushRevalidationTraceEntry({
+    segmentId: parallelId,
+    segmentType: "parallel",
+    belongsToRoute,
+    source: "parallel",
+    defaultShouldRevalidate: true,
+    finalShouldRevalidate: true,
+    reason: "full-refetch",
   });
 }
 
@@ -100,23 +88,14 @@ function emitRevalidationDecision(
   routeKey: string,
   shouldRevalidate: boolean,
 ): void {
-  let routerCtx;
-  try {
-    routerCtx = getRouterContext();
-  } catch {
-    return;
-  }
-  if (routerCtx?.telemetry) {
-    safeEmit(resolveSink(routerCtx.telemetry), {
-      type: "revalidation.decision",
-      timestamp: performance.now(),
-      requestId: routerCtx.requestId,
-      segmentId,
-      pathname,
-      routeKey,
-      shouldRevalidate,
-    });
-  }
+  observeEvent({
+    type: "revalidation.decision",
+    timestamp: performance.now(),
+    segmentId,
+    pathname,
+    routeKey,
+    shouldRevalidate,
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -221,6 +200,10 @@ export async function resolveLoadersWithRevalidation<TEnv>(
     ),
   );
 
+  // Partial (revalidation) render path: a throwing DSL loader must still fire
+  // onError/loader.error. isPartial flags the reporting phase accordingly.
+  const errorContext = { ...buildLoaderErrorContext(ctx), isPartial: true };
+
   const loadersToRun = revalidationChecks.filter((c) => c.shouldRun);
   const segments: ResolvedSegment[] = loadersToRun.map(
     ({ loaderEntry, loader, segmentId, index }) => ({
@@ -232,10 +215,13 @@ export async function resolveLoadersWithRevalidation<TEnv>(
       params: ctx.params,
       loaderId: loader.$$id,
       loaderData: deps.wrapLoaderPromise(
-        resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+        runInsideLoaderScope(() =>
+          resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+        ),
         entry,
         segmentId,
         ctx.pathname,
+        errorContext,
       ),
       belongsToRoute,
     }),
@@ -269,28 +255,39 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
     belongsToRoute: boolean,
     shortCodeOverride?: string,
   ): Promise<void> {
-    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);
+    // 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);
     }
-    allMatchedIds.push(...matchedIds);
 
     const seenParallelEntryIds = new Set<string>();
     for (const parallelEntry of getParallelEntries(entry.parallel)) {
@@ -302,6 +299,39 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
     const childBelongsToRoute = belongsToRoute || entry.type === "route";
     for (const layoutEntry of entry.layout) {
       await collectEntryLoaders(layoutEntry, childBelongsToRoute);
+      // Inherit route loaders for orphan layouts with parallels.
+      // Resolve directly — do NOT re-enter collectEntryLoaders with the
+      // route entry, as that would re-iterate route.layout and loop.
+      if (
+        entry.type === "route" &&
+        entry.loader &&
+        entry.loader.length > 0 &&
+        Object.keys(layoutEntry.parallel).length > 0
+      ) {
+        const inherited = await resolveLoadersWithRevalidation(
+          entry,
+          context,
+          childBelongsToRoute,
+          clientSegmentIds,
+          prevParams,
+          request,
+          prevUrl,
+          nextUrl,
+          routeKey,
+          deps,
+          actionContext,
+          layoutEntry.shortCode,
+          stale,
+        );
+        for (const seg of inherited.segments) {
+          if (!seenIds.has(seg.id)) {
+            seenIds.add(seg.id);
+            seg._inherited = true;
+            allLoaderSegments.push(seg);
+          }
+        }
+        allMatchedIds.push(...inherited.matchedIds);
+      }
     }
   }
 
@@ -354,6 +384,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.
  */
@@ -371,9 +492,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(
@@ -398,44 +540,61 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
 
     const isFullRefetch = clientSegmentIds.size === 0;
     const isNewParent = !clientSegmentIds.has(entry.shortCode);
-    if (
-      isFullRefetch ||
-      clientSegmentIds.has(parallelId) ||
-      belongsToRoute ||
-      isNewParent
-    ) {
-      matchedIds.push(parallelId);
+
+    // 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
+    // on the next request, perpetuating the staleness).
+    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;
-      }
+    let shouldResolve: boolean;
+    if (isFullRefetch) {
+      // Client has nothing cached — slot MUST render. User revalidate fns are
+      // bypassed here because returning false would leave the segment blank
+      // with no client-side fallback.
+      traceFullRefetchedParallelSlot(parallelId, belongsToRoute);
+      shouldResolve = true;
+    } else {
+      // For non-empty client sets, consult user revalidate fns. When the slot
+      // is unknown to the client, override the type-derived default so the
+      // soft chain seeds with the right "new segment" / "parent-chain" value.
+      let defaultOverride: { value: boolean; reason: string } | undefined;
       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 value =
+          parentChainDefault === "force-render"
+            ? true
+            : belongsToRoute || isNewParent;
+        defaultOverride = {
+          value,
+          reason: value ? "new-segment" : "skip-parent-chain",
+        };
       }
 
       const dummySegment: ResolvedSegment = {
@@ -453,7 +612,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
           : {}),
       };
 
-      return await evaluateRevalidation({
+      shouldResolve = await evaluateRevalidation({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -469,8 +628,9 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
         actionContext,
         stale,
         traceSource: "parallel",
+        defaultOverride,
       });
-    })();
+    }
     emitRevalidationDecision(
       parallelId,
       context.pathname,
@@ -478,44 +638,17 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       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;
-      }
-    }
+    const { component, handlerRan } = await resolveParallelSlotComponent({
+      shouldResolve,
+      parallelEntry,
+      slot,
+      parallelId,
+      handler,
+      context,
+      deps,
+      routeKey,
+      params,
+    });
 
     segments.push({
       id: parallelId,
@@ -524,9 +657,13 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       index: 0,
       component,
       loading: parallelEntry.loading === false ? null : parallelEntry.loading,
-      transition: parallelEntry.transition,
+      transition: applyViewTransitionDefault(
+        parallelEntry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       slot,
+      _handlerRan: handlerRan,
       belongsToRoute,
       parallelName: `${parallelEntry.id}.${slot}`,
       ...(parallelEntry.mountPath
@@ -534,28 +671,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 };
@@ -581,6 +699,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
 ): Promise<{ segment: ResolvedSegment; matchedId: string }> {
   const matchedId = entry.shortCode;
 
+  let handlerRan = false;
   const component = await revalidate(
     async () => {
       const hasSegment = clientSegmentIds.has(entry.shortCode);
@@ -657,6 +776,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       return shouldRevalidate;
     },
     async () => {
+      handlerRan = true;
       const doneHandler = track(`handler:${entry.id}`, 2);
       (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
         entry.shortCode;
@@ -671,14 +791,26 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         return staticComponent;
       }
       const routeEntry = entry as Extract<EntryData, { type: "route" }>;
+      // For Passthrough routes at runtime, use the live handler instead of
+      // the build handler. At build time (context.build === true), always
+      // use the build handler from routeEntry.handler.
+      const handler =
+        !context.build && routeEntry.liveHandler
+          ? routeEntry.liveHandler
+          : routeEntry.handler;
       if (!routeEntry.loading) {
-        const result = handleHandlerResult(await routeEntry.handler(context));
+        const result = handleHandlerResult(
+          await observeHandler(entry.id, handler, context),
+        );
         doneHandler();
         return result;
       }
       if (!actionContext) {
-        const result = handleHandlerResult(routeEntry.handler(context));
+        const result = handleHandlerResult(
+          observeHandler(entry.id, handler, context),
+        );
         if (result instanceof Promise) {
+          warnOnStreamedResponse(result, routeEntry.id);
           result.finally(doneHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
             segmentId: entry.shortCode,
@@ -701,7 +833,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         entryId: entry.id,
       });
       const actionResult = handleHandlerResult(
-        await routeEntry.handler(context),
+        await observeHandler(entry.id, handler, context),
       );
       doneHandler();
       return {
@@ -711,10 +843,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,
@@ -724,13 +858,17 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
     index: 0,
     component: resolvedComponent,
     loading: entry.loading === false ? null : entry.loading,
-    transition: entry.transition,
+    transition: applyViewTransitionDefault(
+      entry.transition,
+      deps.viewTransitionDefault,
+    ),
     params,
     belongsToRoute,
     ...(entry.type === "layout" || entry.type === "cache"
       ? { layoutName: entry.id }
       : {}),
     ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
+    _handlerRan: handlerRan,
   };
 
   return { segment, matchedId };
@@ -749,7 +887,6 @@ export async function resolveSegmentWithRevalidation<TEnv>(
   request: Request,
   prevUrl: URL,
   nextUrl: URL,
-  loaderPromises: Map<string, Promise<any>>,
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
   stale?: boolean,
@@ -811,11 +948,11 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         prevUrl,
         nextUrl,
         routeKey,
-        loaderPromises,
         true,
         deps,
         actionContext,
         stale,
+        entry,
       );
       segments.push(...orphanResult.segments);
       matchedIds.push(...orphanResult.matchedIds);
@@ -895,7 +1032,6 @@ export async function resolveSegmentWithRevalidation<TEnv>(
         prevUrl,
         nextUrl,
         routeKey,
-        loaderPromises,
         false,
         deps,
         actionContext,
@@ -922,11 +1058,12 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   prevUrl: URL,
   nextUrl: URL,
   routeKey: string,
-  loaderPromises: Map<string, Promise<any>>,
   belongsToRoute: boolean,
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
   stale?: boolean,
+  /** Parent route entry — its loaders are inherited so parallel slots can access them. */
+  parentRouteEntry?: EntryData,
 ): Promise<SegmentRevalidationResult> {
   invariant(
     orphan.type === "layout" || orphan.type === "cache",
@@ -954,6 +1091,37 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   segments.push(...loaderResult.segments);
   matchedIds.push(...loaderResult.matchedIds);
 
+  // Inherit parent route's loaders so parallel slots inside this layout
+  // can access them via useLoader(). See resolveOrphanLayout in fresh.ts.
+  if (
+    parentRouteEntry &&
+    parentRouteEntry.loader &&
+    parentRouteEntry.loader.length > 0 &&
+    Object.keys(orphan.parallel).length > 0
+  ) {
+    const inheritedResult = await resolveLoadersWithRevalidation(
+      parentRouteEntry,
+      context,
+      belongsToRoute,
+      clientSegmentIds,
+      prevParams,
+      request,
+      prevUrl,
+      nextUrl,
+      routeKey,
+      deps,
+      actionContext,
+      orphan.shortCode,
+      stale,
+    );
+    // Tag as inherited so buildMatchResult can deduplicate when safe
+    for (const s of inheritedResult.segments) {
+      s._inherited = true;
+    }
+    segments.push(...inheritedResult.segments);
+    matchedIds.push(...inheritedResult.matchedIds);
+  }
+
   // Handler-first: resolve orphan layout handler before its parallels
   // so ctx.set() values are visible to parallel children.
   matchedIds.push(orphan.shortCode);
@@ -1026,165 +1194,40 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     belongsToRoute,
     layoutName: orphan.id,
     loading: orphan.loading === false ? null : orphan.loading,
-    transition: orphan.transition,
+    transition: applyViewTransitionDefault(
+      orphan.transition,
+      deps.viewTransitionDefault,
+    ),
     ...(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)) {
-      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];
-
-    // 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 (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 }
-        : {}),
-    });
-  }
+  // 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 };
 }
@@ -1202,7 +1245,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,
@@ -1235,6 +1277,10 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     }
 
     const nonParallelEntry = entry as Exclude<EntryData, { type: "parallel" }>;
+    if (entry.type === "cache") {
+      const store = RangoContext.getStore();
+      if (store) store.insideCacheScope = true;
+    }
     const doneEntry = track(`segment:${entry.id}`, 1);
     const resolved = await resolveWithErrorBoundary(
       nonParallelEntry,
@@ -1250,7 +1296,6 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
           request,
           prevUrl,
           nextUrl,
-          loaderPromises,
           deps,
           actionContext,
           stale,