@qzsy/vinext 0.1.7

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

@@ -0,0 +1,102 @@
+//#region src/server/app-page-boundary.d.ts
+type AppPageParams = Record<string, string | string[]>;
+type ResolveAppPageHttpAccessBoundaryComponentOptions<TModule, TComponent> = {
+  getDefaultExport: (module: TModule | null | undefined) => TComponent | null | undefined;
+  rootForbiddenModule?: TModule | null;
+  rootNotFoundModule?: TModule | null;
+  rootUnauthorizedModule?: TModule | null;
+  routeForbiddenModule?: TModule | null;
+  routeNotFoundModule?: TModule | null;
+  routeUnauthorizedModule?: TModule | null;
+  statusCode: number;
+};
+type ResolveAppPageHttpAccessBoundaryModuleOptions<TModule> = {
+  rootForbiddenModule?: TModule | null;
+  rootNotFoundModule?: TModule | null;
+  rootUnauthorizedModule?: TModule | null;
+  routeForbiddenModule?: TModule | null;
+  routeNotFoundModule?: TModule | null;
+  routeUnauthorizedModule?: TModule | null;
+  statusCode: number;
+};
+type ResolveAppPageParentHttpAccessBoundaryModuleOptions<TModule> = {
+  layoutIndex: number;
+  rootForbiddenModule?: TModule | null;
+  rootNotFoundModule?: TModule | null;
+  rootUnauthorizedModule?: TModule | null;
+  routeForbiddenModules?: readonly (TModule | null | undefined)[] | null;
+  routeNotFoundModules?: readonly (TModule | null | undefined)[] | null;
+  routeUnauthorizedModules?: readonly (TModule | null | undefined)[] | null;
+  statusCode: number;
+};
+type ResolveAppPageErrorBoundaryOptions<TModule, TComponent> = {
+  getDefaultExport: (module: TModule | null | undefined) => TComponent | null | undefined;
+  globalErrorModule?: TModule | null;
+  errorModules?: readonly (TModule | null | undefined)[] | null;
+  layoutErrorModules?: readonly (TModule | null | undefined)[] | null;
+  pageErrorModule?: TModule | null;
+};
+type ResolveAppPageErrorBoundaryResult<TComponent> = {
+  component: TComponent | null;
+  isGlobalError: boolean;
+};
+type WrapAppPageBoundaryElementOptions<TElement, TLayoutModule, TLayoutComponent, TChildSegments, TGlobalErrorComponent> = {
+  element: TElement;
+  getDefaultExport: (module: TLayoutModule | null | undefined) => TLayoutComponent | null | undefined;
+  globalErrorComponent?: TGlobalErrorComponent | null;
+  includeGlobalErrorBoundary: boolean;
+  isRscRequest: boolean;
+  layoutModules: readonly (TLayoutModule | null | undefined)[];
+  layoutTreePositions?: readonly number[] | null;
+  makeThenableParams: (params: AppPageParams) => unknown;
+  matchedParams: AppPageParams;
+  renderErrorBoundary: (component: TGlobalErrorComponent, children: TElement) => TElement;
+  renderLayout: (component: TLayoutComponent, children: TElement, params: unknown) => TElement;
+  renderLayoutSegmentProvider?: (segmentMap: {
+    children: TChildSegments;
+  }, children: TElement) => TElement;
+  resolveChildSegments?: (routeSegments: readonly string[], treePosition: number, params: AppPageParams) => TChildSegments;
+  routeSegments?: readonly string[];
+  skipLayoutWrapping?: boolean;
+};
+type AppPageBoundaryOnError = (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
+type RenderAppPageBoundaryResponseOptions<TElement> = {
+  createHtmlResponse: (rscStream: ReadableStream<Uint8Array>, status: number) => Promise<Response>;
+  createRscOnErrorHandler: () => AppPageBoundaryOnError;
+  element: TElement;
+  isEdgeRuntime?: boolean;
+  isRscRequest: boolean;
+  middlewareHeaders?: Headers | null;
+  renderToReadableStream: (element: TElement, options: {
+    onError: AppPageBoundaryOnError;
+  }) => 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;
+/**
+ * Like {@link resolveAppPageParentHttpAccessBoundaryModule}, but also returns
+ * the layout index that owns the resolved boundary so callers can slice the
+ * layouts array to skip rendering layouts below the boundary owner.
+ *
+ * `layoutIndex` is the per-layout index where the boundary lives, or `null` if
+ * the resolved boundary is the root module (which conceptually sits above all
+ * layouts when no layout-level boundary is present).
+ *
+ * Used by the page-error fast path to make `forbidden()` / `unauthorized()` /
+ * `notFound()` escalate past intermediate layouts that lack a boundary file,
+ * matching Next.js's `create-component-tree.tsx` behavior where the nearest
+ * ancestor boundary owns the fallback subtree.
+ *
+ * @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>): {
+  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 };

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

@@ -0,0 +1,120 @@
+import { runWithFetchDedupe } from "../shims/fetch-cache.js";
+import { resolveAppPageSegmentParams } from "./app-page-params.js";
+import { VINEXT_RSC_CONTENT_TYPE, VINEXT_RSC_VARY_HEADER, applyRscCompatibilityIdHeader } from "./app-rsc-cache-busting.js";
+import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
+import { applyEdgeRuntimeHeader } from "./app-page-response.js";
+//#region src/server/app-page-boundary.ts
+function resolveAppPageHttpAccessBoundaryComponent(options) {
+	return options.getDefaultExport(resolveAppPageHttpAccessBoundaryModule({
+		rootForbiddenModule: options.rootForbiddenModule,
+		rootNotFoundModule: options.rootNotFoundModule,
+		rootUnauthorizedModule: options.rootUnauthorizedModule,
+		routeForbiddenModule: options.routeForbiddenModule,
+		routeNotFoundModule: options.routeNotFoundModule,
+		routeUnauthorizedModule: options.routeUnauthorizedModule,
+		statusCode: options.statusCode
+	})) ?? null;
+}
+function resolveAppPageHttpAccessBoundaryModule(options) {
+	let boundaryModule;
+	if (options.statusCode === 403) boundaryModule = options.routeForbiddenModule ?? options.rootForbiddenModule;
+	else if (options.statusCode === 401) boundaryModule = options.routeUnauthorizedModule ?? options.rootUnauthorizedModule;
+	else boundaryModule = options.routeNotFoundModule ?? options.rootNotFoundModule;
+	return boundaryModule ?? null;
+}
+function resolveAppPageParentHttpAccessBoundaryModule(options) {
+	return resolveAppPageParentHttpAccessBoundary(options).module;
+}
+/**
+* Like {@link resolveAppPageParentHttpAccessBoundaryModule}, but also returns
+* the layout index that owns the resolved boundary so callers can slice the
+* layouts array to skip rendering layouts below the boundary owner.
+*
+* `layoutIndex` is the per-layout index where the boundary lives, or `null` if
+* the resolved boundary is the root module (which conceptually sits above all
+* layouts when no layout-level boundary is present).
+*
+* Used by the page-error fast path to make `forbidden()` / `unauthorized()` /
+* `notFound()` escalate past intermediate layouts that lack a boundary file,
+* matching Next.js's `create-component-tree.tsx` behavior where the nearest
+* ancestor boundary owns the fallback subtree.
+*
+* @see https://github.com/vercel/next.js/blob/canary/packages/next/src/server/app-render/create-component-tree.tsx
+*/
+function resolveAppPageParentHttpAccessBoundary(options) {
+	let routeModules = options.routeNotFoundModules;
+	let rootModule = options.rootNotFoundModule;
+	if (options.statusCode === 403) {
+		routeModules = options.routeForbiddenModules;
+		rootModule = options.rootForbiddenModule;
+	} else if (options.statusCode === 401) {
+		routeModules = options.routeUnauthorizedModules;
+		rootModule = options.rootUnauthorizedModule;
+	}
+	if (routeModules) for (let index = options.layoutIndex - 1; index >= 0; index--) {
+		const module = routeModules[index];
+		if (module) return {
+			module,
+			layoutIndex: index
+		};
+	}
+	return {
+		module: rootModule ?? null,
+		layoutIndex: null
+	};
+}
+function resolveAppPageErrorBoundary(options) {
+	const pageErrorComponent = options.getDefaultExport(options.pageErrorModule);
+	if (pageErrorComponent) return {
+		component: pageErrorComponent,
+		isGlobalError: false
+	};
+	const segmentErrorModules = options.errorModules ?? options.layoutErrorModules;
+	if (segmentErrorModules) for (let index = segmentErrorModules.length - 1; index >= 0; index--) {
+		const segmentErrorComponent = options.getDefaultExport(segmentErrorModules[index]);
+		if (segmentErrorComponent) return {
+			component: segmentErrorComponent,
+			isGlobalError: false
+		};
+	}
+	const globalErrorComponent = options.getDefaultExport(options.globalErrorModule);
+	return {
+		component: globalErrorComponent ?? null,
+		isGlobalError: Boolean(globalErrorComponent)
+	};
+}
+function wrapAppPageBoundaryElement(options) {
+	let element = options.element;
+	if (!options.skipLayoutWrapping) for (let index = options.layoutModules.length - 1; index >= 0; index--) {
+		const layoutComponent = options.getDefaultExport(options.layoutModules[index]);
+		if (!layoutComponent) continue;
+		const treePosition = options.layoutTreePositions ? options.layoutTreePositions[index] : 0;
+		const asyncParams = options.makeThenableParams(resolveAppPageSegmentParams(options.routeSegments, treePosition, options.matchedParams));
+		element = options.renderLayout(layoutComponent, element, asyncParams);
+		if (options.isRscRequest && options.renderLayoutSegmentProvider && options.resolveChildSegments) {
+			const childSegments = options.resolveChildSegments(options.routeSegments ?? [], treePosition, options.matchedParams);
+			element = options.renderLayoutSegmentProvider({ children: childSegments }, element);
+		}
+	}
+	if (options.isRscRequest && options.includeGlobalErrorBoundary && options.globalErrorComponent) element = options.renderErrorBoundary(options.globalErrorComponent, element);
+	return element;
+}
+async function renderAppPageBoundaryResponse(options) {
+	const rscStream = runWithFetchDedupe(() => options.renderToReadableStream(options.element, { onError: options.createRscOnErrorHandler() }));
+	if (options.isRscRequest) {
+		const headers = new Headers({
+			"Content-Type": VINEXT_RSC_CONTENT_TYPE,
+			Vary: VINEXT_RSC_VARY_HEADER
+		});
+		applyEdgeRuntimeHeader(headers, options.isEdgeRuntime);
+		mergeMiddlewareResponseHeaders(headers, options.middlewareHeaders ?? null);
+		applyRscCompatibilityIdHeader(headers);
+		return new Response(rscStream, {
+			status: options.status,
+			headers
+		});
+	}
+	return options.createHtmlResponse(rscStream, options.status);
+}
+//#endregion
+export { renderAppPageBoundaryResponse, resolveAppPageErrorBoundary, resolveAppPageHttpAccessBoundaryComponent, resolveAppPageHttpAccessBoundaryModule, resolveAppPageParentHttpAccessBoundary, resolveAppPageParentHttpAccessBoundaryModule, wrapAppPageBoundaryElement };

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

@@ -0,0 +1,62 @@
+import { RenderObservation } from "./cache-proof.js";
+import { CachedAppPageValue } from "../shims/cache-handler.js";
+import { AppRscRenderMode } from "./app-rsc-render-mode.js";
+import { AppPageRenderObservationState } from "./app-page-render-observation.js";
+
+//#region src/server/app-page-cache-finalizer.d.ts
+type AppPageDebugLogger = (event: string, detail: string) => void;
+type AppPageCacheSetter = (key: string, data: CachedAppPageValue, revalidateSeconds: number, tags: string[], expireSeconds?: number) => Promise<void>;
+type AppPageRscCacheKeyBuilder = (pathname: string, mountedSlotsHeader?: string | null, renderMode?: AppRscRenderMode, interceptionContext?: string | null) => string;
+type AppPageRequestCacheLife = {
+  revalidate?: number;
+  expire?: number;
+};
+type BuildAppPageCacheRenderObservation = (input: {
+  cacheTags: readonly string[];
+  state: AppPageRenderObservationState;
+}) => RenderObservation;
+type FinalizeAppPageHtmlCacheResponseOptions = {
+  capturedDynamicUsageBeforeContextCleanup?: () => boolean;
+  capturedRscDataPromise: Promise<ArrayBuffer> | null;
+  cleanPathname: string;
+  consumeDynamicUsage: () => boolean;
+  consumeRenderObservationState?: () => AppPageRenderObservationState;
+  createHtmlRenderObservation?: BuildAppPageCacheRenderObservation;
+  createRscRenderObservation?: BuildAppPageCacheRenderObservation;
+  getPageTags: () => string[];
+  getRequestCacheLife?: () => AppPageRequestCacheLife | null;
+  isrDebug?: AppPageDebugLogger;
+  isrHtmlKey: (pathname: string) => string;
+  isrRscKey: AppPageRscCacheKeyBuilder;
+  isrSet: AppPageCacheSetter;
+  interceptionContext?: string | null;
+  preserveClientResponseHeaders?: boolean;
+  expireSeconds?: number;
+  revalidateSeconds: number | null;
+  waitUntil?: (promise: Promise<void>) => void;
+};
+type ScheduleAppPageRscCacheWriteOptions = {
+  capturedRscDataPromise: Promise<ArrayBuffer> | null;
+  cleanPathname: string;
+  consumeDynamicUsage: () => boolean;
+  consumeRenderObservationState?: () => AppPageRenderObservationState;
+  createRscRenderObservation?: BuildAppPageCacheRenderObservation;
+  dynamicUsedDuringBuild: boolean;
+  getPageTags: () => string[];
+  getRequestCacheLife?: () => AppPageRequestCacheLife | null;
+  isrDebug?: AppPageDebugLogger;
+  isrRscKey: AppPageRscCacheKeyBuilder;
+  isrSet: AppPageCacheSetter;
+  interceptionContext?: string | null;
+  mountedSlotsHeader?: string | null;
+  renderMode?: AppRscRenderMode;
+  preserveClientResponseHeaders?: boolean;
+  expireSeconds?: number;
+  revalidateSeconds: number | null;
+  waitUntil?: (promise: Promise<void>) => void;
+};
+declare function finalizeAppPageHtmlCacheResponse(response: Response, options: FinalizeAppPageHtmlCacheResponseOptions): Response;
+declare function finalizeAppPageRscCacheResponse(response: Response, options: ScheduleAppPageRscCacheWriteOptions): Response;
+declare function scheduleAppPageRscCacheWrite(options: ScheduleAppPageRscCacheWriteOptions): boolean;
+//#endregion
+export { finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, scheduleAppPageRscCacheWrite };

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

@@ -0,0 +1,122 @@
+import { setCacheStateHeaders } from "./cache-headers.js";
+import { applyCdnResponseHeaders } from "./cache-control.js";
+import { buildAppPageCacheValue } from "./isr-cache.js";
+import { readStreamAsText } from "../utils/text-stream.js";
+import { createEmptyAppPageRenderObservationState } from "./app-page-render-observation.js";
+//#region src/server/app-page-cache-finalizer.ts
+function applyPendingDynamicCdnHeaders(headers, tags) {
+	applyCdnResponseHeaders(headers, {
+		cacheControl: headers.get("Cache-Control") ?? "",
+		pendingDynamicCheck: true,
+		tags
+	});
+	setCacheStateHeaders(headers, "MISS");
+}
+function resolveAppPageCacheWritePolicy(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;
+	if (revalidateSeconds === null || Number.isNaN(revalidateSeconds) || revalidateSeconds <= 0) return null;
+	return {
+		expireSeconds,
+		revalidateSeconds
+	};
+}
+function finalizeAppPageHtmlCacheResponse(response, options) {
+	if (!response.body) return response;
+	const [streamForClient, streamForCache] = response.body.tee();
+	const htmlKey = options.isrHtmlKey(options.cleanPathname);
+	const rscKey = options.isrRscKey(options.cleanPathname, null, void 0, options.interceptionContext);
+	const clientHeaders = new Headers(response.headers);
+	if (options.preserveClientResponseHeaders !== true) applyPendingDynamicCdnHeaders(clientHeaders, options.getPageTags());
+	const cachePromise = (async () => {
+		try {
+			const cachedHtml = await readStreamAsText(streamForCache);
+			if (options.capturedDynamicUsageBeforeContextCleanup?.() === true || options.consumeDynamicUsage()) {
+				options.isrDebug?.("HTML cache write skipped (dynamic usage during render)", htmlKey);
+				return;
+			}
+			const cachePolicy = resolveAppPageCacheWritePolicy({
+				expireSeconds: options.expireSeconds,
+				requestCacheLife: options.getRequestCacheLife?.(),
+				revalidateSeconds: options.revalidateSeconds
+			});
+			if (!cachePolicy) {
+				options.isrDebug?.("HTML cache write skipped (no cache policy)", htmlKey);
+				return;
+			}
+			const pageTags = options.getPageTags();
+			const observationState = options.consumeRenderObservationState?.() ?? createEmptyAppPageRenderObservationState();
+			const htmlRenderObservation = options.createHtmlRenderObservation?.({
+				cacheTags: pageTags,
+				state: observationState
+			});
+			const rscRenderObservation = options.createRscRenderObservation?.({
+				cacheTags: pageTags,
+				state: observationState
+			});
+			const writes = [options.isrSet(htmlKey, buildAppPageCacheValue(cachedHtml, void 0, 200, htmlRenderObservation), cachePolicy.revalidateSeconds, pageTags, cachePolicy.expireSeconds)];
+			if (options.capturedRscDataPromise) writes.push(options.capturedRscDataPromise.then((rscData) => options.isrSet(rscKey, buildAppPageCacheValue("", rscData, 200, rscRenderObservation), cachePolicy.revalidateSeconds, pageTags, cachePolicy.expireSeconds)));
+			await Promise.all(writes);
+			options.isrDebug?.("HTML cache written", htmlKey);
+		} catch (cacheError) {
+			console.error("[vinext] ISR cache write error:", cacheError);
+		}
+	})();
+	options.waitUntil?.(cachePromise);
+	return new Response(streamForClient, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: clientHeaders
+	});
+}
+function finalizeAppPageRscCacheResponse(response, options) {
+	if (!scheduleAppPageRscCacheWrite(options)) return response;
+	if (options.preserveClientResponseHeaders === true) return response;
+	const clientHeaders = new Headers(response.headers);
+	applyPendingDynamicCdnHeaders(clientHeaders, options.getPageTags());
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: clientHeaders
+	});
+}
+function scheduleAppPageRscCacheWrite(options) {
+	const capturedRscDataPromise = options.capturedRscDataPromise;
+	if (!capturedRscDataPromise || options.dynamicUsedDuringBuild) return false;
+	const rscKey = options.isrRscKey(options.cleanPathname, options.mountedSlotsHeader, options.renderMode, options.interceptionContext);
+	const cachePromise = (async () => {
+		try {
+			const rscData = await capturedRscDataPromise;
+			if (options.consumeDynamicUsage()) {
+				options.isrDebug?.("RSC cache write skipped (dynamic usage during render)", rscKey);
+				return;
+			}
+			const cachePolicy = resolveAppPageCacheWritePolicy({
+				expireSeconds: options.expireSeconds,
+				requestCacheLife: options.getRequestCacheLife?.(),
+				revalidateSeconds: options.revalidateSeconds
+			});
+			if (!cachePolicy) {
+				options.isrDebug?.("RSC cache write skipped (no cache policy)", rscKey);
+				return;
+			}
+			const pageTags = options.getPageTags();
+			const observationState = options.consumeRenderObservationState?.() ?? createEmptyAppPageRenderObservationState();
+			const rscRenderObservation = options.createRscRenderObservation?.({
+				cacheTags: pageTags,
+				state: observationState
+			});
+			await options.isrSet(rscKey, buildAppPageCacheValue("", rscData, 200, rscRenderObservation), cachePolicy.revalidateSeconds, pageTags, cachePolicy.expireSeconds);
+			options.isrDebug?.("RSC cache written", rscKey);
+		} catch (cacheError) {
+			console.error("[vinext] ISR RSC cache write error:", cacheError);
+		}
+	})();
+	options.waitUntil?.(cachePromise);
+	return true;
+}
+//#endregion
+export { finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, scheduleAppPageRscCacheWrite };

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

