@rangojs/router 0.24.4 → 0.25.0

package/src/router/loader-resolution.ts

@@ -64,12 +64,15 @@ import {
 } from "./segment-resolution/prefetch-deferral.js";
 import {
   assertNonCacheableReadAllowed,
+  getLoaderReverseScope,
   isInsideLoaderScope,
+  scopeReverse,
   runInsideLoaderBodyScope,
   runInsideLoaderRun,
   isInsidePushCallbackScope,
   runInsidePushCallbackScope,
   type LoaderRunIdentity,
+  type ScopableReverse,
 } from "../server/context.js";
 import { debugLog } from "./logging.js";
 
@@ -179,6 +182,8 @@ export function wrapLoaderWithErrorHandling<T>(
   // The token is the loader's $$id (hash#export in prod, pathfrag#export in dev),
   // not a clean display name.
   const loaderName = segmentId.split(".").pop() || "unknown";
+  // Captured now: the rejection can settle outside the request's ALS frame.
+  const renderErrors = _getRequestContext()?._renderErrors;
 
   return Promise.resolve(promise)
     .then(
@@ -275,6 +280,11 @@ export function wrapLoaderWithErrorHandling<T>(
         };
       }
 
+      // The error renders in place inside a 200 as a value, which neither
+      // Flight nor Fizz reports: record it like their errors, so a writer
+      // that reads _renderErrors (the document cache) does not store it.
+      renderErrors?.push(error);
+
       // Find nearest error boundary
       const fallback = findNearestErrorBoundary(entry);
 
@@ -543,6 +553,11 @@ function createLoaderExecutor<TEnv>(
     // (runInsideLoaderScope in fresh.ts). Handler-invoked loaders are NOT
     // inside loader scope. This determines whether rendered() is allowed.
     const isDslLoader = isInsideLoaderScope();
+    // The body resolves ctx.reverse(".name") in its DSL declaration's module
+    // (a layout's / parallel's / cache()'s loader). A route's loader, and one
+    // a handler starts with ctx.use(), resolve from the route. One run per
+    // request: the first declaration to start it wins.
+    const reverseScope = getLoaderReverseScope();
 
     // Owning segment for ctx.handle() attribution, captured SYNCHRONOUSLY at
     // kickoff: segment resolution sets _currentSegmentId while resolving the
@@ -568,6 +583,7 @@ function createLoaderExecutor<TEnv>(
         InternalHandlerContext<any, TEnv>,
         | "_routeName"
         | "_responseType"
+        | "_reverseScope"
         | "_currentSegmentId"
         | "_claimLoaderPushes"
         | "_runLoaderIsolated"
@@ -648,9 +664,13 @@ function createLoaderExecutor<TEnv>(
       }) as LoaderContext["use"],
       method: "GET",
       body: undefined,
-      reverse: ctx.reverse as LoaderContext["reverse"],
+      reverse: scopeReverse(
+        ctx.reverse as ScopableReverse,
+        reverseScope,
+      ) as LoaderContext["reverse"],
       _routeName: internal._routeName,
       _responseType: internal._responseType,
+      _reverseScope: reverseScope,
       _currentSegmentId: owningSegmentId,
       _claimLoaderPushes: internal._claimLoaderPushes,
       _runLoaderIsolated: internal._runLoaderIsolated,

package/src/router/manifest.ts

@@ -11,10 +11,8 @@ import MapRootLayout from "../server/root-layout";
 import { joinPrefix } from "./pattern-matching.js";
 import type { RouteEntry } from "../types";
 import type { UrlPatterns } from "../urls";
-import {
-  isIncludeProvider,
-  resolveIncludeModule,
-} from "../urls/include-provider.js";
+import { isIncludeProvider } from "../urls/include-provider.js";
+import { resolveEntryPatterns } from "./lazy-includes.js";
 import { VERSION } from "@rangojs/router:version";
 
 // Tags an error thrown while dynamically importing an async include's module
@@ -167,6 +165,9 @@ export async function loadManifest(
     // undefined) so a prior lazy build's scope cannot leak into a later
     // non-lazy build on the same ALS-backed Store.
     Store.includeScope = lazyContext?.includeScope;
+    // Same rule for the include's tree position (hidden include names).
+    Store.scopePath = lazyContext?.scopePath;
+    Store.hiddenScopePath = lazyContext?.hiddenScopePath;
 
     const handlerExecStart = performance.now();
     const useItems = await getContext().runWithStore(
@@ -190,10 +191,7 @@ export async function loadManifest(
           // cache the resolved patterns on the entry so later renders reuse them.
           if (isIncludeProvider(entry.lazyPatterns)) {
             try {
-              entry.lazyPatterns = resolveIncludeModule(
-                await entry.lazyPatterns(),
-                entry.staticPrefix,
-              ) as unknown as UrlPatterns<any>;
+              await resolveEntryPatterns(entry);
             } catch (err) {
               // A failed dynamic import of a REAL, matched route's module is a
               // server error, not a missing route. Tag it so the outer catch

package/src/router/match-api.ts

@@ -54,10 +54,12 @@ import {
   type RouteSnapshot,
 } from "./route-snapshot.js";
 import { resolveNavigation } from "./navigation-snapshot.js";
+import { pathKey, visitorUrl } from "../server/rewrite-trail.js";
 import { withLayoutLoaderCopies } from "../client-urls/layout-loader-copies.js";
 import {
   partialDeferralMode,
   planPrefetchDeferral,
+  resolveInterceptDeferralScope,
   requestKind,
 } from "./segment-resolution/prefetch-deferral.js";
 
@@ -375,6 +377,12 @@ export async function createMatchContextForPartial<TEnv>(
   }
 
   setRequestContextPrevRouteKey(nav.effectiveFromMatch?.routeKey);
+  // Two visitor URLs can share a rewrite target, and the render may read
+  // ctx.rewrittenFrom: a move of the visitor's URL counts as a change.
+  if (reqCtx && nav.prevVisitorUrl) {
+    reqCtx._visitorMoved =
+      pathKey(visitorUrl(reqCtx, cleanUrl)) !== pathKey(nav.prevVisitorUrl);
+  }
 
   const interceptSelectorContext: InterceptSelectorContext = {
     // The source's params come from matching its URL (the intercept source
@@ -484,7 +492,6 @@ export async function createMatchContextForPartial<TEnv>(
       prefetch: kind === "prefetch",
       method: request.method,
       isAction,
-      isIntercept,
       isShellCapture: reqCtx?._shellCaptureRun === true,
     }),
     matched,
@@ -492,6 +499,9 @@ export async function createMatchContextForPartial<TEnv>(
     // What the page holds, not the copy forced above: see
     // prefetch-deferral.ts.
     held,
+    interceptResult
+      ? resolveInterceptDeferralScope(interceptResult.intercept)
+      : undefined,
   );
   (handlerContext as InternalHandlerContext<any, TEnv>)._prefetchDeferral =
     deferral;

package/src/router/match-middleware/background-revalidation.ts

@@ -230,10 +230,8 @@ export async function rerenderAndCacheRoute<TEnv>(
             handlerContext,
             true, // belongsToRoute
             undefined, // no revalidationContext: render fresh
-            // Skip intercept middleware: the foreground already ran it.
-            // Re-running it here would double its side effects, and a
-            // short-circuit Response would abort the write.
-            { skipMiddleware: true },
+            // A handler error rejects, so the failure is never cached.
+            { background: true },
           ),
         )),
       );

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

@@ -101,6 +101,7 @@ import { treeHasStreaming } from "./segment-resolution.js";
 import { loaderPins } from "../segment-resolution/loader-cache.js";
 import {
   fillSends,
+  interceptFillSkips,
   recordUse,
 } from "../segment-resolution/prefetch-deferral.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
@@ -127,6 +128,7 @@ import { ShellRecordUnavailableError } from "../../cache/shell-snapshot.js";
 import { prerenderStoreShortCircuits } from "../navigation-snapshot.js";
 import { paramsEqual } from "../params-util.js";
 import { requestHeaders } from "../../server/request-headers.js";
+import { isInterceptSegment } from "../../browser/intercept-utils.js";
 
 // Lazily initialized prerender store singleton and dynamically imported deps.
 // Dynamic imports prevent pulling in @vitejs/plugin-rsc/rsc virtual module at
@@ -207,6 +209,7 @@ async function* resolveFreshLoadersAndYield<TEnv>(
   resolveLoadersOnlyWithRevalidation: RouterContext<TEnv>["resolveLoadersOnlyWithRevalidation"],
 ): AsyncGenerator<ResolvedSegment> {
   const loaderStart = performance.now();
+  entries = entries.filter((e) => !interceptFillSkips(ctx, e.shortCode));
 
   if (ctx.isFullMatch) {
     if (resolveLoadersOnly) {
@@ -347,14 +350,8 @@ async function* yieldFromStore<TEnv>(
     !ctx.isFullMatch && !paramsEqual(ctx.matched.params, ctx.prevParams);
   const resendRouteSegments = replaceable === true && ctx.isAction;
   for (const segment of segments) {
-    if (
-      !ctx.isFullMatch &&
-      ctx.clientSegmentSet.has(segment.id) &&
-      // A stored intercept segment is re-sent, as on the runtime cache path:
-      // its loaders run (handleCacheHitIntercept), and a kept (null) one would
-      // be left out of the response with its loaders' new data.
-      !segment.namespace?.startsWith("intercept:")
-    ) {
+    if (interceptFillSkips(ctx, segment)) continue;
+    if (!ctx.isFullMatch && ctx.clientSegmentSet.has(segment.id)) {
       // A fill keeps it (fillSends); otherwise it is sent again when the
       // params changed or an action re-sends the route's own segments.
       const sends =
@@ -912,10 +909,15 @@ export function withCacheLookup<TEnv>(
     const entryRevalidateMap = canCheckSegmentRevalidation
       ? buildEntryRevalidateMap(ctx.entries)
       : undefined;
+    const searchChanged =
+      ctx.prevUrl.search !== ctx.url.search ||
+      pipelineReqCtx?._visitorMoved === true;
+    const routeParamsChanged = !paramsEqual(ctx.matched.params, ctx.prevParams);
 
     yield* liveSegments;
 
     for (const segment of cacheResult.segments) {
+      if (interceptFillSkips(ctx, segment)) continue;
       if (!ctx.clientSegmentSet.has(segment.id)) {
         if (isTraceActive()) {
           pushRevalidationTraceEntry({
@@ -932,12 +934,8 @@ export function withCacheLookup<TEnv>(
         continue;
       }
 
-      if (segment.namespace?.startsWith("intercept:")) {
-        yield segment;
-        continue;
-      }
-
-      // A fill keeps a held segment outright (fillSends).
+      // A fill keeps a held segment outright (fillSends), an intercept's
+      // included.
       if (
         fillSends(ctx.handlerContext, segment.id, ctx.clientSegmentSet) ===
         false
@@ -946,14 +944,12 @@ export function withCacheLookup<TEnv>(
         yield segment;
         continue;
       }
+      if (isInterceptSegment(segment)) {
+        yield segment;
+        continue;
+      }
 
       const entryInfo = entryRevalidateMap?.get(segment.id);
-
-      const searchChanged = ctx.prevUrl.search !== ctx.url.search;
-      const routeParamsChanged = !paramsEqual(
-        ctx.matched.params,
-        ctx.prevParams,
-      );
       const shouldDefaultRevalidate =
         (searchChanged || routeParamsChanged) &&
         (segment.type === "route" ||

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

@@ -29,7 +29,7 @@
  *         v
  *   +----------------------+    +----------------------------+
  *   | Fresh intercept?     |yes>| resolveInterceptEntry()    |
- *   | (!cacheHit or        |    | - middleware, loaders, UI  |
+ *   | (!cacheHit or        |    | - loaders, UI              |
  *   |  no intercept segs)  |    +----------------------------+
  *   +----------------------+              |
  *         | no                            v
@@ -59,7 +59,7 @@
  *
  * 1. Fresh intercept (no cache):
  *    - Full resolution of intercept entry
- *    - Resolves middleware, loaders, and component
+ *    - Resolves loaders and component
  *    - Yields all intercept segments
  *
  * 2. Cache hit with intercept:
@@ -106,6 +106,7 @@ import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 import { debugLog } from "../logging.js";
+import { isInterceptSegment } from "../../browser/intercept-utils.js";
 
 /**
  * Creates intercept resolution middleware
@@ -151,7 +152,7 @@ export function withInterceptResolution<TEnv>(
 
     if (skipInterceptResolution) {
       if (ctx.interceptResult && state.cacheHit && ctx.isIntercept) {
-        await handleCacheHitIntercept(ctx, state, segments);
+        yield* await handleCacheHitIntercept(ctx, state, segments);
       }
       if (ms) {
         ms.metrics.push({
@@ -212,77 +213,57 @@ export function withInterceptResolution<TEnv>(
   };
 }
 
+/**
+ * A cache or prerender hit that carries the intercept's slot: the slot keeps
+ * its stored component and layout, and its loaders, never stored, resolve as
+ * loader segments of it. Returns those segments for the caller to yield.
+ */
 async function handleCacheHitIntercept<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
   segments: ResolvedSegment[],
-): Promise<void> {
-  if (!ctx.interceptResult) return;
+): Promise<ResolvedSegment[]> {
+  if (!ctx.interceptResult) return [];
 
   const { resolveInterceptLoadersOnly } = getRouterContext<TEnv>();
 
   const slotName = ctx.interceptResult.intercept.slotName;
 
-  const interceptSegments = segments.filter((s) =>
-    s.namespace?.startsWith("intercept:"),
-  );
-  state.interceptSegments = interceptSegments;
-
-  if (resolveInterceptLoadersOnly) {
-    const Store = ctx.Store;
-    const freshLoaderResult = await Store.run(() =>
-      resolveInterceptLoadersOnly(
-        ctx.interceptResult!.intercept,
-        ctx.interceptResult!.entry,
-        ctx.matched.params,
-        ctx.handlerContext,
-        true, // belongsToRoute
-        {
-          clientSegmentIds: ctx.clientSegmentSet,
-          prevParams: ctx.prevParams,
-          request: ctx.request,
-          prevUrl: ctx.prevUrl,
-          nextUrl: ctx.url,
-          routeKey: ctx.routeKey,
-          actionContext: ctx.actionContext,
-          stale: ctx.stale,
-        },
-      ),
-    );
+  const cachedSlot = segments.filter(isInterceptSegment);
+  // A record stored before 0.25.0 carries the loaders' aggregate on the slot;
+  // the loader segments below replace it. Build versions hash the router's
+  // code, so only a `version` pinned across the upgrade (createRouter's or
+  // the store's) still reads one.
+  for (const slot of cachedSlot) {
+    delete slot.loaderDataPromise;
+    delete slot.loaderIds;
+  }
 
-    if (freshLoaderResult) {
-      const interceptMainSegment = interceptSegments.find(
-        (s) => s.type === "parallel" && s.slot,
-      );
-      if (interceptMainSegment) {
-        interceptMainSegment.loaderDataPromise =
-          freshLoaderResult.loaderDataPromise;
-        interceptMainSegment.loaderIds = freshLoaderResult.loaderIds;
-        debugLog(
-          "matchPartial.intercept",
-          freshLoaderResult.loaderIds.length > 0
-            ? "cache hit with fresh intercept loaders"
-            : "cache hit, every intercept loader held",
+  const loaderSegments = resolveInterceptLoadersOnly
+    ? await ctx.Store.run(() =>
+        resolveInterceptLoadersOnly(
+          ctx.interceptResult!.intercept,
+          ctx.interceptResult!.entry,
+          ctx.handlerContext,
+          true, // belongsToRoute
           {
-            routeName: ctx.localRouteName,
-            slotName,
+            clientSegmentIds: ctx.clientSegmentSet,
+            prevParams: ctx.prevParams,
+            request: ctx.request,
+            prevUrl: ctx.prevUrl,
+            nextUrl: ctx.url,
+            routeKey: ctx.routeKey,
+            actionContext: ctx.actionContext,
+            stale: ctx.stale,
           },
-        );
-      }
-    } else {
-      debugLog(
-        "matchPartial.intercept",
-        "cache hit, intercept has no loaders",
-        {
-          routeName: ctx.localRouteName,
-          slotName,
-        },
-      );
-    }
-  }
-
+        ),
+      )
+    : [];
+  const interceptSegments = [...cachedSlot, ...loaderSegments];
+  state.interceptSegments = interceptSegments;
   state.slots[slotName] = {
     active: true,
     segments: interceptSegments,
   };
+  return loaderSegments;
 }

package/src/router/match-result.ts

@@ -109,10 +109,14 @@
  */
 import type { MatchResult, ResolvedSegment } from "../types.js";
 import { isPlaceholder } from "../types/segments.js";
+import { loaderParentId } from "../browser/react/filter-segment-order.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
 import { debugLog } from "./logging.js";
 import { appendMetric } from "./metrics.js";
-import { collectInterceptTargetNames } from "./intercept-resolution.js";
+import {
+  collectInterceptTargetNames,
+  interceptSegmentIds,
+} from "./intercept-resolution.js";
 
 export async function collectSegments(
   generator: AsyncGenerator<ResolvedSegment>,
@@ -192,6 +196,25 @@ function deduplicateLoaderSegments(
   return { segments: result, removedIds };
 }
 
+/**
+ * An intercept's `matched`: the client's ids without any of the slot's (its
+ * id and every loader segment on it, another intercept's into the same slot
+ * included), then the slot's (interceptSegmentIds). One order for the
+ * prefetch, its fill, an action and a revisit: a fill whose `matched` differs
+ * from its tree's is rendered as a new tree (browser/partial-update.ts
+ * fillHoles).
+ */
+function interceptMatched(
+  clientIds: readonly string[],
+  slotIds: readonly string[],
+): string[] {
+  // loaderParentId leaves a non-loader id as it is: the slot's own id goes too.
+  return [
+    ...clientIds.filter((id) => loaderParentId(id) !== slotIds[0]),
+    ...slotIds,
+  ];
+}
+
 export function buildMatchResult<TEnv>(
   allSegments: ResolvedSegment[],
   ctx: MatchContext<TEnv>,
@@ -223,7 +246,13 @@ export function buildMatchResult<TEnv>(
   } else {
     allIds = ctx.interceptResult
       ? ctx.clientSegmentIds.length > 0
-        ? [...ctx.clientSegmentIds, ...state.interceptSegments.map((s) => s.id)]
+        ? interceptMatched(
+            ctx.clientSegmentIds,
+            interceptSegmentIds(
+              ctx.interceptResult.entry,
+              ctx.interceptResult.intercept,
+            ),
+          )
         : allSegments.map((s) => s.id)
       : [...state.matchedIds, ...state.interceptSegments.map((s) => s.id)];
 

package/src/router/middleware.ts

@@ -34,11 +34,7 @@ import { assertNonCacheableReadAllowed } from "../server/context.js";
 import { readGuardedTheme } from "../server/cookie-store.js";
 import { defineSlot, slotAccessor } from "../server/slot-accessors.js";
 import type { Theme } from "../theme/types.js";
-import {
-  isRewrite,
-  rewriteNotSupported,
-  type Rewrite,
-} from "../route-definition/rewrite.js";
+import { isRewrite, type Rewrite } from "../route-definition/rewrite.js";
 import { defineRewrittenFrom } from "../server/rewrite-trail.js";
 
 // Re-export types consumed through this module's path.
@@ -324,8 +320,8 @@ export function createMiddlewareContext<TEnv>(
     waitUntil: reqCtx ? reqCtx.waitUntil.bind(reqCtx) : fireAndForgetWaitUntil,
 
     get: ((keyOrVar: any) => {
-      // "use cache" only: intercept middleware runs inside a cache()
-      // subtree's render scope, and a middleware read is never cached there.
+      // "use cache" only: middleware runs before any cache() subtree
+      // renders, so the cache() read guard never applies to it.
       if (
         isNonCacheable(variables, keyOrVar) &&
         getCacheExecScope() !== undefined
@@ -517,13 +513,11 @@ function mergeReqCtxStub(
 // Clone `base` with stub headers merged into a fresh Headers (the clone keeps
 // the body mutable for post-next() modifications). Set-Cookie is always
 // appended; other headers obey stubOverridesNonCookie (see mergeStubHeaders).
-// mergeReqCtx folds in RequestContext stub cookies/headers; the intercept
-// short-circuit path passes false (its reqCtx headers are not merged here),
-// which is the one deliberate divergence between the call sites.
+// RequestContext stub cookies/headers are folded in last.
 function mergeResponse(
   base: Response,
   stub: Headers,
-  opts: { stubOverridesNonCookie: boolean; mergeReqCtx: boolean },
+  opts: { stubOverridesNonCookie: boolean },
 ): Response {
   const mergedHeaders = new Headers(base.headers);
   // The reserved external-redirect marker is never a trust signal and must never
@@ -532,9 +526,7 @@ function mergeResponse(
   // guard would not touch) to the client. The opt-in is the out-of-band brand.
   mergedHeaders.delete(EXTERNAL_REDIRECT_MARKER);
   mergeStubHeaders(mergedHeaders, stub, opts.stubOverridesNonCookie);
-  if (opts.mergeReqCtx) {
-    mergeReqCtxStub(mergedHeaders, _getRequestContext());
-  }
+  mergeReqCtxStub(mergedHeaders, _getRequestContext());
   const merged = new Response(base.body, {
     status: base.status,
     statusText: base.statusText,
@@ -597,7 +589,6 @@ export async function executeMiddleware<TEnv>(
       // and reqCtx stub headers are merged in.
       responseHolder.response = mergeResponse(response, stubResponse.headers, {
         stubOverridesNonCookie: true,
-        mergeReqCtx: true,
       });
 
       return responseHolder.response;
@@ -740,7 +731,6 @@ export async function executeMiddleware<TEnv>(
       // (stubOverridesNonCookie=false); reqCtx stub headers still merge in.
       const merged = mergeResponse(result, stubResponse.headers, {
         stubOverridesNonCookie: false,
-        mergeReqCtx: true,
       });
       responseHolder.response = merged;
       return merged;
@@ -796,137 +786,6 @@ export async function executeMiddleware<TEnv>(
   return finalResponse;
 }
 
-/**
- * Execute middleware for intercepts (simplified execution)
- *
- * Intercepts use a shared stubResponse from the request context. This function:
- * - Runs middleware in sequence with a simple next() chain
- * - Returns Response if any middleware short-circuits (returns OR throws a Response, or redirects, BEFORE next())
- * - Returns null if all middleware calls next() - headers set after next() remain on stubResponse
- *
- * @param middlewares - Array of middleware functions
- * @param request - Original request
- * @param env - Environment bindings
- * @param params - Route params
- * @param variables - Shared variables object
- * @param stubResponse - Response from request context for collecting headers/cookies
- */
-export async function executeInterceptMiddleware<TEnv>(
-  middlewares: MiddlewareFn<TEnv>[],
-  request: Request,
-  env: TEnv,
-  params: Record<string, string>,
-  variables: Record<string, any>,
-  stubResponse: Response,
-  reverse?: (
-    name: string,
-    params?: Record<string, string>,
-    search?: Record<string, unknown>,
-  ) => string,
-): Promise<Response | null> {
-  if (middlewares.length === 0) {
-    return null;
-  }
-
-  let index = 0;
-  let earlyResponse: Response | null = null;
-
-  // Use provided stubResponse - headers/cookies set here will be merged by the caller
-  const responseHolder: ResponseHolder = { response: stubResponse };
-
-  const next = async (): Promise<Response> => {
-    if (index >= middlewares.length || earlyResponse) {
-      return stubResponse;
-    }
-
-    const ordinal = index;
-    const middleware = middlewares[index++];
-    const ctx = createMiddlewareContext(
-      request,
-      env,
-      params,
-      variables,
-      responseHolder,
-      reverse,
-    );
-
-    let nextCalled = false;
-    const guardedNext = (): Promise<Response> => {
-      if (nextCalled) {
-        throw new Error(
-          `[@rangojs/router] Intercept middleware called next() more than once.`,
-        );
-      }
-      nextCalled = true;
-      return next();
-    };
-
-    // Span-wrap each intercept middleware as rango.middleware (metric:false —
-    // intercept runs inside the render phase already metered by render:total, so
-    // it contributes a span but no separate perf metric). Bare MiddlewareFns
-    // have no pattern, so the label is scoped to "*" like a pattern-less entry.
-    const label = getMiddlewareMetricLabel(
-      { handler: middleware, pattern: null } as MiddlewareEntry<TEnv>,
-      ordinal,
-    );
-
-    const result: Response | void = await observePhase(
-      PHASES.middleware(label),
-      async () => {
-        try {
-          return await middleware(ctx, guardedNext);
-        } catch (error) {
-          // Thrown Response is short-circuit control flow, parity with the
-          // explicit-return path below. Absorb it INSIDE the span so the tracing
-          // runner settles rango.middleware as success, not STATUS_ERROR (same
-          // reasoning as executeMiddleware's main chain). Real errors propagate.
-          if (error instanceof Response) return error;
-          if (isRewrite(error)) throw rewriteNotSupported(error, "intercept");
-          throw error;
-        }
-      },
-    );
-    if (isRewrite(result)) throw returnedRewriteError(middleware);
-
-    if (result instanceof Response) {
-      earlyResponse = result;
-      return result;
-    }
-
-    return stubResponse;
-  };
-
-  await next();
-
-  // Return early response if middleware short-circuited (returned Response BEFORE next())
-  if (earlyResponse) {
-    // Capture in const for TypeScript narrowing (earlyResponse is `let` which loses narrowing in callbacks)
-    const response: Response = earlyResponse;
-
-    // Merge any headers/cookies set on stub into the early response
-    let hasStubHeaders = false;
-    stubResponse.headers.forEach(() => {
-      hasStubHeaders = true;
-    });
-
-    if (hasStubHeaders) {
-      // Only fill in missing headers — the returned Response's explicit headers
-      // take precedence (stubOverridesNonCookie=false), matching executeMiddleware.
-      // mergeReqCtx=false: the intercept path deliberately does NOT merge reqCtx
-      // stub headers here (pinned by intercept-middleware-headers.test.ts).
-      return mergeResponse(response, stubResponse.headers, {
-        stubOverridesNonCookie: false,
-        mergeReqCtx: false,
-      });
-    }
-    return response;
-  }
-
-  // All middleware completed without short-circuit
-  // Headers/cookies set on stubResponse will be merged into the final response by the caller
-  return null;
-}
-
 /**
  * Execute middleware chain for loaders (simpler signature)
  *