vinext 1.0.0-beta.0 → 1.0.0-beta.2

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

@@ -4,12 +4,16 @@ 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 { DEFAULT_GLOBAL_ERROR_MODULE } from "./default-global-error-module.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 { createElement } from "react";
 //#region src/server/app-page-element-builder.ts
@@ -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 } = 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 && 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-execution.d.ts

@@ -6,6 +6,7 @@ type AppPageSpecialError = {
   kind: "redirect";
   location: string;
   statusCode: number;
+  type?: "push" | "replace";
   fromMetadata?: boolean;
 } | {
   kind: "http-access-fallback";
@@ -132,7 +133,8 @@ declare function probeAppPageLayouts(options: ProbeAppPageLayoutsOptions): Promi
 declare function probeAppPageComponent(options: ProbeAppPageComponentOptions): Promise<Response | null>;
 declare function probeAppPageThrownError(options: ProbeAppPageThrownErrorOptions): Promise<unknown>;
 declare function readAppPageBinaryStream(stream: ReadableStream<Uint8Array>): Promise<ArrayBuffer>;
+declare function bufferAppPageBinaryStream(stream: ReadableStream<Uint8Array>): Promise<ReadableStream<Uint8Array>>;
 declare function teeAppPageRscStreamForCapture(stream: ReadableStream<Uint8Array>, shouldCapture: boolean): AppPageRscStreamCapture;
 declare function buildAppPageFontLinkHeader(preloads: readonly AppPageFontPreload[] | null | undefined): string;
 //#endregion
-export { AppPageFontPreload, AppPageSpecialError, LayoutClassificationOptions, type LayoutFlags, buildAppPageFontLinkHeader, buildAppPageSpecialErrorResponse, probeAppPageComponent, probeAppPageLayouts, probeAppPageThrownError, readAppPageBinaryStream, resolveAppPageSpecialError, tagAppPageMetadataError, teeAppPageRscStreamForCapture };
+export { AppPageFontPreload, AppPageSpecialError, LayoutClassificationOptions, type LayoutFlags, bufferAppPageBinaryStream, buildAppPageFontLinkHeader, buildAppPageSpecialErrorResponse, probeAppPageComponent, probeAppPageLayouts, probeAppPageThrownError, readAppPageBinaryStream, resolveAppPageSpecialError, tagAppPageMetadataError, teeAppPageRscStreamForCapture };

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

@@ -1,5 +1,4 @@
-import { addBasePathToPathname } from "../utils/base-path.js";
-import { VINEXT_RSC_REDIRECT_HEADER } from "./headers.js";
+import { VINEXT_RSC_REDIRECT_HEADER, VINEXT_RSC_REDIRECT_TYPE_HEADER } from "./headers.js";
 import { runWithConnectionProbe } from "../shims/headers.js";
 import { VINEXT_RSC_CONTENT_TYPE, applyRscCompatibilityIdHeader, applyRscDeploymentIdHeader, createRscRedirectLocation } from "./app-rsc-cache-busting.js";
 import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
@@ -7,28 +6,9 @@ import { applyEdgeRuntimeHeader } from "./app-page-response.js";
 import { parseNextHttpErrorDigest, parseNextRedirectDigest } from "./next-error-digest.js";
 import { renderSsrErrorMetaTags } from "./app-ssr-error-meta.js";
 import { isPromiseLike } from "../utils/promise.js";
+import { formatNextRedirectDigest } from "./app-rsc-redirect-flight.js";
 //#region src/server/app-page-execution.ts
 /**
-* Builds the canonical `NEXT_REDIRECT;<type>;<url>;<status>;` digest that
-* Next.js encodes on `redirect()` / `permanentRedirect()` throws. Used when
-* we synthesize a flight payload for an RSC navigation: the digest must
-* round-trip through the client's `RedirectErrorBoundary` so the same
-* `getURLFromRedirectError` / `getRedirectTypeFromError` helpers decode it.
-*
-* The URL is included verbatim, not encoded — Next.js's `getRedirectError`
-* sets `digest = ${CODE};${type};${url};${status};` with the raw URL, and the
-* client decodes via `error.digest.split(';').slice(2, -2).join(';')`. We
-* default `type=replace` because `redirect()` is replace-style outside of
-* server actions, matching Next.js's `getRedirectError` default.
-*
-* Reference:
-*   `.nextjs-ref/packages/next/src/client/components/redirect.ts:20-23`
-*   `.nextjs-ref/packages/next/src/client/components/redirect-error.ts`
-*/
-function formatNextRedirectDigest(options) {
-	return `NEXT_REDIRECT;replace;${options.url};${options.statusCode};`;
-}
-/**
 * Marker we tag onto a thrown redirect/notFound error when it originates from
 * `generateMetadata()` (vs. a server component itself). Metadata resolution is
 * suspended/streamed in Next.js, so a redirect from metadata is not emitted as
@@ -73,12 +53,13 @@ function mergeAppPageSpecialErrorHeaders(response, middlewareContext) {
 function resolveAppPageSpecialError(error) {
 	if (!(error && typeof error === "object" && "digest" in error)) return null;
 	const digest = String(error.digest);
-	const fromMetadata = error[APP_PAGE_METADATA_ERROR_MARKER] === true;
+	const fromMetadata = Reflect.get(error, APP_PAGE_METADATA_ERROR_MARKER) === true;
 	const redirect = parseNextRedirectDigest(digest);
 	if (redirect) return {
 		kind: "redirect",
 		location: redirect.url,
 		statusCode: redirect.status,
+		type: redirect.type === "push" ? "push" : "replace",
 		...fromMetadata ? { fromMetadata: true } : {}
 	};
 	const httpError = parseNextHttpErrorDigest(digest);
@@ -97,17 +78,15 @@ function resolveAppPageSpecialError(error) {
 * in `app-render.tsx`: a `redirect("/about")` call from a page mounted at
 * `/blog` (basePath) produces `Location: /blog/about`.
 *
-* Skips prefixing when:
-*  - basePath is unset / empty
-*  - the target is a full URL pointing at a different origin (external redirect)
-*  - the target already starts with the basePath (caller did the work themselves)
+* Skips prefixing only when basePath is unset or the raw target does not start
+* with `/`, matching Next.js's literal `addPathPrefix()` contract.
 */
-function applyAppPageRedirectBasePath(location, requestUrl, basePath) {
-	const resolved = new URL(location, requestUrl);
-	const requestOrigin = new URL(requestUrl).origin;
-	if (!basePath || resolved.origin !== requestOrigin) return resolved.toString();
-	resolved.pathname = addBasePathToPathname(resolved.pathname, basePath);
-	return resolved.toString();
+function applyAppPageRedirectBasePath(location, basePath) {
+	if (!basePath || !location.startsWith("/")) return location;
+	const queryIndex = location.indexOf("?");
+	const hashIndex = location.indexOf("#");
+	const suffixIndex = queryIndex === -1 ? hashIndex : hashIndex === -1 ? queryIndex : Math.min(queryIndex, hashIndex);
+	return `${basePath}${suffixIndex === -1 ? location : location.slice(0, suffixIndex)}${suffixIndex === -1 ? "" : location.slice(suffixIndex)}`;
 }
 /**
 * Returns a path-relative form (`/foo?bar`) of an absolute URL when it shares
@@ -141,9 +120,10 @@ function buildMetadataRedirectHtmlResponse(options) {
 async function buildAppPageSpecialErrorResponse(options) {
 	if (options.specialError.kind === "redirect") {
 		options.clearRequestContext();
-		const prefixedLocation = applyAppPageRedirectBasePath(options.specialError.location, options.request.url, options.basePath);
+		const prefixedLocation = applyAppPageRedirectBasePath(options.specialError.location, options.basePath);
 		const digestUrl = sameOriginPathOrAbsolute(prefixedLocation, options.request.url);
 		const digest = formatNextRedirectDigest({
+			type: options.specialError.type ?? "replace",
 			url: digestUrl,
 			statusCode: options.specialError.statusCode
 		});
@@ -155,14 +135,13 @@ async function buildAppPageSpecialErrorResponse(options) {
 		});
 		if (Boolean(options.buildRscRedirectFlightStream) && options.isRscRequest && options.buildRscRedirectFlightStream) {
 			const stream = options.buildRscRedirectFlightStream({ digest });
-			const headers = new Headers({
-				"Content-Type": VINEXT_RSC_CONTENT_TYPE,
-				[VINEXT_RSC_REDIRECT_HEADER]: digestUrl
-			});
+			const headers = new Headers({ "Content-Type": VINEXT_RSC_CONTENT_TYPE });
 			applyEdgeRuntimeHeader(headers, options.isEdgeRuntime);
 			applyRscCompatibilityIdHeader(headers);
 			applyRscDeploymentIdHeader(headers);
 			mergeMiddlewareResponseHeaders(headers, options.middlewareContext?.headers ?? null);
+			headers.set(VINEXT_RSC_REDIRECT_HEADER, digestUrl);
+			headers.set(VINEXT_RSC_REDIRECT_TYPE_HEADER, options.specialError.type ?? "replace");
 			const pendingCookies = options.getAndClearPendingCookies?.() ?? [];
 			for (const cookie of pendingCookies) headers.append("Set-Cookie", cookie);
 			return new Response(stream, {
@@ -313,6 +292,19 @@ async function readAppPageBinaryStream(stream) {
 	}
 	return buffer.buffer;
 }
+async function bufferAppPageBinaryStream(stream) {
+	const reader = stream.getReader();
+	const chunks = [];
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		chunks.push(value);
+	}
+	return new ReadableStream({ start(controller) {
+		for (const chunk of chunks) controller.enqueue(chunk);
+		controller.close();
+	} });
+}
 function teeAppPageRscStreamForCapture(stream, shouldCapture) {
 	if (!shouldCapture) return { ssrStream: stream };
 	const [ssrStream, sideStream] = stream.tee();
@@ -326,4 +318,4 @@ function buildAppPageFontLinkHeader(preloads) {
 	return preloads.map((preload) => `<${preload.href}>; rel=preload; as=font; type=${preload.type}; crossorigin`).join(", ");
 }
 //#endregion
-export { buildAppPageFontLinkHeader, buildAppPageSpecialErrorResponse, probeAppPageComponent, probeAppPageLayouts, probeAppPageThrownError, readAppPageBinaryStream, resolveAppPageSpecialError, tagAppPageMetadataError, teeAppPageRscStreamForCapture };
+export { bufferAppPageBinaryStream, buildAppPageFontLinkHeader, buildAppPageSpecialErrorResponse, probeAppPageComponent, probeAppPageLayouts, probeAppPageThrownError, readAppPageBinaryStream, resolveAppPageSpecialError, tagAppPageMetadataError, teeAppPageRscStreamForCapture };

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 };