@rangojs/router 0.0.0-experimental.65 → 0.0.0-experimental.655f3c16

package/src/router/loader-resolution.ts

@@ -21,7 +21,7 @@ import type {
 } from "../types";
 import type { LoaderRevalidationResult, ActionContext } from "./types";
 import { isHandle, collectHandleData, type Handle } from "../handle.js";
-import type { HandleStore, HandleData } from "../server/handle-store.js";
+import { buildHandleSnapshot } from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
 import { isInsideLoaderScope } from "../server/context.js";
@@ -284,10 +284,9 @@ function createLoaderExecutor<TEnv>(
             );
           }
           const segmentOrder = reqCtx._renderBarrierSegmentOrder ?? [];
-          const snapshot = buildHandleSnapshot(
-            reqCtx._handleStore,
-            segmentOrder,
-          );
+          const snapshot =
+            reqCtx._renderBarrierHandleSnapshot ??
+            buildHandleSnapshot(reqCtx._handleStore, segmentOrder);
           return collectHandleData(item, snapshot, segmentOrder);
         }
 
@@ -324,6 +323,17 @@ function createLoaderExecutor<TEnv>(
           );
         }
 
+        // Bidirectional deadlock check: if a handler already started
+        // awaiting this loader, calling rendered() would deadlock.
+        if (reqCtx._handlerLoaderDeps?.has(currentLoaderId)) {
+          throw new Error(
+            `Deadlock: loader "${currentLoaderId}" called ctx.rendered() but a handler ` +
+              `is already awaiting this loader via ctx.use(). The handler blocks ` +
+              `segment resolution, which blocks the barrier, which blocks this loader. ` +
+              `Move the data dependency to a loader-to-loader pattern instead.`,
+          );
+        }
+
         // Register this loader as waiting for the barrier so that
         // setupLoaderAccess can detect deadlocks when a handler
         // tries to await the same loader via ctx.use().
@@ -354,25 +364,6 @@ function createLoaderExecutor<TEnv>(
   return useLoader;
 }
 
