vinext 1.0.0-beta.9 → 1.0.0

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

@@ -1,11 +1,12 @@
-import { consumeDynamicUsage, consumeInvalidDynamicUsageError } from "../shims/headers.js";
+import { consumeDynamicUsage, consumeInvalidDynamicUsageError, isRenderDynamicLatched } from "../shims/headers.js";
 import { _consumeRequestScopedCacheLife } from "../shims/cache-request-state.js";
 import { getCollectedFetchTags } from "../shims/fetch-cache.js";
 import { readStreamAsText } from "../utils/text-stream.js";
 import { buildAppPageFontLinkHeader, teeAppPageRscStreamForCapture } from "./app-page-execution.js";
+import { recordAppPageRenderError, traceAppPageRender } from "./app-page-tracing.js";
 import { buildAppPageTags } from "./implicit-tags.js";
 import { consumeAppPageRenderObservationState, createAppPageHtmlOutputScope, createAppPageRenderObservation, createAppPageRscOutputScope } from "./app-page-render-observation.js";
-import { buildAppPageLinkHeader, isAppSsrRenderResult } from "./app-page-stream.js";
+import { buildAppPageLinkHeader, createAppPageSsrErrorHandler, isAppSsrRenderResult } from "./app-page-stream.js";
 //#region src/server/app-page-cache-render.ts
 /**
 * Render an App page element to HTML (and optionally its RSC payload) for cache
@@ -14,7 +15,14 @@ import { buildAppPageLinkHeader, isAppSsrRenderResult } from "./app-page-stream.
 * shell regeneration.
 */
 async function renderAppPageCacheArtifacts(options) {
-	const rscCapture = teeAppPageRscStreamForCapture(options.renderToReadableStream(options.element, { onError: options.onError }), options.captureRscData);
+	return traceAppPageRender(options.route.pattern, "prerender", (renderSpan) => renderAppPageCacheArtifactsImpl(options, renderSpan));
+}
+async function renderAppPageCacheArtifactsImpl(options, renderSpan) {
+	const rscStream = options.renderToReadableStream(options.element, { onError(error, requestInfo, errorContext) {
+		recordAppPageRenderError(renderSpan, error);
+		return options.onError(error, requestInfo, errorContext);
+	} });
+	const rscCapture = teeAppPageRscStreamForCapture(rscStream, options.captureRscData);
 	const capturedRscDataRef = { value: null };
 	const fontPreloads = options.getFontPreloads();
 	const htmlResult = await (await options.loadSsrHandler()).handleSsr(rscCapture.ssrStream, options.getNavigationContext(), {
@@ -29,13 +37,21 @@ async function renderAppPageCacheArtifacts(options) {
 		waitForAllReady: options.waitForAllReady,
 		isStaticGeneration: true,
 		isForceStatic: options.isForceStatic,
+		onSsrError: options.onSsrError && options.isCapturedRscError ? createAppPageSsrErrorHandler((error) => {
+			recordAppPageRenderError(renderSpan, error);
+			return options.onSsrError?.(error);
+		}, options.isCapturedRscError) : options.onSsrError ? (error) => {
+			recordAppPageRenderError(renderSpan, error);
+			return options.onSsrError?.(error);
+		} : void 0,
 		...rscCapture.sideStream ? {
 			sideStream: rscCapture.sideStream,
 			capturedRscDataRef
 		} : {}
 	});
 	const htmlStream = isAppSsrRenderResult(htmlResult) ? htmlResult.htmlStream : htmlResult;
-	const linkHeader = buildAppPageLinkHeader(isAppSsrRenderResult(htmlResult) ? htmlResult.linkHeader : void 0, buildAppPageFontLinkHeader(fontPreloads), options.reactMaxHeadersLength);
+	const reactLinkHeader = isAppSsrRenderResult(htmlResult) ? htmlResult.linkHeader : void 0;
+	const linkHeader = buildAppPageLinkHeader(reactLinkHeader, buildAppPageFontLinkHeader(fontPreloads), options.reactMaxHeadersLength);
 	const html = await readStreamAsText(htmlStream);
 	let rscData;
 	if (options.captureRscData) {
@@ -47,7 +63,7 @@ async function renderAppPageCacheArtifacts(options) {
 	const tags = buildAppPageTags(options.cleanPathname, getCollectedFetchTags(), options.route.routeSegments);
 	const observationState = consumeAppPageRenderObservationState();
 	consumeInvalidDynamicUsageError();
-	consumeDynamicUsage();
+	const usedDynamicApi = consumeDynamicUsage() || isRenderDynamicLatched();
 	const result = {
 		html,
 		htmlRenderObservation: createAppPageRenderObservation({
@@ -67,6 +83,7 @@ async function renderAppPageCacheArtifacts(options) {
 		}),
 		...linkHeader ? { linkHeader } : {},
 		tags,
+		usedDynamicApi,
 		cacheControl: typeof cacheLife?.revalidate === "number" ? {
 			revalidate: cacheLife.revalidate,
 			expire: cacheLife.expire,

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

@@ -8,7 +8,7 @@ type AppPageDebugLogger = (event: string, detail: string) => void;
 type AppPageCacheGetter = (key: string) => Promise<ISRCacheEntry | null>;
 type AppPageBackgroundRegenerator = (key: string, renderFn: () => Promise<void>) => void;
 type AppPageRscCacheKeyBuilder = (pathname: string, mountedSlotsHeader?: string | null, renderMode?: AppRscRenderMode, interceptionContext?: string | null, interceptionId?: string | null) => string;
-type AppPageCacheOutcomeMetric = Readonly<{
+export type AppPageCacheOutcomeMetric = Readonly<{
   artifact: "html" | "rsc";
   /**
    * Internal cache lookup key for debugging and tests. Runtime telemetry sinks should hash or
@@ -22,11 +22,18 @@ type AppPageCacheOutcomeRecorder = (metric: AppPageCacheOutcomeMetric) => void;
 type AppPageCacheRenderResult = {
   cacheControl?: CacheControlMetadata;
   html: string;
-  htmlRenderObservation?: RenderObservation;
+  htmlRenderObservation: RenderObservation;
   linkHeader?: string;
   rscData: ArrayBuffer;
-  rscRenderObservation?: RenderObservation;
+  rscRenderObservation: RenderObservation;
+  /**
+   * The route-level revalidate of the route this render regenerated, or null
+   * when it has none and the render's cacheLife sets it. Undefined keeps the
+   * matched route's read seed, as when the render regenerated that route.
+   */
+  revalidateSeconds?: number | null;
   tags: string[];
+  usedDynamicApi: boolean;
 };
 type BuildAppPageCachedResponseOptions = {
   cacheControl?: CacheControlMetadata;
@@ -37,12 +44,17 @@ type BuildAppPageCachedResponseOptions = {
   middlewareHeaders?: Headers | null;
   middlewareStatus?: number | null;
   mountedSlotsHeader?: string | null;
+  /** The current request's route params, which the client reads on RSC responses. */
+  params?: Record<string, string | string[]>;
+  /** The current request's path and query, which the client reads on RSC responses. */
+  renderedPathAndSearch?: string | null;
   revalidateSeconds: number;
 };
 type ReadAppPageCacheResponseOptions = {
   cleanPathname: string;
   clearRequestContext: () => void;
   isEdgeRuntime?: boolean;
+  isRoutePPREnabled?: boolean;
   isRscRequest: boolean;
   isrDebug?: AppPageDebugLogger;
   isrGet: AppPageCacheGetter;
@@ -55,7 +67,14 @@ type ReadAppPageCacheResponseOptions = {
   middlewareHeaders?: Headers | null;
   middlewareStatus?: number | null;
   mountedSlotsHeader?: string | null;
+  /**
+   * Resolves the current request's route params for a cached RSC response.
+   * Called only once an entry can answer the request, since resolving them
+   * may load route modules.
+   */
+  resolveParams?: () => Promise<Record<string, string | string[]>>;
   recordCacheOutcome?: AppPageCacheOutcomeRecorder;
+  renderedPathAndSearch?: string | null;
   renderMode?: AppRscRenderMode;
   expireSeconds?: number;
   revalidateSeconds: number;
@@ -75,10 +94,10 @@ type ReadAppPageFallbackShellCacheResponseOptions = {
   revalidateSeconds: number;
   rewriteHtml: (html: string) => string;
 };
-declare function buildAppPageCacheTags(pathname: string, extraTags: readonly string[]): string[];
-declare function buildAppRouteCacheTags(pathname: string, extraTags: readonly string[], routeSegments: readonly string[]): string[];
-declare function buildAppPageCachedResponse(cachedValue: CachedAppPageValue, options: BuildAppPageCachedResponseOptions): Response | null;
-declare function readAppPageCacheResponse(options: ReadAppPageCacheResponseOptions): Promise<Response | null>;
-declare function readAppPageFallbackShellCacheResponse(options: ReadAppPageFallbackShellCacheResponseOptions): Promise<Response | null>;
+export declare function buildAppPageCacheTags(pathname: string, extraTags: readonly string[]): string[];
+export declare function buildAppRouteCacheTags(pathname: string, extraTags: readonly string[], routeSegments: readonly string[]): string[];
+export declare function buildAppPageCachedResponse(cachedValue: CachedAppPageValue, options: BuildAppPageCachedResponseOptions): Response | null;
+export declare function readAppPageCacheResponse(options: ReadAppPageCacheResponseOptions): Promise<Response | null>;
+export declare function readAppPageFallbackShellCacheResponse(options: ReadAppPageFallbackShellCacheResponseOptions): Promise<Response | null>;
 //#endregion
-export { AppPageCacheOutcomeMetric, buildAppPageCacheTags, buildAppPageCachedResponse, buildAppRouteCacheTags, finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, readAppPageCacheResponse, readAppPageFallbackShellCacheResponse, scheduleAppPageRscCacheWrite };
+export { finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, scheduleAppPageRscCacheWrite };

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

@@ -1,15 +1,16 @@
-import { VINEXT_MOUNTED_SLOTS_HEADER, VINEXT_RSC_VARY_HEADER } from "./headers.js";
-import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
+import { VINEXT_MOUNTED_SLOTS_HEADER, VINEXT_RSC_VARY_HEADER } from "./app-rsc-vary.js";
+import { VINEXT_PARAMS_HEADER, VINEXT_RENDERED_PATH_AND_SEARCH_HEADER } from "./headers.js";
 import { applyCdnResponseHeaders } from "./cache-control.js";
 import { decideIsr } from "./isr-decision.js";
-import { buildAppPageCacheValue, isrCacheControl } from "./isr-cache.js";
+import { buildAppPageCacheValue, isrCacheControl, resolveRouteExpireSeconds } from "./isr-cache.js";
+import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
 import { encodeCacheTag } from "../utils/encode-cache-tag.js";
 import { setCacheStateHeaders } from "./cache-headers.js";
 import { VINEXT_RSC_CONTENT_TYPE, applyRscCompatibilityIdHeader, applyRscDeploymentIdHeader } from "./app-rsc-cache-busting.js";
 import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
 import { markFrameworkLinkHeaders } from "./app-response-header-provenance.js";
 import { applyClientStaleTimeHeader, applyEdgeRuntimeHeader } from "./app-page-response.js";
-import { hasCompleteNegativeRequestApiProof } from "./cache-proof.js";
+import { hasQueryInvariantRenderProof } from "./cache-proof.js";
 import { isAppPprDynamicFallbackShellHtml } from "./app-ppr-fallback-shell.js";
 import { buildPageCacheTags } from "./implicit-tags.js";
 import { finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, scheduleAppPageRscCacheWrite } from "./app-page-cache-finalizer.js";
@@ -49,28 +50,44 @@ function buildAppPageCachedHeaders(options) {
 	applyCdnResponseHeaders(headers, { cacheControl: options.cacheControl });
 	setCacheStateHeaders(headers, options.cacheState);
 	applyEdgeRuntimeHeader(headers, options.isEdgeRuntime);
+	if (options.params && Object.keys(options.params).length > 0) headers.set(VINEXT_PARAMS_HEADER, encodeURIComponent(JSON.stringify(options.params)));
 	if (options.mountedSlotsHeader) headers.set(VINEXT_MOUNTED_SLOTS_HEADER, options.mountedSlotsHeader);
 	applyClientStaleTimeHeader(headers, options.staleTimeSeconds);
 	mergeMiddlewareResponseHeaders(headers, options.middlewareHeaders ?? null);
-	if (options.linkHeader) if (Array.isArray(options.linkHeader)) for (const value of options.linkHeader) headers.append("Link", value);
-	else headers.append("Link", options.linkHeader);
+	if (options.linkHeader) {
+		if (Array.isArray(options.linkHeader)) for (const value of options.linkHeader) headers.append("Link", value);
+		else headers.append("Link", options.linkHeader);
+	}
 	return headers;
 }
 function getCachedAppPageValue(entry) {
 	return entry?.value.value && entry.value.value.kind === "APP_PAGE" ? entry.value.value : null;
 }
-function hasQueryInvariantAppPageProof(cachedValue) {
-	return cachedValue.renderObservation !== void 0 && hasCompleteNegativeRequestApiProof(cachedValue.renderObservation, ["searchParams"]);
-}
 function resolveRegeneratedAppPageCacheControl(options) {
-	let revalidateSeconds = options.routeRevalidateSeconds;
 	const renderRevalidateSeconds = options.renderCacheControl?.revalidate;
-	if (typeof renderRevalidateSeconds === "number") revalidateSeconds = revalidateSeconds > 0 ? Math.min(revalidateSeconds, renderRevalidateSeconds) : renderRevalidateSeconds;
+	let revalidateSeconds;
+	if (typeof renderRevalidateSeconds === "number") revalidateSeconds = options.routeRevalidateSeconds === null ? renderRevalidateSeconds : Math.min(options.routeRevalidateSeconds, renderRevalidateSeconds);
+	else revalidateSeconds = options.routeRevalidateSeconds ?? 0;
 	return isrCacheControl(revalidateSeconds, {
-		expireSeconds: options.renderCacheControl?.expire ?? options.expireSeconds,
+		expireSeconds: options.renderCacheControl?.expire ?? resolveRouteExpireSeconds(revalidateSeconds, options.expireSeconds),
 		staleSeconds: resolveClientStaleTimeSeconds(options.renderCacheControl)
 	});
 }
+/**
+* When a regeneration fails, Next.js re-stores the previous entry with a short
+* revalidate so it isn't retried on every request
+* (`server/response-cache/index.ts`). `revalidate = false`, which vinext holds
+* as Infinity, retries after 3 s like Next.js's `revalidate || 3`.
+*/
+function resolveRegenerationFailureCacheControl(previous) {
+	const previousRevalidate = typeof previous.revalidate === "number" && Number.isFinite(previous.revalidate) ? previous.revalidate : 0;
+	const revalidate = Math.min(Math.max(previousRevalidate || 3, 3), 30);
+	return {
+		revalidate,
+		...previous.expire === void 0 ? {} : { expire: Math.max(revalidate + 3, previous.expire) },
+		...previous.stale === void 0 ? {} : { stale: previous.stale }
+	};
+}
 function buildAppPageCachedResponse(cachedValue, options) {
 	const status = options.middlewareStatus ?? (cachedValue.status || 200);
 	const { cacheControl } = decideIsr({
@@ -90,8 +107,10 @@ function buildAppPageCachedResponse(cachedValue, options) {
 			isEdgeRuntime: options.isEdgeRuntime,
 			middlewareHeaders: options.middlewareHeaders,
 			mountedSlotsHeader: options.mountedSlotsHeader,
+			params: options.params,
 			staleTimeSeconds
 		});
+		if (options.renderedPathAndSearch) rscHeaders.set(VINEXT_RENDERED_PATH_AND_SEARCH_HEADER, encodeURIComponent(options.renderedPathAndSearch));
 		applyRscCompatibilityIdHeader(rscHeaders);
 		applyRscDeploymentIdHeader(rscHeaders);
 		return new Response(cachedValue.rscData, {
@@ -150,6 +169,16 @@ async function readAppPageCacheResponse(options) {
 	}
 	const isrKey = options.isRscRequest ? options.isrRscKey(options.cleanPathname, null, options.renderMode, options.interceptionContext, options.interceptionId) : options.isrHtmlKey(options.cleanPathname);
 	const artifact = options.isRscRequest ? "rsc" : "html";
+	let paramsFailure;
+	const resolveCachedResponseParams = async (cachedValue) => {
+		if (!options.isRscRequest || !cachedValue.rscData) return void 0;
+		try {
+			return await options.resolveParams?.();
+		} catch (error) {
+			paramsFailure = { error };
+			throw error;
+		}
+	};
 	try {
 		const cached = await options.isrGet(isrKey);
 		const cachedValue = getCachedAppPageValue(cached);
@@ -173,7 +202,7 @@ async function readAppPageCacheResponse(options) {
 			options.isrDebug?.("MISS (non app-page cache entry)", options.cleanPathname);
 			return null;
 		}
-		if (cachedValue && options.hasRequestSearchParams === true && !hasQueryInvariantAppPageProof(cachedValue)) {
+		if (cachedValue && options.hasRequestSearchParams === true && cachedValue.prerendered !== true && !hasQueryInvariantRenderProof(cachedValue.renderObservation)) {
 			recordAppPageCacheOutcome(options.recordCacheOutcome, {
 				artifact,
 				cacheKey: isrKey,
@@ -193,6 +222,8 @@ async function readAppPageCacheResponse(options) {
 				middlewareHeaders: options.middlewareHeaders,
 				middlewareStatus: options.middlewareStatus,
 				mountedSlotsHeader: options.mountedSlotsHeader,
+				params: await resolveCachedResponseParams(cachedValue),
+				renderedPathAndSearch: options.renderedPathAndSearch,
 				revalidateSeconds: options.revalidateSeconds
 			});
 			if (hitResponse) {
@@ -215,23 +246,60 @@ async function readAppPageCacheResponse(options) {
 			options.isrDebug?.("MISS (empty cached entry)", options.cleanPathname);
 		}
 		if (cached?.isStale && cachedValue) {
-			options.scheduleBackgroundRegeneration(isrKey, async () => {
+			const keepPreviousEntry = async (key, previous) => {
+				const previousValue = getCachedAppPageValue(previous);
+				const previousCacheControl = previous.value.cacheControl;
+				const previousTags = previousValue?.renderObservation?.cacheTags;
+				if (!previousValue || !previousCacheControl || !previousTags || previous.isExpired) return;
+				try {
+					const current = await options.isrGet(key);
+					if (!current || current.value.lastModified === previous.value.lastModified) await options.isrSet(key, previousValue, {
+						cacheControl: resolveRegenerationFailureCacheControl(previousCacheControl),
+						tags: [...previousTags]
+					});
+				} catch (storeError) {
+					console.error(`[vinext] Failed to keep the previous entry for ${key}:`, storeError);
+				}
+			};
+			const regenerate = async () => {
 				const revalidatedPage = await options.renderFreshPageForCache();
 				const cacheControl = resolveRegeneratedAppPageCacheControl({
 					expireSeconds: options.expireSeconds,
 					renderCacheControl: revalidatedPage.cacheControl,
-					routeRevalidateSeconds: options.revalidateSeconds
+					routeRevalidateSeconds: revalidatedPage.revalidateSeconds === void 0 ? options.revalidateSeconds || null : revalidatedPage.revalidateSeconds
 				});
-				const writes = [options.isrSet(options.isRscRequest ? isrKey : options.isrRscKey(options.cleanPathname, null, options.renderMode, options.interceptionContext, options.interceptionId), buildAppPageCacheValue("", revalidatedPage.rscData, 200, revalidatedPage.rscRenderObservation), {
-					cacheControl,
-					tags: revalidatedPage.tags
-				})];
-				if (!options.isRscRequest) writes.push(options.isrSet(isrKey, buildAppPageCacheValue(revalidatedPage.html, void 0, 200, revalidatedPage.htmlRenderObservation, revalidatedPage.linkHeader ? { link: revalidatedPage.linkHeader } : void 0), {
-					cacheControl,
-					tags: revalidatedPage.tags
-				}));
-				await Promise.all(writes);
+				if (options.isRoutePPREnabled !== true && (revalidatedPage.usedDynamicApi || cacheControl.revalidate === 0)) throw new Error(`Page changed from static to dynamic at runtime ${options.cleanPathname}
+see more here https://nextjs.org/docs/messages/app-static-to-dynamic-error`);
+				if (!hasQueryInvariantRenderProof(revalidatedPage.rscRenderObservation) || !options.isRscRequest && !hasQueryInvariantRenderProof(revalidatedPage.htmlRenderObservation)) {
+					options.isrDebug?.("regen write skipped (searchParams not proven unread)", isrKey);
+					return;
+				}
+				const rscKey = options.isRscRequest ? isrKey : options.isrRscKey(options.cleanPathname, null, options.renderMode, options.interceptionContext, options.interceptionId);
+				const store = async (key, value) => {
+					try {
+						await options.isrSet(key, value, {
+							cacheControl,
+							tags: revalidatedPage.tags
+						});
+						return true;
+					} catch (storeError) {
+						console.warn(`[vinext] Failed to update prerender cache for ${key}:`, storeError);
+						return false;
+					}
+				};
+				if (!await store(rscKey, buildAppPageCacheValue("", revalidatedPage.rscData, 200, revalidatedPage.rscRenderObservation))) return;
+				if (!options.isRscRequest) {
+					if (!await store(isrKey, buildAppPageCacheValue(revalidatedPage.html, void 0, 200, revalidatedPage.htmlRenderObservation, revalidatedPage.linkHeader ? { link: revalidatedPage.linkHeader } : void 0))) return;
+				}
 				options.isrDebug?.("regen complete", options.cleanPathname);
+			};
+			options.scheduleBackgroundRegeneration(isrKey, async () => {
+				try {
+					await regenerate();
+				} catch (error) {
+					await keepPreviousEntry(isrKey, cached);
+					throw error;
+				}
 			});
 			const staleResponse = buildAppPageCachedResponse(cachedValue, {
 				cacheState: "STALE",
@@ -242,6 +310,8 @@ async function readAppPageCacheResponse(options) {
 				middlewareHeaders: options.middlewareHeaders,
 				middlewareStatus: options.middlewareStatus,
 				mountedSlotsHeader: options.mountedSlotsHeader,
+				params: await resolveCachedResponseParams(cachedValue),
+				renderedPathAndSearch: options.renderedPathAndSearch,
 				revalidateSeconds: options.revalidateSeconds
 			});
 			if (staleResponse) {
@@ -273,6 +343,7 @@ async function readAppPageCacheResponse(options) {
 			options.isrDebug?.("MISS (no cache entry)", options.cleanPathname);
 		}
 	} catch (isrReadError) {
+		if (paramsFailure) throw paramsFailure.error;
 		recordAppPageCacheOutcome(options.recordCacheOutcome, {
 			artifact,
 			cacheKey: isrKey,

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

@@ -10,6 +10,7 @@ import { AppPageMiddlewareContext } from "./app-page-response.js";
 import { AppLayoutParamAccessTracker } from "./app-layout-param-observation.js";
 import { RootParams } from "../shims/root-params.js";
 import { AppPageSsrHandler } from "./app-page-stream.js";
+import { AppRenderErrorContextOverrides } from "./app-rsc-error-handler.js";
 import { AppPageCacheSetter, ISRCacheEntry } from "./isr-cache.js";
 import { PprFallbackShellState } from "../shims/ppr-fallback-shell.js";
 import { FetchCacheMode } from "../shims/fetch-cache.js";
@@ -21,14 +22,15 @@ import { ReactFormState } from "react-dom/client";
 //#region src/server/app-page-dispatch.d.ts
 type AppPageParams = Record<string, string | string[]>;
 type AppPageElement = ReactNode | Readonly<Record<string, ReactNode>>;
-type AppPageRenderableElement = ReactNode | AppOutgoingElements;
-type AppPageBoundaryOnError = (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
+export type AppPageRenderableElement = ReactNode | AppOutgoingElements;
+export type AppPageBoundaryOnError = (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
 type AppPageDebugLogger = (event: string, detail: string) => void;
 type AppPageCacheGetter = (key: string) => Promise<ISRCacheEntry | null>;
 type AppPageBackgroundRegenerationErrorContext = {
   routerKind: "App Router";
   routePath: string;
   routeType: "render";
+  shouldReport?: (error: unknown) => boolean;
 };
 type AppPageBackgroundRegenerator = (key: string, renderFn: () => Promise<void>, errorContext?: AppPageBackgroundRegenerationErrorContext) => void;
 type AppPageDispatchIntercept<TPage = unknown> = {
@@ -86,7 +88,7 @@ type AppPageDispatchSlot = {
   slotPatternParts?: readonly string[] | null;
   slotParamNames?: readonly string[] | null;
 };
-type AppPageDispatchRoute = {
+export type AppPageDispatchRoute = {
   __buildTimeClassifications?: LayoutClassificationOptions["buildTimeClassifications"];
   __buildTimeReasons?: LayoutClassificationOptions["buildTimeReasons"];
   error?: AppPageModule | null;
@@ -110,15 +112,15 @@ type AppPageDispatchRoute = {
   unauthorizedTreePosition?: number | null;
   unauthorizeds?: readonly (AppPageModule | null | undefined)[];
 };
-type AppPagePprRuntime<TRoute extends AppPageDispatchRoute> = {
+export type AppPagePprRuntime<TRoute extends AppPageDispatchRoute> = {
   beginFinalRender(state: AppPagePprState): void;
   getState(): AppPagePprState | null;
   run<T>(shell: NonNullable<DispatchAppPageOptions<TRoute>["pprFallbackShell"]>, fn: () => T): T;
   tryServe(options: DispatchAppPageOptions<TRoute>, currentRevalidateSeconds: number | null, isDraftMode: boolean, isForceStatic: boolean, isForceDynamic: boolean): Promise<Response | null>;
   warm(options: WarmPprFallbackShellCachesOptions): Promise<void>;
 };
-type AppPagePprState = PprFallbackShellState;
-type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
+export type AppPagePprState = PprFallbackShellState;
+export type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   /** Configured basePath (e.g. "/blog"). Used to prefix redirect Locations. */
   basePath?: string;
   /** Bypass shared RSC caches when the client-supplied interception context was not verified. */
@@ -136,6 +138,7 @@ type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
    */
   reactMaxHeadersLength?: number;
   buildPageElement: (route: TRoute, params: AppPageParams, opts: AppPageDispatchInterceptOptions | undefined, searchParams: URLSearchParams, layoutParamAccess?: AppLayoutParamAccessTracker, options?: {
+    isForceStatic?: boolean;
     observeMetadataSearchParamsAccess?: boolean;
     observePageSearchParamsAccess?: boolean;
     serveStreamingMetadata?: boolean;
@@ -144,7 +147,7 @@ type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   cleanPathname: string;
   displayPathname?: string;
   clearRequestContext: () => void;
-  createRscOnErrorHandler: (pathname: string, routePath: string) => AppPageBoundaryOnError;
+  createRscOnErrorHandler: (pathname: string, routePath: string, overrides?: AppRenderErrorContextOverrides) => AppPageBoundaryOnError;
   debugClassification?: (layoutId: string, reason: ClassificationReason) => void;
   draftModeSecret: string;
   dynamicConfig?: string;
@@ -167,7 +170,13 @@ type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   getFontStyles: () => string[];
   getNavigationContext: () => NavigationContext | null;
   getSourceRoute: (sourceRouteIndex: number) => TRoute | undefined;
+  /**
+   * Whether `generateStaticParams` is exported at or below the route's last
+   * dynamic segment (`hasAppPageGenerateStaticParamsAtLastDynamicSegment`).
+   */
   hasGenerateStaticParams: boolean;
+  /** Whether any segment of the route exports `generateStaticParams`. */
+  hasAnyGenerateStaticParams: boolean;
   hasCustomGlobalError?: boolean;
   hasPageDefaultExport: boolean;
   hasPageModule: boolean;
@@ -175,6 +184,13 @@ type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   htmlLimitedBots?: string;
   interceptionContext: string | null;
   isEdgeRuntime?: boolean;
+  /**
+   * Whether the route's loader tree resolves `runtime = "edge"` (or
+   * `"experimental-edge"`), which disables static generation outside
+   * `cacheComponents`. Every parallel branch merges at each node, as
+   * in Next.js's Turbopack build (`collectAppPageStaticGenerationRuntimes`).
+   */
+  isStaticGenerationEdgeRuntime?: boolean;
   isProgressiveActionRender?: boolean;
   isProduction: boolean;
   isRscRequest: boolean;
@@ -231,6 +247,13 @@ type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   resolveRouteFetchCacheMode?: (route: TRoute) => FetchCacheMode | null;
   resolveRouteRevalidateSeconds?: (route: TRoute) => number | null;
   resolveRouteDynamicConfig?: (route: TRoute) => string | null | undefined;
+  /**
+   * `isAppPageStaticEligible` for another route, from that route's own segment
+   * config, `generateStaticParams`, dynamism and runtime. A direct intercepted
+   * RSC response renders its source route, so it takes the source's
+   * cacheability.
+   */
+  resolveRouteStaticEligible: (route: TRoute) => boolean;
   rootForbiddenModule?: AppPageModule | null;
   rootNotFoundModule?: AppPageModule | null;
   rootUnauthorizedModule?: AppPageModule | null;
@@ -246,7 +269,7 @@ type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   }) => void;
   renderMode?: AppRscRenderMode;
 };
-declare function shouldReadAppPageCache(options: {
+export declare function shouldReadAppPageCache(options: {
   isProgressiveActionRender: boolean;
   isDraftMode: boolean;
   isForceDynamic: boolean;
@@ -255,7 +278,6 @@ declare function shouldReadAppPageCache(options: {
   revalidateSeconds: number | null;
   scriptNonce?: string;
 }): boolean;
-declare function hasSearchParams(searchParams: URLSearchParams | null | undefined): boolean;
-declare function dispatchAppPage<TRoute extends AppPageDispatchRoute>(options: DispatchAppPageOptions<TRoute>): Promise<Response>;
-//#endregion
-export { AppPageBoundaryOnError, AppPageDispatchRoute, AppPagePprRuntime, AppPagePprState, AppPageRenderableElement, DispatchAppPageOptions, dispatchAppPage, hasSearchParams, shouldReadAppPageCache };
+export declare function hasSearchParams(searchParams: URLSearchParams | null | undefined): boolean;
+export declare function dispatchAppPage<TRoute extends AppPageDispatchRoute>(options: DispatchAppPageOptions<TRoute>): Promise<Response>;
+//#endregion