@@ -0,0 +1,53 @@
+import { CacheControlMetadata } from "../shims/cache-handler.js";
+import { NavigationContext } from "../shims/navigation-context-state.js";
+import { AppPageFontPreload } from "./app-page-execution.js";
+import { RootParams } from "../shims/root-params.js";
+import { AppPageSsrHandler } from "./app-page-stream.js";
+import { createAppPageRenderObservation } from "./app-page-render-observation.js";
+import { ReactNode } from "react";
+
+//#region src/server/app-page-cache-render.d.ts
+type AppPageRenderableElement = ReactNode | Record<string, ReactNode>;
+type AppPageCacheRoute = {
+  pattern: string;
+  routeSegments: readonly string[];
+};
+type RenderAppPageCacheArtifactsOptions = {
+  basePath?: string;
+  captureRscData: boolean;
+  cleanPathname: string;
+  clientTraceMetadata?: readonly string[];
+  element: AppPageRenderableElement;
+  getFontLinks: () => string[];
+  getFontPreloads: () => AppPageFontPreload[];
+  getFontStyles: () => string[];
+  getNavigationContext: () => NavigationContext | null;
+  loadSsrHandler: () => Promise<AppPageSsrHandler>;
+  mountedSlotsHeader?: string | null;
+  navigationParams: Record<string, unknown>;
+  onError: (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
+  reactMaxHeadersLength?: number;
+  renderToReadableStream: (element: AppPageRenderableElement, options: {
+    onError: (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
+  }) => ReadableStream<Uint8Array>;
+  rootParams?: RootParams;
+  route: AppPageCacheRoute;
+  waitForAllReady?: boolean;
+};
+type RenderAppPageCacheArtifactsResult = {
+  cacheControl?: CacheControlMetadata;
+  html: string;
+  htmlRenderObservation: ReturnType<typeof createAppPageRenderObservation>;
+  rscData?: ArrayBuffer;
+  rscRenderObservation?: ReturnType<typeof createAppPageRenderObservation>;
+  tags: string[];
+};
+/**
+ * Render an App page element to HTML (and optionally its RSC payload) for cache
+ * storage. Combines the RSC stream, SSR handler, observation consumption, and
+ * 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 };

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

@@ -0,0 +1,91 @@
+import { consumeDynamicUsage, consumeInvalidDynamicUsageError } 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 { teeAppPageRscStreamForCapture } from "./app-page-execution.js";
+import { consumeAppPageRenderObservationState, createAppPageHtmlOutputScope, createAppPageRenderObservation, createAppPageRscOutputScope } from "./app-page-render-observation.js";
+import { isAppSsrRenderResult } from "./app-page-stream.js";
+import { buildAppPageTags } from "./implicit-tags.js";
+//#region src/server/app-page-cache-render.ts
+/**
+* Render an App page element to HTML (and optionally its RSC payload) for cache
+* storage. Combines the RSC stream, SSR handler, observation consumption, and
+* cache-tag construction used by both normal ISR revalidation and PPR fallback
+* shell regeneration.
+*/
+async function renderAppPageCacheArtifacts(options) {
+	const rscCapture = teeAppPageRscStreamForCapture(options.renderToReadableStream(options.element, { onError: options.onError }), options.captureRscData);
+	const capturedRscDataRef = { value: null };
+	const htmlResult = await (await options.loadSsrHandler()).handleSsr(rscCapture.ssrStream, options.getNavigationContext(), {
+		links: options.getFontLinks(),
+		styles: options.getFontStyles(),
+		preloads: options.getFontPreloads()
+	}, {
+		basePath: options.basePath,
+		clientTraceMetadata: options.clientTraceMetadata,
+		reactMaxHeadersLength: options.reactMaxHeadersLength,
+		rootParams: options.rootParams,
+		waitForAllReady: options.waitForAllReady,
+		...rscCapture.sideStream ? {
+			sideStream: rscCapture.sideStream,
+			capturedRscDataRef
+		} : {}
+	});
+	const html = await readStreamAsText(isAppSsrRenderResult(htmlResult) ? htmlResult.htmlStream : htmlResult);
+	let rscData;
+	if (options.captureRscData) {
+		const capturedPromise = capturedRscDataRef.value;
+		if (!capturedPromise) throw new Error("[vinext] Expected captured RSC data while rendering app page cache artifacts");
+		rscData = await capturedPromise;
+	}
+	const cacheLife = _consumeRequestScopedCacheLife();
+	const tags = buildAppPageTags(options.cleanPathname, getCollectedFetchTags(), options.route.routeSegments);
+	const observationState = consumeAppPageRenderObservationState();
+	consumeInvalidDynamicUsageError();
+	consumeDynamicUsage();
+	const result = {
+		html,
+		htmlRenderObservation: createAppPageRenderObservation({
+			boundaryOutcome: { kind: "success" },
+			cacheability: "public",
+			cacheTags: tags,
+			cleanPathname: options.cleanPathname,
+			completeness: "complete",
+			output: createAppPageHtmlOutputScope({
+				element: options.element,
+				renderEpoch: null,
+				rootBoundaryId: null,
+				routePattern: options.route.pattern
+			}),
+			params: options.navigationParams,
+			state: observationState
+		}),
+		tags,
+		cacheControl: typeof cacheLife?.revalidate === "number" ? {
+			revalidate: cacheLife.revalidate,
+			expire: cacheLife.expire
+		} : void 0
+	};
+	if (options.captureRscData) {
+		result.rscData = rscData;
+		result.rscRenderObservation = createAppPageRenderObservation({
+			boundaryOutcome: { kind: "success" },
+			cacheability: "public",
+			cacheTags: tags,
+			cleanPathname: options.cleanPathname,
+			completeness: "complete",
+			output: createAppPageRscOutputScope({
+				element: options.element,
+				mountedSlotsHeader: options.mountedSlotsHeader,
+				renderEpoch: null,
+				rootBoundaryId: null,
+				routePattern: options.route.pattern
+			}),
+			params: options.navigationParams,
+			state: observationState
+		});
+	}
+	return result;
+}
+//#endregion
+export { renderAppPageCacheArtifacts };

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

@@ -0,0 +1,83 @@
+import { RenderObservation } from "./cache-proof.js";
+import { CacheControlMetadata, CachedAppPageValue } from "../shims/cache-handler.js";
+import { AppRscRenderMode } from "./app-rsc-render-mode.js";
+import { finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, scheduleAppPageRscCacheWrite } from "./app-page-cache-finalizer.js";
+import { ISRCacheEntry } from "./isr-cache.js";
+
+//#region src/server/app-page-cache.d.ts
+type AppPageDebugLogger = (event: string, detail: string) => void;
+type AppPageCacheGetter = (key: string) => Promise<ISRCacheEntry | null>;
+type AppPageCacheSetter = (key: string, data: CachedAppPageValue, revalidateSeconds: number, tags: string[], expireSeconds?: number) => Promise<void>;
+type AppPageBackgroundRegenerator = (key: string, renderFn: () => Promise<void>) => void;
+type AppPageRscCacheKeyBuilder = (pathname: string, mountedSlotsHeader?: string | null, renderMode?: AppRscRenderMode, interceptionContext?: string | null) => string;
+type AppPageCacheOutcomeMetric = Readonly<{
+  artifact: "html" | "rsc";
+  /**
+   * Internal cache lookup key for debugging and tests. Runtime telemetry sinks should hash or
+   * redact this value before export to avoid high-cardinality or user-derived labels.
+   */
+  cacheKey: string;
+  outcome: "hit" | "miss" | "stale";
+  reason: "empty-entry" | "no-entry" | "non-app-page-entry" | "query-variant-unproven" | "read-error" | "served" | "stale-empty-entry";
+}>;
+type AppPageCacheOutcomeRecorder = (metric: AppPageCacheOutcomeMetric) => void;
+type AppPageCacheRenderResult = {
+  cacheControl?: CacheControlMetadata;
+  html: string;
+  htmlRenderObservation?: RenderObservation;
+  rscData: ArrayBuffer;
+  rscRenderObservation?: RenderObservation;
+  tags: string[];
+};
+type BuildAppPageCachedResponseOptions = {
+  cacheControl?: CacheControlMetadata;
+  cacheState: "HIT" | "STALE";
+  expireSeconds?: number;
+  isEdgeRuntime?: boolean;
+  isRscRequest: boolean;
+  middlewareHeaders?: Headers | null;
+  middlewareStatus?: number | null;
+  mountedSlotsHeader?: string | null;
+  revalidateSeconds: number;
+};
+type ReadAppPageCacheResponseOptions = {
+  cleanPathname: string;
+  clearRequestContext: () => void;
+  isEdgeRuntime?: boolean;
+  isRscRequest: boolean;
+  isrDebug?: AppPageDebugLogger;
+  isrGet: AppPageCacheGetter;
+  isrHtmlKey: (pathname: string) => string;
+  isrRscKey: AppPageRscCacheKeyBuilder;
+  isrSet: AppPageCacheSetter;
+  interceptionContext?: string | null;
+  hasRequestSearchParams?: boolean;
+  middlewareHeaders?: Headers | null;
+  middlewareStatus?: number | null;
+  mountedSlotsHeader?: string | null;
+  recordCacheOutcome?: AppPageCacheOutcomeRecorder;
+  renderMode?: AppRscRenderMode;
+  expireSeconds?: number;
+  revalidateSeconds: number;
+  renderFreshPageForCache: () => Promise<AppPageCacheRenderResult>;
+  scheduleBackgroundRegeneration: AppPageBackgroundRegenerator;
+};
+type ReadAppPageFallbackShellCacheResponseOptions = {
+  clearRequestContext: () => void;
+  expireSeconds?: number;
+  fallbackPathname: string;
+  isEdgeRuntime?: boolean;
+  isrDebug?: AppPageDebugLogger;
+  isrGet: AppPageCacheGetter;
+  isrHtmlKey: (pathname: string) => string;
+  middlewareHeaders?: Headers | null;
+  middlewareStatus?: number | null;
+  revalidateSeconds: number;
+  rewriteHtml: (html: string) => string;
+};
+declare function buildAppPageCacheTags(pathname: string, extraTags: 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>;
+//#endregion
+export { AppPageCacheOutcomeMetric, buildAppPageCacheTags, buildAppPageCachedResponse, finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, readAppPageCacheResponse, readAppPageFallbackShellCacheResponse, scheduleAppPageRscCacheWrite };