@rangojs/router 0.23.0 → 0.24.1

package/src/router/intercept-resolution.ts

@@ -262,13 +262,23 @@ export async function resolveInterceptEntry<TEnv>(
 
   latchPprHeaderScopeForInterceptTarget(interceptEntry);
 
+  // The intercept segment's id: the tag scope its handler and layout record in
+  // (#957, cache-tag.ts runInSegmentTagScope) and the owner of its handler's
+  // and loaders' handle pushes, pinned before the loader kickoffs as
+  // fresh.ts/revalidation.ts pin theirs (createLoaderExecutor captures it at
+  // kickoff; a handler's ctx.use(Handle) reads it when called).
+  const slotSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
+  (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+    slotSegmentId;
+  const hasLoaders = interceptEntry.loader.length > 0;
+
   const loaderPromises: Promise<any>[] = [];
   const loaderIds: string[] = [];
 
   for (let i = 0; i < interceptEntry.loader.length; i++) {
     const loaderEntry = interceptEntry.loader[i];
     const { loader, revalidate: loaderRevalidateFns } = loaderEntry;
-    const segmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}D${i}.${loader.$$id}`;
+    const segmentId = `${slotSegmentId}D${i}.${loader.$$id}`;
 
     if (revalidationContext) {
       const {
@@ -282,8 +292,7 @@ export async function resolveInterceptEntry<TEnv>(
         stale,
       } = revalidationContext;
 
-      const interceptSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
-      if (clientSegmentIds.has(interceptSegmentId)) {
+      if (clientSegmentIds.has(slotSegmentId)) {
         const dummySegment: ResolvedSegment = {
           id: segmentId,
           namespace: `intercept:${interceptEntry.routeName}`,
@@ -345,9 +354,6 @@ export async function resolveInterceptEntry<TEnv>(
     );
   }
 
-  // The intercept segment's id, and the tag scope its handler and layout
-  // record in (#957, cache-tag.ts runInSegmentTagScope).
-  const slotSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
   let handlerResult: ReactNode;
   try {
     const handler = interceptEntry.handler;
@@ -399,7 +405,7 @@ export async function resolveInterceptEntry<TEnv>(
   const streamedComponent = (promise: Promise<unknown>): ReactNode =>
     trackStreamedHandler(deps, promise, {
       boundaryEntry: parentEntry,
-      segmentId: `${parentEntry.shortCode}.${interceptEntry.slotName}`,
+      segmentId: slotSegmentId,
       segmentType: "parallel",
       context,
       routeKey: interceptEntry.routeName,
@@ -442,6 +448,13 @@ export async function resolveInterceptEntry<TEnv>(
     }
   }
 
+  // The aggregate lists the loaders that ran; empty, not absent, when the
+  // client holds the slot and all skipped. Absent replaces the client's
+  // aggregate, empty merges into it (merge-segment-loaders.ts).
+  if (hasLoaders && loaderPromises.length === 0) {
+    loaderDataPromise = [];
+  }
+
   const interceptSegment = {
     id: slotSegmentId,
     namespace: `intercept:${interceptEntry.routeName}`,
@@ -455,7 +468,7 @@ export async function resolveInterceptEntry<TEnv>(
     belongsToRoute,
     parallelName: `intercept:${interceptEntry.routeName}.${interceptEntry.slotName}`,
     loaderDataPromise,
-    loaderIds: loaderIds.length > 0 ? loaderIds : undefined,
+    loaderIds: hasLoaders ? loaderIds : undefined,
   };
   segments.push(interceptSegment);
 
@@ -498,6 +511,10 @@ export async function resolveInterceptLoadersOnly<TEnv>(
 
   latchPprHeaderScopeForInterceptTarget(interceptEntry);
 
+  // The loaders' handle push owner, as in resolveInterceptEntry.
+  const slotSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
+  (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+    slotSegmentId;
   const loaderPromises: Promise<any>[] = [];
   const loaderIds: string[] = [];
 
@@ -515,10 +532,9 @@ export async function resolveInterceptLoadersOnly<TEnv>(
   for (let i = 0; i < interceptEntry.loader.length; i++) {
     const loaderEntry = interceptEntry.loader[i];
     const { loader, revalidate: loaderRevalidateFns } = loaderEntry;
-    const segmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}D${i}.${loader.$$id}`;
+    const segmentId = `${slotSegmentId}D${i}.${loader.$$id}`;
 
-    const interceptSegmentId = `${parentEntry.shortCode}.${interceptEntry.slotName}`;
-    if (clientSegmentIds.has(interceptSegmentId)) {
+    if (clientSegmentIds.has(slotSegmentId)) {
       const dummySegment: ResolvedSegment = {
         id: segmentId,
         namespace: `intercept:${interceptEntry.routeName}`,
@@ -581,8 +597,9 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     );
   }
 
+  // Every loader held: the empty aggregate (see resolveInterceptEntry).
   if (loaderPromises.length === 0) {
-    return null;
+    return { loaderDataPromise: [], loaderIds };
   }
 
   // Match fresh-path semantics: only defer (no await) when loading is truthy.

package/src/router/internal-params.ts

@@ -0,0 +1,16 @@
+/**
+ * Strip internal _rsc* query params from a URL.
+ * Returns a new URL with only user-facing params.
+ *
+ * A leaf, so request-scoped modules (server/rewrite-trail.ts) can strip
+ * without importing the handler context's graph.
+ */
+export function stripInternalParams(url: URL): URL {
+  const clean = new URL(url);
+  for (const key of [...clean.searchParams.keys()]) {
+    if (key.startsWith("_rsc")) {
+      clean.searchParams.delete(key);
+    }
+  }
+  return clean;
+}

package/src/router/loader-resolution.ts

@@ -55,6 +55,7 @@ import {
 } from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { defineRewrittenFrom } from "../server/rewrite-trail.js";
 import {
   firstUnitCandidate,
   loaderOwner,
@@ -777,6 +778,7 @@ function createLoaderExecutor<TEnv>(
         return renderedPromise;
       },
     };
+    defineRewrittenFrom(loaderCtx, reqCtxRef ?? _getRequestContext());
     (loaderCtx as any)[NOCACHE_SYMBOL] = true;
 
     // Meter this loader once via observePhase (loader:<id> perf metric +

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

@@ -109,11 +109,12 @@ import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import { getContext } from "../../server/context.js";
 import { executionStart } from "../../cache/tag-invalidation.js";
 import {
+  bindRes,
   createRequestContext,
   runWithRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
-import { isFillRequest } from "../segment-resolution/prefetch-deferral.js";
+import { recordUse } from "../segment-resolution/prefetch-deferral.js";
 
 /**
  * Re-render a cached route in the background and write it with
@@ -166,9 +167,7 @@ export async function rerenderAndCacheRoute<TEnv>(
     themeConfig: requestCtx._themeConfig,
   });
   const renderCtx: RequestContext<TEnv> = Object.assign(
-    Object.create(requestCtx, {
-      res: Object.getOwnPropertyDescriptor(sink, "res")!,
-    }),
+    Object.create(requestCtx),
     {
       _handleStore: handleStore,
       _metricsStore: undefined,
@@ -185,6 +184,8 @@ export async function rerenderAndCacheRoute<TEnv>(
       _setKeepCacheDirective: sink._setKeepCacheDirective,
     },
   );
+  // ctx.res reads the sink's stub, not the live request's.
+  bindRes(renderCtx, () => sink.res);
   const store = Object.assign(Object.create(ctx.Store), { metrics: undefined });
   const runInStore = <T>(fn: () => T): T =>
     getContext().runWithStore(
@@ -282,15 +283,16 @@ export function withBackgroundRevalidation<TEnv>(
     // Only trigger background revalidation if:
     // 1. Cache was hit and stale
     // 2. Cache scope exists
-    // 3. The request is not a fill (prefetch: false). A fill runs no handler
-    //    of a segment the client holds, and the re-render runs every handler
-    //    of the route. The record stays stale until a request that reads it
-    //    arrives: the prefetch before the fill already was one.
+    // 3. The request may refresh the record (RecordUse.refresh): a fill may
+    //    not (prefetch: false). It runs no handler of a segment the client
+    //    holds, and the re-render runs every handler of the route. The record
+    //    stays stale until a request that reads it arrives: the prefetch
+    //    before the fill already was one.
     if (
       !state.shouldRevalidate ||
       !state.cacheHit ||
       !ctx.cacheScope ||
-      isFillRequest(ctx.handlerContext)
+      !recordUse(ctx.handlerContext).refresh
     ) {
       return;
     }

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

@@ -100,8 +100,8 @@ import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
 import { treeHasStreaming } from "./segment-resolution.js";
 import { loaderPins } from "../segment-resolution/loader-cache.js";
 import {
-  defersAboveRecord,
-  isFillRequest,
+  fillSends,
+  recordUse,
 } from "../segment-resolution/prefetch-deferral.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
 import {
@@ -346,20 +346,23 @@ async function* yieldFromStore<TEnv>(
   const paramsChanged =
     !ctx.isFullMatch && !paramsEqual(ctx.matched.params, ctx.prevParams);
   const resendRouteSegments = replaceable === true && ctx.isAction;
-  // A fill (prefetch-deferral.ts) keeps every segment the client holds.
-  const fill = isFillRequest(ctx.handlerContext);
   for (const segment of segments) {
     if (
       !ctx.isFullMatch &&
       ctx.clientSegmentSet.has(segment.id) &&
-      (fill ||
-        (!paramsChanged &&
-          !(
-            resendRouteSegments &&
-            (segment.type === "route" || segment.belongsToRoute === true)
-          )))
+      // 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:")
     ) {
-      keepClientSegment(segment);
+      // 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 =
+        fillSends(ctx.handlerContext, segment.id, ctx.clientSegmentSet) ??
+        (paramsChanged ||
+          (resendRouteSegments &&
+            (segment.type === "route" || segment.belongsToRoute === true)));
+      if (!sends) keepClientSegment(segment);
     }
     yield segment;
   }
@@ -739,7 +742,7 @@ export function withCacheLookup<TEnv>(
     if (
       ctx.isAction ||
       !ctx.cacheScope?.enabled ||
-      defersAboveRecord(ctx.handlerContext)
+      !recordUse(ctx.handlerContext).read
     ) {
       yield* source;
       if (ms) {
@@ -912,7 +915,6 @@ export function withCacheLookup<TEnv>(
 
     yield* liveSegments;
 
-    const fill = isFillRequest(ctx.handlerContext);
     for (const segment of cacheResult.segments) {
       if (!ctx.clientSegmentSet.has(segment.id)) {
         if (isTraceActive()) {
@@ -935,8 +937,11 @@ export function withCacheLookup<TEnv>(
         continue;
       }
 
-      // A fill (prefetch-deferral.ts) skips a held segment outright.
-      if (fill) {
+      // A fill keeps a held segment outright (fillSends).
+      if (
+        fillSends(ctx.handlerContext, segment.id, ctx.clientSegmentSet) ===
+        false
+      ) {
         keepClientSegment(segment);
         yield segment;
         continue;

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

@@ -114,10 +114,7 @@ import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 import { rerenderAndCacheRoute } from "./background-revalidation.js";
-import {
-  defersAboveRecord,
-  isFillRequest,
-} from "../segment-resolution/prefetch-deferral.js";
+import { recordUse } from "../segment-resolution/prefetch-deferral.js";
 
 /**
  * Creates cache store middleware
@@ -161,7 +158,7 @@ export function withCacheStore<TEnv>(
       ctx.isAction ||
       state.cacheHit ||
       ctx.request.method !== "GET" ||
-      defersAboveRecord(ctx.handlerContext)
+      !recordUse(ctx.handlerContext).write
     ) {
       if (ms) {
         ms.metrics.push({
@@ -200,13 +197,14 @@ export function withCacheStore<TEnv>(
         cacheScope.covers(s.id, s.namespace),
     );
 
-    // A fill renders what the client is missing and nothing else. When that
-    // is everything the record covers, it writes like any other request.
-    // When the client holds part of it, the write would be partial, and the
-    // proactive re-render below would run handlers a fill must not run. The
-    // stale-hit refresh skips a fill for the same reason
+    // The client holds part of what the record covers, so writing it takes
+    // the proactive re-render below, which a request that may not refresh
+    // the record (RecordUse.refresh) does not start. That is a fill: it
+    // renders what the client is missing and nothing else, and writes like
+    // any other request only when that is everything the record covers. The
+    // stale-hit refresh skips it for the same reason
     // (withBackgroundRevalidation).
-    if (hasNullComponents && isFillRequest(ctx.handlerContext)) return;
+    if (hasNullComponents && !recordUse(ctx.handlerContext).refresh) return;
 
     const requestCtx = getRequestContext();
     if (!requestCtx) return;

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

@@ -260,7 +260,9 @@ async function handleCacheHitIntercept<TEnv>(
         interceptMainSegment.loaderIds = freshLoaderResult.loaderIds;
         debugLog(
           "matchPartial.intercept",
-          "cache hit with fresh intercept loaders",
+          freshLoaderResult.loaderIds.length > 0
+            ? "cache hit with fresh intercept loaders"
+            : "cache hit, every intercept loader held",
           {
             routeName: ctx.localRouteName,
             slotName,
@@ -270,7 +272,7 @@ async function handleCacheHitIntercept<TEnv>(
     } else {
       debugLog(
         "matchPartial.intercept",
-        "cache hit without intercept loader revalidation",
+        "cache hit, intercept has no loaders",
         {
           routeName: ctx.localRouteName,
           slotName,

package/src/router/middleware-types.ts

@@ -8,6 +8,7 @@ import type { GlobalReverseFunction } from "../reverse.js";
 import type { Theme } from "../theme/types.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import type { RequestScope } from "../types/request-scope.js";
+import type { Rewrite } from "../route-definition/rewrite.js";
 
 type GetVariableFn = {
   <T>(contextVar: ContextVar<T>): T | undefined;
@@ -81,6 +82,21 @@ export interface MiddlewareContext<
 
   /** Global route names only; see {@link GlobalReverseFunction}. */
   reverse: GlobalReverseFunction<DefaultReverseRouteMap>;
+
+  /**
+   * Whether `value` is a `rewrite()` thrown downstream. A middleware that
+   * wraps `next()` in try/catch rethrows it, so the request re-dispatches:
+   *
+   * ```ts
+   * try {
+   *   return await next();
+   * } catch (error) {
+   *   if (ctx.isRewrite(error)) throw error;
+   *   return new Response("Error", { status: 500 });
+   * }
+   * ```
+   */
+  isRewrite(value: unknown): value is Rewrite;
 }
 
 export type MiddlewareFn<

package/src/router/middleware.ts

@@ -32,7 +32,14 @@ import {
 import { getCacheExecScope } from "../cache/cache-exec-scope.js";
 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 { defineRewrittenFrom } from "../server/rewrite-trail.js";
 
 // Re-export types consumed through this module's path.
 export type {
@@ -43,19 +50,54 @@ export type {
 } from "./middleware-types.js";
 
 /**
- * Middleware ctx.theme: the visitor's theme cookie, guarded like the handler
- * ctx.theme and cookies() (#971, #946), so a read inside a "use cache"
- * function the middleware calls throws. Non-enumerable like the handler and
- * request-context getters: a spread of the ctx (inside a "use cache"
- * function, say) does not read it. One shared descriptor, so every ctx keeps
- * the same property shape.
+ * The middleware ctx's accessors: shared descriptors (slot-accessors.ts).
+ * routeName, _routeName, theme and setTheme read only the request context;
+ * headers calls the per-ctx closure in HEADERS_SLOT.
  */
-const MIDDLEWARE_THEME_DESCRIPTOR: PropertyDescriptor = {
-  get(): Theme | undefined {
-    return readGuardedTheme(_getRequestContext(), "ctx.theme");
+const HEADERS_SLOT: unique symbol = Symbol("rango.middlewareContext.headers");
+
+const MIDDLEWARE_ACCESSORS: Record<
+  "routeName" | "_routeName" | "headers" | "setTheme" | "theme",
+  PropertyDescriptor
+> = {
+  // Re-derived from the request context on each access, so global middleware
+  // sees the matched route name after await next().
+  routeName: {
+    get(): string | undefined {
+      const raw = _getRequestContext()?._routeName;
+      return raw && !isAutoGeneratedRouteName(raw) ? raw : undefined;
+    },
+    enumerable: true,
+    configurable: true,
+  },
+  // The matched route key, auto-generated names included (the handler ctx's
+  // _routeName); undefined before routing.
+  _routeName: {
+    get(): string | undefined {
+      return _getRequestContext()?._routeName;
+    },
+    enumerable: true,
+    configurable: true,
+  },
+  headers: slotAccessor(HEADERS_SLOT, true),
+  setTheme: {
+    get(): MiddlewareContext<unknown>["setTheme"] {
+      return _getRequestContext()?.setTheme;
+    },
+    enumerable: true,
+    configurable: true,
+  },
+  // The visitor's theme cookie, guarded like the handler ctx.theme and
+  // cookies() (#971, #946), so a read inside a "use cache" function the
+  // middleware calls throws. Non-enumerable like the handler and
+  // request-context getters: a spread of the ctx does not read it.
+  theme: {
+    get(): Theme | undefined {
+      return readGuardedTheme(_getRequestContext(), "ctx.theme");
+    },
+    enumerable: false,
+    configurable: true,
   },
-  enumerable: false,
-  configurable: true,
 };
 
 const MIDDLEWARE_METRIC_DEPTH = 1;
@@ -252,15 +294,20 @@ export function createMiddlewareContext<TEnv>(
 
   // reqCtx captured once above: the request-scoped platform fields
   // (originalUrl, executionContext, waitUntil) are immutable per request,
-  // so snapshotting beats re-reading ALS on every access. The lazy getters
-  // below (routeName, theme, setTheme) stay lazy because those can change
-  // during `await next()`.
+  // so snapshotting beats re-reading ALS on every access. The accessors
+  // (routeName, _routeName, theme, setTheme: MIDDLEWARE_ACCESSORS) read the
+  // request context on each access because those can change during
+  // `await next()`.
   //
   // Request-scoped like the handler ctx (issue #940): the NOCACHE_SYMBOL brand
   // below makes a "use cache" function taking it key by host, _routeName,
   // pathname, params and search; set/header/headers throw inside that
   // function, and non-cacheable get reads run the shared guard.
-  const ctx: MiddlewareContext<TEnv> & { readonly _routeName?: string } = {
+  // Data members only: the accessors are MIDDLEWARE_ACCESSORS.
+  const fields: Omit<
+    MiddlewareContext<TEnv>,
+    "routeName" | "headers" | "setTheme"
+  > = {
     request,
     url,
     originalUrl: reqCtx?.originalUrl ?? new URL(request.url),
@@ -269,39 +316,12 @@ export function createMiddlewareContext<TEnv>(
     env: env as MiddlewareContext<TEnv>["env"],
     params,
     build: reqCtx?.build ?? false,
+    isRewrite,
     dynamic(): void {
       reqCtx?.dynamic();
     },
     executionContext: reqCtx?.executionContext,
     waitUntil: reqCtx ? reqCtx.waitUntil.bind(reqCtx) : fireAndForgetWaitUntil,
-    // Getter: re-derives from request context on each access so that global
-    // middleware sees the matched route name after await next().
-    get routeName(): MiddlewareContext<TEnv>["routeName"] {
-      const reqCtx = _getRequestContext();
-      const raw = reqCtx?._routeName;
-      return (
-        raw && !isAutoGeneratedRouteName(raw) ? raw : undefined
-      ) as MiddlewareContext<TEnv>["routeName"];
-    },
-
-    // The matched route key, auto-generated names included (the handler
-    // ctx's _routeName); undefined before routing.
-    get _routeName(): string | undefined {
-      return _getRequestContext()?._routeName;
-    },
-
-    // Guarded only inside a "use cache" body: the stamp covers a miss that
-    // took this ctx as an argument, the exec scope a stale refresh (which does
-    // not stamp its args, cache-runtime.ts). A write there is lost on a hit.
-    get headers(): Headers {
-      const headers = getResponse().headers;
-      return (INSIDE_CACHE_EXEC as symbol) in ctx ||
-        getCacheExecScope() !== undefined
-        ? guardHeaderWrites(headers, () =>
-            assertNotInsideCacheExec(ctx, "headers"),
-          )
-        : headers;
-    },
 
     get: ((keyOrVar: any) => {
       // "use cache" only: intercept middleware runs inside a cache()
@@ -338,11 +358,6 @@ export function createMiddlewareContext<TEnv>(
       responseHolder.response.headers.set(name, value);
     },
 
-    // theme: MIDDLEWARE_THEME_DESCRIPTOR, defined after this literal.
-    get setTheme(): MiddlewareContext<TEnv>["setTheme"] {
-      return _getRequestContext()?.setTheme;
-    },
-
     setLocationState(entries) {
       const reqCtx = _getRequestContext();
       if (!reqCtx) {
@@ -376,11 +391,46 @@ export function createMiddlewareContext<TEnv>(
       }
     },
   };
-  Object.defineProperty(ctx, "theme", MIDDLEWARE_THEME_DESCRIPTOR);
+  const ctx = fields as MiddlewareContext<TEnv>;
+  // Guarded only inside a "use cache" body: the stamp covers a miss that
+  // took this ctx as an argument, the exec scope a stale refresh (which does
+  // not stamp its args, cache-runtime.ts). A write there is lost on a hit.
+  defineSlot(ctx, HEADERS_SLOT, (): Headers => {
+    const headers = getResponse().headers;
+    return (INSIDE_CACHE_EXEC as symbol) in ctx ||
+      getCacheExecScope() !== undefined
+      ? guardHeaderWrites(headers, () =>
+          assertNotInsideCacheExec(ctx, "headers"),
+        )
+      : headers;
+  });
+  Object.defineProperty(ctx, "routeName", MIDDLEWARE_ACCESSORS.routeName);
+  Object.defineProperty(ctx, "_routeName", MIDDLEWARE_ACCESSORS._routeName);
+  Object.defineProperty(ctx, "headers", MIDDLEWARE_ACCESSORS.headers);
+  Object.defineProperty(ctx, "setTheme", MIDDLEWARE_ACCESSORS.setTheme);
+  Object.defineProperty(ctx, "theme", MIDDLEWARE_ACCESSORS.theme);
+  defineRewrittenFrom(ctx, reqCtx, "middleware");
   (ctx as any)[NOCACHE_SYMBOL] = true;
   return ctx;
 }
 
+/** A middleware threw a Rewrite after its next() started the downstream. */
+function rewriteAfterNextError(handler: Function, rewrite: Rewrite): Error {
+  return new Error(
+    `Middleware "${handler.name || "(anonymous)"}" threw rewrite() after ` +
+      `calling next(). Throw rewrite() before await next().`,
+    { cause: rewrite },
+  );
+}
+
+/** A middleware returned a Rewrite: only a thrown one re-dispatches. */
+function returnedRewriteError(handler: Function): Error {
+  return new Error(
+    `Middleware "${handler.name || "(anonymous)"}" returned a rewrite(). ` +
+      `Throw it instead: \`throw rewrite(...)\`, don't return it.`,
+  );
+}
+
 /**
  * Match middleware entries against a pathname
  * Returns entries that match, with extracted params
@@ -584,6 +634,12 @@ export async function executeMiddleware<TEnv>(
     // downstream chain and overwrite responseHolder.response.
     let nextPromise: Promise<Response> | null = null;
     let nextResolvedAt: number | undefined;
+    // Whether next() rejected with a Rewrite: only then did nothing render
+    // (a downstream middleware rewrote before its own next()). Any other
+    // rejection can come after the route rendered (a route middleware that
+    // throws after its next(), the render's own error), so a rewrite thrown
+    // after it would re-dispatch onto the used handle store.
+    let nextRejectedWithRewrite = false;
     const wrappedNext = (): Promise<Response> => {
       if (nextPromise) {
         throw new Error(
@@ -599,6 +655,7 @@ export async function executeMiddleware<TEnv>(
         },
         (err) => {
           nextResolvedAt = performance.now();
+          nextRejectedWithRewrite = isRewrite(err);
           throw err;
         },
       );
@@ -612,6 +669,11 @@ export async function executeMiddleware<TEnv>(
     // middleware-over-middleware and the core handler underneath. Pass-through
     // when neither surface is active.
     let result: Response | void;
+    // A thrown rewrite() is control flow like a thrown Response: held past
+    // the span (which settles as success) and rethrown below, so it unwinds
+    // to the dispatcher (rsc/handler.ts) with no further code of this
+    // middleware run.
+    let rewrite: Rewrite | undefined;
     try {
       result = await observePhase(PHASES.middleware(metricLabel), async () => {
         try {
@@ -627,6 +689,10 @@ export async function executeMiddleware<TEnv>(
           // this convention (segment-resolution/helpers.ts keeps result handling
           // outside the span). Real errors propagate past the span.
           if (error instanceof Response) return error;
+          if (isRewrite(error)) {
+            rewrite = error;
+            return undefined;
+          }
           throw error;
         }
       });
@@ -635,6 +701,16 @@ export async function executeMiddleware<TEnv>(
       // error paths (idempotent guard in finishMiddleware).
       finishMiddleware();
     }
+    // A rewrite after this middleware's next() started the downstream chain
+    // (resolved, still running, or failed) would leave that render running
+    // against the context the next pass moves, or re-dispatch onto what it
+    // already pushed, and drop the response it built. Only a rewrite after
+    // next() rejected with a Rewrite (nothing rendered) unwinds.
+    if (rewrite && nextPromise && !nextRejectedWithRewrite) {
+      throw rewriteAfterNextError(entry.handler, rewrite);
+    }
+    if (rewrite) throw rewrite;
+    if (isRewrite(result)) throw returnedRewriteError(entry.handler);
 
     // Record post-next() processing time when middleware did work after
     // the downstream chain resolved (e.g. adding headers, logging).
@@ -805,10 +881,12 @@ export async function executeInterceptMiddleware<TEnv>(
           // 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;

package/src/router/revalidation.ts

@@ -20,7 +20,7 @@ import { makeIsAction } from "./is-action.js";
 /**
  * Options for revalidation evaluation
  */
-interface EvaluateRevalidationOptions<TEnv> {
+export interface EvaluateRevalidationOptions<TEnv> {
   /** Current segment to evaluate */
   segment: ResolvedSegment;
   /** Previous route params (from route match, not segment) */