@rangojs/router 0.0.0-experimental.e16b7c00 → 0.0.0-experimental.e9c0b2f2

package/src/router/router-options.ts

@@ -11,6 +11,7 @@ import type { UrlPatterns } from "../urls.js";
 import type { UrlBuilder } from "../urls/pattern-types.js";
 import type { NamedRouteEntry } from "./content-negotiation.js";
 import type { TelemetrySink } from "./telemetry.js";
+import type { RouterTracingConfig } from "./tracing.js";
 import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
 
 /**
@@ -132,6 +133,21 @@ export interface RangoOptions<TEnv = any> {
    */
   allowDebugManifest?: boolean;
 
+  /**
+   * DEVELOPMENT/TEST ONLY. Emit an `X-Rango-Cache` response header describing
+   * the cache status of the matched route, for use by testing primitives such
+   * as `assertCacheStatus`.
+   *
+   * Defaults to `false`. When neither this option nor the
+   * `RANGO_TEST_SIGNALS=1` environment flag is set, NO header is emitted and
+   * router output is byte-identical to the default.
+   *
+   * The header encodes per-segment (v1: coarse route-level) status keyed by the
+   * route NAME, e.g. `X-Rango-Cache: product.detail=hit`. Do NOT enable in
+   * production — it exposes internal cache decisions.
+   */
+  debugCacheSignal?: boolean;
+
   /**
    * Document component that wraps the entire application.
    *
@@ -481,6 +497,21 @@ export interface RangoOptions<TEnv = any> {
    */
   prefetchCacheTTL?: number | false;
 
+  /**
+   * Prefix for the rango state cookie name. The resolved name is
+   * `{prefix}_{routerId}`; the prefix is sanitized to cookie-name-safe
+   * characters (`[A-Za-z0-9-]`) and an empty result falls back to the default.
+   *
+   * The rango state cookie keys the client's prefetch / HTTP caches. Overriding
+   * the prefix lets you align it with cookie-naming policies or consent-manager
+   * classification lists, or avoid colliding with an existing `rango-state`
+   * cookie. It is not a full-name override: the `_{routerId}` suffix is what
+   * keeps sibling apps on one origin from clobbering each other's state.
+   *
+   * @default "rango-state"
+   */
+  stateCookiePrefix?: string;
+
   /**
    * Enable connection warmup to keep TCP+TLS alive after idle periods.
    *
@@ -492,6 +523,29 @@ export interface RangoOptions<TEnv = any> {
    */
   warmup?: boolean;
 
+  /**
+   * Wrap the hydrated client tree in `React.StrictMode`.
+   *
+   * The Rango browser entry hydrates the app inside `<React.StrictMode>` by
+   * default. StrictMode double-invokes render and (in development) mounts,
+   * unmounts, then remounts every effect to surface impure renders and missing
+   * effect cleanup. Production builds treat StrictMode as a no-op, so this flag
+   * only changes development behavior in a normal app.
+   *
+   * Set to `false` to hydrate without the StrictMode wrapper. The main reason to
+   * opt out is to isolate StrictMode's intentional double-render/double-effect
+   * from genuine re-renders when measuring client-hook stability — with
+   * StrictMode off, render counts are exact in development too.
+   *
+   * The value is resolved server-side at router creation and shipped to the
+   * client in the initial payload metadata; the browser entry reads it once at
+   * hydration. Changing it does not affect the SSR HTML (StrictMode emits no
+   * DOM), so toggling it never causes a hydration mismatch.
+   *
+   * @default true
+   */
+  strictMode?: boolean;
+
   /**
    * Shorthand timeout (ms) applied to both action execution and render start.
    * Does NOT apply to streamIdleMs.
@@ -544,11 +598,14 @@ export interface RangoOptions<TEnv = any> {
   onTimeout?: OnTimeoutCallback<TEnv>;
 
   /**
-   * Telemetry sink for structured lifecycle events.
+   * Telemetry sink for structured, discrete lifecycle EVENTS: request
+   * start/end/error, loader start/end/error, handler errors, cache decisions,
+   * revalidation decisions, timeouts, origin rejections.
    *
-   * When provided, the router emits events for request start/end,
-   * loader start/end/error, handler errors, cache decisions, and
-   * revalidation decisions.
+   * This is the EVENT surface. Phase-duration SPANS (request/middleware/action/
+   * handler/loader/render/ssr timing wired into a tracing backend) come from the
+   * separate `tracing` option below — a sink does not emit them, because async-context nesting
+   * cannot be faithfully reconstructed from after-the-fact start/end events.
    *
    * No-op when not configured (zero overhead).
    *
@@ -561,6 +618,18 @@ export interface RangoOptions<TEnv = any> {
    * });
    * ```
    *
+   * @example OpenTelemetry — pair the event sink with the tracing slot
+   * ```typescript
+   * import { createOTelTracing, createOTelSink } from "@rangojs/router";
+   * import { trace } from "@opentelemetry/api";
+   *
+   * const tracer = trace.getTracer("my-app");
+   * const router = createRouter({
+   *   tracing: createOTelTracing(tracer), // phase spans
+   *   telemetry: createOTelSink(tracer), // discrete-fact events
+   * });
+   * ```
+   *
    * @example Custom sink
    * ```typescript
    * const router = createRouter({
@@ -574,6 +643,44 @@ export interface RangoOptions<TEnv = any> {
    */
   telemetry?: TelemetrySink;
 
