@rangojs/router 0.27.0 → 0.29.0

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

@@ -1,945 +0,0 @@
-/**
- * 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,
-  type LoaderEntry,
-} 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 { trackStreamedHandler } from "./streamed-handler-boundary.js";
-import { observeSegmentHandler } from "../instrument.js";
-import { withReverseScope } from "../handler-context.js";
-import {
-  track,
-  RangoContext,
-  runInsideLoaderScope,
-  latchCachedHeaderScope,
-  latchPprHeaderScopeForEntries,
-} from "../../server/context.js";
-
-/**
- * Register flagged loader $$ids on the request context and return their
- * indices. Must run BEFORE kickoff: rendered() checks the set to fail
- * fast on the barrier cycle (resolution awaits the loader, the barrier
- * awaits resolution).
- */
-function registerAwaitBeforeFlushIds(loaderEntries: LoaderEntry[]): number[] {
-  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);
-      }
-    }
-  }
-  return awaitedIndices;
-}
-
-function stampAwaitBeforeFlush(
-  loaderEntry: LoaderEntry,
-): { awaitBeforeFlush: true } | Record<string, never> {
-  return loaderEntry.awaitBeforeFlush === true
-    ? { awaitBeforeFlush: true as const }
-    : {};
-}
-
-// ---------------------------------------------------------------------------
-// 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 bake/seed key input only; lane rule: see resolveLoaderData
-  // (loader-cache.ts). Unflagged loaders mask at capture regardless of the key.
-  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: flagged loaders execute at capture
-    // (lane rule: see resolveLoaderData, loader-cache.ts), so their handle
-    // pushes must land in the prelude.
-    const awaitedIndices = registerAwaitBeforeFlushIds(loaderEntries);
-
-    // 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: segment-system's
-        // value-delivery await and the dev SSR-suspension diagnostic both
-        // key off it.
-        ...stampAwaitBeforeFlush(loaderEntry),
-        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.bake === true ? segmentId : null,
-              ),
-            loader.$$id,
-            loaderEntry.reverseScope,
-          ),
-          entry,
-          segmentId,
-          ctx.pathname,
-          errorContext,
-          loaderEntry.awaitBeforeFlush,
-        ),
-        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.
-  //
-  // Flagged loaders still get awaitBeforeFlush stamped: auto-raise and
-  // settled-value delivery key off the field, and this path already paid
-  // the pre-flush await.
-  registerAwaitBeforeFlushIds(loaderEntries);
-  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.bake === true ? segmentId : null,
-          ),
-        loader.$$id,
-        loaderEntry.reverseScope,
-      ),
-      entry,
-      segmentId,
-      ctx.pathname,
-      errorContext,
-      loaderEntry.awaitBeforeFlush,
-    );
-    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,
-      ...stampAwaitBeforeFlush(loaderEntry),
-      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;
-  /**
-   * The matched route's full entry chain. resolveAllSegments defaults it to
-   * its `entries`; withCacheLookup passes it when it resolves only the entries
-   * above a cache() boundary. An orphan list can hold an entry of the chain: a
-   * bare cache() marker sits in its layout's layout[] (it wraps that layout's
-   * routes) and is the parent of the routes after it. For those routes it
-   * resolves once, as a chain entry, below the cache() header latch (issue
-   * #918: resolved twice on a MISS, once and discarded on a HIT).
-   */
-  chain?: readonly EntryData[];
-  /**
-   * The matched chain entry being resolved: where the sync path catches a
-   * handler error, so a streamed handler (or slot owned by a routeless layout)
-   * recovers into the same boundary. resolveSegment sets it for the entry it
-   * resolves; nested resolutions keep the outer value.
-   */
-  boundaryEntry?: EntryData;
-}
-
-/**
- * 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[] = [];
-  const boundaryEntry = options?.boundaryEntry ?? entry;
-  if (!options?.boundaryEntry) options = { ...options, boundaryEntry };
-
-  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,
-      ),
-      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) {
-      if (options?.chain?.includes(orphan)) continue;
-      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(
-          observeSegmentHandler(entry.shortCode, entry.id, handler, context),
-        );
-        if (result instanceof Promise) {
-          warnOnStreamedResponse(result, entry.id);
-          result.finally(doneRouteHandler).catch(() => {});
-          component = trackStreamedHandler(deps, result, {
-            boundaryEntry,
-            segmentId: entry.shortCode,
-            segmentType: entry.type,
-            context,
-            routeKey,
-            params,
-            recover: !options?.throwOnError,
-          });
-        } else {
-          doneRouteHandler();
-          component = result;
-        }
-      } else {
-        component = handleHandlerResult(
-          await observeSegmentHandler(
-            entry.shortCode,
-            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,
-      ),
-      params,
-      belongsToRoute: true,
-      ...(entry.clientGroup ? { clientGroup: entry.clientGroup } : {}),
-      ...(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.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);
-  }
-
-  // Routeless entries nested in this one (a layout() after a bare cache()
-  // marker, a wrapper inside a routeless wrapper) wrap the same content one
-  // level deeper. Issue #918: they were never rendered. None is in the
-  // matched chain: that would put this orphan in it, and resolveSegment
-  // skips those.
-  for (const nested of orphan.layout) {
-    segments.push(
-      ...(await resolveOrphanLayout(
-        nested,
-        params,
-        context,
-        loaderPromises,
-        belongsToRoute,
-        deps,
-        options,
-        routeKey,
-      )),
-    );
-  }
-
-  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}`[]);
-  const slotContext = withReverseScope(context, parallelEntry.reverseScope);
-
-  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"
-            ? observeSegmentHandler(
-                `${parentShortCode}.${slot}`,
-                `${parallelEntry.id}.${slot}`,
-                handler,
-                slotContext,
-              )
-            : handler;
-        if (result instanceof Promise) {
-          result.finally(doneParallelHandler).catch(() => {});
-          component = trackStreamedHandler(deps, result, {
-            boundaryEntry: options?.boundaryEntry ?? parallelEntry,
-            segmentId: `${parentShortCode}.${slot}`,
-            segmentType: "parallel",
-            context,
-            routeKey,
-            params,
-            recover: !options?.throwOnError,
-          });
-        } else {
-          doneParallelHandler();
-          component = result as ReactNode;
-        }
-      } else {
-        component =
-          typeof handler === "function"
-            ? await observeSegmentHandler(
-                `${parentShortCode}.${slot}`,
-                `${parallelEntry.id}.${slot}`,
-                handler,
-                slotContext,
-              )
-            : 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,
-      ),
-      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>();
-  const segmentOptions: ResolveSegmentOptions = {
-    ...options,
-    chain: options?.chain ?? entries,
-  };
-
-  // 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. A route entry carries `cache` when
-    // cache() is among its own children (dsl-helpers.ts cache()).
-    if (entry.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,
-          segmentOptions,
-        ),
-      (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;
-}