vinext 0.1.2 → 0.1.4

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

@@ -1,14 +1,15 @@
+import { NEVER_CACHE_CONTROL } 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 } from "../shims/error-boundary.js";
 import { LayoutSegmentProvider } from "../shims/layout-segment-context.js";
 import { MetadataHead, ViewportHead } from "../shims/metadata.js";
 import { resolveAppPageSpecialError } from "./app-page-execution.js";
 import { resolveAppPageHead } from "./app-page-head.js";
-import { createAppPageLayoutEntries } from "./app-page-route-wiring.js";
+import { createAppPageLayoutEntries, createAppPageSourcePage } from "./app-page-route-wiring.js";
 import { buildClientHookErrorMessage } from "../shims/client-hook-error.js";
-import DefaultGlobalError from "../shims/default-global-error.js";
 import { renderAppPageBoundaryResponse, resolveAppPageErrorBoundary, resolveAppPageHttpAccessBoundaryModule, wrapAppPageBoundaryElement } from "./app-page-boundary.js";
 import { createAppPageFontData, renderAppPageHtmlResponse } from "./app-page-stream.js";
 import { Fragment, createElement } from "react";
@@ -76,12 +77,14 @@ function resolveHttpAccessFallbackHeadLayoutTreePositions(route, layoutModules)
 function createAppPageBoundaryRscPayload(options) {
 	const routeId = AppElementsWire.encodeRouteId(options.pathname, null);
 	const layoutEntries = createAppPageBoundaryLayoutEntries(options.route, options.layoutModules);
+	const sourcePageSegments = options.sourcePageSegments ?? options.route?.routeSegments;
 	return {
 		...AppElementsWire.createMetadataEntries({
 			interceptionContext: null,
 			layoutIds: layoutEntries.map((entry) => entry.id),
 			rootLayoutTreePath: layoutEntries[0]?.treePath ?? null,
-			routeId
+			routeId,
+			sourcePage: sourcePageSegments ? createAppPageSourcePage(sourcePageSegments) : null
 		}),
 		[routeId]: options.element
 	};
@@ -122,7 +125,8 @@ async function renderAppPageBoundaryElementResponse(options) {
 			element: options.element,
 			layoutModules: options.layoutModules,
 			pathname,
-			route: options.route
+			route: options.route,
+			sourcePageSegments: options.sourcePageSegments
 		}),
 		isEdgeRuntime: options.isEdgeRuntime,
 		isRscRequest: options.isRscRequest,
@@ -261,16 +265,25 @@ async function renderAppPageErrorBoundary(options) {
 			skipLayoutWrapping: errorBoundary.isGlobalError
 		});
 	};