+  /**
+   * Span tracing for the router's performance phases (request, middleware, action,
+   * loaders, render, ssr). Connects the same phases shown in the
+   * `debugPerformance` timeline to the host platform's tracing system. This is
+   * the SPAN surface (the `telemetry` option above is the event surface).
+   *
+   * Two factories produce a config, both for this slot:
+   * - `createOTelTracing(tracer)` from `@rangojs/router` — any platform with an
+   *   OpenTelemetry SDK (including Node). Bridges the phases onto
+   *   `tracer.startActiveSpan`.
+   * - `createCloudflareTracing()` from `@rangojs/router/cloudflare` — Cloudflare
+   *   Workers native custom spans, alongside the automatic KV/D1/fetch spans.
+   *
+   * When tracing is unset — or off-platform (no OTel SDK / no Cloudflare tracing
+   * destination) — every span call falls through to the work directly, so the
+   * request behaves exactly as if tracing were off.
+   *
+   * @example OpenTelemetry
+   * ```typescript
+   * import { createOTelTracing } from "@rangojs/router";
+   * import { trace } from "@opentelemetry/api";
+   *
+   * const router = createRouter({
+   *   tracing: createOTelTracing(trace.getTracer("my-app")),
+   * });
+   * ```
+   *
+   * @example Cloudflare
+   * ```typescript
+   * import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+   *
+   * const router = createRouter({
+   *   tracing: createCloudflareTracing({ spans: { ssr: false } }),
+   * });
+   * ```
+   */
+  tracing?: RouterTracingConfig;
+
   /**
    * SSR configuration options.
    *

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

@@ -19,67 +19,25 @@ import type {
 } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { resolveLoaderData } from "./loader-cache.js";
-import { _getRequestContext } from "../../server/request-context.js";
-import { appendMetric } from "../metrics.js";
 import {
   handleHandlerResult,
   tryStaticHandler,
   tryStaticSlot,
   resolveLayoutComponent,
   resolveWithErrorBoundary,
+  warnOnStreamedResponse,
+  buildLoaderErrorContext,
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
-import { resolveSink, safeEmit } from "../telemetry.js";
+import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
+import { observeHandler } from "../instrument.js";
 import {
   track,
   RangoContext,
   runInsideLoaderScope,
 } from "../../server/context.js";
 
-// ---------------------------------------------------------------------------
-// Streamed handler telemetry
-// ---------------------------------------------------------------------------
-
-/**
- * Attach a fire-and-forget rejection observer to a streamed handler promise.
- * React catches the actual error via its error boundary; this only emits
- * the handler.error telemetry event.
- */
-function observeStreamedHandler(
-  promise: Promise<ReactNode>,
-  segmentId: string,
-  segmentType: string,
-  pathname?: string,
-  routeKey?: string,
-  params?: Record<string, string>,
-): void {
-  let routerCtx;
-  try {
-    routerCtx = getRouterContext();
-  } catch {
-    return;
-  }
-  if (!routerCtx?.telemetry) return;
-  const sink = resolveSink(routerCtx.telemetry);
-  const reqId = routerCtx.requestId;
-  promise.catch((err: unknown) => {
-    const errorObj = err instanceof Error ? err : new Error(String(err));
-    safeEmit(sink, {
-      type: "handler.error",
-      timestamp: performance.now(),
-      requestId: reqId,
-      segmentId,
-      segmentType,
-      error: errorObj,
-      handledByBoundary: true,
-      pathname,
-      routeKey,
-      params,
-    });
-  });
-}
-
 // ---------------------------------------------------------------------------
 // Fresh path (full match, no revalidation)
 // ---------------------------------------------------------------------------
