vinext 1.0.0-beta.8 → 1.0.0

package/dist/server/isr-cache.js

@@ -1,76 +1,14 @@
-import { getRequestExecutionContext } from "../shims/request-context.js";
 import { PRERENDER_REVALIDATE_HEADER, PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER } from "../utils/protocol-headers.js";
+import { getRequestExecutionContext } from "../shims/request-context.js";
 import { reportRequestError } from "./instrumentation.js";
 import { getCdnCacheAdapter } from "../shims/cdn-cache.js";
 import { fnv1a64 } from "../utils/hash.js";
 import { normalizeMountedSlotsHeader } from "./app-mounted-slots-header.js";
 import { APP_RSC_RENDER_MODE_NAVIGATION, getRscRenderModeCacheVariant } from "./app-rsc-render-mode.js";
 import { normalizeAppPageInterceptionProofPathname } from "./app-page-render-identity.js";
+import { getRevalidateSecret, isOnDemandRevalidateRequest, isRevalidateSecret } from "./revalidation-request.js";
 //#region src/server/isr-cache.ts
 /**
-* Build-time secret that authenticates on-demand revalidation requests, the
-* vinext analog of Next.js's prerender-manifest `previewModeId`.
-*
-* `res.revalidate()` loops back into the server via an internal `fetch()`. On
-* Cloudflare Workers that loopback can land on a *different* isolate than the
-* sender, so a per-process random secret would mismatch across isolates and
-* false-reject legitimate revalidations (and, symmetrically, two isolates with
-* independently-rolled secrets could never agree). The fix mirrors Next.js's
-* `previewModeId`: the secret is generated once at BUILD time and baked
-* (server-only — never into the client bundle) into every server bundle via the
-* `__VINEXT_REVALIDATE_SECRET` Vite `define`, so it is byte-for-byte identical in
-* every isolate. See `vinext build` CLI (`__VINEXT_SHARED_REVALIDATE_SECRET`) and
-* the `vinext:compiler-define-server` plugin. The sender attaches it as the
-* {@link PRERENDER_REVALIDATE_HEADER} value; the receiver authorizes a request
-* only when the incoming value equals this secret (see
-* {@link isOnDemandRevalidateRequest}).
-*
-* When the build-time define is absent — dev mode, and any path that doesn't
-* run through `vinext build` — we fall back to a lazily-generated random secret.
-* Those paths are single-process, but Vite can evaluate this module separately
-* in its RSC and SSR module graphs. Store the fallback on `globalThis` under a
-* registry symbol so every module copy in the process reads the same value.
-*/
-const _DEV_REVALIDATE_SECRET_KEY = Symbol.for("vinext.isrCache.devRevalidateSecret");
-function getRevalidateSecret() {
-	const baked = process.env.__VINEXT_REVALIDATE_SECRET;
-	if (baked) return baked;
-	const globals = globalThis;
-	const existing = globals[_DEV_REVALIDATE_SECRET_KEY];
-	if (typeof existing === "string") return existing;
-	const bytes = /* @__PURE__ */ new Uint8Array(32);
-	crypto.getRandomValues(bytes);
-	const secret = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
-	globals[_DEV_REVALIDATE_SECRET_KEY] = secret;
-	return secret;
-}
-/**
-* Constant-time string equality. Avoids leaking secret length / prefix via
-* early-exit timing on the on-demand revalidation auth check. Returns false
-* for length mismatch (the only safe option without revealing the secret
-* length, and equality is impossible anyway).
-*/
-function safeEqual(a, b) {
-	if (a.length !== b.length) return false;
-	let mismatch = 0;
-	for (let i = 0; i < a.length; i++) mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
-	return mismatch === 0;
-}
-function isRevalidateSecret(value) {
-	if (typeof value !== "string" || value.length === 0) return false;
-	return safeEqual(value, getRevalidateSecret());
-}
-/**
-* Authorize an incoming request as an on-demand revalidation trigger. Mirrors
-* Next.js's `checkIsOnDemandRevalidate`: the {@link PRERENDER_REVALIDATE_HEADER}
-* value must *equal* the process revalidate secret. Header presence alone is
-* NOT sufficient — see the security note on {@link PRERENDER_REVALIDATE_HEADER}.
-*/
-function isOnDemandRevalidateRequest(headerValue) {
-	if (typeof headerValue !== "string") return false;
-	return isRevalidateSecret(headerValue);
-}
-/**
 * Get a cache entry with staleness information.
 *
 * Returns { value, isStale: false } for fresh entries,
@@ -101,6 +39,15 @@ function isrCacheControl(revalidateSeconds, claims = {}) {
 	};
 }
 /**
+* The route-level `expireTime` only bounds a finite revalidate. Like Next.js,
+* a `revalidate = false` entry keeps no expire of its own and stays until it
+* is invalidated; only a cacheLife expire can bound it.
+* https://github.com/vercel/next.js/blob/v16.2.7/packages/next/src/build/index.ts#L3035-L3058
+*/
+function resolveRouteExpireSeconds(revalidateSeconds, expireSeconds) {
+	return revalidateSeconds === false || revalidateSeconds === Infinity ? void 0 : expireSeconds;
+}
+/**
 * Store a value in the ISR cache under the given write policy.
 */
 async function isrSet(key, data, policy) {
@@ -149,14 +96,15 @@ function coalesceOnDemandRevalidation(key, renderFn) {
 *
 * When `errorContext` is provided and the render function fails, the error
 * is reported via `reportRequestError` (instrumentation hook) with
-* `revalidateReason: "stale"`.
+* `revalidateReason: "stale"`, unless `shouldReport` suppresses an error that
+* an inner render boundary already reported.
 */
 function triggerBackgroundRegeneration(key, renderFn, errorContext) {
 	if (!getCdnCacheAdapter().ownsBackgroundRevalidation) return;
 	if (pendingRegenerations.has(key)) return;
-	const promise = renderFn().catch((err) => {
+	const promise = renderFn().catch(async (err) => {
 		console.error(`[vinext] ISR background regeneration failed for ${key}:`, err);
-		if (errorContext) reportRequestError(err instanceof Error ? err : new Error(String(err)), {
+		if (errorContext && (errorContext.shouldReport?.(err) ?? true)) await reportRequestError(err, {
 			path: key,
 			method: "GET",
 			headers: {}
@@ -224,7 +172,7 @@ function isrCacheKey(router, pathname, buildId) {
 * Cloudflare KV key under its 512-byte limit for long pathnames.
 */
 function appIsrCacheKey(pathname, suffix, buildId = process.env.__VINEXT_BUILD_ID) {
-	return buildCacheKey(buildId ? `app:${buildId}` : "app", pathname, suffix);
+	return buildCacheKey(buildId ? `app:v2:${buildId}` : "app:v2", pathname, suffix);
 }
 function appIsrHtmlKey(pathname) {
 	return appIsrCacheKey(pathname, "html");
@@ -255,7 +203,7 @@ function appIsrRscKey(pathname, mountedSlotsHeader, renderMode = APP_RSC_RENDER_
 	return appIsrCacheKey(pathname, variant ? `rsc:${variant}` : "rsc");
 }
 function appIsrRouteKey(pathname) {
-	return appIsrCacheKey(pathname, "route");
+	return appIsrCacheKey(pathname, pathname !== "/" && pathname.endsWith("/") ? "route:trailing-slash" : "route");
 }
 //#endregion
-export { PRERENDER_REVALIDATE_HEADER, PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER, appIsrCacheKey, appIsrHtmlKey, appIsrRouteKey, appIsrRscKey, buildAppPageCacheValue, buildPagesCacheValue, coalesceOnDemandRevalidation, getRevalidateSecret, isOnDemandRevalidateRequest, isRevalidateSecret, isrCacheControl, isrCacheKey, isrGet, isrSet, isrSetPrerenderedAppPage, normalizeMountedSlotsHeader, triggerBackgroundRegeneration };
+export { PRERENDER_REVALIDATE_HEADER, PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER, appIsrCacheKey, appIsrHtmlKey, appIsrRouteKey, appIsrRscKey, buildAppPageCacheValue, buildPagesCacheValue, coalesceOnDemandRevalidation, getRevalidateSecret, isOnDemandRevalidateRequest, isRevalidateSecret, isrCacheControl, isrCacheKey, isrGet, isrSet, isrSetPrerenderedAppPage, normalizeMountedSlotsHeader, resolveRouteExpireSeconds, triggerBackgroundRegeneration };

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

@@ -55,7 +55,7 @@ type DecideIsrOptions = {
  * 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;
+export 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
@@ -65,7 +65,7 @@ declare function decideIsr(options: DecideIsrOptions): IsrDecision;
  * 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 | false, expireSeconds?: number): string;
+export declare function buildMissIsrCacheControl(revalidateSeconds: number | false, expireSeconds?: number): string;
 /**
  * Build the `Cache-Control` string for a fresh (MISS) app-route response.
  *
@@ -76,6 +76,6 @@ declare function buildMissIsrCacheControl(revalidateSeconds: number | false, exp
  * Used by `applyRouteHandlerRevalidateHeader` which operates on a fresh
  * response that has no per-entry cache metadata.
  */
-declare function buildAppRouteMissIsrCacheControl(revalidateSeconds: number, expireSeconds?: number): string;
+export 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 };
+export { NEVER_CACHE_CONTROL as ISR_NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL as ISR_NO_STORE_CACHE_CONTROL };

package/dist/server/metadata-route-build-data.d.ts

@@ -16,8 +16,7 @@ type MetadataRouteEntryData = {
   headData?: MetadataRouteHeadData | null;
   fileDataBase64?: string;
 };
-declare function createMetadataRouteEntryData(route: MetadataFileRoute): MetadataRouteEntryData;
-declare function createMetadataRouteEntrySource(input: MetadataRouteEntrySourceInput): string;
-declare function createMetadataRouteEntriesSource(routes: readonly MetadataFileRoute[], moduleNames: ReadonlyMap<string, string>): string[];
-//#endregion
-export { createMetadataRouteEntriesSource, createMetadataRouteEntryData, createMetadataRouteEntrySource };
+export declare function createMetadataRouteEntryData(route: MetadataFileRoute): MetadataRouteEntryData;
+export declare function createMetadataRouteEntrySource(input: MetadataRouteEntrySourceInput): string;
+export declare function createMetadataRouteEntriesSource(routes: readonly MetadataFileRoute[], moduleNames: ReadonlyMap<string, string>): string[];
+//#endregion

package/dist/server/metadata-route-cache-policy.d.ts

@@ -1,6 +1,5 @@
 //#region src/server/metadata-route-cache-policy.d.ts
-declare function isMetadataResponseCacheable(response: {
+export declare function isMetadataResponseCacheable(response: {
   headers: Headers;
 }): boolean;
-//#endregion
-export { isMetadataResponseCacheable };
+//#endregion

package/dist/server/metadata-route-response.d.ts

@@ -11,7 +11,7 @@ type MetadataRouteBackgroundRegenerator = (key: string, renderFn: () => Promise<
   routePath: string;
   routeType: "route";
 }) => void;
-type MetadataRuntimeRoute = MetadataFileRoute & {
+export type MetadataRuntimeRoute = MetadataFileRoute & {
   fileDataBase64?: string;
 };
 type MetadataRouteRequestOptions = {
@@ -21,9 +21,10 @@ type MetadataRouteRequestOptions = {
   isrRouteKey?: (pathname: string) => string;
   isrSet?: MetadataRouteCacheSetter;
   makeThenableParams: MetadataRouteMakeThenableParams;
+  routePathname?: string;
   scheduleBackgroundRegeneration?: MetadataRouteBackgroundRegenerator;
 };
-type PrerenderableMetadataRoute = {
+export type PrerenderableMetadataRoute = {
   path: string;
   routePattern: string;
   routeSegments: string[];
@@ -33,8 +34,7 @@ type PrerenderableMetadataRoute = {
  * `"use cache"` function. These are safe to invoke during prerendering and the
  * resulting response can be seeded as an App Route artifact.
  */
-declare function getPrerenderableMetadataRoutePaths(metadataRoutes: readonly MetadataRuntimeRoute[]): Promise<PrerenderableMetadataRoute[]>;
-declare function isMetadataRouteRequestPath(metadataRoutes: readonly MetadataRuntimeRoute[], cleanPathname: string): boolean;
-declare function handleMetadataRouteRequest(options: MetadataRouteRequestOptions): Promise<Response | null>;
-//#endregion
-export { MetadataRuntimeRoute, PrerenderableMetadataRoute, getPrerenderableMetadataRoutePaths, handleMetadataRouteRequest, isMetadataRouteRequestPath };
+export declare function getPrerenderableMetadataRoutePaths(metadataRoutes: readonly MetadataRuntimeRoute[]): Promise<PrerenderableMetadataRoute[]>;
+export declare function isMetadataRouteRequestPath(metadataRoutes: readonly MetadataRuntimeRoute[], cleanPathname: string): boolean;
+export declare function handleMetadataRouteRequest(options: MetadataRouteRequestOptions): Promise<Response | null>;
+//#endregion

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

@@ -1,13 +1,18 @@
-import { closeAfterResponse, createRequestContext, markFullyBufferedBody, runWithRequestContext } from "../shims/unified-request-context.js";
+import { markFullyBufferedBody } from "./fully-buffered-response.js";
+import { closeAfterResponse, createRequestContext, runWithRequestContext } from "../shims/unified-request-context.js";
+import { decodeMatchedParams } from "../routing/utils.js";
 import { getRequestExecutionContext } from "../shims/request-context.js";
 import { VINEXT_METADATA_ROUTE_CACHE_HEADER } from "./headers.js";
 import { notFoundResponse } from "./http-error-responses.js";
-import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
+import { beginRouteCacheability, markRouteCacheabilityExplicitResponsePolicy } from "../shims/cacheability-classification.js";
+import { hasCdnResponsePolicy, hasExplicitNonCacheableResponsePolicy } from "./cache-control.js";
 import { isrCacheControl } from "./isr-cache.js";
+import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
 import { _consumeRequestScopedCacheLife, cacheLifeProfiles } from "../shims/cache-request-state.js";
 import { ensureFetchPatch, getCollectedFetchTags, setCurrentFetchSoftTags } from "../shims/fetch-cache.js";
 import { isValidMetadataImageId, manifestToJson, matchMetadataRoutePattern, robotsToText, sitemapToXml } from "./metadata-routes.js";
 import { applyPrerenderCacheLifeHeader, applyPrerenderCacheTagsHeader } from "./prerender-cache-life-header.js";
+import { canonicalizeAppPageParams } from "./app-page-segment-state.js";
 import { buildPageCacheTags } from "./implicit-tags.js";
 import { buildAppRouteCacheValue, buildRouteHandlerCachedResponse } from "./app-route-handler-response.js";
 import { isMetadataResponseCacheable } from "./metadata-route-cache-policy.js";
@@ -49,6 +54,7 @@ function metadataRouteCacheHeader(route) {
 	return CACHE_HEADERS.revalidate;
 }
 function withMetadataRouteCacheHeader(response, route) {
+	if (hasCdnResponsePolicy(response.headers) && !hasExplicitNonCacheableResponsePolicy(response.headers)) markRouteCacheabilityExplicitResponsePolicy();
 	const headers = new Headers(response.headers);
 	if (!headers.has("Cache-Control")) headers.set("Cache-Control", metadataRouteCacheHeader(route));
 	return new Response(response.body, {
@@ -57,13 +63,18 @@ function withMetadataRouteCacheHeader(response, route) {
 		statusText: response.statusText
 	});
 }
+function beginMetadataRouteCacheability(route) {
+	beginRouteCacheability("app-route", route.patternParts ? `/${route.patternParts.join("/")}` : route.servedUrl);
+}
 function getMetadataRouteFunctions(route) {
 	const cached = routeFunctionCache.get(route);
 	if (cached) return cached;
 	const generateImageMetadata = route.isDynamic && isImageMetadataRoute(route) ? readFunction(route.module, "generateImageMetadata") : null;
 	const functions = {
 		defaultExport: route.isDynamic ? readFunction(route.module, "default") : null,
+		dynamicParams: route.isDynamic && typeof route.module?.dynamicParams === "boolean" ? route.module.dynamicParams : void 0,
 		generateImageMetadata,
+		generateStaticParams: route.isDynamic ? readFunction(route.module, "generateStaticParams") : null,
 		generateSitemaps: route.type === "sitemap" && route.isDynamic ? readFunction(route.module, "generateSitemaps") : null,
 		hasGeneratedImageMetadata: route.isDynamic && isImageMetadataRoute(route) && Boolean(generateImageMetadata)
 	};
@@ -255,6 +266,39 @@ function matchMetadataRoute(route, cleanPathname, functions, getUrlParts) {
 		imageId: null
 	} : null;
 }
+function metadataRouteParamNames(patternParts) {
+	return patternParts.flatMap((part) => {
+		if (!part.startsWith(":")) return [];
+		return [part.slice(1, part.endsWith("+") || part.endsWith("*") ? -1 : void 0)];
+	});
+}
+function metadataRouteOptionalCatchAllParamNames(patternParts) {
+	return patternParts.flatMap((part) => part.startsWith(":") && part.endsWith("*") ? [part.slice(1, -1)] : []);
+}
+function metadataRouteRawParams(route, match, routePathname) {
+	const urlParts = routePathname.split("/").filter(Boolean);
+	if (match.imageId !== null) urlParts.pop();
+	const params = Object.create(null);
+	let urlIndex = 0;
+	for (const part of route.patternParts ?? []) {
+		if (!part.startsWith(":")) {
+			urlIndex++;
+			continue;
+		}
+		const isCatchAll = part.endsWith("+") || part.endsWith("*");
+		const name = part.slice(1, isCatchAll ? -1 : void 0);
+		if (!isCatchAll) {
+			const value = urlParts[urlIndex++];
+			if (value !== void 0) params[name] = value;
+			continue;
+		}
+		const matchedValue = match.params?.[name];
+		const valueCount = Array.isArray(matchedValue) ? matchedValue.length : matchedValue ? 1 : 0;
+		if (valueCount > 0) params[name] = urlParts.slice(urlIndex, urlIndex + valueCount);
+		urlIndex += valueCount;
+	}
+	return params;
+}
 function findGeneratedSitemapId(entries, rawId) {
 	if (!Array.isArray(entries)) return null;
 	for (const entry of entries) {
@@ -385,6 +429,7 @@ async function handleMetadataRouteRequest(options) {
 		if (route.type === "sitemap" && route.isDynamic) {
 			if (functions.generateSitemaps) {
 				if (isGeneratedSitemapPath(route, options.cleanPathname)) {
+					beginMetadataRouteCacheability(route);
 					const render = async () => {
 						setCurrentFetchSoftTags(buildMetadataRouteTags(route, options.cleanPathname, []));
 						const response = await handleGeneratedSitemap(route, options.cleanPathname, functions);
@@ -403,6 +448,27 @@ async function handleMetadataRouteRequest(options) {
 		}
 		const match = matchMetadataRoute(route, options.cleanPathname, functions, getUrlParts);
 		if (!match) continue;
+		beginMetadataRouteCacheability(route);
+		const rawParams = route.patternParts ? metadataRouteRawParams(route, match, options.routePathname ?? options.cleanPathname) : Object.create(null);
+		if (route.patternParts) {
+			const runtimeParams = { ...rawParams };
+			decodeMatchedParams(runtimeParams);
+			match.params = runtimeParams;
+		}
+		if (route.isDynamic && isImageMetadataRoute(route) && functions.dynamicParams === false) {
+			const validationParams = { ...rawParams };
+			canonicalizeAppPageParams(validationParams);
+			const { validateAppPageDynamicParams } = await import("./app-page-request.js");
+			const dynamicParamsResponse = await validateAppPageDynamicParams({
+				enforceStaticParamsOnly: true,
+				generateStaticParams: functions.generateStaticParams,
+				isDynamicRoute: Boolean(route.patternParts),
+				optionalCatchAllParamNames: metadataRouteOptionalCatchAllParamNames(route.patternParts ?? []),
+				params: validationParams,
+				requiredParamNames: metadataRouteParamNames(route.patternParts ?? [])
+			});
+			if (dynamicParamsResponse) return dynamicParamsResponse;
+		}
 		const render = async () => {
 			setCurrentFetchSoftTags(buildMetadataRouteTags(route, options.cleanPathname, []));
 			return captureRenderedMetadataRoute(route.isDynamic ? await callDynamicMetadataRoute(route, match, options.makeThenableParams, functions) : serveStaticMetadataRoute(route));

package/dist/server/metadata-routes.d.ts

@@ -1,5 +1,5 @@
 //#region src/server/metadata-routes.d.ts
-type SitemapEntry = {
+export type SitemapEntry = {
   url: string;
   lastModified?: string | Date;
   changeFrequency?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
@@ -44,12 +44,12 @@ type RobotsRule = {
   crawlDelay?: number;
   other?: Record<string, string | number | Array<string | number>>;
 };
-type RobotsConfig = {
+export type RobotsConfig = {
   rules: RobotsRule | RobotsRule[];
   sitemap?: string | string[];
   host?: string;
 };
-type ManifestConfig = {
+export type ManifestConfig = {
   name?: string;
   short_name?: string;
   description?: string;
@@ -66,7 +66,7 @@ type ManifestConfig = {
   [key: string]: unknown;
 };
 /** Map of metadata file base names to their URL path and content type. */
-declare const METADATA_FILE_MAP: Record<string, {
+export declare const METADATA_FILE_MAP: Record<string, {
   /** URL path this file is served at */
   urlPath: string;
   /** Content type for the response */
@@ -83,15 +83,15 @@ declare const METADATA_FILE_MAP: Record<string, {
 /**
  * Convert a sitemap array to XML string.
  */
-declare function sitemapToXml(entries: SitemapEntry[]): string;
+export declare function sitemapToXml(entries: SitemapEntry[]): string;
 /**
  * Convert a robots config to text format.
  */
-declare function robotsToText(config: RobotsConfig): string;
+export declare function robotsToText(config: RobotsConfig): string;
 /**
  * Convert a manifest config to JSON string.
  */
-declare function manifestToJson(config: ManifestConfig): string;
+export declare function manifestToJson(config: ManifestConfig): string;
 /**
  * Compute the static URL for a metadata file given its app directory
  * parent path and filename.
@@ -101,8 +101,8 @@ declare function manifestToJson(config: ManifestConfig): string;
  *   fillStaticMetadataSegment("/blog/[slug]", "favicon.ico") -> "/blog/-/favicon.ico"
  *   fillStaticMetadataSegment("/(group)/group", "icon.png") -> "/group/icon-131tc6.png"
  */
-declare function fillStaticMetadataSegment(appDirPath: string, lastSegment: string): string;
-type MetadataFileRoute = {
+export declare function fillStaticMetadataSegment(appDirPath: string, lastSegment: string): string;
+export type MetadataFileRoute = {
   /** Type of metadata file */
   type: string;
   /** Whether this is a dynamic (code-generated) route */
@@ -128,7 +128,7 @@ type MetadataFileRoute = {
   /** Sibling .alt.txt file for static social image metadata routes. */
   altFilePath?: string;
 };
-type MetadataRouteHeadData = {
+export type MetadataRouteHeadData = {
   kind: "favicon" | "icon" | "apple";
   href: string;
   type?: string;
@@ -144,16 +144,15 @@ type MetadataRouteHeadData = {
   kind: "manifest";
   href: string;
 };
-declare function getMetadataRouteKind(route: Pick<MetadataFileRoute, "type">): MetadataRouteHeadData["kind"] | null;
-declare function getMetadataImageRouteKind(route: Pick<MetadataFileRoute, "type">): Extract<MetadataRouteHeadData["kind"], "icon" | "apple" | "openGraph" | "twitter"> | null;
-declare function isValidMetadataImageId(id: string): boolean;
-declare function matchMetadataRoutePattern(urlParts: string[], patternParts: string[]): Record<string, string | string[]> | null;
-declare function matchMetadataFileBaseName(metaType: string, baseName: string): string | null;
+export declare function getMetadataRouteKind(route: Pick<MetadataFileRoute, "type">): MetadataRouteHeadData["kind"] | null;
+export declare function getMetadataImageRouteKind(route: Pick<MetadataFileRoute, "type">): Extract<MetadataRouteHeadData["kind"], "icon" | "apple" | "openGraph" | "twitter"> | null;
+export declare function isValidMetadataImageId(id: string): boolean;
+export declare function matchMetadataRoutePattern(urlParts: string[], patternParts: string[]): Record<string, string | string[]> | null;
+export declare function matchMetadataFileBaseName(metaType: string, baseName: string): string | null;
 /** Clear the {@link scanMetadataFiles} cache (call when app files change in dev). */
-declare function invalidateMetadataFileCache(): void;
+export declare function invalidateMetadataFileCache(): void;
 /**
  * Scan an app directory for metadata files.
  */
-declare function scanMetadataFiles(appDir: string): MetadataFileRoute[];
-//#endregion
-export { METADATA_FILE_MAP, ManifestConfig, MetadataFileRoute, MetadataRouteHeadData, RobotsConfig, SitemapEntry, fillStaticMetadataSegment, getMetadataImageRouteKind, getMetadataRouteKind, invalidateMetadataFileCache, isValidMetadataImageId, manifestToJson, matchMetadataFileBaseName, matchMetadataRoutePattern, robotsToText, scanMetadataFiles, sitemapToXml };
+export declare function scanMetadataFiles(appDir: string): MetadataFileRoute[];
+//#endregion

package/dist/server/middleware-matcher-pattern.d.ts

@@ -1,6 +1,6 @@
 import { HasCondition } from "../config/next-config.js";
 //#region src/server/middleware-matcher-pattern.d.ts
-type CompiledMiddlewareMatcherPattern = {
+export type CompiledMiddlewareMatcherPattern = {
   regexp: RegExp;
   error?: never;
 } | {
@@ -8,14 +8,13 @@ type CompiledMiddlewareMatcherPattern = {
   error: string;
   kind: "invalid" | "unsafe";
 };
-type MiddlewareMatcherObject = {
+export type MiddlewareMatcherObject = {
   source: string;
   locale?: false;
   has?: HasCondition[];
   missing?: HasCondition[];
 };
-declare function isValidMiddlewareMatcherObjectConfig(value: unknown): value is MiddlewareMatcherObject;
-declare function compileMiddlewareMatcherPattern(source: string): CompiledMiddlewareMatcherPattern;
-declare function validateMiddlewareMatcherPatterns(value: unknown): void;
-//#endregion
-export { CompiledMiddlewareMatcherPattern, MiddlewareMatcherObject, compileMiddlewareMatcherPattern, isValidMiddlewareMatcherObjectConfig, validateMiddlewareMatcherPatterns };
+export declare function isValidMiddlewareMatcherObjectConfig(value: unknown): value is MiddlewareMatcherObject;
+export declare function compileMiddlewareMatcherPattern(source: string): CompiledMiddlewareMatcherPattern;
+export declare function validateMiddlewareMatcherPatterns(value: unknown): void;
+//#endregion

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

@@ -1,14 +1,21 @@
 import { NextI18nConfig } from "../config/next-config.js";
 import { MiddlewareMatcherObject } from "./middleware-matcher-pattern.js";
 //#region src/server/middleware-matcher.d.ts
-type MatcherConfig = string | Array<string | MiddlewareMatcherObject>;
-type MiddlewareLocaleMatchContext = {
+export type MatcherConfig = string | Array<string | MiddlewareMatcherObject>;
+export type MiddlewareLocaleMatchContext = {
   kind: "defaulted";
   defaultLocale: string;
 } | {
   kind: "internal" | "literal";
 };
-declare function matchesMiddleware(pathname: string, matcher: MatcherConfig | undefined, request?: Request, i18nConfig?: NextI18nConfig | null, localeContext?: MiddlewareLocaleMatchContext): boolean;
-declare function matchPattern(pathname: string, pattern: string): boolean;
-//#endregion
-export { MatcherConfig, MiddlewareLocaleMatchContext, matchPattern, matchesMiddleware };
+export declare function matchesMiddleware(pathname: string, matcher: MatcherConfig | undefined, request?: Request, i18nConfig?: NextI18nConfig | null, localeContext?: MiddlewareLocaleMatchContext): boolean;
+/**
+ * Whether a pathname can reach middleware, ignoring request-specific
+ * `has`/`missing` conditions. This is deliberately separate from
+ * `matchesMiddleware`: ordinary middleware execution must still evaluate the
+ * full request, while cacheability certification needs a stable answer for
+ * every request that can share the pathname's cache entry.
+ */
+export declare function matchesMiddlewarePathname(pathname: string, matcher: MatcherConfig | undefined, i18nConfig?: NextI18nConfig | null, localeContext?: MiddlewareLocaleMatchContext): boolean;
+export declare function matchPattern(pathname: string, pattern: string): boolean;
+//#endregion

package/dist/server/middleware-matcher.js

@@ -27,6 +27,27 @@ function matchesMiddleware(pathname, matcher, request, i18nConfig, localeContext
 	}
 	return false;
 }
+/**
+* Whether a pathname can reach middleware, ignoring request-specific
+* `has`/`missing` conditions. This is deliberately separate from
+* `matchesMiddleware`: ordinary middleware execution must still evaluate the
+* full request, while cacheability certification needs a stable answer for
+* every request that can share the pathname's cache entry.
+*/
+function matchesMiddlewarePathname(pathname, matcher, i18nConfig, localeContext) {
+	if (!matcher) return true;
+	if (typeof matcher === "string") return matchMatcherPattern(pathname, matcher, i18nConfig, localeContext);
+	if (!Array.isArray(matcher)) return true;
+	for (const item of matcher) {
+		if (typeof item === "string") {
+			if (matchMatcherPattern(pathname, item, i18nConfig, localeContext)) return true;
+			continue;
+		}
+		if (!isValidMiddlewareMatcherObjectConfig(item)) return true;
+		if (matchObjectMatcher(pathname, item, i18nConfig, localeContext)) return true;
+	}
+	return false;
+}
 function matchMatcherPattern(pathname, pattern, i18nConfig, localeContext) {
 	if (!i18nConfig) return matchPattern(pathname, pattern);
 	if (localeContext) {
@@ -66,4 +87,4 @@ function compileMatcherPattern(pattern) {
 	return UNSAFE_MATCHER_PATTERN;
 }
 //#endregion
-export { matchPattern, matchesMiddleware };
+export { matchPattern, matchesMiddleware, matchesMiddlewarePathname };

package/dist/server/middleware-path-to-regexp.d.ts

@@ -1,14 +1,13 @@
 //#region src/server/middleware-path-to-regexp.d.ts
-type MiddlewarePathToken = string | MiddlewarePathKey;
-type MiddlewarePathKey = {
+export type MiddlewarePathToken = string | MiddlewarePathKey;
+export type MiddlewarePathKey = {
   name: string | number;
   prefix: string;
   suffix: string;
   pattern: string;
   modifier: string;
 };
-declare function parseMiddlewarePath(value: string): MiddlewarePathToken[];
-declare function normalizeMiddlewarePathTokens(tokens: MiddlewarePathToken[]): MiddlewarePathToken[];
-declare function middlewarePathTokensToRegExp(tokens: MiddlewarePathToken[]): RegExp;
-//#endregion
-export { MiddlewarePathKey, MiddlewarePathToken, middlewarePathTokensToRegExp, normalizeMiddlewarePathTokens, parseMiddlewarePath };
+export declare function parseMiddlewarePath(value: string): MiddlewarePathToken[];
+export declare function normalizeMiddlewarePathTokens(tokens: MiddlewarePathToken[]): MiddlewarePathToken[];
+export declare function middlewarePathTokensToRegExp(tokens: MiddlewarePathToken[]): RegExp;
+//#endregion

package/dist/server/middleware-path-to-regexp.js

@@ -211,15 +211,17 @@ function middlewarePathTokensToRegExp(tokens) {
 		}
 		const prefix = escapeRegex(token.prefix);
 		const suffix = escapeRegex(token.suffix);
-		if (token.pattern) if (prefix || suffix) if (token.modifier === "+" || token.modifier === "*") {
-			const optional = token.modifier === "*" ? "?" : "";
-			route += `(?:${prefix}((?:${token.pattern})(?:${suffix}${prefix}(?:${token.pattern}))*)${suffix})${optional}`;
-		} else route += `(?:${prefix}(${token.pattern})${suffix})${token.modifier}`;
-		else {
-			if (token.modifier === "+" || token.modifier === "*") throw new TypeError(`Can not repeat "${token.name}" without a prefix and suffix`);
-			route += `(${token.pattern})${token.modifier}`;
-		}
-		else route += `(?:${prefix}${suffix})${token.modifier}`;
+		if (token.pattern) {
+			if (prefix || suffix) {
+				if (token.modifier === "+" || token.modifier === "*") {
+					const optional = token.modifier === "*" ? "?" : "";
+					route += `(?:${prefix}((?:${token.pattern})(?:${suffix}${prefix}(?:${token.pattern}))*)${suffix})${optional}`;
+				} else route += `(?:${prefix}(${token.pattern})${suffix})${token.modifier}`;
+			} else {
+				if (token.modifier === "+" || token.modifier === "*") throw new TypeError(`Can not repeat "${token.name}" without a prefix and suffix`);
+				route += `(${token.pattern})${token.modifier}`;
+			}
+		} else route += `(?:${prefix}${suffix})${token.modifier}`;
 	}
 	route += `${delimiterRegex}?$`;
 	return new RegExp(route, "i");

package/dist/server/middleware-response-headers.d.ts

@@ -1,5 +1,5 @@
 //#region src/server/middleware-response-headers.d.ts
-declare function mergeVaryHeader(target: Headers, value: string): void;
+export declare function mergeVaryHeader(target: Headers, value: string): void;
 /**
  * Merge middleware response headers into a target Headers object.
  *
@@ -7,6 +7,5 @@ declare function mergeVaryHeader(target: Headers, value: string): void;
  * contribute values. All other headers use set() so middleware owns singular
  * response headers like Cache-Control.
  */
-declare function mergeMiddlewareResponseHeaders(target: Headers, middlewareHeaders: Headers | null): void;
-//#endregion
-export { mergeMiddlewareResponseHeaders, mergeVaryHeader };
+export declare function mergeMiddlewareResponseHeaders(target: Headers, middlewareHeaders: Headers | null): void;
+//#endregion

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

@@ -2,9 +2,11 @@ import { NextI18nConfig } from "../config/next-config.js";
 import { ExecutionContextLike } from "../shims/request-context.js";
 import { NextFetchEvent, NextRequest } from "../shims/server.js";
 //#region src/server/middleware-runtime.d.ts
-type MiddlewareModule = Record<string, unknown>;
-type MiddlewareResult = {
+export type MiddlewareModule = Record<string, unknown>;
+export type MiddlewareResult = {
   continue: boolean;
+  /** True when this pathname can match middleware for some request context. */
+  pathnameEligible?: boolean;
   redirectUrl?: string;
   redirectStatus?: number;
   rewriteUrl?: string;
@@ -42,6 +44,10 @@ type ExecuteMiddlewareOptions = {
   isProxy: boolean;
   module: MiddlewareModule;
   normalizedPathname?: string;
+  /** Called only after the configured matcher accepts this request. */
+  onMatch?: () => void;
+  /** Called when the pathname matches, before request `has`/`missing` checks. */
+  onPathMatch?: () => void;
   /**
    * The caller already created an isolated body branch for middleware. This
    * lets App Router normalize that branch's URL and headers without adding a
@@ -61,12 +67,11 @@ type ExecuteMiddlewareOptions = {
 type RunGeneratedMiddlewareOptions = ExecuteMiddlewareOptions & {
   ctx?: ExecutionContextLike;
 };
-declare function createMiddlewareMissingExportError(filePath: string | undefined, isProxy: boolean): Error;
-declare function resolveMiddlewareModuleHandler(mod: MiddlewareModule, options: {
+export declare function createMiddlewareMissingExportError(filePath: string | undefined, isProxy: boolean): Error;
+export declare function resolveMiddlewareModuleHandler(mod: MiddlewareModule, options: {
   filePath?: string;
   isProxy: boolean;
 }): MiddlewareHandler;
-declare function executeMiddleware(options: ExecuteMiddlewareOptions): Promise<MiddlewareResult>;
-declare function runGeneratedMiddleware(options: RunGeneratedMiddlewareOptions): Promise<MiddlewareResult>;
-//#endregion
-export { MiddlewareModule, MiddlewareResult, createMiddlewareMissingExportError, executeMiddleware, resolveMiddlewareModuleHandler, runGeneratedMiddleware };
+export declare function executeMiddleware(options: ExecuteMiddlewareOptions): Promise<MiddlewareResult>;
+export declare function runGeneratedMiddleware(options: RunGeneratedMiddlewareOptions): Promise<MiddlewareResult>;
+//#endregion