vinext 1.0.0-beta.9 → 1.0.1

package/dist/server/isr-cache.js

@@ -1,76 +1,15 @@
-import { getRequestExecutionContext } from "../shims/request-context.js";
 import { PRERENDER_REVALIDATE_HEADER, PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER } from "../utils/protocol-headers.js";
+import { normalizePathnameForRouteMatch } from "../routing/utils.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 +40,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 +97,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: {}
@@ -216,6 +165,10 @@ function buildCacheKey(prefix, pathname, suffix) {
 function isrCacheKey(router, pathname, buildId) {
 	return buildCacheKey(buildId ? `${router}:${buildId}` : router, pathname);
 }
+/** Build and request time share the same locale-stripped Pages pathname identity. */
+function pagesIsrCacheKey(pathname, buildId, i18nCacheVariant) {
+	return isrCacheKey("pages:v2", normalizeCachePathname(normalizePathnameForRouteMatch(pathname)) + (i18nCacheVariant ? `::i18n=${encodeURIComponent(i18nCacheVariant)}` : ""), buildId);
+}
 /**
 * Compute an App Router ISR key for one cache artifact.
 *
@@ -224,7 +177,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 +208,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, pagesIsrCacheKey, 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-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,21 +1,31 @@
-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, markRouteCacheabilityResponseBodyComplete, recordRouteCacheability } from "../shims/cacheability-classification.js";
+import { NEVER_CACHE_CONTROL, applyCdnResponseHeaders, hasCdnResponsePolicy } from "./cache-control.js";
+import { buildAppRouteMissIsrCacheControl } from "./isr-decision.js";
 import { isrCacheControl } from "./isr-cache.js";
-import { _consumeRequestScopedCacheLife, cacheLifeProfiles } from "../shims/cache-request-state.js";
+import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
+import { isRenderDynamicLatched } from "../shims/internal/headers-state.js";
+import { getActiveDraftModeState, getHeadersContext, hasDraftModeCookieHeader, replaceHeadersContext } from "../shims/headers.js";
+import { _consumeRequestScopedCacheLife } 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";
+import { createStaticGenerationHeadersContext } from "./app-static-generation.js";
+import { completeAppRouteHandlerResponse } from "./app-route-handler-execution.js";
 //#region src/server/metadata-route-response.ts
 function isOuterMetadataCacheEnabled() {
 	return process.env.NODE_ENV !== "development";
 }
 const routeFunctionCache = /* @__PURE__ */ new WeakMap();
+const userMetadataResponses = /* @__PURE__ */ new WeakSet();
 const USE_CACHE_FUNCTION_SYMBOL = Symbol.for("vinext.useCacheFunction");
 const CACHE_HEADERS = {
 	noCache: "no-cache, no-store",
@@ -48,14 +58,20 @@ function metadataRouteCacheHeader(route) {
 	if (route.isDynamic && isImageMetadataRoute(route) && process.env.NODE_ENV === "development") return CACHE_HEADERS.noCache;
 	return CACHE_HEADERS.revalidate;
 }
-function withMetadataRouteCacheHeader(response, route) {
-	const headers = new Headers(response.headers);
-	if (!headers.has("Cache-Control")) headers.set("Cache-Control", metadataRouteCacheHeader(route));
-	return new Response(response.body, {
-		headers,
-		status: response.status,
-		statusText: response.statusText
-	});
+function beginMetadataRouteCacheability(route) {
+	const dynamic = route.module?.dynamic;
+	if (dynamic === "force-static" || dynamic === "error") {
+		const current = getHeadersContext();
+		const staticContext = createStaticGenerationHeadersContext({
+			dynamicConfig: dynamic,
+			routeKind: "route",
+			routePattern: route.servedUrl,
+			draftModeEnabled: getActiveDraftModeState() ?? void 0,
+			draftModeSecret: current?.draftModeSecret
+		});
+		replaceHeadersContext(staticContext);
+	}
+	beginRouteCacheability("app-route", route.patternParts ? `/${route.patternParts.join("/")}` : route.servedUrl);
 }
 function getMetadataRouteFunctions(route) {
 	const cached = routeFunctionCache.get(route);
@@ -63,7 +79,9 @@ function getMetadataRouteFunctions(route) {
 	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)
 	};
@@ -126,29 +144,68 @@ function markMetadataRouteCacheValue(value) {
 function buildMetadataRouteTags(route, cleanPathname, collectedTags) {
 	return buildPageCacheTags(cleanPathname, collectedTags, route.routeSegments ?? [], "route");
 }
-function captureRenderedMetadataRoute(response) {
-	const cacheLife = _consumeRequestScopedCacheLife();
+async function captureRenderedMetadataRoute(response, route, cleanPathname) {
+	const isUserResponse = userMetadataResponses.has(response);
+	let completed = false;
+	if (isOuterMetadataCacheEnabled()) {
+		const result = await completeAppRouteHandlerResponse(response);
+		response = result.response;
+		completed = result.completed;
+		if (completed) markRouteCacheabilityResponseBodyComplete();
+	}
+	const browserCacheControl = response.headers.get("Cache-Control") ?? void 0;
+	const hasUserPolicy = isUserResponse && hasCdnResponsePolicy(response.headers);
+	if (hasUserPolicy) markRouteCacheabilityExplicitResponsePolicy();
+	const observedCacheLife = _consumeRequestScopedCacheLife();
 	const collectedTags = getCollectedFetchTags();
+	const revalidate = typeof route.module?.revalidate === "number" ? route.module.revalidate : Infinity;
+	const frameworkRevalidate = Math.min(observedCacheLife?.revalidate ?? Infinity, revalidate);
+	const cacheLife = {
+		...observedCacheLife,
+		revalidate: frameworkRevalidate
+	};
+	const cacheable = (response.status < 400 || response.status === 404) && completed && !isRenderDynamicLatched() && !getActiveDraftModeState() && !hasDraftModeCookieHeader() && route.module?.dynamic !== "force-dynamic" && frameworkRevalidate > 0 && !response.headers.has("set-cookie");
+	const cacheControl = cacheable ? buildAppRouteMissIsrCacheControl(frameworkRevalidate, cacheLife?.expire) : NEVER_CACHE_CONTROL;
+	if (isUserResponse && !hasUserPolicy) {
+		response = new Response(response.body, {
+			headers: new Headers(response.headers),
+			status: response.status,
+			statusText: response.statusText
+		});
+		applyCdnResponseHeaders(response.headers, { cacheControl: isOuterMetadataCacheEnabled() ? cacheControl : metadataRouteCacheHeader(route) });
+	}
+	recordRouteCacheability(cacheable ? {
+		cacheable: true,
+		cacheControl,
+		tags: buildMetadataRouteTags(route, cleanPathname, collectedTags)
+	} : {
+		cacheable: false,
+		dynamicUsage: true
+	});
 	if (process.env.VINEXT_PRERENDER === "1") {
-		applyPrerenderCacheLifeHeader(response.headers, cacheLife);
+		applyPrerenderCacheLifeHeader(response.headers, {
+			...cacheLife,
+			revalidate: cacheable ? frameworkRevalidate : 0
+		});
 		applyPrerenderCacheTagsHeader(response.headers, collectedTags);
 	}
 	return {
+		browserCacheControl,
 		cacheLife,
+		cacheable,
 		collectedTags,
 		response
 	};
 }
 async function writeRenderedMetadataRoute(options, route, routeKey, rendered, previousEntry) {
-	if (!options.isrSet || !rendered.response.ok || !isMetadataResponseCacheable(rendered.response)) return;
+	if (!options.isrSet || !rendered.cacheable) return;
 	const previousCacheControl = previousEntry?.value.cacheControl;
-	const defaultCacheLife = cacheLifeProfiles.default;
-	const revalidate = rendered.cacheLife?.revalidate ?? previousCacheControl?.revalidate ?? defaultCacheLife.revalidate ?? 900;
-	const expire = rendered.cacheLife?.expire ?? previousCacheControl?.expire ?? defaultCacheLife.expire;
+	const revalidate = rendered.cacheLife?.revalidate ?? previousCacheControl?.revalidate ?? (typeof route.module?.revalidate === "number" ? route.module.revalidate : false);
+	const expire = rendered.cacheLife?.expire ?? previousCacheControl?.expire;
 	const stale = resolveClientStaleTimeSeconds(rendered.cacheLife) ?? previousCacheControl?.stale;
-	const value = markMetadataRouteCacheValue(await buildAppRouteCacheValue(rendered.response));
+	const value = markMetadataRouteCacheValue(await buildAppRouteCacheValue(rendered.response, rendered.browserCacheControl));
 	await options.isrSet(routeKey, value, {
-		cacheControl: isrCacheControl(revalidate, {
+		cacheControl: isrCacheControl(revalidate === Infinity ? false : revalidate, {
 			...typeof expire === "number" ? { expireSeconds: expire } : {},
 			...typeof stale === "number" ? { staleSeconds: stale } : {}
 		}),
@@ -160,16 +217,21 @@ async function runMetadataRouteRegeneration(options, route, render, routeKey, pr
 	try {
 		await runWithRequestContext(requestContext, async () => {
 			ensureFetchPatch();
+			beginMetadataRouteCacheability(route);
 			setCurrentFetchSoftTags(buildMetadataRouteTags(route, options.cleanPathname, []));
 			const rendered = await render();
-			if (rendered) await writeRenderedMetadataRoute(options, route, routeKey, rendered, previousEntry);
+			if (rendered) try {
+				await writeRenderedMetadataRoute(options, route, routeKey, rendered, previousEntry);
+			} finally {
+				rendered.response.body?.cancel().catch(() => {});
+			}
 		});
 	} finally {
 		await closeAfterResponse(requestContext);
 	}
 }
-async function readMatchedPrerenderedMetadataRouteResponse(options, route, functions, render) {
-	if (!isOuterMetadataCacheEnabled() || !options.isrGet || !options.isrRouteKey) return {
+async function readMatchedPrerenderedMetadataRouteResponse(options, route, render) {
+	if (!isOuterMetadataCacheEnabled() || !options.isrGet || !options.isrRouteKey || getActiveDraftModeState() || hasDraftModeCookieHeader() || route.module?.dynamic === "force-dynamic" || route.module?.revalidate === 0) return {
 		cachedEntry: null,
 		response: null
 	};
@@ -203,7 +265,7 @@ async function readMatchedPrerenderedMetadataRouteResponse(options, route, funct
 			revalidateSeconds
 		})
 	};
-	if (isUseCacheFunction(functions.defaultExport) && options.isrSet && options.scheduleBackgroundRegeneration) {
+	if (options.isrSet && options.scheduleBackgroundRegeneration) {
 		const executionContext = getRequestExecutionContext();
 		options.scheduleBackgroundRegeneration(routeKey, () => runMetadataRouteRegeneration(options, route, render, routeKey, cached, executionContext), {
 			routerKind: "App Router",
@@ -255,6 +317,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) {
@@ -286,7 +381,10 @@ async function handleGeneratedSitemap(route, cleanPathname, functions) {
 	const matchedId = findGeneratedSitemapId(await functions.generateSitemaps({}), rawId);
 	if (!matchedId) return notFoundResponse();
 	const result = await functions.defaultExport({ id: makeThenableMetadataRouteId(matchedId) });
-	if (result instanceof Response) return withMetadataRouteCacheHeader(result, route);
+	if (result instanceof Response) {
+		userMetadataResponses.add(result);
+		return result;
+	}
 	if (!isSitemapEntries(result)) throw new TypeError("Metadata sitemap routes must return an array.");
 	return markFullyBufferedBody(new Response(sitemapToXml(result), { headers: {
 		"Content-Type": route.contentType,
@@ -323,7 +421,10 @@ async function callDynamicMetadataRoute(route, match, makeThenableParams, functi
 			id: makeThenableMetadataRouteId(matchedImageId)
 		});
 	} else result = await functions.defaultExport({ params: paramsThenable });
-	if (result instanceof Response) return withMetadataRouteCacheHeader(result, route);
+	if (result instanceof Response) {
+		userMetadataResponses.add(result);
+		return result;
+	}
 	let body;
 	if (route.type === "sitemap") {
 		if (!isSitemapEntries(result)) throw new TypeError("Metadata sitemap routes must return an array.");
@@ -366,8 +467,8 @@ function isMetadataRouteRequestPath(metadataRoutes, cleanPathname) {
 	}
 	return false;
 }
-async function writeMetadataRouteMiss(options, route, functions, rendered, cachedEntry) {
-	if (process.env.VINEXT_PRERENDER === "1" || !isOuterMetadataCacheEnabled() || !rendered.response.ok || !isMetadataResponseCacheable(rendered.response) || !isUseCacheFunction(functions.defaultExport) || !options.isrRouteKey || !options.isrSet) return;
+async function writeMetadataRouteMiss(options, route, rendered, cachedEntry) {
+	if (process.env.VINEXT_PRERENDER === "1" || !isOuterMetadataCacheEnabled() || !rendered.cacheable || !options.isrRouteKey || !options.isrSet) return;
 	try {
 		await writeRenderedMetadataRoute(options, route, options.isrRouteKey(options.cleanPathname), {
 			...rendered,
@@ -385,16 +486,17 @@ 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);
-						return response ? captureRenderedMetadataRoute(response) : null;
+						return response ? captureRenderedMetadataRoute(response, route, options.cleanPathname) : null;
 					};
-					const cached = await readMatchedPrerenderedMetadataRouteResponse(options, route, functions, render);
+					const cached = await readMatchedPrerenderedMetadataRouteResponse(options, route, render);
 					if (cached.response) return cached.response;
 					const rendered = await render();
 					if (rendered) {
-						await writeMetadataRouteMiss(options, route, functions, rendered, cached.cachedEntry);
+						await writeMetadataRouteMiss(options, route, rendered, cached.cachedEntry);
 						return rendered.response;
 					}
 				}
@@ -403,14 +505,35 @@ 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));
+			return captureRenderedMetadataRoute(route.isDynamic ? await callDynamicMetadataRoute(route, match, options.makeThenableParams, functions) : serveStaticMetadataRoute(route), route, options.cleanPathname);
 		};
-		const cached = await readMatchedPrerenderedMetadataRouteResponse(options, route, functions, render);
+		const cached = await readMatchedPrerenderedMetadataRouteResponse(options, route, render);
 		if (cached.response) return cached.response;
 		const rendered = await render();
-		await writeMetadataRouteMiss(options, route, functions, rendered, cached.cachedEntry);
+		await writeMetadataRouteMiss(options, route, rendered, cached.cachedEntry);
 		return rendered.response;
 	}
 	return null;

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