@@ -101,7 +59,13 @@ export async function resolveLoaders<TEnv>(
   const shortCode = shortCodeOverride ?? entry.shortCode;
   const hasLoading = "loading" in entry && entry.loading !== undefined;
   const loadingDisabled = hasLoading && entry.loading === false;
-  const ms = _getRequestContext()?._metricsStore;
+
+  // 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 (!loadingDisabled) {
     // Streaming loaders: promises kick off now, settle during RSC serialization.
@@ -123,6 +87,7 @@ export async function resolveLoaders<TEnv>(
           entry,
           segmentId,
           ctx.pathname,
+          errorContext,
         ),
         belongsToRoute,
       };
@@ -133,46 +98,46 @@ export async function resolveLoaders<TEnv>(
 
   // Loading disabled: still start all loaders in parallel, but only emit
   // settled promises so handlers don't stream loading placeholders.
-  const pendingLoaderData = loaderEntries.map((loaderEntry) => {
-    const start = performance.now();
-    const promise = runInsideLoaderScope(() =>
-      resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+  //
+  // Wrap each loader promise with wrapLoaderPromise BEFORE awaiting. The wrapped
+  // promise resolves to a LoaderDataResult and never rejects, routing a failed
+  // loader to its own per-loader error boundary. Awaiting the RAW promises here
+  // instead would (1) propagate a rejection to the segment-level boundary,
+  // collapsing the whole entry and discarding successful sibling data, and
+  // (2) leave the other in-flight raw promises without a .catch, producing
+  // unhandled rejections. Mirrors the loading path and intercept-resolution.
+  const pendingLoaderData = loaderEntries.map((loaderEntry, i) => {
+    const { loader } = loaderEntry;
+    const segmentId = `${shortCode}D${i}.${loader.$$id}`;
+    const wrapped = deps.wrapLoaderPromise(
+      runInsideLoaderScope(() =>
+        resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+      ),
+      entry,
+      segmentId,
+      ctx.pathname,
+      errorContext,
     );
-    return { promise, start, loaderId: loaderEntry.loader.$$id };
+    return { wrapped, segmentId };
   });
-  await Promise.all(pendingLoaderData.map((p) => p.promise));
+  await Promise.all(pendingLoaderData.map((p) => p.wrapped));
 
   return loaderEntries.map((loaderEntry, i) => {
     const { loader } = loaderEntry;
-    const segmentId = `${shortCode}D${i}.${loader.$$id}`;
     const pending = pendingLoaderData[i]!;
-    if (ms && !ms.metrics.some((m) => m.label === `loader:${loader.$$id}`)) {
-      // All loaders ran in parallel via Promise.all — each span covers
-      // from its own kickoff to the batch settlement, giving a ceiling
-      // on that loader's contribution to the overall wait.
-      const batchEnd = performance.now();
-      appendMetric(
-        ms,
-        `loader:${loader.$$id}`,
-        pending.start,
-        batchEnd - pending.start,
-        2,
-      );
-    }
+    // 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: segmentId,
+      id: pending.segmentId,
       namespace: entry.id,
       type: "loader" as const,
       index: i,
       component: null,
       params: ctx.params,
       loaderId: loader.$$id,
-      loaderData: deps.wrapLoaderPromise(
-        pending.promise,
-        entry,
-        segmentId,
-        ctx.pathname,
-      ),
+      loaderData: pending.wrapped,
       belongsToRoute,
     };
   });
@@ -184,6 +149,15 @@ export async function resolveLoaders<TEnv>(
 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;
 }
 
 /**
@@ -295,8 +269,11 @@ export async function resolveSegment<TEnv>(
         !context.build && entry.liveHandler ? entry.liveHandler : entry.handler;
       const doneRouteHandler = track(`handler:${entry.id}`, 2);
       if (entry.loading) {
-        const result = handleHandlerResult(handler(context));
+        const result = handleHandlerResult(
+          observeHandler(entry.id, handler, context),
+        );
         if (result instanceof Promise) {
+          warnOnStreamedResponse(result, entry.id);
           result.finally(doneRouteHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
             segmentId: entry.shortCode,
@@ -316,7 +293,9 @@ export async function resolveSegment<TEnv>(
           component = result;
         }
       } else {
-        component = handleHandlerResult(await handler(context));
+        component = handleHandlerResult(
+          await observeHandler(entry.id, handler, context),
+        );
         doneRouteHandler();
       }
     }
@@ -541,7 +520,9 @@ export async function resolveParallelEntry<TEnv>(
         parallelEntry.loading !== undefined && parallelEntry.loading !== false;
       if (hasLoadingFallback) {
         const result =
-          typeof handler === "function" ? handler(context) : handler;
+          typeof handler === "function"
+            ? observeHandler(`${parallelEntry.id}.${slot}`, handler, context)
+            : handler;
         if (result instanceof Promise) {
           result.finally(doneParallelHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
@@ -563,7 +544,13 @@ export async function resolveParallelEntry<TEnv>(
         }
       } else {
         component =
-          typeof handler === "function" ? await handler(context) : handler;
+          typeof handler === "function"
+            ? await observeHandler(
+                `${parallelEntry.id}.${slot}`,
+                handler,
+                context,
+              )
+            : handler;
         doneParallelHandler();
       }
     }
@@ -667,6 +654,7 @@ export async function resolveAllSegments<TEnv>(
       deps,
       { request: safeRequest, url: context.url, routeKey, telemetry },
       context.pathname,
+      options?.throwOnError,
     );
     doneEntry();
     // Deduplicate by segment ID. include() scopes can produce entries that

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

@@ -19,13 +19,48 @@ import {
 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
 // ---------------------------------------------------------------------------
@@ -52,6 +87,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 +165,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));
 }
 
 // ---------------------------------------------------------------------------
@@ -250,11 +324,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,7 +19,7 @@
  */
 
 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 { sortedRouteParams } from "../../cache/cache-key-utils.js";
@@ -57,12 +57,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}`;
 }
 
 /**
@@ -76,7 +77,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");
 }
@@ -106,6 +113,11 @@ 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,
@@ -135,19 +147,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);
-  // Loader tags are config-derived, so they are the complete set whether this is
-  // a cache hit or miss; record them every time so a document built from this
-  // loader is tagged for invalidation.
   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(
@@ -162,7 +206,7 @@ export function resolveLoaderData<TEnv>(
       getItem: (k) => store.getItem!(k),
       setItem: (k, v, o) => store.setItem!(k, v, o),
       key,
-      execute: () => originalUse(loaderEntry.loader),
+      execute: () => runMiss(loaderEntry.loader),
       serialize: (d) => codec.serializeResult(d),
       deserialize: (v) => codec.deserializeResult(v),
       storeOptions: { ttl, swr, tags },
@@ -174,17 +218,7 @@ export function resolveLoaderData<TEnv>(
     });
   })();
 
-  // 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;
 }