-/**
- * Build a HandleData snapshot from the HandleStore using segment ordering.
- * Reads data directly from the store for each segment in order.
- */
-function buildHandleSnapshot(
-  handleStore: HandleStore,
-  segmentOrder: string[],
-): HandleData {
-  const data: HandleData = {};
-  for (const segmentId of segmentOrder) {
-    const segData = handleStore.getDataForSegment(segmentId);
-    for (const handleName in segData) {
-      if (!data[handleName]) data[handleName] = {};
-      data[handleName][segmentId] = segData[handleName];
-    }
-  }
-  return data;
-}
-
 /**
  * Set up the use() method on handler context to access loaders and handles.
  *
@@ -386,15 +377,22 @@ export function setupLoaderAccess<TEnv>(
   ctx: HandlerContext<any, TEnv>,
   loaderPromises: Map<string, Promise<any>>,
 ): void {
-  // Eagerly capture the HandleStore at setup time (before pipeline async ops).
-  // In workerd/Cloudflare, dynamic imports and fetch() in the match pipeline
-  // can disrupt AsyncLocalStorage, causing getRequestContext() to return
-  // undefined when handlers later call ctx.use(handle). Capturing early
-  // ensures the store reference survives ALS disruption.
-  const handleStoreRef = _getRequestContext()?._handleStore;
+  // Eagerly capture the request context and HandleStore at setup time
+  // (before pipeline async ops). In workerd/Cloudflare, dynamic imports and
+  // fetch() in the match pipeline can disrupt AsyncLocalStorage, causing
+  // getRequestContext() to return undefined when handlers later call
+  // ctx.use(handle). Capturing early ensures references survive ALS disruption.
+  const reqCtxRef = _getRequestContext();
+  const handleStoreRef = reqCtxRef?._handleStore;
 
   const useLoader = createLoaderExecutor(ctx, loaderPromises);
 
+  // Track whether we're inside a handle push callback. Loaders started
+  // from push callbacks (e.g. push(async () => ctx.use(Loader))) do NOT
+  // block segment resolution, so they must not be registered as handler
+  // dependencies for deadlock detection.
+  let insideHandlePush = false;
+
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     if (isHandle(item)) {
       const handle = item;
@@ -414,28 +412,53 @@ export function setupLoaderAccess<TEnv>(
       ) => {
         if (!store) return;
 
-        const valueOrPromise =
-          typeof dataOrFn === "function"
-            ? (dataOrFn as () => Promise<unknown>)()
-            : dataOrFn;
+        if (typeof dataOrFn === "function") {
+          // Mark scope so ctx.use(loader) calls inside the callback
+          // are not registered as handler-to-loader deps.
+          insideHandlePush = true;
+          try {
+            const result = (dataOrFn as () => Promise<unknown>)();
+            store.push(handle.$$id, segmentId, result);
+          } finally {
+            insideHandlePush = false;
+          }
+          return;
+        }
 
-        store.push(handle.$$id, segmentId, valueOrPromise);
+        store.push(handle.$$id, segmentId, dataOrFn);
       };
     }
 
-    // Deadlock guard: if a HANDLER awaits a loader that called rendered(),
-    // the handler blocks segment resolution which blocks the barrier.
-    // Skip this check when inside a DSL loader scope (resolveLoaderData
-    // also calls ctx.use() but that's DSL-to-DSL, not handler-to-loader).
+    // Deadlock guard and handler-to-loader dependency tracking.
+    // Skip when inside a DSL loader scope (resolveLoaderData also calls
+    // ctx.use() but that's DSL-to-DSL, not handler-to-loader) or when
+    // inside a handle push callback (push callbacks don't block segment
+    // resolution so they can't cause rendered() deadlocks).
     const loader = item as LoaderDefinition<any, any>;
-    if (loaderPromises.has(loader.$$id) && !isInsideLoaderScope()) {
-      const reqCtx = _getRequestContext();
-      if (reqCtx?._renderBarrierWaiters?.has(loader.$$id)) {
-        throw new Error(
-          `Deadlock: handler is awaiting loader "${loader.$$id}" which called ctx.rendered(). ` +
-            `The loader is waiting for segment resolution, but the handler blocks resolution. ` +
-            `Move the data dependency to a loader-to-loader pattern instead.`,
-        );
+    if (!isInsideLoaderScope() && !insideHandlePush) {
+      const reqCtx = reqCtxRef ?? _getRequestContext();
+      if (reqCtx) {
+        // Direction 1: handler awaits loader that already called rendered()
+        if (
+          loaderPromises.has(loader.$$id) &&
+          reqCtx._renderBarrierWaiters?.has(loader.$$id)
+        ) {
+          throw new Error(
+            `Deadlock: handler is awaiting loader "${loader.$$id}" which called ctx.rendered(). ` +
+              `The loader is waiting for segment resolution, but the handler blocks resolution. ` +
+              `Move the data dependency to a loader-to-loader pattern instead.`,
+          );
+        }
+        // Direction 2: track dep so rendered() can detect the deadlock
+        // if the loader calls it later. Skip when the barrier has already
+        // resolved — no deadlock is possible (rendered() resolves immediately).
+        // _renderBarrierSegmentOrder is undefined before resolution, string[]
+        // after. This also prevents false positives from handle push callbacks
+        // that resume after their first await (post-barrier-resolution).
+        if (reqCtx._renderBarrierSegmentOrder === undefined) {
+          if (!reqCtx._handlerLoaderDeps) reqCtx._handlerLoaderDeps = new Set();
+          reqCtx._handlerLoaderDeps.add(loader.$$id);
+        }
       }
     }
 

package/src/router/match-middleware/cache-lookup.ts

@@ -194,11 +194,13 @@ async function* yieldFromStore<TEnv>(
   state.cachedSegments = segments;
   state.cachedMatchedIds = segments.map((s) => s.id);
 
-  // Set streaming flag and resolve render barrier.
+  // Set streaming flag (once) and resolve render barrier.
   const reqCtx = handleStoreRef ? undefined : _lazyGetRequestContext?.();
   const barrierReqCtx = reqCtx ?? _getRequestContext();
   if (barrierReqCtx) {
-    barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    if (barrierReqCtx._treeHasStreaming === undefined) {
+      barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    }
     barrierReqCtx._resolveRenderBarrier(segments);
   }
 
@@ -249,6 +251,7 @@ async function* yieldFromStore<TEnv>(
           ctx.url,
           ctx.routeKey,
           ctx.actionContext,
+          ctx.stale || undefined,
         ),
       );
       state.matchedIds = [
@@ -596,7 +599,7 @@ export function withCacheLookup<TEnv>(
         routeKey: ctx.routeKey,
         context: ctx.handlerContext,
         actionContext: ctx.actionContext,
-        stale: cacheResult.shouldRevalidate || undefined,
+        stale: cacheResult.shouldRevalidate || ctx.stale || undefined,
         traceSource: "cache-hit",
       });
 
@@ -623,10 +626,12 @@ export function withCacheLookup<TEnv>(
       yield segment;
     }
 
-    // Set streaming flag and resolve render barrier.
+    // Set streaming flag (once) and resolve render barrier.
     const barrierReqCtx = _getRequestContext();
     if (barrierReqCtx) {
-      barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+      if (barrierReqCtx._treeHasStreaming === undefined) {
+        barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+      }
       barrierReqCtx._resolveRenderBarrier(cacheResult.segments);
     }
 

package/src/router/match-middleware/segment-resolution.ts

@@ -168,7 +168,7 @@ export function withSegmentResolution<TEnv>(
     }
 
     const reqCtx = _getRequestContext();
-    if (reqCtx) {
+    if (reqCtx && reqCtx._treeHasStreaming === undefined) {
       reqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
     }
 

package/src/router/match-result.ts

@@ -125,6 +125,69 @@ export async function collectSegments(
   return segments;
 }
 
+/**
+ * Deduplicate inherited loader segments by loaderId.
+ *
+ * When a route has loaders and a child layout has parallel slots, the same
+ * loader is resolved twice: once for the route and once inherited into the
+ * layout (tagged with `_inherited`). The inherited copy is only needed when
+ * the route uses `loading()` — in that case, the loader data is inside a
+ * LoaderBoundary/Suspense that parallel slots can't reach through. Without
+ * loading(), useLoader() traverses parent contexts and finds the data.
+ */
+function deduplicateLoaderSegments(
+  segments: ResolvedSegment[],
+  logPrefix: string,
+): ResolvedSegment[] {
+  // First pass: collect loaderIds of original (non-inherited) segments
+  // and whether their parent entry uses loading()
+  const originalLoaders = new Set<string>();
+  const loadersWithLoading = new Set<string>();
+  for (const s of segments) {
+    if (s.type === "loader" && s.loaderId && !s._inherited) {
+      originalLoaders.add(s.loaderId);
+      // If the segment has a sibling with loading, the parent uses loading()
+      // We detect this by checking if any non-loader segment in the same
+      // namespace has loading defined
+    }
+  }
+  // Check if any layout/route segment has loading — if a loader's namespace
+  // matches a segment with loading, the inherited copy is needed
+  for (const s of segments) {
+    if (s.type !== "loader" && s.loading !== undefined && s.loading !== false) {
+      // Find loaders in this namespace
+      for (const l of segments) {
+        if (l.type === "loader" && l.namespace === s.namespace && l.loaderId) {
+          loadersWithLoading.add(l.loaderId);
+        }
+      }
+    }
+  }
+
+  const result: ResolvedSegment[] = [];
+  let dedupCount = 0;
+
+  for (const s of segments) {
+    if (
+      s.type === "loader" &&
+      s.loaderId &&
+      s._inherited &&
+      originalLoaders.has(s.loaderId) &&
+      !loadersWithLoading.has(s.loaderId)
+    ) {
+      dedupCount++;
+      continue;
+    }
+    result.push(s);
+  }
+
+  if (dedupCount > 0) {
+    debugLog(logPrefix, `deduped ${dedupCount} inherited loader segment(s)`);
+  }
+
+  return result;
+}
+
 /**
  * Build the final MatchResult from collected segments and context
  */
