vinext 1.0.0-beta.1 → 1.0.0-beta.2

package/dist/server/app-page-element-builder.js

@@ -4,13 +4,17 @@ import "./app-elements.js";
 import { createAppPageRenderIdentity } from "./app-page-render-identity.js";
 import { matchRoutePattern } from "../routing/route-pattern.js";
 import { makeThenableParams } from "../shims/thenable-params.js";
-import { resolveAppPageBranchParams } from "./app-page-params.js";
-import { resolveActiveParallelRouteHeadInputs, resolveAppPageHead } from "./app-page-head.js";
+import { resolveAppPageBranchParams, resolveAppPageSegmentParams } from "./app-page-params.js";
+import { resolveAppPageSpecialError } from "./app-page-execution.js";
+import { prepareAppPageHead, resolveActiveParallelRouteHeadInputs } from "./app-page-head.js";
 import { createAppPageSearchParamsObserver, makeObservedAppPageSearchParamsThenable } from "./app-page-search-params-observation.js";
 import { buildAppPageElements, createAppPageSourcePage, createAppPageTreePath } from "./app-page-route-wiring.js";
+import { resolveHttpAccessFallbackMetadata, resolveHttpAccessFallbackViewport } from "./app-page-http-access-fallback-metadata.js";
+import "./app-rsc-route-matching.js";
+import { resolveAppPageParentHttpAccessBoundary } from "./app-page-boundary.js";
+import { sanitizeErrorForClient } from "./app-rsc-errors.js";
 import { DEFAULT_GLOBAL_ERROR_MODULE } from "./default-global-error-module.js";
 import { shouldServeStreamingMetadata } from "./streaming-metadata.js";
