vinext 0.1.2 → 0.1.3

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

@@ -24,6 +24,7 @@ type AppPageInterceptOptions<TModule extends AppPageModule = AppPageModule> = {
   interceptSlotId?: string | null;
   interceptSlotKey?: string | null;
   interceptSourceMatchedUrl?: string | null;
+  interceptSourcePageSegments?: readonly string[] | null;
 };
 type AppPagePageRequest<TModule extends AppPageModule = AppPageModule> = {
   /** Interception context from current-route navigation (null for direct visits). */opts?: AppPageInterceptOptions<TModule> | null; /** URL search params from the incoming request (null when unavailable). */

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

@@ -6,7 +6,7 @@ import { createAppPageRenderIdentity } from "./app-page-render-identity.js";
 import { makeThenableParams } from "../shims/thenable-params.js";
 import { resolveActiveParallelRouteHeadInputs, resolveAppPageHead } from "./app-page-head.js";
 import { makeObservedAppPageSearchParamsThenable } from "./app-page-search-params-observation.js";
-import { buildAppPageElements, createAppPageTreePath } from "./app-page-route-wiring.js";
+import { buildAppPageElements, createAppPageSourcePage, createAppPageTreePath } from "./app-page-route-wiring.js";
 import { DEFAULT_GLOBAL_ERROR_MODULE } from "./default-global-error-module.js";
 import "./app-rsc-route-matching.js";
 import { shouldServeStreamingMetadata } from "./streaming-metadata.js";
@@ -36,6 +36,7 @@ async function buildPageElements(options) {
 	const effectivePageModule = isSiblingIntercept ? opts.interceptPage : pageModule;
 	const EffectivePageComponent = effectivePageModule?.default;
 	const effectiveParams = isSiblingIntercept ? opts.interceptParams ?? params : params;
+	const sourcePageSegments = isSiblingIntercept ? opts?.interceptSourcePageSegments : route.routeSegments;
 	const hasPageModule = !!pageModule;
 	const renderIdentity = createAppPageRenderIdentity({
 		displayPathname,
@@ -56,7 +57,8 @@ async function buildPageElements(options) {
 				interceptionContext: renderIdentity.interceptionContext,
 				layoutIds: noExportLayoutIds,
 				rootLayoutTreePath: noExportRootLayout,
-				routeId: renderIdentity.routeId
+				routeId: renderIdentity.routeId,
+				sourcePage: createAppPageSourcePage(sourcePageSegments)
 			}),
 			[renderIdentity.routeId]: createElement("div", null, "Page has no default export")
 		};
@@ -112,6 +114,7 @@ async function buildPageElements(options) {
 		resolvedViewport,
 		renderIdentity,
 		routePath,
+		sourcePageSegments,
 		rootNotFoundModule: rootNotFoundModule ?? null,
 		rootForbiddenModule: rootForbiddenModule ?? null,
 		rootUnauthorizedModule: rootUnauthorizedModule ?? null,

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

@@ -121,13 +121,18 @@ type ProbeAppPageComponentOptions = {
   probePage: () => unknown;
   runWithSuppressedHookWarning<T>(probe: () => Promise<T>): Promise<T>;
 };
+type ProbeAppPageThrownErrorOptions = {
+  probePage: () => unknown;
+  runWithSuppressedHookWarning<T>(probe: () => Promise<T>): Promise<T>;
+};
 declare function resolveAppPageSpecialError(error: unknown): AppPageSpecialError | null;
 declare function buildAppPageSpecialErrorResponse(options: BuildAppPageSpecialErrorResponseOptions): Promise<Response>;
 /** See `LayoutFlags` type docblock in app-elements.ts for lifecycle. */
 declare function probeAppPageLayouts(options: ProbeAppPageLayoutsOptions): Promise<ProbeAppPageLayoutsResult>;
 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 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, readAppPageBinaryStream, resolveAppPageSpecialError, tagAppPageMetadataError, teeAppPageRscStreamForCapture };
+export { AppPageFontPreload, AppPageSpecialError, LayoutClassificationOptions, type LayoutFlags, buildAppPageFontLinkHeader, buildAppPageSpecialErrorResponse, probeAppPageComponent, probeAppPageLayouts, probeAppPageThrownError, readAppPageBinaryStream, resolveAppPageSpecialError, tagAppPageMetadataError, teeAppPageRscStreamForCapture };

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

@@ -274,6 +274,26 @@ async function probeAppPageComponent(options) {
 		return outcome.completed ? outcome.result : null;
 	});
 }