@@ -181,6 +244,11 @@ export function buildMatchResult<TEnv>(
     );
   }
 
+  const dedupedSegments = deduplicateLoaderSegments(
+    segmentsToRender,
+    logPrefix,
+  );
+
   debugLog(logPrefix, "all segments", {
     segments: allSegments.map((s) => ({
       id: s.id,
@@ -189,13 +257,23 @@ export function buildMatchResult<TEnv>(
     })),
   });
   debugLog(logPrefix, "segments to render", {
-    segmentIds: segmentsToRender.map((s) => s.id),
+    segmentIds: dedupedSegments.map((s) => s.id),
   });
 
+  // Remove deduped loader IDs from matched so the client doesn't treat
+  // them as missing segments and trigger a fallback refetch.
+  const removedIds = new Set(
+    segmentsToRender
+      .filter((s) => !dedupedSegments.includes(s))
+      .map((s) => s.id),
+  );
+  const matchedIds =
+    removedIds.size > 0 ? allIds.filter((id) => !removedIds.has(id)) : allIds;
+
   return {
-    segments: segmentsToRender,
-    matched: allIds,
-    diff: segmentsToRender.map((s) => s.id),
+    segments: dedupedSegments,
+    matched: matchedIds,
+    diff: dedupedSegments.map((s) => s.id),
     params: ctx.matched.params,
     routeName: ctx.routeKey,
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,

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

@@ -419,6 +419,10 @@ export async function resolveOrphanLayout<TEnv>(
         deps,
         orphan.shortCode,
       );
+      // Tag as inherited so buildMatchResult can deduplicate when safe
+      for (const s of inheritedLoaders) {
+        s._inherited = true;
+      }
       segments.push(...inheritedLoaders);
     }
   }
