@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/segment-system.tsx

@@ -1,6 +1,6 @@
 import * as React from "react";
 import { createElement, type ReactNode, type ComponentType } from "react";
-import { OutletProvider } from "./client.js";
+import { OutletProvider } from "./outlet-provider.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
 import { decodeLoaderResults } from "./decode-loader-results.js";
@@ -10,17 +10,58 @@ import {
   LoaderBoundary,
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
+import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
 import { getMemoizedContentPromise } from "./segment-content-promise.js";
-import { getMemoizedLoaderPromise } from "./segment-loader-promise.js";
+import {
+  buildLoaderPromise,
+  getMemoizedLoaderPromise,
+} from "./segment-loader-promise.js";
+
+/**
+ * Debug log for the segment tree build, gated on the baked flag. Runs on BOTH
+ * sides now, environment-tagged: `[Browser][segments]` lines up with the
+ * `[Browser][boot]` sequence around hydrateRoot; `[Server][segments]` exposes
+ * the SSR/RSC tree-build stalls (blocking loader awaits during fizz are what
+ * dominate MISS TTFB) that used to be invisible because the logs were
+ * window-gated. Server lines have no request correlation — segment-system is
+ * shared client code and cannot import request-context (node:async_hooks
+ * would enter the browser bundle) — so on a busy server, correlate by
+ * timestamp + segment ids.
+ */
+function segDebugLog(msg: string, details?: Record<string, unknown>): void {
+  if (!INTERNAL_RANGO_DEBUG) return;
+  const env = typeof window === "object" ? "[Browser]" : "[Server]";
+  const prefix = `${env}[segments] ${msg} @ ${Math.round(performance.now())}ms`;
+  if (details) {
+    console.log(prefix, details);
+    return;
+  }
+  console.log(prefix);
+}
 
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
 const ReactViewTransition: any =
   "ViewTransition" in React ? (React as any).ViewTransition : null;
 
-function restoreParallelLoaderMarkers(
+// A loading skeleton is renderable only when it is a real ReactNode value.
+// `false` is treated as "not renderable" here. This is the three-term gate;
+// the distinct two-term gate at the LoaderBoundary site deliberately treats
+// `false` as "create a boundary without a RouteContentWrapper"
+// (tree-structure.md), so it must NOT use this helper.
+function isRenderableLoading(loading: ReactNode): boolean {
+  return loading !== undefined && loading !== null && loading !== false;
+}
+
+// Exported for unit testing the no-parallel fast path (D6); internal otherwise.
+export function restoreParallelLoaderMarkers(
   segments: ResolvedSegment[],
 ): ResolvedSegment[] {
+  // Parallel-loading markers only exist when a parallel segment is present, so
+  // a list with no parallel slot has nothing to restore. Skip the Map alloc and
+  // full scan in that (common) case — this runs on every render.
+  if (!segments.some((s) => s.type === "parallel")) return segments;
+
   const parallelLoadingByNamespace = new Map<string, ReactNode>();
   let nextSegments: ResolvedSegment[] | null = null;
 
@@ -28,12 +69,7 @@ function restoreParallelLoaderMarkers(
     const segment = segments[i];
 
     if (segment.type === "parallel") {
-      if (
-        segment.namespace &&
-        segment.loading !== undefined &&
-        segment.loading !== null &&
-        segment.loading !== false
-      ) {
+      if (segment.namespace && isRenderableLoading(segment.loading)) {
         parallelLoadingByNamespace.set(segment.namespace, segment.loading);
       }
       continue;
@@ -142,8 +178,14 @@ function wrapDefaultOutletContent(
 /**
  * Render segments into a React tree with proper layout nesting
  *
- * Layouts nest using OutletProvider, while route + parallel + error + notFound segments
- * render as siblings in a Fragment.
+ * Layouts nest using OutletProvider; a layout receives the inner content via
+ * its `<Outlet />`. Parallel segments do NOT render as inline Fragment siblings
+ * — they flow through OutletContext.parallel and are resolved where a layout
+ * places `<ParallelOutlet name="@sidebar" />` (or `<Outlet name="@sidebar" />`).
+ *
+ * The result is always wrapped in RootErrorBoundary so unhandled errors never
+ * blank the screen. When `options.rootLayout` is provided it wraps the error
+ * boundary at the OUTERMOST level (so the app shell survives errors).
  *
  * Error segments are treated like route segments - they render their fallback
  * component in place of the failed segment. When an error occurs in a handler,
@@ -155,27 +197,30 @@ function wrapDefaultOutletContent(
  * notFoundBoundary's fallback component.
  *
  * @param segments - Array of resolved segments to render
- * @returns ReactNode representing the component tree
+ * @returns Promise resolving to the ReactNode tree (the function is async)
  *
  * @example
  * ```typescript
  * const segments = [
- *   { id: 'L0.0', type: 'layout', component: <RootLayout /> },
- *   { id: 'L1.0', type: 'layout', component: <BlogLayout /> },
- *   { id: 'R2.0', type: 'route', component: <BlogPost /> },
- *   { id: 'P3.0', type: 'parallel', component: <Sidebar />, slot: '@sidebar' }
+ *   { id: 'L0.0', type: 'layout', component: <BlogLayout /> },
+ *   { id: 'L0R1', type: 'route', component: <BlogPost /> },
+ *   { id: 'L0R1.@sidebar', type: 'parallel', component: <Sidebar />, slot: '@sidebar' }
  * ];
  *
- * const tree = renderSegments(segments);
- * // Results in:
- * // <OutletProvider><RootLayout>
- * //   <OutletProvider><BlogLayout>
- * //     <><BlogPost /><Sidebar /></>
- * //   </BlogLayout></OutletProvider>
- * // </RootLayout></OutletProvider>
+ * // BlogLayout renders <Outlet /> for the route and
+ * // <ParallelOutlet name="@sidebar" /> for the parallel slot.
+ * const tree = await renderSegments(segments, { rootLayout: RootLayout });
+ * // Results in (outermost first):
+ * // <RootLayout>
+ * //   <RootErrorBoundary>
+ * //     <OutletProvider segment={BlogLayout} parallel={[Sidebar]}>
+ * //       <BlogPost />
+ * //     </OutletProvider>
+ * //   </RootErrorBoundary>
+ * // </RootLayout>
  *
  * // For server actions, pass isAction to await components:
- * const tree = renderSegments(segments, { isAction: true });
+ * const tree = await renderSegments(segments, { isAction: true });
  * ```
  */
 export async function renderSegments(
@@ -189,6 +234,17 @@ export async function renderSegments(
     rootLayout: RootLayout,
   } = options || {};
 
+  const segDebug = INTERNAL_RANGO_DEBUG;
+  const segDebugStart = segDebug ? performance.now() : 0;
+  if (segDebug) {
+    segDebugLog("renderSegments start", {
+      segments: segments.map((s) => `${s.id}:${s.type}`),
+      isAction: !!isAction,
+      forceAwait: !!forceAwait,
+      intercepts: interceptSegments?.length ?? 0,
+    });
+  }
+
   const temporalLazyRefs: Promise<any>[] = [];
   const normalizedSegments = restoreParallelLoaderMarkers(segments);
   const normalizedInterceptSegments = interceptSegments
@@ -249,6 +305,7 @@ export async function renderSegments(
       `Expected layout, route, error, or notFound segment, got ${node.segment.type}`,
     );
     const { component, id, params, loading } = node.segment;
+    const segNodeStart = segDebug ? performance.now() : 0;
 
     // Param-agnostic keys are opt-in via the transition() DSL (see
     // inTransitionScope above). A route (and its route-owned layouts) inside a
@@ -283,31 +340,71 @@ export async function renderSegments(
             .map(([k, v]) => `${k}=${v}`)
             .join(",")
         : "";
-    const key = `${paramStr ? `${id}-${paramStr}` : id}`;
+    const key = paramStr ? `${id}-${paramStr}` : id;
 
-    // Get loader entries for this node
     const loaderEntries = node.loaders.filter(
       (loader) => loader.loaderId && loader.loaderData !== undefined,
     );
 
-    // Determine the component content (with or without Suspense wrapper)
-    // Wrap when loading skeleton defined OR component is Promise (needs Suspense)
-    // During actions, await component Promise to prevent Suspense from triggering
-    // This keeps existing content visible instead of showing loading skeleton
     let resolvedComponent = component;
     if (isAction && component instanceof Promise) {
+      const componentAwaitStart = segDebug ? performance.now() : 0;
       resolvedComponent = await component;
+      if (segDebug) {
+        segDebugLog(`segment ${id}: component awaited (action)`, {
+          ms: Math.round(performance.now() - componentAwaitStart),
+        });
+      }
     }
 
-    let nodeContent: ReactNode =
-      loading !== null && loading !== undefined && loading !== false
-        ? createElement(RouteContentWrapper, {
-            key: `suspense-loading-${id}`,
-            content: getMemoizedContentPromise(resolvedComponent),
-            fallback: loading,
-            segmentId: id,
-          })
-        : registerLazyRef(resolvedComponent);
+    let nodeContent: ReactNode = null;
+    if (isRenderableLoading(loading)) {
+      // forceAwait (popstate, stale-revalidation, fully-prefetched nav) renders a
+      // loading() route with the route content ALREADY resolved, so its
+      // RouteContentWrapper Suspender does not suspend for a microtask and flash
+      // the loading() fallback on a NORMAL (non-transition) commit. The router
+      // data is known-ready on these paths, so awaiting the content here is free.
+      // The wrapper tree is unchanged (RouteContentWrapper is still created with
+      // the same key/fallback) — only the `content` prop is a resolved node
+      // instead of a pending promise, which Suspender renders synchronously. This
+      // mirrors the forceAwait loaderData unwrap above; a CLIENT component that
+      // suspends on mount inside the content still reveals a fallback (it is not
+      // pre-resolved).
+      const contentPromise = getMemoizedContentPromise(resolvedComponent);
+      let loadingContent: Promise<ReactNode> | ReactNode = contentPromise;
+      if (forceAwait) {
+        const contentAwaitStart = segDebug ? performance.now() : 0;
+        loadingContent = await contentPromise;
+        if (segDebug) {
+          segDebugLog(`segment ${id}: content awaited (forceAwait)`, {
+            ms: Math.round(performance.now() - contentAwaitStart),
+          });
+        }
+      }
+      nodeContent = createElement(RouteContentWrapper, {
+        key: `suspense-loading-${id}`,
+        content: loadingContent,
+        fallback: loading,
+        segmentId: id,
+      });
+    } else {
+      // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. A segment in the no-loading()
+      // branch whose component decodes as a Promise/lazy gets registered into
+      // temporalLazyRefs and awaited before commit (see below) — which on builds
+      // where the segment component arrives deferred defeats client-nav streaming.
+      if (INTERNAL_RANGO_DEBUG && typeof window === "object") {
+        const c = resolvedComponent as unknown;
+        console.log("[VT-DIAG] renderSegments no-loading-branch segment", {
+          id,
+          type: node.segment.type,
+          componentIsPromise: c instanceof Promise,
+          componentIsLazy:
+            c != null && typeof c === "object" && "_payload" in c,
+          componentTypeof: typeof c,
+        });
+      }
+      nodeContent = registerLazyRef(resolvedComponent);
+    }
 
     // Wrap with <ViewTransition> if transition config exists (React experimental only).
     // An empty config ({}) creates a bare <ViewTransition> boundary that participates
@@ -351,18 +448,27 @@ export async function renderSegments(
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
 
-    // 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
-    // If forceAwait or isAction is set, pre-resolve promises so LoaderBoundary won't suspend
     if (loading !== undefined && loading !== null) {
-      // Aggregate built here only — the loaderless and no-loading branches don't
-      // read it (the latter builds its own per-parallel promises).
       const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
+      let boundaryLoaderData: Promise<any[]> | any[] = loaderDataPromise;
+      if (forceAwait || isAction) {
+        const awaitStart = segDebug ? performance.now() : 0;
+        boundaryLoaderData = await loaderDataPromise;
+        if (segDebug) {
+          segDebugLog(`segment ${id}: loaders awaited (forceAwait/action)`, {
+            loaderIds,
+            ms: Math.round(performance.now() - awaitStart),
+          });
+        }
+      } else if (segDebug) {
+        segDebugLog(
+          `segment ${id}: streaming loaders via LoaderBoundary (suspense)`,
+          { loaderIds },
+        );
+      }
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
-        loaderDataPromise:
-          forceAwait || isAction ? await loaderDataPromise : loaderDataPromise,
+        loaderDataPromise: boundaryLoaderData,
         loaderIds,
         fallback: loading,
         outletKey: key,
@@ -372,7 +478,6 @@ export async function renderSegments(
         children: nodeContent,
       });
     } else if (loaderEntries.length === 0) {
-      // No loaders, no loading - simple OutletProvider
       content = createElement(OutletProvider, {
         key,
         content: outletContent,
@@ -381,34 +486,37 @@ export async function renderSegments(
         children: nodeContent,
       });
     } else {
-      // Has loaders but no loading skeleton.
-      // Split: parallel-owned loaders stream (their parallel has loading()),
-      // layout-owned loaders are awaited (they gate the layout content).
       const layoutLoaders = loaderEntries.filter((l) => !l.parallelLoading);
       const parallelOwnedLoaders = loaderEntries.filter(
         (l) => !!l.parallelLoading,
       );
 
-      // Await only layout-owned loaders
       const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
-      const layoutLoaderDataPromise =
-        layoutLoaders.length > 0
-          ? Promise.all(
-              layoutLoaders.map((l) =>
-                l.loaderData instanceof Promise
-                  ? l.loaderData
-                  : Promise.resolve(l.loaderData),
-              ),
-            )
-          : Promise.resolve([]);
-      const resolvedData = await layoutLoaderDataPromise;
+      // No loading() on this segment, so its loader data cannot stream behind
+      // a Suspense fallback — the tree build BLOCKS here until the data
+      // arrives. On the initial document this await runs before hydrateRoot.
+      const layoutAwaitStart = segDebug ? performance.now() : 0;
+      const resolvedData = await buildLoaderPromise(layoutLoaders);
+      if (segDebug) {
+        segDebugLog(`segment ${id}: layout loaders awaited (blocking)`, {
+          loaderIds: layoutLoaderIds,
+          ms: Math.round(performance.now() - layoutAwaitStart),
+        });
+      }
+      const decodeStart = segDebug ? performance.now() : 0;
       const { loaderData, errorFallback } = decodeLoaderResults(
         resolvedData,
         layoutLoaderIds,
       );
+      if (segDebug) {
+        const decodeMs = Math.round(performance.now() - decodeStart);
+        if (decodeMs > 0) {
+          segDebugLog(`segment ${id}: loader results decoded`, {
+            ms: decodeMs,
+          });
+        }
+      }
 
-      // Parallel-owned loaders: attach to their owning parallel segment
-      // as loaderDataPromise so ParallelOutlet wraps in LoaderBoundary
       if (parallelOwnedLoaders.length > 0) {
         const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
 
@@ -436,10 +544,27 @@ export async function renderSegments(
 
           p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
           const aggregated = getMemoizedLoaderPromise(ownedLoaders);
-          p.loaderDataPromise =
-            (forceAwait || isAction) && aggregated instanceof Promise
-              ? await aggregated
-              : aggregated;
+          if ((forceAwait || isAction) && aggregated instanceof Promise) {
+            const parallelAwaitStart = segDebug ? performance.now() : 0;
+            p.loaderDataPromise = await aggregated;
+            if (segDebug) {
+              segDebugLog(
+                `segment ${id}: parallel ${p.id} loaders awaited (forceAwait/action)`,
+                {
+                  loaderIds: p.loaderIds,
+                  ms: Math.round(performance.now() - parallelAwaitStart),
+                },
+              );
+            }
+          } else {
+            p.loaderDataPromise = aggregated;
+            if (segDebug) {
+              segDebugLog(
+                `segment ${id}: parallel ${p.id} loaders streaming (suspense)`,
+                { loaderIds: p.loaderIds },
+              );
+            }
+          }
         }
       }
 
@@ -463,28 +588,56 @@ export async function renderSegments(
         children: content,
       });
     }
+
+    if (segDebug) {
+      segDebugLog(`segment ${id} built`, {
+        type: node.segment.type,
+        ms: Math.round(performance.now() - segNodeStart),
+        loaders: node.loaders.map((l) => l.loaderId).filter(Boolean),
+        hasLoading: loading !== undefined && loading !== null,
+        parallel: node.parallel.map((p) => p.id),
+      });
+    }
   }
 
-  // Always wrap with root error boundary to prevent white screens
-  // This catches any unhandled errors that bubble up from the segment tree
   const errorBoundaryWrapped = createElement(RootErrorBoundary, {
     children: content,
   });
   if (typeof window === "object") {
+    // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. If this await dominates the
+    // navigation time, a deferred/lazy segment component is being fully resolved
+    // before commit, which defeats client-nav streaming. The await itself is
+    // functional (it preloads lazy chunk refs); only the timing log is gated.
+    const vtDebug = INTERNAL_RANGO_DEBUG && temporalLazyRefs.length > 0;
+    const vtDebugStart = vtDebug ? performance.now() : 0;
+    if (vtDebug) {
+      console.log("[VT-DIAG] renderSegments awaiting temporalLazyRefs", {
+        count: temporalLazyRefs.length,
+      });
+    }
     await Promise.allSettled(temporalLazyRefs);
+    if (vtDebug) {
+      console.log("[VT-DIAG] renderSegments temporalLazyRefs settled", {
+        count: temporalLazyRefs.length,
+        ms: Math.round(performance.now() - vtDebugStart),
+      });
+    }
   }
 
-  // Build the final result, optionally wrapped with root layout
   let result: ReactNode = errorBoundaryWrapped;
 
-  // If rootLayout is provided, wrap the error boundary with it
-  // This ensures the app shell stays mounted even during errors (prevents FOUC)
   if (RootLayout) {
     result = createElement(RootLayout, {
       children: errorBoundaryWrapped,
     });
   }
 
+  if (segDebug) {
+    segDebugLog("renderSegments complete", {
+      ms: Math.round(performance.now() - segDebugStart),
+    });
+  }
+
   return result;
 }
 
@@ -516,6 +669,31 @@ export async function renderSegments(
  * @param segments - Main segments from the route tree
  * @param interceptSegments - Optional intercept segments to inject
  */
+// Loader segment ids have the grammar `${parentId}D${index}.${loaderId}`.
+// parentId is the parent shortCode (M/L/P/R/C + digits, never "D") for normal
+// loaders, or `${shortCode}.${slotName}` for intercept-slot loaders, where the
+// slot name is user-controlled (`@${string}`) and may contain an uppercase "D"
+// (e.g. "@Detail"). Strip from the first `D<index>.` separator so the slot name
+// is preserved; splitting on a bare "D" mis-cut "@Detail" to "@" and silently
+// dropped the loader's data. The first-`D<index>.` strip is only correct because
+// slot names cannot contain "." -- assertValidSlotName (route-definition/
+// dsl-helpers.ts) rejects a "." at definition time, so a name like "@D3.foo"
+// (which WOULD mis-cut here) can never reach this function.
+function loaderParentId(loaderSegmentId: string): string {
+  return loaderSegmentId.replace(/D\d+\..*$/, "");
+}
+
+// Append a value to the array stored under `key`, creating the array on first
+// use. Single Map lookup (vs the has/get!().push double-lookup idiom).
+function pushToGroup<K, V>(map: Map<K, V[]>, key: K, value: V): void {
+  const arr = map.get(key);
+  if (arr) {
+    arr.push(value);
+  } else {
+    map.set(key, [value]);
+  }
+}
+
 function* segmentTreeWalk(
   segments: ResolvedSegment[],
   interceptSegments?: ResolvedSegment[],
@@ -536,19 +714,12 @@ function* segmentTreeWalk(
       // Extract parent ID from parallel ID
       // Example: "L0R1L0.@sidebar" → "L0R1L0"
       const parentId = segment.id.split(".")[0];
-      if (!parallelsByParent.has(parentId)) {
-        parallelsByParent.set(parentId, []);
-      }
-      parallelsByParent.get(parentId)!.push(segment);
+      pushToGroup(parallelsByParent, parentId, segment);
     } else if (segment.type === "loader") {
       // Extract parent ID from loader ID
-      // Example: "L0D0.cart" → "L0"
-      // Loader ID format: {parentShortCode}D{index}.{loaderId}
-      const parentId = segment.id.split("D")[0];
-      if (!loadersByParent.has(parentId)) {
-        loadersByParent.set(parentId, []);
-      }
-      loadersByParent.get(parentId)!.push(segment);
+      // Example: "L0D0.cart" → "L0"; "L0.@DetailD0.x" → "L0.@Detail"
+      const parentId = loaderParentId(segment.id);
+      pushToGroup(loadersByParent, parentId, segment);
     } else {
       // Layout, route, error, and notFound segments are all rendered in the tree
       // Error/notFound segments replace the failed segment with fallback UI
@@ -563,17 +734,11 @@ function* segmentTreeWalk(
       if (intercept.type === "parallel" && intercept.slot) {
         // Extract parent ID from intercept ID (e.g., "M4L0L0L2.@modal" → "M4L0L0L2")
         const parentId = intercept.id.split(".")[0];
-        if (!parallelsByParent.has(parentId)) {
-          parallelsByParent.set(parentId, []);
-        }
-        parallelsByParent.get(parentId)!.push(intercept);
+        pushToGroup(parallelsByParent, parentId, intercept);
       } else if (intercept.type === "loader") {
-        // Intercept loaders - extract parent from loader ID
-        const parentId = intercept.id.split("D")[0];
-        if (!loadersByParent.has(parentId)) {
-          loadersByParent.set(parentId, []);
-        }
-        loadersByParent.get(parentId)!.push(intercept);
+        // Intercept loaders - extract parent from loader ID (slot name preserved)
+        const parentId = loaderParentId(intercept.id);
+        pushToGroup(loadersByParent, parentId, intercept);
       }
     }
   }

package/src/server/context.ts

@@ -150,6 +150,19 @@ export type InterceptWhenFn<TEnv = any> = (
   ctx: InterceptSelectorContext<TEnv>,
 ) => boolean;
 
+/**
+ * Config object passed to intercept() (its 4th argument). `when` gates whether
+ * the intercept activates on a soft navigation — a single match-time selector or
+ * an array of them (ALL must return true; omit to always activate). This is the
+ * intercept counterpart to transition({ when }); both express conditional
+ * behavior as a config field rather than a separate DSL helper.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface InterceptConfig<TEnv = any> {
+  when?: InterceptWhenFn<TEnv> | InterceptWhenFn<TEnv>[];
+}
+
 /**
  * Intercept entry stored in EntryData
  * Contains the slot name, route to intercept, and handler
@@ -220,6 +233,13 @@ export type EntryData =
       staticHandlerId?: string;
       /** Response type for non-RSC routes (json, text, image, any) */
       responseType?: string;
+      /**
+       * PPR (partial pre-rendering) opt-in from the path() `ppr` option. A
+       * document-level property of the page route: `true` uses the default
+       * shell policy, an object carries ttl/swr/tags. Read by the integrated
+       * PPR serve path (rsc/shell-serve.ts resolvePprConfig).
+       */
+      ppr?: boolean | import("../urls/pattern-types.js").PartialPrerenderProps;
     } & EntryPropCommon &
       EntryPropDatas &
       EntryPropSegments &
@@ -750,14 +770,23 @@ const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
 
 // Purity-only scope: marks that a loader FUNCTION BODY is executing, regardless
 // of how the loader was invoked (DSL via runInsideLoaderScope, or handler-
-// invoked via ctx.use). Consulted ONLY by isInsideCacheScope() to exempt
-// request-scoped reads. It deliberately does NOT affect isInsideLoaderScope(),
-// so rendered()/barrier/deadlock gating (which must distinguish DSL from
-// handler-invoked loaders) is unchanged.
+// invoked via ctx.use). Consulted by isInsideCacheScope() to exempt
+// request-scoped reads, by getCurrentLoaderBodyId() for guard-warning
+// attribution, and by isInsideHandlerInvokedLoaderBody() for the
+// consumption-lane rule (the shell-capture guard exemption). It deliberately
+// does NOT affect isInsideLoaderScope(), so rendered()/barrier/deadlock
+// gating (which must distinguish DSL from handler-invoked loaders) is
+// unchanged.
 const LOADER_BODY_SCOPE_KEY = Symbol.for("rangojs-router:loader-body-scope");
-const loaderBodyScopeALS: AsyncLocalStorage<{ active: true }> = ((
-  globalThis as any
-)[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage<{ active: true }>());
+const loaderBodyScopeALS: AsyncLocalStorage<{
+  active: true;
+  loaderId?: string;
+  handlerInvoked?: boolean;
+}> = ((globalThis as any)[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage<{
+  active: true;
+  loaderId?: string;
+  handlerInvoked?: boolean;
+}>());
 
 /**
  * Check if the current execution is inside a cache() DSL boundary.
@@ -802,6 +831,67 @@ export function runInsideLoaderScope<T>(fn: () => T): T {
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
  * never trip the cache-scope guards — loaders always run fresh.
  */
-export function runInsideLoaderBodyScope<T>(fn: () => T): T {
-  return loaderBodyScopeALS.run({ active: true }, fn);
+export function runInsideLoaderBodyScope<T>(
+  fn: () => T,
+  loaderId?: string,
+  handlerInvoked?: boolean,
+): T {
+  return loaderBodyScopeALS.run({ active: true, loaderId, handlerInvoked }, fn);
+}
+
+/**
+ * The $$id of the loader whose body is currently executing, or undefined
+ * outside any loader body. Used by the shell-capture identity guard
+ * (cookie-store.ts) so its refusal warning can name the loader that read
+ * cookies()/headers() instead of blaming a lane it cannot see — the old
+ * hardcoded "bake-lane loader" text misled a live-lane debugging session
+ * (issue #672, secondary).
+ */
+export function getCurrentLoaderBodyId(): string | undefined {
+  return loaderBodyScopeALS.getStore()?.loaderId;
+}
+
+/**
+ * True while a HANDLER-invoked loader body (`await ctx.use(Loader)` from a
+ * handler, not the DSL segment funnel) is executing. The consumption-lane
+ * rule keys off this: handler consumption yields a BAKED copy in every shared
+ * artifact — cache(), "use cache", and the PPR shell — so the shell-capture
+ * identity guard (cookie-store.ts) permits cookies()/headers() here, exactly
+ * like the cache-purity guards do. DSL segment loaders (live lane masked at
+ * capture, bake lane guarded) never set the flag.
+ */
+export function isInsideHandlerInvokedLoaderBody(): boolean {
+  return loaderBodyScopeALS.getStore()?.handlerInvoked === true;
+}
+
+// Scope for handle PUSH CALLBACKS (push(() => ...), including async ones).
+// A push callback's value is stored as-is; if it is a promise it is NOT tracked
+// by handleStore.settled and does not block segment resolution, so a
+// ctx.use(loader) made from inside such a callback can never form a rendered()
+// deadlock. This is an ALS (not a plain boolean) so the exemption survives the
+// callback's own awaits — an async push callback that resumes after `await`
+// still reads as "inside a push callback" and stays out of the deadlock guard.
+const PUSH_CALLBACK_SCOPE_KEY = Symbol.for(
+  "rangojs-router:push-callback-scope",
+);
+const pushCallbackScopeALS: AsyncLocalStorage<{ active: true }> = ((
+  globalThis as any
+)[PUSH_CALLBACK_SCOPE_KEY] ??= new AsyncLocalStorage<{ active: true }>());
+
+/**
+ * Check if the current execution is inside a handle push callback (sync or an
+ * async callback's continuation). Used by the handler-to-loader deadlock guard
+ * to exempt push-callback continuations.
+ */
+export function isInsidePushCallbackScope(): boolean {
+  return pushCallbackScopeALS.getStore()?.active === true;
+}
+
+/**
+ * Run `fn` inside a push-callback scope. Wraps the invocation of a handle push
+ * callback so that any ctx.use(loader) it makes — including after one of its own
+ * awaits — is exempt from the deadlock guard.
+ */
+export function runInsidePushCallbackScope<T>(fn: () => T): T {
+  return pushCallbackScopeALS.run({ active: true }, fn);
 }