@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

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

@@ -9,23 +9,59 @@
  */
 
 import type { ReactNode } from "react";
-import { DataNotFoundError } from "../../errors";
+import { isDataNotFoundError } from "../../errors";
 import {
   createErrorInfo,
   createErrorSegment,
   createNotFoundInfo,
   createNotFoundSegment,
+  resolveNotFoundFallback,
 } from "../error-handling.js";
 import { getRequestContext } from "../../server/request-context.js";
 import { DefaultErrorFallback } from "../../default-error-boundary.js";
 import type { EntryData } from "../../server/context";
-import type { ResolvedSegment, ErrorInfo, HandlerContext } from "../../types";
+import type {
+  ResolvedSegment,
+  ErrorInfo,
+  HandlerContext,
+  InternalHandlerContext,
+} from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { debugLog } from "../logging.js";
 import { tryStaticLookup } from "./static-store.js";
+import { observeHandler } from "../instrument.js";
 import type { TelemetrySink } from "../telemetry.js";
 import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
 
+/** The errorContext shape wrapLoaderPromise expects as its 5th argument. */
+type LoaderErrorContext<TEnv> = NonNullable<
+  Parameters<SegmentResolutionDeps<TEnv>["wrapLoaderPromise"]>[4]
+>;
+
+/**
+ * Build the errorContext passed to wrapLoaderPromise so a throwing DSL loader
+ * fires createRouter({ onError }) (phase "loader") and emits the loader.error
+ * telemetry event. wrapLoaderPromise only wires the onError/telemetry path when
+ * this 5th argument is present; every real call site previously omitted it, so
+ * loaders were the one phase whose failures were silently dropped (handlers,
+ * actions, routing, rendering, and fetchable loaders all reported correctly).
+ *
+ * The fields come off the handler context, which already carries the request,
+ * url, params, env, and (on the internal shape) the matched route name.
+ */
+export function buildLoaderErrorContext<TEnv>(
+  ctx: HandlerContext<any, TEnv>,
+): LoaderErrorContext<TEnv> {
+  const internal = ctx as InternalHandlerContext<any, TEnv>;
+  return {
+    request: ctx.request,
+    url: ctx.url,
+    routeKey: internal._routeName,
+    params: ctx.params as Record<string, string>,
+    env: ctx.env,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Handler result processing
 // ---------------------------------------------------------------------------
@@ -36,7 +72,7 @@ import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
  * the short-circuit mechanism. Otherwise return the ReactNode.
  */
 export function handleHandlerResult(
-  result: ReactNode | Response | Promise<ReactNode> | Promise<Response>,
+  result: ReactNode | Response | Promise<ReactNode | Response>,
 ): ReactNode {
   if (result instanceof Response) {
     throw result;
@@ -52,6 +88,40 @@ export function handleHandlerResult(
   return result;
 }
 
+/**
+ * Dev-only: warn when a handler on a route that declares loading() resolves or
+ * rejects with a Response (e.g. redirect()).
+ *
+ * On a non-loading route a returned/thrown Response short-circuits to an HTTP
+ * redirect. But when the route declares loading(), the handler result is
+ * streamed (not awaited at the resolution boundary), so the Response surfaces
+ * only during RSC serialization and is rendered into the stream instead of
+ * becoming a 302/308 — a silent failure mode. Issue redirects from middleware,
+ * a loader, or a synchronous handler return instead. Compiled out in production.
+ */
+export function warnOnStreamedResponse(
+  result: Promise<unknown>,
+  entryId: string,
+): void {
+  if (process.env.NODE_ENV === "production") return;
+  // A Response can surface either as a rejection (handleHandlerResult rethrows a
+  // resolved Response) or as a resolved value (the raw parallel-slot handler is
+  // not run through handleHandlerResult). Check both so every streamed path is
+  // covered. Each handler is an independent observer; it does not consume the
+  // rejection for the trackHandler/observeStreamedHandler chains.
+  const check = (value: unknown) => {
+    if (value instanceof Response) {
+      console.warn(
+        `[rango] Handler for "${entryId}" returned a Response (e.g. ` +
+          `redirect()), but it declares loading(): the Response is rendered ` +
+          `into the RSC stream, NOT sent as an HTTP redirect. Issue redirects ` +
+          `from middleware, a loader, or a synchronous handler return.`,
+      );
+    }
+  };
+  result.then(check, check);
+}
+
 // ---------------------------------------------------------------------------
 // Static handler interception
 // ---------------------------------------------------------------------------
@@ -96,11 +166,16 @@ export async function resolveLayoutComponent<TEnv>(
   entry: EntryData,
   context: HandlerContext<any, TEnv>,
 ): Promise<ReactNode> {
-  const component = await tryStaticHandler(entry, entry.shortCode);
-  if (component !== undefined) return component;
-  return typeof entry.handler === "function"
-    ? handleHandlerResult(await entry.handler(context))
-    : (entry.handler as ReactNode);
+  // Static/prerender hit: no handler runs, so emit no rango.handler span.
+  const staticComponent = await tryStaticHandler(entry, entry.shortCode);
+  if (staticComponent !== undefined) return staticComponent;
+  const handler = entry.handler;
+  if (typeof handler !== "function") return handler as ReactNode;
+  // Wrap ONLY the handler call in the rango.handler span (the perf metric is owned
+  // by track("handler:<id>") at the call site). handleHandlerResult stays OUTSIDE
+  // the span so a handler that returns a Response (redirect control flow, which it
+  // rethrows) is not recorded as a span error — mirrors the route-handler sites.
+  return handleHandlerResult(await observeHandler(entry.id, handler, context));
 }
 
 // ---------------------------------------------------------------------------
@@ -178,36 +253,38 @@ export function catchSegmentError<TEnv>(
     }
   };
 
-  if (error instanceof DataNotFoundError) {
-    const notFoundFallback = deps.findNearestNotFoundBoundary(entry);
+  if (isDataNotFoundError(error)) {
+    const effectiveNotFoundFallback = resolveNotFoundFallback(
+      deps.findNearestNotFoundBoundary(entry),
+      deps.notFoundComponent,
+      pathname,
+    );
 
-    if (notFoundFallback) {
-      const notFoundInfo = createNotFoundInfo(
-        error,
-        entry.shortCode,
-        entry.type,
-        pathname,
-      );
+    const notFoundInfo = createNotFoundInfo(
+      error,
+      entry.shortCode,
+      entry.type,
+      pathname,
+    );
 
-      reportError(true, {
-        notFound: true,
-        message: notFoundInfo.message,
-      });
+    reportError(true, {
+      notFound: true,
+      message: notFoundInfo.message,
+    });
 
-      debugLog("segment", "notFound boundary handled error", {
-        segmentId: entry.shortCode,
-        message: notFoundInfo.message,
-      });
+    debugLog("segment", "notFound boundary handled error", {
+      segmentId: entry.shortCode,
+      message: notFoundInfo.message,
+    });
 
-      setResponseStatus(404);
+    setResponseStatus(404);
 
-      return createNotFoundSegment(
-        notFoundInfo,
-        notFoundFallback,
-        entry,
-        params,
-      );
-    }
+    return createNotFoundSegment(
+      notFoundInfo,
+      effectiveNotFoundFallback,
+      entry,
+      params,
+    );
   }
 
   const fallback = deps.findNearestErrorBoundary(entry);
@@ -245,11 +322,17 @@ export async function resolveWithErrorBoundary<TEnv, TResult>(
   deps: SegmentResolutionDeps<TEnv>,
   report?: ErrorReportContext,
   pathname?: string,
+  throwOnError?: boolean,
 ): Promise<TResult> {
   try {
     return await resolveFn();
   } catch (error) {
     if (error instanceof Response) throw error;
+    // Pre-render surfaces render failures to the build instead of baking the
+    // error boundary as a frozen 200 (issue #587). A `throw new Skip()` in a
+    // render fn also propagates here so the build can skip that URL rather than
+    // bake its error page. The live request path leaves throwOnError unset.
+    if (throwOnError) throw error;
     const segment = catchSegmentError(
       error,
       entry,

package/src/router/segment-resolution/loader-cache.ts

@@ -8,7 +8,7 @@
  * Cache key resolution (3-tier, matching CacheScope.resolveKey):
  *   1. options.key(requestCtx) — full override
  *   2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
- *   3. loader:{loaderId}:{pathname}:{sortedParams} — default
+ *   3. loader:{loaderId}:{host}{pathname}:{sortedParams} — default
  *
  * Values are serialized via RSC Flight (serializeResult/deserializeResult),
  * supporting ReactNode, Promises, null, and all RSC-serializable types.
@@ -19,18 +19,33 @@
  */
 
 import type { LoaderEntry } from "../../server/context.js";
-import type { HandlerContext } from "../../types.js";
+import type { HandlerContext, InternalHandlerContext } from "../../types.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
-import { getRequestContext } from "../../server/request-context.js";
+import {
+  getRequestContext,
+  _getRequestContext,
+  runWithRequestContext,
+} from "../../server/request-context.js";
+import { observePhase, PHASES } from "../instrument.js";
 import { sortedRouteParams } from "../../cache/cache-key-utils.js";
 import {
   resolveTtl,
   resolveSwrWindow,
   resolveCacheKey,
   resolveCacheStore,
+  resolveTagsOption,
   DEFAULT_ROUTE_TTL,
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
+import {
+  maskNestedContainerThenables,
+  overlayLoaderContainer,
+} from "./loader-snapshot.js";
+import { recordRequestTags } from "../../cache/cache-tag.js";
+import {
+  isShellCaptureActive,
+  createMaskedLoaderPromise,
+} from "./loader-mask.js";
 // Lazy-loaded to avoid pulling @vitejs/plugin-rsc/rsc into modules that
 // import segment-resolution but never use loader caching.
 let _serializeResult: typeof import("../../cache/segment-codec.js").serializeResult;
@@ -55,12 +70,13 @@ function debugLoaderCacheLog(message: string): void {
 
 function getDefaultLoaderCacheKey(
   loaderId: string,
+  host: string,
   pathname: string,
   params: Record<string, string>,
 ): string {
   const paramStr = sortedRouteParams(params);
   const base = paramStr ? `${pathname}:${paramStr}` : pathname;
-  return `loader:${loaderId}:${base}`;
+  return `loader:${loaderId}:${host}${base}`;
 }
 
 /**
@@ -74,7 +90,13 @@ async function resolveLoaderKey(
   params: Record<string, string>,
 ): Promise<string> {
   const options = loaderEntry.cache!.options;
-  const defaultKey = getDefaultLoaderCacheKey(loaderId, pathname, params);
+  // The host is part of the loader cache identity, matching the route-level
+  // cache (cache-scope getCacheKeyBase: `${host}${pathname}`) and "use cache"
+  // (cache-runtime pushes ctx.url.host). Without it, a multi-tenant host router
+  // serving the same pathname for different hosts would leak one host's cached
+  // loader data to another.
+  const host = getRequestContext()?.url?.host ?? "localhost";
+  const defaultKey = getDefaultLoaderCacheKey(loaderId, host, pathname, params);
   if (options === false) return defaultKey;
   return resolveCacheKey(options.key, store, defaultKey, "LoaderCache");
 }
@@ -87,23 +109,8 @@ async function resolveLoaderKey(
  */
 function resolveTags(loaderEntry: LoaderEntry): string[] | undefined {
   const options = loaderEntry.cache?.options;
-  if (!options || !options.tags) return undefined;
-
-  if (typeof options.tags === "function") {
-    const requestCtx = getRequestContext();
-    if (!requestCtx) return undefined;
-    try {
-      return options.tags(requestCtx);
-    } catch (error) {
-      console.error(
-        `[LoaderCache] Tags function failed, caching without tags:`,
-        error,
-      );
-      return undefined;
-    }
-  }
-
-  return options.tags;
+  if (!options) return undefined;
+  return resolveTagsOption(options.tags, getRequestContext(), "LoaderCache");
 }
 
 function getLoaderStore(
@@ -119,11 +126,107 @@ function getLoaderStore(
  *
  * When the LoaderEntry has no cache config, delegates directly to ctx.use(loader).
  * When cached, checks store first and stores on miss via waitUntil.
+ *
+ * Loader metering is NOT done here — it lives at the ctx.use execution funnel
+ * (observePhase; see instrument.ts). A cache HIT returns without calling ctx.use,
+ * so it emits no loader phase (the loader did not execute; the hit is only a
+ * LoaderCache debug log).
  */
 export function resolveLoaderData<TEnv>(
   loaderEntry: LoaderEntry,
   ctx: HandlerContext<any, TEnv>,
   pathname: string,
+  bakeSegmentKey?: string | null,
+): Promise<any> {
+  // One ALS read serves the capture check, the record registration, and the
+  // seed lookup — this runs for every loader on every request.
+  const reqCtx = _getRequestContext();
+  // PPR shell capture policy — gated here, the single funnel every loader
+  // segment path routes through (fresh resolveLoaders, cache-hit
+  // resolveLoadersOnly, revalidation resolveLoadersOnlyWithRevalidation).
+  //
+  // Two lanes (docs/design/loader-container-bake.md):
+  // - LIVE lane (entry has renderable loading(); no `bakeSegmentKey`): never
+  //   execute during capture. The slot gets a never-resolving promise so the
+  //   LoaderBoundary postpones (a hole). See loader-mask.ts.
+  // - BAKE lane (no renderable loading(); callers pass `bakeSegmentKey`):
+  //   execute during capture exactly like axis 1 — the settled container bakes
+  //   into the prelude, nested pending promises postpone at the consumer's own
+  //   Suspense. The container promise is registered on the derived context so
+  //   captureAndStoreShell pins it into the snapshot's loader family; on a
+  //   shell HIT the recorded container is overlaid onto the fresh run so the
+  //   payload matches the frozen prelude byte-for-byte.
+  if (isShellCaptureActive(reqCtx)) {
+    // EXPERIMENT (streaming useLoader, feat/useloader-suspense): route
+    // loaders are LIVE at capture UNCONDITIONALLY — the loading()-keyed lane
+    // trigger is suspended on this branch. Read-site suspension postpones
+    // each masked stream at the consumer's own Suspense boundary, so holes
+    // no longer require a route-level loading(); baking route data into a
+    // shell is expressed via cache()/"use cache", not by omitting loading().
+    // The former bake-at-capture path (execute + nested-thenable mask +
+    // snapshot pinning via _shellCaptureLoaderRecords, see git history) is
+    // bypassed: with no records registered the serve-side seed overlay is a
+    // no-op and every HIT runs loaders fresh. A masked reader with NO
+    // Suspense above it root-postpones and the capture's <body> sanity gate
+    // refuses the shell (runtime render + eternal-MISS warning), which is
+    // the intended degrade for boundary-less ppr routes.
+    return createMaskedLoaderPromise();
+  }
+
+  if (bakeSegmentKey) {
+    const seed = reqCtx?._shellLoaderSeed;
+    if (seed && seed.has(bakeSegmentKey)) {
+      const recorded = seed.get(bakeSegmentKey)!;
+      if (!recorded.holes) {
+        // Pin-first (hole-free record): the pinned container is what the
+        // payload serves either way (recorded paths win wholesale), so
+        // resolve it immediately instead of gating on the fresh run's
+        // latency — a slow bake-lane loader body otherwise stalls the HIT
+        // tail for values that get discarded. The fresh run still executes
+        // for its side effects and cache read-through writes, lifetime-
+        // extended so the runtime cannot cancel it when the stream closes
+        // first; its rejection is swallowed here (the payload already
+        // matches the prelude, which a fresh error value never could).
+        //
+        // CONTRACT (deliberate divergence from the gated overlay's
+        // fresh-only-keys passthrough): a hole-free pin serves the pinned
+        // SHAPE wholesale — a key the fresh run adds mid-TTL is dropped.
+        // It could never render server-side anyway: no hole was postponed
+        // for it at capture, so the prelude froze the without-that-field
+        // branch and the resume pass has nothing to fill; passing it
+        // through only made the hydration payload disagree with the frozen
+        // prelude (client-side mismatch repair — the divergence class the
+        // snapshot exists to prevent). A field that is per-request must be
+        // promise-shaped at capture (masked -> hole marker -> holes: 1 ->
+        // the gated path below, which preserves fresh-only passthrough) or
+        // live behind loading(). Anything else is uncached nondeterminism
+        // in shell material — the documented drift residual.
+        const fresh = executeLoaderData(loaderEntry, ctx, pathname);
+        fresh.catch(() => {});
+        reqCtx?.executionContext?.waitUntil?.(fresh);
+        return Promise.resolve(
+          overlayLoaderContainer(undefined, recorded.container),
+        );
+      }
+      // Hole-carrying record: run fresh (only the loader body can mint the
+      // live nested promises), then pin the recorded paths over it. A fresh
+      // REJECTION here skips the overlay and flows to the per-loader error
+      // boundary — the payload then diverges from the prelude (same residual
+      // class as uncached nondeterminism in shell material).
+      return executeLoaderData(loaderEntry, ctx, pathname).then(
+        (fresh: unknown) => overlayLoaderContainer(fresh, recorded.container),
+      );
+    }
+  }
+
+  return executeLoaderData(loaderEntry, ctx, pathname);
+}
+
+/** The pre-policy loader execution: cache read-through or plain ctx.use. */
+function executeLoaderData<TEnv>(
+  loaderEntry: LoaderEntry,
+  ctx: HandlerContext<any, TEnv>,
+  pathname: string,
 ): Promise<any> {
   const cacheConfig = loaderEntry.cache;
 
@@ -148,15 +251,51 @@ export function resolveLoaderData<TEnv>(
 
   const loaderId = loaderEntry.loader.$$id;
 
+  // A handler that later awaits this same loader via ctx.use(loader) must get
+  // THIS memoized promise, not a fresh execution. Rather than rebind ctx.use
+  // once per cached loader (O(N) chained wrappers + a synchronous
+  // capture-before-overwrite invariant), install a single stable interceptor on
+  // the first cached loader that consults a per-ctx override table, then just
+  // prime the table for each subsequent cached loader. The captured pre-
+  // interceptor `originalUse` (whatever setup mode installed it) runs the
+  // cache-miss execute, so a loader never awaits its own in-flight promise.
+  const internal = ctx as InternalHandlerContext<any, TEnv>;
+  let overrides = internal._loaderCacheOverrides;
+  if (!overrides) {
+    overrides = internal._loaderCacheOverrides = new Map();
+    const originalUse = ctx.use;
+    internal._loaderCacheOriginalUse = originalUse;
+    ctx.use = ((item: any) => {
+      const cached = overrides!.get(item?.$$id);
+      if (cached) return cached;
+      return originalUse(item);
+    }) as typeof ctx.use;
+  }
+  const runMiss = internal._loaderCacheOriginalUse!;
+
+  // Dedup the cache read-through across repeated resolutions of the SAME
+  // loaderId in one request. An orphan layout with parallel slots inherits its
+  // parent route's loaders, so resolveOrphanLayout (fresh.ts) re-resolves the
+  // parent's loaders under a different shortCode — calling resolveLoaderData
+  // again for the same loaderId. The cache key (loader:{loaderId}:{host}
+  // {pathname}:{sortedParams}) does not include the shortCode and ctx/params
+  // are identical, so both resolutions produce the same data. Reuse the already
+  // in-flight dataPromise instead of issuing a second getItem/setItem (e.g. a
+  // second KV round-trip) for one logical cached loader. The shortCode only
+  // affects the emitted segmentId in resolveLoaders, not the cached value.
+  const existing = overrides.get(loaderId);
+  if (existing) return existing;
+
+  // Compute ttl/swr/tags only AFTER the dedup short-circuit: a deduped second
+  // resolution of the same loaderId (the orphan-layout inheritance path) must
+  // not re-run the user tags() callback. These values are only consumed inside
+  // the read-through below, so they belong here, past the dedup gate.
   const ttl = resolveTtl(options.ttl, store.defaults, DEFAULT_ROUTE_TTL);
   const swrWindow = resolveSwrWindow(options.swr, store.defaults);
   const swr = swrWindow || undefined;
   const tags = resolveTags(loaderEntry);
+  recordRequestTags(tags);
 
-  // Wrap ctx.use() so cache HIT primes the handler's memoization map.
-  // ctx.use() closes over the match context's loaderPromises (not request context's).
-  // By intercepting ctx.use(), we inject cached data into the correct map.
-  const originalUse = ctx.use;
   const dataPromise = (async () => {
     const codec = await getCodec();
     const key = await resolveLoaderKey(
@@ -167,11 +306,30 @@ export function resolveLoaderData<TEnv>(
       ctx.params,
     );
 
+    // Capture the request context up front (foreground, ALS present) so the
+    // background stale revalidation can re-establish it. On workerd a waitUntil
+    // task runs detached from the request's I/O context, so a loader body that
+    // reads the ambient getRequestContext() would otherwise throw "called
+    // outside of a request context" and the revalidation would fail silently.
+    // The wrap is applied via wrapBackground (background path only); the
+    // foreground miss runs execute() directly since its context is present.
+    const requestCtxForExecute = getRequestContext();
     return readThroughItem({
       getItem: (k) => store.getItem!(k),
       setItem: (k, v, o) => store.setItem!(k, v, o),
       key,
-      execute: () => originalUse(loaderEntry.loader),
+      execute: () => runMiss(loaderEntry.loader),
+      // The rango.background span (kind=loader-revalidation) wraps the WHOLE
+      // stale revalidation — the re-execution AND the serialize/setItem write
+      // (read-through-swr routes the full task through wrapBackground) — so
+      // the loader's rango.loader span, its fetch/KV platform spans, and the
+      // store write all nest under one explanatory parent instead of dangling
+      // under the ended foreground phases. Inside runWithRequestContext so
+      // observePhase can read tracing on workerd (ALS detaches in waitUntil).
+      wrapBackground: (run) =>
+        runWithRequestContext(requestCtxForExecute, () =>
+          observePhase(PHASES.background("loader-revalidation"), run),
+        ),
       serialize: (d) => codec.serializeResult(d),
       deserialize: (v) => codec.deserializeResult(v),
       storeOptions: { ttl, swr, tags },
@@ -179,21 +337,11 @@ export function resolveLoaderData<TEnv>(
       onStale: () => debugLoaderCacheLog(`[LoaderCache] STALE: ${key}`),
       onMiss: () => debugLoaderCacheLog(`[LoaderCache] MISS: ${key}`),
       onCached: () => debugLoaderCacheLog(`[LoaderCache] Cached: ${key}`),
-      host: getRequestContext(),
+      host: requestCtxForExecute,
     });
   })();
 
-  // Temporarily replace ctx.use() so the handler's call returns cached data.
-  // This is needed because ctx.use() closes over the match context's loaderPromises
-  // map which is separate from the request context. By wrapping use(), we intercept
-  // the handler's call and return the shared dataPromise.
-  const wrappedUse = ((item: any) => {
-    if (item === loaderEntry.loader || item?.$$id === loaderId) {
-      return dataPromise;
-    }
-    return originalUse(item);
-  }) as typeof ctx.use;
-  ctx.use = wrappedUse;
+  overrides.set(loaderId, dataPromise);
 
   return dataPromise;
 }

package/src/router/segment-resolution/loader-mask.ts

@@ -0,0 +1,60 @@
+/**
+ * PPR shell-capture loader masking.
+ *
+ * During a shell CAPTURE re-render (Axis 2, see docs/design/ppr-shell-resume.md)
+ * route loaders are the "live lane": they must NOT execute — no side effects, no
+ * cost, no cache round-trips. Instead every loader segment's value slot receives
+ * a never-resolving promise, so the loader-consuming Suspense subtree stays
+ * pending and React's static `prerender` marks it as a postponed hole. The frozen
+ * shell (prelude) captures only the fallback; the resumed serve pass runs the
+ * loaders fresh through the unchanged execution path and streams their output
+ * into the holes.
+ *
+ * Capture mode is signalled by `requestCtx._shellCaptureRun`, set to true ONLY on
+ * the derived request context of the background capture task (shell-capture.ts) —
+ * NOT by the foreground render, whose `_shellCapture` descriptor merely means "a
+ * capture is wanted" and must not change behavior. This module is the single home
+ * for the mask so every loader execution site gates the same way (loader-cache.ts
+ * `resolveLoaderData`, fresh.ts `resolveLoaders`).
+ */
+
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../../server/request-context.js";
+
+/**
+ * True when the current render is the active PPR shell capture and route loaders
+ * must be masked rather than executed. Reads `_shellCaptureRun` off the ALS
+ * request context (the capture task re-establishes its derived context via
+ * runWithRequestContext), so it is accurate at the loader resolution sites, which
+ * run synchronously inside the pipeline's context frame.
+ */
+export function isShellCaptureActive(
+  reqCtx: RequestContext<any> | undefined = _getRequestContext(),
+): boolean {
+  return reqCtx?._shellCaptureRun === true;
+}
+
+// createMaskedLoaderPromise moved to the leaf module mask-nested.ts (shared
+// with the handle-push funnel in request-context, which cannot import THIS
+// module without a cycle). Re-exported to keep the mask API in one place.
+export { createMaskedLoaderPromise } from "./mask-nested.js";
+
+/**
+ * Lane decision for an entry's loaders under PPR (the loading() value decides;
+ * docs/design/loader-container-bake.md):
+ *
+ * - RENDERABLE loading() (the LoaderBoundary Suspense fallback) — the LIVE
+ *   lane: masked at capture, guaranteed fresh on every serve. Returns true.
+ * - No loading() (absent, or explicitly `false`, incl. `loading(x, { ssr:
+ *   false })` under the SSR manifest) — the BAKE lane: the loader executes
+ *   during capture, its settled container bakes, nested pending promises hole
+ *   at the consumer's own Suspense. Returns false.
+ *
+ * Mirrors segment-system's isRenderableLoading so the mask decision and the
+ * tree's boundary placement can never disagree.
+ */
+export function entryLoadingMasksLoaders(loading: unknown): boolean {
+  return loading !== undefined && loading !== null && loading !== false;
+}