vinext 1.0.0-beta.9 → 1.0.0

package/dist/server/app-metadata-tracing.d.ts

@@ -0,0 +1,12 @@
+//#region src/server/app-metadata-tracing.d.ts
+type AppMetadataModuleType = "forbidden" | "layout" | "not-found" | "page" | "unauthorized";
+export declare function createAppMetadataModuleRoute(routeSegments: readonly string[], moduleType: AppMetadataModuleType): string;
+export declare function traceGenerateMetadata<T>(moduleRoute: string, callback: () => T): T;
+export declare function createGenerateMetadataSpanDescriptor(moduleRoute: string): {
+  readonly attributes: {
+    readonly "next.page": string;
+  };
+  readonly name: `generateMetadata ${string}`;
+  readonly type: "ResolveMetadata.generateMetadata";
+};
+//#endregion

package/dist/server/app-metadata-tracing.js

@@ -0,0 +1,17 @@
+import { frameworkTracer } from "./tracer.js";
+//#region src/server/app-metadata-tracing.ts
+function createAppMetadataModuleRoute(routeSegments, moduleType) {
+	return `/${[...routeSegments.filter((segment) => !segment.startsWith("@")), moduleType].join("/")}`;
+}
+function traceGenerateMetadata(moduleRoute, callback) {
+	return frameworkTracer.trace(createGenerateMetadataSpanDescriptor(moduleRoute), callback);
+}
+function createGenerateMetadataSpanDescriptor(moduleRoute) {
+	return {
+		attributes: { "next.page": moduleRoute },
+		name: `generateMetadata ${moduleRoute}`,
+		type: "ResolveMetadata.generateMetadata"
+	};
+}
+//#endregion
+export { createAppMetadataModuleRoute, createGenerateMetadataSpanDescriptor, traceGenerateMetadata };

package/dist/server/app-middleware.d.ts

@@ -2,12 +2,12 @@ import { NextI18nConfig } from "../config/next-config.js";
 import { MiddlewareModule } from "./middleware-runtime.js";
 import { FLIGHT_HEADERS } from "./headers.js";
 //#region src/server/app-middleware.d.ts
