vinext 0.1.0 → 0.1.2

package/dist/server/pages-page-data.d.ts

@@ -2,7 +2,7 @@ import { Route } from "../routing/pages-router.js";
 import { VinextNextData } from "../client/vinext-next-data.js";
 import { CachedPagesValue } from "../shims/cache.js";
 import { ISRCacheEntry } from "./isr-cache.js";
-import { PagesGsspResponse, PagesI18nRenderContext } from "./pages-page-response.js";
+import { PagesGsspResponse, PagesI18nRenderContext, PagesNextDataExtras } from "./pages-page-response.js";
 import { ReactNode } from "react";
 
 //#region src/server/pages-page-data.d.ts
@@ -90,6 +90,7 @@ type RenderPagesIsrHtmlOptions = {
   routePattern: string;
   safeJsonStringify: (value: unknown) => string;
   vinext?: VinextNextData["__vinext"];
+  nextData?: PagesNextDataExtras;
 };
 type ResolvePagesPageDataOptions = {
   applyRequestContexts: () => void;
@@ -125,17 +126,25 @@ type ResolvePagesPageDataOptions = {
    * When true, this dispatch was triggered by an on-demand revalidation
    * request (e.g. `res.revalidate()` in a Pages Router API route, or an
    * equivalent webhook). Maps to `revalidateReason: "on-demand"` when
-   * `getStaticProps` is invoked. Mirrors Next.js's
+   * `getStaticProps` is invoked, and bypasses the fresh/stale cache-hit
+   * short-circuits so the entry is regenerated synchronously. Mirrors Next.js's
    * `renderOpts.isOnDemandRevalidate` flag — see
    * `.nextjs-ref/packages/next/src/server/render.tsx`.
    *
-   * Forward-looking plumbing: no caller currently sets this — `res.revalidate()`
-   * is not yet implemented in vinext. The `"on-demand"` branch in the
-   * `revalidateReason` resolver is intentionally unreachable today; keeping the
-   * typed contract here means wiring it up will be a one-line change once the
-   * trigger lands.
+   * The page handler sets this only when the incoming request's
+   * `x-prerender-revalidate` header (`PRERENDER_REVALIDATE_HEADER`) *equals* the
+   * process revalidate secret that `res.revalidate()` attaches to its internal
+   * request (`isOnDemandRevalidateRequest`). It is never set on mere header
+   * presence — see the security note in `isr-cache.ts`.
    */
   isOnDemandRevalidate?: boolean;
+  /**
+   * The deployment ID used for deployment-skew protection. When set, it is
+   * included as `x-nextjs-deployment-id` on all `_next/data` responses
+   * (success, redirect, notFound). Mirrors Next.js pages-handler.ts behavior.
+   * Typically sourced from `process.env.__VINEXT_DEPLOYMENT_ID || process.env.NEXT_DEPLOYMENT_ID`.
+   */
+  deploymentId?: string;
   pageModule: PagesPageModule;
   params: Record<string, unknown>;
   query: Record<string, unknown>;
@@ -155,6 +164,28 @@ type ResolvePagesPageDataOptions = {
   }) => void;
   renderIsrPassToStringAsync: (element: ReactNode) => Promise<string>;
   vinext?: VinextNextData["__vinext"];
+  nextData?: PagesNextDataExtras;
+  /**
+   * The request's User-Agent string. When this matches a known crawler/bot
+   * pattern, ISR cache-HIT and cache-STALE responses receive an ETag header
+   * for consistency with the fresh-MISS path (which also attaches an ETag for
+   * bot UAs via `renderPagesPageResponse`). See the divergence note in
+   * `pages-page-response.ts` for why UA-gating is used instead of Next.js's
+   * `isDynamic` check.
+   */
+  userAgent?: string;
+  /**
+   * The incoming request's `If-None-Match` header value. When the cached HTML
+   * ETag matches (weak-ETag semantics), the ISR cache-HIT or cache-STALE
+   * response is a `304 Not Modified` with no body.
+   */
+  ifNoneMatch?: string;
+  /**
+   * The incoming request's `Cache-Control` header value. When it contains
+   * `no-cache`, the 304 short-circuit is skipped and a full response is
+   * returned — mirroring the `fresh` package used by Next.js.
+   */
+  requestCacheControl?: string;
 };
 type ResolvePagesPageDataRenderResult = {
   kind: "render";

package/dist/server/pages-page-data.js

@@ -1,22 +1,26 @@
+import { NEXTJS_DEPLOYMENT_ID_HEADER } from "./headers.js";
 import { normalizeStaticPathname } from "../routing/route-pattern.js";
 import { buildCacheStateHeaders } from "./cache-headers.js";
+import { applyCdnResponseHeaders } from "./cache-control.js";
+import { decideIsr } from "./isr-decision.js";
 import { buildPagesCacheValue } from "./isr-cache.js";
 import { isSerializableProps } from "./pages-serializable-props.js";
 import { hasPagesGetInitialProps, isResponseSent, loadPagesGetInitialProps } from "./pages-get-initial-props.js";
-import { applyCdnResponseHeaders, buildCachedRevalidateCacheControl } from "./cache-control.js";
 import { buildNextDataJsonResponse } from "./pages-data-route.js";
-import { buildPagesNextDataScript } from "./pages-page-response.js";
+import { buildPagesNextDataScript, etagMatches, generatePagesETag, isPagesStreamingBot, requestsNoCache } from "./pages-page-response.js";
 //#region src/server/pages-page-data.ts
-function buildPagesDataNotFoundResponse() {
+function buildPagesDataNotFoundResponse(deploymentId) {
+	const headers = { "Content-Type": "application/json" };
+	if (deploymentId) headers[NEXTJS_DEPLOYMENT_ID_HEADER] = deploymentId;
 	return new Response("{}", {
 		status: 404,
-		headers: { "Content-Type": "application/json" }
+		headers
 	});
 }
 function buildPagesNotFoundResult(options) {
 	if (options.isDataReq) return {
 		kind: "response",
-		response: buildPagesDataNotFoundResponse()
+		response: buildPagesDataNotFoundResponse(options.deploymentId)
 	};
 	return { kind: "notFound" };
 }
@@ -46,10 +50,14 @@ function resolvePagesRedirectStatus(redirect) {
 */
 function buildPagesRedirectResponse(redirect, options) {
 	const destination = options.sanitizeDestination(redirect.destination);
-	if (options.isDataReq) return buildNextDataJsonResponse({
-		__N_REDIRECT: destination,
-		__N_REDIRECT_STATUS: resolvePagesRedirectStatus(redirect)
-	}, options.safeJsonStringify);
+	if (options.isDataReq) {
+		const init = { headers: {} };
+		if (options.deploymentId) init.headers[NEXTJS_DEPLOYMENT_ID_HEADER] = options.deploymentId;
+		return buildNextDataJsonResponse({
+			__N_REDIRECT: destination,
+			__N_REDIRECT_STATUS: resolvePagesRedirectStatus(redirect)
+		}, options.safeJsonStringify, init);
+	}
 	return new Response(null, {
 		status: resolvePagesRedirectStatus(redirect),
 		headers: { Location: destination }
@@ -81,19 +89,47 @@ function matchesPagesStaticPath(pathEntry, params, routeUrl) {
 	});
 }
 function buildPagesCacheResponse(html, cacheState, fontLinkHeader, revalidateSeconds, expireSeconds, cacheControl, status) {
-	const effectiveRevalidateSeconds = cacheControl?.revalidate ?? revalidateSeconds ?? 60;
-	const effectiveExpireSeconds = cacheControl === void 0 ? void 0 : cacheControl.expire ?? expireSeconds;
+	const { cacheControl: cacheControlHeader } = decideIsr({
+		cacheState,
+		kind: "pages",
+		revalidateSeconds: revalidateSeconds ?? 60,
+		expireSeconds,
+		cacheControlMeta: cacheControl
+	});
 	const headers = new Headers({
 		"Content-Type": "text/html",
 		...buildCacheStateHeaders(cacheState)
 	});
-	applyCdnResponseHeaders(headers, { cacheControl: buildCachedRevalidateCacheControl(cacheState, effectiveRevalidateSeconds, effectiveExpireSeconds) });
+	applyCdnResponseHeaders(headers, { cacheControl: cacheControlHeader });
 	if (fontLinkHeader) headers.set("Link", fontLinkHeader);
 	return new Response(html, {
 		status: status ?? 200,
 		headers
 	});
 }
+/**
+* For bot / crawler UAs, attach an ETag to a cached ISR response (HIT or
+* STALE) so it is consistent with the fresh-MISS path, then check for a
+* matching `If-None-Match`. When the check passes — and the request did NOT
+* carry `Cache-Control: no-cache` — returns a 304 response; otherwise returns
+* `null` so the caller can return the full response.
+*
+* Extracted to avoid duplicating the same three-line block across the HIT and
+* STALE branches.
+*/
+function applyBotETagAndCheck(cachedResponse, html, options) {
+	if (!options.userAgent || !isPagesStreamingBot(options.userAgent)) return null;
+	const etag = generatePagesETag(html);
+	cachedResponse.headers.set("ETag", etag);
+	if (!requestsNoCache(options.requestCacheControl) && options.ifNoneMatch && etagMatches(etag, options.ifNoneMatch)) return {
+		kind: "response",
+		response: new Response(null, {
+			status: 304,
+			headers: cachedResponse.headers
+		})
+	};
+	return null;
+}
 function rewritePagesCachedHtml(cachedHtml, freshBody, nextDataScript) {
 	const bodyStart = cachedHtml.indexOf("<div id=\"__next\">");
 	const contentStart = bodyStart >= 0 ? bodyStart + 17 : -1;
@@ -117,6 +153,7 @@ async function renderPagesIsrHtml(options) {
 		params: options.params,
 		routePattern: options.routePattern,
 		safeJsonStringify: options.safeJsonStringify,
+		nextData: options.nextData,
 		vinext: options.vinext
 	});
 	return rewritePagesCachedHtml(options.cachedHtml, freshBody, nextDataScript);
@@ -174,11 +211,16 @@ async function resolvePagesPageData(options) {
 		const cacheKey = options.isrCacheKey("pages", pathname);
 		const cached = await options.isrGet(cacheKey);
 		const cachedValue = cached?.value.value;
-		if (cachedValue?.kind === "PAGES" && cached && !cached.isStale && !options.scriptNonce && !options.isDataReq) return {
-			kind: "response",
-			response: buildPagesCacheResponse(cachedValue.html, "HIT", options.fontLinkHeader, void 0, options.expireSeconds, cached.value.cacheControl, cachedValue.status)
-		};
-		if (cachedValue?.kind === "PAGES" && cached && cached.isStale && !options.scriptNonce && !options.isDataReq) {
+		if (!options.isOnDemandRevalidate && cachedValue?.kind === "PAGES" && cached && !cached.isStale && !options.scriptNonce && !options.isDataReq) {
+			const hitResponse = buildPagesCacheResponse(cachedValue.html, "HIT", options.fontLinkHeader, void 0, options.expireSeconds, cached.value.cacheControl, cachedValue.status);
+			const hitBotResult = applyBotETagAndCheck(hitResponse, cachedValue.html, options);
+			if (hitBotResult) return hitBotResult;
+			return {
+				kind: "response",
+				response: hitResponse
+			};
+		}
+		if (!options.isOnDemandRevalidate && cachedValue?.kind === "PAGES" && cached && cached.isStale && !options.scriptNonce && !options.isDataReq) {
 			options.triggerBackgroundRegeneration(cacheKey, async function() {
 				return options.runInFreshUnifiedContext(async () => {
 					const freshResult = await options.pageModule.getStaticProps?.({
@@ -200,6 +242,7 @@ async function resolvePagesPageData(options) {
 							renderIsrPassToStringAsync: options.renderIsrPassToStringAsync,
 							routePattern: options.routePattern,
 							safeJsonStringify: options.safeJsonStringify,
+							nextData: options.nextData,
 							vinext: options.vinext
 						});
 						await options.isrSet(cacheKey, buildPagesCacheValue(freshHtml, freshResult.props, options.statusCode), freshResult.revalidate, void 0, options.expireSeconds);
@@ -210,9 +253,12 @@ async function resolvePagesPageData(options) {
 				routePath: options.routePattern,
 				routeType: "render"
 			});
+			const staleResponse = buildPagesCacheResponse(cachedValue.html, "STALE", options.fontLinkHeader, void 0, options.expireSeconds, cached.value.cacheControl, cachedValue.status);
+			const staleBotResult = applyBotETagAndCheck(staleResponse, cachedValue.html, options);
+			if (staleBotResult) return staleBotResult;
 			return {
 				kind: "response",
-				response: buildPagesCacheResponse(cachedValue.html, "STALE", options.fontLinkHeader, void 0, options.expireSeconds, cached.value.cacheControl, cachedValue.status)
+				response: staleResponse
 			};
 		}
 		const result = await options.pageModule.getStaticProps({

package/dist/server/pages-page-handler.d.ts

@@ -28,6 +28,7 @@ type I18nConfig = {
 } | null;
 type VinextConfigSubset = {
   basePath: string;
+  assetPrefix: string;
   trailingSlash: boolean;
   expireTime?: number;
   clientTraceMetadata?: readonly string[];
@@ -47,8 +48,15 @@ type CreatePagesPageHandlerOptions = {
   vinextConfig: VinextConfigSubset; /** Build ID embedded at build time (or null in dev). */
   buildId: string | null; /** Whether the app has user-defined middleware. */
   hasMiddleware: boolean; /** Absolute file path of `pages/_app` (or null). Used for manifest lookup. */
-  appAssetPath: string | null; /** `setSSRContext` from `next/router`. */
-  setSSRContext: ((ctx: Record<string, unknown> | null) => void) | null; /** `setI18nContext` from `vinext/i18n-context`. */
+  appAssetPath: string | null; /** Whether next.config rewrites are configured (gates Pages router readiness). */
+  hasRewrites: boolean; /** `setSSRContext` from `next/router`. */
+  setSSRContext: ((ctx: Record<string, unknown> | null) => void) | null;
+  /**
+   * `getPagesNavigationIsReadyFromSerializedState` from `next/router`. Decides
+   * the initial `router.isReady` value for the Pages Router navigation
+   * compat hooks (mirrors Next.js's Pages adapter readiness gate).
+   */
+  getPagesNavigationIsReadyFromSerializedState: ((routePattern: string | undefined, searchString: string, nextData?: Record<string, unknown>) => boolean) | null; /** `setI18nContext` from `vinext/i18n-context`. */
   setI18nContext: ((ctx: Record<string, unknown>) => void) | null; /** `wrapWithRouterContext` from `next/router`. */
   wrapWithRouterContext: ((element: ReactNode) => ReactNode) | null; /** `resetSSRHead` from `next/head`. */
   resetSSRHead: (() => void) | undefined; /** `getSSRHeadHTML` from `next/head`. */

package/dist/server/pages-page-handler.js

@@ -1,13 +1,17 @@
 import { createRequestContext, runWithRequestContext } from "../shims/unified-request-context.js";
 import { patternToNextFormat } from "../routing/route-validation.js";
 import { getRequestExecutionContext } from "../shims/request-context.js";
+import { NEXTJS_DEPLOYMENT_ID_HEADER } from "./headers.js";
 import { reportRequestError } from "./instrumentation.js";
-import { isrCacheKey, isrGet, isrSet, triggerBackgroundRegeneration } from "./isr-cache.js";
+import { NEVER_CACHE_CONTROL } from "./cache-control.js";
+import "./isr-decision.js";
+import { PRERENDER_REVALIDATE_HEADER, isOnDemandRevalidateRequest, isrCacheKey, isrGet, isrSet, triggerBackgroundRegeneration } from "./isr-cache.js";
 import { ensureFetchPatch } from "../shims/fetch-cache.js";
 import { mergeRouteParamsIntoQuery, parseQueryString } from "../utils/query.js";
 import { getScriptNonceFromHeaderSources } from "./csp.js";
 import { resolvePagesI18nRequest } from "./pages-i18n.js";
 import { buildDefaultPagesNotFoundResponse } from "./pages-default-404.js";
+import { buildPagesReadinessNextData } from "./pages-readiness.js";
 import { resolvePagesPageMethodResponse } from "./pages-page-method.js";
 import { buildNextDataJsonResponse, buildNextDataNotFoundResponse, normalizePagesDataRequest } from "./pages-data-route.js";
 import { createPagesReqRes } from "./pages-node-compat.js";
@@ -30,7 +34,7 @@ function buildI18nRenderContext(i18nConfig, locale, currentDefaultLocale, domain
 * accepts the same options shape the generated entry always passed inline.
 */
 function createPagesPageHandler(opts) {
-	const { pageRoutes, errorPageRoute, matchRoute, i18nConfig, vinextConfig, buildId, hasMiddleware, appAssetPath, setSSRContext, setI18nContext, wrapWithRouterContext, resetSSRHead, getSSRHeadHTML, setDocumentInitialHead, flushPreloads, getFontLinks, getFontStyles, getFontPreloads, renderToReadableStream, renderIsrPassToStringAsync, safeJsonStringify, sanitizeDestination, createPageElement, enhancePageElement, AppComponent, DocumentComponent } = opts;
+	const { pageRoutes, errorPageRoute, matchRoute, i18nConfig, vinextConfig, buildId, hasMiddleware, appAssetPath, hasRewrites, setSSRContext, getPagesNavigationIsReadyFromSerializedState, setI18nContext, wrapWithRouterContext, resetSSRHead, getSSRHeadHTML, setDocumentInitialHead, flushPreloads, getFontLinks, getFontStyles, getFontPreloads, renderToReadableStream, renderIsrPassToStringAsync, safeJsonStringify, sanitizeDestination, createPageElement, enhancePageElement, AppComponent, DocumentComponent } = opts;
 	function renderToStringAsync(element) {
 		return renderToReadableStream(element).then((stream) => new Response(stream).text());
 	}
@@ -102,15 +106,24 @@ function createPagesPageHandler(opts) {
 				const routePattern = patternToNextFormat(route.pattern);
 				const renderStatusCode = renderStatusCodeOverride ?? (routePattern === "/404" ? 404 : void 0);
 				const query = mergeRouteParamsIntoQuery(parseQueryString(routeUrl), params);
-				function applySSRContext() {
+				const pageModule = route.module;
+				const pagesNextData = buildPagesReadinessNextData({
+					pageModule,
+					appComponent: AppComponent,
+					hasRewrites
+				});
+				const navigationIsReady = typeof getPagesNavigationIsReadyFromSerializedState === "function" ? getPagesNavigationIsReadyFromSerializedState(routePattern, new URL(renderAsPath ?? routeUrl, "http://_").search, pagesNextData) : true;
+				function applySSRContext(extra) {
 					if (typeof setSSRContext === "function") setSSRContext({
 						pathname: routePattern,
 						query,
 						asPath: renderAsPath ?? routeUrl,
+						navigationIsReady,
 						locale,
 						locales: i18nConfig ? i18nConfig.locales : void 0,
 						defaultLocale: currentDefaultLocale,
-						domainLocales
+						domainLocales,
+						...extra
 					});
 					if (i18nConfig && typeof setI18nContext === "function") setI18nContext({
 						locale,
@@ -120,8 +133,7 @@ function createPagesPageHandler(opts) {
 						hostname: new URL(request.url).hostname
 					});
 				}
-				applySSRContext();
-				const pageModule = route.module;
+				applySSRContext({ nextData: pagesNextData });
 				const PageComponent = pageModule.default;
 				if (!PageComponent) return new Response("Page has no default export", { status: 500 });
 				if (!isDataReq && routePattern !== "/_error" && routePattern !== "/404" && routePattern !== "/500" && renderStatusCodeOverride === void 0) {
@@ -131,8 +143,17 @@ function createPagesPageHandler(opts) {
 					});
 					if (methodResponse) return methodResponse;
 				}
-				const pageModuleUrl = resolveClientModuleUrl(manifest, route.filePath);
-				const appModuleUrl = resolveClientModuleUrl(manifest, appAssetPath);
+				const pageModuleUrl = resolveClientModuleUrl(manifest, route.filePath, vinextConfig.basePath, vinextConfig.assetPrefix);
+				const appModuleUrl = resolveClientModuleUrl(manifest, appAssetPath, vinextConfig.basePath, vinextConfig.assetPrefix);
+				const serializedPagesNextData = {
+					...pagesNextData,
+					__vinext: {
+						...pagesNextData.__vinext,
+						pageModuleUrl,
+						appModuleUrl,
+						hasMiddleware
+					}
+				};
 				const scriptNonce = getScriptNonceFromHeaderSources(request.headers, middlewareHeaders);
 				let fontLinkHeader = "";
 				let allFontPreloads = [];
@@ -145,6 +166,7 @@ function createPagesPageHandler(opts) {
 					err,
 					applyRequestContexts: applySSRContext,
 					buildId,
+					deploymentId: process.env.__VINEXT_DEPLOYMENT_ID || process.env.NEXT_DEPLOYMENT_ID,
 					createGsspReqRes() {
 						return createPagesReqRes({
 							body: void 0,
@@ -164,6 +186,7 @@ function createPagesPageHandler(opts) {
 					isrSet,
 					expireSeconds: vinextConfig.expireTime,
 					isBuildTimePrerendering: typeof process !== "undefined" && process.env && process.env.VINEXT_PRERENDER === "1",
+					isOnDemandRevalidate: isOnDemandRevalidateRequest(request.headers.get(PRERENDER_REVALIDATE_HEADER)),
 					pageModule,
 					params,
 					query,
@@ -183,11 +206,11 @@ function createPagesPageHandler(opts) {
 					scriptNonce,
 					statusCode: renderStatusCode,
 					triggerBackgroundRegeneration,
-					vinext: {
-						pageModuleUrl,
-						appModuleUrl,
-						hasMiddleware
-					}
+					vinext: serializedPagesNextData.__vinext,
+					nextData: serializedPagesNextData,
+					userAgent: request.headers.get("user-agent") ?? void 0,
+					ifNoneMatch: request.headers.get("if-none-match") ?? void 0,
+					requestCacheControl: request.headers.get("cache-control") ?? void 0
 				});
 				if (pageDataResult.kind === "notFound") {
 					const notFoundRoute = findNotFoundRoute();
@@ -212,6 +235,7 @@ function createPagesPageHandler(opts) {
 					pathname: routePattern,
 					query,
 					asPath: renderAsPath ?? routeUrl,
+					navigationIsReady: false,
 					locale,
 					locales: i18nConfig ? i18nConfig.locales : void 0,
 					defaultLocale: currentDefaultLocale,
@@ -234,7 +258,11 @@ function createPagesPageHandler(opts) {
 							hasUserCacheControl = true;
 							break;
 						}
-						if (!hasUserCacheControl) init.headers["Cache-Control"] = "private, no-cache, no-store, max-age=0, must-revalidate";
+						if (!hasUserCacheControl) init.headers["Cache-Control"] = NEVER_CACHE_CONTROL;
+					}
+					if (routePattern !== "/_error" && routePattern !== "/500") {
+						const deploymentId = process.env.__VINEXT_DEPLOYMENT_ID || process.env.NEXT_DEPLOYMENT_ID;
+						if (deploymentId) init.headers[NEXTJS_DEPLOYMENT_ID_HEADER] = deploymentId;
 					}
 					return buildNextDataJsonResponse(pageProps, safeJsonStringify, init);
 				}
@@ -246,7 +274,9 @@ function createPagesPageHandler(opts) {
 						manifest,
 						moduleIds: pageModuleIds,
 						scriptNonce,
-						disableOptimizedLoading: vinextConfig.disableOptimizedLoading
+						disableOptimizedLoading: vinextConfig.disableOptimizedLoading,
+						basePath: vinextConfig.basePath,
+						assetPrefix: vinextConfig.assetPrefix
 					}),
 					buildId,
 					clearSsrContext() {
@@ -288,11 +318,10 @@ function createPagesPageHandler(opts) {
 					safeJsonStringify,
 					scriptNonce,
 					statusCode: renderStatusCode,
-					vinext: {
-						pageModuleUrl,
-						appModuleUrl,
-						hasMiddleware
-					}
+					nextData: serializedPagesNextData,
+					userAgent: request.headers.get("user-agent") ?? void 0,
+					ifNoneMatch: request.headers.get("if-none-match") ?? void 0,
+					requestCacheControl: request.headers.get("cache-control") ?? void 0
 				});
 			} catch (e) {
 				console.error("[vinext] SSR error:", e);

package/dist/server/pages-page-response.d.ts

@@ -4,10 +4,40 @@ import { RenderPageEnhancers } from "./pages-document-initial-props.js";
 import { ComponentType, ReactNode } from "react";
 
 //#region src/server/pages-page-response.d.ts
+/**
+ * Returns true when the User-Agent belongs to a bot or crawler that cannot
+ * reliably consume a streamed HTML response.
+ */
+declare function isPagesStreamingBot(userAgent: string): boolean;
+declare function generatePagesETag(payload: string): string;
+/**
+ * Mirrors Next.js `sendEtagResponse` semantics (weak/strong comparison).
+ *
+ * A weak ETag `W/"..."` matches both `W/"..."` and `"..."` in `If-None-Match`.
+ * A strong ETag `"..."` only matches the same strong token.
+ * `*` always matches.
+ */
+declare function etagMatches(etag: string, ifNoneMatch: string): boolean;
+/**
+ * Returns true when a request `Cache-Control` header asks to bypass the 304
+ * short-circuit. Mirrors the `fresh` package's check used by Next.js's
+ * `sendEtagResponse` (`/(?:^|,)\s*?no-cache\s*?(?:,|$)/`). Shared by the
+ * fresh-MISS bot path here and the ISR HIT/STALE paths in
+ * `pages-page-data.ts` so the two cannot drift.
+ */
+declare function requestsNoCache(cacheControl: string | undefined): boolean;
 type PagesFontPreload = {
   href: string;
   type: string;
 };
+/**
+ * The `__NEXT_DATA__` fields beyond the always-present core that the Pages
+ * renderer serializes: the `__vinext` block plus the readiness flags
+ * (gssp/gsp/gip/appGip/autoExport/isExperimentalCompile) the client uses to
+ * recompute the initial `router.isReady`. Shared by every render path
+ * (initial, ISR regeneration) so they emit identical readiness state.
+ */
+type PagesNextDataExtras = Pick<VinextNextData, "__vinext" | "appGip" | "autoExport" | "gip" | "gsp" | "gssp" | "isExperimentalCompile">;
 type PagesI18nRenderContext = {
   locale?: string;
   locales?: string[];
@@ -73,10 +103,33 @@ type RenderPagesPageResponseOptions = {
   scriptNonce?: string;
   statusCode?: number;
   vinext?: VinextNextData["__vinext"];
+  nextData?: PagesNextDataExtras;
+  /**
+   * The request's User-Agent string (from `request.headers.get('user-agent')`).
+   * When this matches a known crawler / bot pattern, the response is fully
+   * buffered before sending so bots receive a single complete HTML chunk with
+   * an ETag header. Omitting this field disables bot-detection (streaming as
+   * normal), which is the correct behaviour for non-HTML requests and tests.
+   */
+  userAgent?: string;
+  /**
+   * The incoming request's `If-None-Match` header value. When set and the
+   * computed ETag matches (weak-ETag semantics, mirroring Next.js's
+   * `sendEtagResponse`), a `304 Not Modified` is returned with an empty body.
+   * Only evaluated on bot/buffered responses that carry an ETag.
+   */
+  ifNoneMatch?: string;
+  /**
+   * The incoming request's `Cache-Control` header value. When the value
+   * contains `no-cache`, the 304 short-circuit is skipped and a full 200
+   * response is always returned — mirroring the `fresh` package used by
+   * Next.js's `sendEtagResponse`.
+   */
+  requestCacheControl?: string;
 };
-declare function buildPagesNextDataScript(options: Pick<RenderPagesPageResponseOptions, "buildId" | "i18n" | "isFallback" | "pageProps" | "params" | "routePattern" | "safeJsonStringify" | "scriptNonce"> & {
+declare function buildPagesNextDataScript(options: Pick<RenderPagesPageResponseOptions, "buildId" | "i18n" | "isFallback" | "pageProps" | "params" | "routePattern" | "safeJsonStringify" | "scriptNonce" | "nextData"> & {
   vinext?: VinextNextData["__vinext"];
 }): string;
 declare function renderPagesPageResponse(options: RenderPagesPageResponseOptions): Promise<Response>;
 //#endregion
-export { PagesGsspResponse, PagesI18nRenderContext, buildPagesNextDataScript, renderPagesPageResponse };
+export { PagesGsspResponse, PagesI18nRenderContext, PagesNextDataExtras, buildPagesNextDataScript, etagMatches, generatePagesETag, isPagesStreamingBot, renderPagesPageResponse, requestsNoCache };

package/dist/server/pages-page-response.js

@@ -1,16 +1,64 @@
 import { getRequestExecutionContext } from "../shims/request-context.js";
 import { reportRequestError } from "./instrumentation.js";
 import { setCacheStateHeaders } from "./cache-headers.js";
+import { fnv1a52 } from "../utils/hash.js";
 import { encodeCacheTag } from "../utils/encode-cache-tag.js";
+import { NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL, applyCdnResponseHeaders } from "./cache-control.js";
+import { buildMissIsrCacheControl } from "./isr-decision.js";
 import { withScriptNonce } from "../shims/script-nonce-context.js";
 import { createInlineScriptTag, createNonceAttribute, escapeHtmlAttr } from "./html.js";
 import { getClientTraceMetadataHTML } from "./client-trace-metadata.js";
 import { readStreamAsText } from "../utils/text-stream.js";
 import { loadUserDocumentInitialProps, runDocumentRenderPage } from "./pages-document-initial-props.js";
 import { callDocumentGetInitialProps } from "./document-initial-head.js";
-import { applyCdnResponseHeaders, buildRevalidateCacheControl } from "./cache-control.js";
 import React from "react";
 //#region src/server/pages-page-response.ts
+/**
+* Crawlers that cannot handle streamed HTML: they read metadata only from
+* the first network chunk, so streaming would give them an incomplete <head>.
+* Pattern sourced from Next.js html-bots.ts (updated to match the canary).
+*/
+const HTML_LIMITED_BOT_UA_RE = /[\w-]+-Google|Google-[\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight/i;
+/**
+* Googlebot (the main search crawler) executes JavaScript via a headless
+* browser, so it too cannot safely handle mid-stream HTML mutations.
+* Matches "Googlebot" but NOT suffixed variants like "Googlebot-Image".
+*/
+const HEADLESS_BROWSER_BOT_UA_RE = /Googlebot(?!-)|Googlebot$/i;
+/**
+* Returns true when the User-Agent belongs to a bot or crawler that cannot
+* reliably consume a streamed HTML response.
+*/
+function isPagesStreamingBot(userAgent) {
+	return HEADLESS_BROWSER_BOT_UA_RE.test(userAgent) || HTML_LIMITED_BOT_UA_RE.test(userAgent);
+}
+function generatePagesETag(payload) {
+	return "\"" + fnv1a52(payload).toString(36) + payload.length.toString(36) + "\"";
+}
+/**
+* Mirrors Next.js `sendEtagResponse` semantics (weak/strong comparison).
+*
+* A weak ETag `W/"..."` matches both `W/"..."` and `"..."` in `If-None-Match`.
+* A strong ETag `"..."` only matches the same strong token.
+* `*` always matches.
+*/
+function etagMatches(etag, ifNoneMatch) {
+	if (ifNoneMatch === "*") return true;
+	const normalize = (t) => t.replace(/^W\//, "");
+	const etagNorm = normalize(etag.trim());
+	for (const token of ifNoneMatch.split(",")) if (normalize(token.trim()) === etagNorm) return true;
+	return false;
+}
+/**
+* Returns true when a request `Cache-Control` header asks to bypass the 304
+* short-circuit. Mirrors the `fresh` package's check used by Next.js's
+* `sendEtagResponse` (`/(?:^|,)\s*?no-cache\s*?(?:,|$)/`). Shared by the
+* fresh-MISS bot path here and the ISR HIT/STALE paths in
+* `pages-page-data.ts` so the two cannot drift.
+*/
+function requestsNoCache(cacheControl) {
+	return /(?:^|,)\s*no-cache\s*(?:,|$)/.test(cacheControl ?? "");
+}
 function buildPagesFontHeadHtml(fontLinks, fontPreloads, fontStyles, scriptNonce) {
 	let html = "";
 	const nonceAttr = createNonceAttribute(scriptNonce);
@@ -27,13 +75,19 @@ function buildPagesNextDataScript(options) {
 		buildId: options.buildId,
 		isFallback: options.isFallback === true
 	};
+	if (options.nextData) {
+		for (const [key, value] of Object.entries(options.nextData)) if (value !== void 0) nextDataPayload[key] = value;
+	}
 	if (options.i18n.locales) {
 		nextDataPayload.locale = options.i18n.locale;
 		nextDataPayload.locales = options.i18n.locales;
 		nextDataPayload.defaultLocale = options.i18n.defaultLocale;
 		nextDataPayload.domainLocales = options.i18n.domainLocales;
 	}
-	if (options.vinext) nextDataPayload.__vinext = options.vinext;
+	if (options.vinext) nextDataPayload.__vinext = {
+		...options.nextData?.__vinext,
+		...options.vinext
+	};
 	const localeGlobals = options.i18n.locales ? `;window.__VINEXT_LOCALE__=${options.safeJsonStringify(options.i18n.locale)};window.__VINEXT_LOCALES__=${options.safeJsonStringify(options.i18n.locales)};window.__VINEXT_DEFAULT_LOCALE__=${options.safeJsonStringify(options.i18n.defaultLocale)}` : "";
 	return createInlineScriptTag(`window.__NEXT_DATA__ = ${options.safeJsonStringify(nextDataPayload)}${localeGlobals}`, options.scriptNonce);
 }
@@ -129,6 +183,7 @@ async function renderPagesPageResponse(options) {
 		routePattern: options.routePattern,
 		safeJsonStringify: options.safeJsonStringify,
 		scriptNonce: options.scriptNonce,
+		nextData: options.nextData,
 		vinext: options.vinext
 	});
 	const bodyMarker = "<!--VINEXT_STREAM_BODY-->";
@@ -194,21 +249,34 @@ async function renderPagesPageResponse(options) {
 	}
 	const compositeStream = await buildPagesCompositeStream(responseBodyStream, shellPrefix, shellSuffix);
 	const userSetCacheControl = responseHeaders.has("Cache-Control");
-	if (options.scriptNonce) responseHeaders.set("Cache-Control", "no-store, must-revalidate");
+	if (options.scriptNonce) responseHeaders.set("Cache-Control", NO_STORE_CACHE_CONTROL);
 	else if (options.isrRevalidateSeconds) {
 		const isrPathname = options.routeUrl.split("?")[0];
 		const stem = isrPathname.endsWith("/") ? isrPathname.slice(0, -1) : isrPathname;
 		applyCdnResponseHeaders(responseHeaders, {
-			cacheControl: buildRevalidateCacheControl(options.isrRevalidateSeconds, options.expireSeconds),
+			cacheControl: buildMissIsrCacheControl(options.isrRevalidateSeconds, options.expireSeconds),
 			tags: [encodeCacheTag(`_N_T_${stem || "/"}`)]
 		});
 		setCacheStateHeaders(responseHeaders, "MISS");
-	} else if (options.gsspRes && !userSetCacheControl) responseHeaders.set("Cache-Control", "private, no-cache, no-store, max-age=0, must-revalidate");
+	} else if (options.gsspRes && !userSetCacheControl) responseHeaders.set("Cache-Control", NEVER_CACHE_CONTROL);
 	if (options.fontLinkHeader) responseHeaders.set("Link", options.fontLinkHeader);
+	if (options.userAgent && isPagesStreamingBot(options.userAgent)) {
+		const fullHtml = await readStreamAsText(compositeStream);
+		const etag = generatePagesETag(fullHtml);
+		responseHeaders.set("ETag", etag);
+		if (!requestsNoCache(options.requestCacheControl) && options.ifNoneMatch && etagMatches(etag, options.ifNoneMatch)) return new Response(null, {
+			status: 304,
+			headers: responseHeaders
+		});
+		return new Response(fullHtml, {
+			status: finalStatus,
+			headers: responseHeaders
+		});
+	}
 	return Object.assign(new Response(compositeStream, {
 		status: finalStatus,
 		headers: responseHeaders
 	}), { __vinextStreamedHtmlResponse: true });
 }
 //#endregion
-export { buildPagesNextDataScript, renderPagesPageResponse };
+export { buildPagesNextDataScript, etagMatches, generatePagesETag, isPagesStreamingBot, renderPagesPageResponse, requestsNoCache };