@@ -728,6 +732,7 @@ export async function resolveLoadersOnly<TEnv>(
         for (const seg of inherited) {
           if (!seenIds.has(seg.id)) {
             seenIds.add(seg.id);
+            seg._inherited = true;
             loaderSegments.push(seg);
           }
         }

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

@@ -346,6 +346,7 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
         for (const seg of inherited.segments) {
           if (!seenIds.has(seg.id)) {
             seenIds.add(seg.id);
+            seg._inherited = true;
             allLoaderSegments.push(seg);
           }
         }
@@ -1036,6 +1037,10 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       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);
   }
@@ -1126,6 +1131,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     );
 
     if (!resolvedParallelEntries.has(parallelEntry.id)) {
+      // shortCodeOverride must match the parent layout, not the parallel entry.
       const loaderResult = await resolveLoadersWithRevalidation(
         parallelEntry,
         context,
@@ -1138,7 +1144,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         routeKey,
         deps,
         actionContext,
-        undefined,
+        orphan.shortCode,
         stale,
       );
       segments.push(...loaderResult.segments);

package/src/rsc/handler.ts

@@ -15,6 +15,7 @@ import {
   setRequestContextParams,
   requireRequestContext,
   getRequestContext,
+  _getRequestContext,
   createRequestContext,
 } from "../server/request-context.js";
 import * as rscDeps from "@vitejs/plugin-rsc/rsc";
@@ -166,10 +167,13 @@ export function createRSCHandler<
     phase: ErrorPhase,
     context: Parameters<typeof invokeOnError<TEnv>>[3],
   ): void {
-    if (error != null && typeof error === "object") {
-      const reportedErrors = requireRequestContext()._reportedErrors;
-      if (reportedErrors.has(error)) return;
-      reportedErrors.add(error);
+    // Guard: abort signal handlers fire asynchronously outside the ALS
+    // request scope, so the context may be gone. Skip dedup in that
+    // case — the error is from a cancelled stream, not a real failure.
+    const reqCtx = _getRequestContext();
+    if (error != null && typeof error === "object" && reqCtx) {
+      if (reqCtx._reportedErrors.has(error)) return;
+      reqCtx._reportedErrors.add(error);
     }
     invokeOnError(router.onError, error, phase, context, "RSC");
   }
@@ -1090,7 +1094,11 @@ export function createRSCHandler<
             },
           };
 
