vinext 1.0.0-beta.8 → 1.0.0

package/dist/server/app-page-render.js

@@ -1,22 +1,31 @@
+import { preserveFullyBufferedBodyMetadata } from "./fully-buffered-response.js";
+import { bindRequestContext } from "../shims/unified-request-context.js";
 import { VINEXT_RSC_COMPLETION_METADATA_HEADER } from "./headers.js";
-import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
-import { NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL, applyCdnResponseHeaders } from "./cache-control.js";
+import { internalServerErrorResponse } from "./http-error-responses.js";
+import { isRouteCacheabilityEvaluation, recordRouteCacheabilityClientTraceMetadataMarker } from "../shims/cacheability-classification.js";
+import { NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL, applyCdnResponseHeaders, isCdnResponsePolicyHeader } from "./cache-control.js";
 import { createArtifactCompatibilityEnvelope, createArtifactCompatibilityGraphVersion } from "./artifact-compatibility.js";
 import { AppElementsWire, isAppElementsRecord } from "./app-elements-wire.js";
 import "./app-elements.js";
-import { peekDynamicUsage } from "../shims/headers.js";
+import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
+import { isRenderDynamicLatched, peekDynamicUsage } from "../shims/headers.js";
 import { runWithFetchDedupe } from "../shims/fetch-cache.js";
-import { buildAppPageHtmlResponse, buildAppPageRscResponse, resolveAppPageHtmlResponsePolicy, resolveAppPageRscResponsePolicy } from "./app-page-response.js";
+import { deferUntilStreamConsumed } from "./defer-until-stream-consumed.js";
+import { isBailoutToCSRError } from "../shims/navigation-errors.js";
+import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
+import { copyLinkHeaderProvenance } from "./app-response-header-provenance.js";
+import { applyEdgeRuntimeHeader, buildAppPageHtmlResponse, buildAppPageRscResponse, resolveAppPageHtmlResponsePolicy, resolveAppPageRscResponsePolicy, resolveUncacheableCacheControl } from "./app-page-response.js";
 import { buildAppPageFontLinkHeader, readAppPageBinaryStream, resolveAppPageSpecialError, teeAppPageRscStreamForCapture } from "./app-page-execution.js";
 import { probeAppPageBeforeRender } from "./app-page-probe.js";
+import { hasDigest } from "./app-rsc-errors.js";
+import { recordAppPageRenderError, traceAppPageRender } from "./app-page-tracing.js";
+import { traceResponseStartWithCompletion } from "./response-start-tracing.js";
 import { DEFAULT_CACHE_VARIANT_BUDGET, buildCacheVariantWithRouteBudget, buildRenderObservation, buildRenderRequestApiObservations, createStaticLayoutArtifactReuseDecision } from "./cache-proof.js";
 import { createAppPageHtmlOutputScope, createAppPageRenderObservation, createAppPageRscOutputScope } from "./app-page-render-observation.js";
-import { finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse } from "./app-page-cache-finalizer.js";
-import { appendRscCompletionMetadata } from "./rsc-completion-metadata.js";
+import { finalizeAppPageCacheabilityEvaluationResponse, finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse } from "./app-page-cache-finalizer.js";
 import { createStaticLayoutClientReuseArtifactCompatibility, createStaticLayoutClientReusePayloadHash, createStaticLayoutClientReuseRouteId } from "./static-layout-client-reuse-proof.js";
-import { hasDigest } from "./app-rsc-errors.js";
-import { deferUntilStreamConsumed } from "./defer-until-stream-consumed.js";
-import { buildAppPageLinkHeader, createAppPageFontData, createAppPageRscErrorTracker, renderAppPageHtmlStream, renderAppPageHtmlStreamWithRecovery } from "./app-page-stream.js";
+import { appendRscCompletionMetadata } from "./rsc-completion-metadata.js";
+import { buildAppPageLinkHeader, createAppPageFontData, createAppPageRscErrorTracker, createAppPageSsrErrorHandler, renderAppPageHtmlStream, renderAppPageHtmlStreamWithRecovery } from "./app-page-stream.js";
 import { getStaticLayoutObservationSkipRejection } from "./app-layout-param-observation.js";
 import { createClientReuseSkipTransportPlan, crossCheckClientReuseManifestEntryWithCache } from "./skip-cache-proof.js";
 //#region src/server/app-page-render.ts
@@ -53,7 +62,34 @@ function applyRequestCacheLife(options) {
 		revalidateSeconds
 	};
 }
