vinext 1.2.1 → 1.3.1

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

@@ -1,6 +1,8 @@
 import { stripBasePath } from "../utils/base-path.js";
 import { isNavigationSignalError } from "../utils/navigation-signal.js";
 import { NEVER_CACHE_CONTROL, applyCdnResponseHeaders } from "./cache-control.js";
+import { isRenderDynamicLatched, isStaticGenerationAccessError } from "../shims/internal/headers-state.js";
+import { createArtifactCompatibilityEnvelope } from "./artifact-compatibility.js";
 import { AppElementsWire } from "./app-elements-wire.js";
 import "./app-elements.js";
 import DefaultGlobalError from "../shims/default-global-error.js";
@@ -8,20 +10,52 @@ import { ErrorBoundary, GlobalErrorBoundary, SerializedErrorBoundary } from "../
 import { LayoutSegmentProvider } from "../shims/layout-segment-context.js";
 import { withUseCacheLayoutMarker } from "../shims/internal/app-page-props-cache-key.js";
 import { MetadataHead, ViewportHead } from "../shims/metadata.js";
-import { resolveAppPageBranchParams, resolveAppPageSegmentParams } from "./app-page-params.js";
 import { stripRscSuffix } from "./app-rsc-cache-busting.js";
+import { copyLinkHeaderProvenance } from "./app-response-header-provenance.js";
 import { buildRscRedirectFlightStream } from "./app-rsc-redirect-flight.js";
 import { bufferAppPageBinaryStream, buildAppPageSpecialErrorResponse, resolveAppPageSpecialError } from "./app-page-execution.js";
-import { createAppPageLayoutEntries, createAppPageSourcePage } from "./app-page-route-wiring.js";
-import { createAppPageFontData, createAppPageRscErrorTracker, createAppPageSsrErrorHandler, renderAppPageHtmlResponse } from "./app-page-stream.js";
+import { resolveAppPageBranchParams, resolveAppPageSegmentParams } from "./app-page-params.js";
+import { createAppPageLayoutEntries, createAppPageRouteBodyMetadata, createAppPageSourcePage } from "./app-page-route-wiring.js";
 import { buildClientHookErrorMessage } from "../shims/client-hook-error.js";
-import { resolveActiveParallelRouteHeadInputs, resolveAppPageHead } from "./app-page-head.js";
-import { resolveHttpAccessFallbackMetadata, resolveHttpAccessFallbackViewport } from "./app-page-http-access-fallback-metadata.js";
-import "./app-rsc-route-matching.js";
+import { createAppPageMetadataSearchParamsObserver } from "./app-page-search-params-observation.js";
+import { hasAppPageDynamicMetadata, prepareAppPageHead, resolveActiveParallelRouteHeadInputs, resolveAppPageHead, slotInterceptKeepsSourceHead } from "./app-page-head.js";
 import { renderAppPageBoundaryResponse, resolveAppPageErrorBoundary, resolveAppPageHttpAccessBoundaryModule, wrapAppPageBoundaryElement } from "./app-page-boundary.js";
+import { createRouteNotFoundHeadPlanOptions, recoverAppPageRouteHead, resolveHttpAccessFallbackMetadata, resolveHttpAccessFallbackViewport } from "./app-page-http-access-fallback-metadata.js";
+import "./app-rsc-route-matching.js";
 import { resolveSlotParamOverrides } from "./app-page-element-builder.js";
-import { Fragment, createElement } from "react";
+import { createAppPageFontData, createAppPageRscErrorTracker, createAppPageSsrErrorHandler, renderAppPageHtmlResponse } from "./app-page-stream.js";
+import { Fragment, Suspense, createElement } from "react";
 //#region src/server/app-page-boundary-render.ts
