@rangojs/router 0.0.0-experimental.fb6e2f40 → 0.0.0-experimental.fce7fbd1

package/src/static-handler.ts

@@ -96,7 +96,7 @@ export function Static<TParams extends Record<string, any>>(
 
   if (!id) {
     throw new Error(
-      "[rsc-router] Static: missing $$id. " +
+      "[rango] Static: missing $$id. " +
         "Ensure the exposeInternalIds Vite plugin is configured.",
     );
   }

package/src/testing/cache-status.ts

@@ -0,0 +1,166 @@
+/**
+ * Cache-status testing primitives for @rangojs/router consumers.
+ *
+ * Two complementary paths, both DEVELOPMENT/TEST ONLY:
+ *
+ * 1. Header path — `parseCacheHeader` / `assertCacheStatus` read the
+ *    `X-Rango-Cache` response header. The header is emitted only when the
+ *    router's debug cache signal gate is on (the `debugCacheSignal` option or
+ *    `RANGO_TEST_SIGNALS=1`). With the gate off there is no header and these
+ *    helpers throw a clear "header missing" error.
+ *
+ * 2. Telemetry path — `createCacheSink` returns a `{ sink, events }` pair the
+ *    consumer wires via `createRouter({ telemetry: sink })`. This has ZERO
+ *    production surface: no header, just structured `cache.decision` events
+ *    (which carry the same coarse `segments` cache signal).
+ *
+ * v1 cache status is COARSE (route-level): the router reports a single entry
+ * keyed by the route key (the route NAME), not per individual segment.
+ *
+ * Import path: from a Vitest unit/integration test use `@rangojs/router/testing`;
+ * from a Playwright e2e use `@rangojs/router/testing/e2e` (the barrel pulls a
+ * build-only virtual that does not resolve in a plain Playwright runner).
+ */
+
+import type {
+  CacheDecisionEvent,
+  CacheSegmentStatus,
+  TelemetryEvent,
+  TelemetrySink,
+} from "../router/telemetry.js";
+
+const CACHE_HEADER = "X-Rango-Cache";
+
+/** Expected cache status passed to assertCacheStatus. */
+export type ExpectedCacheStatus = CacheSegmentStatus;
+
+/** A target carrying response headers (a Response or a `{ headers }` object). */
+export type CacheStatusTarget = Response | { headers: Headers };
+
+/**
+ * Parse an `X-Rango-Cache` header value into a `{ routeKey: status }` map.
+ *
+ * Header format: `<routeKey>=<status>, <routeKey2>=<status2>`. The key is the
+ * route NAME (ctx.routeKey, e.g. `product.detail`), NOT the URL pattern —
+ * see assertCacheStatus. Whitespace around entries and the `=` is tolerated.
+ * Entries without a status are ignored.
+ *
+ * @example
+ * parseCacheHeader("product.detail=hit, shop.layout=stale")
+ * // => { "product.detail": "hit", "shop.layout": "stale" }
+ */
+export function parseCacheHeader(
+  headerValue: string | null | undefined,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (!headerValue) return result;
+  for (const rawEntry of headerValue.split(",")) {
+    const entry = rawEntry.trim();
+    if (entry.length === 0) continue;
+    const eq = entry.indexOf("=");
+    if (eq === -1) continue;
+    const id = entry.slice(0, eq).trim();
+    const status = entry.slice(eq + 1).trim();
+    if (id.length === 0 || status.length === 0) continue;
+    result[id] = status;
+  }
+  return result;
+}
+
+function getHeaders(target: CacheStatusTarget): Headers {
+  return target.headers;
+}
+
+/**
+ * Assert that the `X-Rango-Cache` header reports `expected` status for the
+ * given route. Throws a descriptive error when the header is missing (gate
+ * off), the route is absent, or the status differs.
+ *
+ * `routeKey` is the route NAME (e.g. `product.detail`), the same id the header
+ * carries — NOT the URL pattern (`/products/:id`). The signal is built from
+ * ctx.routeKey (telemetry.ts), so a pattern-shaped key never matches.
+ *
+ * The header is produced by the RSC render pipeline, so get the Response from
+ * the router's real fetch path (`router.fetch(...)`), with the debug cache
+ * signal gate enabled (`debugCacheSignal: true` or `RANGO_TEST_SIGNALS=1`).
+ * NOTE: `dispatch()` is the non-RSC primitive and never emits this header.
+ *
+ * @example
+ * // debugCacheSignal must be enabled on the router under test.
+ * const res = await router.fetch(new Request("https://app/products/42"));
+ * assertCacheStatus(res, "product.detail", "hit");
+ */
+export function assertCacheStatus(
+  target: CacheStatusTarget,
+  segment: string,
+  expected: ExpectedCacheStatus,
+): void {
+  const headerValue = getHeaders(target).get(CACHE_HEADER);
+  if (headerValue === null) {
+    throw new Error(
+      `assertCacheStatus: response has no ${CACHE_HEADER} header. ` +
+        `Enable the debug cache signal via createRouter({ debugCacheSignal: true }) ` +
+        `or RANGO_TEST_SIGNALS=1.`,
+    );
+  }
+  const map = parseCacheHeader(headerValue);
+  const actual = map[segment];
+  if (actual === undefined) {
+    const known = Object.keys(map);
+    throw new Error(
+      `assertCacheStatus: segment "${segment}" not found in ${CACHE_HEADER} ` +
+        `("${headerValue}"). Known segments: ${
+          known.length > 0 ? known.join(", ") : "(none)"
+        }.`,
+    );
+  }
+  if (actual !== expected) {
+    throw new Error(
+      `assertCacheStatus: segment "${segment}" expected "${expected}" but got "${actual}".`,
+    );
+  }
+}
+
+/**
+ * A telemetry sink paired with the array it records events into.
+ */
+export interface CacheSink {
+  /** Wire into `createRouter({ telemetry: sink })`. */
+  sink: TelemetrySink;
+  /** All telemetry events captured so far, in emit order. */
+  events: TelemetryEvent[];
+}
+
+/**
+ * Create a capturing telemetry sink for asserting on `cache.decision` events.
+ *
+ * This is the ZERO-production-surface path: no response header is emitted, the
+ * consumer just inspects the captured events.
+ *
+ * @example
+ * const { sink, events } = createCacheSink();
+ * const router = createRouter({ telemetry: sink, ... });
+ * // ...send a request through the router's RSC fetch path...
+ * const decisions = filterCacheDecisions(events);
+ * expect(decisions[0].segments?.[0].cacheStatus).toBe("hit");
+ */
+export function createCacheSink(): CacheSink {
+  const events: TelemetryEvent[] = [];
+  const sink: TelemetrySink = {
+    emit(event: TelemetryEvent): void {
+      events.push(event);
+    },
+  };
+  return { sink, events };
+}
+
+/**
+ * Filter captured telemetry events down to `cache.decision` events.
+ */
+export function filterCacheDecisions(
+  events: readonly TelemetryEvent[],
+): CacheDecisionEvent[] {
+  return events.filter(
+    (e): e is CacheDecisionEvent => e.type === "cache.decision",
+  );
+}

package/src/testing/collect-handle.ts

@@ -0,0 +1,63 @@
+/**
+ * collectHandle — unit-test a handle's `collect`/accumulator function directly.
+ *
+ * A handle's collect function (the `createHandle(collect)` argument that maps the
+ * per-segment pushed values into the accumulated result) is otherwise not
+ * directly reachable: createHandle keeps it in a private registry keyed by the
+ * handle's `$$id` and returns only `{ __brand, $$id }`. This primitive runs that
+ * REAL registered collect on per-segment values you provide and returns the
+ * accumulated result — so the mapper/accumulator is unit-testable without a full
+ * route match.
+ *
+ * It relies on createHandle registering the collect even in a bare test (it
+ * assigns a runtime fallback id when the Vite plugin did not inject one). If a
+ * handle's module was never imported (so createHandle never ran), the collect is
+ * unregistered and this falls back to a flat array with a warning.
+ */
+
+import { getCollectFn, type Handle } from "../handle.js";
+
+/**
+ * Run a handle's collect function on per-segment pushed values.
+ *
+ * @param handle - The handle whose collect to run.
+ * @param segments - Per-segment pushed values: each entry is the array of values
+ *   one route segment pushed for this handle, in parent -> child order. Empty
+ *   per-segment arrays are dropped before the collect runs, matching production
+ *   collectHandleData (a segment that pushed nothing is not passed through).
+ * @returns The accumulated value the handle's collect produces.
+ *
+ * @example
+ * ```ts
+ * // Default flatten
+ * collectHandle(Breadcrumbs, [[{ label: "Home", href: "/" }], [{ label: "P", href: "/p" }]]);
+ * // -> [{ label: "Home", href: "/" }, { label: "P", href: "/p" }]
+ *
+ * // Custom "last wins"
+ * const PageTitle = createHandle<string, string>((s) => s.flat().at(-1) ?? "");
+ * collectHandle(PageTitle, [["Home"], ["Product"]]); // -> "Product"
+ * ```
+ */
+export function collectHandle<TData, TAccumulated>(
+  handle: Handle<TData, TAccumulated>,
+  segments: ReadonlyArray<ReadonlyArray<TData>>,
+): TAccumulated {
+  const collectFn = getCollectFn(handle.$$id) as
+    | ((segments: TData[][]) => TAccumulated)
+    | undefined;
+
+  if (!collectFn) {
+    console.warn(
+      `[rango] collectHandle: handle "${handle.$$id}" has no registered collect ` +
+        `function. Import the handle's module so createHandle() runs. Falling ` +
+        `back to a flat array.`,
+    );
+    return segments.flat() as unknown as TAccumulated;
+  }
+
+  // Match production collectHandleData (handle.ts): segments that pushed
+  // nothing (empty arrays) are dropped before the collect runs, so a collect
+  // that inspects segment count or indices sees the same input as at runtime.
+  const nonEmpty = segments.filter((seg) => seg.length > 0) as TData[][];
+  return collectFn(nonEmpty);
+}

package/src/testing/dispatch.ts

@@ -0,0 +1,440 @@
+/**
+ * dispatch — in-process request -> Response for unit/integration tests,
+ * WITHOUT the Flight RSC runtime.
+ *
+ * dispatch runs the router's real matching and middleware execution so that
+ * redirects, 404s, response routes (path.json / path.text / path.html / ...),
+ * and middleware short-circuits behave exactly as in production. It deliberately
+ * does NOT render React Server Components: there is no Flight stream, no SSR,
+ * and no DOM. Hit an RSC (component) route and dispatch throws a clear error
+ * directing you to renderServer()/renderToFlightString or an e2e test.
+ *
+ * What dispatch DOES support:
+ * - Trailing-slash and other findMatch() redirects   -> 308 with Location
+ * - Unmatched paths                                  -> 404 Response
+ * - Response routes (non-RSC)                         -> serialized Response
+ *   - json:           JSON.stringify({ data }) with application/json
+ *   - text/html/xml/md: String(result) with the mapped MIME type
+ *   - handler returning a Response:                     passed through
+ *   - handler throwing an error:                        typed 500 / RouterError
+ *     status, matching handleResponseRoute (JSON error envelope for json
+ *     routes, text/plain message otherwise)
+ *   - content-negotiated route:                         Vary: Accept appended
+ * - Global middleware (router.use(...)) AND route-level middleware, with full
+ *   next()/short-circuit/throw-Response/header+cookie-merge fidelity.
+ * - Partial (client-navigation) requests to a RESPONSE route (?_rsc_partial):
+ *   global middleware runs first (so an auth gate can still 401/redirect),
+ *   then — if it passes through — an X-RSC-Reload is returned. Route-level
+ *   middleware is skipped on a partial, exactly as production skips it.
+ *
+ * What dispatch DOES NOT support (and why):
+ * - RSC component routes — rendering requires the Flight serializer + React
+ *   server runtime, which is the boundary this primitive is defined to avoid.
+ *   This includes partial requests that resolve to a component route.
+ * - Server actions (?_rsc_action) — RSC protocol concerns handled by
+ *   router.fetch().
+ * - ctx.onError() callbacks on a thrown response-route handler error: the
+ *   error is serialized into the same typed 500 / RouterError Response as
+ *   production, but registered onError handlers are NOT invoked here. Cover
+ *   onError side effects with an e2e test.
+ *
+ * dispatch reuses router.previewMatch(), which itself runs content negotiation
+ * and resolves route middleware from the matched entry tree, so dispatch's
+ * route-middleware collection is exactly the router's, not a re-implementation.
+ */
+
+import {
+  createRequestContext,
+  runWithRequestContext,
+  setRequestContextParams,
+} from "../server/request-context.js";
+import { executeMiddleware, matchMiddleware } from "../router/middleware.js";
+import type {
+  MiddlewareEntry,
+  MiddlewareFn,
+} from "../router/middleware-types.js";
+import {
+  createReverseFunction,
+  stripInternalParams,
+} from "../router/handler-context.js";
+import { NOCACHE_SYMBOL } from "../cache/taint.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
+import { setRouterManifest } from "../route-map-builder.js";
+import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
+import { RouterError } from "../errors.js";
+import { createResponseErrorPayload } from "../rsc/response-error.js";
+import { createResponseWithMergedHeaders } from "../rsc/helpers.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
+import type { Rango } from "../router/router-interfaces.js";
+
+/**
+ * The internal subset of the router surface dispatch depends on. The public
+ * `Rango` router carries these members at runtime (they are declared on the
+ * internal interface), so dispatch accepts a public `Rango` and reads them
+ * through this shape — the consumer never needs a cast.
+ */
+interface DispatchableRouter<TEnv> {
+  id?: string;
+  routerId?: string;
+  routeMap: Record<string, unknown>;
+  middleware: MiddlewareEntry<TEnv>[];
+  findMatch(pathname: string): {
+    redirectTo?: string;
+    routeKey?: string;
+    params?: Record<string, string>;
+  } | null;
+  previewMatch(
+    request: Request,
+    input?: { env?: TEnv },
+  ): Promise<{
+    routeMiddleware?: Array<{
+      handler: MiddlewareFn<TEnv>;
+      params: Record<string, string>;
+    }>;
+    responseType?: string;
+    handler?: Function;
+    params?: Record<string, string>;
+    routeKey?: string;
+    negotiated?: boolean;
+  } | null>;
+  basename?: string;
+  cache?:
+    | { enabled?: boolean; store?: SegmentCacheStore }
+    | ((
+        env: TEnv,
+        executionContext: unknown,
+      ) => { enabled?: boolean; store?: SegmentCacheStore });
+  cacheProfiles?: Record<string, CacheProfile>;
+}
+
+/**
+ * Options for dispatch.
+ */
+export interface DispatchOptions<TEnv = any> {
+  /** Environment bindings forwarded to matching and middleware. */
+  env?: TEnv;
+}
+
+const DEFAULT_ORIGIN = "http://localhost/";
+
+function toRequest(request: Request | string): Request {
+  if (request instanceof Request) return request;
+  return new Request(new URL(request, DEFAULT_ORIGIN));
+}
+
+/**
+ * Serialize a response-route handler result, mirroring the router's
+ * handleResponseRoute() contract:
+ * - a returned Response is passed through unchanged,
+ * - "json" wraps the value as JSON.stringify({ data }) with application/json,
+ * - text/html/xml/md stringify with the mapped MIME type.
+ */
+function serializeResponseRouteResult(
+  result: unknown,
+  responseType: string,
+): Response {
+  if (result instanceof Response) return result;
+
+  if (responseType === "json") {
+    return new Response(JSON.stringify({ data: result }), {
+      status: 200,
+      headers: { "content-type": "application/json;charset=utf-8" },
+    });
+  }
+
+  if (Object.hasOwn(RESPONSE_TYPE_MIME, responseType)) {
+    return new Response(String(result), {
+      status: 200,
+      headers: {
+        "content-type": `${RESPONSE_TYPE_MIME[responseType]};charset=utf-8`,
+      },
+    });
+  }
+
+  throw new Error(
+    `dispatch(): response route handler for "${responseType}" must return a ` +
+      `Response object, got ${typeof result}. Binary/streaming response types ` +
+      `(image, stream, any) must return a Response explicitly.`,
+  );
+}
+
+/**
+ * Serialize a thrown handler error into the same typed Response the router's
+ * handleResponseRoute() catch block produces:
+ * - status is the RouterError.status, else 500,
+ * - "json" routes return { error: <createResponseErrorPayload> } as JSON,
+ * - all other types return a text/plain body (the RouterError message verbatim,
+ *   the Error message in dev, else "Internal Server Error").
+ *
+ * Reuses the production createResponseErrorPayload so the JSON error envelope
+ * is byte-identical rather than re-derived.
+ */
+function serializeResponseRouteError(
+  error: unknown,
+  responseType: string,
+): Response {
+  const isDev = process.env.NODE_ENV !== "production";
+  const status = error instanceof RouterError ? error.status : 500;
+
+  if (responseType === "json") {
+    return new Response(
+      JSON.stringify({ error: createResponseErrorPayload(error, isDev) }),
+      {
+        status,
+        headers: { "content-type": "application/json;charset=utf-8" },
+      },
+    );
+  }
+
+  const message =
+    error instanceof RouterError
+      ? error.message
+      : isDev && error instanceof Error
+        ? error.message
+        : "Internal Server Error";
+  return new Response(message, {
+    status,
+    headers: { "content-type": "text/plain;charset=utf-8" },
+  });
+}
+
+/**
+ * Run a request through the router in-process and return the Response.
+ *
+ * @example
+ * ```ts
+ * const router = createRouter<Env>({}).routes(urls(({ path }) => [
+ *   path.json("/api/health", () => ({ ok: true }), { name: "health" }),
+ * ]));
+ *
+ * const res = await dispatch(router, "/api/health");
+ * expect(res.status).toBe(200);
+ * expect(await res.json()).toEqual({ data: { ok: true } });
+ * ```
+ */
+export async function dispatch<TEnv = any>(
+  publicRouter: Rango<TEnv, any>,
+  request: Request | string,
+  opts: DispatchOptions<TEnv> = {},
+): Promise<Response> {
+  // The public Rango type intentionally hides the matching internals; read them
+  // through the dispatchable shape (present at runtime). Consumers pass their
+  // real router with no cast.
+  const router = publicRouter as unknown as DispatchableRouter<TEnv>;
+  const req = toRequest(request);
+  const url = new URL(req.url);
+  const env = (opts.env ?? {}) as TEnv;
+
+  // Seed the per-router manifest so reverse() resolves during handler execution.
+  const routerId = router.id ?? router.routerId;
+  if (routerId) {
+    setRouterManifest(routerId, router.routeMap as Record<string, string>);
+  }
+
+  // findMatch carries trailing-slash/redirect targets and null on no match.
+  // previewMatch swallows redirects, so detect them here first.
+  const match = router.findMatch(url.pathname);
+
+  if (match?.redirectTo) {
+    return new Response(null, {
+      status: 308,
+      headers: { Location: match.redirectTo + url.search },
+    });
+  }
+
+  if (!match) {
+    return new Response("Not Found", {
+      status: 404,
+      headers: { "content-type": "text/plain;charset=utf-8" },
+    });
+  }
+
+  // previewMatch resolves responseType, the response-route handler, and the
+  // route middleware from the matched entry tree (with content negotiation).
+  const preview = await router.previewMatch(req, { env });
+
+  // No preview (e.g. resolved to a redirect inside previewMatch) — fall back to
+  // the findMatch result. A bare match with no responseType is an RSC route.
+  const responseType = preview?.responseType;
+  const handler = preview?.handler;
+  const params = preview?.params ?? match.params ?? {};
+  const routeKey = preview?.routeKey ?? match.routeKey;
+
+  if (!responseType || typeof handler !== "function") {
+    throw new Error(
+      `dispatch() does not render RSC routes — the route matched at ` +
+        `"${url.pathname}" is a React Server Component route, not a response ` +
+        `route. Use renderServer()/renderToFlightString or an e2e test to ` +
+        `exercise component rendering.`,
+    );
+  }
+
+  const variables: Record<string, unknown> = {};
+
+  // Resolve the router's cache store the way the production handler does, so a
+  // "use cache" inside a response-route handler reaches the request-scope
+  // (NOCACHE) detection below instead of bypassing on a missing store.
+  let cacheStore: SegmentCacheStore | undefined;
+  const cacheOption = router.cache;
+  if (cacheOption && !url.searchParams.has("__no_cache")) {
+    const cacheConfig =
+      typeof cacheOption === "function"
+        ? cacheOption(env, undefined)
+        : cacheOption;
+    if (cacheConfig.enabled !== false) cacheStore = cacheConfig.store;
+  }
+
+  const requestContext = createRequestContext<TEnv>({
+    env,
+    request: req,
+    url,
+    variables,
+    cacheStore,
+    cacheProfiles: router.cacheProfiles,
+  });
+  // Match production: the RSC handler stores the router's basename on the
+  // request context (handler.ts), and redirect() prefixes root-relative URLs
+  // with it. Mirror it so basename-redirect tests behave as they do in a real
+  // mounted app instead of always seeing no prefix.
+  requestContext._basename = router.basename;
+
+  // Match production's response-route reverse EXACTLY: the real handler builds
+  // it from the route map alone (response-route-handler.ts), with NO matched
+  // routeKey or params. Passing routeKey/params here would auto-fill params from
+  // the matched route, so ctx.reverse("name") could pass in a test while the
+  // real handler throws for the missing param.
+  const reverse = createReverseFunction(
+    router.routeMap as Record<string, string>,
+  ) as (
+    name: string,
+    p?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ) => string;
+
+  return runWithRequestContext(requestContext, async () => {
+    // Set params before middleware/handler run, so global middleware sees
+    // ctx.params (production sets them during matching, before middleware).
+    if (routeKey !== undefined) {
+      setRequestContextParams(params, routeKey);
+    } else {
+      requestContext.params = params;
+    }
+
+    // Match production: a partial (client-navigation) request to a response
+    // route is short-circuited to X-RSC-Reload, but ONLY after GLOBAL
+    // (app-level) middleware has run. In production the partial check lives
+    // inside coreHandler (handler.ts wraps it with executeMiddleware) and,
+    // within handleResponseRoute, precedes the route-level middleware
+    // (response-route-handler.ts). So global middleware (e.g. an auth gate)
+    // can still 401/redirect a partial request; only when it calls next()
+    // through does the reload get emitted. Route-level middleware is skipped
+    // on a partial, exactly as production skips it.
+    const isPartial = url.searchParams.has("_rsc_partial");
+    const partialFinalHandler = async (): Promise<Response> =>
+      createResponseWithMergedHeaders(null, {
+        status: 200,
+        headers: {
+          "X-RSC-Reload": stripInternalParams(url).toString(),
+          "content-type": "text/x-component;charset=utf-8",
+        },
+      });
+
+    const cleanUrl = new URL(req.url);
+    for (const key of [...cleanUrl.searchParams.keys()]) {
+      if (key.startsWith("_rsc")) cleanUrl.searchParams.delete(key);
+    }
+
+    // Lightweight response-handler context mirroring handleResponseRoute.
+    const responseHandlerCtx = {
+      request: req,
+      params,
+      env,
+      searchParams: cleanUrl.searchParams,
+      url: cleanUrl,
+      originalUrl: requestContext.originalUrl,
+      pathname: url.pathname,
+      reverse,
+      get: requestContext.get,
+      header: (name: string, value: string) =>
+        requestContext.header(name, value),
+      waitUntil: requestContext.waitUntil.bind(requestContext),
+      executionContext: requestContext.executionContext,
+      _responseType: responseType,
+    };
+    // Brand as request-scoped so a "use cache" inside a response-route handler
+    // is detected as a request-scope violation here exactly as in production
+    // (response-route-handler.ts brands the same shape).
+    (responseHandlerCtx as Record<symbol, unknown>)[NOCACHE_SYMBOL] = true;
+
+    const callHandler = async (): Promise<Response> => {
+      let serialized: Response;
+      try {
+        const result = await (handler as Function)(responseHandlerCtx);
+        serialized = serializeResponseRouteResult(result, responseType);
+      } catch (error) {
+        // Mirror handleResponseRoute's catch: a genuine handler error becomes
+        // the router's typed 500 / RouterError-status Response (NOT a rejected
+        // promise). Middleware short-circuit via thrown Response is handled by
+        // executeMiddleware and never reaches here.
+        serialized = serializeResponseRouteError(error, responseType);
+      }
+
+      // Route through the SAME production finalizer the RSC handler uses, so
+      // ctx.onResponse() callbacks fire and stub headers/cookies + ctx.setStatus
+      // merge identically to production (handleResponseRoute also goes through
+      // createResponseWithMergedHeaders). Runs inside runWithRequestContext, so
+      // _getRequestContext() resolves to this request's context.
+      const merged = createResponseWithMergedHeaders(serialized.body, {
+        status: serialized.status,
+        statusText: serialized.statusText,
+        headers: serialized.headers,
+      });
+
+      // Append Vary: Accept on content-negotiated responses, matching
+      // handleResponseRoute's callHandlerWithVary. Skipped on WebSocket upgrade
+      // responses (immutable headers, Vary meaningless for a 101).
+      if (preview?.negotiated && !isWebSocketUpgradeResponse(merged)) {
+        merged.headers.append("Vary", "Accept");
+      }
+
+      return merged;
+    };
+
+    // On a partial request the reload IS the terminal handler; otherwise the
+    // response-route handler is. Either way global middleware wraps it.
+    const finalHandler = isPartial ? partialFinalHandler : callHandler;
+
+    // Combine global (pattern-matched) middleware with route middleware,
+    // preserving the router's order: global runs before route-level. Route
+    // middleware is skipped on a partial request (production returns the
+    // reload before handleResponseRoute reaches its route middleware).
+    const globalMatches = matchMiddleware(url.pathname, router.middleware);
+    const routeMiddlewareEntries = isPartial
+      ? []
+      : (preview?.routeMiddleware ?? []).map((mw) => ({
+          entry: {
+            pattern: null,
+            regex: null,
+            paramNames: [],
+            handler: mw.handler,
+            mountPrefix: null,
+          } as MiddlewareEntry<TEnv>,
+          params: mw.params,
+        }));
+    const allMiddleware = [...globalMatches, ...routeMiddlewareEntries];
+
+    if (allMiddleware.length === 0) {
+      return finalHandler();
+    }
+
+    return executeMiddleware<TEnv>(
+      allMiddleware,
+      req,
+      env,
+      variables,
+      finalHandler,
+      reverse,
+    );
+  });
+}