-type AppMiddlewareContext = {
+export type AppMiddlewareContext = {
   headers: Headers | null;
   requestHeaders: Headers | null;
   status: number | null;
 };
-type ApplyAppMiddlewareOptions = {
+export type ApplyAppMiddlewareOptions = {
   basePath?: string;
   cleanPathname: string;
   context: AppMiddlewareContext;
@@ -35,7 +35,7 @@ type ApplyAppMiddlewareOptions = {
    */
   trailingSlash?: boolean;
 };
-type ApplyAppMiddlewareResult = {
+export type ApplyAppMiddlewareResult = {
   kind: "continue";
   cleanPathname: string;
   /** Present on real middleware results; optional for older generated callers. */
@@ -52,8 +52,8 @@ type ApplyAppMiddlewareResult = {
   pathnameEligible?: boolean;
   response: Response;
 };
-declare function isExternalMiddlewareRewrite(rewriteUrl: string, request: Request): boolean;
-declare function proxyExternalMiddlewareRewrite(request: Request, rewriteUrl: string, context: AppMiddlewareContext): Promise<Response>;
-declare function applyAppMiddleware(options: ApplyAppMiddlewareOptions): Promise<ApplyAppMiddlewareResult>;
+export declare function isExternalMiddlewareRewrite(rewriteUrl: string, request: Request): boolean;
+export declare function proxyExternalMiddlewareRewrite(request: Request, rewriteUrl: string, context: AppMiddlewareContext): Promise<Response>;
+export declare function applyAppMiddleware(options: ApplyAppMiddlewareOptions): Promise<ApplyAppMiddlewareResult>;
 //#endregion
-export { AppMiddlewareContext, ApplyAppMiddlewareOptions, ApplyAppMiddlewareResult, FLIGHT_HEADERS, applyAppMiddleware, isExternalMiddlewareRewrite, proxyExternalMiddlewareRewrite };
+export { FLIGHT_HEADERS };

package/dist/server/app-middleware.js

@@ -1,14 +1,13 @@
 import { VINEXT_MW_CTX_HEADER } from "../utils/protocol-headers.js";
-import { FLIGHT_HEADERS } from "./headers.js";
 import { buildRequestHeadersFromMiddlewareResponse } from "../utils/middleware-request-headers.js";
 import { isExternalUrl } from "../utils/external-url.js";
+import { FLIGHT_HEADERS } from "./headers.js";
 import { internalServerErrorResponse } from "./http-error-responses.js";
 import { cloneRequestWithHeaders, processMiddlewareHeaders } from "./request-pipeline.js";
 import { executeMiddleware } from "./middleware-runtime.js";
 import { applyMiddlewareRequestHeaders, setHeadersContext } from "../shims/headers.js";
-import { setNavigationContext } from "../shims/navigation-context-state.js";
 import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
-import "../shims/navigation.js";
+import { setNavigationContext } from "../shims/navigation-context-accessors.js";
 //#region src/server/app-middleware.ts
 const FLIGHT_HEADER_SET = new Set(FLIGHT_HEADERS);
 function isForwardedMiddlewareContext(value) {

package/dist/server/app-mounted-slots-header.d.ts

@@ -30,6 +30,5 @@
  *   - app-elements (outgoing x-vinext-mounted-slots construction)
  *   - isr-cache (RSC cache key generation)
  */
-declare function normalizeMountedSlotsHeader(raw: string | null | undefined): string | null;
-//#endregion
-export { normalizeMountedSlotsHeader };
+export declare function normalizeMountedSlotsHeader(raw: string | null | undefined): string | null;
+//#endregion

package/dist/server/app-mounted-slots-header.js

@@ -1,4 +1,4 @@
-import { AppElementsWire } from "./app-elements-wire.js";
+import { isAppElementsWireSlotId } from "./app-elements-wire-key.js";
 //#region src/server/app-mounted-slots-header.ts
 /**
 * Normalize the `x-vinext-mounted-slots` header for request handling and cache keying.
@@ -45,7 +45,7 @@ const MAX_SLOT_TOKENS = 16;
 */
 function isValidSlotToken(token) {
 	if (token.length === 0 || token.length > MAX_TOKEN_LENGTH) return false;
-	return AppElementsWire.isSlotId(token);
+	return isAppElementsWireSlotId(token);
 }
 function normalizeMountedSlotsHeader(raw) {
 	if (!raw) return null;

package/dist/server/app-optimistic-routing.d.ts

@@ -6,7 +6,7 @@ type OptimisticRouteMatch = {
   params: Record<string, string | string[]>;
   route: RouteManifestRoute;
 };
-type OptimisticRouteTemplate = {
+export type OptimisticRouteTemplate = {
   elements: AppElements;
   mountedSlotsHeader: string | null;
   omittedBfcacheSegmentIds: readonly string[];
@@ -21,27 +21,27 @@ type OptimisticNavigationPayload = {
   template: OptimisticRouteTemplate;
   urlParts: readonly string[];
 };
-declare function getOptimisticRouteTemplateKey(options: {
+export declare function getOptimisticRouteTemplateKey(options: {
   interceptionContext: string | null;
   mountedSlotsHeader: string | null;
   routeId: string;
 }): string;
-declare function getOptimisticPrefetchSourceKey(options: {
+export declare function getOptimisticPrefetchSourceKey(options: {
   cacheKey: string;
   interceptionContext: string | null;
   mountedSlotsHeader: string | null;
 }): string;
-declare function matchOptimisticRouteManifestRoute(options: {
+export declare function matchOptimisticRouteManifestRoute(options: {
   basePath: string;
   href: string;
   routeManifest: RouteManifest;
 }): OptimisticRouteMatch | null;
-declare function resolveOptimisticNavigationParamsForHref(options: {
+export declare function resolveOptimisticNavigationParamsForHref(options: {
   basePath: string;
   href: string;
   routeManifest: RouteManifest;
 }): Record<string, string | string[]> | null;
-declare function createOptimisticRouteTemplate(options: {
+export declare function createOptimisticRouteTemplate(options: {
   allowLoadingShell?: boolean;
   basePath: string;
   elements: AppElements;
@@ -50,7 +50,7 @@ declare function createOptimisticRouteTemplate(options: {
   mountedSlotsHeader: string | null;
   routeManifest: RouteManifest;
 }): OptimisticRouteTemplate | null;
-declare function createOptimisticRouteElements(template: OptimisticRouteTemplate): AppElements;
+export declare function createOptimisticRouteElements(template: OptimisticRouteTemplate): AppElements;
 /**
  * A loading-shell prefetch stops at the first loading boundary, so layouts
  * below that boundary are present in the route metadata but absent from the
@@ -59,7 +59,7 @@ declare function createOptimisticRouteElements(template: OptimisticRouteTemplate
  * keeps the shared segment active in this case, which also means the ancestor
  * loading boundary does not re-trigger.
  */
-declare function canCommitOptimisticRouteTemplate(options: {
+export declare function canCommitOptimisticRouteTemplate(options: {
   currentElements: AppElements;
   currentLayoutIds: readonly string[];
   currentParams: Readonly<Record<string, string | string[]>>;
@@ -68,7 +68,7 @@ declare function canCommitOptimisticRouteTemplate(options: {
   targetUrlParts: readonly string[];
   template: OptimisticRouteTemplate;
 }): boolean;
-declare function resolveOptimisticNavigationPayload(options: {
+export declare function resolveOptimisticNavigationPayload(options: {
   basePath: string;
   href: string;
   interceptionContext: string | null;
@@ -76,5 +76,4 @@ declare function resolveOptimisticNavigationPayload(options: {
   routeManifest: RouteManifest;
   templates: ReadonlyMap<string, OptimisticRouteTemplate>;
 }): OptimisticNavigationPayload | null;
-//#endregion
-export { OptimisticRouteTemplate, canCommitOptimisticRouteTemplate, createOptimisticRouteElements, createOptimisticRouteTemplate, getOptimisticPrefetchSourceKey, getOptimisticRouteTemplateKey, matchOptimisticRouteManifestRoute, resolveOptimisticNavigationParamsForHref, resolveOptimisticNavigationPayload };
+//#endregion

package/dist/server/app-optimistic-routing.js

@@ -1,6 +1,6 @@
+import { isUnknownRecord } from "../utils/record.js";
 import { buildParams, decodeMatchedParams, splitPathnameForRouteMatch } from "../routing/utils.js";
 import { stripBasePath } from "../utils/base-path.js";
-import { isUnknownRecord } from "../utils/record.js";
 import { AppElementsWire } from "./app-elements-wire.js";
 import "./app-elements.js";
 import { extractRawRoutePatternParams, matchRoutePattern } from "../routing/route-pattern.js";
@@ -127,7 +127,8 @@ function hrefToRouteParts(href, basePath) {
 		return null;
 	}
 	stripRscCacheBustingSearchParam(url);
-	const appPathname = stripBasePath(stripRscSuffix(url.pathname), basePath);
+	const withoutRscSuffix = stripRscSuffix(url.pathname);
+	const appPathname = stripBasePath(withoutRscSuffix, basePath);
 	const pathname = appPathname === "" ? "/" : appPathname;
 	return {
 		normalized: splitPathnameForRouteMatch(pathname),

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

@@ -10,6 +10,7 @@ import { ApplyAppPageFileBasedMetadata } from "./app-page-head.js";
 import { AppPageRouteWiringRoute } from "./app-page-route-wiring.js";
 import { AppPageInterceptOptions } from "./app-page-element-builder.js";
 import { AppPageSsrHandler } from "./app-page-stream.js";
+import { AppRenderErrorContextOverrides } from "./app-rsc-error-handler.js";
 import { ComponentType, ReactNode } from "react";
 //#region src/server/app-page-boundary-render.d.ts
 type AppPageComponent = ComponentType<any>;
@@ -17,7 +18,7 @@ type AppPageModule = Record<string, unknown> & {
   default?: AppPageComponent | null | undefined;
 };
 type AppPageBoundaryOnError = (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
-type AppPageBoundaryRoute<TModule extends AppPageModule = AppPageModule> = {
+export type AppPageBoundaryRoute<TModule extends AppPageModule = AppPageModule> = {
   error?: TModule | null;
   errorPaths?: readonly TModule[] | null;
   errors?: readonly (TModule | null | undefined)[] | null;
@@ -41,7 +42,7 @@ type AppPageBoundaryRenderCommonOptions<TModule extends AppPageModule = AppPageM
   applyFileBasedMetadata?: ApplyAppPageFileBasedMetadata;
   buildFontLinkHeader: (preloads: readonly AppPageFontPreload[] | null | undefined) => string;
   clearRequestContext: () => void;
-  createRscOnErrorHandler: (pathname: string, routePath: string) => AppPageBoundaryOnError;
+  createRscOnErrorHandler: (pathname: string, routePath: string, overrides?: AppRenderErrorContextOverrides) => AppPageBoundaryOnError;
   getAndClearPendingCookies?: () => string[];
   getFontLinks: () => string[];
   getFontPreloads: () => AppPageFontPreload[];
@@ -108,7 +109,6 @@ type RenderAppPageErrorBoundaryOptions<TModule extends AppPageModule = AppPageMo
   route?: AppPageBoundaryRoute<TModule> | null;
   sanitizeErrorForClient: (error: Error) => Error;
 } & AppPageBoundaryRenderCommonOptions<TModule>;
-declare function renderAppPageHttpAccessFallback<TModule extends AppPageModule>(options: RenderAppPageHttpAccessFallbackOptions<TModule>): Promise<Response | null>;
-declare function renderAppPageErrorBoundary<TModule extends AppPageModule>(options: RenderAppPageErrorBoundaryOptions<TModule>): Promise<Response | null>;
-//#endregion
-export { AppPageBoundaryRoute, renderAppPageErrorBoundary, renderAppPageHttpAccessFallback };
+export declare function renderAppPageHttpAccessFallback<TModule extends AppPageModule>(options: RenderAppPageHttpAccessFallbackOptions<TModule>): Promise<Response | null>;
+export declare function renderAppPageErrorBoundary<TModule extends AppPageModule>(options: RenderAppPageErrorBoundaryOptions<TModule>): Promise<Response | null>;
+//#endregion

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

@@ -1,9 +1,9 @@
 import { stripBasePath } from "../utils/base-path.js";
+import { isNavigationSignalError } from "../utils/navigation-signal.js";
 import { NEVER_CACHE_CONTROL, applyCdnResponseHeaders } from "./cache-control.js";
 import { AppElementsWire } from "./app-elements-wire.js";
 import "./app-elements.js";
 import DefaultGlobalError from "../shims/default-global-error.js";
-import { isNavigationSignalError } from "../utils/navigation-signal.js";
 import { ErrorBoundary, GlobalErrorBoundary, SerializedErrorBoundary } from "../shims/error-boundary.js";
 import { LayoutSegmentProvider } from "../shims/layout-segment-context.js";
 import { MetadataHead, ViewportHead } from "../shims/metadata.js";
@@ -18,7 +18,7 @@ import { resolveHttpAccessFallbackMetadata, resolveHttpAccessFallbackViewport }
 import "./app-rsc-route-matching.js";
 import { renderAppPageBoundaryResponse, resolveAppPageErrorBoundary, resolveAppPageHttpAccessBoundaryModule, wrapAppPageBoundaryElement } from "./app-page-boundary.js";
 import { resolveSlotParamOverrides } from "./app-page-element-builder.js";
-import { createAppPageFontData, createAppPageRscErrorTracker, renderAppPageHtmlResponse } from "./app-page-stream.js";
+import { createAppPageFontData, createAppPageRscErrorTracker, createAppPageSsrErrorHandler, renderAppPageHtmlResponse } from "./app-page-stream.js";
 import { Fragment, createElement } from "react";
 //#region src/server/app-page-boundary-render.ts
 const DEFAULT_GLOBAL_ERROR_COMPONENT = DefaultGlobalError;
@@ -133,7 +133,8 @@ async function renderAppPageBoundaryElementResponse(options) {
 		route: options.route,
 		sourcePageSegments: options.sourcePageSegments
 	});
-	const rscErrorTracker = createAppPageRscErrorTracker(options.createRscOnErrorHandler(pathname, options.routePattern ?? pathname));
+	const baseRscOnErrorHandler = options.createRscOnErrorHandler(pathname, options.routePattern ?? pathname);
+	const rscErrorTracker = createAppPageRscErrorTracker(baseRscOnErrorHandler);
 	const resolveCapturedSpecialError = (error) => resolveAppPageSpecialError(error) ?? resolveAppPageSpecialError(rscErrorTracker.getCapturedSpecialError());
 	const renderSpecialErrorResponse = (specialError) => renderBoundarySpecialErrorResponse(options, specialError);
 	const handleSpecialErrors = options.handleSpecialErrors === true;
@@ -147,6 +148,7 @@ async function renderAppPageBoundaryElementResponse(options) {
 					getStyles: options.getFontStyles
 				});
 				const ssrHandler = await options.loadSsrHandler();
+				const onSsrError = options.createRscOnErrorHandler(pathname, options.routePattern ?? pathname, { renderSource: "server-rendering" });
 				return renderAppPageHtmlResponse({
 					clearRequestContext: options.clearRequestContext,
 					fontData,
@@ -163,7 +165,8 @@ async function renderAppPageBoundaryElementResponse(options) {
 					scriptNonce: options.scriptNonce,
 					ssrHandler,
 					status: responseStatus,
-					initialDevServerError: options.initialDevServerError
+					initialDevServerError: options.initialDevServerError,
+					onSsrError: createAppPageSsrErrorHandler(onSsrError, rscErrorTracker.isCapturedError)
 				});
 			},
 			createRscOnErrorHandler() {
@@ -254,6 +257,7 @@ async function renderAppPageHttpAccessFallback(options) {
 				},
 				...intercept?.interceptNotFound ? {
 					notFoundModule: intercept.interceptNotFound,
+					notFoundModuleRouteSegments: (intercept.interceptNotFoundBranchSegments ?? intercept.interceptSourcePageSegments ?? fallbackRouteSegments).slice(0, intercept.interceptNotFoundTreePosition ?? 0),
 					notFoundParams: resolveAppPageBranchParams(intercept.interceptNotFoundBranchSegments ?? intercept.interceptBranchSegments ?? fallbackRouteSegments, intercept.interceptNotFoundTreePosition ?? 0, effectiveParams)
 				} : {},
 				ownerTreePosition: fallbackRouteSegments.length
@@ -261,7 +265,9 @@ async function renderAppPageHttpAccessFallback(options) {
 			const fallbackHeadOptions = {
 				boundaryModule,
 				boundaryParams,
+				boundaryRouteSegments: fallbackRouteSegments.slice(0, boundaryTreePosition ?? 0),
 				branchNotFoundConventions: options.statusCode === 404,
+				errorConvention: options.statusCode === 403 ? "forbidden" : options.statusCode === 401 ? "unauthorized" : "not-found",
 				layoutModules,
 				layoutTreePositions: resolveHttpAccessFallbackHeadLayoutTreePositions(options.route, layoutModules),
 				parallelBranches,

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

@@ -1,5 +1,5 @@
 //#region src/server/app-page-boundary.d.ts
-type AppPageParams = Record<string, string | string[]>;
+export type AppPageParams = Record<string, string | string[]>;
 type ResolveAppPageHttpAccessBoundaryComponentOptions<TModule, TComponent> = {
   getDefaultExport: (module: TModule | null | undefined) => TComponent | null | undefined;
   rootForbiddenModule?: TModule | null;
@@ -72,9 +72,9 @@ type RenderAppPageBoundaryResponseOptions<TElement> = {
   }) => ReadableStream<Uint8Array>;
   status: number;
 };
-declare function resolveAppPageHttpAccessBoundaryComponent<TModule, TComponent>(options: ResolveAppPageHttpAccessBoundaryComponentOptions<TModule, TComponent>): TComponent | null;
-declare function resolveAppPageHttpAccessBoundaryModule<TModule>(options: ResolveAppPageHttpAccessBoundaryModuleOptions<TModule>): TModule | null;
-declare function resolveAppPageParentHttpAccessBoundaryModule<TModule>(options: ResolveAppPageParentHttpAccessBoundaryModuleOptions<TModule>): TModule | null;
+export declare function resolveAppPageHttpAccessBoundaryComponent<TModule, TComponent>(options: ResolveAppPageHttpAccessBoundaryComponentOptions<TModule, TComponent>): TComponent | null;
+export declare function resolveAppPageHttpAccessBoundaryModule<TModule>(options: ResolveAppPageHttpAccessBoundaryModuleOptions<TModule>): TModule | null;
+export declare function resolveAppPageParentHttpAccessBoundaryModule<TModule>(options: ResolveAppPageParentHttpAccessBoundaryModuleOptions<TModule>): TModule | null;
 /**
  * Like {@link resolveAppPageParentHttpAccessBoundaryModule}, but also returns
  * the layout index that owns the resolved boundary so callers can slice the
@@ -91,12 +91,11 @@ declare function resolveAppPageParentHttpAccessBoundaryModule<TModule>(options:
  *
  * @see https://github.com/vercel/next.js/blob/canary/packages/next/src/server/app-render/create-component-tree.tsx
  */
-declare function resolveAppPageParentHttpAccessBoundary<TModule>(options: ResolveAppPageParentHttpAccessBoundaryModuleOptions<TModule>): {
+export declare function resolveAppPageParentHttpAccessBoundary<TModule>(options: ResolveAppPageParentHttpAccessBoundaryModuleOptions<TModule>): {
   module: TModule | null;
   layoutIndex: number | null;
 };
-declare function resolveAppPageErrorBoundary<TModule, TComponent>(options: ResolveAppPageErrorBoundaryOptions<TModule, TComponent>): ResolveAppPageErrorBoundaryResult<TComponent>;
-declare function wrapAppPageBoundaryElement<TElement, TLayoutModule, TLayoutComponent, TChildSegments, TGlobalErrorComponent>(options: WrapAppPageBoundaryElementOptions<TElement, TLayoutModule, TLayoutComponent, TChildSegments, TGlobalErrorComponent>): TElement;
-declare function renderAppPageBoundaryResponse<TElement>(options: RenderAppPageBoundaryResponseOptions<TElement>): Promise<Response>;
-//#endregion
-export { AppPageParams, renderAppPageBoundaryResponse, resolveAppPageErrorBoundary, resolveAppPageHttpAccessBoundaryComponent, resolveAppPageHttpAccessBoundaryModule, resolveAppPageParentHttpAccessBoundary, resolveAppPageParentHttpAccessBoundaryModule, wrapAppPageBoundaryElement };
+export declare function resolveAppPageErrorBoundary<TModule, TComponent>(options: ResolveAppPageErrorBoundaryOptions<TModule, TComponent>): ResolveAppPageErrorBoundaryResult<TComponent>;
+export declare function wrapAppPageBoundaryElement<TElement, TLayoutModule, TLayoutComponent, TChildSegments, TGlobalErrorComponent>(options: WrapAppPageBoundaryElementOptions<TElement, TLayoutModule, TLayoutComponent, TChildSegments, TGlobalErrorComponent>): TElement;
+export declare function renderAppPageBoundaryResponse<TElement>(options: RenderAppPageBoundaryResponseOptions<TElement>): Promise<Response>;
+//#endregion

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

@@ -1,4 +1,4 @@
-import { VINEXT_RSC_VARY_HEADER } from "./headers.js";
+import { VINEXT_RSC_VARY_HEADER } from "./app-rsc-vary.js";
 import { runWithFetchDedupe } from "../shims/fetch-cache.js";
 import { resolveAppPageSegmentParams } from "./app-page-params.js";
 import { VINEXT_RSC_CONTENT_TYPE, applyRscCompatibilityIdHeader, applyRscDeploymentIdHeader } from "./app-rsc-cache-busting.js";

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

@@ -21,16 +21,24 @@ type FinalizeAppPageCacheabilityEvaluationOptions = {
   getPageTags: () => string[];
   getRequestCacheLife?: () => AppPageRequestCacheLife | null;
   expireSeconds?: number;
+  /**
+   * `false` for routes Next.js classifies as dynamic (ƒ), which are never
+   * cacheable even when a cacheLife resolves during the render.
+   */
+  isStaticEligible: boolean;
   revalidateSeconds: number | null;
 };
 type FinalizeAppPageHtmlCacheResponseOptions = {
+  bypassInterceptionContextCache?: boolean;
   capturedDynamicUsageBeforeContextCleanup?: () => boolean;
   capturedRscDataPromise: Promise<ArrayBuffer> | null;
   cleanPathname: string;
+  /** Private marker surrounding this render's injected client trace metadata. */
+  clientTraceMetadataMarker?: string;
   consumeDynamicUsage: () => boolean;
   consumeRenderObservationState?: () => AppPageRenderObservationState;
-  createHtmlRenderObservation?: BuildAppPageCacheRenderObservation;
-  createRscRenderObservation?: BuildAppPageCacheRenderObservation;
+  createHtmlRenderObservation: BuildAppPageCacheRenderObservation;
+  createRscRenderObservation: BuildAppPageCacheRenderObservation;
   getPageTags: () => string[];
   getRequestCacheLife?: () => AppPageRequestCacheLife | null;
   isrDebug?: AppPageDebugLogger;
@@ -42,6 +50,7 @@ type FinalizeAppPageHtmlCacheResponseOptions = {
   omitPendingDynamicCacheState?: boolean;
   preserveClientResponseHeaders?: boolean;
   expireSeconds?: number;
+  isStaticEligible: boolean;
   revalidateSeconds: number | null;
   linkHeader: string | null;
   waitUntil?: (promise: Promise<void>) => void;
@@ -52,7 +61,7 @@ type ScheduleAppPageRscCacheWriteOptions = {
   cleanPathname: string;
   consumeDynamicUsage: () => boolean;
   consumeRenderObservationState?: () => AppPageRenderObservationState;
-  createRscRenderObservation?: BuildAppPageCacheRenderObservation;
+  createRscRenderObservation: BuildAppPageCacheRenderObservation;
   dynamicUsedDuringBuild: boolean;
   getPageTags: () => string[];
   getRequestCacheLife?: () => AppPageRequestCacheLife | null;
@@ -66,6 +75,7 @@ type ScheduleAppPageRscCacheWriteOptions = {
   renderMode?: AppRscRenderMode;
   preserveClientResponseHeaders?: boolean;
   expireSeconds?: number;
+  isStaticEligible: boolean;
   revalidateSeconds: number | null;
   waitUntil?: (promise: Promise<void>) => void;
 };
@@ -73,9 +83,8 @@ type ScheduleAppPageRscCacheWriteOptions = {
  * Complete probe/admission classification for an App Page response that does
  * not enter the ISR cache-write path. Ordinary requests pass through unchanged.
  */
-declare function finalizeAppPageCacheabilityEvaluationResponse(response: Response, options: FinalizeAppPageCacheabilityEvaluationOptions): Response;
-declare function finalizeAppPageHtmlCacheResponse(response: Response, options: FinalizeAppPageHtmlCacheResponseOptions): Response;
-declare function finalizeAppPageRscCacheResponse(response: Response, options: ScheduleAppPageRscCacheWriteOptions): Response;
-declare function scheduleAppPageRscCacheWrite(options: ScheduleAppPageRscCacheWriteOptions): boolean;
-//#endregion
-export { finalizeAppPageCacheabilityEvaluationResponse, finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, scheduleAppPageRscCacheWrite };
+export declare function finalizeAppPageCacheabilityEvaluationResponse(response: Response, options: FinalizeAppPageCacheabilityEvaluationOptions): Response;
+export declare function finalizeAppPageHtmlCacheResponse(response: Response, options: FinalizeAppPageHtmlCacheResponseOptions): Response;
+export declare function finalizeAppPageRscCacheResponse(response: Response, options: ScheduleAppPageRscCacheWriteOptions): Response;
+export declare function scheduleAppPageRscCacheWrite(options: ScheduleAppPageRscCacheWriteOptions): boolean;
+//#endregion

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

@@ -1,23 +1,26 @@
 import { NEXTJS_CACHE_HEADER, VINEXT_CACHE_HEADER } from "./headers.js";
+import { getCdnCacheAdapter } from "../shims/cdn-cache.js";
+import { captureRouteCacheabilityResponsePolicy, deferRouteCacheability, isRouteCacheabilityEvaluation } from "../shims/cacheability-classification.js";
+import { NO_STORE_CACHE_CONTROL, STATIC_CACHE_CONTROL, applyCdnResponseHeaders, buildRevalidateCacheControl, captureCdnResponsePolicyHeaders, hasExplicitNonCacheableResponsePolicy } from "./cache-control.js";
+import { buildAppPageCacheValue, isrCacheControl, resolveRouteExpireSeconds } from "./isr-cache.js";
 import { resolveClientStaleTimeSeconds } from "../utils/cache-control-metadata.js";
-import { NO_STORE_CACHE_CONTROL, STATIC_CACHE_CONTROL, applyCdnResponseHeaders, buildRevalidateCacheControl, hasExplicitNonCacheableResponsePolicy } from "./cache-control.js";
-import { buildAppPageCacheValue, isrCacheControl } from "./isr-cache.js";
 import { setCacheStateHeaders } from "./cache-headers.js";
 import { readStreamAsText } from "../utils/text-stream.js";
+import { deferUntilStreamConsumed } from "./defer-until-stream-consumed.js";
 import { markFrameworkLinkHeaders } from "./app-response-header-provenance.js";
-import { captureRouteCacheabilityResponsePolicy, deferRouteCacheability, isRouteCacheabilityEvaluation } from "../shims/cacheability-classification.js";
+import { hasQueryInvariantRenderProof } from "./cache-proof.js";
 import { createEmptyAppPageRenderObservationState } from "./app-page-render-observation.js";
-import { deferUntilStreamConsumed } from "./defer-until-stream-consumed.js";
 //#region src/server/app-page-cache-finalizer.ts
 function applyPendingDynamicCdnHeaders(headers, tags, options = {}) {
+	const cacheable = headers.get("Cache-Control") ?? "";
 	applyCdnResponseHeaders(headers, {
-		cacheControl: headers.get("Cache-Control") ?? "",
+		cacheControl: cacheable,
 		pendingDynamicCheck: true,
 		tags
 	});
 	finalizePendingCacheStateHeaders(headers, options);
 }
-function applyUncacheableRscVariantNoStoreHeaders(headers, options = {}) {
+function applyUncacheableVariantNoStoreHeaders(headers, options = {}) {
 	applyCdnResponseHeaders(headers, { cacheControl: NO_STORE_CACHE_CONTROL });
 	finalizePendingCacheStateHeaders(headers, {
 		...options,
@@ -35,10 +38,9 @@ function finalizePendingCacheStateHeaders(headers, options = {}) {
 }
 function resolveAppPageCacheControl(options) {
 	let revalidateSeconds = options.revalidateSeconds;
-	let expireSeconds = options.expireSeconds;
 	const requestCacheLife = options.requestCacheLife;
 	if (requestCacheLife?.revalidate !== void 0) revalidateSeconds = revalidateSeconds === null ? requestCacheLife.revalidate : Math.min(revalidateSeconds, requestCacheLife.revalidate);
-	if (requestCacheLife?.expire !== void 0) expireSeconds = requestCacheLife.expire;
+	const expireSeconds = requestCacheLife?.expire ?? resolveRouteExpireSeconds(revalidateSeconds, options.expireSeconds);
 	if (revalidateSeconds === null || Number.isNaN(revalidateSeconds) || revalidateSeconds <= 0) return null;
 	return isrCacheControl(revalidateSeconds, {
 		expireSeconds,
@@ -52,17 +54,22 @@ function finalizeEvaluatedAppPageResponse(response, options) {
 	if (!isRouteCacheabilityEvaluation()) return null;
 	const complete = deferRouteCacheability();
 	if (!complete) return response;
-	captureRouteCacheabilityResponsePolicy(response.headers);
+	captureRouteCacheabilityResponsePolicy(captureCdnResponsePolicyHeaders(response.headers));
 	let completed = false;
 	const finish = () => {
 		if (completed) return;
 		completed = true;
+		const observationState = options.consumeRenderObservationState?.();
 		let outcome;
 		if (options.capturedDynamicUsageBeforeContextCleanup?.() === true || options.consumeDynamicUsage()) outcome = {
 			cacheable: false,
 			dynamicUsage: true,
 			reason: "dynamic API used during render"
 		};
+		else if (options.isStaticEligible === false) outcome = {
+			cacheable: false,
+			reason: "route is not statically generated"
+		};
 		else if (response.headers.has("set-cookie") || hasExplicitNonCacheableResponsePolicy(response.headers)) outcome = {
 			cacheable: false,
 			reason: "response explicitly opts out of shared caching"
@@ -76,13 +83,13 @@ function finalizeEvaluatedAppPageResponse(response, options) {
 			outcome = cacheControl ? {
 				cacheable: true,
 				cacheControl: appPageCacheControlHeader(cacheControl),
+				...observationState && !observationState.requestApis.includes("searchParams") ? { searchParamsUnread: true } : {},
 				tags: options.getPageTags()
 			} : {
 				cacheable: false,
 				reason: "render did not produce a cache policy"
 			};
 		}
-		options.consumeRenderObservationState?.();
 		complete(outcome);
 	};
 	if (!response.body) {
@@ -105,9 +112,25 @@ function finalizeAppPageCacheabilityEvaluationResponse(response, options) {
 function finalizeAppPageHtmlCacheResponse(response, options) {
 	const probeResponse = finalizeEvaluatedAppPageResponse(response, options);
 	if (probeResponse) {
-		options.capturedRscDataPromise?.catch(() => {});
+		if (options.capturedRscDataPromise) {
+			const adapter = getCdnCacheAdapter();
+			if (adapter.captureAppPageRscData) adapter.captureAppPageRscData(options.capturedRscDataPromise);
+			else options.capturedRscDataPromise.catch(() => {});
+		}
 		return probeResponse;
 	}
+	if (options.bypassInterceptionContextCache === true) {
+		options.capturedRscDataPromise?.catch(() => {});
+		const headers = new Headers(response.headers);
+		applyUncacheableVariantNoStoreHeaders(headers, { omitCacheState: options.omitPendingDynamicCacheState === true });
+		const clientResponse = new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers
+		});
+		markFrameworkLinkHeaders(clientResponse.headers, options.linkHeader);
+		return clientResponse;
+	}
 	if (!response.body) return response;
 	const [streamForClient, streamForCache] = response.body.tee();
 	const htmlKey = options.isrHtmlKey(options.cleanPathname);
@@ -116,7 +139,7 @@ function finalizeAppPageHtmlCacheResponse(response, options) {
 	if (options.preserveClientResponseHeaders !== true) applyPendingDynamicCdnHeaders(clientHeaders, options.getPageTags(), { omitCacheState: options.omitPendingDynamicCacheState === true });
 	const cachePromise = (async () => {
 		try {
-			const cachedHtml = await readStreamAsText(streamForCache);
+			let cachedHtml = await readStreamAsText(streamForCache);
 			if (options.capturedDynamicUsageBeforeContextCleanup?.() === true || options.consumeDynamicUsage()) {
 				options.isrDebug?.("HTML cache write skipped (dynamic usage during render)", htmlKey);
 				return;
@@ -130,17 +153,25 @@ function finalizeAppPageHtmlCacheResponse(response, options) {
 				options.isrDebug?.("HTML cache write skipped (no cache policy)", htmlKey);
 				return;
 			}
+			if (options.clientTraceMetadataMarker) {
+				const { stripClientTraceMetadataBlock } = await import("./client-trace-metadata.js");
+				cachedHtml = stripClientTraceMetadataBlock(cachedHtml, options.clientTraceMetadataMarker);
+			}
 			const pageTags = options.getPageTags();
 			const observationState = options.consumeRenderObservationState?.() ?? createEmptyAppPageRenderObservationState();
-			const htmlRenderObservation = options.createHtmlRenderObservation?.({
+			const htmlRenderObservation = options.createHtmlRenderObservation({
 				cacheTags: pageTags,
 				state: observationState
 			});
-			const rscRenderObservation = options.createRscRenderObservation?.({
+			const rscRenderObservation = options.createRscRenderObservation({
 				cacheTags: pageTags,
 				state: observationState
 			});
 			const linkHeader = options.linkHeader;
+			if (!hasQueryInvariantRenderProof(htmlRenderObservation) || !hasQueryInvariantRenderProof(rscRenderObservation)) {
+				options.isrDebug?.("HTML cache write skipped (searchParams not proven unread)", htmlKey);
+				return;
+			}
 			const writes = [options.isrSet(htmlKey, buildAppPageCacheValue(cachedHtml, void 0, 200, htmlRenderObservation, linkHeader ? { link: linkHeader } : void 0), {
 				cacheControl,
 				tags: pageTags
@@ -174,7 +205,7 @@ function finalizeAppPageRscCacheResponse(response, options) {
 	const isUncacheableVariant = Boolean(options.mountedSlotsHeader) || options.bypassInterceptionContextCache === true;
 	if (options.preserveClientResponseHeaders === true && !isUncacheableVariant) return response;
 	const clientHeaders = new Headers(response.headers);
-	if (isUncacheableVariant) applyUncacheableRscVariantNoStoreHeaders(clientHeaders, { omitCacheState: options.omitPendingDynamicCacheState === true });
+	if (isUncacheableVariant) applyUncacheableVariantNoStoreHeaders(clientHeaders, { omitCacheState: options.omitPendingDynamicCacheState === true });
 	else applyPendingDynamicCdnHeaders(clientHeaders, options.getPageTags(), { omitCacheState: options.omitPendingDynamicCacheState === true });
 	return new Response(response.body, {
 		status: response.status,
@@ -204,10 +235,14 @@ function scheduleAppPageRscCacheWrite(options) {
 			}
 			const pageTags = options.getPageTags();
 			const observationState = options.consumeRenderObservationState?.() ?? createEmptyAppPageRenderObservationState();
-			const rscRenderObservation = options.createRscRenderObservation?.({
+			const rscRenderObservation = options.createRscRenderObservation({
 				cacheTags: pageTags,
 				state: observationState
 			});
+			if (!hasQueryInvariantRenderProof(rscRenderObservation)) {
+				options.isrDebug?.("RSC cache write skipped (searchParams not proven unread)", rscKey);
+				return;
+			}
 			await options.isrSet(rscKey, buildAppPageCacheValue("", rscData, 200, rscRenderObservation), {
 				cacheControl,
 				tags: pageTags

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

@@ -12,7 +12,7 @@ type AppPageCacheRoute = {
   pattern: string;
   routeSegments: readonly string[];
 };
-type RenderAppPageCacheArtifactsOptions = {
+export type RenderAppPageCacheArtifactsOptions = {
   basePath?: string;
   captureRscData: boolean;
   cleanPathname: string;
@@ -25,7 +25,9 @@ type RenderAppPageCacheArtifactsOptions = {
   loadSsrHandler: () => Promise<AppPageSsrHandler>;
   mountedSlotsHeader?: string | null;
   navigationParams: Record<string, unknown>;
+  isCapturedRscError?: (error: unknown) => boolean;
   onError: (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
+  onSsrError?: (error: unknown) => unknown;
   reactMaxHeadersLength?: number;
   renderToReadableStream: (element: AppPageRenderableElement, options: {
     onError: (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
@@ -35,7 +37,7 @@ type RenderAppPageCacheArtifactsOptions = {
   waitForAllReady?: boolean;
   isForceStatic?: boolean;
 };
-type RenderAppPageCacheArtifactsResult = {
+export type RenderAppPageCacheArtifactsResult = {
   cacheControl?: CacheControlMetadata;
   html: string;
   htmlRenderObservation: ReturnType<typeof createAppPageRenderObservation>;
@@ -43,6 +45,8 @@ type RenderAppPageCacheArtifactsResult = {
   rscData?: ArrayBuffer;
   rscRenderObservation?: ReturnType<typeof createAppPageRenderObservation>;
   tags: string[];
+  /** The render used a dynamic API, so its output must not be stored. */
+  usedDynamicApi: boolean;
 };
 /**
  * Render an App page element to HTML (and optionally its RSC payload) for cache
@@ -50,6 +54,5 @@ type RenderAppPageCacheArtifactsResult = {
  * cache-tag construction used by both normal ISR revalidation and PPR fallback
  * shell regeneration.
  */
-declare function renderAppPageCacheArtifacts(options: RenderAppPageCacheArtifactsOptions): Promise<RenderAppPageCacheArtifactsResult>;
-//#endregion
-export { RenderAppPageCacheArtifactsOptions, RenderAppPageCacheArtifactsResult, renderAppPageCacheArtifacts };
+export declare function renderAppPageCacheArtifacts(options: RenderAppPageCacheArtifactsOptions): Promise<RenderAppPageCacheArtifactsResult>;
+//#endregion