-	const renderWith = (BoundaryComponent) => renderAppPageBoundaryElementResponse({
-		...options,
-		element: buildElement(BoundaryComponent),
-		initialDevServerError: rawError,
-		layoutModules,
-		navigationParams: matchedParams,
-		route: options.route,
-		routePattern: options.route?.pattern,
-		status: 200
-	});
+	const renderWith = async (BoundaryComponent) => {
+		const response = await renderAppPageBoundaryElementResponse({
+			...options,
+			element: buildElement(BoundaryComponent),
+			initialDevServerError: rawError,
+			layoutModules,
+			navigationParams: matchedParams,
+			route: options.route,
+			routePattern: options.route?.pattern,
+			status: errorBoundary.isGlobalError ? 500 : 200
+		});
+		if (errorBoundary.isGlobalError) {
+			response.headers.set("Cache-Control", NEVER_CACHE_CONTROL);
+			response.headers.delete("CDN-Cache-Control");
+			response.headers.delete("Cloudflare-CDN-Cache-Control");
+			response.headers.delete("Cache-Tag");
+		}
+		return response;
+	};
 	try {
 		return await renderWith(errorBoundary.component);
 	} catch (renderError) {

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

@@ -0,0 +1,53 @@
+import { CacheControlMetadata } from "../shims/cache.js";
+import { NavigationContext } from "../shims/navigation.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.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

@@ -1,8 +1,8 @@
 import { RenderObservation } from "./cache-proof.js";
 import { CacheControlMetadata, CachedAppPageValue } from "../shims/cache.js";
+import { AppPageRenderObservationState } from "./app-page-render-observation.js";
 import { AppRscRenderMode } from "./app-rsc-render-mode.js";
 import { ISRCacheEntry } from "./isr-cache.js";
-import { AppPageRenderObservationState } from "./app-page-render-observation.js";
 
 //#region src/server/app-page-cache.d.ts
 type AppPageDebugLogger = (event: string, detail: string) => void;
@@ -70,6 +70,19 @@ type ReadAppPageCacheResponseOptions = {
   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;
+};
 type FinalizeAppPageHtmlCacheResponseOptions = {
   capturedDynamicUsageBeforeContextCleanup?: () => boolean;
   capturedRscDataPromise: Promise<ArrayBuffer> | null;
@@ -113,8 +126,9 @@ type ScheduleAppPageRscCacheWriteOptions = {
 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>;
 declare function finalizeAppPageHtmlCacheResponse(response: Response, options: FinalizeAppPageHtmlCacheResponseOptions): Response;
 declare function finalizeAppPageRscCacheResponse(response: Response, options: ScheduleAppPageRscCacheWriteOptions): Response;
 declare function scheduleAppPageRscCacheWrite(options: ScheduleAppPageRscCacheWriteOptions): boolean;
 //#endregion
-export { AppPageCacheOutcomeMetric, buildAppPageCacheTags, buildAppPageCachedResponse, finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, readAppPageCacheResponse, scheduleAppPageRscCacheWrite };
+export { AppPageCacheOutcomeMetric, buildAppPageCacheTags, buildAppPageCachedResponse, finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, readAppPageCacheResponse, readAppPageFallbackShellCacheResponse, scheduleAppPageRscCacheWrite };

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

@@ -10,6 +10,7 @@ import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js
 import { applyEdgeRuntimeHeader } from "./app-page-response.js";
 import { hasCompleteNegativeRequestApiProof } from "./cache-proof.js";
 import { createEmptyAppPageRenderObservationState } from "./app-page-render-observation.js";
+import { isAppPprDynamicFallbackShellHtml } from "./app-ppr-fallback-shell.js";
 //#region src/server/app-page-cache.ts
 /**
 * Apply the CDN cache adapter's headers to a freshly-streamed response whose
@@ -121,6 +122,29 @@ function buildAppPageCachedResponse(cachedValue, options) {
 		headers: htmlHeaders
 	});
 }
+async function serveAppPageCachedHtml(options, transformValue) {
+	if (typeof options.cachedValue.html !== "string" || options.cachedValue.html.length === 0) {
+		if (options.cached?.isStale) options.scheduleRegeneration();
+		options.isrDebug?.(options.emptyDebugMessage, options.pathname);
+		return null;
+	}
+	const cacheState = options.cached?.isStale ? "STALE" : "HIT";
+	if (options.cached?.isStale) options.scheduleRegeneration();
+	const response = buildAppPageCachedResponse(transformValue ? transformValue(options.cachedValue) : options.cachedValue, {
+		cacheState,
+		cacheControl: options.cached?.value.cacheControl,
+		expireSeconds: options.expireSeconds,
+		isEdgeRuntime: options.isEdgeRuntime,
+		isRscRequest: false,
+		middlewareHeaders: options.middlewareHeaders,
+		middlewareStatus: options.middlewareStatus,
+		revalidateSeconds: options.revalidateSeconds
+	});
+	if (!response) return null;
+	options.isrDebug?.(`${cacheState} (${options.stateDebugLabel})`, options.pathname);
+	options.clearRequestContext();
+	return response;
+}
 async function readAppPageCacheResponse(options) {
 	const isrKey = options.isRscRequest ? options.isrRscKey(options.cleanPathname, options.mountedSlotsHeader, options.renderMode, options.interceptionContext) : options.isrHtmlKey(options.cleanPathname);
 	const artifact = options.isRscRequest ? "rsc" : "html";
@@ -239,6 +263,43 @@ async function readAppPageCacheResponse(options) {
 	}
 	return null;
 }
+async function readAppPageFallbackShellCacheResponse(options) {
+	const isrKey = options.isrHtmlKey(options.fallbackPathname);
+	try {
+		const cached = await options.isrGet(isrKey);
+		const cachedValue = getCachedAppPageValue(cached);
+		if (!cachedValue) {
+			options.isrDebug?.("MISS (fallback shell)", options.fallbackPathname);
+			return null;
+		}
+		if (isAppPprDynamicFallbackShellHtml(cachedValue.html)) {
+			options.isrDebug?.("MISS (dynamic fallback shell requires resume)", options.fallbackPathname);
+			return null;
+		}
+		return await serveAppPageCachedHtml({
+			cached,
+			cachedValue,
+			clearRequestContext: options.clearRequestContext,
+			emptyDebugMessage: "MISS (empty fallback shell)",
+			expireSeconds: options.expireSeconds,
+			isEdgeRuntime: options.isEdgeRuntime,
+			isrDebug: options.isrDebug,
+			middlewareHeaders: options.middlewareHeaders,
+			middlewareStatus: options.middlewareStatus,
+			pathname: options.fallbackPathname,
+			revalidateSeconds: options.revalidateSeconds,
+			scheduleRegeneration() {},
+			stateDebugLabel: "fallback shell"
+		}, (value) => ({
+			...value,
+			html: options.rewriteHtml(value.html)
+		}));
+	} catch (isrReadError) {
+		options.isrDebug?.("MISS (fallback shell read error)", options.fallbackPathname);
+		console.error("[vinext] ISR fallback shell cache read error:", isrReadError);
+		return null;
+	}
+}
 function finalizeAppPageHtmlCacheResponse(response, options) {
 	if (!response.body) return response;
 	const [streamForClient, streamForCache] = response.body.tee();
@@ -334,4 +395,4 @@ function scheduleAppPageRscCacheWrite(options) {
 	return true;
 }
 //#endregion
-export { buildAppPageCacheTags, buildAppPageCachedResponse, finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, readAppPageCacheResponse, scheduleAppPageRscCacheWrite };
+export { buildAppPageCacheTags, buildAppPageCachedResponse, finalizeAppPageHtmlCacheResponse, finalizeAppPageRscCacheResponse, readAppPageCacheResponse, readAppPageFallbackShellCacheResponse, scheduleAppPageRscCacheWrite };

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

@@ -11,6 +11,7 @@ import { AppLayoutParamAccessTracker } from "./app-layout-param-observation.js";
 import { AppRscRenderMode } from "./app-rsc-render-mode.js";
 import { ISRCacheEntry } from "./isr-cache.js";
 import { FetchCacheMode } from "../shims/fetch-cache.js";
+import { AppPagePprFallbackCacheShell } from "./app-ppr-fallback-shell.js";
 import { ValidateAppPageDynamicParamsOptions } from "./app-page-request.js";
 import { ReactNode } from "react";
 import { ReactFormState } from "react-dom/client";
@@ -36,6 +37,7 @@ type AppPageDispatchIntercept<TPage = unknown> = {
   slotId?: string | null;
   slotKey: string;
   sourceRouteIndex: number;
+  sourcePageSegments?: readonly string[] | null;
 };
 type AppPageDispatchInterceptOptions<TPage = unknown> = {
   interceptionContext: string | null;
@@ -45,6 +47,7 @@ type AppPageDispatchInterceptOptions<TPage = unknown> = {
   interceptSlotId?: string | null;
   interceptSlotKey: string;
   interceptSourceMatchedUrl?: string | null;
+  interceptSourcePageSegments?: readonly string[] | null;
 };
 type AppPageModule = {
   default?: unknown;
@@ -120,6 +123,7 @@ type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   getNavigationContext: () => NavigationContext | null;
   getSourceRoute: (sourceRouteIndex: number) => TRoute | undefined;
   hasGenerateStaticParams: boolean;
+  hasCustomGlobalError?: boolean;
   hasPageDefaultExport: boolean;
   hasPageModule: boolean;
   handlerStart: number;
@@ -138,6 +142,20 @@ type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   middlewareContext: AppPageMiddlewareContext;
   mountedSlotsHeader?: string | null;
   params: AppPageParams;
+  pprFallbackCacheShells?: readonly AppPagePprFallbackCacheShell[] | null;
+  pprFallbackShell?: {
+    fallbackParamNames: readonly string[];
+    routePattern: string;
+  };
+  /**
+   * Set of concrete URL paths that were pre-rendered at build time for this
+   * route. When the exact cache entry for a known pregenerated path is absent
+   * (evicted, stale-empty, cold start, read error), the fallback shell must
+   * NOT be served — the route is a valid generated route whose cache merely
+   * has a transient gap. Falls through to a fresh render instead.
+   */
+  renderedConcreteUrlPaths?: ReadonlySet<string>;
+  skipStaticParamsValidation?: boolean;
   staticParamsValidationParams?: AppPageParams;
   rootParams?: RootParams;
   probeLayoutAt: (layoutIndex: number, layoutParamAccess?: AppLayoutParamAccessTracker) => unknown;
@@ -152,10 +170,18 @@ type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   }, middlewareContext: AppPageMiddlewareContext | null) => Promise<Response | null>;
   renderToReadableStream: (element: AppPageRenderableElement, options: {
     onError: AppPageBoundaryOnError;
+    signal?: AbortSignal;
   }) => ReadableStream<Uint8Array>;
+  prerenderToReadableStream?: (element: AppPageRenderableElement, options: {
+    onError: AppPageBoundaryOnError;
+    signal?: AbortSignal;
+  }) => Promise<{
+    prelude: ReadableStream<Uint8Array>;
+  }>;
   request: Request;
   revalidateSeconds: number | null;
   resolveRouteFetchCacheMode?: (route: TRoute) => FetchCacheMode | null;
+  resolveRouteDynamicConfig?: (route: TRoute) => string | null | undefined;
   rootForbiddenModule?: AppPageModule | null;
   rootNotFoundModule?: AppPageModule | null;
   rootUnauthorizedModule?: AppPageModule | null;