+/**
+* A render that is known dynamic is never cacheable: a route Next.js can't make
+* static, draft mode, `force-dynamic`, `revalidate = 0`, or a dynamic API read
+* before the response left the render. Responses that leave the render before
+* its response policy, such as error boundaries and special errors, get the
+* same header as the normal render.
+*/
+function applyIneligibleRouteCachePolicy(response, options) {
+	const cacheControl = resolveEarlyResponseCacheControl(options);
+	if (!cacheControl) return response;
+	const middlewarePolicy = [...options.middlewareContext.headers ?? []].filter(([name, value]) => isCdnResponsePolicyHeader(name) && response.headers.get(name) === value);
+	if (middlewarePolicy.some(([name]) => name === "cache-control")) return response;
+	const stamped = preserveFullyBufferedBodyMetadata(response, new Response(response.body, response));
+	copyLinkHeaderProvenance(response.headers, stamped.headers);
+	applyCdnResponseHeaders(stamped.headers, { cacheControl });
+	for (const [name, value] of middlewarePolicy) stamped.headers.set(name, value);
+	return stamped;
+}
+/** The known-dynamic branches of the RSC and HTML response policies, in their order. */
+function resolveEarlyResponseCacheControl(options) {
+	const uncacheable = resolveUncacheableCacheControl(options.isProduction);
+	if (!options.isStaticEligible || options.isDraftMode || options.isForceDynamic) return uncacheable;
+	if (!options.isRscRequest && (options.scriptNonce || options.isProgressiveActionRender)) return NO_STORE_CACHE_CONTROL;
+	const ignoresDynamicUsage = (options.isForceStatic || options.isDynamicError) && (options.revalidateSeconds === null || options.revalidateSeconds === Infinity);
+	return options.revalidateSeconds === 0 || !ignoresDynamicUsage && (options.peekDynamicUsage?.() ?? peekDynamicUsage()) ? uncacheable : null;
+}
 function resolveAppPageCacheWriteRevalidateSeconds(options) {
+	if (!options.isStaticEligible) return null;
 	if (options.revalidateSeconds === null && (options.isForceStatic || options.isDynamicError)) return Infinity;
 	return options.revalidateSeconds;
 }
@@ -266,10 +302,62 @@ function wrapRscResponseForDevErrorReporting(response, consumeInvalidDynamicUsag
 	});
 }
 async function renderAppPageLifecycle(options) {
+	if (options.isRscRequest) {
+		const prepared = await prepareAppPageElement(options);
+		return prepared instanceof Response ? applyIneligibleRouteCachePolicy(prepared, options) : renderAppPageLifecycleImpl(prepared);
+	}
+	const operation = options.traceOperation ?? (options.isPrerender ? "prerender" : "render");
+	let resolveResponse;
+	let rejectResponse;
+	let renderCompletion = Promise.resolve();
+	const responsePromise = new Promise((resolve, reject) => {
+		resolveResponse = resolve;
+		rejectResponse = reject;
+	});
+	traceAppPageRender(options.routePattern, operation, async (renderSpan) => {
+		try {
+			const prepared = await prepareAppPageElement(options);
+			if (prepared instanceof Response) {
+				const traced = traceResponseStartWithCompletion(applyIneligibleRouteCachePolicy(prepared, options));
+				resolveResponse(traced.response);
+				await traced.started;
+				return;
+			}
+			const traced = traceResponseStartWithCompletion(await renderAppPageLifecycleImpl({
+				...prepared,
+				onRenderComplete(completion) {
+					renderCompletion = completion;
+					completion.catch(() => {});
+					options.onRenderComplete?.(completion);
+				}
+			}, renderSpan));
+			resolveResponse(traced.response);
+			await Promise.all([renderCompletion, traced.started]);
+		} catch (error) {
+			rejectResponse(error);
+			throw error;
+		}
+	}).catch(() => {});
+	return responsePromise;
+}
+async function prepareAppPageElement(options) {
+	if (!options.prepareElement) return options;
+	const prepared = await options.prepareElement();
+	return prepared.response ?? {
+		...options,
+		element: prepared.element
+	};
+}
+async function renderAppPageLifecycleImpl(options, renderSpan) {
 	let dynamicUsageObserved = false;
 	let dynamicUsageFinalized = false;
+	const isCacheCandidateHtmlRender = options.isCacheCandidate === true && options.isPrerender !== true && !options.isRscRequest;
+	const readsRenderDynamicLatch = isCacheCandidateHtmlRender || !options.isRscRequest && options.pprFallbackShellSignal === void 0 && (options.isPrerender === true || isRouteCacheabilityEvaluation());
+	const readDynamicUsage = bindRequestContext(() => options.consumeDynamicUsage() || readsRenderDynamicLatch && isRenderDynamicLatched());
+	const consumeRenderObservationState = options.consumeRenderObservationState && bindRequestContext(options.consumeRenderObservationState);
+	const peekRenderDynamicUsage = () => (options.peekDynamicUsage?.() ?? peekDynamicUsage()) || readsRenderDynamicLatch && isRenderDynamicLatched();
 	const consumeRenderDynamicUsage = () => {
-		if (!dynamicUsageObserved) dynamicUsageObserved = options.consumeDynamicUsage();
+		if (!dynamicUsageObserved) dynamicUsageObserved = readDynamicUsage();
 		return dynamicUsageObserved;
 	};
 	const finalizeRenderDynamicUsage = () => {
@@ -304,7 +392,7 @@ async function renderAppPageLifecycle(options) {
 		},
 		classification: options.classification
 	});