+async function AppPageBoundaryStreamedMetadata(props) {
+	return createAppPageRouteBodyMetadata(await props.metadata, props.pathname, "body", props.trailingSlash, props.scriptNonce);
+}
+AppPageBoundaryStreamedMetadata.displayName = "Vinext.StreamingMetadata";
+/** Holds the response open until a head it doesn't render settles, as Next.js streams it. */
+async function AppPageBoundarySettledHead(props) {
+	await props.head;
+	return null;
+}
+AppPageBoundarySettledHead.displayName = "Vinext.ErrorShellMetadata";
+/**
+* Fail a fallback document once its body has streamed if a head it streamed
+* behind Suspense hit a `dynamic = "error"` access error. Inside a Suspense
+* boundary, React would only report it and finish the document, so the 404
+* could be served, and stored, where Next.js fails the render. An errored body
+* reaches the client truncated and is never written to the cache.
+*/
+function failOnLateAccessError(response, accessErrors) {
+	if (accessErrors.length === 0 || !response.body) return response;
+	const body = response.body.pipeThrough(new TransformStream({ async flush() {
+		for (const accessError of await Promise.all(accessErrors)) if (accessError) throw accessError;
+	} }));
+	const wrapped = new Response(body, {
+		headers: response.headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+	copyLinkHeaderProvenance(response.headers, wrapped.headers);
+	return wrapped;
+}
 const DEFAULT_GLOBAL_ERROR_COMPONENT = DefaultGlobalError;
 function getDefaultExport(module) {
 	return module?.default ?? null;
@@ -34,6 +68,8 @@ function resolveHttpAccessBoundaryTreePosition(route, boundaryModule, statusCode
 	if (boundaryModule === routeBoundary && statusCode === 403) return route.forbiddenTreePosition ?? null;
 	if (boundaryModule === routeBoundary && statusCode === 401) return route.unauthorizedTreePosition ?? null;
 	for (let index = (layoutBoundaries?.length ?? 0) - 1; index >= 0; index--) if (layoutBoundaries?.[index] === boundaryModule) return route.layoutTreePositions?.[index] ?? null;
+	const segmentIndex = (statusCode === 403 ? route.segmentForbiddens : statusCode === 401 ? route.segmentUnauthorizeds : route.segmentNotFounds)?.lastIndexOf(boundaryModule) ?? -1;
+	if (segmentIndex !== -1) return (statusCode === 403 ? route.segmentForbiddenTreePositions : statusCode === 401 ? route.segmentUnauthorizedTreePositions : route.segmentNotFoundTreePositions)?.[segmentIndex] ?? null;
 	return null;
 }
 function wrapRenderedBoundaryElement(options) {
@@ -96,14 +132,19 @@ function createAppPageBoundaryRscPayload(options) {
 	const routeId = AppElementsWire.encodeRouteId(options.pathname, null);
 	const layoutEntries = createAppPageBoundaryLayoutEntries(options.route, options.layoutModules);
 	const sourcePageSegments = options.sourcePageSegments ?? options.route?.routeSegments;
+	const rootLayoutTreePath = layoutEntries[0]?.treePath ?? null;
 	return {
 		...AppElementsWire.createMetadataEntries({
 			interceptionContext: null,
 			layoutIds: layoutEntries.map((entry) => entry.id),
-			rootLayoutTreePath: layoutEntries[0]?.treePath ?? null,
+			rootLayoutTreePath,
 			routeId,
 			sourcePage: sourcePageSegments ? createAppPageSourcePage(sourcePageSegments) : null
 		}),
+		[AppElementsWire.keys.artifactCompatibility]: createArtifactCompatibilityEnvelope({
+			deploymentVersion: process.env.__VINEXT_BUILD_ID ?? null,
+			rootBoundaryId: rootLayoutTreePath
+		}),
 		[routeId]: options.element
 	};
 }
@@ -157,6 +198,7 @@ async function renderAppPageBoundaryElementResponse(options) {
 					isCacheCandidate: options.isCacheCandidate,
 					isEdgeRuntime: options.isEdgeRuntime,
 					middlewareHeaders: options.middlewareContext.headers,
+					preloadRoutePattern: options.route ? options.route.pattern : null,
 					navigationContext: options.getNavigationContext() ?? {
 						pathname,
 						searchParams: requestUrl.searchParams,
@@ -217,17 +259,23 @@ async function renderAppPageHttpAccessFallback(options) {
 	const layoutModules = options.layoutModules ?? options.route?.layouts ?? options.rootLayouts;
 	const pathname = new URL(options.requestUrl).pathname;
 	const routePathname = options.routePathname ?? stripRscSuffix(stripBasePath(pathname, options.basePath ?? ""));
-	const routeSegments = resolveHttpAccessFallbackHeadRouteSegments(options.route, layoutModules);
+	const headBoundaryModule = options.headBoundaryModule ?? boundaryModule;
+	const headLayoutModules = options.headLayoutModules ?? layoutModules;
+	const routeSegments = resolveHttpAccessFallbackHeadRouteSegments(options.route, headLayoutModules);
 	const fallbackRouteSegments = routeSegments ?? [];
 	let head;
+	let streamedRouteMetadata = null;
+	let streamedConventionHead = null;
+	const lateAccessErrors = [];
 	try {
 		if ([
 			401,
 			403,
 			404
 		].includes(options.statusCode)) {
-			const boundaryTreePosition = resolveHttpAccessBoundaryTreePosition(options.route, boundaryModule, options.statusCode);
-			const boundaryParams = boundaryTreePosition == null ? {} : resolveAppPageSegmentParams(fallbackRouteSegments, boundaryTreePosition, options.matchedParams);
+			const boundaryTreePosition = resolveHttpAccessBoundaryTreePosition(options.route, headBoundaryModule, options.statusCode);
+			const boundaryRouteSegments = (options.route?.routeSegments ?? fallbackRouteSegments).slice(0, boundaryTreePosition ?? 0);
+			const boundaryParams = boundaryTreePosition == null ? {} : resolveAppPageSegmentParams(boundaryRouteSegments, boundaryTreePosition, options.matchedParams);
 			const intercept = options.intercept;
 			const isSiblingIntercept = intercept?.interceptSlotKey === "__vinext_page_intercept" && intercept.interceptPage != null;
 			const effectiveParams = isSiblingIntercept ? intercept.interceptParams ?? options.matchedParams : options.matchedParams;
@@ -249,52 +297,180 @@ async function renderAppPageHttpAccessFallback(options) {
 				slotParams,
 				slots: options.route?.slots ?? null
 			});
-			const primaryParallelBranch = isSiblingIntercept ? {
+			const resolvePrimaryParallelBranch = (segments) => isSiblingIntercept ? {
 				head: {
 					layoutModules: intercept?.interceptLayouts ?? [],
-					layoutParams: (intercept?.interceptLayoutSegments ?? []).map((segments) => resolveAppPageBranchParams(intercept?.interceptBranchSegments ?? segments, segments.length, effectiveParams, segments)),
+					layoutParams: (intercept?.interceptLayoutSegments ?? []).map((layoutSegments) => resolveAppPageBranchParams(intercept?.interceptBranchSegments ?? layoutSegments, layoutSegments.length, effectiveParams, layoutSegments)),
 					pageModule: intercept?.interceptPage ?? null,
 					params: effectiveParams,
-					routeSegments: intercept?.interceptSourcePageSegments ?? fallbackRouteSegments
+					routeSegments: intercept?.interceptSourcePageSegments ?? segments
 				},
 				...intercept?.interceptNotFound ? {
 					notFoundModule: intercept.interceptNotFound,
-					notFoundModuleRouteSegments: (intercept.interceptNotFoundBranchSegments ?? intercept.interceptSourcePageSegments ?? fallbackRouteSegments).slice(0, intercept.interceptNotFoundTreePosition ?? 0),
-					notFoundParams: resolveAppPageBranchParams(intercept.interceptNotFoundBranchSegments ?? intercept.interceptBranchSegments ?? fallbackRouteSegments, intercept.interceptNotFoundTreePosition ?? 0, effectiveParams)
+					notFoundModuleRouteSegments: (intercept.interceptNotFoundBranchSegments ?? intercept.interceptSourcePageSegments ?? segments).slice(0, intercept.interceptNotFoundTreePosition ?? 0),
+					notFoundParams: resolveAppPageBranchParams(intercept.interceptNotFoundBranchSegments ?? intercept.interceptBranchSegments ?? segments, intercept.interceptNotFoundTreePosition ?? 0, effectiveParams)
 				} : {},
-				ownerTreePosition: fallbackRouteSegments.length
+				ownerTreePosition: segments.length
 			} : null;
+			const primaryParallelBranch = resolvePrimaryParallelBranch(fallbackRouteSegments);
 			const fallbackHeadOptions = {
-				boundaryModule,
+				boundaryModule: headBoundaryModule,
 				boundaryParams,
-				boundaryRouteSegments: fallbackRouteSegments.slice(0, boundaryTreePosition ?? 0),
+				boundaryRouteSegments,
 				branchNotFoundConventions: options.statusCode === 404,
 				errorConvention: options.statusCode === 403 ? "forbidden" : options.statusCode === 401 ? "unauthorized" : "not-found",
-				layoutModules,
-				layoutTreePositions: resolveHttpAccessFallbackHeadLayoutTreePositions(options.route, layoutModules),
+				layoutModules: headLayoutModules,
+				layoutTreePositions: resolveHttpAccessFallbackHeadLayoutTreePositions(options.route, headLayoutModules),
 				parallelBranches,
 				params: options.matchedParams,
 				primaryParallelBranch,
 				routeSegments
 			};
-			const [metadata, viewport] = await Promise.all([resolveHttpAccessFallbackMetadata({
-				applyFileBasedMetadata: options.applyFileBasedMetadata,
-				basePath: options.basePath ?? "",
-				...fallbackHeadOptions,
-				metadataRoutes: options.metadataRoutes,
-				routePath: options.route?.pattern ?? pathname
-			}), resolveHttpAccessFallbackViewport(fallbackHeadOptions)]);
-			head = {
-				metadata,
-				viewport
+			const startConventionHead = ({ errorShell = false } = {}) => {
+				const settle = (branch) => errorShell ? branch.catch((error) => {
+					if (isStaticGenerationAccessError(error)) throw error;
+					return null;
+				}) : branch;
+				const metadata = settle(resolveHttpAccessFallbackMetadata({
+					applyFileBasedMetadata: options.applyFileBasedMetadata,
+					basePath: options.basePath ?? "",
+					...fallbackHeadOptions,
+					metadataRoutes: options.metadataRoutes,
+					routePath: options.route?.pattern ?? pathname
+				}));
+				const viewport = settle(resolveHttpAccessFallbackViewport(fallbackHeadOptions));
+				metadata.catch(() => null);
+				viewport.catch(() => null);
+				return {
+					metadata,
+					viewport
+				};
+			};
+			const resolveConventionHead = async (settings) => {
+				const conventionHead = startConventionHead(settings);
+				const [metadata, viewport] = await Promise.all([conventionHead.metadata, conventionHead.viewport]);
+				return {
+					metadata,
+					viewport
+				};
 			};
+			const route = options.route;
+			const routeHead = options.routeHead;
+			if (routeHead && route) {
+				const prepareRouteHead = () => {
+					if (routeHead.prepared) return routeHead.prepared;
+					const fullRouteSegments = route.routeSegments ?? [];
+					const routePrimaryParallelBranch = resolvePrimaryParallelBranch(fullRouteSegments);
+					const sourceParallelBranches = resolveActiveParallelRouteHeadInputs({
+						layoutTreePositions: route.layoutTreePositions,
+						params: options.matchedParams,
+						routeSegments: fullRouteSegments,
+						slotParams,
+						slots: route.slots ?? null
+					});
+					const interceptSlotKey = intercept?.interceptPage != null && !isSiblingIntercept ? intercept.interceptSlotKey ?? null : null;
+					const routeParallelBranches = interceptSlotKey === null || slotInterceptKeepsSourceHead({
+						interceptSlotKey,
+						route,
+						sourceParallelRoutes: sourceParallelBranches
+					}) ? sourceParallelBranches : resolveActiveParallelRouteHeadInputs({
+						interceptBranchSegments: intercept?.interceptBranchSegments ?? null,
+						interceptLayouts: intercept?.interceptLayouts ?? null,
+						interceptLayoutSegments: intercept?.interceptLayoutSegments ?? null,
+						interceptNotFoundBranchSegments: intercept?.interceptNotFoundBranchSegments ?? null,
+						interceptNotFound: intercept?.interceptNotFound ?? null,
+						interceptNotFoundTreePosition: intercept?.interceptNotFoundTreePosition ?? null,
+						interceptPage: intercept?.interceptPage ?? null,
+						interceptParams: intercept?.interceptParams ?? null,
+						interceptSlotKey,
+						interceptSourcePageSegments: intercept?.interceptSourcePageSegments ?? null,
+						layoutTreePositions: route.layoutTreePositions,
+						params: options.matchedParams,
+						routeSegments: fullRouteSegments,
+						slotParams,
+						slots: route.slots ?? null
+					});
+					const routeLayoutModules = route.layouts ?? options.rootLayouts;
+					const headOptions = {
+						applyFileBasedMetadata: options.applyFileBasedMetadata,
+						basePath: options.basePath ?? "",
+						layoutModules: routeLayoutModules,
+						layoutTreePositions: route.layoutTreePositions,
+						metadataRoutes: options.metadataRoutes,
+						pageModule: isSiblingIntercept ? null : route.page ?? null,
+						parallelRoutes: [...routePrimaryParallelBranch ? [routePrimaryParallelBranch.head] : [], ...routeParallelBranches.map((branch) => branch.head)],
+						params: effectiveParams,
+						routePath: route.pattern ?? pathname,
+						routeSegments: route.routeSegments ?? null,
+						searchParams: routeHead.searchParams,
+						searchParamsObserver: createAppPageMetadataSearchParamsObserver(routeHead.observeSearchParams)
+					};
+					return {
+						...recoverAppPageRouteHead(prepareAppPageHead(headOptions), {
+							applyFileBasedMetadata: options.applyFileBasedMetadata,
+							basePath: options.basePath ?? "",
+							metadataRoutes: options.metadataRoutes,
+							resolvePlanOptions: () => createRouteNotFoundHeadPlanOptions({
+								parallelBranches: routeParallelBranches,
+								params: effectiveParams,
+								primaryParallelBranch: routePrimaryParallelBranch,
+								rootNotFoundModule: options.rootNotFoundModule,
+								route: {
+									...route,
+									layouts: routeLayoutModules
+								}
+							}),
+							routePath: route.pattern ?? pathname
+						}),
+						metadataPlacement: routeHead.streamMetadata && hasAppPageDynamicMetadata(headOptions) ? "body" : "head"
+					};
+				};
+				const routeHeadResult = prepareRouteHead();
+				const throwIfAccessError = async () => {
+					const accessError = await routeHeadResult.accessError;
+					if (accessError) throw accessError;
+				};
+				const conventionHeadBranches = options.isRscRequest ? null : startConventionHead({ errorShell: true });
+				const isHtmlLimitedBot = options.serveStreamingMetadata === false;
+				let conventionHead = null;
+				if (conventionHeadBranches && isHtmlLimitedBot) {
+					const [metadata, viewport] = await Promise.all([conventionHeadBranches.metadata, conventionHeadBranches.viewport]);
+					conventionHead = {
+						metadata,
+						viewport
+					};
+				} else if (conventionHeadBranches) {
+					await conventionHeadBranches.viewport;
+					streamedConventionHead = conventionHeadBranches.metadata.catch(() => null);
+					lateAccessErrors.push(conventionHeadBranches.metadata.then(() => null, (error) => isStaticGenerationAccessError(error) ? error : null));
+				}
+				if (!options.isRscRequest && routeHeadResult.metadataPlacement === "body") {
+					streamedRouteMetadata = routeHeadResult.metadata;
+					lateAccessErrors.push(routeHeadResult.accessError);
+					head = {
+						metadata: null,
+						viewport: await routeHeadResult.viewport
+					};
+				} else {
+					const [metadata, viewport] = await Promise.all([
+						routeHeadResult.metadata,
+						routeHeadResult.viewport,
+						throwIfAccessError()
+					]);
+					head = {
+						metadata,
+						viewport
+					};
+				}
+				if (conventionHead && !streamedRouteMetadata && isHtmlLimitedBot && (!options.isCacheCandidate || isRenderDynamicLatched())) head = conventionHead;
+			} else head = await resolveConventionHead();
 		} else head = await resolveAppPageHead({
 			applyFileBasedMetadata: options.applyFileBasedMetadata,
 			basePath: options.basePath ?? "",
-			layoutModules,
-			layoutTreePositions: resolveHttpAccessFallbackHeadLayoutTreePositions(options.route, layoutModules),
+			layoutModules: headLayoutModules,
+			layoutTreePositions: resolveHttpAccessFallbackHeadLayoutTreePositions(options.route, headLayoutModules),
 			metadataRoutes: options.metadataRoutes,
-			pageModule: boundaryModule,
+			pageModule: headBoundaryModule,
 			params: options.matchedParams,
 			routePath: options.route?.pattern ?? pathname,
 			routeSegments
@@ -316,16 +492,30 @@ async function renderAppPageHttpAccessFallback(options) {
 	if (metadata) headElements.push(createElement(MetadataHead, {
 		key: "metadata",
 		metadata,
-		pathname,
+		pathname: routePathname,
 		trailingSlash: options.trailingSlash
 	}));
-	headElements.push(createElement(ViewportHead, {
+	if (viewport) headElements.push(createElement(ViewportHead, {
 		key: "viewport",
 		viewport
 	}));
+	const bodyElements = [];
+	if (streamedRouteMetadata) bodyElements.push(createElement("div", {
+		hidden: true,
+		key: "streamed-metadata"
+	}, createElement(Suspense, { fallback: null }, createElement(AppPageBoundaryStreamedMetadata, {
+		metadata: streamedRouteMetadata,
+		pathname: routePathname,
+		scriptNonce: options.scriptNonce,
+		trailingSlash: options.trailingSlash
+	}))));
+	if (streamedConventionHead) bodyElements.push(createElement("div", {
+		hidden: true,
+		key: "error-shell-metadata"
+	}, createElement(Suspense, { fallback: null }, createElement(AppPageBoundarySettledHead, { head: streamedConventionHead }))));
 	const skipLayoutWrapping = options.skipLayoutWrapping ?? false;
 	const element = wrapRenderedBoundaryElement({
-		element: createElement(Fragment, null, ...headElements, createElement(boundaryComponent)),
+		element: createElement(Fragment, null, ...headElements, createElement(boundaryComponent), ...bodyElements),
 		globalErrorModule: options.globalErrorModule,
 		includeGlobalErrorBoundary: true,
 		isRscRequest: options.isRscRequest,
@@ -337,7 +527,7 @@ async function renderAppPageHttpAccessFallback(options) {
 		routeSegments: options.route?.routeSegments,
 		skipLayoutWrapping
 	});
-	return renderAppPageBoundaryElementResponse({
+	return failOnLateAccessError(await renderAppPageBoundaryElementResponse({
 		...options,
 		element,
 		handleSpecialErrors: true,
@@ -347,7 +537,7 @@ async function renderAppPageHttpAccessFallback(options) {
 		route: skipLayoutWrapping ? null : options.route,
 		routePattern: options.route?.pattern,
 		status: options.statusCode
-	});
+	}), lateAccessErrors);
 }
 async function renderAppPageErrorBoundary(options) {
 	const errorBoundary = resolveAppPageErrorBoundary({

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

@@ -29,6 +29,13 @@ type ResolveAppPageParentHttpAccessBoundaryModuleOptions<TModule> = {
   routeUnauthorizedModules?: readonly (TModule | null | undefined)[] | null;
   statusCode: number;
 };
+type ResolveAppPageLayoutHttpAccessBoundaryOptions<TModule> = {
+  /** Segment boundaries for the status, root first, aligned with the positions. */
+  boundaryModules: readonly (TModule | null | undefined)[];
+  boundaryTreePositions: readonly number[];
+  /** Tree position of the layout that threw. */
+  layoutTreePosition: number;
+};
 type ResolveAppPageErrorBoundaryOptions<TModule, TComponent> = {
   getDefaultExport: (module: TModule | null | undefined) => TComponent | null | undefined;
   globalErrorModule?: TModule | null;
@@ -74,11 +81,32 @@ type RenderAppPageBoundaryResponseOptions<TElement> = {
 };
 export declare function resolveAppPageHttpAccessBoundaryComponent<TModule, TComponent>(options: ResolveAppPageHttpAccessBoundaryComponentOptions<TModule, TComponent>): TComponent | null;
 export declare function resolveAppPageHttpAccessBoundaryModule<TModule>(options: ResolveAppPageHttpAccessBoundaryModuleOptions<TModule>): TModule | null;
-export declare function resolveAppPageParentHttpAccessBoundaryModule<TModule>(options: ResolveAppPageParentHttpAccessBoundaryModuleOptions<TModule>): TModule | null;
 /**
- * Like {@link resolveAppPageParentHttpAccessBoundaryModule}, but also returns
- * the layout index that owns the resolved boundary so callers can slice the
- * layouts array to skip rendering layouts below the boundary owner.
+ * The boundary that catches `notFound()` / `forbidden()` / `unauthorized()`
+ * thrown by a layout: the deepest segment boundary above the layout's own
+ * segment. A segment's boundary wraps its children inside its layout, so the
+ * layout's own boundary, and any below it, cannot catch the layout's error.
+ * Returns `null` when no segment above the layout has one (issue #4045).
+ */
+export declare function resolveAppPageLayoutHttpAccessBoundary<TModule>(options: ResolveAppPageLayoutHttpAccessBoundaryOptions<TModule>): {
+  module: TModule;
+  treePosition: number;
+} | null;
+/**
+ * Tree position at which the root segment's boundary catches a layout's error.
+ * Next.js gives a first-layer route group the root segment's boundary (the
+ * custom file or the built-in page) when the group has none of its
+ * own, so the boundary renders inside the group's layout, which is often the
+ * root layout. Without `app/layout`, the root layout sits deeper (for example
+ * `app/[lang]/layout`), and the boundary renders inside it so the page keeps
+ * its `<html>` and `<body>`. A boundary file above that root layout renders
+ * there too.
+ */
+export declare function resolveAppPageRootHttpAccessBoundaryTreePosition(routeSegments: readonly string[], layoutTreePositions: readonly number[], layoutTreePosition: number | undefined): number;
+/**
+ * Resolves the nearest layout-aligned boundary before `layoutIndex`, falling
+ * back to the root module, and returns the layout index that owns it so
+ * callers can slice the layouts array to skip layouts below the boundary owner.
  *
  * `layoutIndex` is the per-layout index where the boundary lives, or `null` if
  * the resolved boundary is the root module (which conceptually sits above all
@@ -98,4 +126,5 @@ export declare function resolveAppPageParentHttpAccessBoundary<TModule>(options:
 export declare function resolveAppPageErrorBoundary<TModule, TComponent>(options: ResolveAppPageErrorBoundaryOptions<TModule, TComponent>): ResolveAppPageErrorBoundaryResult<TComponent>;
 export declare function wrapAppPageBoundaryElement<TElement, TLayoutModule, TLayoutComponent, TChildSegments, TGlobalErrorComponent>(options: WrapAppPageBoundaryElementOptions<TElement, TLayoutModule, TLayoutComponent, TChildSegments, TGlobalErrorComponent>): TElement;
 export declare function renderAppPageBoundaryResponse<TElement>(options: RenderAppPageBoundaryResponseOptions<TElement>): Promise<Response>;
-//#endregion
+//#endregion
+export {};

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

@@ -1,9 +1,10 @@
 import { VINEXT_RSC_VARY_HEADER } from "./app-rsc-vary.js";
 import { runWithFetchDedupe } from "../shims/fetch-cache.js";
-import { resolveAppPageSegmentParams } from "./app-page-params.js";
 import { VINEXT_RSC_CONTENT_TYPE, applyRscCompatibilityIdHeader, applyRscDeploymentIdHeader } from "./app-rsc-cache-busting.js";
 import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
 import { applyEdgeRuntimeHeader } from "./app-page-response.js";
+import { resolveAppPageSegmentParams } from "./app-page-params.js";
+import { isAppPageRouteGroupSegment } from "./app-page-segment-state.js";
 //#region src/server/app-page-boundary.ts
 function resolveAppPageHttpAccessBoundaryComponent(options) {
 	return options.getDefaultExport(resolveAppPageHttpAccessBoundaryModule({
@@ -23,13 +24,45 @@ function resolveAppPageHttpAccessBoundaryModule(options) {
 	else boundaryModule = options.routeNotFoundModule ?? options.rootNotFoundModule;
 	return boundaryModule ?? null;
 }
-function resolveAppPageParentHttpAccessBoundaryModule(options) {
-	return resolveAppPageParentHttpAccessBoundary(options).module;
+/**
+* The boundary that catches `notFound()` / `forbidden()` / `unauthorized()`
+* thrown by a layout: the deepest segment boundary above the layout's own
+* segment. A segment's boundary wraps its children inside its layout, so the
+* layout's own boundary, and any below it, cannot catch the layout's error.
+* Returns `null` when no segment above the layout has one (issue #4045).
+*/
+function resolveAppPageLayoutHttpAccessBoundary(options) {
+	for (let index = options.boundaryTreePositions.length - 1; index >= 0; index--) {
+		const treePosition = options.boundaryTreePositions[index];
+		const module = options.boundaryModules[index];
+		if (module && treePosition < options.layoutTreePosition) return {
+			module,
+			treePosition
+		};
+	}
+	return null;
+}
+/**
+* Tree position at which the root segment's boundary catches a layout's error.
+* Next.js gives a first-layer route group the root segment's boundary (the
+* custom file or the built-in page) when the group has none of its
+* own, so the boundary renders inside the group's layout, which is often the
+* root layout. Without `app/layout`, the root layout sits deeper (for example
+* `app/[lang]/layout`), and the boundary renders inside it so the page keeps
+* its `<html>` and `<body>`. A boundary file above that root layout renders
+* there too.
+*/
+function resolveAppPageRootHttpAccessBoundaryTreePosition(routeSegments, layoutTreePositions, layoutTreePosition) {
+	if (layoutTreePosition === void 0) return 0;
+	const firstSegment = routeSegments[0];
+	const groupTreePosition = layoutTreePosition > 1 && firstSegment !== void 0 && isAppPageRouteGroupSegment(firstSegment) ? 1 : 0;
+	const rootLayoutTreePosition = layoutTreePositions[0] ?? 0;
+	return rootLayoutTreePosition < layoutTreePosition ? Math.max(groupTreePosition, rootLayoutTreePosition) : groupTreePosition;
 }
 /**
-* Like {@link resolveAppPageParentHttpAccessBoundaryModule}, but also returns
-* the layout index that owns the resolved boundary so callers can slice the
-* layouts array to skip rendering layouts below the boundary owner.
+* Resolves the nearest layout-aligned boundary before `layoutIndex`, falling
+* back to the root module, and returns the layout index that owns it so
+* callers can slice the layouts array to skip layouts below the boundary owner.
 *
 * `layoutIndex` is the per-layout index where the boundary lives, or `null` if
 * the resolved boundary is the root module (which conceptually sits above all
@@ -119,4 +152,4 @@ async function renderAppPageBoundaryResponse(options) {
 	return options.createHtmlResponse(rscStream, options.status);
 }
 //#endregion
-export { renderAppPageBoundaryResponse, resolveAppPageErrorBoundary, resolveAppPageHttpAccessBoundaryComponent, resolveAppPageHttpAccessBoundaryModule, resolveAppPageParentHttpAccessBoundary, resolveAppPageParentHttpAccessBoundaryModule, wrapAppPageBoundaryElement };
+export { renderAppPageBoundaryResponse, resolveAppPageErrorBoundary, resolveAppPageHttpAccessBoundaryComponent, resolveAppPageHttpAccessBoundaryModule, resolveAppPageLayoutHttpAccessBoundary, resolveAppPageParentHttpAccessBoundary, resolveAppPageRootHttpAccessBoundaryTreePosition, wrapAppPageBoundaryElement };

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

@@ -98,4 +98,5 @@ export declare function finalizeAppPageCacheabilityEvaluationResponse(response:
 export declare function finalizeAppPageHtmlCacheResponse(response: Response, options: FinalizeAppPageHtmlCacheResponseOptions): Response;
 export declare function finalizeAppPageRscCacheResponse(response: Response, options: ScheduleAppPageRscCacheWriteOptions): Response;
 export declare function scheduleAppPageRscCacheWrite(options: ScheduleAppPageRscCacheWriteOptions): boolean;
-//#endregion
+//#endregion
+export {};

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

@@ -1,3 +1,4 @@
+import { deferUntilStreamConsumed } from "./defer-until-stream-consumed.js";
 import { NEXTJS_CACHE_HEADER, VINEXT_CACHE_HEADER } from "./headers.js";
 import { getCdnCacheAdapter } from "../shims/cdn-cache.js";
 import { captureRouteCacheabilityResponsePolicy, deferRouteCacheability, isRouteCacheabilityEvaluation } from "../shims/cacheability-classification.js";
@@ -6,7 +7,6 @@ import { buildAppPageCacheValue, isrCacheControl, resolveRouteExpireSeconds } fr
 import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
 import { setCacheStateHeaders } from "./cache-headers.js";
 import { readStreamAsText } from "../utils/text-stream.js";
-import { deferUntilStreamConsumed } from "./defer-until-stream-consumed.js";
 import { markFrameworkLinkHeaders } from "./app-response-header-provenance.js";
 import { hasQueryInvariantRenderProof } from "./cache-proof.js";
 import { createEmptyAppPageRenderObservationState } from "./app-page-render-observation.js";

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

@@ -35,7 +35,14 @@ export type RenderAppPageCacheArtifactsOptions = {
    * Render the document of a special error that rejected the shell, or return
    * null to fail the render with it.
    */
-  renderShellSpecialError?: (error: unknown) => Promise<AppPageCacheSpecialErrorDocument | null>;
+  renderShellSpecialError?: (error: unknown,
+  /** The page's own document, in which parallel slot boundaries caught it. */
+  caughtDocument?: {
+    html: string;
+    linkHeader?: string;
+  }) => Promise<AppPageCacheSpecialErrorDocument | null>;
+  /** The parallel slot not-found boundaries that catch a shell error. See handleSsr. */
+  resolveCaughtNotFoundBoundaries?: (error: unknown) => readonly string[] | null;
   renderToReadableStream: (element: AppPageRenderableElement, options: {
     onError: (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
   }) => ReadableStream<Uint8Array>;
@@ -73,4 +80,5 @@ export type RenderAppPageCacheArtifactsResult = {
  * shell regeneration.
  */
 export declare function renderAppPageCacheArtifacts(options: RenderAppPageCacheArtifactsOptions): Promise<RenderAppPageCacheArtifactsResult>;
-//#endregion
+//#endregion
+export {};

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

@@ -5,9 +5,9 @@ import { getCollectedFetchTags } from "../shims/fetch-cache.js";
 import { readStreamAsText } from "../utils/text-stream.js";
 import { buildAppPageFontLinkHeader, teeAppPageRscStreamForCapture } from "./app-page-execution.js";
 import { recordAppPageRenderError, traceAppPageRender } from "./app-page-tracing.js";
-import { buildAppPageTags } from "./implicit-tags.js";
-import { consumeAppPageRenderObservationState, createAppPageHtmlOutputScope, createAppPageRenderObservation, createAppPageRscOutputScope } from "./app-page-render-observation.js";
 import { buildAppPageLinkHeader, createAppPageSsrErrorHandler, isAppSsrRenderResult } from "./app-page-stream.js";
+import { consumeAppPageRenderObservationState, createAppPageHtmlOutputScope, createAppPageRenderObservation, createAppPageRscOutputScope } from "./app-page-render-observation.js";
+import { buildAppPageTags } from "./implicit-tags.js";
 //#region src/server/app-page-cache-render.ts
 /**
 * Render an App page element to HTML (and optionally its RSC payload) for cache
@@ -43,6 +43,8 @@ async function renderAppPageCacheArtifactsImpl(options, renderSpan) {
 			mirrorNextFlight: options.mirrorNextFlight,
 			isStaticGeneration: true,
 			isForceStatic: options.isForceStatic,
+			preloadRoutePattern: options.route.pattern,
+			resolveCaughtNotFoundBoundaries: options.resolveCaughtNotFoundBoundaries,
 			onSsrError: options.onSsrError && options.isCapturedRscError ? createAppPageSsrErrorHandler((error) => {
 				recordAppPageRenderError(renderSpan, error);
 				return options.onSsrError?.(error);
@@ -68,6 +70,17 @@ async function renderAppPageCacheArtifactsImpl(options, renderSpan) {
 		const reactLinkHeader = isAppSsrRenderResult(htmlResult) ? htmlResult.linkHeader : void 0;
 		linkHeader = buildAppPageLinkHeader(reactLinkHeader, buildAppPageFontLinkHeader(fontPreloads), options.reactMaxHeadersLength);
 		html = await readStreamAsText(htmlStream);
+		const caughtShellError = isAppSsrRenderResult(htmlResult) ? htmlResult.caughtShellError : void 0;
+		if (caughtShellError !== void 0) {
+			await capturedRscDataRef.value?.catch(() => {});
+			specialErrorDocument = await options.renderShellSpecialError?.(caughtShellError, {
+				html,
+				linkHeader
+			}) ?? null;
+			if (!specialErrorDocument) throw caughtShellError;
+			html = specialErrorDocument.html;
+			linkHeader = specialErrorDocument.linkHeader;
+		}
 	}
 	let rscData;
 	if (options.captureRscData) {

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

@@ -10,10 +10,10 @@ import { VINEXT_RSC_CONTENT_TYPE, applyRscCompatibilityIdHeader, applyRscDeploym
 import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
 import { markFrameworkLinkHeaders } from "./app-response-header-provenance.js";
 import { applyClientStaleTimeHeader, applyEdgeRuntimeHeader } from "./app-page-response.js";
-import { hasQueryInvariantRenderProof } from "./cache-proof.js";
 import { isAppPprDynamicFallbackShellHtml } from "./app-ppr-fallback-shell.js";
-import { buildPageCacheTags } from "./implicit-tags.js";
+import { hasQueryInvariantRenderProof } from "./cache-proof.js";
 import { finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, scheduleAppPageRscCacheWrite } from "./app-page-cache-finalizer.js";
+import { buildPageCacheTags } from "./implicit-tags.js";
 //#region src/server/app-page-cache.ts
 function recordAppPageCacheOutcome(recordCacheOutcome, input) {
 	try {