-          const rscStream = renderToReadableStream(payload);
+          const rscStream = renderToReadableStream(payload, {
+            onError: (error: unknown) => {
+              callOnError(error, "rendering", { request, url, env });
+            },
+          });
 
           const isRscRequest =
             isPartial ||

package/src/rsc/loader-fetch.ts

@@ -168,8 +168,19 @@ export async function handleLoaderFetch<TEnv>(
             loaderResult: unknown;
           }
           const loaderPayload: LoaderPayload = { loaderResult: result };
-          const rscStream =
-            ctx.renderToReadableStream<LoaderPayload>(loaderPayload);
+          const rscStream = ctx.renderToReadableStream<LoaderPayload>(
+            loaderPayload,
+            {
+              onError: (error: unknown) => {
+                ctx.callOnError(error, "rendering", {
+                  request,
+                  url,
+                  env,
+                  loaderName: loaderId,
+                });
+              },
+            },
+          );
 
           return createResponseWithMergedHeaders(rscStream, {
             headers: { "content-type": "text/x-component;charset=utf-8" },
@@ -199,7 +210,16 @@ export async function handleLoaderFetch<TEnv>(
         name: err.name,
       },
     };
-    const rscStream = ctx.renderToReadableStream(errorPayload);
+    const rscStream = ctx.renderToReadableStream(errorPayload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", {
+          request,
+          url,
+          env,
+          loaderName: loaderId,
+        });
+      },
+    });
 
     return createResponseWithMergedHeaders(rscStream, {
       status: 500,

package/src/rsc/progressive-enhancement.ts

@@ -259,7 +259,11 @@ export async function handleProgressiveEnhancement<TEnv>(
       formState: actionResult,
     };
 
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", { request, url, env });
+      },
+    });
     // metricsStore=undefined is safe: the handler already stashed the early
     // SSR setup promise on request variables, so getSSRSetup returns it
     // without falling back to a fresh startSSRSetup.
@@ -360,7 +364,11 @@ async function renderPeErrorBoundary<TEnv>(
     },
   };
 
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
+  });
   // metricsStore=undefined is safe: the handler already stashed the early
   // SSR setup promise on request variables, so getSSRSetup returns it
   // without falling back to a fresh startSSRSetup.

package/src/rsc/rsc-rendering.ts

