@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

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

@@ -0,0 +1,879 @@
+/**
+ * Fresh Path Segment Resolution
+ *
+ * Functions for resolving segments during a full (non-revalidation) request.
+ * Handles loaders, layouts, routes, parallels, orphan layouts, and error boundaries.
+ */
+
+import type { ReactNode } from "react";
+import { invariant } from "../../errors";
+import {
+  getParallelEntries,
+  getParallelSlotEntries,
+  type EntryData,
+} from "../../server/context";
+import type {
+  HandlerContext,
+  InternalHandlerContext,
+  ResolvedSegment,
+} from "../../types";
+import type { SegmentResolutionDeps } from "../types.js";
+import { resolveLoaderData } from "./loader-cache.js";
+import {
+  isShellCaptureActive,
+  entryLoadingMasksLoaders,
+} from "./loader-mask.js";
+import {
+  handleHandlerResult,
+  tryStaticHandler,
+  tryStaticSlot,
+  resolveLayoutComponent,
+  resolveWithErrorBoundary,
+  warnOnStreamedResponse,
+  buildLoaderErrorContext,
+} from "./helpers.js";
+import { applyViewTransitionDefault } from "./view-transition-default.js";
+import { _getRequestContext } from "../../server/request-context.js";
+import { getRouterContext } from "../router-context.js";
+import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
+import { observeHandler } from "../instrument.js";
+import {
+  track,
+  RangoContext,
+  runInsideLoaderScope,
+  latchCachedHeaderScope,
+  latchPprHeaderScopeForEntries,
+} from "../../server/context.js";
+
+// ---------------------------------------------------------------------------
+// Fresh path (full match, no revalidation)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve loaders for an entry and emit segments.
+ * Loaders are run lazily via ctx.use() and memoized for parallel execution.
+ */
+export async function resolveLoaders<TEnv>(
+  entry: EntryData,
+  ctx: HandlerContext<any, TEnv>,
+  belongsToRoute: boolean,
+  deps: SegmentResolutionDeps<TEnv>,
+  shortCodeOverride?: string,
+): Promise<ResolvedSegment[]> {
+  const loaderEntries = entry.loader ?? [];
+  if (loaderEntries.length === 0) return [];
+
+  const shortCode = shortCodeOverride ?? entry.shortCode;
+
+  // Pin `_currentSegmentId` to the OWNING entry BEFORE the loader kickoffs:
+  // createLoaderExecutor captures it synchronously at kickoff for
+  // ctx.use(Handle) push attribution (loader writes land in the same bucket
+  // as the entry's handler pushes — shortCode is in matched/segmentOrder, so
+  // collectHandleData keeps them; an id outside the order is silently
+  // dropped). resolveLoaders runs BEFORE the handler-resolution sites assign
+  // this (fresh.ts handler-first ordering), so without the pin the captured
+  // value is a stale sibling's id (document lane) or undefined (navigation
+  // lane — pushes silently vanished).
+  (ctx as InternalHandlerContext<any, TEnv>)._currentSegmentId = shortCode;
+  const hasLoading = "loading" in entry && entry.loading !== undefined;
+  const loadingDisabled = hasLoading && entry.loading === false;
+
+  // Emit the streaming (non-awaiting) loader shape when loading is enabled OR
+  // during a PPR shell capture. In capture, LIVE-lane loaders are masked with
+  // never-resolving promises (loader-mask.ts); the loading-disabled branch below
+  // AWAITS the loader promises, which would hang the capture render's match()
+  // forever on those masked promises. Forcing the streaming shape lets match()
+  // complete so the prerender can postpone the loader subtrees as holes. The
+  // `!loadingDisabled` short-circuit keeps the ALS check off the hot path (only
+  // loading-disabled entries consult it), so normal requests are unchanged.
+  const emitStreaming = !loadingDisabled || isShellCaptureActive();
+
+  // PPR lane decision for this entry's loaders (loader-container-bake): an
+  // entry WITHOUT renderable loading() puts its loaders on the BAKE lane —
+  // executed at capture (container bakes, nested pending promises hole at the
+  // consumer's Suspense) and overlay-pinned from the shell snapshot on a HIT.
+  // Renderable loading() keeps the LIVE lane (masked at capture, always
+  // fresh). Computed per entry; resolveLoaderData applies the policy.
+  const bakeLane = !entryLoadingMasksLoaders(entry.loading);
+
+  // Error context for wrapLoaderPromise: without it, a throwing DSL loader never
+  // fires createRouter({ onError }) (phase "loader") nor emits the loader.error
+  // telemetry event — wrapLoaderPromise only builds the onError/telemetry path
+  // when errorContext is supplied. Built from ctx so the live render path reports
+  // loader failures the same way handlers/actions/routing/fetchable-loaders do.
+  const errorContext = buildLoaderErrorContext(ctx);
+
+  if (emitStreaming) {
+    // awaitBeforeFlush (loader(Def, { ssr: false })): document
+    // renders await these loaders before returning, so their data is settled,
+    // their handle pushes beat the barrier snapshot, and a thrown notFound()'s
+    // status write deterministically precedes Response construction. The ids
+    // must register on the request context BEFORE kickoff — rendered() checks
+    // the set to fail fast on the barrier cycle (segment resolution awaits the
+    // loader, the barrier awaits segment resolution, rendered() awaits the
+    // barrier), and the loader body can call rendered() before the await below
+    // is reached.
+    //
+    // Shell-capture renders await too — deliberately. Flagged loaders BAKE at
+    // capture (they execute for real; loader-mask masks only LIVE-lane
+    // loaders, so nothing here can hang that would not already hold the
+    // capture gate, which awaits the same records). Skipping the await
+    // (pre-#822 behavior) let the capture's render-barrier snapshot resolve
+    // before the bake settled, so the loader's handle pushes missed the
+    // captured HTML: every HIT then served the pre-push <head> (default
+    // <title>/meta, crawler-visible) even though the stored handles row
+    // carried the value and hydration corrected it (scar tissue:
+    // vite-rsc-demo /client-shop/ppr title).
+    const awaitedIndices: number[] = [];
+    for (let i = 0; i < loaderEntries.length; i++) {
+      if (loaderEntries[i]!.awaitBeforeFlush) awaitedIndices.push(i);
+    }
+    if (awaitedIndices.length > 0) {
+      const reqCtx = _getRequestContext();
+      if (reqCtx) {
+        reqCtx._awaitBeforeFlushLoaderIds ??= new Set();
+        for (const i of awaitedIndices) {
+          reqCtx._awaitBeforeFlushLoaderIds.add(loaderEntries[i]!.loader.$$id);
+        }
+      }
+    }
+
+    // Streaming loaders: promises kick off now, settle during RSC serialization.
+    const segments = loaderEntries.map((loaderEntry, i) => {
+      const { loader } = loaderEntry;
+      const segmentId = `${shortCode}D${i}.${loader.$$id}`;
+      return {
+        id: segmentId,
+        namespace: entry.id,
+        type: "loader" as const,
+        index: i,
+        component: null,
+        params: ctx.params,
+        loaderId: loader.$$id,
+        // Stamped on document AND capture renders (both collect
+        // awaitedIndices): segment-system's value-delivery await and the dev
+        // SSR-suspension diagnostic both key off it.
+        ...(awaitedIndices.includes(i)
+          ? { awaitBeforeFlush: true as const }
+          : {}),
+        loaderData: deps.wrapLoaderPromise(
+          runInsideLoaderScope(() =>
+            resolveLoaderData(
+              loaderEntry,
+              ctx,
+              ctx.pathname,
+              // The bake key rides for flagged loaders too: ssr:false
+              // bakes at capture regardless of the entry's loading() lane
+              // (loader-cache.ts capture branch) and its HIT-tail seed
+              // overlay needs the same key.
+              bakeLane || loaderEntry.awaitBeforeFlush === true
+                ? segmentId
+                : null,
+            ),
+          ),
+          entry,
+          segmentId,
+          ctx.pathname,
+          errorContext,
+        ),
+        belongsToRoute,
+      };
+    });
+
+    // Await only the flagged loaders; unflagged siblings keep streaming (their
+    // promises were kicked off above and stay pending in the emitted segments).
+    // The wrapped promise is contracted to never reject (wrapLoaderPromise), so
+    // a flagged loader failure resolves with its error envelope and cannot
+    // collapse resolution — same contract the loading-disabled path relies on.
+    if (awaitedIndices.length > 0) {
+      await Promise.all(awaitedIndices.map((i) => segments[i]!.loaderData));
+    }
+
+    return segments;
+  }
+
+  // Loading disabled: still start all loaders in parallel, but only emit
+  // settled promises so handlers don't stream loading placeholders.
+  //
+  // Wrap each loader promise with wrapLoaderPromise BEFORE awaiting. The wrapped
+  // promise resolves to a LoaderDataResult and never rejects, routing a failed
+  // loader to its own per-loader error boundary. Awaiting the RAW promises here
+  // instead would (1) propagate a rejection to the segment-level boundary,
+  // collapsing the whole entry and discarding successful sibling data, and
+  // (2) leave the other in-flight raw promises without a .catch, producing
+  // unhandled rejections. Mirrors the loading path and intercept-resolution.
+  const pendingLoaderData = loaderEntries.map((loaderEntry, i) => {
+    const { loader } = loaderEntry;
+    const segmentId = `${shortCode}D${i}.${loader.$$id}`;
+    const wrapped = deps.wrapLoaderPromise(
+      runInsideLoaderScope(() =>
+        resolveLoaderData(
+          loaderEntry,
+          ctx,
+          ctx.pathname,
+          bakeLane || loaderEntry.awaitBeforeFlush === true ? segmentId : null,
+        ),
+      ),
+      entry,
+      segmentId,
+      ctx.pathname,
+      errorContext,
+    );
+    return { wrapped, segmentId };
+  });
+  await Promise.all(pendingLoaderData.map((p) => p.wrapped));
+
+  return loaderEntries.map((loaderEntry, i) => {
+    const { loader } = loaderEntry;
+    const pending = pendingLoaderData[i]!;
+    // The "loader:<id>" perf metric is recorded by observePhase at the single
+    // loader-metering site (useLoader, reached via ctx.use during
+    // resolveLoaderData), with the real per-loader duration rather than a
+    // Promise.all batch ceiling.
+    return {
+      id: pending.segmentId,
+      namespace: entry.id,
+      type: "loader" as const,
+      index: i,
+      component: null,
+      params: ctx.params,
+      loaderId: loader.$$id,
+      loaderData: pending.wrapped,
+      belongsToRoute,
+    };
+  });
+}
+
+/**
+ * Options for segment resolution.
+ */
+export interface ResolveSegmentOptions {
+  /** When true, skip resolveLoaders() calls (used for pre-rendering) */
+  skipLoaders?: boolean;
+  /**
+   * When true, a thrown render error is re-thrown instead of being converted
+   * into an error-boundary segment. Set only by the pre-render path so a
+   * build-time render failure (and a `throw new Skip()` inside a render fn)
+   * surfaces to the build instead of being silently baked into a frozen error
+   * page served as a 200 (issue #587). The live request path leaves this unset,
+   * so error boundaries keep catching at request time.
+   */
+  throwOnError?: boolean;
+}
+
+/**
+ * Resolve segments from EntryData.
+ * Executes middlewares, loaders, parallels, and handlers in correct order.
+ * Returns array: [main segment, ...orphan layout segments]
+ */
+export async function resolveSegment<TEnv>(
+  entry: EntryData,
+  routeKey: string,
+  params: Record<string, string>,
+  context: HandlerContext<any, TEnv>,
+  loaderPromises: Map<string, Promise<any>>,
+  deps: SegmentResolutionDeps<TEnv>,
+  isRouteEntry: boolean = false,
+  options?: ResolveSegmentOptions,
+): Promise<ResolvedSegment[]> {
+  const segments: ResolvedSegment[] = [];
+
+  if (entry.type === "layout" || entry.type === "cache") {
+    if (!options?.skipLoaders) {
+      const loaderSegments = await resolveLoaders(entry, context, false, deps);
+      segments.push(...loaderSegments);
+    }
+
+    // Handler-first: layout handler executes before its parallels and orphan
+    // layouts so that ctx.set() values are visible to all children.
+    (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+      entry.shortCode;
+
+    const doneLayoutHandler = track(`handler:${entry.id}`, 2);
+    const component = await resolveLayoutComponent(entry, context);
+    doneLayoutHandler();
+
+    segments.push({
+      id: entry.shortCode,
+      namespace: entry.id,
+      type: "layout",
+      index: 0,
+      component,
+      loading: entry.loading === false ? null : entry.loading,
+      transition: applyViewTransitionDefault(
+        entry.transition,
+        deps.viewTransitionDefault,
+        entry.shortCode,
+      ),
+      params,
+      belongsToRoute: false,
+      layoutName: entry.id,
+      ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
+    });
+
+    const resolvedParallelEntries = new Set<string>();
+    for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+      entry.parallel,
+    )) {
+      const parallelSegments = await resolveParallelEntry(
+        parallelEntry,
+        params,
+        context,
+        false,
+        entry.shortCode,
+        deps,
+        options,
+        routeKey,
+        [slot],
+        !resolvedParallelEntries.has(parallelEntry.id),
+      );
+      segments.push(...parallelSegments);
+      resolvedParallelEntries.add(parallelEntry.id);
+    }
+
+    for (const orphan of entry.layout) {
+      const orphanSegments = await resolveOrphanLayout(
+        orphan,
+        params,
+        context,
+        loaderPromises,
+        false,
+        deps,
+        options,
+        routeKey,
+      );
+      segments.push(...orphanSegments);
+    }
+  } else if (entry.type === "route") {
+    if (!options?.skipLoaders) {
+      const loaderSegments = await resolveLoaders(entry, context, true, deps);
+      segments.push(...loaderSegments);
+    }
+
+    // Route handler EXECUTES before its children (orphan layouts, parallels).
+    // This lets the handler set() context variables that children can read
+    // via get(). Caching wraps all segments together (per-route, not
+    // per-segment), so either all run or none do -- no partial scenarios.
+    //
+    // The handler's segment is PUSHED after orphans/parallels to preserve
+    // the correct tree composition order (layouts wrap the route content).
+    (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+      entry.shortCode;
+    let component: ReactNode | undefined = await tryStaticHandler(
+      entry,
+      entry.shortCode,
+    );
+    if (component === undefined) {
+      // 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 entry.handler.
+      const handler =
+        !context.build && entry.liveHandler ? entry.liveHandler : entry.handler;
+      const doneRouteHandler = track(`handler:${entry.id}`, 2);
+      if (entry.loading) {
+        const result = handleHandlerResult(
+          observeHandler(entry.id, handler, context),
+        );
+        if (result instanceof Promise) {
+          warnOnStreamedResponse(result, entry.id);
+          result.finally(doneRouteHandler).catch(() => {});
+          const tracked = deps.trackHandler(result, {
+            segmentId: entry.shortCode,
+            segmentType: entry.type,
+          });
+          observeStreamedHandler(
+            tracked,
+            entry.shortCode,
+            entry.type,
+            context.pathname,
+            routeKey,
+            params,
+          );
+          component = tracked;
+        } else {
+          doneRouteHandler();
+          component = result;
+        }
+      } else {
+        component = handleHandlerResult(
+          await observeHandler(entry.id, handler, context),
+        );
+        doneRouteHandler();
+      }
+    }
+
+    for (const orphan of entry.layout) {
+      const orphanSegments = await resolveOrphanLayout(
+        orphan,
+        params,
+        context,
+        loaderPromises,
+        true,
+        deps,
+        options,
+        routeKey,
+        entry,
+      );
+      segments.push(...orphanSegments);
+    }
+
+    const resolvedParallelEntries = new Set<string>();
+    for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+      entry.parallel,
+    )) {
+      const parallelSegments = await resolveParallelEntry(
+        parallelEntry,
+        params,
+        context,
+        true,
+        entry.shortCode,
+        deps,
+        options,
+        routeKey,
+        [slot],
+        !resolvedParallelEntries.has(parallelEntry.id),
+      );
+      segments.push(...parallelSegments);
+      resolvedParallelEntries.add(parallelEntry.id);
+    }
+
+    segments.push({
+      id: entry.shortCode,
+      namespace: entry.id,
+      type: "route",
+      index: 0,
+      component: component ?? null,
+      loading: entry.loading === false ? null : entry.loading,
+      transition: applyViewTransitionDefault(
+        entry.transition,
+        deps.viewTransitionDefault,
+        entry.shortCode,
+      ),
+      params,
+      belongsToRoute: true,
+      ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
+    });
+  } else {
+    throw new Error(`Unknown entry type: ${(entry as any).type}`);
+  }
+
+  return segments;
+}
+
+/**
+ * Resolve orphan layout with its middlewares, loaders, and parallels.
+ */
+export async function resolveOrphanLayout<TEnv>(
+  orphan: EntryData,
+  params: Record<string, string>,
+  context: HandlerContext<any, TEnv>,
+  loaderPromises: Map<string, Promise<any>>,
+  belongsToRoute: boolean,
+  deps: SegmentResolutionDeps<TEnv>,
+  options?: ResolveSegmentOptions,
+  routeKey?: string,
+  /** Parent route entry — its loaders are inherited by the layout so
+   *  parallel slots inside this layout can access them via useLoader(). */
+  parentRouteEntry?: EntryData,
+): Promise<ResolvedSegment[]> {
+  invariant(
+    orphan.type === "layout" || orphan.type === "cache",
+    `Expected orphan to be a layout or cache, got: ${orphan.type}`,
+  );
+
+  const segments: ResolvedSegment[] = [];
+  if (!options?.skipLoaders) {
+    const loaderSegments = await resolveLoaders(
+      orphan,
+      context,
+      belongsToRoute,
+      deps,
+    );
+    segments.push(...loaderSegments);
+
+    // Inherit parent route's loaders so parallel slots inside this layout
+    // can access them via useLoader(). Without this, the route's loaders
+    // are only in the route's OutletProvider (rendered as <Outlet /> content),
+    // which is a child — not a parent — of the layout's context.
+    if (
+      parentRouteEntry &&
+      parentRouteEntry.loader &&
+      parentRouteEntry.loader.length > 0 &&
+      Object.keys(orphan.parallel).length > 0
+    ) {
+      const inheritedLoaders = await resolveLoaders(
+        parentRouteEntry,
+        context,
+        belongsToRoute,
+        deps,
+        orphan.shortCode,
+      );
+      // Tag as inherited so buildMatchResult can deduplicate when safe
+      for (const s of inheritedLoaders) {
+        s._inherited = true;
+      }
+      segments.push(...inheritedLoaders);
+    }
+  }
+
+  // Handler-first: orphan layout handler executes before its parallels
+  // so that ctx.set() values are visible to parallel children.
+  const doneOrphanHandler = track(`handler:${orphan.id}`, 2);
+  const component = await resolveLayoutComponent(orphan, context);
+  doneOrphanHandler();
+
+  segments.push({
+    id: orphan.shortCode,
+    namespace: orphan.id,
+    type: "layout",
+    index: 0,
+    component,
+    params,
+    belongsToRoute,
+    layoutName: orphan.id,
+    loading: orphan.loading === false ? null : orphan.loading,
+    transition: applyViewTransitionDefault(
+      orphan.transition,
+      deps.viewTransitionDefault,
+      orphan.shortCode,
+    ),
+    ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
+  });
+
+  const resolvedParallelEntries = new Set<string>();
+  for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+    orphan.parallel,
+  )) {
+    const parallelSegments = await resolveParallelEntry(
+      parallelEntry,
+      params,
+      context,
+      belongsToRoute,
+      orphan.shortCode,
+      deps,
+      options,
+      routeKey,
+      [slot],
+      !resolvedParallelEntries.has(parallelEntry.id),
+    );
+    segments.push(...parallelSegments);
+    resolvedParallelEntries.add(parallelEntry.id);
+  }
+
+  return segments;
+}
+
+/**
+ * Resolve parallel EntryData with its loaders and slot handlers.
+ */
+export async function resolveParallelEntry<TEnv>(
+  parallelEntry: EntryData,
+  params: Record<string, string>,
+  context: HandlerContext<any, TEnv>,
+  belongsToRoute: boolean,
+  parentShortCode: string,
+  deps: SegmentResolutionDeps<TEnv>,
+  options?: ResolveSegmentOptions,
+  routeKey?: string,
+  slotNames?: `@${string}`[],
+  includeLoaders: boolean = true,
+): Promise<ResolvedSegment[]> {
+  invariant(
+    parallelEntry.type === "parallel",
+    `Expected parallel entry, got: ${parallelEntry.type}`,
+  );
+
+  const segments: ResolvedSegment[] = [];
+
+  const slots = parallelEntry.handler as Record<
+    `@${string}`,
+    | ((ctx: HandlerContext<any, TEnv>) => ReactNode | Promise<ReactNode>)
+    | ReactNode
+  >;
+
+  const slotsToResolve = slotNames ?? (Object.keys(slots) as `@${string}`[]);
+
+  for (const slot of slotsToResolve) {
+    // Try static lookup first — in production, handler bodies are evicted
+    // and replaced with stubs that have no .handler property (undefined).
+    // The static store holds the pre-rendered component for these slots.
+    let component: ReactNode | undefined = await tryStaticSlot(
+      parallelEntry,
+      slot,
+      `${parentShortCode}.${slot}`,
+    );
+
+    if (component === undefined) {
+      const handler = slots[slot];
+      if (handler === undefined) {
+        continue;
+      }
+      // Pin `_currentSegmentId` to the slot's own id so handle pushes from
+      // inside the slot handler get their own bucket in the HandleStore.
+      // Parent-keying would collapse them into the parent layout's bucket;
+      // the partial-update merge then replaces the parent's bucket on a
+      // slot-only revalidation and drops layout-pushed Meta/Breadcrumbs.
+      // filterSegmentOrder() retains slot ids so the client preserves them.
+      (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+        `${parentShortCode}.${slot}`;
+      const doneParallelHandler = track(
+        `handler:${parallelEntry.id}.${slot}`,
+        2,
+      );
+      const hasLoadingFallback =
+        parallelEntry.loading !== undefined && parallelEntry.loading !== false;
+      if (hasLoadingFallback) {
+        const result =
+          typeof handler === "function"
+            ? observeHandler(`${parallelEntry.id}.${slot}`, handler, context)
+            : handler;
+        if (result instanceof Promise) {
+          result.finally(doneParallelHandler).catch(() => {});
+          const tracked = deps.trackHandler(result, {
+            segmentId: `${parentShortCode}.${slot}`,
+            segmentType: "parallel",
+          });
+          observeStreamedHandler(
+            tracked,
+            `${parentShortCode}.${slot}`,
+            "parallel",
+            context.pathname,
+            routeKey,
+            params,
+          );
+          component = tracked as ReactNode;
+        } else {
+          doneParallelHandler();
+          component = result as ReactNode;
+        }
+      } else {
+        component =
+          typeof handler === "function"
+            ? await observeHandler(
+                `${parallelEntry.id}.${slot}`,
+                handler,
+                context,
+              )
+            : handler;
+        doneParallelHandler();
+      }
+    }
+
+    segments.push({
+      id: `${parentShortCode}.${slot}`,
+      namespace: parallelEntry.id,
+      type: "parallel",
+      index: 0,
+      component,
+      loading: parallelEntry.loading === false ? null : parallelEntry.loading,
+      transition: applyViewTransitionDefault(
+        parallelEntry.transition,
+        deps.viewTransitionDefault,
+        `${parentShortCode}.${slot}`,
+      ),
+      params,
+      slot,
+      belongsToRoute,
+      parallelName: `${parallelEntry.id}.${slot}`,
+      ...(parallelEntry.mountPath
+        ? { mountPath: parallelEntry.mountPath }
+        : {}),
+    });
+  }
+
+  if (!options?.skipLoaders && includeLoaders) {
+    const loaderSegments = await resolveLoaders(
+      parallelEntry,
+      context,
+      belongsToRoute,
+      deps,
+      parentShortCode,
+    );
+    // Tag parallel-owned loaders so renderSegments can stream them
+    // using the parallel's loading() instead of awaiting on the layout
+    const parallelLoading =
+      parallelEntry.loading === false ? undefined : parallelEntry.loading;
+    if (parallelLoading) {
+      for (const seg of loaderSegments) {
+        seg.parallelLoading = parallelLoading;
+      }
+    }
+    segments.push(...loaderSegments);
+  }
+
+  return segments;
+}
+
+/**
+ * Resolve all segments for a route (used for single-cache-per-request pattern).
+ */
+export async function resolveAllSegments<TEnv>(
+  entries: EntryData[],
+  routeKey: string,
+  params: Record<string, string>,
+  context: HandlerContext<any, TEnv>,
+  loaderPromises: Map<string, Promise<any>>,
+  deps: SegmentResolutionDeps<TEnv>,
+  options?: ResolveSegmentOptions,
+): Promise<ResolvedSegment[]> {
+  const allSegments: ResolvedSegment[] = [];
+  const seenIds = new Set<string>();
+
+  // ppr routes are document-scoped cached territory: the whole chain (root
+  // layout down to the page) bakes into the shared shell, so the header-write
+  // guard latches BEFORE any entry resolves (unlike the positional cache()
+  // latch below). See assertCachedHeaderWriteAllowed (server/context.ts).
+  latchPprHeaderScopeForEntries(entries, routeKey);
+
+  // Safe request access: during build-time prerendering, context.request
+  // is a throwing getter. Use undefined when unavailable.
+  let safeRequest: Request | undefined;
+  try {
+    safeRequest = context.request;
+  } catch {}
+
+  // Get telemetry sink from RouterContext (may not exist during prerendering)
+  let telemetry;
+  try {
+    telemetry = getRouterContext()?.telemetry;
+  } catch {}
+
+  for (const entry of entries) {
+    // Set ALS flag when entering a cache() boundary so that ctx.get()
+    // can guard non-cacheable variable reads. Also latch the header-write
+    // scope (response-level side effects — headers/cookies/status).
+    // Persists for all descendant entries.
+    if (entry.type === "cache") {
+      const store = RangoContext.getStore();
+      if (store) store.insideCacheScope = true;
+      latchCachedHeaderScope("cache", routeKey);
+    }
+    const doneEntry = track(`segment:${entry.id}`, 1);
+    const resolvedSegments = await resolveWithErrorBoundary(
+      entry,
+      params,
+      () =>
+        resolveSegment(
+          entry,
+          routeKey,
+          params,
+          context,
+          loaderPromises,
+          deps,
+          false,
+          options,
+        ),
+      (seg) => [seg],
+      deps,
+      { request: safeRequest, url: context.url, routeKey, telemetry },
+      context.pathname,
+      options?.throwOnError,
+    );
+    doneEntry();
+    // Deduplicate by segment ID. include() scopes can produce entries that
+    // resolve the same shared layout/loader segment. Duplicates in the segment
+    // array propagate to the client's matched[] and change the React tree depth.
+    for (const seg of resolvedSegments) {
+      if (!seenIds.has(seg.id)) {
+        seenIds.add(seg.id);
+        allSegments.push(seg);
+      }
+    }
+  }
+
+  return allSegments;
+}
+
+/**
+ * Resolve only loader segments for all entries (used when serving cached non-loader segments).
+ */
+export async function resolveLoadersOnly<TEnv>(
+  entries: EntryData[],
+  context: HandlerContext<any, TEnv>,
+  deps: SegmentResolutionDeps<TEnv>,
+): Promise<ResolvedSegment[]> {
+  const loaderSegments: ResolvedSegment[] = [];
+  const seenIds = new Set<string>();
+
+  // Loader-only serves (cached non-loader segments) still run loaders live —
+  // on a ppr route their header writes are dead letters (headers flushed with
+  // the shell), so the guard latches here too. cache() needs no latch: loader
+  // writes are exempt under cache() (see assertCachedHeaderWriteAllowed).
+  latchPprHeaderScopeForEntries(
+    entries,
+    (context as InternalHandlerContext<any, TEnv>)._routeName,
+  );
+
+  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 entryLoaders = entry.loader ?? [];
+    const sc = shortCodeOverride ?? entry.shortCode;
+    const allAlreadySeen =
+      entryLoaders.length > 0 &&
+      entryLoaders.every((le, i) =>
+        seenIds.has(`${sc}D${i}.${le.loader.$$id}`),
+      );
+    if (!allAlreadySeen) {
+      const segments = await resolveLoaders(
+        entry,
+        context,
+        belongsToRoute,
+        deps,
+        shortCodeOverride,
+      );
+      for (const seg of segments) {
+        if (!seenIds.has(seg.id)) {
+          seenIds.add(seg.id);
+          loaderSegments.push(seg);
+        }
+      }
+    }
+
+    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);
+      // 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 resolveLoaders(
+          entry,
+          context,
+          childBelongsToRoute,
+          deps,
+          layoutEntry.shortCode,
+        );
+        for (const seg of inherited) {
+          if (!seenIds.has(seg.id)) {
+            seenIds.add(seg.id);
+            seg._inherited = true;
+            loaderSegments.push(seg);
+          }
+        }
+      }
+    }
+  }
+
+  for (const entry of entries) {
+    await collectEntryLoaders(entry, entry.type === "route");
+  }
+
+  return loaderSegments;
+}