-	if (preRenderResult.response) return preRenderResult.response;
+	if (preRenderResult.response) return applyIneligibleRouteCachePolicy(preRenderResult.response, options);
 	const layoutFlags = preRenderResult.layoutFlags;
 	const artifactCompatibility = createAppPageArtifactCompatibility(options.element, options.routePattern);
 	const rootBoundaryId = artifactCompatibility?.rootBoundaryId ?? null;
@@ -331,7 +419,7 @@ async function renderAppPageLifecycle(options) {
 		layoutFlags,
 		layoutParamAccess: options.layoutParamAccess
 	});
-	const shouldBypassRscCacheForSkipTransport = options.isRscRequest && isSkipTransportEnabled(skipDisposition);
+	const shouldBypassRscCache = options.isRscRequest && isSkipTransportEnabled(skipDisposition) || options.bypassInterceptionContextCache === true;
 	const dynamicStaleTimeSeconds = options.dynamicStaleTimeSeconds ?? resolveConfiguredDynamicStaleTimeSeconds();
 	const outgoingElement = AppElementsWire.encodeOutgoingPayload({
 		element: options.element,
@@ -341,7 +429,18 @@ async function renderAppPageLifecycle(options) {
 		skipDisposition: options.isRscRequest ? skipDisposition : void 0
 	});
 	const compileEnd = options.isProduction ? void 0 : performance.now();
-	const rscErrorTracker = createAppPageRscErrorTracker(options.createRscOnErrorHandler(options.cleanPathname, options.routePattern));
+	const errorContextOverrides = {
+		...options.isProgressiveActionRender ? {
+			renderSource: "react-server-components-payload",
+			routeType: "action"
+		} : {},
+		...options.isPrerender ? { revalidateReason: "stale" } : {}
+	};
+	const baseOnError = options.createRscOnErrorHandler(options.cleanPathname, options.routePattern, errorContextOverrides);
+	const rscErrorTracker = createAppPageRscErrorTracker((error, requestInfo, errorContext) => {
+		if (renderSpan) recordAppPageRenderError(renderSpan, error);
+		return baseOnError(error, requestInfo, errorContext);
+	});
 	let rscStream = await runWithFetchDedupe(async () => {
 		if (options.pprFallbackShellSignal && options.prerenderToReadableStream) {
 			const reactSignal = options.pprFallbackShellReactSignal ?? options.pprFallbackShellSignal;
@@ -360,8 +459,8 @@ async function renderAppPageLifecycle(options) {
 	let expireSeconds = options.expireSeconds;
 	const shouldWaitForAllReady = options.isPrerender === true && options.isSpeculativePrerender !== true;
 	const shouldReadRequestCacheLifeForPrerender = options.isPrerender === true;
-	const mayResolveCacheLifeAfterHeaders = options.isProgressiveActionRender !== true && (revalidateSeconds === null || revalidateSeconds > 0 && revalidateSeconds !== Infinity) && !options.isDraftMode && !options.isForceDynamic && !shouldBypassRscCacheForSkipTransport;
-	const shouldCaptureRscForCacheMetadata = (options.isProduction || options.isPrerender === true) && mayResolveCacheLifeAfterHeaders;
+	const mayResolveCacheLifeAfterHeaders = options.isProgressiveActionRender !== true && (revalidateSeconds === null || revalidateSeconds > 0) && !options.isDraftMode && !options.isForceDynamic && !shouldBypassRscCache;
+	const shouldCaptureRscForCacheMetadata = (options.isProduction || options.isPrerender === true) && mayResolveCacheLifeAfterHeaders && options.isStaticEligible;
 	const createBufferedRscStream = (close) => new ReadableStream({ start(controller) {
 		if (pprFallbackShellRsc) controller.enqueue(pprFallbackShellRsc);
 		if (close) controller.close();
@@ -385,7 +484,6 @@ async function renderAppPageLifecycle(options) {
 			}));
 		}
 		const dynamicUsedDuringBuild = consumeRenderDynamicUsage();
-		const shouldBypassRscCache = shouldBypassRscCacheForSkipTransport;
 		const rscResponsePolicy = shouldBypassRscCache ? { cacheControl: NO_STORE_CACHE_CONTROL } : resolveAppPageRscResponsePolicy({
 			dynamicUsedDuringBuild,
 			isDraftMode: options.isDraftMode,
@@ -393,10 +491,11 @@ async function renderAppPageLifecycle(options) {
 			isForceDynamic: options.isForceDynamic,
 			isForceStatic: options.isForceStatic,
 			isProduction: options.isProduction,
+			isStaticEligible: options.isStaticEligible,
 			expireSeconds,
 			revalidateSeconds
 		});
-		if (shouldBypassRscCache) options.isrDebug?.("RSC cache write skipped (skip transport payload)", options.cleanPathname);
+		if (shouldBypassRscCache) options.isrDebug?.(options.bypassInterceptionContextCache === true ? "RSC cache write skipped (unverified interception context)" : "RSC cache write skipped (skip transport payload)", options.cleanPathname);
 		const shouldEmitDynamicStaleTime = dynamicStaleTimeSeconds !== void 0 && options.isPrerender !== true && !options.isForceStatic && (dynamicUsedDuringBuild || options.isForceDynamic);
 		const staleTimePending = options.isPrerender !== true && mayResolveCacheLifeAfterHeaders && !dynamicUsedDuringBuild;
 		const rscResponse = buildAppPageRscResponse(rscForResponse, {
@@ -432,11 +531,13 @@ async function renderAppPageLifecycle(options) {
 			statusText: rscResponse.statusText,
 			headers: completionHeaders
 		}) : rscResponse;
-		return finalizeAppPageRscCacheResponse(!options.isProduction && completionResponse.body && options.consumeInvalidDynamicUsageError ? wrapRscResponseForDevErrorReporting(completionResponse, options.consumeInvalidDynamicUsageError) : completionResponse, {
+		const devRscResponse = !options.isProduction && completionResponse.body && options.consumeInvalidDynamicUsageError ? wrapRscResponseForDevErrorReporting(completionResponse, options.consumeInvalidDynamicUsageError) : completionResponse;
+		return finalizeAppPageRscCacheResponse(devRscResponse, {
 			capturedRscDataPromise: options.isProduction && shouldCaptureRscForCacheMetadata ? capturedRscDataRef.value : null,
+			bypassInterceptionContextCache: options.bypassInterceptionContextCache,
 			cleanPathname: options.cleanPathname,
 			consumeDynamicUsage: finalizeRenderDynamicUsage,
-			consumeRenderObservationState: options.consumeRenderObservationState,
+			consumeRenderObservationState,
 			createRscRenderObservation(input) {
 				return createAppPageRenderObservation({
 					boundaryOutcome: { kind: "success" },
@@ -466,9 +567,11 @@ async function renderAppPageLifecycle(options) {
 			renderMode: options.renderMode,
 			preserveClientResponseHeaders: rscResponsePolicy.cacheState !== "MISS",
 			expireSeconds,
+			isStaticEligible: options.isStaticEligible,
 			revalidateSeconds: resolveAppPageCacheWriteRevalidateSeconds({
 				isDynamicError: options.isDynamicError,
 				isForceStatic: options.isForceStatic,
+				isStaticEligible: options.isStaticEligible,
 				revalidateSeconds
 			}),
 			waitUntil(promise) {
@@ -482,6 +585,8 @@ async function renderAppPageLifecycle(options) {
 		getStyles: options.getFontStyles
 	});
 	const fontLinkHeader = buildAppPageFontLinkHeader(fontData.preloads);
+	const clientTraceMetadataMarker = options.isProduction && options.isPrerender !== true && options.clientTraceMetadata && options.clientTraceMetadata.length > 0 ? crypto.randomUUID() : void 0;
+	if (clientTraceMetadataMarker) recordRouteCacheabilityClientTraceMetadataMarker(clientTraceMetadataMarker);
 	let requestCacheLifeForPrerender = null;
 	let dynamicUsedDuringHtmlRender = false;
 	let renderEnd;
@@ -490,11 +595,30 @@ async function renderAppPageLifecycle(options) {
 			if (!options.isProduction) renderEnd = performance.now();
 		},
 		renderErrorBoundaryResponse(error) {
+			if (isCacheCandidateHtmlRender && isBailoutToCSRError(error)) {
+				console.error(`${error.reason} should be wrapped in a suspense boundary at page "${options.routePattern}". Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout`);
+				options.clearRequestContext();
+				const headers = new Headers();
+				mergeMiddlewareResponseHeaders(headers, options.middlewareContext.headers);
+				headers.set("Cache-Control", NEVER_CACHE_CONTROL);
+				applyEdgeRuntimeHeader(headers, options.isEdgeRuntime);
+				const response = internalServerErrorResponse(void 0, { headers });
+				applyCdnResponseHeaders(response.headers, { cacheControl: NEVER_CACHE_CONTROL });
+				return Promise.resolve(response);
+			}
 			const capturedRscError = rscErrorTracker.getCapturedError();
 			return options.renderErrorBoundaryResponse(capturedRscError ?? error, capturedRscError === null ? "ssr" : "rsc");
 		},
 		async renderHtmlStream() {
 			const ssrHandler = await options.loadSsrHandler();
+			const baseOnSsrError = options.createRscOnErrorHandler(options.cleanPathname, options.routePattern, {
+				...errorContextOverrides,
+				renderSource: "server-rendering"
+			});
+			const onSsrError = (error, requestInfo, errorContext) => {
+				if (renderSpan) recordAppPageRenderError(renderSpan, error);
+				return baseOnSsrError(error, requestInfo, errorContext);
+			};
 			return renderAppPageHtmlStream({
 				capturedRscDataRef,
 				getInitialNavigationCacheMetadata: () => {
@@ -505,7 +629,8 @@ async function renderAppPageLifecycle(options) {
 						const observation = options.peekRenderObservationState?.();
 						kind = observation && (observation.dynamicFetches.length > 0 || observation.requestApis.length > 0) ? "dynamic" : "static";
 					}
-					const staleTimeSeconds = resolveClientStaleTimeSeconds(options.isPrerender === true ? requestCacheLifeForPrerender : options.peekRequestCacheLife?.());
+					const requestCacheLife = options.isPrerender === true ? requestCacheLifeForPrerender ?? options.peekRequestCacheLife?.() : options.peekRequestCacheLife?.();
+					const staleTimeSeconds = resolveClientStaleTimeSeconds(requestCacheLife);
 					return {
 						kind,
 						...kind === "dynamic" && dynamicStaleTimeSeconds !== void 0 && options.isPrerender !== true ? { dynamicStaleTimeSeconds } : {},
@@ -517,6 +642,7 @@ async function renderAppPageLifecycle(options) {
 				navigationContext: options.getNavigationContext(),
 				basePath: options.basePath,
 				clientTraceMetadata: options.clientTraceMetadata,
+				clientTraceMetadataMarker,
 				reactMaxHeadersLength: options.reactMaxHeadersLength,
 				rootParams: options.rootParams,
 				pprFallbackShellSignal: options.pprFallbackShellSignal,
@@ -528,7 +654,9 @@ async function renderAppPageLifecycle(options) {
 				fallbackToErrorDocumentOnShellError: options.isPrerender === true && options.isSpeculativePrerender === true ? false : void 0,
 				waitForAllReady: shouldWaitForAllReady,
 				isStaticGeneration: options.isPrerender === true,
-				isForceStatic: options.isForceStatic
+				isForceStatic: options.isForceStatic,
+				isCacheCandidate: isCacheCandidateHtmlRender,
+				onSsrError: createAppPageSsrErrorHandler(onSsrError, rscErrorTracker.isCapturedError)
 			});
 		},
 		renderSpecialErrorResponse(specialError) {
@@ -536,7 +664,8 @@ async function renderAppPageLifecycle(options) {
 		},
 		resolveSpecialError: resolveAppPageSpecialError
 	});
-	if (htmlRender.response) return htmlRender.response;
+	options.onRenderComplete?.(htmlRender.renderComplete);
+	if (htmlRender.response) return applyIneligibleRouteCachePolicy(htmlRender.response, options);
 	let htmlStream = htmlRender.htmlStream;
 	if (!htmlStream) throw new Error("[vinext] Expected an HTML stream when no fallback response was returned");
 	const linkHeader = buildAppPageLinkHeader(htmlRender.linkHeader, fontLinkHeader, options.reactMaxHeadersLength);
@@ -547,14 +676,14 @@ async function renderAppPageLifecycle(options) {
 			const specialError = resolveAppPageSpecialError(captured);
 			if (specialError) {
 				htmlStream.cancel().catch(() => {});
-				return options.renderPageSpecialError(specialError);
+				return applyIneligibleRouteCachePolicy(await options.renderPageSpecialError(specialError), options);
 			}
 		}
 	}
 	let dynamicUsedDuringRender = consumeRenderDynamicUsage();
 	dynamicUsedDuringHtmlRender = dynamicUsedDuringRender;
 	const stopSpeculativeMetadataWaitOnDynamicUsage = options.isSpeculativePrerender === true && shouldReadRequestCacheLifeForPrerender ? () => {
-		if (dynamicUsedDuringRender || (options.peekDynamicUsage?.() ?? peekDynamicUsage())) {
+		if (dynamicUsedDuringRender || peekRenderDynamicUsage()) {
 			dynamicUsedDuringRender = true;
 			dynamicUsedDuringHtmlRender = true;
 			return true;
@@ -562,6 +691,7 @@ async function renderAppPageLifecycle(options) {
 		return false;
 	} : void 0;
 	if (shouldWaitForAllReady || shouldReadRequestCacheLifeForPrerender) await settleCapturedRscRenderForCacheMetadata(htmlRender.capturedRscData, stopSpeculativeMetadataWaitOnDynamicUsage);
+	if (stopSpeculativeMetadataWaitOnDynamicUsage) await waitUnlessDynamic(htmlRender.renderComplete, stopSpeculativeMetadataWaitOnDynamicUsage);
 	if (shouldReadRequestCacheLifeForPrerender) {
 		requestCacheLifeForPrerender = readRequestCacheLifeForPrerender(options);
 		({expireSeconds, revalidateSeconds} = applyRequestCacheLife({
@@ -588,6 +718,7 @@ async function renderAppPageLifecycle(options) {
 		isForceDynamic: options.isForceDynamic,
 		isForceStatic: options.isForceStatic,
 		isProduction: options.isProduction,
+		isStaticEligible: options.isStaticEligible,
 		expireSeconds,
 		revalidateSeconds
 	});
@@ -629,13 +760,15 @@ async function renderAppPageLifecycle(options) {
 		});
 		if (options.isPrerender === true) return isrResponse;
 		return finalizeAppPageHtmlCacheResponse(isrResponse, {
+			bypassInterceptionContextCache: options.bypassInterceptionContextCache,
 			capturedDynamicUsageBeforeContextCleanup() {
 				return dynamicUsedBeforeContextCleanup;
 			},
 			capturedRscDataPromise: capturedRscDataRef.value,
 			cleanPathname: options.cleanPathname,
+			clientTraceMetadataMarker,
 			consumeDynamicUsage: consumeRenderDynamicUsage,
-			consumeRenderObservationState: options.consumeRenderObservationState,
+			consumeRenderObservationState,
 			createHtmlRenderObservation(input) {
 				return createAppPageRenderObservation({
 					boundaryOutcome: { kind: "success" },
@@ -675,9 +808,11 @@ async function renderAppPageLifecycle(options) {
 			omitPendingDynamicCacheState: options.omitPendingDynamicCacheState,
 			preserveClientResponseHeaders: !htmlResponsePolicy.shouldWriteToCache,
 			expireSeconds,
+			isStaticEligible: options.isStaticEligible,
 			revalidateSeconds: resolveAppPageCacheWriteRevalidateSeconds({
 				isDynamicError: options.isDynamicError,
 				isForceStatic: options.isForceStatic,
+				isStaticEligible: options.isStaticEligible,
 				revalidateSeconds
 			}),
 			linkHeader: linkHeader ?? null,
@@ -686,7 +821,7 @@ async function renderAppPageLifecycle(options) {
 			}
 		});
 	}
-	return buildAppPageHtmlResponse(safeHtmlStream, {
+	const response = buildAppPageHtmlResponse(safeHtmlStream, {
 		cacheTags: options.isPrerender === true ? options.getPageTags() : void 0,
 		draftCookie,
 		linkHeader,
@@ -696,6 +831,27 @@ async function renderAppPageLifecycle(options) {
 		requestCacheLife: requestCacheLifeForPrerender,
 		timing: htmlResponseTiming
 	});
+	return finalizeAppPageCacheabilityEvaluationResponse(response, {
+		capturedDynamicUsageBeforeContextCleanup() {
+			return dynamicUsedBeforeContextCleanup;
+		},
+		consumeDynamicUsage: consumeRenderDynamicUsage,
+		consumeRenderObservationState,
+		getPageTags() {
+			return options.getPageTags();
+		},
+		getRequestCacheLife() {
+			return readRequestCacheLifeForCachePolicy(options);
+		},
+		expireSeconds,
+		isStaticEligible: options.isStaticEligible,
+		revalidateSeconds: resolveAppPageCacheWriteRevalidateSeconds({
+			isDynamicError: options.isDynamicError,
+			isForceStatic: options.isForceStatic,
+			isStaticEligible: options.isStaticEligible,
+			revalidateSeconds
+		})
+	});
 }
 async function settleCapturedRscRenderForCacheMetadata(capturedRscDataPromise, shouldStopWaiting) {
 	if (!capturedRscDataPromise) return;
@@ -705,8 +861,16 @@ async function settleCapturedRscRenderForCacheMetadata(capturedRscDataPromise, s
 		} catch {}
 		return;
 	}
+	await waitUnlessDynamic(capturedRscDataPromise, shouldStopWaiting);
+}
+/**
+* Wait for `promise` to settle, or until `shouldStopWaiting` reports that the
+* render turned dynamic. Rejections are ignored: the response stream and the
+* cache-write path own render error propagation.
+*/
+async function waitUnlessDynamic(promise, shouldStopWaiting) {
 	let settled = false;
-	const settledPromise = capturedRscDataPromise.catch(() => {}).then(() => {
+	const settledPromise = promise.catch(() => {}).then(() => {
 		settled = true;
 	});
 	try {
@@ -714,4 +878,4 @@ async function settleCapturedRscRenderForCacheMetadata(capturedRscDataPromise, s
 	} finally {}
 }
 //#endregion
-export { renderAppPageLifecycle };
+export { applyIneligibleRouteCachePolicy, renderAppPageLifecycle };

package/dist/server/app-page-request.d.ts

@@ -31,11 +31,13 @@ type ParallelGenerateStaticParamsBranch = {
   patternParts?: readonly string[] | null;
   routeSegments?: readonly string[] | null;
 };
-type ValidateAppPageDynamicParamsOptions = {
+export type ValidateAppPageDynamicParamsOptions = {
   enforceStaticParamsOnly: boolean;
   generateStaticParams?: GenerateStaticParams | GenerateStaticParamsSource | readonly (GenerateStaticParams | GenerateStaticParamsSource | null | undefined)[] | null;
   isDynamicRoute: boolean;
+  optionalCatchAllParamNames?: readonly string[];
   params: AppPageParams;
+  requiredParamNames?: readonly string[];
 };
 type ResolveAppPageGenerateStaticParamsSourcesOptions = {
   layouts?: readonly (GenerateStaticParamsModule | null | undefined)[];
@@ -133,11 +135,10 @@ type ResolveAppPageInterceptResult<TInterceptOpts> = {
   interceptOpts: TInterceptOpts | undefined;
   response: Response | null;
 };
-declare function resolveAppPageGenerateStaticParamsSources(options: ResolveAppPageGenerateStaticParamsSourcesOptions): GenerateStaticParamsSource[];
-declare function validateAppPageDynamicParams(options: ValidateAppPageDynamicParamsOptions): Promise<Response | null>;
-declare function resolveAppPageInterceptionRerenderTarget<TRoute, TPage, TInterceptOpts>(options: ResolveAppPageInterceptionRerenderTargetOptions<TRoute, TPage, TInterceptOpts>): Promise<ResolveAppPageInterceptionRerenderTargetResult<TRoute, TInterceptOpts>>;
-declare function resolveAppPageActionRerenderTarget<TRoute, TPage, TInterceptOpts>(options: ResolveAppPageActionRerenderTargetOptions<TRoute, TPage, TInterceptOpts>): Promise<ResolveAppPageActionRerenderTargetResult<TRoute, TInterceptOpts>>;
-declare function resolveAppPageIntercept<TRoute, TPage, TInterceptOpts, TElement>(options: ResolveAppPageInterceptOptions<TRoute, TPage, TInterceptOpts, TElement>): Promise<ResolveAppPageInterceptResult<TInterceptOpts>>;
-declare function buildAppPageElement<TElement>(options: BuildAppPageElementOptions<TElement>): Promise<BuildAppPageElementResult<TElement>>;
-//#endregion
-export { ValidateAppPageDynamicParamsOptions, buildAppPageElement, resolveAppPageActionRerenderTarget, resolveAppPageGenerateStaticParamsSources, resolveAppPageIntercept, resolveAppPageInterceptionRerenderTarget, validateAppPageDynamicParams };
+export declare function resolveAppPageGenerateStaticParamsSources(options: ResolveAppPageGenerateStaticParamsSourcesOptions): GenerateStaticParamsSource[];
+export declare function validateAppPageDynamicParams(options: ValidateAppPageDynamicParamsOptions): Promise<Response | null>;
+export declare function resolveAppPageInterceptionRerenderTarget<TRoute, TPage, TInterceptOpts>(options: ResolveAppPageInterceptionRerenderTargetOptions<TRoute, TPage, TInterceptOpts>): Promise<ResolveAppPageInterceptionRerenderTargetResult<TRoute, TInterceptOpts>>;
+export declare function resolveAppPageActionRerenderTarget<TRoute, TPage, TInterceptOpts>(options: ResolveAppPageActionRerenderTargetOptions<TRoute, TPage, TInterceptOpts>): Promise<ResolveAppPageActionRerenderTargetResult<TRoute, TInterceptOpts>>;
+export declare function resolveAppPageIntercept<TRoute, TPage, TInterceptOpts, TElement>(options: ResolveAppPageInterceptOptions<TRoute, TPage, TInterceptOpts, TElement>): Promise<ResolveAppPageInterceptResult<TInterceptOpts>>;
+export declare function buildAppPageElement<TElement>(options: BuildAppPageElementOptions<TElement>): Promise<BuildAppPageElementResult<TElement>>;
+//#endregion

package/dist/server/app-page-request.js

@@ -110,18 +110,21 @@ function resolveAppPageGenerateStaticParamsSources(options) {
 	}
 	return sources;
 }
-function areStaticParamsAllowed(params, staticParams, allowMissingValues = false) {
-	const paramKeys = Object.keys(params);
+function areStaticParamsAllowed(params, staticParams, allowMissingValues = false, paramKeys = Object.keys(params), optionalCatchAllParamNames = []) {
 	const stringParamMatches = (value, staticValue) => value === encodeURIComponent(staticValue);
-	return staticParams.some((staticParamSet) => paramKeys.every((key) => {
-		const value = params[key];
-		const staticValue = staticParamSet[key];
-		if (!Object.hasOwn(staticParamSet, key)) return allowMissingValues;
-		if (Array.isArray(value)) return Array.isArray(staticValue) && value.length === staticValue.length && value.every((part, index) => typeof staticValue[index] === "string" ? stringParamMatches(part, staticValue[index]) : part === staticValue[index]);
-		if (typeof staticValue === "string") return stringParamMatches(value, staticValue);
-		if (typeof staticValue === "number" || typeof staticValue === "boolean") return String(value) === String(staticValue);
-		return JSON.stringify(value) === JSON.stringify(staticValue);
-	}));
+	return staticParams.some((staticParamSet) => {
+		if (!staticParamSet || typeof staticParamSet !== "object" || Array.isArray(staticParamSet)) return false;
+		return paramKeys.every((key) => {
+			const value = params[key];
+			const staticValue = staticParamSet[key];
+			if (!Object.hasOwn(staticParamSet, key)) return allowMissingValues;
+			if (value === void 0) return optionalCatchAllParamNames.includes(key) && (staticValue === void 0 || staticValue === null || staticValue === false || Array.isArray(staticValue) && staticValue.length === 0);
+			if (Array.isArray(value)) return Array.isArray(staticValue) && value.length === staticValue.length && value.every((part, index) => typeof staticValue[index] === "string" ? stringParamMatches(part, staticValue[index]) : part === staticValue[index]);
+			if (typeof staticValue === "string") return stringParamMatches(value, staticValue);
+			if (typeof staticValue === "number" || typeof staticValue === "boolean") return String(value) === String(staticValue);
+			return JSON.stringify(value) === JSON.stringify(staticValue);
+		});
+	});
 }
 function remapStaticParamsToRouteParams(staticParams, source) {
 	if (!source.paramAliases) return [...staticParams];
@@ -227,9 +230,10 @@ async function validateAppPageDynamicParams(options) {
 		const result = await generateIndependentStaticParams(sources, chainedStaticParams, options.params);
 		if (result.validated) {
 			validatedIndependentResults = true;
-			if (!areStaticParamsAllowed(options.params, result.staticParams, true)) return notFoundResponse();
+			if (!areStaticParamsAllowed(options.params, result.staticParams, options.requiredParamNames === void 0, options.requiredParamNames, options.optionalCatchAllParamNames)) return notFoundResponse();
 		}
 	}
+	if (options.requiredParamNames && !validatedIndependentResults) return notFoundResponse();
 	if (chainedStaticParams && !validatedIndependentResults) {
 		if (!areStaticParamsAllowed(options.params, chainedStaticParams)) return notFoundResponse();
 	}

package/dist/server/app-page-response.d.ts

@@ -1,10 +1,10 @@
 import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
 //#region src/server/app-page-response.d.ts
-type AppPageMiddlewareContext = {
+export type AppPageMiddlewareContext = {
   headers: Headers | null;
   status: number | null;
 };
-type AppPageResponseTiming = {
+export type AppPageResponseTiming = {
   compileEnd?: number;
   handlerStart: number;
   renderEnd?: number;
@@ -26,6 +26,11 @@ type ResolveAppPageResponsePolicyBaseOptions = {
   isForceDynamic: boolean;
   isForceStatic: boolean;
   isProduction: boolean;
+  /**
+   * `false` for routes Next.js classifies as dynamic (ƒ). Their responses are
+   * never cached, whatever their revalidate.
+   */
+  isStaticEligible: boolean;
   expireSeconds?: number;
   revalidateSeconds: number | null;
 };
@@ -70,9 +75,15 @@ type BuildAppPageHtmlResponseOptions = {
  * prerender seed) — `use cache` scopes keep resolving after headers commit,
  * so a streaming response can never carry it.
  */
-declare function applyClientStaleTimeHeader(headers: Headers, staleTimeSeconds: number | undefined): void;
-declare function resolveAppPageRscResponsePolicy(options: ResolveAppPageRscResponsePolicyOptions): AppPageResponsePolicy;
-declare function resolveAppPageHtmlResponsePolicy(options: ResolveAppPageHtmlResponsePolicyOptions): AppPageHtmlResponsePolicy;
+export declare function applyClientStaleTimeHeader(headers: Headers, staleTimeSeconds: number | undefined): void;
+/**
+ * Next.js sends `private, no-cache, no-store, max-age=0, must-revalidate` for
+ * an App page response it knows is dynamic. Dev responses never cache, so they
+ * keep vinext's dev `no-store` header.
+ */
+export declare function resolveUncacheableCacheControl(isProduction: boolean): string;
+export declare function resolveAppPageRscResponsePolicy(options: ResolveAppPageRscResponsePolicyOptions): AppPageResponsePolicy;
+export declare function resolveAppPageHtmlResponsePolicy(options: ResolveAppPageHtmlResponsePolicyOptions): AppPageHtmlResponsePolicy;
 /**
  * Mirror Next.js' edge-runtime marker (set in edge-ssr-app.ts). Only routes
  * whose resolved segment config is `runtime = "edge"` should advertise it —
@@ -80,8 +91,8 @@ declare function resolveAppPageHtmlResponsePolicy(options: ResolveAppPageHtmlRes
  * the configured runtime from the response. Centralized so every response
  * construction site can opt in without re-deriving the header name.
  */
-declare function applyEdgeRuntimeHeader(headers: Headers, isEdgeRuntime: boolean | undefined): void;
-declare function buildAppPageRscResponse(body: ReadableStream, options: BuildAppPageRscResponseOptions): Response;
-declare function buildAppPageHtmlResponse(body: ReadableStream, options: BuildAppPageHtmlResponseOptions): Response;
+export declare function applyEdgeRuntimeHeader(headers: Headers, isEdgeRuntime: boolean | undefined): void;
+export declare function buildAppPageRscResponse(body: ReadableStream, options: BuildAppPageRscResponseOptions): Response;
+export declare function buildAppPageHtmlResponse(body: ReadableStream, options: BuildAppPageHtmlResponseOptions): Response;
 //#endregion
-export { AppPageMiddlewareContext, AppPageResponseTiming, applyClientStaleTimeHeader, applyEdgeRuntimeHeader, buildAppPageHtmlResponse, buildAppPageRscResponse, mergeMiddlewareResponseHeaders, resolveAppPageHtmlResponsePolicy, resolveAppPageRscResponsePolicy };
+export { mergeMiddlewareResponseHeaders };