@@ -173,7 +173,11 @@ export async function handleRscRendering<TEnv>(
 
   // Serialize to RSC stream
   const rscSerializeStart = performance.now();
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
+  });
   const rscSerializeDur = performance.now() - rscSerializeStart;
   // This measures synchronous stream creation, not end-to-end stream consumption.
   appendMetric(

package/src/rsc/server-action.ts

@@ -226,6 +226,9 @@ export async function executeServerAction<TEnv>(
 
       const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
         temporaryReferences,
+        onError: (error: unknown) => {
+          ctx.callOnError(error, "rendering", { request, url, env });
+        },
       });
 
       return createResponseWithMergedHeaders(rscStream, {
@@ -332,6 +335,9 @@ export async function revalidateAfterAction<TEnv>(
   const renderStart = performance.now();
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
     temporaryReferences,
+    onError: (error: unknown) => {
+      ctx.callOnError(error, "rendering", { request, url, env });
+    },
   });
   const rscSerializeDur = performance.now() - renderStart;
   // This measures synchronous stream creation, not end-to-end stream consumption.

package/src/rsc/types.ts

@@ -70,6 +70,7 @@ export interface RSCDependencies {
     payload: T,
     options?: {
       temporaryReferences?: unknown;
+      onError?: (error: unknown) => string | void;
     },
   ) => ReadableStream<Uint8Array>;
 

package/src/segment-content-promise.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from "react";
+import type { ResolvedSegment } from "./types.js";
+
+/**
+ * Return a stable Promise wrapping `component`, memoized on `segment`.
+ *
+ * When `component` is already a Promise, returns it directly. Otherwise,
+ * returns a memoized `Promise.resolve(component)` whose identity persists
+ * across renders (stashed on the segment) so React's `use()` inside
+ * Suspender recognises it as already-fulfilled after the first observation.
+ * Without this, a fresh `Promise.resolve` each render would suspend for one
+ * microtask and briefly commit the loading fallback — the intercept /
+ * parallel-slot flicker this indirection is here to prevent.
+ *
+ * Takes `component` as a parameter (instead of reading `segment.component`)
+ * so `renderSegments` can feed in the awaited resolvedComponent during
+ * actions without having to mutate the segment.
+ *
+ * @internal
+ */
+export function getMemoizedContentPromise(
+  segment: ResolvedSegment,
+  component: ReactNode,
+): Promise<ReactNode> {
+  if (component instanceof Promise) {
+    return component as Promise<ReactNode>;
+  }
+  if (
+    segment.contentPromise !== undefined &&
+    segment.contentSource === component
+  ) {
+    return segment.contentPromise;
+  }
+  const promise = Promise.resolve(component);
+  segment.contentPromise = promise;
+  segment.contentSource = component;
+  return promise;
+}

package/src/segment-system.tsx

@@ -2,11 +2,7 @@ import * as React from "react";
 import { createElement, type ReactNode, type ComponentType } from "react";
 import { OutletProvider } from "./client.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
-import type {
-  ResolvedSegment,
-  LoaderDataResult,
-  RootLayoutProps,
-} from "./types.js";
+import type { ResolvedSegment, RootLayoutProps } from "./types.js";
 import { isLoaderDataResult } from "./types.js";
 import { invariant } from "./errors.js";
 import {
@@ -14,6 +10,7 @@ import {
   LoaderBoundary,
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
+import { getMemoizedContentPromise } from "./segment-content-promise.js";
 
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
@@ -278,10 +275,7 @@ export async function renderSegments(
       loading !== null && loading !== undefined && loading !== false
         ? createElement(RouteContentWrapper, {
             key: `suspense-loading-${id}`,
-            content:
-              resolvedComponent instanceof Promise
-                ? resolvedComponent
-                : Promise.resolve(resolvedComponent),
+            content: getMemoizedContentPromise(node.segment, resolvedComponent),
             fallback: loading,
             segmentId: id,
           })
@@ -305,8 +299,25 @@ export async function renderSegments(
 
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
-    const loaderDataPromise =
-      loaderEntries.length > 0
+
+    // Memoize the aggregate Promise.all across renders. A fresh Promise.all
+    // starts pending even when every input is already fulfilled (it needs
+    // one microtask to settle), which causes React's use() inside
+    // LoaderBoundary to suspend and briefly commit the fallback — the flicker
+    // seen when opening/closing intercepts while the main route's loaders
+    // haven't actually changed. Reusing the same aggregate ref when the
+    // underlying loader.loaderData references are unchanged keeps the promise
+    // in React's "known fulfilled" state after the first render.
+    const layoutLoaderSources = loaderEntries.map(
+      (loader) => loader.loaderData,
+    );
+    const shouldReuseLoaderPromise =
+      node.segment.loaderDataPromise !== undefined &&
+      hasSameReferences(node.segment.layoutLoaderSources, layoutLoaderSources);
+
+    const loaderDataPromise = shouldReuseLoaderPromise
+      ? node.segment.loaderDataPromise!
+      : loaderEntries.length > 0
         ? Promise.all(
             loaderEntries.map((loader) =>
               loader.loaderData instanceof Promise
@@ -316,6 +327,9 @@ export async function renderSegments(
           )
         : Promise.resolve([]);
 
+    node.segment.loaderDataPromise = loaderDataPromise;
+    node.segment.layoutLoaderSources = layoutLoaderSources;
+
     // Use LoaderBoundary when loading is defined to maintain consistent tree structure
     // This ensures cached segments (which may not have loader segments) have the same
     // tree structure as fresh segments, preventing React remounts