vinext 1.0.0 → 1.1.0

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

@@ -23,6 +23,13 @@ type AppPageRequestCacheLife = {
   stale?: number;
 };
 type AppPageRenderableElement = ReactNode | Readonly<Record<string, ReactNode>>;
+type AppPageSpecialErrorRenderOptions = {
+  /**
+   * The document may be stored in place of the page's, so like a cache
+   * candidate's render it must not carry the request's query.
+   */
+  isCacheCandidate?: boolean;
+};
 type PreparedAppPageElement = {
   element: AppPageRenderableElement;
   response?: never;
@@ -63,7 +70,6 @@ type RenderAppPageLifecycleOptionsBase = {
   getDraftModeCookieHeader: () => string | null | undefined;
   handlerStart: number;
   hasCustomGlobalError?: boolean;
-  hasLoadingBoundary: boolean;
   dynamicStaleTimeSeconds?: number;
   isDynamicError: boolean;
   isDraftMode: boolean;
@@ -83,9 +89,12 @@ type RenderAppPageLifecycleOptionsBase = {
   isCacheCandidate?: boolean;
   isProgressiveActionRender?: boolean;
   isPrerender?: boolean;
+  /** PPR routes send every RSC response as a 200. */
+  isRoutePPREnabled?: boolean;
   isSpeculativePrerender?: boolean;
+  /** Wait for the whole document before its first byte, as a prerender does. */
+  renderWholeDocument?: boolean;
   isProduction: boolean;
-  probePageBeforeRender?: boolean;
   omitPendingDynamicCacheState?: boolean;
   isRscRequest: boolean;
   traceOperation?: "prerender" | "render";
@@ -107,13 +116,12 @@ type RenderAppPageLifecycleOptionsBase = {
   rootParams?: RootParams;
   peekRenderObservationState?: () => AppPageRenderObservationState;
   probeLayoutAt: (layoutIndex: number) => unknown;
-  probePage: () => unknown;
   expireSeconds?: number;
   formState?: ReactFormState | null;
   revalidateSeconds: number | null;
   renderErrorBoundaryResponse: (error: unknown, errorOrigin: "rsc" | "ssr") => Promise<Response | null>;
   renderLayoutSpecialError: (specialError: AppPageSpecialError, layoutIndex: number) => Promise<Response>;
-  renderPageSpecialError: (specialError: AppPageSpecialError) => Promise<Response>;
+  renderPageSpecialError: (specialError: AppPageSpecialError, renderOptions?: AppPageSpecialErrorRenderOptions) => Promise<Response>;
   renderToReadableStream: (element: ReactNode | AppOutgoingElements, options: {
     onError: AppPageBoundaryOnError;
     signal?: AbortSignal;
@@ -150,6 +158,6 @@ type RenderAppPageLifecycleOptions = RenderAppPageLifecycleOptionsBase & ({
  * its response policy, such as error boundaries and special errors, get the
  * same header as the normal render.
  */
-export declare function applyIneligibleRouteCachePolicy(response: Response, options: Pick<RenderAppPageLifecycleOptions, "isDraftMode" | "isDynamicError" | "isForceDynamic" | "isForceStatic" | "isProduction" | "isProgressiveActionRender" | "isRscRequest" | "isStaticEligible" | "middlewareContext" | "peekDynamicUsage" | "revalidateSeconds" | "scriptNonce">): Response;
+export declare function applyIneligibleRouteCachePolicy(response: Response, options: Pick<RenderAppPageLifecycleOptions, "dynamicStaleTimeSeconds" | "isDraftMode" | "isDynamicError" | "isForceDynamic" | "isForceStatic" | "isProduction" | "isProgressiveActionRender" | "isRscRequest" | "isStaticEligible" | "middlewareContext" | "peekDynamicUsage" | "revalidateSeconds" | "scriptNonce">, probeCacheLife?: AppPageRequestCacheLife | null): Response;
 export declare function renderAppPageLifecycle(options: RenderAppPageLifecycleOptions): Promise<Response>;
 //#endregion

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

@@ -1,31 +1,36 @@
 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 { getRequestExecutionContext } from "../shims/request-context.js";
+import { VINEXT_DYNAMIC_STALE_TIME_HEADER, VINEXT_RSC_COMPLETION_METADATA_HEADER } from "./headers.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 { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
-import { isRenderDynamicLatched, peekDynamicUsage } from "../shims/headers.js";
+import { isRenderDynamicLatched, markDynamicUsage } from "../shims/internal/headers-state.js";
+import { peekDynamicUsage, runWithDetachedDynamicUsage } from "../shims/headers.js";
 import { runWithFetchDedupe } from "../shims/fetch-cache.js";
+import { setCacheStateHeaders } from "./cache-headers.js";
 import { deferUntilStreamConsumed } from "./defer-until-stream-consumed.js";
+import { createArtifactCompatibilityEnvelope, createArtifactCompatibilityGraphVersion } from "./artifact-compatibility.js";
+import { AppElementsWire, isAppElementsRecord } from "./app-elements-wire.js";
+import "./app-elements.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 { applyPrerenderCacheLifeHeader, applyPrerenderCacheTagsHeader } from "./prerender-cache-life-header.js";
+import { copyLinkHeaderProvenance, getFrameworkLinkHeader } from "./app-response-header-provenance.js";
+import { applyClientStaleTimeHeader, applyEdgeRuntimeHeader, buildAppPageHtmlResponse, buildAppPageRscResponse, resolveAppPageHtmlResponsePolicy, resolveAppPageRscResponsePolicy, resolveUncacheableCacheControl } from "./app-page-response.js";
+import { buildAppPageFontLinkHeader, readAppPageBinaryStream, resolveAppPageShellSpecialError, resolveAppPageSpecialError, resolveAppPageSpecialErrorStoredHeaders, 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 { buildAppPageLinkHeader, createAppPageFontData, createAppPageRscErrorTracker, createAppPageSsrErrorHandler, renderAppPageHtmlStream, renderAppPageHtmlStreamWithRecovery } from "./app-page-stream.js";
+import { createAppPageRscRenderStatusResolver } from "./app-page-rsc-render-status.js";
 import { finalizeAppPageCacheabilityEvaluationResponse, finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse } from "./app-page-cache-finalizer.js";
 import { createStaticLayoutClientReuseArtifactCompatibility, createStaticLayoutClientReusePayloadHash, createStaticLayoutClientReuseRouteId } from "./static-layout-client-reuse-proof.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
@@ -69,15 +74,32 @@ function applyRequestCacheLife(options) {
 * its response policy, such as error boundaries and special errors, get the
 * same header as the normal render.
 */
-function applyIneligibleRouteCachePolicy(response, options) {
+function applyIneligibleRouteCachePolicy(response, options, probeCacheLife = null) {
 	const cacheControl = resolveEarlyResponseCacheControl(options);
-	if (!cacheControl) return response;
+	const isRscRedirect = options.isRscRequest && response.headers.has("X-Vinext-Rsc-Redirect");
+	if (!cacheControl) {
+		const staleTimeSeconds = isRscRedirect ? resolveClientStaleTimeSeconds(probeCacheLife) : void 0;
+		if (staleTimeSeconds === void 0) return response;
+		const stamped = cloneForStamping(response);
+		applyClientStaleTimeHeader(stamped.headers, staleTimeSeconds);
+		return stamped;
+	}
+	const dynamicStaleTimeSeconds = isRscRedirect ? options.dynamicStaleTimeSeconds ?? resolveConfiguredDynamicStaleTimeSeconds() : void 0;
 	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 keepsMiddlewareCacheControl = middlewarePolicy.some(([name]) => name === "cache-control");
+	if (keepsMiddlewareCacheControl && dynamicStaleTimeSeconds === void 0) return response;
+	const stamped = cloneForStamping(response);
+	if (!keepsMiddlewareCacheControl) {
+		applyCdnResponseHeaders(stamped.headers, { cacheControl });
+		for (const [name, value] of middlewarePolicy) stamped.headers.set(name, value);
+	}
+	if (dynamicStaleTimeSeconds !== void 0) stamped.headers.set(VINEXT_DYNAMIC_STALE_TIME_HEADER, String(dynamicStaleTimeSeconds));
+	return stamped;
+}
+/** Some early responses have immutable headers, so stamp a copy. */
+function cloneForStamping(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. */
@@ -367,32 +389,26 @@ async function renderAppPageLifecycleImpl(options, renderSpan) {
 		}
 		return dynamicUsageObserved;
 	};
-	const configuredProbePageBeforeRender = options.probePageBeforeRender ?? options.isRscRequest;
-	const probePageBeforeRender = options.isRscRequest || configuredProbePageBeforeRender && !(options.peekDynamicUsage?.() ?? false);
-	const preRenderResult = await probeAppPageBeforeRender({
-		hasLoadingBoundary: options.hasLoadingBoundary,
-		probePageBeforeRender,
+	const probeOutcome = await runWithDetachedDynamicUsage(() => probeAppPageBeforeRender({
 		skipProbes: options.pprFallbackShellSignal !== void 0,
 		layoutCount: options.layoutCount,
 		probeLayoutAt(layoutIndex) {
 			return options.probeLayoutAt(layoutIndex);
 		},
-		probePage() {
-			return options.probePage();
-		},
 		renderLayoutSpecialError(specialError, layoutIndex) {
 			return options.renderLayoutSpecialError(specialError, layoutIndex);
 		},
-		renderPageSpecialError(specialError) {
-			return options.renderPageSpecialError(specialError);
-		},
 		resolveSpecialError: resolveAppPageSpecialError,
 		runWithSuppressedHookWarning(probe) {
 			return options.runWithSuppressedHookWarning(probe);
 		},
 		classification: options.classification
-	});
-	if (preRenderResult.response) return applyIneligibleRouteCachePolicy(preRenderResult.response, options);
+	}));
+	const preRenderResult = probeOutcome.result;
+	if (preRenderResult.response) {
+		if (probeOutcome.dynamicDetected) markDynamicUsage();
+		return applyIneligibleRouteCachePolicy(preRenderResult.response, options, probeOutcome.cacheLife);
+	}
 	const layoutFlags = preRenderResult.layoutFlags;
 	const artifactCompatibility = createAppPageArtifactCompatibility(options.element, options.routePattern);
 	const rootBoundaryId = artifactCompatibility?.rootBoundaryId ?? null;
@@ -457,7 +473,7 @@ async function renderAppPageLifecycleImpl(options, renderSpan) {
 	if (options.pprFallbackShellSignal) pprFallbackShellRsc = new Uint8Array(await readAppPageBinaryStream(rscStream));
 	let revalidateSeconds = options.revalidateSeconds;
 	let expireSeconds = options.expireSeconds;
-	const shouldWaitForAllReady = options.isPrerender === true && options.isSpeculativePrerender !== true;
+	const shouldWaitForAllReady = options.isPrerender === true && options.isSpeculativePrerender !== true || options.renderWholeDocument === true;
 	const shouldReadRequestCacheLifeForPrerender = options.isPrerender === true;
 	const mayResolveCacheLifeAfterHeaders = options.isProgressiveActionRender !== true && (revalidateSeconds === null || revalidateSeconds > 0) && !options.isDraftMode && !options.isForceDynamic && !shouldBypassRscCache;
 	const shouldCaptureRscForCacheMetadata = (options.isProduction || options.isPrerender === true) && mayResolveCacheLifeAfterHeaders && options.isStaticEligible;
@@ -473,6 +489,16 @@ async function renderAppPageLifecycleImpl(options, renderSpan) {
 	const capturedRscDataRef = { value: null };
 	if (rscCapture.sideStream && options.isRscRequest) capturedRscDataRef.value = readAppPageBinaryStream(rscCapture.sideStream);
 	if (options.isRscRequest) {
+		const resolveRscRenderStatus = options.isProduction && shouldCaptureRscForCacheMetadata && capturedRscDataRef.value !== null && options.isPrerender !== true && options.isRoutePPREnabled !== true ? createAppPageRscRenderStatusResolver({
+			basePath: options.basePath,
+			capturedRscData: capturedRscDataRef.value,
+			getCapturedSpecialError: rscErrorTracker.getCapturedSpecialError,
+			getCapturedSpecialErrors: rscErrorTracker.getCapturedSpecialErrors,
+			isForceStatic: options.isForceStatic,
+			loadSsrHandler: options.loadSsrHandler,
+			navigationContext: options.getNavigationContext(),
+			rootParams: options.rootParams
+		}) : void 0;
 		let requestCacheLifeForPrerender = null;
 		if (shouldWaitForAllReady) await settleCapturedRscRenderForCacheMetadata(capturedRscDataRef.value);
 		if (shouldReadRequestCacheLifeForPrerender) {
@@ -565,6 +591,7 @@ async function renderAppPageLifecycleImpl(options, renderSpan) {
 			mountedSlotsHeader: options.mountedSlotsHeader,
 			omitPendingDynamicCacheState: options.omitPendingDynamicCacheState,
 			renderMode: options.renderMode,
+			resolveRscRenderStatus,
 			preserveClientResponseHeaders: rscResponsePolicy.cacheState !== "MISS",
 			expireSeconds,
 			isStaticEligible: options.isStaticEligible,
@@ -590,6 +617,145 @@ async function renderAppPageLifecycleImpl(options, renderSpan) {
 	let requestCacheLifeForPrerender = null;
 	let dynamicUsedDuringHtmlRender = false;
 	let renderEnd;
+	let shellSpecialError = null;
+	const resolveHtmlCacheWrite = (dynamicUsedDuringRender) => {
+		const htmlResponsePolicy = resolveAppPageHtmlResponsePolicy({
+			dynamicUsedDuringRender,
+			isProgressiveActionRender: options.isProgressiveActionRender === true,
+			hasScriptNonce: Boolean(options.scriptNonce),
+			isDraftMode: options.isDraftMode,
+			isDynamicError: options.isDynamicError,
+			isForceDynamic: options.isForceDynamic,
+			isForceStatic: options.isForceStatic,
+			isProduction: options.isProduction,
+			isStaticEligible: options.isStaticEligible,
+			expireSeconds,
+			revalidateSeconds
+		});
+		const shouldSpeculativelyWriteCache = options.isProduction && shouldCaptureRscForCacheMetadata && !options.isEdgeRuntime && revalidateSeconds === null && !options.isDynamicError && !options.isForceStatic && !options.scriptNonce && options.isProgressiveActionRender !== true && !dynamicUsedDuringRender;
+		return {
+			htmlResponsePolicy,
+			shouldWriteHtmlCache: htmlResponsePolicy.shouldWriteToCache || shouldSpeculativelyWriteCache
+		};
+	};
+	const finalizeHtmlCacheWrite = (response, write) => finalizeAppPageHtmlCacheResponse(response, {
+		bypassInterceptionContextCache: options.bypassInterceptionContextCache,
+		capturedDynamicUsageBeforeContextCleanup: write.capturedDynamicUsageBeforeContextCleanup,
+		capturedRscDataPromise: capturedRscDataRef.value,
+		cleanPathname: options.cleanPathname,
+		clientTraceMetadataMarker,
+		consumeDynamicUsage: consumeRenderDynamicUsage,
+		consumeRenderObservationState,
+		createHtmlRenderObservation(input) {
+			return createAppPageRenderObservation({
+				boundaryOutcome: { kind: "success" },
+				cacheability: "public",
+				cacheTags: input.cacheTags,
+				cleanPathname: options.cleanPathname,
+				completeness: "complete",
+				output: htmlOutputScope,
+				params: options.navigationParams,
+				state: input.state
+			});
+		},
+		createRscRenderObservation(input) {
+			return createAppPageRenderObservation({
+				boundaryOutcome: { kind: "success" },
+				cacheability: "public",
+				cacheTags: input.cacheTags,
+				cleanPathname: options.cleanPathname,
+				completeness: "complete",
+				output: rscOutputScope,
+				params: options.navigationParams,
+				state: input.state
+			});
+		},
+		getPageTags() {
+			return options.getPageTags();
+		},
+		getRequestCacheLife() {
+			return readRequestCacheLifeForCachePolicy(options);
+		},
+		headers: write.headers,
+		isrDebug: options.isrDebug,
+		isrHtmlKey: options.isrHtmlKey,
+		isrRscKey: options.isrRscKey,
+		isrSet: options.isrSet,
+		interceptionContext: options.interceptionContext,
+		interceptionId: options.interceptionId,
+		omitPendingDynamicCacheState: options.omitPendingDynamicCacheState,
+		preserveClientResponseHeaders: !write.htmlResponsePolicy.shouldWriteToCache,
+		expireSeconds,
+		isStaticEligible: options.isStaticEligible,
+		revalidateSeconds: resolveAppPageCacheWriteRevalidateSeconds({
+			isDynamicError: options.isDynamicError,
+			isForceStatic: options.isForceStatic,
+			isStaticEligible: options.isStaticEligible,
+			revalidateSeconds
+		}),
+		linkHeader: write.linkHeader,
+		status: write.status,
+		waitUntil(cachePromise) {
+			options.waitUntil?.(cachePromise);
+		}
+	});
+	const mayStoreShellSpecialError = () => options.isProduction && shouldCaptureRscForCacheMetadata && options.isPrerender !== true && capturedRscDataRef.value !== null && resolveEarlyResponseCacheControl(options) === null;
+	const mayPrerenderShellSpecialError = () => options.isPrerender === true && options.isSpeculativePrerender !== true && options.pprFallbackShellSignal === void 0 && shouldCaptureRscForCacheMetadata && capturedRscDataRef.value !== null && resolveEarlyResponseCacheControl(options) === null;
+	const readPrerenderCacheMetadata = () => ({
+		cacheTags: options.getPageTags(),
+		requestCacheLife: readRequestCacheLifeForPrerender(options)
+	});
+	let prerenderedSpecialError = null;
+	const finalizePrerenderedShellSpecialErrorResponse = async (response, specialError, prerendered) => {
+		if (response.status !== specialError.statusCode) return applyIneligibleRouteCachePolicy(response, options);
+		const body = await response.arrayBuffer();
+		const { cacheTags, requestCacheLife } = prerendered.redirectMetadata ?? readPrerenderCacheMetadata();
+		({expireSeconds, revalidateSeconds} = applyRequestCacheLife({
+			expireSeconds,
+			requestCacheLife,
+			revalidateSeconds
+		}));
+		const { htmlResponsePolicy } = resolveHtmlCacheWrite(prerendered.dynamicUsed || consumeRenderDynamicUsage());
+		const headers = new Headers(response.headers);
+		if (htmlResponsePolicy.cacheControl && !headers.has("cache-control")) headers.set("Cache-Control", htmlResponsePolicy.cacheControl);
+		applyPrerenderCacheLifeHeader(headers, requestCacheLife);
+		applyPrerenderCacheTagsHeader(headers, cacheTags);
+		getRequestExecutionContext()?.recordPrerenderSpecialError?.({
+			headers: resolveAppPageSpecialErrorStoredHeaders(specialError, options.basePath) ?? {},
+			status: response.status
+		});
+		const prerenderResponse = new Response(body, {
+			headers,
+			status: response.status,
+			statusText: response.statusText
+		});
+		copyLinkHeaderProvenance(response.headers, prerenderResponse.headers);
+		return prerenderResponse;
+	};
+	const finalizeShellSpecialErrorResponse = (response, specialError) => {
+		if (response.status !== specialError.statusCode) return applyIneligibleRouteCachePolicy(response, options);
+		const dynamicUsedDuringRender = consumeRenderDynamicUsage();
+		const { htmlResponsePolicy, shouldWriteHtmlCache } = resolveHtmlCacheWrite(dynamicUsedDuringRender);
+		const headers = new Headers(response.headers);
+		if (htmlResponsePolicy.cacheControl && !headers.has("cache-control")) headers.set("Cache-Control", htmlResponsePolicy.cacheControl);
+		if (htmlResponsePolicy.cacheState) setCacheStateHeaders(headers, htmlResponsePolicy.cacheState);
+		const policyResponse = new Response(response.body, {
+			headers,
+			status: response.status,
+			statusText: response.statusText
+		});
+		copyLinkHeaderProvenance(response.headers, policyResponse.headers);
+		if (!shouldWriteHtmlCache) return policyResponse;
+		const clientResponse = finalizeHtmlCacheWrite(policyResponse, {
+			capturedDynamicUsageBeforeContextCleanup: () => dynamicUsedDuringRender,
+			headers: resolveAppPageSpecialErrorStoredHeaders(specialError, options.basePath),
+			htmlResponsePolicy,
+			linkHeader: getFrameworkLinkHeader(response.headers),
+			status: response.status
+		});
+		copyLinkHeaderProvenance(response.headers, clientResponse.headers);
+		return clientResponse;
+	};
 	const htmlRender = await renderAppPageHtmlStreamWithRecovery({
 		onShellRendered() {
 			if (!options.isProduction) renderEnd = performance.now();
@@ -656,30 +822,34 @@ async function renderAppPageLifecycleImpl(options, renderSpan) {
 				isStaticGeneration: options.isPrerender === true,
 				isForceStatic: options.isForceStatic,
 				isCacheCandidate: isCacheCandidateHtmlRender,
-				onSsrError: createAppPageSsrErrorHandler(onSsrError, rscErrorTracker.isCapturedError)
+				onSsrError: createAppPageSsrErrorHandler(onSsrError, rscErrorTracker.isCapturedError),
+				mirrorNextFlight: () => rscErrorTracker.getCapturedSpecialError() !== null
 			});
 		},
-		renderSpecialErrorResponse(specialError) {
-			return options.renderPageSpecialError(specialError);
+		async renderSpecialErrorResponse(specialError) {
+			shellSpecialError = specialError;
+			const mayPrerender = mayPrerenderShellSpecialError();
+			if (mayStoreShellSpecialError() || mayPrerender) await settleCapturedRscRenderForCacheMetadata(capturedRscDataRef.value, peekRenderDynamicUsage);
+			if (mayPrerender) prerenderedSpecialError = {
+				dynamicUsed: consumeRenderDynamicUsage(),
+				redirectMetadata: specialError.kind === "redirect" ? readPrerenderCacheMetadata() : null
+			};
+			return options.renderPageSpecialError(specialError, { isCacheCandidate: isCacheCandidateHtmlRender });
 		},
-		resolveSpecialError: resolveAppPageSpecialError
+		resolveSpecialError(error) {
+			return resolveAppPageShellSpecialError(error, rscErrorTracker.getCapturedSpecialErrors(error));
+		}
 	});
 	options.onRenderComplete?.(htmlRender.renderComplete);
-	if (htmlRender.response) return applyIneligibleRouteCachePolicy(htmlRender.response, options);
+	if (htmlRender.response) {
+		if (shellSpecialError && options.isProduction && options.isPrerender !== true && resolveEarlyResponseCacheControl(options) === null) return finalizeShellSpecialErrorResponse(htmlRender.response, shellSpecialError);
+		if (shellSpecialError && prerenderedSpecialError) return finalizePrerenderedShellSpecialErrorResponse(htmlRender.response, shellSpecialError, prerenderedSpecialError);
+		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);
 	if (options.isPrerender === true) await htmlRender.metadataReady;
-	if (options.hasLoadingBoundary || !probePageBeforeRender) {
-		const captured = rscErrorTracker.getCapturedSpecialError();
-		if (captured) {
-			const specialError = resolveAppPageSpecialError(captured);
-			if (specialError) {
-				htmlStream.cancel().catch(() => {});
-				return applyIneligibleRouteCachePolicy(await options.renderPageSpecialError(specialError), options);
-			}
-		}
-	}
 	let dynamicUsedDuringRender = consumeRenderDynamicUsage();
 	dynamicUsedDuringHtmlRender = dynamicUsedDuringRender;
 	const stopSpeculativeMetadataWaitOnDynamicUsage = options.isSpeculativePrerender === true && shouldReadRequestCacheLifeForPrerender ? () => {
@@ -709,19 +879,7 @@ async function renderAppPageLifecycleImpl(options, renderSpan) {
 		dynamicUsedDuringHtmlRender = dynamicUsedBeforeContextCleanup;
 		options.clearRequestContext();
 	});
-	const htmlResponsePolicy = resolveAppPageHtmlResponsePolicy({
-		dynamicUsedDuringRender,
-		isProgressiveActionRender: options.isProgressiveActionRender === true,
-		hasScriptNonce: Boolean(options.scriptNonce),
-		isDraftMode: options.isDraftMode,
-		isDynamicError: options.isDynamicError,
-		isForceDynamic: options.isForceDynamic,
-		isForceStatic: options.isForceStatic,
-		isProduction: options.isProduction,
-		isStaticEligible: options.isStaticEligible,
-		expireSeconds,
-		revalidateSeconds
-	});
+	const { htmlResponsePolicy, shouldWriteHtmlCache } = resolveHtmlCacheWrite(dynamicUsedDuringRender);
 	const htmlResponseTiming = buildResponseTiming({
 		compileEnd,
 		handlerStart: options.handlerStart,
@@ -746,8 +904,7 @@ async function renderAppPageLifecycleImpl(options, renderSpan) {
 		applyCdnResponseHeaders(response.headers, { cacheControl: NEVER_CACHE_CONTROL });
 		return response;
 	}
-	const shouldSpeculativelyWriteCache = options.isProduction && shouldCaptureRscForCacheMetadata && !options.isEdgeRuntime && revalidateSeconds === null && !options.isDynamicError && !options.isForceStatic && !options.scriptNonce && options.isProgressiveActionRender !== true && !dynamicUsedDuringRender;
-	if (htmlResponsePolicy.shouldWriteToCache || shouldSpeculativelyWriteCache) {
+	if (shouldWriteHtmlCache) {
 		const isrResponse = buildAppPageHtmlResponse(safeHtmlStream, {
 			cacheTags: options.isPrerender === true ? options.getPageTags() : void 0,
 			draftCookie,
@@ -759,66 +916,10 @@ async function renderAppPageLifecycleImpl(options, renderSpan) {
 			timing: htmlResponseTiming
 		});
 		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,
-			createHtmlRenderObservation(input) {
-				return createAppPageRenderObservation({
-					boundaryOutcome: { kind: "success" },
-					cacheability: "public",
-					cacheTags: input.cacheTags,
-					cleanPathname: options.cleanPathname,
-					completeness: "complete",
-					output: htmlOutputScope,
-					params: options.navigationParams,
-					state: input.state
-				});
-			},
-			createRscRenderObservation(input) {
-				return createAppPageRenderObservation({
-					boundaryOutcome: { kind: "success" },
-					cacheability: "public",
-					cacheTags: input.cacheTags,
-					cleanPathname: options.cleanPathname,
-					completeness: "complete",
-					output: rscOutputScope,
-					params: options.navigationParams,
-					state: input.state
-				});
-			},
-			getPageTags() {
-				return options.getPageTags();
-			},
-			getRequestCacheLife() {
-				return readRequestCacheLifeForCachePolicy(options);
-			},
-			isrDebug: options.isrDebug,
-			isrHtmlKey: options.isrHtmlKey,
-			isrRscKey: options.isrRscKey,
-			isrSet: options.isrSet,
-			interceptionContext: options.interceptionContext,
-			interceptionId: options.interceptionId,
-			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,
-			waitUntil(cachePromise) {
-				options.waitUntil?.(cachePromise);
-			}
+		return finalizeHtmlCacheWrite(isrResponse, {
+			capturedDynamicUsageBeforeContextCleanup: () => dynamicUsedBeforeContextCleanup,
+			htmlResponsePolicy,
+			linkHeader: linkHeader ?? null
 		});
 	}
 	const response = buildAppPageHtmlResponse(safeHtmlStream, {

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

@@ -49,7 +49,6 @@ type ResolveAppPageGenerateStaticParamsSourcesOptions = {
 };
 type BuildAppPageElementOptions<TElement> = {
   buildPageElement: () => Promise<TElement>;
-  probePageSpecialError?: () => Promise<AppPageSpecialError | null>;
   renderErrorBoundaryPage: (error: unknown) => Promise<Response | null>;
   renderSpecialError: (specialError: AppPageSpecialError) => Promise<Response>;
   resolveSpecialError: (error: unknown) => AppPageSpecialError | null;

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

@@ -333,8 +333,7 @@ async function buildAppPageElement(options) {
 			response: null
 		};
 	} catch (error) {
-		const buildSpecialError = options.resolveSpecialError(error);
-		const specialError = (buildSpecialError ? await options.probePageSpecialError?.() : null) ?? buildSpecialError;
+		const specialError = options.resolveSpecialError(error);
 		if (specialError) return {
 			element: null,
 			response: await options.renderSpecialError(specialError)

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

@@ -71,9 +71,10 @@ type BuildAppPageHtmlResponseOptions = {
   timing?: AppPageResponseTiming;
 };
 /**
- * Only ever set from a *completed* render's cacheLife (cache replay or
- * prerender seed) — `use cache` scopes keep resolving after headers commit,
- * so a streaming response can never carry it.
+ * Only ever set from a *completed* render's cacheLife (cache replay,
+ * prerender seed, or a layout probe's early redirect) — `use cache` scopes
+ * keep resolving after headers commit, so a streaming response can never
+ * carry it.
  */
 export declare function applyClientStaleTimeHeader(headers: Headers, staleTimeSeconds: number | undefined): void;
 /**

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

@@ -18,9 +18,10 @@ function applyDynamicStaleTimeHeader(headers, dynamicStaleTimeSeconds) {
 	if (dynamicStaleTimeSeconds !== void 0 && Number.isInteger(dynamicStaleTimeSeconds) && dynamicStaleTimeSeconds >= 0) headers.set(VINEXT_DYNAMIC_STALE_TIME_HEADER, String(dynamicStaleTimeSeconds));
 }
 /**
-* Only ever set from a *completed* render's cacheLife (cache replay or
-* prerender seed) — `use cache` scopes keep resolving after headers commit,
-* so a streaming response can never carry it.
+* Only ever set from a *completed* render's cacheLife (cache replay,
+* prerender seed, or a layout probe's early redirect) — `use cache` scopes
+* keep resolving after headers commit, so a streaming response can never
+* carry it.
 */
 function applyClientStaleTimeHeader(headers, staleTimeSeconds) {
 	if (staleTimeSeconds === void 0) return;

package/dist/server/app-page-route-wiring.d.ts

@@ -140,14 +140,15 @@ type BuildAppPageRouteElementOptions<TModule extends AppPageModule = AppPageModu
   makeThenableParams: MakeThenableParams;
   matchedParams: AppPageParams;
   metadataPlacement?: "body" | "head";
-  resolvedMetadata: Metadata | null;
+  /**
+   * Starts resolving the page's head. The head, its streamed body tags and its
+   * error outlet each call this while Flight renders them, so callers memoise
+   * it per render with React's `cache()`. Without it the head has no metadata.
+   */
+  resolveHead?: (() => AppPageRouteHead) | null;
   resolvedMetadataPathname?: string;
-  resolvedViewport: Viewport;
   scriptNonce?: string;
-  streamingMetadata?: Promise<Metadata | null> | null;
-  streamingMetadataOutlet?: Promise<unknown> | null;
   streamingMetadataOutletSuspended?: boolean;
-  streamingMetadataTags?: Promise<Metadata | null> | null;
   trailingSlash?: boolean;
   rootForbiddenModule?: TModule | null;
   rootNotFoundModule?: TModule | null;
@@ -158,6 +159,17 @@ type BuildAppPageRouteElementOptions<TModule extends AppPageModule = AppPageModu
   searchParams?: unknown;
   slotOverrides?: Readonly<Record<string, AppPageSlotOverride<TModule>>> | null;
 };
+/**
+ * A page's head as Flight renders it. `metadata` and `viewport` hold the tags
+ * to render, including the HTTP access fallback's when resolution failed, so
+ * they never reject. `outlet` rejects with the resolution error so the route's
+ * boundaries can handle it.
+ */
+export type AppPageRouteHead = {
+  metadata: Promise<Metadata | null>;
+  outlet: Promise<null>;
+  viewport: Promise<Viewport>;
+};
 type MakeThenableParams = (params: AppPageParams, observer?: ThenableParamsObserver) => unknown;
 type BuildAppPageElementsOptions<TModule extends AppPageModule = AppPageModule, TErrorModule extends AppPageErrorModule = AppPageErrorModule> = BuildAppPageRouteElementOptions<TModule, TErrorModule> & {
   interception?: AppElementsInterception | null;