-import "./app-rsc-route-matching.js";
 import { createElement } from "react";
 //#region src/server/app-page-element-builder.ts
 function resolveInterceptLayoutParams(branchSegments, layoutSegments, params) {
@@ -41,7 +45,7 @@ function isReactOwnedPageComponent(component) {
 async function buildPageElements(options) {
 	const { route, params, routePath, displayPathname = routePath, pageRequest, globalErrorModule, rootNotFoundModule, rootForbiddenModule, rootUnauthorizedModule, metadataRoutes } = options;
 	const slotParamOverrides = resolveSlotParamOverrides(route, routePath);
-	const { opts, searchParams, isRscRequest, mountedSlotsHeader, renderMode = APP_RSC_RENDER_MODE_NAVIGATION, observeMetadataSearchParamsAccess = false, observePageSearchParamsAccess = false, serveStreamingMetadata } = pageRequest;
+	const { opts, searchParams, isRscRequest, mountedSlotsHeader, renderMode = APP_RSC_RENDER_MODE_NAVIGATION, observeMetadataSearchParamsAccess = false, observePageSearchParamsAccess = false, serveStreamingMetadata, isProduction = process.env.NODE_ENV === "production" } = pageRequest;
 	const pageModule = route.page;
 	const isSiblingIntercept = opts?.interceptSlotKey === "__vinext_page_intercept" && !!opts?.interceptPage;
 	const effectivePageModule = isSiblingIntercept ? opts.interceptPage : pageModule;
@@ -76,38 +80,116 @@ async function buildPageElements(options) {
 			[renderIdentity.routeId]: createElement("div", null, "Page has no default export")
 		};
 	}
-	const { hasDynamicMetadata, metadata: resolvedMetadata, pageSearchParams, viewport: resolvedViewport } = await resolveAppPageHead({
-		applyFileBasedMetadata: options.applyFileBasedMetadata,
-		basePath: options.basePath ?? "",
-		layoutModules: route.layouts,
+	const activeParallelRouteHeadInputs = resolveActiveParallelRouteHeadInputs({
+		interceptBranchSegments: opts?.interceptBranchSegments ?? null,
+		interceptLayouts: opts?.interceptLayouts ?? null,
+		interceptLayoutSegments: opts?.interceptLayoutSegments ?? null,
+		interceptNotFoundBranchSegments: opts?.interceptNotFoundBranchSegments ?? null,
+		interceptNotFound: opts?.interceptNotFound ?? null,
+		interceptNotFoundTreePosition: opts?.interceptNotFoundTreePosition ?? null,
+		interceptPage: opts?.interceptPage ?? null,
+		interceptParams: opts?.interceptParams ?? null,
+		interceptSlotKey: opts?.interceptSlotKey ?? null,
+		interceptSourcePageSegments: opts?.interceptSourcePageSegments ?? null,
 		layoutTreePositions: route.layoutTreePositions,
-		metadataRoutes,
-		pageModule: isSiblingIntercept ? null : effectivePageModule ?? null,
-		parallelRoutes: [...resolveActiveParallelRouteHeadInputs({
-			interceptBranchSegments: opts?.interceptBranchSegments ?? null,
-			interceptLayouts: opts?.interceptLayouts ?? null,
-			interceptLayoutSegments: opts?.interceptLayoutSegments ?? null,
-			interceptPage: opts?.interceptPage ?? null,
-			interceptParams: opts?.interceptParams ?? null,
-			interceptSlotKey: opts?.interceptSlotKey ?? null,
-			layoutTreePositions: route.layoutTreePositions,
-			params,
-			routeSegments: route.routeSegments ?? [],
-			slotParams: slotParamOverrides,
-			slots: route.slots ?? null
-		}), ...isSiblingIntercept ? [{
+		params,
+		routeSegments: route.routeSegments ?? [],
+		slotParams: slotParamOverrides,
+		slots: route.slots ?? null
+	});
+	const primaryParallelRouteHeadInput = isSiblingIntercept ? {
+		head: {
 			layoutModules: opts?.interceptLayouts ?? [],
 			layoutParams: (opts?.interceptLayoutSegments ?? []).map((segments) => resolveInterceptLayoutParams(opts?.interceptBranchSegments ?? segments, segments, effectiveParams)),
 			pageModule: effectivePageModule ?? null,
 			params: effectiveParams,
 			routeSegments: opts?.interceptSourcePageSegments ?? route.routeSegments ?? []
-		}] : []],
+		},
+		...opts?.interceptNotFound ? {
+			notFoundModule: opts.interceptNotFound,
+			notFoundParams: resolveAppPageBranchParams(opts.interceptNotFoundBranchSegments ?? opts.interceptBranchSegments ?? route.routeSegments ?? [], opts.interceptNotFoundTreePosition ?? 0, effectiveParams)
+		} : {},
+		ownerTreePosition: route.routeSegments?.length ?? 0
+	} : null;
+	const parallelRoutes = [...activeParallelRouteHeadInputs.map((input) => input.head), ...primaryParallelRouteHeadInput ? [primaryParallelRouteHeadInput.head] : []];
+	const metadataSearchParamsObserver = observeMetadataSearchParamsAccess ? createAppPageSearchParamsObserver() : void 0;
+	const preparedHead = prepareAppPageHead({
+		applyFileBasedMetadata: options.applyFileBasedMetadata,
+		basePath: options.basePath ?? "",
+		layoutModules: route.layouts,
+		layoutTreePositions: route.layoutTreePositions,
+		metadataRoutes,
+		pageModule: isSiblingIntercept ? null : effectivePageModule ?? null,
+		parallelRoutes,
 		params: effectiveParams,
 		routePath: route.pattern,
 		routeSegments: route.routeSegments ?? null,
 		searchParams,
-		searchParamsObserver: observeMetadataSearchParamsAccess ? createAppPageSearchParamsObserver() : void 0
+		searchParamsObserver: metadataSearchParamsObserver
 	});
+	const { hasDynamicMetadata, pageSearchParams } = preparedHead;
+	const streamGeneratedHead = serveStreamingMetadata ?? shouldServeStreamingMetadata(pageRequest.request.headers.get("user-agent") ?? "", options.htmlLimitedBots);
+	const metadataPlacement = hasDynamicMetadata && streamGeneratedHead ? "body" : "head";
+	const shouldDeferMetadata = metadataPlacement === "body";
+	const streamingMetadata = shouldDeferMetadata ? isProduction ? preparedHead.metadata.catch((error) => {
+		throw sanitizeErrorForClient(error, "production");
+	}) : preparedHead.metadata : null;
+	streamingMetadata?.catch(() => null);
+	const resolveNotFoundFallbackPlanOptions = () => {
+		const routeBoundaryModule = route.notFound;
+		const parentBoundary = resolveAppPageParentHttpAccessBoundary({
+			layoutIndex: route.layouts.length,
+			rootForbiddenModule,
+			rootNotFoundModule,
+			rootUnauthorizedModule,
+			routeForbiddenModules: route.forbiddens,
+			routeNotFoundModules: route.notFounds,
+			routeUnauthorizedModules: route.unauthorizeds,
+			statusCode: 404
+		});
+		const boundaryModule = routeBoundaryModule ?? parentBoundary.module;
+		const boundaryTreePosition = routeBoundaryModule ? route.notFoundTreePosition : parentBoundary.layoutIndex === null ? null : route.layoutTreePositions?.[parentBoundary.layoutIndex];
+		return {
+			boundaryModule,
+			boundaryParams: boundaryModule && boundaryTreePosition != null ? resolveAppPageSegmentParams(route.routeSegments ?? [], boundaryTreePosition, effectiveParams) : {},
+			layoutModules: route.layouts,
+			layoutTreePositions: route.layoutTreePositions,
+			parallelBranches: activeParallelRouteHeadInputs,
+			params: effectiveParams,
+			primaryParallelBranch: primaryParallelRouteHeadInput,
+			routeSegments: route.routeSegments ?? null
+		};
+	};
+	let viewportErrorOutlet = null;
+	let metadataErrorOutlet = null;
+	const resolveMetadataErrorTags = async (error) => {
+		if (resolveAppPageSpecialError(error)?.kind !== "http-access-fallback") return null;
+		return resolveHttpAccessFallbackMetadata({
+			applyFileBasedMetadata: options.applyFileBasedMetadata,
+			basePath: options.basePath ?? "",
+			...resolveNotFoundFallbackPlanOptions(),
+			metadataRoutes,
+			routePath: route.pattern
+		}).catch(() => null);
+	};
+	const [resolvedMetadata, resolvedViewport] = await Promise.all([shouldDeferMetadata ? Promise.resolve(null) : preparedHead.metadata.catch((error) => {
+		metadataErrorOutlet = Promise.reject(isProduction ? sanitizeErrorForClient(error, "production") : error);
+		metadataErrorOutlet.catch(() => null);
+		return resolveMetadataErrorTags(error);
+	}), preparedHead.viewport.catch(async (error) => {
+		const specialError = resolveAppPageSpecialError(error);
+		viewportErrorOutlet = Promise.reject(isProduction ? sanitizeErrorForClient(error, "production") : error);
+		viewportErrorOutlet.catch(() => null);
+		return specialError?.kind === "http-access-fallback" ? resolveHttpAccessFallbackViewport(resolveNotFoundFallbackPlanOptions()).catch(() => ({})) : {};
+	})]);
+	const streamingMetadataTags = shouldDeferMetadata ? preparedHead.metadata.catch(resolveMetadataErrorTags) : null;
+	const streamingMetadataOutletInputs = [
+		streamingMetadata,
+		metadataErrorOutlet,
+		viewportErrorOutlet
+	].filter((promise) => promise !== null).map((promise) => Promise.resolve(promise));
+	const streamingMetadataOutlet = streamingMetadataOutletInputs.length > 0 ? Promise.all(streamingMetadataOutletInputs).then(() => null) : null;
+	streamingMetadataOutlet?.catch(() => null);
 	const pageProps = { params: makeThenableParams(effectiveParams) };
 	const hasRequestSearchParams = Object.keys(pageSearchParams).length > 0;
 	const createPageElement = (PageComponent, props) => {
@@ -127,7 +209,6 @@ async function buildPageElements(options) {
 	const pageSearchParamsThenable = searchParams ? makeThenableParams(pageSearchParams) : void 0;
 	const mountedSlotIds = mountedSlotsHeader ? new Set(mountedSlotsHeader.split(" ")) : null;
 	const slotOverrides = buildSlotOverrides(route, params, routePath, opts);
-	const metadataPlacement = hasDynamicMetadata && (serveStreamingMetadata ?? shouldServeStreamingMetadata(pageRequest.request.headers.get("user-agent") ?? "", options.htmlLimitedBots)) ? "body" : "head";
 	let siblingInterceptElement = isSiblingIntercept && EffectivePageComponent ? createPageElement(EffectivePageComponent, pageProps) : null;
 	if (isSiblingIntercept && siblingInterceptElement !== null && opts?.interceptLayouts?.length) for (let i = opts.interceptLayouts.length - 1; i >= 0; i--) {
 		const LayoutComponent = opts.interceptLayouts[i]?.default;
@@ -149,6 +230,10 @@ async function buildPageElements(options) {
 		resolvedMetadata,
 		resolvedMetadataPathname: routePath,
 		resolvedViewport,
+		streamingMetadata,
+		streamingMetadataOutlet,
+		streamingMetadataOutletSuspended: streamGeneratedHead,
+		streamingMetadataTags,
 		renderIdentity,
 		routePath,
 		sourcePageSegments,
@@ -293,4 +378,4 @@ function collectParamNameSet(params) {
 	return set;
 }
 //#endregion
-export { buildPageElements, resolveAppPageNavigationParams, resolveInterceptedSlotSegments };
+export { buildPageElements, resolveAppPageNavigationParams, resolveInterceptedSlotSegments, resolveSlotParamOverrides };

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

@@ -8,6 +8,14 @@ import { applyFileBasedMetadata } from "./file-based-metadata.js";
 type AppPageSearchParams = Record<string, string | string[]>;
 type AppPageHeadModule = Record<string, unknown>;
 type ApplyAppPageFileBasedMetadata = typeof applyFileBasedMetadata;
+type OrderedAppPageMetadataSource<TModule extends AppPageHeadModule = AppPageHeadModule> = {
+  /** Preserve an empty result as the most specific file-metadata source. */includeWhenEmpty?: boolean;
+  module: TModule;
+  params: AppPageParams;
+  routeSegments: readonly string[];
+  searchParams?: AppPageSearchParams;
+  searchParamsObserver?: ThenableParamsObserver;
+};
 type AppPageHeadParallelRoute<TModule extends AppPageHeadModule = AppPageHeadModule> = {
   layoutParams?: readonly AppPageParams[] | null;
   layoutModule?: TModule | null;
@@ -17,11 +25,19 @@ type AppPageHeadParallelRoute<TModule extends AppPageHeadModule = AppPageHeadMod
   params?: AppPageParams | null;
   routeSegments?: readonly string[] | null;
 };
+type ActiveParallelRouteHeadInput<TModule extends AppPageHeadModule = AppPageHeadModule> = {
+  head: AppPageHeadParallelRoute<TModule>;
+  notFoundModule?: TModule | null;
+  notFoundParams?: AppPageParams | null;
+  ownerTreePosition: number;
+};
 type AppPageHeadSlot<TModule extends AppPageHeadModule = AppPageHeadModule> = {
   configLayouts?: readonly (TModule | null | undefined)[] | null;
   configLayoutTreePositions?: readonly number[] | null;
   layout?: TModule | null;
   layoutIndex?: number;
+  notFound?: TModule | null;
+  notFoundTreePosition?: number | null;
   page?: TModule | null;
   routeSegments?: readonly string[] | null;
 };
@@ -30,8 +46,12 @@ type ResolveActiveParallelRouteHeadInputsOptions<TModule extends AppPageHeadModu
   interceptBranchSegments?: readonly string[] | null;
   interceptLayoutSegments?: readonly (readonly string[])[] | null;
   interceptPage?: TModule | null;
+  interceptNotFoundBranchSegments?: readonly string[] | null;
+  interceptNotFound?: TModule | null;
+  interceptNotFoundTreePosition?: number | null;
   interceptParams?: AppPageParams | null;
   interceptSlotKey?: string | null;
+  interceptSourcePageSegments?: readonly string[] | null;
   layoutTreePositions?: readonly number[] | null;
   params: AppPageParams;
   routeSegments: readonly string[];
@@ -59,6 +79,18 @@ type ResolveAppPageHeadOptions<TModule extends AppPageHeadModule = AppPageHeadMo
   searchParams?: URLSearchParams | null;
   searchParamsObserver?: ThenableParamsObserver;
 };
+type AppPageMetadataOutputOptions = {
+  applyFileBasedMetadata?: ApplyAppPageFileBasedMetadata;
+  basePath?: string;
+  fallbackOnFileMetadataError?: boolean;
+  metadataRoutes: readonly MetadataFileRoute[];
+  params: AppPageParams;
+  routePath: string;
+  routeSegments?: readonly string[] | null;
+};
+type ResolveOrderedAppPageMetadataOptions<TModule extends AppPageHeadModule = AppPageHeadModule> = AppPageMetadataOutputOptions & {
+  sources: readonly OrderedAppPageMetadataSource<TModule>[];
+};
 type ResolveAppPageHeadResult = {
   hasDynamicMetadata: boolean;
   hasSearchParams: boolean;
@@ -66,12 +98,32 @@ type ResolveAppPageHeadResult = {
   pageSearchParams: AppPageSearchParams;
   viewport: Viewport;
 };
+type PreparedAppPageHead = Omit<ResolveAppPageHeadResult, "metadata" | "viewport"> & {
+  metadata: Promise<Metadata | null>;
+  viewport: Promise<Viewport>;
+};
 type AppPageSearchParamsCollection = {
   hasSearchParams: boolean;
   pageSearchParams: AppPageSearchParams;
 };
-declare function resolveActiveParallelRouteHeadInputs<TModule extends AppPageHeadModule>(options: ResolveActiveParallelRouteHeadInputsOptions<TModule>): AppPageHeadParallelRoute<TModule>[];
+declare function resolveActiveParallelRouteHeadInputs<TModule extends AppPageHeadModule>(options: ResolveActiveParallelRouteHeadInputsOptions<TModule>): ActiveParallelRouteHeadInput<TModule>[];
 declare function collectAppPageSearchParams(searchParams: URLSearchParams | null | undefined): AppPageSearchParamsCollection;
+/**
+ * Resolve an explicit metadata-source sequence.
+ *
+ * Route-specific conventions own source selection and ordering. This resolver
+ * only supplies each source with its accumulated parent, merges the results,
+ * and applies file-based metadata at the end.
+ */
+declare function resolveOrderedAppPageMetadata<TModule extends AppPageHeadModule>(options: ResolveOrderedAppPageMetadataOptions<TModule>): Promise<Metadata | null>;
 declare function resolveAppPageHead<TModule extends AppPageHeadModule>(options: ResolveAppPageHeadOptions<TModule>): Promise<ResolveAppPageHeadResult>;
+/**
+ * Start metadata and viewport resolution without coupling their completion.
+ *
+ * Live document renders can place the metadata promise behind Suspense while
+ * still waiting for viewport tags before the shell is emitted. Blocking
+ * callers use {@link resolveAppPageHead} and observe the same result as before.
+ */
+declare function prepareAppPageHead<TModule extends AppPageHeadModule>(options: ResolveAppPageHeadOptions<TModule>): PreparedAppPageHead;
 //#endregion
-export { AppPageSearchParams, ApplyAppPageFileBasedMetadata, collectAppPageSearchParams, resolveActiveParallelRouteHeadInputs, resolveAppPageHead };
+export { ActiveParallelRouteHeadInput, AppPageHeadModule, AppPageHeadParallelRoute, AppPageSearchParams, ApplyAppPageFileBasedMetadata, OrderedAppPageMetadataSource, PreparedAppPageHead, ResolveAppPageHeadResult, ResolveOrderedAppPageMetadataOptions, collectAppPageSearchParams, prepareAppPageHead, resolveActiveParallelRouteHeadInputs, resolveAppPageHead, resolveOrderedAppPageMetadata };

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

@@ -26,33 +26,58 @@ function resolveActiveParallelRouteHeadInputs(options) {
 	return Object.entries(options.slots ?? {}).map(([slotKey, slot]) => {
 		const ownerTreePosition = options.layoutTreePositions?.[slot.layoutIndex ?? 0] ?? 0;
 		const ownerParams = resolveAppPageSegmentParams(options.routeSegments, ownerTreePosition, options.params);
+		const slotParams = options.slotParams?.[slotKey] ?? options.params;
+		const notFoundParams = slot.notFound ? {
+			...ownerParams,
+			...resolveParallelLayoutParams(slot.routeSegments ?? options.routeSegments, slot.notFoundTreePosition ?? 0, slotParams)
+		} : null;
 		if (options.interceptSlotKey === slotKey && options.interceptPage) {
 			const interceptLayouts = options.interceptLayouts ?? [];
+			const inheritedSlotNotFound = slot.notFoundTreePosition === 0 ? slot.notFound ?? null : null;
+			const interceptNotFound = options.interceptNotFound ?? inheritedSlotNotFound;
+			const interceptNotFoundParams = interceptNotFound ? {
+				...ownerParams,
+				...resolveParallelLayoutParams(options.interceptNotFoundBranchSegments ?? options.interceptBranchSegments ?? options.routeSegments, options.interceptNotFound ? options.interceptNotFoundTreePosition ?? 0 : slot.notFoundTreePosition ?? 0, options.interceptParams ?? options.params)
+			} : null;
 			return {
-				layoutModules: [slot.layout, ...interceptLayouts].filter(isPresent),
-				layoutParams: [...slot.layout ? [ownerParams] : [], ...interceptLayouts.filter(isPresent).map((_, index) => {
-					const segments = options.interceptLayoutSegments?.[index] ?? [];
-					return {
-						...ownerParams,
-						...resolveParallelLayoutParams(options.interceptBranchSegments ?? segments, segments.length, options.interceptParams ?? options.params)
-					};
-				})],
-				layoutTreePositions: [...slot.layout ? [0] : [], ...interceptLayouts.filter(isPresent).map(() => options.routeSegments.length)],
-				pageModule: options.interceptPage,
-				params: options.interceptParams ?? options.params,
-				routeSegments: options.routeSegments
+				head: {
+					layoutModules: [slot.layout, ...interceptLayouts].filter(isPresent),
+					layoutParams: [...slot.layout ? [ownerParams] : [], ...interceptLayouts.filter(isPresent).map((_, index) => {
+						const segments = options.interceptLayoutSegments?.[index] ?? [];
+						return {
+							...ownerParams,
+							...resolveParallelLayoutParams(options.interceptBranchSegments ?? segments, segments.length, options.interceptParams ?? options.params)
+						};
+					})],
+					layoutTreePositions: [...slot.layout ? [0] : [], ...interceptLayouts.filter(isPresent).map(() => options.routeSegments.length)],
+					pageModule: options.interceptPage,
+					params: options.interceptParams ?? options.params,
+					routeSegments: options.interceptSourcePageSegments ?? options.routeSegments
+				},
+				...interceptNotFound ? {
+					notFoundModule: interceptNotFound,
+					notFoundParams: interceptNotFoundParams
+				} : {},
+				ownerTreePosition
 			};
 		}
 		return {
-			layoutModules: [slot.layout, ...slot.configLayouts ?? []].filter(isPresent),
-			layoutParams: [...slot.layout ? [ownerParams] : [], ...(slot.configLayoutTreePositions ?? []).map((treePosition) => ({
-				...ownerParams,
-				...resolveParallelLayoutParams(slot.routeSegments ?? options.routeSegments, treePosition, options.slotParams?.[slotKey] ?? options.params)
-			}))],
-			layoutTreePositions: [...slot.layout ? [0] : [], ...slot.configLayoutTreePositions ?? []],
-			pageModule: slot.page,
-			params: options.slotParams?.[slotKey] ?? options.params,
-			routeSegments: slot.routeSegments ?? options.routeSegments
+			head: {
+				layoutModules: [slot.layout, ...slot.configLayouts ?? []].filter(isPresent),
+				layoutParams: [...slot.layout ? [ownerParams] : [], ...(slot.configLayoutTreePositions ?? []).map((treePosition) => ({
+					...ownerParams,
+					...resolveParallelLayoutParams(slot.routeSegments ?? options.routeSegments, treePosition, options.slotParams?.[slotKey] ?? options.params)
+				}))],
+				layoutTreePositions: [...slot.layout ? [0] : [], ...slot.configLayoutTreePositions ?? []],
+				pageModule: slot.page,
+				params: slotParams,
+				routeSegments: slot.routeSegments ?? options.routeSegments
+			},
+			...slot.notFound ? {
+				notFoundModule: slot.notFound,
+				notFoundParams
+			} : {},
+			ownerTreePosition
 		};
 	});
 }
@@ -97,6 +122,20 @@ function createMetadataSources(metadataResults, routeSegments, layoutTreePositio
 	});
 	return metadataSources;
 }
+async function finalizeAppPageMetadata(metadata, metadataSources, options) {
+	let resolvedMetadata = metadata;
+	if (options.applyFileBasedMetadata && options.metadataRoutes.length > 0) try {
+		resolvedMetadata = await options.applyFileBasedMetadata(metadata, options.routePath, options.params, options.metadataRoutes, {
+			routeSegments: options.routeSegments ?? [],
+			metadataSources,
+			basePath: options.basePath ?? ""
+		});
+	} catch (error) {
+		if (!options.fallbackOnFileMetadataError) throw error;
+		console.error(`[vinext] File-based metadata resolution failed while rendering error boundary for ${options.routePath}:`, error);
+	}
+	return resolvedMetadata ? postProcessMetadata(resolvedMetadata) : null;
+}
 function createLayoutInputs(layoutModules, layoutTreePositions) {
 	const layoutInputs = [];
 	for (let index = 0; index < layoutModules.length; index++) {
@@ -132,21 +171,21 @@ async function resolveLayoutViewport(layoutInputs, params, routeSegments) {
 		return resolveModuleViewport(layoutInput.module, layoutParams);
 	}));
 }
-async function resolveParallelRouteHead(parallelRoute, fallbackParams, fallbackRouteSegments, pageSearchParams, parent, searchParamsObserver) {
+function getParallelRouteModules(parallelRoute) {
+	return [...parallelRoute.layoutModules ?? [], parallelRoute.layoutModule].filter(isPresent);
+}
+function parallelRouteHasDynamicMetadata(parallelRoute) {
+	return getParallelRouteModules(parallelRoute).some(hasGenerateMetadata) || hasGenerateMetadata(parallelRoute.pageModule);
+}
+async function resolveParallelRouteMetadata(parallelRoute, fallbackParams, fallbackRouteSegments, pageSearchParams, parent, searchParamsObserver) {
 	const params = parallelRoute.params ?? fallbackParams;
 	const routeSegments = parallelRoute.routeSegments ?? fallbackRouteSegments;
 	const metadataResults = [];
-	const viewportResults = [];
 	const metadataSources = [];
 	let accumulatedMetadata = parent;
-	const layoutModules = [...parallelRoute.layoutModules ?? [], parallelRoute.layoutModule].filter(isPresent);
+	const layoutModules = getParallelRouteModules(parallelRoute);
 	const layoutTreePositions = parallelRoute.layoutTreePositions ?? [];
 	const layoutParams = parallelRoute.layoutParams ?? [];
-	const hasDynamicMetadata = layoutModules.some(hasGenerateMetadata) || hasGenerateMetadata(parallelRoute.pageModule);
-	const layoutViewportPromises = layoutModules.map((layoutModule, index) => resolveModuleViewport(layoutModule, layoutParams[index] ?? resolveParallelLayoutParams(routeSegments, layoutTreePositions[index] ?? 0, params)));
-	const pageViewportPromise = parallelRoute.pageModule ? resolveModuleViewport(parallelRoute.pageModule, params, pageSearchParams, searchParamsObserver) : Promise.resolve(null);
-	for (const layoutViewportPromise of layoutViewportPromises) layoutViewportPromise.catch(() => null);
-	pageViewportPromise.catch(() => null);
 	for (const [index, layoutModule] of layoutModules.entries()) {
 		const layoutMetadata = await resolveModuleMetadata(layoutModule, layoutParams[index] ?? resolveParallelLayoutParams(routeSegments, layoutTreePositions[index] ?? 0, params), void 0, accumulatedMetadata);
 		metadataResults.push(layoutMetadata);
@@ -167,20 +206,72 @@ async function resolveParallelRouteHead(parallelRoute, fallbackParams, fallbackR
 			routeSegments
 		});
 	}
-	viewportResults.push(...await Promise.all(layoutViewportPromises));
-	const pageViewport = await pageViewportPromise;
-	if (parallelRoute.pageModule) viewportResults.push(pageViewport);
 	return {
-		hasDynamicMetadata,
 		metadataResults,
-		metadataSources,
-		viewportResults
+		metadataSources
 	};
 }
+async function resolveParallelRouteViewport(parallelRoute, fallbackParams, fallbackRouteSegments, pageSearchParams, searchParamsObserver) {
+	const params = parallelRoute.params ?? fallbackParams;
+	const routeSegments = parallelRoute.routeSegments ?? fallbackRouteSegments;
+	const layoutModules = getParallelRouteModules(parallelRoute);
+	const layoutTreePositions = parallelRoute.layoutTreePositions ?? [];
+	const layoutParams = parallelRoute.layoutParams ?? [];
+	const layoutViewportPromise = Promise.all(layoutModules.map((layoutModule, index) => resolveModuleViewport(layoutModule, layoutParams[index] ?? resolveParallelLayoutParams(routeSegments, layoutTreePositions[index] ?? 0, params))));
+	const pageViewportPromise = parallelRoute.pageModule ? resolveModuleViewport(parallelRoute.pageModule, params, pageSearchParams, searchParamsObserver) : Promise.resolve(null);
+	const [layoutViewports, pageViewport] = await Promise.all([layoutViewportPromise, pageViewportPromise]);
+	return parallelRoute.pageModule ? [...layoutViewports, pageViewport] : layoutViewports;
+}
+/**
+* Resolve an explicit metadata-source sequence.
+*
+* Route-specific conventions own source selection and ordering. This resolver
+* only supplies each source with its accumulated parent, merges the results,
+* and applies file-based metadata at the end.
+*/
+function resolveOrderedAppPageMetadata(options) {
+	return runWithFetchDedupe(async () => {
+		const metadataPromises = [];
+		let accumulatedEntriesPromise = Promise.resolve([]);
+		for (const source of options.sources) {
+			const parentPromise = accumulatedEntriesPromise.then((entries) => entries.length > 0 ? mergeMetadataEntries(entries) : {});
+			const metadataPromise = resolveModuleMetadata(source.module, source.params, source.searchParams, parentPromise, source.searchParamsObserver);
+			metadataPromises.push(metadataPromise);
+			metadataPromise.catch(() => null);
+			accumulatedEntriesPromise = Promise.all([accumulatedEntriesPromise, metadataPromise]).then(([entries, metadata]) => metadata ? [...entries, { metadata }] : entries);
+			accumulatedEntriesPromise.catch(() => null);
+		}
+		const [metadataEntries, metadataResults] = await Promise.all([accumulatedEntriesPromise, Promise.all(metadataPromises)]);
+		const metadataSources = options.sources.flatMap((source, index) => {
+			const metadata = metadataResults[index] ?? null;
+			return metadata || source.includeWhenEmpty ? [{
+				metadata,
+				routeSegments: source.routeSegments
+			}] : [];
+		});
+		return finalizeAppPageMetadata(metadataEntries.length > 0 ? mergeMetadataEntries(metadataEntries) : null, metadataSources, options);
+	});
+}
 async function resolveAppPageHead(options) {
-	return await runWithFetchDedupe(() => resolveAppPageHeadInner(options));
+	const prepared = prepareAppPageHead(options);
+	const [metadata, viewport] = await Promise.all([prepared.metadata, prepared.viewport]);
+	return {
+		...prepared,
+		metadata,
+		viewport
+	};
+}
+/**
+* Start metadata and viewport resolution without coupling their completion.
+*
+* Live document renders can place the metadata promise behind Suspense while
+* still waiting for viewport tags before the shell is emitted. Blocking
+* callers use {@link resolveAppPageHead} and observe the same result as before.
+*/
+function prepareAppPageHead(options) {
+	return runWithFetchDedupe(() => prepareAppPageHeadInner(options));
 }
-async function resolveAppPageHeadInner(options) {
+function prepareAppPageHeadInner(options) {
 	const routeSegments = options.routeSegments ?? [];
 	const layoutTreePositions = options.layoutTreePositions ?? [];
 	const layoutInputs = createLayoutInputs(options.layoutModules, layoutTreePositions);
@@ -195,57 +286,52 @@ async function resolveAppPageHeadInner(options) {
 	pageParentPromise.catch(() => null);
 	const pageMetadataPromise = options.pageModule ? resolveModuleMetadata(options.pageModule, options.params, pageSearchParams, pageParentPromise, options.searchParamsObserver) : Promise.resolve(null);
 	const pageViewportPromise = options.pageModule ? resolveModuleViewport(options.pageModule, options.params, pageSearchParams, options.searchParamsObserver) : Promise.resolve(null);
-	const parallelRouteHeadPromise = Promise.all((options.parallelRoutes ?? []).map((parallelRoute) => resolveParallelRouteHead(parallelRoute, options.params, routeSegments, pageSearchParams, pageParentPromise, options.searchParamsObserver)));
-	const [layoutMetadataResults, layoutViewportResults, pageMetadata, pageViewport, parallelRouteHeads] = await Promise.all([
+	const parallelRoutes = options.parallelRoutes ?? [];
+	const parallelRouteMetadataPromise = Promise.all(parallelRoutes.map((parallelRoute) => resolveParallelRouteMetadata(parallelRoute, options.params, routeSegments, pageSearchParams, pageParentPromise, options.searchParamsObserver)));
+	const parallelRouteViewportPromise = Promise.all(parallelRoutes.map((parallelRoute) => resolveParallelRouteViewport(parallelRoute, options.params, routeSegments, pageSearchParams, options.searchParamsObserver)));
+	const hasDynamicMetadata = primaryHasDynamicMetadata || parallelRoutes.some(parallelRouteHasDynamicMetadata);
+	const metadata = Promise.all([
 		layoutMetadataPromise,
-		layoutViewportPromise,
 		pageMetadataPromise,
+		parallelRouteMetadataPromise
+	]).then(async ([layoutMetadataResults, pageMetadata, parallelRouteMetadata]) => {
+		const parallelMetadataResults = parallelRouteMetadata.flatMap((head) => head.metadataResults);
+		const parallelMetadataSources = parallelRouteMetadata.flatMap((head) => head.metadataSources);
+		const primaryPageHasTitle = pageMetadata != null && pageMetadata.title !== void 0;
+		const metadataEntries = [
+			...layoutMetadataResults.filter(isPresent).map((entry) => ({ metadata: entry })),
+			...pageMetadata ? [{
+				isPage: true,
+				metadata: pageMetadata
+			}] : [],
+			...parallelMetadataResults.filter(isPresent).map((entry) => ({
+				contributesTitle: !primaryPageHasTitle,
+				metadata: entry
+			}))
+		];
+		const resolvedMetadataBase = metadataEntries.length > 0 ? mergeMetadataEntries(metadataEntries) : null;
+		const metadataSources = createMetadataSources(layoutMetadataResults, routeSegments, layoutSourcePositions, pageMetadata, Boolean(options.pageModule));
+		metadataSources.push(...parallelMetadataSources);
+		return finalizeAppPageMetadata(resolvedMetadataBase, metadataSources, options);
+	});
+	const viewport = Promise.all([
+		layoutViewportPromise,
 		pageViewportPromise,
-		parallelRouteHeadPromise
-	]);
-	const parallelMetadataResults = parallelRouteHeads.flatMap((head) => head.metadataResults);
-	const parallelViewportResults = parallelRouteHeads.flatMap((head) => head.viewportResults);
-	const parallelMetadataSources = parallelRouteHeads.flatMap((head) => head.metadataSources);
-	const hasDynamicMetadata = primaryHasDynamicMetadata || parallelRouteHeads.some((head) => head.hasDynamicMetadata);
-	const primaryPageHasTitle = pageMetadata != null && pageMetadata.title !== void 0;
-	const metadataEntries = [
-		...layoutMetadataResults.filter(isPresent).map((metadata) => ({ metadata })),
-		...pageMetadata ? [{
-			isPage: true,
-			metadata: pageMetadata
-		}] : [],
-		...parallelMetadataResults.filter(isPresent).map((metadata) => ({
-			contributesTitle: !primaryPageHasTitle,
-			metadata
-		}))
-	];
-	const viewportList = [
+		parallelRouteViewportPromise
+	]).then(([layoutViewportResults, pageViewport, parallelRouteViewports]) => mergeViewport([
 		...layoutViewportResults.filter(isPresent),
 		...pageViewport ? [pageViewport] : [],
-		...parallelViewportResults.filter(isPresent)
-	];
-	const resolvedMetadataBase = metadataEntries.length > 0 ? mergeMetadataEntries(metadataEntries) : null;
-	const metadataSources = createMetadataSources(layoutMetadataResults, routeSegments, layoutSourcePositions, pageMetadata, Boolean(options.pageModule));
-	metadataSources.push(...parallelMetadataSources);
-	let metadata = resolvedMetadataBase;
-	if (options.applyFileBasedMetadata && options.metadataRoutes.length > 0) try {
-		metadata = await options.applyFileBasedMetadata(resolvedMetadataBase, options.routePath, options.params, options.metadataRoutes, {
-			routeSegments,
-			metadataSources,
-			basePath: options.basePath ?? ""
-		});
-	} catch (error) {
-		if (!options.fallbackOnFileMetadataError) throw error;
-		console.error(`[vinext] File-based metadata resolution failed while rendering error boundary for ${options.routePath}:`, error);
-	}
-	if (metadata) metadata = postProcessMetadata(metadata);
+		...parallelRouteViewports.flat().filter(isPresent)
+	]));
+	metadata.catch(() => null);
+	viewport.catch(() => null);
 	return {
 		hasDynamicMetadata,
 		hasSearchParams,
 		metadata,
 		pageSearchParams,
-		viewport: mergeViewport(viewportList)
+		viewport
 	};
 }
 //#endregion
-export { collectAppPageSearchParams, resolveActiveParallelRouteHeadInputs, resolveAppPageHead };
+export { collectAppPageSearchParams, prepareAppPageHead, resolveActiveParallelRouteHeadInputs, resolveAppPageHead, resolveOrderedAppPageMetadata };

package/dist/server/app-page-http-access-fallback-metadata.d.ts

@@ -0,0 +1,29 @@
+import { MetadataFileRoute } from "./metadata-routes.js";
+import { AppPageParams } from "./app-page-boundary.js";
+import { Metadata, Viewport } from "../shims/metadata.js";
+import { ActiveParallelRouteHeadInput, AppPageHeadModule, ApplyAppPageFileBasedMetadata, OrderedAppPageMetadataSource } from "./app-page-head.js";
+
+//#region src/server/app-page-http-access-fallback-metadata.d.ts
+type HttpAccessFallbackMetadataPlanOptions<TModule extends AppPageHeadModule = AppPageHeadModule> = {
+  boundaryModule?: TModule | null;
+  boundaryParams: AppPageParams; /** Whether active branches may replace the fallback with their local not-found convention. */
+  branchNotFoundConventions?: boolean;
+  layoutModules: readonly (TModule | null | undefined)[];
+  layoutTreePositions?: readonly number[] | null;
+  parallelBranches?: readonly ActiveParallelRouteHeadInput<TModule>[] | null;
+  params: AppPageParams;
+  primaryParallelBranch?: ActiveParallelRouteHeadInput<TModule> | null;
+  routeSegments?: readonly string[] | null;
+};
+type ResolveHttpAccessFallbackMetadataOptions<TModule extends AppPageHeadModule = AppPageHeadModule> = HttpAccessFallbackMetadataPlanOptions<TModule> & {
+  applyFileBasedMetadata?: ApplyAppPageFileBasedMetadata;
+  basePath?: string;
+  fallbackOnFileMetadataError?: boolean;
+  metadataRoutes: readonly MetadataFileRoute[];
+  routePath: string;
+};
+declare function createHttpAccessFallbackMetadataPlan<TModule extends AppPageHeadModule>(options: HttpAccessFallbackMetadataPlanOptions<TModule>): OrderedAppPageMetadataSource<TModule>[];
+declare function resolveHttpAccessFallbackMetadata<TModule extends AppPageHeadModule>(options: ResolveHttpAccessFallbackMetadataOptions<TModule>): Promise<Metadata | null>;
+declare function resolveHttpAccessFallbackViewport<TModule extends AppPageHeadModule>(options: HttpAccessFallbackMetadataPlanOptions<TModule>): Promise<Viewport>;
+//#endregion
+export { createHttpAccessFallbackMetadataPlan, resolveHttpAccessFallbackMetadata, resolveHttpAccessFallbackViewport };