vinext 0.1.1 → 0.1.3

package/dist/server/headers.js

@@ -60,6 +60,13 @@ const RSC_ACTION_HEADER = "x-rsc-action";
 const NEXT_ACTION_HEADER = "next-action";
 /** Next.js action-not-found indicator (value "1"). */
 const NEXTJS_ACTION_NOT_FOUND_HEADER = "x-nextjs-action-not-found";
+/**
+* Deployment ID header used by the Pages Router for deployment-skew
+* protection. Set on every `/_next/data/` response so the client can detect
+* when a new deployment has been rolled out and trigger a hard navigation.
+* Mirrors `NEXT_NAV_DEPLOYMENT_ID_HEADER` from Next.js `lib/constants.ts`.
+*/
+const NEXTJS_DEPLOYMENT_ID_HEADER = "x-nextjs-deployment-id";
 /** Forwarded action marker — set when a request has already been forwarded between workers. */
 const ACTION_FORWARDED_HEADER = "x-action-forwarded";
 /** Indicates revalidation occurred — value is JSON kind (1 = path/tag, 2 = dynamic-only). */
@@ -122,4 +129,4 @@ const INTERNAL_HEADERS = [
 /** Vinext-only internal headers stripped alongside Next.js protocol internals. */
 const VINEXT_INTERNAL_HEADERS = [VINEXT_PRERENDER_ROUTE_PARAMS_HEADER];
 //#endregion
-export { ACTION_FORWARDED_HEADER, ACTION_REDIRECT_HEADER, ACTION_REDIRECT_STATUS_HEADER, ACTION_REDIRECT_TYPE_HEADER, ACTION_REVALIDATED_HEADER, FLIGHT_HEADERS, INTERNAL_HEADERS, MIDDLEWARE_HEADER_PREFIX, MIDDLEWARE_NEXT_HEADER, MIDDLEWARE_OVERRIDE_HEADERS, MIDDLEWARE_REQUEST_HEADER_PREFIX, MIDDLEWARE_REWRITE_HEADER, MIDDLEWARE_SET_COOKIE_HEADER, NEXTJS_ACTION_NOT_FOUND_HEADER, NEXTJS_CACHE_HEADER, NEXT_ACTION_HEADER, NEXT_ROUTER_PREFETCH_HEADER, NEXT_ROUTER_SEGMENT_PREFETCH_HEADER, NEXT_ROUTER_STATE_TREE_HEADER, NEXT_URL_HEADER, RSC_ACTION_HEADER, RSC_HEADER, VINEXT_CACHE_HEADER, VINEXT_CLIENT_REUSE_MANIFEST_HEADER, VINEXT_DYNAMIC_STALE_TIME_HEADER, VINEXT_INTERCEPTION_CONTEXT_HEADER, VINEXT_INTERNAL_HEADERS, VINEXT_MOUNTED_SLOTS_HEADER, VINEXT_MW_CTX_HEADER, VINEXT_PARAMS_HEADER, VINEXT_PRERENDER_ROUTE_PARAMS_HEADER, VINEXT_PRERENDER_SECRET_HEADER, VINEXT_REVALIDATE_HEADER, VINEXT_RSC_MARKER_HEADER, VINEXT_RSC_REDIRECT_HEADER, VINEXT_RSC_RENDER_MODE_HEADER, VINEXT_STATIC_FILE_HEADER, VINEXT_TIMING_HEADER };
+export { ACTION_FORWARDED_HEADER, ACTION_REDIRECT_HEADER, ACTION_REDIRECT_STATUS_HEADER, ACTION_REDIRECT_TYPE_HEADER, ACTION_REVALIDATED_HEADER, FLIGHT_HEADERS, INTERNAL_HEADERS, MIDDLEWARE_HEADER_PREFIX, MIDDLEWARE_NEXT_HEADER, MIDDLEWARE_OVERRIDE_HEADERS, MIDDLEWARE_REQUEST_HEADER_PREFIX, MIDDLEWARE_REWRITE_HEADER, MIDDLEWARE_SET_COOKIE_HEADER, NEXTJS_ACTION_NOT_FOUND_HEADER, NEXTJS_CACHE_HEADER, NEXTJS_DEPLOYMENT_ID_HEADER, NEXT_ACTION_HEADER, NEXT_ROUTER_PREFETCH_HEADER, NEXT_ROUTER_SEGMENT_PREFETCH_HEADER, NEXT_ROUTER_STATE_TREE_HEADER, NEXT_URL_HEADER, RSC_ACTION_HEADER, RSC_HEADER, VINEXT_CACHE_HEADER, VINEXT_CLIENT_REUSE_MANIFEST_HEADER, VINEXT_DYNAMIC_STALE_TIME_HEADER, VINEXT_INTERCEPTION_CONTEXT_HEADER, VINEXT_INTERNAL_HEADERS, VINEXT_MOUNTED_SLOTS_HEADER, VINEXT_MW_CTX_HEADER, VINEXT_PARAMS_HEADER, VINEXT_PRERENDER_ROUTE_PARAMS_HEADER, VINEXT_PRERENDER_SECRET_HEADER, VINEXT_REVALIDATE_HEADER, VINEXT_RSC_MARKER_HEADER, VINEXT_RSC_REDIRECT_HEADER, VINEXT_RSC_RENDER_MODE_HEADER, VINEXT_STATIC_FILE_HEADER, VINEXT_TIMING_HEADER };

package/dist/server/hybrid-route-priority.d.ts

@@ -0,0 +1,22 @@
+//#region src/server/hybrid-route-priority.d.ts
+type HybridRoutePriorityRoute = {
+  isDynamic: boolean;
+  pattern: string;
+  sourcePath?: string | null;
+};
+declare function validateHybridRouteConflicts(pagesRoutes: readonly HybridRoutePriorityRoute[], appRoutes: readonly HybridRoutePriorityRoute[]): void;
+/**
+ * Return whether a matched Pages Router route should own the request instead
+ * of a matched App Router route.
+ *
+ * Next.js registers Pages providers before App providers, then sorts all
+ * dynamic route pathnames together in DefaultRouteMatcherManager. Vinext keeps
+ * separate route tries for each router, so the hybrid boundary needs to apply
+ * that same cross-router ordering after both routers have produced their best
+ * local match. The decision itself lives in
+ * `routing/utils.ts#compareHybridRoutePatterns` so the server and client
+ * always reach the same answer.
+ */
+declare function pagesRouteHasPriorityOverAppRoute(pagesRoute: HybridRoutePriorityRoute, appRoute: HybridRoutePriorityRoute | null): boolean;
+//#endregion
+export { HybridRoutePriorityRoute, pagesRouteHasPriorityOverAppRoute, validateHybridRouteConflicts };

package/dist/server/hybrid-route-priority.js

@@ -0,0 +1,33 @@
+import { compareHybridRoutePatterns } from "../routing/utils.js";
+import { validateRoutePatterns } from "../routing/route-validation.js";
+//#region src/server/hybrid-route-priority.ts
+function validateHybridRouteConflicts(pagesRoutes, appRoutes) {
+	const pagesByPattern = new Map(pagesRoutes.map((route) => [route.pattern, route]));
+	const conflicts = appRoutes.flatMap((appRoute) => {
+		const pagesRoute = pagesByPattern.get(appRoute.pattern);
+		return pagesRoute === void 0 ? [] : [[pagesRoute, appRoute]];
+	});
+	if (conflicts.length > 0) {
+		const message = `Conflicting app and page file${conflicts.length === 1 ? " was" : "s were"} found, please remove the conflicting files to continue:`;
+		throw new Error(`${message}\n${conflicts.map(([pagesRoute, appRoute]) => `  "${pagesRoute.sourcePath ?? pagesRoute.pattern}" - "${appRoute.sourcePath ?? appRoute.pattern}"`).join("\n")}`);
+	}
+	validateRoutePatterns([...pagesRoutes.map((route) => route.pattern), ...appRoutes.map((route) => route.pattern)]);
+}
+/**
+* Return whether a matched Pages Router route should own the request instead
+* of a matched App Router route.
+*
+* Next.js registers Pages providers before App providers, then sorts all
+* dynamic route pathnames together in DefaultRouteMatcherManager. Vinext keeps
+* separate route tries for each router, so the hybrid boundary needs to apply
+* that same cross-router ordering after both routers have produced their best
+* local match. The decision itself lives in
+* `routing/utils.ts#compareHybridRoutePatterns` so the server and client
+* always reach the same answer.
+*/
+function pagesRouteHasPriorityOverAppRoute(pagesRoute, appRoute) {
+	if (appRoute === null) return true;
+	return compareHybridRoutePatterns(pagesRoute.pattern, pagesRoute.isDynamic, appRoute.pattern, appRoute.isDynamic) === "pages";
+}
+//#endregion
+export { pagesRouteHasPriorityOverAppRoute, validateHybridRouteConflicts };

package/dist/server/image-optimization.d.ts

@@ -33,7 +33,15 @@ declare function isImageOptimizationPath(pathname: string): boolean;
  * Controls SVG handling and security headers for the image endpoint.
  */
 type ImageConfig = {
-  /** Allow SVG through the image optimization endpoint. Default: false. */dangerouslyAllowSVG?: boolean;
+  /** Allowed device widths. Defaults to Next.js device sizes. */deviceSizes?: number[]; /** Allowed fixed-image widths. Defaults to Next.js image sizes. */
+  imageSizes?: number[];
+  /**
+   * Allowed output qualities. When unset, any quality from 1-100 is permitted
+   * (matches Next.js: an unset `images.qualities` is not restricted to a single
+   * value). When set, only the listed qualities are accepted.
+   */
+  qualities?: number[]; /** Allow SVG through the image optimization endpoint. Default: false. */
+  dangerouslyAllowSVG?: boolean;
   /**
    * Allow image optimization for hostnames that resolve to private IP addresses.
    * Default: false.
@@ -54,18 +62,19 @@ type ImageConfig = {
  */
 declare const DEFAULT_DEVICE_SIZES: number[];
 declare const DEFAULT_IMAGE_SIZES: number[];
+type ParseImageParamsOptions = {
+  isDev?: boolean;
+};
+declare function resolveDevImageRedirect(requestUrl: URL, allowedWidths?: number[], allowedQualities?: number[], options?: ParseImageParamsOptions): string | null;
 /**
  * Parse and validate image optimization query parameters.
  * Returns null if the request is malformed.
  *
- * When `allowedWidths` is provided, the width must be 0 (no resize) or
- * exactly match one of the allowed values. This matches Next.js behavior
- * where only configured deviceSizes and imageSizes are accepted.
- *
- * When `allowedWidths` is not provided, any width from 0 to ABSOLUTE_MAX_WIDTH
- * is accepted (backwards-compatible fallback).
+ * Ported from Next.js:
+ * test/integration/image-optimizer/test/index.test.ts
+ * https://github.com/vercel/next.js/blob/canary/test/integration/image-optimizer/test/index.test.ts
  */
-declare function parseImageParams(url: URL, allowedWidths?: number[]): {
+declare function parseImageParams(url: URL, allowedWidths?: number[], allowedQualities?: number[], options?: ParseImageParamsOptions): {
   imageUrl: string;
   width: number;
   quality: number;
@@ -113,4 +122,4 @@ type ImageHandlers = {
  */
 declare function handleImageOptimization(request: Request, handlers: ImageHandlers, allowedWidths?: number[], imageConfig?: ImageConfig): Promise<Response>;
 //#endregion
-export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_SIZES, IMAGE_CACHE_CONTROL, IMAGE_CONTENT_SECURITY_POLICY, IMAGE_OPTIMIZATION_PATH, ImageConfig, ImageHandlers, VINEXT_IMAGE_OPTIMIZATION_PATH, handleImageOptimization, isImageOptimizationPath, isSafeImageContentType, negotiateImageFormat, parseImageParams };
+export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_SIZES, IMAGE_CACHE_CONTROL, IMAGE_CONTENT_SECURITY_POLICY, IMAGE_OPTIMIZATION_PATH, ImageConfig, ImageHandlers, ParseImageParamsOptions, VINEXT_IMAGE_OPTIMIZATION_PATH, handleImageOptimization, isImageOptimizationPath, isSafeImageContentType, negotiateImageFormat, parseImageParams, resolveDevImageRedirect };

package/dist/server/image-optimization.js

@@ -56,32 +56,46 @@ const DEFAULT_IMAGE_SIZES = [
 	256,
 	384
 ];
-/**
-* Absolute maximum image width. Even if custom deviceSizes/imageSizes are
-* configured, widths above this are always rejected. This prevents resource
-* exhaustion from absurdly large resize requests.
-*/
-const ABSOLUTE_MAX_WIDTH = 3840;
+const DEV_BLUR_MAX_WIDTH = 8;
+const DEV_BLUR_QUALITY = 70;
+function resolveDevImageRedirect(requestUrl, allowedWidths = [...DEFAULT_DEVICE_SIZES, ...DEFAULT_IMAGE_SIZES], allowedQualities, options = { isDev: true }) {
+	const params = parseImageParams(requestUrl, allowedWidths, allowedQualities, options);
+	if (!params) return null;
+	if (params.imageUrl.startsWith("/@") || params.imageUrl.startsWith("/__vite") || params.imageUrl.startsWith("/node_modules")) return null;
+	const resolved = new URL(params.imageUrl, requestUrl.origin);
+	if (resolved.origin !== requestUrl.origin) return null;
+	return resolved.pathname + resolved.search;
+}
 /**
 * Parse and validate image optimization query parameters.
 * Returns null if the request is malformed.
 *
-* When `allowedWidths` is provided, the width must be 0 (no resize) or
-* exactly match one of the allowed values. This matches Next.js behavior
-* where only configured deviceSizes and imageSizes are accepted.
-*
-* When `allowedWidths` is not provided, any width from 0 to ABSOLUTE_MAX_WIDTH
-* is accepted (backwards-compatible fallback).
+* Ported from Next.js:
+* test/integration/image-optimizer/test/index.test.ts
+* https://github.com/vercel/next.js/blob/canary/test/integration/image-optimizer/test/index.test.ts
 */
-function parseImageParams(url, allowedWidths) {
+function parseImageParams(url, allowedWidths = [...DEFAULT_DEVICE_SIZES, ...DEFAULT_IMAGE_SIZES], allowedQualities, options = {}) {
+	const allowedParamNames = new Set([
+		"url",
+		"w",
+		"q"
+	]);
+	for (const name of url.searchParams.keys()) if (!allowedParamNames.has(name) || url.searchParams.getAll(name).length !== 1) return null;
 	const imageUrl = url.searchParams.get("url");
 	if (!imageUrl) return null;
-	const w = parseInt(url.searchParams.get("w") || "0", 10);
-	const q = parseInt(url.searchParams.get("q") || "75", 10);
-	if (Number.isNaN(w) || w < 0) return null;
-	if (w > ABSOLUTE_MAX_WIDTH) return null;
-	if (allowedWidths && w !== 0 && !allowedWidths.includes(w)) return null;
-	if (Number.isNaN(q) || q < 1 || q > 100) return null;
+	if (imageUrl.length > 3072) return null;
+	const widthParam = url.searchParams.get("w");
+	const qualityParam = url.searchParams.get("q");
+	if (!widthParam || !/^[0-9]+$/.test(widthParam)) return null;
+	if (!qualityParam || !/^[0-9]+$/.test(qualityParam)) return null;
+	const width = Number.parseInt(widthParam, 10);
+	const quality = Number.parseInt(qualityParam, 10);
+	if (String(width) !== widthParam || String(quality) !== qualityParam) return null;
+	const isDevBlurWidth = options.isDev && width <= DEV_BLUR_MAX_WIDTH;
+	const isDevBlurQuality = options.isDev && quality === DEV_BLUR_QUALITY;
+	if (width <= 0 || !allowedWidths.includes(width) && !isDevBlurWidth) return null;
+	if (quality < 1 || quality > 100) return null;
+	if (allowedQualities && !allowedQualities.includes(quality) && !isDevBlurQuality) return null;
 	const normalizedUrl = imageUrl.replaceAll("\\", "/");
 	if (!normalizedUrl.startsWith("/") || normalizedUrl.startsWith("//")) return null;
 	try {
@@ -92,8 +106,8 @@ function parseImageParams(url, allowedWidths) {
 	}
 	return {
 		imageUrl: normalizedUrl,
-		width: w,
-		quality: q
+		width,
+		quality
 	};
 }
 /**
@@ -174,7 +188,7 @@ function createPassthroughImageResponse(source, config) {
 * cache headers.
 */
 async function handleImageOptimization(request, handlers, allowedWidths, imageConfig) {
-	const params = parseImageParams(new URL(request.url), allowedWidths);
+	const params = parseImageParams(new URL(request.url), allowedWidths, imageConfig?.qualities);
 	if (!params) return badRequestResponse();
 	const { imageUrl, width, quality } = params;
 	const source = await handlers.fetchAsset(imageUrl, request);
@@ -212,4 +226,4 @@ async function handleImageOptimization(request, handlers, allowedWidths, imageCo
 	}
 }
 //#endregion
-export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_SIZES, IMAGE_CACHE_CONTROL, IMAGE_CONTENT_SECURITY_POLICY, IMAGE_OPTIMIZATION_PATH, VINEXT_IMAGE_OPTIMIZATION_PATH, handleImageOptimization, isImageOptimizationPath, isSafeImageContentType, negotiateImageFormat, parseImageParams };
+export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_SIZES, IMAGE_CACHE_CONTROL, IMAGE_CONTENT_SECURITY_POLICY, IMAGE_OPTIMIZATION_PATH, VINEXT_IMAGE_OPTIMIZATION_PATH, handleImageOptimization, isImageOptimizationPath, isSafeImageContentType, negotiateImageFormat, parseImageParams, resolveDevImageRedirect };

package/dist/server/implicit-tags.d.ts

@@ -1,5 +1,6 @@
 //#region src/server/implicit-tags.d.ts
 type AppCacheLeafKind = "page" | "route";
+declare function buildAppPageTags(cleanPathname: string, extraTags: string[], routeSegments: readonly string[]): string[];
 declare function buildPageCacheTags(pathname: string, extraTags: string[], routeSegments: string[], leafKind: AppCacheLeafKind): string[];
 //#endregion
-export { buildPageCacheTags };
+export { buildAppPageTags, buildPageCacheTags };

package/dist/server/implicit-tags.js

@@ -29,6 +29,9 @@ function appendDerivedTags(tags, routePath) {
 		appendUnique(tags, `${NEXT_CACHE_IMPLICIT_TAG_ID}${currentPathname}`);
 	}
 }
+function buildAppPageTags(cleanPathname, extraTags, routeSegments) {
+	return buildPageCacheTags(cleanPathname, extraTags, [...routeSegments], "page");
+}
 function buildPageCacheTags(pathname, extraTags, routeSegments, leafKind) {
 	const tags = [pathname, `${NEXT_CACHE_IMPLICIT_TAG_ID}${pathname}`];
 	if (pathname === "/") appendUnique(tags, `${NEXT_CACHE_IMPLICIT_TAG_ID}/index`);
@@ -38,4 +41,4 @@ function buildPageCacheTags(pathname, extraTags, routeSegments, leafKind) {
 	return tags.map(encodeCacheTag);
 }
 //#endregion
-export { buildPageCacheTags };
+export { buildAppPageTags, buildPageCacheTags };

package/dist/server/instrumentation-runtime.d.ts

@@ -34,6 +34,12 @@
  * Ensure the instrumentation module's `register()` and `onRequestError`
  * hooks have been applied exactly once.
  *
+ * After `register()` runs, we extend the OTel tracer provider so that spans
+ * created inside Cache Component renders (warmup / fallback-resume phases) use
+ * a fresh OTel context rather than inheriting the prerender work unit store.
+ * This mirrors Next.js's `afterRegistration()` call in
+ * `instrumentation-node-extensions.ts`.
+ *
  * @param instrumentationModule - The imported `instrumentation.ts` module.
  *   Passed as an argument so the generated entry can import it normally
  *   without this helper needing to know the module path.

package/dist/server/instrumentation-runtime.js

@@ -1,3 +1,4 @@
+import { extendTracerProviderForCacheComponents } from "./otel-tracer-extension.js";
 //#region src/server/instrumentation-runtime.ts
 let initialized = false;
 let initPromise = null;
@@ -8,6 +9,12 @@ function isOnRequestErrorHandler(value) {
 * Ensure the instrumentation module's `register()` and `onRequestError`
 * hooks have been applied exactly once.
 *
+* After `register()` runs, we extend the OTel tracer provider so that spans
+* created inside Cache Component renders (warmup / fallback-resume phases) use
+* a fresh OTel context rather than inheriting the prerender work unit store.
+* This mirrors Next.js's `afterRegistration()` call in
+* `instrumentation-node-extensions.ts`.
+*
 * @param instrumentationModule - The imported `instrumentation.ts` module.
 *   Passed as an argument so the generated entry can import it normally
 *   without this helper needing to know the module path.
@@ -18,6 +25,7 @@ async function ensureInstrumentationRegistered(instrumentationModule) {
 	if (initPromise) return initPromise;
 	initPromise = (async () => {
 		if (typeof instrumentationModule.register === "function") await instrumentationModule.register();
+		extendTracerProviderForCacheComponents();
 		if (isOnRequestErrorHandler(instrumentationModule.onRequestError)) globalThis.__VINEXT_onRequestErrorHandler__ = instrumentationModule.onRequestError;
 		initialized = true;
 	})();

package/dist/server/isr-decision.d.ts

@@ -0,0 +1,79 @@
+import { CacheControlMetadata } from "../shims/cache.js";
+import { NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL } from "./cache-control.js";
+
+//#region src/server/isr-decision.d.ts
+type IsrDisposition = "HIT" | "STALE" | "MISS";
+type IsrDecision = {
+  disposition: IsrDisposition; /** True when the caller must schedule a background regeneration. */
+  scheduleRegeneration: boolean; /** The `Cache-Control` string to stamp on the response. */
+  cacheControl: string;
+};
+/**
+ * Per-router special-case policies for `Cache-Control`.
+ *
+ * - `"app-page"` / `"pages"`: `buildCachedRevalidateCacheControl` for HIT/STALE.
+ * - `"app-route"`: same, but `revalidateSeconds=0` forces `NEVER_CACHE_CONTROL`
+ *   and `revalidateSeconds=Infinity` forces `STATIC_CACHE_CONTROL`.
+ * - `"dev"`: like `"pages"`, but `revalidate=0`/`Infinity` guards are absent
+ *   (dev never caches when revalidate=0 and never has Infinity entries in practice).
+ */
+type IsrPolicyKind = "app-page" | "app-route" | "pages" | "dev";
+type DecideIsrOptions = {
+  /**
+   * The cache state. Content guards (kind-mismatch, empty body,
+   * query-variant-unproven) must have already passed before passing
+   * `"HIT"` or `"STALE"` here.
+   */
+  cacheState: "HIT" | "STALE" | "MISS"; /** Which router is making the decision. */
+  kind: IsrPolicyKind;
+  /**
+   * The route's configured revalidate window in seconds. Used as the fallback
+   * when `cacheControlMeta` is absent.
+   *
+   * For `"dev"` call sites this is the only source of the revalidate value —
+   * dev never has metadata attached to a cache entry.
+   */
+  revalidateSeconds: number;
+  /**
+   * The expire ceiling (seconds from epoch) read from the route config.
+   * Absent when the route pre-dates expire metadata support.
+   */
+  expireSeconds?: number;
+  /**
+   * Optional per-entry metadata written alongside the cache value.
+   * When present its `revalidate`/`expire` fields override the route defaults,
+   * exactly as the call sites do today with `cacheControl?.revalidate ?? revalidateSeconds`.
+   */
+  cacheControlMeta?: CacheControlMetadata;
+};
+/**
+ * Derive the `Cache-Control` string for an ISR response.
+ *
+ * Content guards (kind mismatch, query-variant-unproven, empty body) are the
+ * caller's responsibility and must happen *before* this call. `cacheState`
+ * must only be `"HIT"` or `"STALE"` when those guards have already passed.
+ */
+declare function decideIsr(options: DecideIsrOptions): IsrDecision;
+/**
+ * Build the `Cache-Control` string for a fresh MISS response whose ISR policy
+ * is known (i.e. revalidate is set and > 0). Uses the unbounded SWR form when
+ * no expire ceiling is available, exactly as `buildRevalidateCacheControl` does.
+ *
+ * Separate from `decideIsr` because a MISS doesn't read a cache entry and
+ * therefore never has `cacheControlMeta`. `expireSeconds` here is the route
+ * config ceiling passed directly from the caller (not a per-entry fallback).
+ */
+declare function buildMissIsrCacheControl(revalidateSeconds: number, expireSeconds?: number): string;
+/**
+ * Build the `Cache-Control` string for a fresh (MISS) app-route response.
+ *
+ * Applies the same `revalidateSeconds=0`→NEVER and `Infinity`→STATIC gates
+ * that `decideIsr` uses for app-route cached responses. `expireSeconds` is
+ * the route config ceiling passed directly (not per-entry metadata fallback).
+ *
+ * Used by `applyRouteHandlerRevalidateHeader` which operates on a fresh
+ * response that has no per-entry cache metadata.
+ */
+declare function buildAppRouteMissIsrCacheControl(revalidateSeconds: number, expireSeconds?: number): string;
+//#endregion
+export { NEVER_CACHE_CONTROL as ISR_NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL as ISR_NO_STORE_CACHE_CONTROL, buildAppRouteMissIsrCacheControl, buildMissIsrCacheControl, decideIsr };

package/dist/server/isr-decision.js

@@ -0,0 +1,70 @@
+import { NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL, STATIC_CACHE_CONTROL, buildCachedRevalidateCacheControl, buildRevalidateCacheControl } from "./cache-control.js";
+//#region src/server/isr-decision.ts
+/** Resolve effective revalidate/expire, preferring per-entry metadata. */
+function resolveRevalidate(options) {
+	return {
+		effectiveRevalidate: options.cacheControlMeta?.revalidate ?? options.revalidateSeconds,
+		effectiveExpire: options.cacheControlMeta === void 0 ? void 0 : options.cacheControlMeta.expire ?? options.expireSeconds
+	};
+}
+function buildCacheControl(disposition, kind, revalidate, expire) {
+	if (kind === "app-route") {
+		if (revalidate === 0) return NEVER_CACHE_CONTROL;
+		if (revalidate === Infinity) return STATIC_CACHE_CONTROL;
+	}
+	return buildCachedRevalidateCacheControl(disposition, revalidate, expire);
+}
+/**
+* Derive the `Cache-Control` string for an ISR response.
+*
+* Content guards (kind mismatch, query-variant-unproven, empty body) are the
+* caller's responsibility and must happen *before* this call. `cacheState`
+* must only be `"HIT"` or `"STALE"` when those guards have already passed.
+*/
+function decideIsr(options) {
+	if (options.cacheState === "MISS") return {
+		disposition: "MISS",
+		scheduleRegeneration: false,
+		cacheControl: ""
+	};
+	const { effectiveRevalidate, effectiveExpire } = resolveRevalidate(options);
+	if (options.cacheState === "HIT") return {
+		disposition: "HIT",
+		scheduleRegeneration: false,
+		cacheControl: buildCacheControl("HIT", options.kind, effectiveRevalidate, effectiveExpire)
+	};
+	return {
+		disposition: "STALE",
+		scheduleRegeneration: true,
+		cacheControl: buildCacheControl("STALE", options.kind, effectiveRevalidate, effectiveExpire)
+	};
+}
+/**
+* Build the `Cache-Control` string for a fresh MISS response whose ISR policy
+* is known (i.e. revalidate is set and > 0). Uses the unbounded SWR form when
+* no expire ceiling is available, exactly as `buildRevalidateCacheControl` does.
+*
+* Separate from `decideIsr` because a MISS doesn't read a cache entry and
+* therefore never has `cacheControlMeta`. `expireSeconds` here is the route
+* config ceiling passed directly from the caller (not a per-entry fallback).
+*/
+function buildMissIsrCacheControl(revalidateSeconds, expireSeconds) {
+	return buildRevalidateCacheControl(revalidateSeconds, expireSeconds);
+}
+/**
+* Build the `Cache-Control` string for a fresh (MISS) app-route response.
+*
+* Applies the same `revalidateSeconds=0`→NEVER and `Infinity`→STATIC gates
+* that `decideIsr` uses for app-route cached responses. `expireSeconds` is
+* the route config ceiling passed directly (not per-entry metadata fallback).
+*
+* Used by `applyRouteHandlerRevalidateHeader` which operates on a fresh
+* response that has no per-entry cache metadata.
+*/
+function buildAppRouteMissIsrCacheControl(revalidateSeconds, expireSeconds) {
+	if (revalidateSeconds === 0) return NEVER_CACHE_CONTROL;
+	if (revalidateSeconds === Infinity) return STATIC_CACHE_CONTROL;
+	return buildRevalidateCacheControl(revalidateSeconds, expireSeconds);
+}
+//#endregion
+export { NEVER_CACHE_CONTROL as ISR_NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL as ISR_NO_STORE_CACHE_CONTROL, buildAppRouteMissIsrCacheControl, buildMissIsrCacheControl, decideIsr };

package/dist/server/metadata-route-response.js

@@ -53,9 +53,9 @@ function getMetadataRouteFunctions(route) {
 	routeFunctionCache.set(route, functions);
 	return functions;
 }
-function matchMetadataRoute(route, cleanPathname, functions) {
+function matchMetadataRoute(route, cleanPathname, functions, getUrlParts) {
 	if (route.patternParts) {
-		const urlParts = cleanPathname.split("/").filter(Boolean);
+		const urlParts = getUrlParts();
 		if (functions.hasGeneratedImageMetadata && urlParts.length > 0) {
 			const params = matchMetadataRoutePattern(urlParts.slice(0, -1), route.patternParts);
 			if (params) return {
@@ -184,6 +184,8 @@ function serveStaticMetadataRoute(route) {
 	}
 }
 async function handleMetadataRouteRequest(options) {
+	let urlParts;
+	const getUrlParts = () => urlParts ??= options.cleanPathname.split("/").filter(Boolean);
 	for (const route of options.metadataRoutes) {
 		const functions = getMetadataRouteFunctions(route);
 		if (route.type === "sitemap" && route.isDynamic) {
@@ -193,7 +195,7 @@ async function handleMetadataRouteRequest(options) {
 				continue;
 			}
 		}
-		const match = matchMetadataRoute(route, options.cleanPathname, functions);
+		const match = matchMetadataRoute(route, options.cleanPathname, functions, getUrlParts);
 		if (!match) continue;
 		return route.isDynamic ? callDynamicMetadataRoute(route, match, options.makeThenableParams, functions) : serveStaticMetadataRoute(route);
 	}

package/dist/server/middleware-runtime.d.ts

@@ -19,6 +19,19 @@ type MiddlewareHandler = (request: NextRequest, event: NextFetchEvent) => Respon
 type ExecuteMiddlewareOptions = {
   basePath?: string;
   filePath?: string;
+  /**
+   * Whether the incoming request was inside the configured basePath. Drives
+   * the `nextUrl.basePath` the middleware observes: in-basePath requests are
+   * re-prefixed so NextURL reports the configured basePath, while
+   * out-of-basePath ("absolute path") requests stay un-prefixed so middleware
+   * sees `nextUrl.basePath === ""` (Next.js `getNextPathnameInfo` semantics —
+   * see test/e2e/middleware-base-path "should execute from absolute paths").
+   * When omitted it is derived from the request URL, which is correct for the
+   * Pages prod/deploy adapters because they pass the original (un-stripped)
+   * URL. Callers that pass an already-stripped URL (dev server, App Router)
+   * must set this explicitly.
+   */
+  hadBasePath?: boolean;
   i18nConfig?: NextI18nConfig | null;
   includeErrorDetails?: boolean;
   /**

package/dist/server/middleware-runtime.js

@@ -1,4 +1,5 @@
 import { normalizePathnameForRouteMatchStrict } from "../routing/utils.js";
+import { addBasePathToPathname, hasBasePath, stripBasePath } from "../utils/base-path.js";
 import "./server-globals.js";
 import { getRequestExecutionContext, runWithExecutionContext } from "../shims/request-context.js";
 import { MIDDLEWARE_REWRITE_HEADER } from "./headers.js";
@@ -99,12 +100,13 @@ function resolveMiddlewarePathname(request) {
 		return badRequestResponse();
 	}
 }
-function createNextRequest(request, normalizedPathname, i18nConfig, basePath, trailingSlash) {
+function createNextRequest(request, normalizedPathname, i18nConfig, basePath, trailingSlash, hadBasePath) {
 	const url = new URL(request.url);
 	let mwRequest = request.body && !request.bodyUsed ? request.clone() : request;
-	if (normalizedPathname !== url.pathname) {
+	const mwPathname = basePath && hadBasePath ? addBasePathToPathname(normalizedPathname, basePath) : normalizedPathname;
+	if (mwPathname !== url.pathname) {
 		const mwUrl = new URL(url);
-		mwUrl.pathname = normalizedPathname;
+		mwUrl.pathname = mwPathname;
 		mwRequest = new Request(mwUrl, mwRequest);
 	}
 	const nextConfig = basePath || i18nConfig || trailingSlash ? {
@@ -124,9 +126,11 @@ async function executeMiddleware(options) {
 		continue: false,
 		response: normalizedPathname
 	};
-	if (!matchesMiddleware(normalizedPathname, middlewareMatcher(options.module), options.request, options.i18nConfig)) return { continue: true };
-	const nextRequest = createNextRequest(options.request, normalizedPathname, options.i18nConfig, options.basePath, options.trailingSlash);
-	const fetchEvent = new NextFetchEvent({ page: normalizedPathname });
+	const hadBasePath = options.hadBasePath ?? (!options.basePath || hasBasePath(new URL(options.request.url).pathname, options.basePath));
+	const matchPathname = options.basePath ? stripBasePath(normalizedPathname, options.basePath) : normalizedPathname;
+	if (!matchesMiddleware(matchPathname, middlewareMatcher(options.module), options.request, options.i18nConfig)) return { continue: true };
+	const nextRequest = createNextRequest(options.request, normalizedPathname, options.i18nConfig, options.basePath, options.trailingSlash, hadBasePath);
+	const fetchEvent = new NextFetchEvent({ page: matchPathname });
 	let response;
 	try {
 		response = await middlewareFn(nextRequest, fetchEvent);
@@ -195,7 +199,7 @@ async function executeMiddleware(options) {
 		try {
 			const rewriteParsed = new URL(rewriteUrl, options.request.url);
 			const requestOrigin = new URL(options.request.url).origin;
-			if (rewriteParsed.origin === requestOrigin) rewritePath = rewriteParsed.pathname + rewriteParsed.search;
+			if (rewriteParsed.origin === requestOrigin) rewritePath = (options.basePath ? stripBasePath(rewriteParsed.pathname, options.basePath) : rewriteParsed.pathname) + rewriteParsed.search;
 			else rewritePath = rewriteParsed.href;
 		} catch {
 			rewritePath = rewriteUrl;

package/dist/server/middleware.js

@@ -85,6 +85,7 @@ async function runMiddleware(runner, middlewarePath, request, i18nConfig, basePa
 	return runGeneratedMiddleware({
 		basePath,
 		filePath: middlewarePath,
+		hadBasePath: true,
 		i18nConfig,
 		includeErrorDetails: process.env.NODE_ENV !== "production",
 		isDataRequest,