vinext 1.3.0 → 1.3.1

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

@@ -7,6 +7,7 @@ import { NavigationContext } from "../shims/navigation-context-state.js";
 import "../shims/navigation.js";
 import { AppPageFontPreload, LayoutClassificationOptions } from "./app-page-execution.js";
 import { AppPageMiddlewareContext } from "./app-page-response.js";
+import { AppPageFallbackRouteHead, AppPagePreparedRouteHead } from "./app-page-head.js";
 import { AppLayoutParamAccessTracker } from "./app-layout-param-observation.js";
 import { RootParams } from "../shims/root-params.js";
 import { AppPageSsrHandler } from "./app-page-stream.js";
@@ -43,8 +44,16 @@ type AppPageDispatchIntercept<TPage = unknown> = {
   interceptLoadings?: readonly unknown[] | null;
   interceptLoadingTreePositions?: readonly number[] | null;
   interceptNotFoundBranchSegments?: readonly string[] | null;
+  interceptNotFounds?: readonly unknown[] | null;
+  interceptNotFoundTreePositions?: readonly number[] | null;
   notFound?: unknown;
   notFoundTreePosition?: number | null;
+  interceptForbiddens?: readonly unknown[] | null;
+  interceptForbiddenTreePositions?: readonly number[] | null;
+  interceptUnauthorizeds?: readonly unknown[] | null;
+  interceptUnauthorizedTreePositions?: readonly number[] | null;
+  interceptErrors?: readonly unknown[] | null;
+  interceptErrorTreePositions?: readonly number[] | null;
   matchedParams: AppPageParams;
   sourceMatchedParams?: AppPageParams;
   page: TPage;
@@ -67,6 +76,14 @@ type AppPageDispatchInterceptOptions<TPage = unknown> = {
   interceptNotFoundBranchSegments?: readonly string[] | null;
   interceptNotFound?: unknown;
   interceptNotFoundTreePosition?: number | null;
+  interceptForbiddens?: readonly unknown[] | null;
+  interceptForbiddenTreePositions?: readonly number[] | null;
+  interceptUnauthorizeds?: readonly unknown[] | null;
+  interceptUnauthorizedTreePositions?: readonly number[] | null;
+  interceptErrors?: readonly unknown[] | null;
+  interceptErrorTreePositions?: readonly number[] | null;
+  interceptNotFounds?: readonly unknown[] | null;
+  interceptNotFoundTreePositions?: readonly number[] | null;
   interceptPage: TPage;
   interceptParams: AppPageParams;
   interceptSlotId?: string | null;
@@ -108,6 +125,12 @@ export type AppPageDispatchRoute = {
   params: readonly string[];
   pattern: string;
   routeSegments: readonly string[];
+  segmentForbiddens?: readonly (AppPageModule | null | undefined)[];
+  segmentForbiddenTreePositions?: readonly number[];
+  segmentNotFounds?: readonly (AppPageModule | null | undefined)[];
+  segmentNotFoundTreePositions?: readonly number[];
+  segmentUnauthorizeds?: readonly (AppPageModule | null | undefined)[];
+  segmentUnauthorizedTreePositions?: readonly number[];
   slots?: Readonly<Record<string, AppPageDispatchSlot>>;
   unauthorized?: AppPageModule | null;
   unauthorizedTreePosition?: number | null;
@@ -140,10 +163,13 @@ export type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   reactMaxHeadersLength?: number;
   buildPageElement: (route: TRoute, params: AppPageParams, opts: AppPageDispatchInterceptOptions | undefined, searchParams: URLSearchParams, layoutParamAccess?: AppLayoutParamAccessTracker, options?: {
     isForceStatic?: boolean;
+    isUncacheableRender?: boolean;
     observeMetadataSearchParamsAccess?: boolean;
     observePageSearchParamsAccess?: boolean;
     serveStreamingMetadata?: boolean;
     placeStreamedMetadataInHead?: boolean;
+    /** Receives the route's head once the render starts resolving it. */
+    onHeadPrepared?: (head: AppPagePreparedRouteHead) => void;
   }) => Promise<AppPageElement>;
   clientReuseManifest?: ClientReuseManifestParseResult;
   cleanPathname: string;
@@ -229,11 +255,17 @@ export type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   renderHttpAccessFallbackPage: (statusCode: number, opts: {
     boundaryComponent?: unknown;
     boundaryModule?: AppPageModule | null;
+    /** Boundary whose metadata the head uses, when not `boundaryModule`. */
+    headBoundaryModule?: AppPageModule | null;
+    /** Layouts whose metadata the head uses, when more than `layouts`. */
+    headLayouts?: readonly AppPageModule[];
     intercept?: AppPageDispatchInterceptOptions | null;
     /** The document may be stored, so it must not carry the request's query. */
     isCacheCandidate?: boolean;
     layouts?: readonly AppPageModule[];
     matchedParams: AppPageParams;
+    /** The route's render threw the signal, so the document keeps the route's head. */
+    routeHead?: AppPageFallbackRouteHead;
   }, middlewareContext: AppPageMiddlewareContext | null) => Promise<Response | null>;
   renderToReadableStream: (element: AppPageRenderableElement, options: {
     onError: AppPageBoundaryOnError;
@@ -290,4 +322,5 @@ export declare function shouldReadAppPageCache(options: {
 }): boolean;
 export declare function hasSearchParams(searchParams: URLSearchParams | null | undefined): boolean;
 export declare function dispatchAppPage<TRoute extends AppPageDispatchRoute>(options: DispatchAppPageOptions<TRoute>): Promise<Response>;
-//#endregion
+//#endregion
+export {};

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

@@ -11,6 +11,7 @@ import { _captureRequestScopedCacheLifeAccessors } from "../shims/cache-request-
 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 { isAppClientReference } from "./app-render-dependency.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";
@@ -18,17 +19,18 @@ 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, resolveAppPageShellSpecialError, resolveAppPageSpecialError, resolveAppPageSpecialErrorStoredHeaders } from "./app-page-execution.js";
+import { buildAppPageSpecialErrorResponse, resolveAppPageCaughtNotFoundBoundaries, 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 { createAppPageRscErrorTracker } from "./app-page-stream.js";
-import { resolveAppPageParentHttpAccessBoundary, resolveAppPageParentHttpAccessBoundaryModule } from "./app-page-boundary.js";
+import { resolveAppPageLayoutHttpAccessBoundary, resolveAppPageParentHttpAccessBoundary, resolveAppPageRootHttpAccessBoundaryTreePosition } 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 { getDefaultHttpAccessFallbackModule } from "./default-http-access-fallback-modules.js";
 import { createAppLayoutParamAccessTracker, isAppLayoutObservationUnsafeForStaticReuse } from "./app-layout-param-observation.js";
+import { consumeAppPageRenderObservationState, discardAppPageRenderState } from "./app-page-render-observation.js";
+import { buildAppPageTags } from "./implicit-tags.js";
 import { resolveAppPageMethodResponse } from "./app-page-method.js";
 import { buildAppPageElement, resolveAppPageIntercept, resolveAppPageInterceptionRerenderTarget, validateAppPageDynamicParams } from "./app-page-request.js";
 import { applyIneligibleRouteCachePolicy, renderAppPageLifecycle } from "./app-page-render.js";
@@ -182,6 +184,14 @@ function toInterceptOptions(interceptionContext, intercept) {
 		interceptNotFoundBranchSegments: intercept.interceptNotFoundBranchSegments,
 		interceptNotFound: intercept.notFound,
 		interceptNotFoundTreePosition: intercept.notFoundTreePosition,
+		interceptForbiddens: intercept.interceptForbiddens,
+		interceptForbiddenTreePositions: intercept.interceptForbiddenTreePositions,
+		interceptUnauthorizeds: intercept.interceptUnauthorizeds,
+		interceptUnauthorizedTreePositions: intercept.interceptUnauthorizedTreePositions,
+		interceptErrors: intercept.interceptErrors,
+		interceptErrorTreePositions: intercept.interceptErrorTreePositions,
+		interceptNotFounds: intercept.interceptNotFounds,
+		interceptNotFoundTreePositions: intercept.interceptNotFoundTreePositions,
 		interceptPage: intercept.page,
 		interceptParams: intercept.matchedParams,
 		interceptSlotId: intercept.slotId ?? null,
@@ -316,6 +326,7 @@ async function dispatchAppPageInner(options) {
 	const isNeverStoredPath = options.pprRuntime === void 0 && hasNoManifestAdmissionState(route.pattern);
 	const shouldReadCache = !isRouteCacheabilityProbe() && isCacheEligibleRender && !isNeverStoredPath;
 	const isCacheCandidate = isCacheEligibleRender && isStaticEligible && options.pprFallbackShell === void 0 && !isNeverStoredPath;
+	const isUncacheableRender = !(isCacheEligibleRender && isStaticEligible) && options.pprFallbackShell === void 0 && (options.pprRuntime === void 0 || !options.isProduction);
 	if (shouldReadCache && isStaticEligible) {
 		traceOperation = resolveAppPageTraceOperation({
 			hasRequestSearchParams,
@@ -381,6 +392,12 @@ async function dispatchAppPageInner(options) {
 				const revalidationDynamicConfig = options.resolveRouteDynamicConfig?.(revalidationTarget.route) ?? (revalidationTarget.route === route ? dynamicConfig : void 0);
 				const revalidationConfigRevalidateSeconds = options.resolveRouteRevalidateSeconds?.(revalidationTarget.route) ?? (revalidationTarget.route === route ? currentRevalidateSeconds : null);
 				const revalidationRouteRevalidateSeconds = revalidationTarget.route === route ? void 0 : revalidationConfigRevalidateSeconds ?? (revalidationDynamicConfig === "force-static" || revalidationDynamicConfig === "error" || options.isProduction && options.pprRuntime === void 0 && options.resolveRouteStaticEligible(revalidationTarget.route) ? Infinity : null);
+				const revalidationRouteHead = {
+					observeSearchParams: revalidationDynamicConfig !== "force-static",
+					searchParams: new URLSearchParams(),
+					streamMetadata: false,
+					value: null
+				};
 				return runAppPageRevalidationContext({
 					cleanPathname: options.cleanPathname,
 					displayPathname: options.displayPathname,
@@ -400,7 +417,10 @@ async function dispatchAppPageInner(options) {
 						observeMetadataSearchParamsAccess: revalidationDynamicConfig !== "force-static",
 						observePageSearchParamsAccess: revalidationDynamicConfig !== "force-static",
 						serveStreamingMetadata: placeGeneratedMetadataInBody,
-						placeStreamedMetadataInHead: true
+						placeStreamedMetadataInHead: true,
+						onHeadPrepared(head) {
+							revalidationRouteHead.value = head;
+						}
 					});
 					const baseRevalidatedOnError = options.createRscOnErrorHandler(options.cleanPathname, revalidationTarget.route.pattern, { revalidateReason: "stale" });
 					const baseRevalidatedOnSsrError = options.createRscOnErrorHandler(options.cleanPathname, revalidationTarget.route.pattern, {
@@ -430,7 +450,8 @@ async function dispatchAppPageInner(options) {
 							return baseRevalidatedOnSsrError(error, void 0, void 0);
 						},
 						reactMaxHeadersLength: options.reactMaxHeadersLength,
-						async renderShellSpecialError(error) {
+						resolveCaughtNotFoundBoundaries: options.isRscRequest ? void 0 : (error) => resolveAppPageCaughtNotFoundBoundaries(error, rscErrorTracker.getCapturedSpecialErrors(error)),
+						async renderShellSpecialError(error, caughtDocument) {
 							const specialError = resolveAppPageShellSpecialError(error, rscErrorTracker.getCapturedSpecialErrors(error));
 							if (!specialError) return null;
 							if (options.isRscRequest) {
@@ -441,8 +462,14 @@ async function dispatchAppPageInner(options) {
 									status: specialError.statusCode
 								};
 							}
+							if (caughtDocument) return {
+								headers: resolveAppPageSpecialErrorStoredHeaders(specialError, options.basePath),
+								html: caughtDocument.html,
+								linkHeader: caughtDocument.linkHeader,
+								status: specialError.statusCode
+							};
 							if (revalidationTarget.route !== route) return null;
-							const document = await renderPageSpecialError(options, specialError, false, revalidationTarget.interceptOpts, true);
+							const document = await renderPageSpecialError(options, specialError, false, revalidationTarget.interceptOpts, true, void 0, revalidationRouteHead);
 							if (document.status !== specialError.statusCode) return null;
 							return {
 								headers: resolveAppPageSpecialErrorStoredHeaders(specialError, options.basePath),
@@ -518,6 +545,15 @@ async function dispatchAppPageInner(options) {
 	let interceptDynamicConfig;
 	let interceptDynamicConfigResolved = false;
 	let isInterceptSourceKnownDynamic = false;
+	const renderedRouteHead = {
+		observeSearchParams: !isForceStatic,
+		searchParams: pageSearchParams,
+		streamMetadata: placeGeneratedMetadataInBody && options.renderWholeDocument !== true,
+		value: null
+	};
+	const onHeadPrepared = (head) => {
+		renderedRouteHead.value = head;
+	};
 	const interceptResult = await resolveAppPageIntercept({
 		async buildPageElement(interceptRoute, interceptParams, interceptOpts, interceptSearchParams, interceptLayoutParamAccess) {
 			const sourceDynamicConfig = interceptDynamicConfigResolved ? interceptDynamicConfig : options.resolveRouteDynamicConfig?.(interceptRoute);
@@ -540,8 +576,10 @@ async function dispatchAppPageInner(options) {
 				isForceStatic: sourceDynamicConfig === "force-static",
 				observeMetadataSearchParamsAccess: sourceDynamicConfig !== "force-static",
 				observePageSearchParamsAccess: sourceDynamicConfig !== "force-static",
+				isUncacheableRender,
 				serveStreamingMetadata: placeGeneratedMetadataInBody,
-				placeStreamedMetadataInHead: options.renderWholeDocument === true
+				placeStreamedMetadataInHead: options.renderWholeDocument === true,
+				onHeadPrepared
 			});
 		},
 		cleanPathname: options.cleanPathname,
@@ -591,20 +629,23 @@ async function dispatchAppPageInner(options) {
 	if (interceptResult.response) return interceptResult.response;
 	const buildCurrentPageElement = () => buildAppPageElement({
 		buildPageElement() {
+			renderedRouteHead.value = null;
 			if (options.actionFailed) throw options.actionError;
 			return options.buildPageElement(route, options.params, interceptResult.interceptOpts, pageSearchParams, layoutParamAccess, {
 				isForceStatic,
 				observeMetadataSearchParamsAccess: !isForceStatic,
 				observePageSearchParamsAccess: !isForceStatic,
+				isUncacheableRender,
 				serveStreamingMetadata: placeGeneratedMetadataInBody,
-				placeStreamedMetadataInHead: options.renderWholeDocument === true
+				placeStreamedMetadataInHead: options.renderWholeDocument === true,
+				onHeadPrepared
 			});
 		},
 		renderErrorBoundaryPage(buildError) {
 			return options.renderErrorBoundaryPage(buildError);
 		},
 		renderSpecialError(specialError) {
-			return renderPageSpecialError(options, specialError, serveStreamingMetadata, interceptResult.interceptOpts);
+			return renderPageSpecialError(options, specialError, serveStreamingMetadata, interceptResult.interceptOpts, false, void 0, renderedRouteHead);
 		},
 		resolveSpecialError: resolveAppPageSpecialError
 	});
@@ -736,10 +777,10 @@ async function dispatchAppPageInner(options) {
 			return options.renderErrorBoundaryPage(renderError, errorOrigin);
 		},
 		renderLayoutSpecialError(specialError, layoutIndex) {
-			return renderLayoutSpecialError(options, specialError, layoutIndex, serveStreamingMetadata);
+			return renderLayoutSpecialError(options, specialError, layoutIndex, serveStreamingMetadata, renderedRouteHead);
 		},
 		renderPageSpecialError(specialError, renderOptions) {
-			return renderPageSpecialError(options, specialError, serveStreamingMetadata, interceptResult.interceptOpts, renderOptions?.isCacheCandidate === true);
+			return renderPageSpecialError(options, specialError, serveStreamingMetadata, interceptResult.interceptOpts, renderOptions?.isCacheCandidate === true, renderOptions?.caughtDocument, renderedRouteHead);
 		},
 		renderToReadableStream: options.renderToReadableStream,
 		hasCustomGlobalError: options.hasCustomGlobalError,
@@ -754,7 +795,22 @@ async function dispatchAppPageInner(options) {
 		}
 	});
 }
-async function renderLayoutSpecialError(options, specialError, layoutIndex, serveStreamingMetadata) {
+/**
+* A signal the route's own render threw keeps the route's head, reusing the
+* one that render prepared. A progressive server action's signal doesn't:
+* Next.js answers it with a not-found tree in place of the page
+* (`createNotFoundLoaderTree`), so the page's metadata never applies.
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/server/app-render/app-render.tsx
+*/
+function resolveFallbackRouteHead(options, renderedRouteHead) {
+	if (options.actionFailed || !renderedRouteHead) return null;
+	const { value, ...render } = renderedRouteHead;
+	return {
+		...render,
+		prepared: value
+	};
+}
+async function renderLayoutSpecialError(options, specialError, layoutIndex, serveStreamingMetadata, renderedRouteHead) {
 	return buildAppPageSpecialErrorResponse({
 		basePath: options.basePath,
 		buildRscRedirectFlightStream: (rscOptions) => buildRscRedirectFlightStream({
@@ -768,31 +824,93 @@ async function renderLayoutSpecialError(options, specialError, layoutIndex, serv
 		isRscRequest: options.isRscRequest,
 		middlewareContext: options.middlewareContext,
 		renderFallbackPage(statusCode) {
-			const parentBoundaryModule = resolveAppPageParentHttpAccessBoundaryModule({
-				layoutIndex,
-				rootForbiddenModule: options.rootForbiddenModule,
-				rootNotFoundModule: options.rootNotFoundModule,
-				rootUnauthorizedModule: options.rootUnauthorizedModule,
-				routeForbiddenModules: options.route.forbiddens,
-				routeNotFoundModules: options.route.notFounds,
-				routeUnauthorizedModules: options.route.unauthorizeds,
-				statusCode
+			return renderLayoutBoundaryFallback(options, statusCode, layoutIndex, {
+				headLayouts: options.route.layouts.slice(0, layoutIndex),
+				routeHead: resolveFallbackRouteHead(options, renderedRouteHead)
 			});
-			const fallbackOptions = {
-				layouts: options.route.layouts.slice(0, layoutIndex),
-				matchedParams: options.params
-			};
-			if (parentBoundaryModule) {
-				fallbackOptions.boundaryComponent = parentBoundaryModule.default;
-				fallbackOptions.boundaryModule = parentBoundaryModule;
-			}
-			return options.renderHttpAccessFallbackPage(statusCode, fallbackOptions, null);
 		},
 		request: options.request,
 		specialError
 	});
 }
-async function renderPageSpecialError(options, specialError, serveStreamingMetadata, intercept, isCacheCandidate = false) {
+/**
+* The fallback for a special error a layout threw, or a parallel slot that
+* layout renders: the boundary above the layout catches it. With
+* `insideLayout`, the layout re-renders around its own segment's boundary
+* instead. Without a segment boundary, Next.js' built-in not-found,
+* forbidden or unauthorized page renders inside the root layout, or without
+* it when the root layout, or a slot beside it outside `insideLayout`, threw.
+*/
+function renderLayoutBoundaryFallback(options, statusCode, layoutIndex, fallbackOptions) {
+	const { route } = options;
+	const layoutTreePositions = route.layoutTreePositions ?? [];
+	const boundaryModules = statusCode === 403 ? route.segmentForbiddens : statusCode === 401 ? route.segmentUnauthorizeds : route.segmentNotFounds;
+	const boundaryTreePositions = statusCode === 403 ? route.segmentForbiddenTreePositions : statusCode === 401 ? route.segmentUnauthorizedTreePositions : route.segmentNotFoundTreePositions;
+	const insideLayout = fallbackOptions.insideLayout === true;
+	const ownLayoutTreePosition = layoutTreePositions[layoutIndex];
+	const layoutTreePosition = ownLayoutTreePosition === void 0 || !insideLayout ? ownLayoutTreePosition : ownLayoutTreePosition + 1;
+	const renderedLayoutCount = insideLayout ? layoutIndex + 1 : layoutIndex;
+	const boundary = layoutTreePosition === void 0 ? null : resolveAppPageLayoutHttpAccessBoundary({
+		boundaryModules: boundaryModules ?? [],
+		boundaryTreePositions: boundaryTreePositions ?? [],
+		layoutTreePosition
+	});
+	const boundaryModule = boundary?.module ?? getDefaultHttpAccessFallbackModule(statusCode);
+	if (!boundaryModule) return Promise.resolve(null);
+	const boundaryTreePosition = Math.max(boundary?.treePosition ?? 0, resolveAppPageRootHttpAccessBoundaryTreePosition(route.routeSegments, layoutTreePositions, layoutTreePosition));
+	const headBoundary = resolveAppPageLayoutHttpAccessBoundary({
+		boundaryModules: boundaryModules ?? [],
+		boundaryTreePositions: boundaryTreePositions ?? [],
+		layoutTreePosition: Number.POSITIVE_INFINITY
+	});
+	return options.renderHttpAccessFallbackPage(statusCode, {
+		boundaryComponent: boundaryModule.default,
+		boundaryModule,
+		headBoundaryModule: headBoundary?.module ?? boundaryModule,
+		headLayouts: fallbackOptions.headLayouts,
+		...fallbackOptions.intercept ? { intercept: fallbackOptions.intercept } : {},
+		...fallbackOptions.isCacheCandidate ? { isCacheCandidate: true } : {},
+		layouts: route.layouts.filter((_, index) => index < renderedLayoutCount && (layoutTreePositions[index] ?? 0) <= boundaryTreePosition),
+		matchedParams: options.params,
+		...fallbackOptions.routeHead ? { routeHead: fallbackOptions.routeHead } : {}
+	}, null);
+}
+/**
+* The fallback for a page's `notFound()` / `forbidden()` / `unauthorized()`.
+* Next.js wraps each segment's children in its boundaries, with or without a
+* layout, so the route's deepest boundary catches the signal and replaces
+* every layout below its segment. Without one, the built-in not-found,
+* forbidden or unauthorized page renders inside the root layout. Returns
+* `null` for routes without segment data.
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/server/app-render/create-component-tree.tsx
+*/
+function renderPageSegmentBoundaryFallback(options, statusCode, intercept, isCacheCandidate, routeHead) {
+	const { route } = options;
+	const boundaryModules = statusCode === 403 ? route.segmentForbiddens : statusCode === 401 ? route.segmentUnauthorizeds : route.segmentNotFounds;
+	const boundaryTreePositions = statusCode === 403 ? route.segmentForbiddenTreePositions : statusCode === 401 ? route.segmentUnauthorizedTreePositions : route.segmentNotFoundTreePositions;
+	if (!boundaryTreePositions) return null;
+	const boundary = resolveAppPageLayoutHttpAccessBoundary({
+		boundaryModules: boundaryModules ?? [],
+		boundaryTreePositions,
+		layoutTreePosition: Number.POSITIVE_INFINITY
+	});
+	const boundaryModule = boundary?.module ?? getDefaultHttpAccessFallbackModule(statusCode);
+	if (!boundaryModule) return Promise.resolve(null);
+	const layoutTreePositions = route.layoutTreePositions ?? [];
+	const boundaryTreePosition = Math.max(boundary?.treePosition ?? 0, resolveAppPageRootHttpAccessBoundaryTreePosition(route.routeSegments, layoutTreePositions, Number.POSITIVE_INFINITY));
+	return options.renderHttpAccessFallbackPage(statusCode, {
+		boundaryComponent: boundaryModule.default,
+		boundaryModule,
+		headLayouts: route.layouts,
+		intercept,
+		...isCacheCandidate ? { isCacheCandidate } : {},
+		layouts: route.layouts.filter((_, index) => (layoutTreePositions[index] ?? 0) <= boundaryTreePosition),
+		matchedParams: options.params,
+		...routeHead ? { routeHead } : {}
+	}, null);
+}
+async function renderPageSpecialError(options, specialError, serveStreamingMetadata, intercept, isCacheCandidate = false, caughtDocument, renderedRouteHead = null) {
+	const routeHead = resolveFallbackRouteHead(options, renderedRouteHead);
 	return buildAppPageSpecialErrorResponse({
 		basePath: options.basePath,
 		buildRscRedirectFlightStream: (rscOptions) => buildRscRedirectFlightStream({
@@ -806,6 +924,16 @@ async function renderPageSpecialError(options, specialError, serveStreamingMetad
 		isRscRequest: options.isRscRequest,
 		middlewareContext: options.middlewareContext,
 		renderFallbackPage(statusCode) {
+			if (caughtDocument) return Promise.resolve(caughtDocument);
+			if (specialError.kind === "http-access-fallback" && specialError.slotLayoutIndex !== void 0) return renderLayoutBoundaryFallback(options, statusCode, specialError.slotLayoutIndex, {
+				headLayouts: options.route.layouts,
+				insideLayout: specialError.slotLayoutIndex === 0 && (statusCode === 404 || isAppClientReference(options.route.layouts[0]?.default)),
+				intercept,
+				isCacheCandidate,
+				routeHead
+			});
+			const pageBoundaryFallback = renderPageSegmentBoundaryFallback(options, statusCode, intercept, isCacheCandidate, routeHead);
+			if (pageBoundaryFallback) return pageBoundaryFallback;
 			const routeBoundaryModule = resolveAppPageRouteBoundaryModule(options.route, statusCode);
 			const layoutCount = options.route.layouts.length;
 			const { module: parentBoundaryModule, layoutIndex: boundaryLayoutIndex } = resolveAppPageParentHttpAccessBoundary({
@@ -822,7 +950,8 @@ async function renderPageSpecialError(options, specialError, serveStreamingMetad
 			const fallbackOptions = {
 				intercept,
 				...isCacheCandidate ? { isCacheCandidate } : {},
-				matchedParams: options.params
+				matchedParams: options.params,
+				...routeHead ? { routeHead } : {}
 			};
 			if (useLayoutAlignedBoundary && boundaryLayoutIndex !== null) {
 				fallbackOptions.layouts = options.route.layouts.slice(0, boundaryLayoutIndex + 1);

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

@@ -3,7 +3,7 @@ import { AppElements } from "./app-elements-wire.js";
 import "./app-elements.js";
 import { AppRscRenderMode } from "./app-rsc-render-mode.js";
 import { AppPageParams } from "./app-page-boundary.js";
-import { ApplyAppPageFileBasedMetadata } from "./app-page-head.js";
+import { AppPagePreparedRouteHead, ApplyAppPageFileBasedMetadata } from "./app-page-head.js";
 import { AppLayoutParamAccessTracker } from "./app-layout-param-observation.js";
 import { AppPageSemanticSegment } from "./app-page-segment-state.js";
 import { AppPageErrorModule, AppPageModule, AppPageRouteWiringRoute } from "./app-page-route-wiring.js";
@@ -31,6 +31,14 @@ export type AppPageInterceptOptions<TModule extends AppPageModule = AppPageModul
   interceptNotFoundBranchSegments?: readonly string[] | null;
   interceptNotFound?: TModule | null;
   interceptNotFoundTreePosition?: number | null;
+  interceptForbiddens?: readonly (TModule | null | undefined)[] | null;
+  interceptForbiddenTreePositions?: readonly number[] | null;
+  interceptUnauthorizeds?: readonly (TModule | null | undefined)[] | null;
+  interceptUnauthorizedTreePositions?: readonly number[] | null;
+  interceptErrors?: readonly (AppPageErrorModule | null | undefined)[] | null;
+  interceptErrorTreePositions?: readonly number[] | null;
+  interceptNotFounds?: readonly (TModule | null | undefined)[] | null;
+  interceptNotFoundTreePositions?: readonly number[] | null;
   interceptPage?: TModule | null;
   interceptParams?: AppPageParams | null;
   interceptSlotId?: string | null;
@@ -57,6 +65,8 @@ export type AppPagePageRequest<TModule extends AppPageModule = AppPageModule> =
   observePageSearchParamsAccess?: boolean;
   /** The route is `dynamic = "force-static"`, so pages read an empty query. */
   isForceStatic?: boolean;
+  /** The render can never be stored (see buildAppPageElements). */
+  isUncacheableRender?: boolean;
   /** Observe page metadata `searchParams` access for cache-safety classification. */
   observeMetadataSearchParamsAccess?: boolean;
   /** Whether generated metadata may stream into the response body. */
@@ -70,6 +80,12 @@ export type AppPagePageRequest<TModule extends AppPageModule = AppPageModule> =
   placeStreamedMetadataInHead?: boolean;
   /** Whether streamed render errors must be sanitized for client transport. */
   isProduction?: boolean;
+  /**
+   * Receives the route's head once this render starts resolving it, so a
+   * special-error fallback after the render can reuse it rather than calling
+   * generateMetadata() again.
+   */
+  onHeadPrepared?: (head: AppPagePreparedRouteHead) => void;
 };
 export type BuildPageElementsOptions<TModule extends AppPageModule = AppPageModule, TErrorModule extends AppPageErrorModule = AppPageErrorModule> = {
   applyFileBasedMetadata?: ApplyAppPageFileBasedMetadata;