vinext 1.0.1 → 1.2.0

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

@@ -26,34 +26,49 @@ async function renderAppPageCacheArtifactsImpl(options, renderSpan) {
 	const rscCapture = teeAppPageRscStreamForCapture(rscStream, options.captureRscData);
 	const capturedRscDataRef = { value: null };
 	const fontPreloads = options.getFontPreloads();
-	const htmlResult = await (await options.loadSsrHandler()).handleSsr(rscCapture.ssrStream, options.getNavigationContext(), {
-		links: options.getFontLinks(),
-		styles: options.getFontStyles(),
-		preloads: fontPreloads
-	}, {
-		basePath: options.basePath,
-		clientTraceMetadata: options.clientTraceMetadata,
-		reactMaxHeadersLength: options.reactMaxHeadersLength,
-		rootParams: options.rootParams,
-		waitForAllReady: options.waitForAllReady,
-		isStaticGeneration: true,
-		isForceStatic: options.isForceStatic,
-		onSsrError: options.onSsrError && options.isCapturedRscError ? createAppPageSsrErrorHandler((error) => {
-			recordAppPageRenderError(renderSpan, error);
-			return options.onSsrError?.(error);
-		}, options.isCapturedRscError) : options.onSsrError ? (error) => {
-			recordAppPageRenderError(renderSpan, error);
-			return options.onSsrError?.(error);
-		} : void 0,
-		...rscCapture.sideStream ? {
-			sideStream: rscCapture.sideStream,
-			capturedRscDataRef
-		} : {}
-	});
-	const htmlStream = isAppSsrRenderResult(htmlResult) ? htmlResult.htmlStream : htmlResult;
-	const reactLinkHeader = isAppSsrRenderResult(htmlResult) ? htmlResult.linkHeader : void 0;
-	const linkHeader = buildAppPageLinkHeader(reactLinkHeader, buildAppPageFontLinkHeader(fontPreloads), options.reactMaxHeadersLength);
-	const html = await readStreamAsText(htmlStream);
+	const ssrHandler = await options.loadSsrHandler();
+	let htmlResult = null;
+	let specialErrorDocument = null;
+	try {
+		htmlResult = await ssrHandler.handleSsr(rscCapture.ssrStream, options.getNavigationContext(), {
+			links: options.getFontLinks(),
+			styles: options.getFontStyles(),
+			preloads: fontPreloads
+		}, {
+			basePath: options.basePath,
+			clientTraceMetadata: options.clientTraceMetadata,
+			reactMaxHeadersLength: options.reactMaxHeadersLength,
+			rootParams: options.rootParams,
+			waitForAllReady: options.waitForAllReady,
+			mirrorNextFlight: options.mirrorNextFlight,
+			isStaticGeneration: true,
+			isForceStatic: options.isForceStatic,
+			onSsrError: options.onSsrError && options.isCapturedRscError ? createAppPageSsrErrorHandler((error) => {
+				recordAppPageRenderError(renderSpan, error);
+				return options.onSsrError?.(error);
+			}, options.isCapturedRscError) : options.onSsrError ? (error) => {
+				recordAppPageRenderError(renderSpan, error);
+				return options.onSsrError?.(error);
+			} : void 0,
+			...rscCapture.sideStream ? {
+				sideStream: rscCapture.sideStream,
+				capturedRscDataRef
+			} : {}
+		});
+	} catch (error) {
+		if (!options.renderShellSpecialError) throw error;
+		await capturedRscDataRef.value?.catch(() => {});
+		specialErrorDocument = await options.renderShellSpecialError(error);
+		if (!specialErrorDocument) throw error;
+	}
+	let html = specialErrorDocument?.html ?? "";
+	let linkHeader = specialErrorDocument?.linkHeader;
+	if (htmlResult) {
+		const htmlStream = isAppSsrRenderResult(htmlResult) ? htmlResult.htmlStream : htmlResult;
+		const reactLinkHeader = isAppSsrRenderResult(htmlResult) ? htmlResult.linkHeader : void 0;
+		linkHeader = buildAppPageLinkHeader(reactLinkHeader, buildAppPageFontLinkHeader(fontPreloads), options.reactMaxHeadersLength);
+		html = await readStreamAsText(htmlStream);
+	}
 	let rscData;
 	if (options.captureRscData) {
 		const capturedPromise = capturedRscDataRef.value;
@@ -65,24 +80,29 @@ async function renderAppPageCacheArtifactsImpl(options, renderSpan) {
 	const observationState = consumeAppPageRenderObservationState();
 	consumeInvalidDynamicUsageError();
 	const usedDynamicApi = consumeDynamicUsage() || isRenderDynamicLatched();
+	const htmlRenderObservation = createAppPageRenderObservation({
+		boundaryOutcome: { kind: "success" },
+		cacheability: "public",
+		cacheTags: tags,
+		cleanPathname: options.cleanPathname,
+		completeness: "complete",
+		output: createAppPageHtmlOutputScope({
+			element: options.element,
+			renderEpoch: null,
+			rootBoundaryId: null,
+			routePattern: options.route.pattern
+		}),
+		params: options.navigationParams,
+		state: observationState
+	});
 	const result = {
 		html,
-		htmlRenderObservation: createAppPageRenderObservation({
-			boundaryOutcome: { kind: "success" },
-			cacheability: "public",
-			cacheTags: tags,
-			cleanPathname: options.cleanPathname,
-			completeness: "complete",
-			output: createAppPageHtmlOutputScope({
-				element: options.element,
-				renderEpoch: null,
-				rootBoundaryId: null,
-				routePattern: options.route.pattern
-			}),
-			params: options.navigationParams,
-			state: observationState
-		}),
+		htmlRenderObservation,
 		...linkHeader ? { linkHeader } : {},
+		...specialErrorDocument ? {
+			headers: specialErrorDocument.headers,
+			status: specialErrorDocument.status
+		} : {},
 		tags,
 		usedDynamicApi,
 		cacheControl: typeof cacheLife?.revalidate === "number" ? {

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

@@ -21,11 +21,15 @@ export type AppPageCacheOutcomeMetric = Readonly<{
 type AppPageCacheOutcomeRecorder = (metric: AppPageCacheOutcomeMetric) => void;
 type AppPageCacheRenderResult = {
   cacheControl?: CacheControlMetadata;
+  /** Response headers stored with both entries, such as a redirect's `location`. */
+  headers?: Record<string, string>;
   html: string;
   htmlRenderObservation: RenderObservation;
   linkHeader?: string;
   rscData: ArrayBuffer;
   rscRenderObservation: RenderObservation;
+  /** The status of a render whose shell ended in a special error. */
+  status?: number;
   /**
    * The route-level revalidate of the route this render regenerated, or null
    * when it has none and the render's cacheLife sets it. Undefined keeps the
@@ -40,6 +44,7 @@ type BuildAppPageCachedResponseOptions = {
   cacheState: "HIT" | "STALE";
   expireSeconds?: number;
   isEdgeRuntime?: boolean;
+  isRoutePPREnabled?: boolean;
   isRscRequest: boolean;
   middlewareHeaders?: Headers | null;
   middlewareStatus?: number | null;
@@ -88,7 +93,7 @@ type ReadAppPageFallbackShellCacheResponseOptions = {
   isEdgeRuntime?: boolean;
   isrDebug?: AppPageDebugLogger;
   isrGet: AppPageCacheGetter;
-  isrHtmlKey: (pathname: string) => string;
+  isrFallbackShellHtmlKey: (pathname: string) => string;
   middlewareHeaders?: Headers | null;
   middlewareStatus?: number | null;
   revalidateSeconds: number;

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

@@ -1,5 +1,5 @@
 import { VINEXT_MOUNTED_SLOTS_HEADER, VINEXT_RSC_VARY_HEADER } from "./app-rsc-vary.js";
-import { VINEXT_PARAMS_HEADER, VINEXT_RENDERED_PATH_AND_SEARCH_HEADER } from "./headers.js";
+import { VINEXT_PARAMS_HEADER, VINEXT_RENDERED_PATH_AND_SEARCH_HEADER, VINEXT_SPECIAL_ERROR_STATUS_HEADER } from "./headers.js";
 import { applyCdnResponseHeaders } from "./cache-control.js";
 import { decideIsr } from "./isr-decision.js";
 import { buildAppPageCacheValue, isrCacheControl, resolveRouteExpireSeconds } from "./isr-cache.js";
@@ -53,6 +53,10 @@ function buildAppPageCachedHeaders(options) {
 	if (options.params && Object.keys(options.params).length > 0) headers.set(VINEXT_PARAMS_HEADER, encodeURIComponent(JSON.stringify(options.params)));
 	if (options.mountedSlotsHeader) headers.set(VINEXT_MOUNTED_SLOTS_HEADER, options.mountedSlotsHeader);
 	applyClientStaleTimeHeader(headers, options.staleTimeSeconds);
+	for (const [name, value] of Object.entries(options.storedHeaders ?? {})) {
+		if (name.toLowerCase() === "link") continue;
+		for (const item of Array.isArray(value) ? value : [value]) headers.append(name, item);
+	}
 	mergeMiddlewareResponseHeaders(headers, options.middlewareHeaders ?? null);
 	if (options.linkHeader) {
 		if (Array.isArray(options.linkHeader)) for (const value of options.linkHeader) headers.append("Link", value);
@@ -88,8 +92,15 @@ function resolveRegenerationFailureCacheControl(previous) {
 		...previous.stale === void 0 ? {} : { stale: previous.stale }
 	};
 }
+function isRedirectStatus(status) {
+	return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
 function buildAppPageCachedResponse(cachedValue, options) {
-	const status = options.middlewareStatus ?? (cachedValue.status || 200);
+	const storedStatus = cachedValue.status || 200;
+	const isRedirect = isRedirectStatus(storedStatus);
+	const isHttpErrorFallbackStatus = storedStatus === 401 || storedStatus === 403 || storedStatus === 404;
+	const replayStatus = options.isRscRequest && (isRedirect || options.isRoutePPREnabled === true) ? 200 : storedStatus;
+	const status = isRedirect || isHttpErrorFallbackStatus ? replayStatus : options.middlewareStatus ?? replayStatus;
 	const { cacheControl } = decideIsr({
 		cacheState: options.cacheState,
 		kind: "app-page",
@@ -108,17 +119,19 @@ function buildAppPageCachedResponse(cachedValue, options) {
 			middlewareHeaders: options.middlewareHeaders,
 			mountedSlotsHeader: options.mountedSlotsHeader,
 			params: options.params,
-			staleTimeSeconds
+			staleTimeSeconds,
+			storedHeaders: cachedValue.headers
 		});
 		if (options.renderedPathAndSearch) rscHeaders.set(VINEXT_RENDERED_PATH_AND_SEARCH_HEADER, encodeURIComponent(options.renderedPathAndSearch));
 		applyRscCompatibilityIdHeader(rscHeaders);
 		applyRscDeploymentIdHeader(rscHeaders);
+		if (isHttpErrorFallbackStatus && status === storedStatus) rscHeaders.set(VINEXT_SPECIAL_ERROR_STATUS_HEADER, String(storedStatus));
 		return new Response(cachedValue.rscData, {
 			status,
 			headers: rscHeaders
 		});
 	}
-	if (typeof cachedValue.html !== "string" || cachedValue.html.length === 0) return null;
+	if (typeof cachedValue.html !== "string" || cachedValue.html.length === 0 && !isRedirect) return null;
 	const htmlHeaders = buildAppPageCachedHeaders({
 		cacheControl,
 		cacheState: options.cacheState,
@@ -126,7 +139,8 @@ function buildAppPageCachedResponse(cachedValue, options) {
 		isEdgeRuntime: options.isEdgeRuntime,
 		linkHeader: cachedValue.headers?.link,
 		middlewareHeaders: options.middlewareHeaders,
-		staleTimeSeconds
+		staleTimeSeconds,
+		storedHeaders: cachedValue.headers
 	});
 	const response = new Response(cachedValue.html, {
 		status,
@@ -218,6 +232,7 @@ async function readAppPageCacheResponse(options) {
 				cacheControl: cached?.value.cacheControl,
 				expireSeconds: options.expireSeconds,
 				isEdgeRuntime: options.isEdgeRuntime,
+				isRoutePPREnabled: options.isRoutePPREnabled,
 				isRscRequest: options.isRscRequest,
 				middlewareHeaders: options.middlewareHeaders,
 				middlewareStatus: options.middlewareStatus,
@@ -287,9 +302,13 @@ see more here https://nextjs.org/docs/messages/app-static-to-dynamic-error`);
 						return false;
 					}
 				};
-				if (!await store(rscKey, buildAppPageCacheValue("", revalidatedPage.rscData, 200, revalidatedPage.rscRenderObservation))) return;
+				const status = revalidatedPage.status ?? 200;
+				if (!await store(rscKey, buildAppPageCacheValue("", revalidatedPage.rscData, status, revalidatedPage.rscRenderObservation, revalidatedPage.headers))) return;
 				if (!options.isRscRequest) {
-					if (!await store(isrKey, buildAppPageCacheValue(revalidatedPage.html, void 0, 200, revalidatedPage.htmlRenderObservation, revalidatedPage.linkHeader ? { link: revalidatedPage.linkHeader } : void 0))) return;
+					if (!await store(isrKey, buildAppPageCacheValue(revalidatedPage.html, void 0, status, revalidatedPage.htmlRenderObservation, revalidatedPage.linkHeader ? {
+						...revalidatedPage.headers,
+						link: revalidatedPage.linkHeader
+					} : revalidatedPage.headers))) return;
 				}
 				options.isrDebug?.("regen complete", options.cleanPathname);
 			};
@@ -306,6 +325,7 @@ see more here https://nextjs.org/docs/messages/app-static-to-dynamic-error`);
 				cacheControl: cached.value.cacheControl,
 				expireSeconds: options.expireSeconds,
 				isEdgeRuntime: options.isEdgeRuntime,
+				isRoutePPREnabled: options.isRoutePPREnabled,
 				isRscRequest: options.isRscRequest,
 				middlewareHeaders: options.middlewareHeaders,
 				middlewareStatus: options.middlewareStatus,
@@ -355,7 +375,7 @@ see more here https://nextjs.org/docs/messages/app-static-to-dynamic-error`);
 	return null;
 }
 async function readAppPageFallbackShellCacheResponse(options) {
-	const isrKey = options.isrHtmlKey(options.fallbackPathname);
+	const isrKey = options.isrFallbackShellHtmlKey(options.fallbackPathname);
 	try {
 		const cached = await options.isrGet(isrKey);
 		const cachedValue = getCachedAppPageValue(cached);

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

@@ -13,7 +13,8 @@ import { AppPageSsrHandler } from "./app-page-stream.js";
 import { AppRenderErrorContextOverrides } from "./app-rsc-error-handler.js";
 import { AppPageCacheSetter, ISRCacheEntry } from "./isr-cache.js";
 import { PprFallbackShellState } from "../shims/ppr-fallback-shell.js";
-import { FetchCacheMode } from "../shims/fetch-cache.js";
+import { FetchCacheMode } from "../shims/fetch-cache-state.js";
+import "../shims/fetch-cache.js";
 import { AppPagePprFallbackCacheShell } from "./app-ppr-fallback-shell.js";
 import { WarmPprFallbackShellCachesOptions } from "./app-ppr-fallback-shell-render.js";
 import { ValidateAppPageDynamicParamsOptions } from "./app-page-request.js";
@@ -142,6 +143,7 @@ export type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
     observeMetadataSearchParamsAccess?: boolean;
     observePageSearchParamsAccess?: boolean;
     serveStreamingMetadata?: boolean;
+    placeStreamedMetadataInHead?: boolean;
   }) => Promise<AppPageElement>;
   clientReuseManifest?: ClientReuseManifestParseResult;
   cleanPathname: string;
@@ -196,6 +198,7 @@ export type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   isRscRequest: boolean;
   isrDebug?: AppPageDebugLogger;
   isrGet: AppPageCacheGetter;
+  isrFallbackShellHtmlKey: (pathname: string) => string;
   isrHtmlKey: (pathname: string) => string;
   isrRscKey: (pathname: string, mountedSlotsHeader?: string | null, renderMode?: AppRscRenderMode, interceptionContext?: string | null, interceptionId?: string | null) => string;
   isrSet: AppPageCacheSetter;
@@ -221,13 +224,14 @@ export type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   staticParamsValidationParams?: AppPageParams;
   rootParams?: RootParams;
   probeLayoutAt: (layoutIndex: number, layoutParamAccess?: AppLayoutParamAccessTracker) => unknown;
-  probePage: (searchParams?: URLSearchParams) => unknown;
   expireSeconds?: number;
   renderErrorBoundaryPage: (error: unknown, errorOrigin?: "rsc" | "ssr") => Promise<Response | null>;
   renderHttpAccessFallbackPage: (statusCode: number, opts: {
     boundaryComponent?: unknown;
     boundaryModule?: AppPageModule | null;
     intercept?: AppPageDispatchInterceptOptions | null;
+    /** The document may be stored, so it must not carry the request's query. */
+    isCacheCandidate?: boolean;
     layouts?: readonly AppPageModule[];
     matchedParams: AppPageParams;
   }, middlewareContext: AppPageMiddlewareContext | null) => Promise<Response | null>;
@@ -268,6 +272,12 @@ export type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
     searchParams: URLSearchParams;
   }) => void;
   renderMode?: AppRscRenderMode;
+  /**
+   * Render the document whole before its first byte, with streamed metadata in
+   * `<head>`, as a background regeneration does. The adapter sets this for a
+   * render no client is waiting on, such as its regeneration or a warm-up.
+   */
+  renderWholeDocument?: boolean;
 };
 export declare function shouldReadAppPageCache(options: {
   isProgressiveActionRender: boolean;

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

@@ -3,29 +3,31 @@ import "../utils/protocol-headers.js";
 import { getRequestExecutionContext } from "../shims/request-context.js";
 import { VINEXT_INTERCEPTION_ID_HEADER, VINEXT_RSC_VARY_HEADER } from "./app-rsc-vary.js";
 import "./headers.js";
+import { runInWorkStoreScope } from "../shims/internal/work-store-scope.js";
 import { beginRouteCacheability, isRouteCacheabilityIdentityProbe, isRouteCacheabilityProbe, markRouteCacheabilityPatternDynamic, readRouteCacheabilityState } from "../shims/cacheability-classification.js";
 import { APP_RSC_RENDER_MODE_PREFETCH_DYNAMIC_SHELL } from "./app-rsc-render-mode.js";
-import { AppElementsWire } from "./app-elements-wire.js";
-import "./app-elements.js";
 import { consumeDynamicUsage, consumeInvalidDynamicUsageError, getAndClearPendingCookies, getDraftModeCookieHeader, getHeadersContext, isDraftModeRequest, peekDynamicUsage, peekRenderRequestApiUsage, runWithIsolatedDynamicUsage, setHeadersContext } from "../shims/headers.js";
 import { _captureRequestScopedCacheLifeAccessors } from "../shims/cache-request-state.js";
 import { ensureFetchPatch, getCollectedFetchTags, peekDynamicFetchObservations, runWithFetchDedupe, setCurrentFetchCacheMode, setCurrentFetchRevalidate, setCurrentFetchSoftTags, setCurrentForceDynamicFetchDefault, setRefreshStaleFetchesInForeground } from "../shims/fetch-cache.js";
 import { cacheabilityManifestPageState } from "./cacheability-manifest.js";
+import { isAppPageStaticEligible } from "./app-segment-config.js";
+import { AppElementsWire } from "./app-elements-wire.js";
+import "./app-elements.js";
 import { VINEXT_RSC_CONTENT_TYPE, applyRscCompatibilityIdHeader, applyRscDeploymentIdHeader } from "./app-rsc-cache-busting.js";
 import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
+import { getFrameworkLinkHeader } from "./app-response-header-provenance.js";
 import { resolveUncacheableCacheControl } from "./app-page-response.js";
 import { buildRscRedirectFlightStream } from "./app-rsc-redirect-flight.js";
-import { buildAppPageSpecialErrorResponse, probeAppPageThrownError, resolveAppPageSpecialError } from "./app-page-execution.js";
+import { buildAppPageSpecialErrorResponse, resolveAppPageShellSpecialError, resolveAppPageSpecialError, resolveAppPageSpecialErrorStoredHeaders } from "./app-page-execution.js";
 import { resolveAppPageTraceOperation } from "./app-page-tracing.js";
 import { createAppPageTreePath } from "./app-page-route-wiring.js";
 import { traceResponseStart } from "./response-start-tracing.js";
 import { buildAppPageTags } from "./implicit-tags.js";
 import { consumeAppPageRenderObservationState, discardAppPageRenderState } from "./app-page-render-observation.js";
-import { isAppPageStaticEligible } from "./app-segment-config.js";
+import { createAppPageRscErrorTracker } from "./app-page-stream.js";
 import { resolveAppPageParentHttpAccessBoundary, resolveAppPageParentHttpAccessBoundaryModule } from "./app-page-boundary.js";
 import { shouldServeStreamingMetadata } from "./streaming-metadata.js";
 import { resolveAppPageNavigationParams } from "./app-page-element-builder.js";
-import { createAppPageRscErrorTracker } from "./app-page-stream.js";
 import { createAppLayoutParamAccessTracker, isAppLayoutObservationUnsafeForStaticReuse } from "./app-layout-param-observation.js";
 import { resolveAppPageMethodResponse } from "./app-page-method.js";
 import { buildAppPageElement, resolveAppPageIntercept, resolveAppPageInterceptionRerenderTarget, validateAppPageDynamicParams } from "./app-page-request.js";
@@ -149,7 +151,7 @@ async function runAppPageRevalidationContext(options, renderFn) {
 		executionContext: getRequestExecutionContext(),
 		unstableCacheRevalidation: "foreground"
 	});
-	const revalidation = runWithRequestContext(requestContext, async () => {
+	const revalidation = runWithRequestContext(requestContext, () => runInWorkStoreScope(async () => {
 		ensureFetchPatch();
 		setRefreshStaleFetchesInForeground(process.env.VINEXT_PRERENDER === "1");
 		setCurrentFetchSoftTags(buildAppPageTags(options.cleanPathname, [], options.routeSegments));
@@ -159,7 +161,7 @@ async function runAppPageRevalidationContext(options, renderFn) {
 			params: options.params
 		});
 		return await runWithFetchDedupe(renderFn);
-	});
+	}));
 	try {
 		return await revalidation;
 	} finally {
@@ -255,7 +257,6 @@ async function dispatchAppPageInner(options) {
 	const pageSearchParams = shouldUseEmptySearchParams ? new URLSearchParams() : options.searchParams;
 	const layoutParamAccess = createAppLayoutParamAccessTracker();
 	const activeLoadingTreePositions = getActiveLoadingTreePositions(route);
-	const hasActiveLoadingBoundary = activeLoadingTreePositions.length > 0;
 	setCurrentFetchSoftTags(buildAppPageTags(options.cleanPathname, [], route.routeSegments));
 	setCurrentFetchCacheMode(options.fetchCache ?? null);
 	setCurrentFetchRevalidate(currentRevalidateSeconds);
@@ -313,7 +314,7 @@ async function dispatchAppPageInner(options) {
 	});
 	const isNeverStoredPath = options.pprRuntime === void 0 && hasNoManifestAdmissionState(route.pattern);
 	const shouldReadCache = !isRouteCacheabilityProbe() && isCacheEligibleRender && !isNeverStoredPath;
-	const isCacheCandidate = isCacheEligibleRender && isStaticEligible && options.pprRuntime === void 0 && !isNeverStoredPath;
+	const isCacheCandidate = isCacheEligibleRender && isStaticEligible && options.pprFallbackShell === void 0 && !isNeverStoredPath;
 	if (shouldReadCache && isStaticEligible) {
 		traceOperation = resolveAppPageTraceOperation({
 			hasRequestSearchParams,
@@ -396,14 +397,16 @@ async function dispatchAppPageInner(options) {
 						isForceStatic: revalidationDynamicConfig === "force-static",
 						observeMetadataSearchParamsAccess: revalidationDynamicConfig !== "force-static",
 						observePageSearchParamsAccess: revalidationDynamicConfig !== "force-static",
-						serveStreamingMetadata: false
+						serveStreamingMetadata: placeGeneratedMetadataInBody,
+						placeStreamedMetadataInHead: true
 					});
 					const baseRevalidatedOnError = options.createRscOnErrorHandler(options.cleanPathname, revalidationTarget.route.pattern, { revalidateReason: "stale" });
 					const baseRevalidatedOnSsrError = options.createRscOnErrorHandler(options.cleanPathname, revalidationTarget.route.pattern, {
 						renderSource: "server-rendering",
 						revalidateReason: "stale"
 					});
-					revalidationRscErrorTracker = createAppPageRscErrorTracker(baseRevalidatedOnError);
+					const rscErrorTracker = createAppPageRscErrorTracker(baseRevalidatedOnError);
+					revalidationRscErrorTracker = rscErrorTracker;
 					const rendered = await renderAppPageCacheArtifacts({
 						basePath: options.basePath,
 						captureRscData: true,
@@ -416,14 +419,36 @@ async function dispatchAppPageInner(options) {
 						getNavigationContext: options.getNavigationContext,
 						loadSsrHandler: options.loadSsrHandler,
 						mountedSlotsHeader: options.mountedSlotsHeader,
+						mirrorNextFlight: () => rscErrorTracker.getCapturedSpecialError() !== null,
 						navigationParams: revalidationTarget.navigationParams,
-						isCapturedRscError: revalidationRscErrorTracker.isCapturedError,
-						onError: revalidationRscErrorTracker.onRenderError,
+						isCapturedRscError: rscErrorTracker.isCapturedError,
+						onError: rscErrorTracker.onRenderError,
 						onSsrError(error) {
 							reportedSsrRevalidationErrors.add(error);
 							return baseRevalidatedOnSsrError(error, void 0, void 0);
 						},
 						reactMaxHeadersLength: options.reactMaxHeadersLength,
+						async renderShellSpecialError(error) {
+							const specialError = resolveAppPageShellSpecialError(error, rscErrorTracker.getCapturedSpecialErrors(error));
+							if (!specialError) return null;
+							if (options.isRscRequest) {
+								if (specialError.fromMetadata === true) return null;
+								return {
+									headers: resolveAppPageSpecialErrorStoredHeaders(specialError, options.basePath),
+									html: "",
+									status: specialError.statusCode
+								};
+							}
+							if (revalidationTarget.route !== route) return null;
+							const document = await renderPageSpecialError(options, specialError, false, revalidationTarget.interceptOpts, true);
+							if (document.status !== specialError.statusCode) return null;
+							return {
+								headers: resolveAppPageSpecialErrorStoredHeaders(specialError, options.basePath),
+								html: await document.text(),
+								linkHeader: getFrameworkLinkHeader(document.headers) ?? void 0,
+								status: specialError.statusCode
+							};
+						},
 						renderToReadableStream: options.renderToReadableStream,
 						rootParams: options.rootParams,
 						route: revalidationTarget.route,
@@ -432,6 +457,7 @@ async function dispatchAppPageInner(options) {
 					});
 					options.clearRequestContext();
 					return {
+						headers: rendered.headers,
 						html: rendered.html,
 						htmlRenderObservation: rendered.htmlRenderObservation,
 						linkHeader: rendered.linkHeader,
@@ -440,6 +466,7 @@ async function dispatchAppPageInner(options) {
 						tags: rendered.tags,
 						cacheControl: rendered.cacheControl,
 						revalidateSeconds: revalidationRouteRevalidateSeconds,
+						status: rendered.status,
 						usedDynamicApi: rendered.usedDynamicApi
 					};
 				});
@@ -465,6 +492,7 @@ async function dispatchAppPageInner(options) {
 		if (dynamicParamsResponse) {
 			const renderedNotFound = await options.renderHttpAccessFallbackPage(404, { matchedParams: options.params }, options.middlewareContext);
 			const cachePolicy = {
+				dynamicStaleTimeSeconds: options.dynamicStaleTimeSeconds,
 				isDraftMode,
 				isDynamicError,
 				isForceDynamic,
@@ -510,7 +538,8 @@ async function dispatchAppPageInner(options) {
 				isForceStatic: sourceDynamicConfig === "force-static",
 				observeMetadataSearchParamsAccess: sourceDynamicConfig !== "force-static",
 				observePageSearchParamsAccess: sourceDynamicConfig !== "force-static",
-				serveStreamingMetadata: placeGeneratedMetadataInBody
+				serveStreamingMetadata: placeGeneratedMetadataInBody,
+				placeStreamedMetadataInHead: options.renderWholeDocument === true
 			});
 		},
 		cleanPathname: options.cleanPathname,
@@ -565,19 +594,10 @@ async function dispatchAppPageInner(options) {
 				isForceStatic,
 				observeMetadataSearchParamsAccess: !isForceStatic,
 				observePageSearchParamsAccess: !isForceStatic,
-				serveStreamingMetadata: placeGeneratedMetadataInBody
+				serveStreamingMetadata: placeGeneratedMetadataInBody,
+				placeStreamedMetadataInHead: options.renderWholeDocument === true
 			});
 		},
-		async probePageSpecialError() {
-			if (hasActiveLoadingBoundary) return null;
-			const pageError = await probeAppPageThrownError({
-				probePage: () => options.probePage(pageSearchParams),
-				runWithSuppressedHookWarning(probe) {
-					return options.runWithSuppressedHookWarning(probe);
-				}
-			});
-			return resolveAppPageSpecialError(pageError);
-		},
 		renderErrorBoundaryPage(buildError) {
 			return options.renderErrorBoundaryPage(buildError);
 		},
@@ -645,7 +665,6 @@ async function dispatchAppPageInner(options) {
 			return requestCacheLife.peek();
 		},
 		handlerStart: options.handlerStart,
-		hasLoadingBoundary: hasActiveLoadingBoundary,
 		omitPendingDynamicCacheState: hasRequestSearchParams && !(isCacheCandidate && !options.isRscRequest),
 		formState: options.formState ?? null,
 		isProgressiveActionRender: options.isProgressiveActionRender === true,
@@ -657,7 +676,9 @@ async function dispatchAppPageInner(options) {
 		isStaticEligible,
 		isCacheCandidate,
 		isPrerender,
+		isRoutePPREnabled: options.pprRuntime !== void 0,
 		isSpeculativePrerender,
+		renderWholeDocument: options.renderWholeDocument === true && !options.isRscRequest,
 		isProduction: options.isProduction,
 		isRscRequest: options.isRscRequest,
 		traceOperation,
@@ -690,10 +711,6 @@ async function dispatchAppPageInner(options) {
 		probeLayoutAt(layoutIndex) {
 			return options.probeLayoutAt(layoutIndex, layoutParamAccess);
 		},
-		probePage() {
-			return options.probePage(pageSearchParams);
-		},
-		probePageBeforeRender: options.isRscRequest,
 		classification: {
 			getLayoutId(index) {
 				const treePosition = route.layoutTreePositions?.[index] ?? 0;
@@ -719,8 +736,8 @@ async function dispatchAppPageInner(options) {
 		renderLayoutSpecialError(specialError, layoutIndex) {
 			return renderLayoutSpecialError(options, specialError, layoutIndex, serveStreamingMetadata);
 		},
-		renderPageSpecialError(specialError) {
-			return renderPageSpecialError(options, specialError, serveStreamingMetadata, interceptResult.interceptOpts);
+		renderPageSpecialError(specialError, renderOptions) {
+			return renderPageSpecialError(options, specialError, serveStreamingMetadata, interceptResult.interceptOpts, renderOptions?.isCacheCandidate === true);
 		},
 		renderToReadableStream: options.renderToReadableStream,
 		hasCustomGlobalError: options.hasCustomGlobalError,
@@ -773,7 +790,7 @@ async function renderLayoutSpecialError(options, specialError, layoutIndex, serv
 		specialError
 	});
 }
-async function renderPageSpecialError(options, specialError, serveStreamingMetadata, intercept) {
+async function renderPageSpecialError(options, specialError, serveStreamingMetadata, intercept, isCacheCandidate = false) {
 	return buildAppPageSpecialErrorResponse({
 		basePath: options.basePath,
 		buildRscRedirectFlightStream: (rscOptions) => buildRscRedirectFlightStream({
@@ -802,6 +819,7 @@ async function renderPageSpecialError(options, specialError, serveStreamingMetad
 			const useLayoutAlignedBoundary = boundaryLayoutIndex !== null && (routeBoundaryModule === null || routeBoundaryModule === parentBoundaryModule);
 			const fallbackOptions = {
 				intercept,
+				...isCacheCandidate ? { isCacheCandidate } : {},
 				matchedParams: options.params
 			};
 			if (useLayoutAlignedBoundary && boundaryLayoutIndex !== null) {

package/dist/server/app-page-element-builder.d.ts

@@ -61,6 +61,13 @@ export type AppPagePageRequest<TModule extends AppPageModule = AppPageModule> =
   observeMetadataSearchParamsAccess?: boolean;
   /** Whether generated metadata may stream into the response body. */
   serveStreamingMetadata?: boolean;
+  /**
+   * Wait for streamed metadata in `<head>`, for a document rendered whole
+   * before it's written, such as a background regeneration. Next.js does this
+   * for every static or ISR render. Its errors still reach the route's
+   * boundaries through the outlet.
+   */
+  placeStreamedMetadataInHead?: boolean;
   /** Whether streamed render errors must be sanitized for client transport. */
   isProduction?: boolean;
 };