+async function probeAppPageThrownError(options) {
+	return options.runWithSuppressedHookWarning(async () => {
+		const outcome = await runWithConnectionProbe(async () => {
+			try {
+				const pageResult = options.probePage();
+				if (isPromiseLike(pageResult)) await pageResult;
+			} catch (error) {
+				return {
+					error,
+					thrown: true
+				};
+			}
+			return {
+				error: null,
+				thrown: false
+			};
+		});
+		return outcome.completed && outcome.result.thrown ? outcome.result.error : null;
+	});
+}
 async function readAppPageBinaryStream(stream) {
 	const reader = stream.getReader();
 	const chunks = [];
@@ -305,4 +325,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, readAppPageBinaryStream, resolveAppPageSpecialError, tagAppPageMetadataError, teeAppPageRscStreamForCapture };
+export { buildAppPageFontLinkHeader, buildAppPageSpecialErrorResponse, probeAppPageComponent, probeAppPageLayouts, probeAppPageThrownError, readAppPageBinaryStream, resolveAppPageSpecialError, tagAppPageMetadataError, teeAppPageRscStreamForCapture };

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

@@ -119,6 +119,7 @@ type ProbeAppPageBeforeRenderResult = {
 };
 type ProbeAppPageBeforeRenderOptions = {
   hasLoadingBoundary: boolean;
+  skipProbes?: boolean;
   layoutCount: number;
   probeLayoutAt: (layoutIndex: number) => unknown;
   probePage: () => unknown;

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

@@ -227,6 +227,10 @@ function buildAppPageProbes(options) {
 }
 async function probeAppPageBeforeRender(options) {
 	let layoutFlags = {};
+	if (options.skipProbes) return {
+		response: null,
+		layoutFlags
+	};
 	if (options.layoutCount > 0) {
 		const layoutProbeResult = await probeAppPageLayouts({
 			layoutCount: options.layoutCount,

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

@@ -7,6 +7,8 @@ type AppPageRenderObservationState = Readonly<{
   requestApis: readonly RenderRequestApiKind[];
 }>;
 declare function createEmptyAppPageRenderObservationState(): AppPageRenderObservationState;
+declare function consumeAppPageRenderObservationState(): AppPageRenderObservationState;
+declare function discardAppPageRenderState(): void;
 declare function createAppPageRenderObservation(options: {
   boundaryOutcome: BoundaryOutcome;
   cacheTags: readonly string[];
@@ -31,4 +33,4 @@ declare function createAppPageHtmlOutputScope(options: {
   routePattern: string;
 }): CacheProofOutputScope;
 //#endregion
-export { AppPageRenderObservationState, createAppPageHtmlOutputScope, createAppPageRenderObservation, createAppPageRscOutputScope, createEmptyAppPageRenderObservationState };
+export { AppPageRenderObservationState, consumeAppPageRenderObservationState, createAppPageHtmlOutputScope, createAppPageRenderObservation, createAppPageRscOutputScope, createEmptyAppPageRenderObservationState, discardAppPageRenderState };

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

@@ -1,7 +1,10 @@
+import { consumeDynamicUsage, consumeInvalidDynamicUsageError, consumeRenderRequestApiUsage } from "../shims/headers.js";
 import { fnv1a64 } from "../utils/hash.js";
+import { _consumeRequestScopedCacheLife } from "../shims/cache.js";
 import { AppElementsWire, isAppElementsRecord } from "./app-elements-wire.js";
 import { normalizeMountedSlotsHeader } from "./app-mounted-slots-header.js";
 import "./app-elements.js";
+import { consumeDynamicFetchObservations } from "../shims/fetch-cache.js";
 import { buildRenderObservation, buildRenderRequestApiObservations } from "./cache-proof.js";
 //#region src/server/app-page-render-observation.ts
 function readRootBoundaryId(element) {
@@ -30,6 +33,19 @@ function createEmptyAppPageRenderObservationState() {
 		requestApis: []
 	};
 }
+function consumeAppPageRenderObservationState() {
+	return {
+		dynamicFetches: consumeDynamicFetchObservations(),
+		requestApis: consumeRenderRequestApiUsage()
+	};
+}
+function discardAppPageRenderState() {
+	_consumeRequestScopedCacheLife();
+	consumeDynamicFetchObservations();
+	consumeRenderRequestApiUsage();
+	consumeInvalidDynamicUsageError();
+	consumeDynamicUsage();
+}
 function createAppPageRenderObservation(options) {
 	return buildRenderObservation({
 		boundaryOutcome: options.boundaryOutcome,
@@ -63,4 +79,4 @@ function createAppPageHtmlOutputScope(options) {
 	};
 }
 //#endregion
-export { createAppPageHtmlOutputScope, createAppPageRenderObservation, createAppPageRscOutputScope, createEmptyAppPageRenderObservationState };
+export { consumeAppPageRenderObservationState, createAppPageHtmlOutputScope, createAppPageRenderObservation, createAppPageRscOutputScope, createEmptyAppPageRenderObservationState, discardAppPageRenderState };

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

@@ -7,8 +7,8 @@ import { AppPageMiddlewareContext } from "./app-page-response.js";
 import { RootParams } from "../shims/root-params.js";
 import { AppPageSsrHandler } from "./app-page-stream.js";
 import { AppLayoutParamAccessTracker } from "./app-layout-param-observation.js";
-import { AppRscRenderMode } from "./app-rsc-render-mode.js";
 import { AppPageRenderObservationState } from "./app-page-render-observation.js";
+import { AppRscRenderMode } from "./app-rsc-render-mode.js";
 import { ReactNode } from "react";
 import { ReactFormState } from "react-dom/client";
 
@@ -49,6 +49,7 @@ type RenderAppPageLifecycleOptions = {
   peekRequestCacheLife?: () => AppPageRequestCacheLife | null;
   getDraftModeCookieHeader: () => string | null | undefined;
   handlerStart: number;
+  hasCustomGlobalError?: boolean;
   hasLoadingBoundary: boolean;
   dynamicStaleTimeSeconds?: number;
   isDynamicError: boolean;
@@ -70,6 +71,9 @@ type RenderAppPageLifecycleOptions = {
   middlewareContext: AppPageMiddlewareContext;
   navigationParams: Record<string, unknown>;
   params: Record<string, unknown>;
+  pprFallbackShellSignal?: AbortSignal;
+  pprFallbackShellReactSignal?: AbortSignal;
+  abortPprFallbackShell?: () => void;
   rootParams?: RootParams;
   peekRenderObservationState?: () => AppPageRenderObservationState;
   probeLayoutAt: (layoutIndex: number) => unknown;
@@ -82,7 +86,14 @@ type RenderAppPageLifecycleOptions = {
   renderPageSpecialError: (specialError: AppPageSpecialError) => Promise<Response>;
   renderToReadableStream: (element: ReactNode | AppOutgoingElements, options: {
     onError: AppPageBoundaryOnError;
+    signal?: AbortSignal;
   }) => ReadableStream<Uint8Array>;
+  prerenderToReadableStream?: (element: ReactNode | AppOutgoingElements, options: {
+    onError: AppPageBoundaryOnError;
+    signal?: AbortSignal;
+  }) => Promise<{
+    prelude: ReadableStream<Uint8Array>;
+  }>;
   routePattern: string;
   runWithSuppressedHookWarning<T>(probe: () => Promise<T>): Promise<T>;
   scriptNonce?: string;

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

@@ -1,4 +1,4 @@
-import { NO_STORE_CACHE_CONTROL } from "./cache-control.js";
+import { NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL, applyCdnResponseHeaders } from "./cache-control.js";
 import { createArtifactCompatibilityEnvelope, createArtifactCompatibilityGraphVersion } from "./artifact-compatibility.js";
 import { AppElementsWire, isAppElementsRecord } from "./app-elements-wire.js";
 import "./app-elements.js";
@@ -249,6 +249,7 @@ function wrapRscResponseForDevErrorReporting(response, consumeInvalidDynamicUsag
 async function renderAppPageLifecycle(options) {
 	const preRenderResult = await probeAppPageBeforeRender({
 		hasLoadingBoundary: options.hasLoadingBoundary,
+		skipProbes: options.pprFallbackShellSignal !== void 0,
 		layoutCount: options.layoutCount,
 		probeLayoutAt(layoutIndex) {
 			return options.probeLayoutAt(layoutIndex);
@@ -315,11 +316,31 @@ async function renderAppPageLifecycle(options) {
 	});
 	const compileEnd = options.isProduction ? void 0 : performance.now();
 	const rscErrorTracker = createAppPageRscErrorTracker(options.createRscOnErrorHandler(options.cleanPathname, options.routePattern));
-	const rscStream = runWithFetchDedupe(() => options.renderToReadableStream(outgoingElement, { onError: rscErrorTracker.onRenderError }));
+	let rscStream = await runWithFetchDedupe(async () => {
+		if (options.pprFallbackShellSignal && options.prerenderToReadableStream) {
+			const reactSignal = options.pprFallbackShellReactSignal ?? options.pprFallbackShellSignal;
+			const pendingResult = options.prerenderToReadableStream(outgoingElement, {
+				onError: rscErrorTracker.onRenderError,
+				signal: reactSignal
+			});
+			if (options.abortPprFallbackShell) setTimeout(options.abortPprFallbackShell, 0);
+			return (await pendingResult).prelude;
+		}
+		return options.renderToReadableStream(outgoingElement, { onError: rscErrorTracker.onRenderError });
+	});
+	let pprFallbackShellRsc = null;
+	if (options.pprFallbackShellSignal) pprFallbackShellRsc = new Uint8Array(await readAppPageBinaryStream(rscStream));
 	let revalidateSeconds = options.revalidateSeconds;
 	let expireSeconds = options.expireSeconds;
 	const shouldCaptureRscForCacheMetadata = options.isProgressiveActionRender !== true && (options.isProduction || options.isPrerender === true) && (revalidateSeconds === null || revalidateSeconds > 0 && revalidateSeconds !== Infinity) && !options.isDraftMode && !options.isForceDynamic && !shouldBypassRscCacheForSkipTransport;
-	const rscCapture = teeAppPageRscStreamForCapture(rscStream, shouldCaptureRscForCacheMetadata);
+	const createBufferedRscStream = (close) => new ReadableStream({ start(controller) {
+		if (pprFallbackShellRsc) controller.enqueue(pprFallbackShellRsc);
+		if (close) controller.close();
+	} });
+	const rscCapture = pprFallbackShellRsc ? {
+		ssrStream: createBufferedRscStream(false),
+		...shouldCaptureRscForCacheMetadata ? { sideStream: createBufferedRscStream(true) } : {}
+	} : teeAppPageRscStreamForCapture(rscStream, shouldCaptureRscForCacheMetadata);
 	const rscForResponse = rscCapture.ssrStream;
 	const capturedRscDataRef = { value: null };
 	if (rscCapture.sideStream && options.isRscRequest) capturedRscDataRef.value = readAppPageBinaryStream(rscCapture.sideStream);
@@ -415,17 +436,19 @@ async function renderAppPageLifecycle(options) {
 			return renderAppPageHtmlStream({
 				capturedRscDataRef,
 				fontData,
+				hasCustomGlobalError: options.hasCustomGlobalError,
 				navigationContext: options.getNavigationContext(),
 				basePath: options.basePath,
 				clientTraceMetadata: options.clientTraceMetadata,
 				reactMaxHeadersLength: options.reactMaxHeadersLength,
 				rootParams: options.rootParams,
+				pprFallbackShellSignal: options.pprFallbackShellSignal,
 				formState: options.formState ?? null,
 				rscStream: rscForResponse,
 				scriptNonce: options.scriptNonce,
 				sideStream: rscCapture.sideStream,
 				ssrHandler,
-				waitForAllReady: options.isPrerender
+				waitForAllReady: options.isPrerender === true
 			});
 		},
 		renderSpecialErrorResponse(specialError) {
@@ -482,6 +505,21 @@ async function renderAppPageLifecycle(options) {
 		renderEnd,
 		responseKind: "html"
 	});
+	if (htmlRender.shellErrorRecovered) {
+		const response = buildAppPageHtmlResponse(safeHtmlStream, {
+			draftCookie,
+			linkHeader,
+			isEdgeRuntime: options.isEdgeRuntime,
+			middlewareContext: {
+				headers: options.middlewareContext.headers,
+				status: 500
+			},
+			policy: { cacheControl: NEVER_CACHE_CONTROL },
+			timing: htmlResponseTiming
+		});
+		applyCdnResponseHeaders(response.headers, { cacheControl: NEVER_CACHE_CONTROL });
+		return response;
+	}
 	const shouldSpeculativelyWriteCache = options.isProduction && shouldCaptureRscForCacheMetadata && revalidateSeconds === null && !options.isDynamicError && !options.isForceStatic && !options.scriptNonce && options.isProgressiveActionRender !== true && !dynamicUsedDuringRender;
 	if (htmlResponsePolicy.shouldWriteToCache || shouldSpeculativelyWriteCache) {
 		const isrResponse = buildAppPageHtmlResponse(safeHtmlStream, {

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

@@ -29,6 +29,7 @@ type ResolveAppPageGenerateStaticParamsSourcesOptions = {
 };
 type BuildAppPageElementOptions<TElement> = {
   buildPageElement: () => Promise<TElement>;
+  probePageSpecialError?: () => Promise<AppPageSpecialError | null>;
   renderErrorBoundaryPage: (error: unknown) => Promise<Response | null>;
   renderSpecialError: (specialError: AppPageSpecialError) => Promise<Response>;
   resolveSpecialError: (error: unknown) => AppPageSpecialError | null;
@@ -44,6 +45,7 @@ type AppPageInterceptMatch<TPage = unknown> = {
   slotId?: string | null;
   slotKey: string;
   sourceRouteIndex: number;
+  sourcePageSegments?: readonly string[] | null;
 };
 type ResolveAppPageInterceptMatchOptions<TRoute, TPage, TInterceptOpts> = {
   cleanPathname: string;

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

@@ -180,7 +180,8 @@ async function buildAppPageElement(options) {
 			response: null
 		};
 	} catch (error) {
-		const specialError = options.resolveSpecialError(error);
+		const buildSpecialError = options.resolveSpecialError(error);
+		const specialError = (buildSpecialError ? await options.probePageSpecialError?.() : null) ?? buildSpecialError;
 		if (specialError) return {
 			element: null,
 			response: await options.renderSpecialError(specialError)

package/dist/server/app-page-route-wiring.d.ts

@@ -130,6 +130,7 @@ type BuildAppPageElementsOptions<TModule extends AppPageModule = AppPageModule,
   renderIdentity?: AppPageRenderIdentity;
   renderMode?: AppRscRenderMode;
   routePath: string;
+  sourcePageSegments?: readonly string[] | null;
 };
 declare function createAppPageTreePath(routeSegments: readonly string[] | null | undefined, treePosition: number): string;
 declare function probeAppPageLayoutWithTracking<TModule extends AppPageModule>(options: {
@@ -143,7 +144,8 @@ declare function createAppPageLayoutEntries<TModule extends AppPageModule, TErro
   forbiddens?: readonly (TModule | null | undefined)[] | null;
   unauthorizeds?: readonly (TModule | null | undefined)[] | null;
 }): AppPageLayoutEntry<TModule, TErrorModule>[];
+declare function createAppPageSourcePage(routeSegments: readonly string[] | null | undefined): string;
 declare function createAppPageRouteBodyMetadata(metadata: Metadata | null, pathname: string, metadataPlacement: "body" | "head", trailingSlash?: boolean): ReactNode;
 declare function buildAppPageElements<TModule extends AppPageModule, TErrorModule extends AppPageErrorModule>(options: BuildAppPageElementsOptions<TModule, TErrorModule>): AppElements;
 //#endregion
-export { AppPageErrorModule, AppPageModule, AppPageRouteWiringRoute, AppPageSlotOverride, buildAppPageElements, createAppPageLayoutEntries, createAppPageRouteBodyMetadata, createAppPageTreePath, probeAppPageLayoutWithTracking, resolveAppPageChildSegments };
+export { AppPageErrorModule, AppPageModule, AppPageRouteWiringRoute, AppPageSlotOverride, buildAppPageElements, createAppPageLayoutEntries, createAppPageRouteBodyMetadata, createAppPageSourcePage, createAppPageTreePath, probeAppPageLayoutWithTracking, resolveAppPageChildSegments };

package/dist/server/app-page-route-wiring.js

@@ -2,7 +2,8 @@ import { createAppRenderDependency, registerAppElementRenderDependencies, render
 import { APP_STATIC_SIBLINGS_KEY, AppElementsWire, normalizeAppElementsSlotBindings } from "./app-elements-wire.js";
 import { APP_RSC_RENDER_MODE_PREFETCH_LOADING_SHELL, shouldSuppressLoadingBoundaries } from "./app-rsc-render-mode.js";
 import { APP_PREFETCH_LOADING_SHELL_MARKER_KEY } from "./app-elements.js";
-import { ErrorBoundary, ForbiddenBoundary, NotFoundBoundary, RedirectBoundary, UnauthorizedBoundary } from "../shims/error-boundary.js";
+import DefaultGlobalError from "../shims/default-global-error.js";
+import { ErrorBoundary, ForbiddenBoundary, GlobalErrorBoundary, NotFoundBoundary, RedirectBoundary, UnauthorizedBoundary } from "../shims/error-boundary.js";
 import { AppRouterScrollTarget } from "../shims/app-router-scroll.js";
 import { LayoutSegmentProvider } from "../shims/layout-segment-context.js";
 import { MetadataHead, ViewportHead, renderMetadataToHtml } from "../shims/metadata.js";
@@ -14,6 +15,7 @@ import { Fragment, Suspense } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/server/app-page-route-wiring.tsx
 const APP_PAGE_LAYOUT_PROBE_CHILD = /* @__PURE__ */ jsx(Fragment, {});
+const DEFAULT_GLOBAL_ERROR_COMPONENT = DefaultGlobalError;
 function getDefaultExport(module) {
 	return module?.default ?? null;
 }
@@ -85,6 +87,9 @@ function createAppPageTemplateEntries(route) {
 		};
 	});
 }
+function createAppPageSourcePage(routeSegments) {
+	return `/${[...routeSegments ?? [], "page"].join("/")}`;
+}
 function createAppPageErrorEntries(route) {
 	return (route.errorPaths ?? route.errors ?? []).flatMap((errorModule, index) => {
 		if (!errorModule) return [];
@@ -206,6 +211,7 @@ function buildAppPageElements(options) {
 		layoutIds: options.route.ids?.layouts ?? layoutEntries.map((entry) => entry.id),
 		rootLayoutTreePath,
 		routeId,
+		sourcePage: createAppPageSourcePage(options.sourcePageSegments ?? routeSegments),
 		slotBindings: createAppPageSlotBindings(options.route, layoutEntries, resolveSlotOverride, {
 			interception: renderIdentity?.interception ?? options.interception ?? null,
 			interceptionContext,
@@ -427,9 +433,12 @@ function buildAppPageElements(options) {
 		});
 	}
 	const globalErrorComponent = getErrorBoundaryExport(options.globalErrorModule);
-	if (globalErrorComponent) routeChildren = /* @__PURE__ */ jsx(ErrorBoundary, {
-		fallback: globalErrorComponent,
-		children: routeChildren
+	routeChildren = /* @__PURE__ */ jsx(GlobalErrorBoundary, {
+		fallback: DEFAULT_GLOBAL_ERROR_COMPONENT,
+		children: globalErrorComponent ? /* @__PURE__ */ jsx(ErrorBoundary, {
+			fallback: globalErrorComponent,
+			children: routeChildren
+		}) : routeChildren
 	});
 	elements[routeId] = /* @__PURE__ */ jsxs(Fragment$1, { children: [
 		createAppPageRouteHead(options.resolvedMetadata, options.resolvedViewport, options.resolvedMetadataPathname ?? options.routePath, metadataPlacement, options.trailingSlash),
@@ -440,4 +449,4 @@ function buildAppPageElements(options) {
 	return elements;
 }
 //#endregion
-export { buildAppPageElements, createAppPageLayoutEntries, createAppPageRouteBodyMetadata, createAppPageTreePath, probeAppPageLayoutWithTracking, resolveAppPageChildSegments };
+export { buildAppPageElements, createAppPageLayoutEntries, createAppPageRouteBodyMetadata, createAppPageSourcePage, createAppPageTreePath, probeAppPageLayoutWithTracking, resolveAppPageChildSegments };

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

@@ -18,6 +18,7 @@ type AppSsrRenderResult = {
   htmlStream: ReadableStream<Uint8Array>;
   metadataReady: Promise<void>;
   capturedRscData: Promise<ArrayBuffer> | null;
+  shellErrorRecovered?: boolean;
   /**
    * Preload `Link` header value emitted by React during SSR (via `onHeaders`),
    * already capped to `reactMaxHeadersLength`. Empty/undefined when React
@@ -62,9 +63,14 @@ type AppPageSsrHandler = {
     sideStream?: ReadableStream<Uint8Array>;
     capturedRscDataRef?: {
       value: Promise<ArrayBuffer> | null;
-    }; /** When true, wait for the full React tree before emitting bytes. */
+    }; /** Abort signal for a build-time PPR fallback-shell static render. */
+    pprFallbackShellSignal?: AbortSignal; /** When true, wait for the full React tree before emitting bytes. */
     waitForAllReady?: boolean; /** Dev-only: original server error to surface in the browser overlay. */
     initialDevServerError?: unknown;
+    /** When true, an SSR-phase-only shell render error resolves to the
+     *  default `__next_error__` error-document shell (with the original
+     *  flight payload and bootstrap) instead of rejecting. See handleSsr. */
+    fallbackToErrorDocumentOnShellError?: boolean;
   }) => Promise<ReadableStream<Uint8Array> | AppSsrRenderResult>;
 };
 type RenderAppPageHtmlStreamOptions = {
@@ -93,9 +99,14 @@ type RenderAppPageHtmlStreamOptions = {
   sideStream?: ReadableStream<Uint8Array>; /** Out-parameter filled with accumulated raw RSC bytes after stream consumption. */
   capturedRscDataRef?: {
     value: Promise<ArrayBuffer> | null;
-  }; /** When true, wait for the full React tree before emitting bytes. */
+  }; /** Abort signal for a build-time PPR fallback-shell static render. */
+  pprFallbackShellSignal?: AbortSignal; /** When true, wait for the full React tree before emitting bytes. */
   waitForAllReady?: boolean; /** Dev-only: original server error to surface in the browser overlay. */
   initialDevServerError?: unknown;
+  /** True when the app supplies a custom global-error.tsx. Disables the
+   *  default error-document shell fallback so SSR shell errors keep driving
+   *  the server-rendered global-error boundary re-render. */
+  hasCustomGlobalError?: boolean;
 };
 type RenderAppPageHtmlResponseOptions = {
   clearRequestContext: () => void;
@@ -108,7 +119,8 @@ type AppPageHtmlStreamRecoveryResult = {
   htmlStream: ReadableStream<Uint8Array> | null;
   response: Response | null;
   metadataReady: Promise<void>;
-  capturedRscData: Promise<ArrayBuffer> | null; /** React-emitted preload `Link` header (already capped). */
+  capturedRscData: Promise<ArrayBuffer> | null;
+  shellErrorRecovered: boolean; /** React-emitted preload `Link` header (already capped). */
   linkHeader?: string;
 };
 type RenderAppPageHtmlStreamWithRecoveryOptions<TSpecialError> = {

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

@@ -11,7 +11,8 @@ function normalizeAppSsrRenderResult(raw, fallbackCapturedRscData = null) {
 	return {
 		htmlStream: raw,
 		metadataReady: resolvedMetadataReady,
-		capturedRscData: fallbackCapturedRscData
+		capturedRscData: fallbackCapturedRscData,
+		shellErrorRecovered: false
 	};
 }
 /**
@@ -62,8 +63,10 @@ async function renderAppPageHtmlStream(options) {
 		rootParams: options.rootParams,
 		sideStream: options.sideStream,
 		capturedRscDataRef: options.capturedRscDataRef,
+		pprFallbackShellSignal: options.pprFallbackShellSignal,
 		waitForAllReady: options.waitForAllReady,
-		initialDevServerError: options.initialDevServerError
+		initialDevServerError: options.initialDevServerError,
+		fallbackToErrorDocumentOnShellError: options.waitForAllReady !== true && options.hasCustomGlobalError === false
 	};
 	return normalizeAppSsrRenderResult(await options.ssrHandler.handleSsr(options.rscStream, options.navigationContext, options.fontData, ssrOptions), options.capturedRscDataRef?.value ?? null);
 }
@@ -121,13 +124,14 @@ async function renderAppPageHtmlResponse(options) {
 }
 async function renderAppPageHtmlStreamWithRecovery(options) {
 	try {
-		const { htmlStream, metadataReady, capturedRscData, linkHeader } = normalizeAppSsrRenderResult(await options.renderHtmlStream());
+		const { htmlStream, metadataReady, capturedRscData, linkHeader, shellErrorRecovered } = normalizeAppSsrRenderResult(await options.renderHtmlStream());
 		options.onShellRendered?.();
 		return {
 			htmlStream,
 			response: null,
 			metadataReady,
 			capturedRscData,
+			shellErrorRecovered: shellErrorRecovered === true,
 			linkHeader
 		};
 	} catch (error) {
@@ -136,14 +140,16 @@ async function renderAppPageHtmlStreamWithRecovery(options) {
 			htmlStream: null,
 			response: await options.renderSpecialErrorResponse(specialError),
 			metadataReady: resolvedMetadataReady,
-			capturedRscData: null
+			capturedRscData: null,
+			shellErrorRecovered: false
 		};
 		const boundaryResponse = await options.renderErrorBoundaryResponse(error);
 		if (boundaryResponse) return {
 			htmlStream: null,
 			response: boundaryResponse,
 			metadataReady: resolvedMetadataReady,
-			capturedRscData: null
+			capturedRscData: null,
+			shellErrorRecovered: false
 		};
 		throw error;
 	}

package/dist/server/app-pages-bridge.d.ts

@@ -3,8 +3,22 @@ import { AppMiddlewareContext } from "./app-middleware.js";
 //#region src/server/app-pages-bridge.d.ts
 type PagesEntry = {
   handleApiRoute?: (request: Request, url: string) => Promise<Response> | Response;
+  matchApiRoute?: (url: string, request: Request) => PagesRouteMatch | null;
+  matchPageRoute?: (url: string, request: Request) => PagesRouteMatch | null;
   renderPage?: (request: Request, url: string, query: Record<string, unknown>, parsedUrl: unknown, middlewareRequestHeaders?: Headers | null) => Promise<Response> | Response;
 };
+type PagesRouteMatch = {
+  route: {
+    isDynamic: boolean;
+    pattern: string;
+  };
+};
+type AppRouteMatch = {
+  route: {
+    isDynamic: boolean;
+    pattern: string;
+  };
+};
 type RenderPagesFallbackDependencies = {
   loadPagesEntry: () => Promise<PagesEntry> | PagesEntry;
   buildRequestHeaders: (requestHeaders: Headers, middlewareRequestHeaders: Headers) => Headers | null;
@@ -28,8 +42,12 @@ type RenderPagesFallbackDependencies = {
   getDraftModeCookieHeader: () => string | null | undefined;
 };
 type RenderPagesFallbackOptions = {
+  allowRscDocumentFallback?: boolean;
+  appRouteMatch?: AppRouteMatch | null;
   isRscRequest: boolean;
+  matchKind?: "dynamic" | "static";
   middlewareContext: AppMiddlewareContext;
+  pathname?: string;
   request: Request;
   url: URL;
 };

package/dist/server/app-pages-bridge.js

@@ -1,11 +1,12 @@
+import { pagesRouteHasPriorityOverAppRoute } from "./hybrid-route-priority.js";
 //#region src/server/app-pages-bridge.ts
 /**
 * Fallback handler to route App Router requests to the Pages Router when no App Router route matches.
 */
 async function renderPagesFallback(options, dependencies) {
-	const { isRscRequest, middlewareContext, request, url } = options;
+	const { allowRscDocumentFallback = false, appRouteMatch = null, isRscRequest, matchKind, middlewareContext, pathname = options.url.pathname, request, url } = options;
 	const { loadPagesEntry, buildRequestHeaders, decodePathParams, applyRouteHandlerMiddlewareContext, getDraftModeCookieHeader } = dependencies;
-	if (isRscRequest) return null;
+	if (isRscRequest && !allowRscDocumentFallback) return null;
 	const pagesEntry = await loadPagesEntry();
 	const pagesRequestHeaders = middlewareContext.requestHeaders ? buildRequestHeaders(request.headers, middlewareContext.requestHeaders) : null;
 	let pagesRequest = request;
@@ -20,17 +21,33 @@ async function renderPagesFallback(options, dependencies) {
 		}
 		pagesRequest = new Request(request.url, pagesRequestInit);
 	}
-	const pagesUrl = decodePathParams(url.pathname) + (url.search || "");
-	const pagesPathname = url.pathname;
+	const queryIndex = pathname.indexOf("?");
+	const pagesPathname = queryIndex === -1 ? pathname : pathname.slice(0, queryIndex);
+	const pagesSearch = queryIndex === -1 ? url.search || "" : pathname.slice(queryIndex);
+	const pagesUrl = decodePathParams(pagesPathname) + pagesSearch;
 	if (pagesPathname.startsWith("/api/") || pagesPathname === "/api") {
 		if (typeof pagesEntry.handleApiRoute !== "function") return null;
+		const hasApiMatcher = typeof pagesEntry.matchApiRoute === "function";
+		const apiMatch = hasApiMatcher ? pagesEntry.matchApiRoute?.(pagesUrl, pagesRequest) ?? null : null;
+		if (hasApiMatcher && apiMatch === null) return null;
+		if (apiMatch !== null && matchKind === "static" && apiMatch.route.isDynamic) return null;
+		if (apiMatch !== null && matchKind === "dynamic" && !apiMatch.route.isDynamic) return null;
+		if (appRouteMatch !== null) {
+			if (apiMatch === null || !pagesRouteHasPriorityOverAppRoute(apiMatch.route, appRouteMatch.route)) return null;
+		}
 		const pagesApiResponse = await pagesEntry.handleApiRoute(pagesRequest, pagesUrl);
 		const draftCookie = getDraftModeCookieHeader();
 		return applyDraftModeCookie(applyRouteHandlerMiddlewareContext(pagesApiResponse, middlewareContext), draftCookie);
 	}
 	if (typeof pagesEntry.renderPage !== "function") return null;
+	const hasPageMatcher = typeof pagesEntry.matchPageRoute === "function";
+	const pageMatch = hasPageMatcher ? pagesEntry.matchPageRoute?.(pagesUrl, pagesRequest) ?? null : null;
+	if (hasPageMatcher && pageMatch === null) return null;
+	if (pageMatch !== null && matchKind === "static" && pageMatch.route.isDynamic) return null;
+	if (pageMatch !== null && matchKind === "dynamic" && !pageMatch.route.isDynamic) return null;
+	if (appRouteMatch !== null && (pageMatch === null || !pagesRouteHasPriorityOverAppRoute(pageMatch.route, appRouteMatch.route))) return null;
 	const pagesRes = await pagesEntry.renderPage(pagesRequest, pagesUrl, {}, void 0, middlewareContext.requestHeaders);
-	if (pagesRes.status === 404) return null;
+	if (pagesRes.status === 404 && pageMatch === null) return null;
 	return applyDraftModeCookie(pagesRes, getDraftModeCookieHeader());
 }
 /**

package/dist/server/app-ppr-fallback-shell-render.d.ts

@@ -0,0 +1,17 @@
+import { PprFallbackShellState } from "../shims/ppr-fallback-shell.js";
+import { ReactNode } from "react";
+
+//#region src/server/app-ppr-fallback-shell-render.d.ts
+type AppPageBoundaryOnError = (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
+type AppPageRenderableElement = ReactNode | Record<string, ReactNode>;
+declare function warmPprFallbackShellCaches(options: {
+  element: AppPageRenderableElement;
+  onError: AppPageBoundaryOnError;
+  renderToReadableStream: (element: AppPageRenderableElement, options: {
+    onError: AppPageBoundaryOnError;
+    signal?: AbortSignal;
+  }) => ReadableStream<Uint8Array>;
+  state: PprFallbackShellState;
+}): Promise<void>;
+//#endregion
+export { warmPprFallbackShellCaches };