@vinext/cloudflare 1.2.1 → 1.3.1

package/dist/cache/response-store-adapter.worker.js

@@ -1,7 +1,8 @@
+import { isCanonicalAppPage } from "./app-page-parts.js";
 import { SHARED_RESPONSE_STAGE_HEADER, finalizeGatewayResponse } from "./browser-cache-policy.js";
-import { captureResponseStoreDataRegeneration, runWithResponseStoreInvocation, setResponseStore } from "./response-store-data.runtime.js";
-import { VINEXT_PARAMS_HEADER, VINEXT_RENDERED_PATH_AND_SEARCH_HEADER, VINEXT_SPECIAL_ERROR_STATUS_HEADER } from "vinext/internal/server/headers";
-import { VINEXT_RSC_CONTENT_TYPE, VINEXT_RSC_VARY_HEADER as VINEXT_RSC_VARY_HEADER$1, applyRscCompatibilityIdHeader, applyRscDeploymentIdHeader, createCanonicalRscRequestHeaders, createCanonicalRscRequestUrl } from "vinext/internal/server/app-rsc-cache-busting";
+import { captureResponseStoreDataRegeneration, runWithResponseStoreInvocation, setResponseStore, trackResponseStoreRegenerationWork } from "./response-store-data.runtime.js";
+import { NEXTJS_DEPLOYMENT_ID_HEADER, VINEXT_PARAMS_HEADER, VINEXT_RENDERED_PATH_AND_SEARCH_HEADER, VINEXT_RSC_COMPLETION_METADATA_HEADER, VINEXT_SPECIAL_ERROR_STATUS_HEADER, VINEXT_STALE_TIME_PENDING_HEADER } from "vinext/internal/server/headers";
+import { VINEXT_RSC_BUILD_ID_HEADER, VINEXT_RSC_COMPATIBILITY_ID_HEADER, VINEXT_RSC_CONTENT_TYPE, VINEXT_RSC_VARY_HEADER as VINEXT_RSC_VARY_HEADER$1, applyRscCompatibilityIdHeader, applyRscDeploymentIdHeader, createCanonicalRscRequestHeaders, createCanonicalRscRequestUrl, stripRscCacheBustingSearchParam } from "vinext/internal/server/app-rsc-cache-busting";
 import { hasSharedCacheCredentials, isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
 import { loadVinextRequestStage } from "vinext/server/request-stage";
 import { loadVinextResponseStage } from "vinext/server/response-stage";
@@ -9,6 +10,8 @@ import { traceCachedResponseStart } from "vinext/internal/server/response-start-
 import { isPageNotModified } from "vinext/internal/server/http-conditional";
 //#region src/cache/response-store-adapter.worker.ts
 const ROUTE_REVALIDATOR_ID = "vinext:response";
+/** Leads the revalidator args of a page part whose render stores both parts. */
+const PAGE_PARTS_REVALIDATOR_ARG = "vinext:page-parts";
 const RESPONSE_STORE_KEY_PARAM = "__workers_response_store";
 const AGE_BASIS_HEADER = "X-Workers-Response-Store-Age-Basis";
 const WARMUP_USER_AGENT = "vinext-cloudflare-cdn-warm";
@@ -22,7 +25,10 @@ function stageContext(ctx, env) {
 		hostRuntime: "worker",
 		passThroughOnException: () => ctx.passThroughOnException(),
 		...ctx.props === void 0 ? {} : { props: ctx.props },
-		waitUntil: (promise) => ctx.waitUntil(promise)
+		waitUntil: (promise) => {
+			trackResponseStoreRegenerationWork(promise);
+			ctx.waitUntil(promise);
+		}
 	});
 }
 function safeProps(props) {
@@ -58,6 +64,15 @@ function prepareInvocation(request, props) {
 function serializeInvocation(request, props) {
 	return JSON.stringify(prepareInvocation(request, props));
 }
+function serializeDispatchInvocation(invocation) {
+	return JSON.stringify({
+		...invocation,
+		request: {
+			...invocation.request,
+			headers: [...invocation.request.headers, ["host", new URL(invocation.request.url).host]]
+		}
+	});
+}
 function parseInvocation(value) {
 	if (typeof value !== "string") throw new TypeError("Invalid vinext response-store invocation");
 	const invocation = JSON.parse(value);
@@ -95,16 +110,29 @@ function createVinextResponseStoreOptions(configuration) {
 		async regenerate(input, { env, ctx }) {
 			if (input.id === ROUTE_REVALIDATOR_ID) {
 				const invocation = parseInvocation(input.args.at(-1));
-				const response = await invokeResponseStage(restoreRequest(invocation), invocation.props, env, ctx, {
+				const request = restoreRequest(invocation);
+				const otherPart = input.args.length > 1 && input.args[0] === PAGE_PARTS_REVALIDATOR_ARG ? otherPagePart(request, invocation.props) : void 0;
+				const capture = otherPagePartCapture(otherPart);
+				const response = await invokeResponseStage(request, invocation.props, env, ctx, {
 					cache: "shared",
 					regeneratesStoredEntry: true,
 					renderWholeDocument: true
-				});
+				}, capture);
 				if (!isCacheable(response)) {
 					await response.body?.cancel().catch(() => {});
+					capture.rscData?.catch(() => {});
 					throw new Error("Vinext response-stage regeneration was not cacheable");
 				}
-				return withoutRequestScopedHeaders(response, invocation.props);
+				const stored = withoutRequestScopedHeaders(response, invocation.props);
+				try {
+					await putOtherPagePart(otherPart, capture, stored);
+				} catch (error) {
+					console.error(JSON.stringify({
+						message: "Vinext response-store regeneration failed to store the page's other part",
+						error: error instanceof Error ? error.message : String(error)
+					}));
+				}
+				return stored;
 			}
 			if (input.id === "vinext:cache-function" && typeof input.args[0] === "string" && typeof input.args[1] === "string") {
 				const invocation = JSON.parse(input.args[1]);
@@ -137,7 +165,8 @@ async function cacheRequest(invocation) {
 	url.searchParams.set(RESPONSE_STORE_KEY_PARAM, `v1.${[...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`);
 	return new Request(url, {
 		headers: CACHE_REQUEST_VARY_HEADERS,
-		method: "GET"
+		method: "GET",
+		redirect: "manual"
 	});
 }
 /**
@@ -157,6 +186,116 @@ function withoutRequestScopedHeaders(response, responseStageProps) {
 		statusText: response.statusText
 	});
 }
+/**
+* The revalidator of a page part. One whose render stores the page's other
+* part says so, as a public config policy's full-URL entry stores its own.
+*/
+function routeRevalidator(serializedInvocation, storesOtherPart) {
+	return {
+		id: ROUTE_REVALIDATOR_ID,
+		args: storesOtherPart ? [PAGE_PARTS_REVALIDATOR_ARG, serializedInvocation] : [serializedInvocation]
+	};
+}
+/** The invocation an RSC navigation to an HTML invocation's page stores under. */
+function rscPartInvocation(htmlRequest, htmlProps) {
+	return prepareInvocation(new Request(new URL(createCanonicalRscRequestUrl(htmlRequest.url), htmlRequest.url), { headers: createCanonicalRscRequestHeaders() }), {
+		...htmlProps,
+		isRscRequest: true,
+		renderMode: "navigation"
+	});
+}
+/** The invocation an HTML request for an RSC invocation's page stores under. */
+function documentPartInvocation(rscRequest, rscProps) {
+	const url = new URL(rscRequest.url);
+	stripRscCacheBustingSearchParam(url);
+	return prepareInvocation(new Request(url), {
+		...rscProps,
+		isRscRequest: false
+	});
+}
+/**
+* The page's RSC payload an HTML render produced, with its document's headers
+* and status.
+*/
+function rscPartResponse(htmlResponse, rscData) {
+	const headers = new Headers(htmlResponse.headers);
+	headers.delete("Content-Length");
+	headers.delete("Link");
+	headers.delete("X-Vinext-Response-Store-Replayable");
+	headers.delete(VINEXT_PARAMS_HEADER);
+	headers.delete(VINEXT_RENDERED_PATH_AND_SEARCH_HEADER);
+	headers.set("Content-Type", VINEXT_RSC_CONTENT_TYPE);
+	headers.set("Vary", VINEXT_RSC_VARY_HEADER$1);
+	applyRscCompatibilityIdHeader(headers);
+	applyRscDeploymentIdHeader(headers);
+	if (isStoredErrorStatus(htmlResponse.status)) headers.set(VINEXT_SPECIAL_ERROR_STATUS_HEADER, String(htmlResponse.status));
+	return new Response(rscData, {
+		headers,
+		status: htmlResponse.status >= 300 && htmlResponse.status < 400 ? 200 : htmlResponse.status
+	});
+}
+/**
+* The page's document an RSC render produced, with the headers an HTML request
+* for the page stores: the RSC response's, without the payload's own.
+*/
+function documentPartResponse(rscResponse, document) {
+	const headers = new Headers(rscResponse.headers);
+	for (const name of [
+		"Content-Length",
+		NEXTJS_DEPLOYMENT_ID_HEADER,
+		VINEXT_RSC_BUILD_ID_HEADER,
+		VINEXT_RSC_COMPATIBILITY_ID_HEADER,
+		VINEXT_RSC_COMPLETION_METADATA_HEADER,
+		VINEXT_STALE_TIME_PENDING_HEADER
+	]) headers.delete(name);
+	headers.set("Content-Type", "text/html; charset=utf-8");
+	if (document.linkHeader) headers.append("Link", document.linkHeader);
+	return new Response(document.html, {
+		headers,
+		status: rscResponse.status
+	});
+}
+/**
+* The other part of the page a canonical App page render stores. Next.js
+* keeps a page's document and RSC payload in one entry, so a render that
+* stores one part also stores the other, under the key a request for that
+* part reads. A variant has no other part.
+*/
+function otherPagePart(identityRequest, identityProps) {
+	if (isCanonicalAppPage(identityProps, false)) return {
+		invocation: rscPartInvocation(identityRequest, identityProps),
+		kind: "rsc"
+	};
+	if (isCanonicalAppPage(identityProps, true)) return {
+		invocation: documentPartInvocation(identityRequest, identityProps),
+		kind: "document"
+	};
+}
+/** What a render captures for the other part of its page. */
+function otherPagePartCapture(part) {
+	if (part?.kind === "rsc") return { captureRscData: true };
+	if (part?.kind === "document") return { captureDocument: true };
+	return {};
+}
+/**
+* Store the other part of the page from the render that stores this one.
+* Admission settles the document before it completes the response. A miss
+* stores it first, so a failed write leaves the render's own part missing too
+* and the next miss retries both. A regeneration's other part stays stale
+* when it fails, so the next read of that part regenerates it. Concurrent
+* misses coalesce each key on its own, so their parts can come from different
+* renders of the page.
+*/
+async function putOtherPagePart(part, capture, stored) {
+	let response;
+	if (part?.kind === "rsc" && capture.rscData) response = rscPartResponse(stored, await capture.rscData);
+	else if (part?.kind === "document" && capture.document) response = documentPartResponse(stored, capture.document);
+	else return;
+	if (!(await responseStore.put(await cacheRequest(part.invocation), response, {
+		coalesce: true,
+		revalidator: routeRevalidator(JSON.stringify(part.invocation), true)
+	})).backingStoreUpdated) throw new Error(`Vinext response-store did not publish the App page ${part.kind} part`);
+}
 function isStoredErrorStatus(status) {
 	return status === 401 || status === 403 || status === 404;
 }
@@ -275,17 +414,9 @@ const handler = { async fetch(request, env, ctx) {
 		const identityRequest = options.cacheIdentity?.request ?? stageRequest;
 		const identityProps = options.cacheIdentity?.props ?? props;
 		const isWarmup = request.headers.get("user-agent") === WARMUP_USER_AGENT;
-		const rscSeed = isWarmup && props !== null && typeof props === "object" && Reflect.get(props, "kind") === "app-page" && Reflect.get(props, "isRscRequest") === false && Reflect.get(props, "matchKind") === "request" && Reflect.get(props, "interceptionContext") === null && Reflect.get(props, "interceptionId") === null && Reflect.get(props, "mountedSlotsHeader") === null ? {
-			props: {
-				...identityProps,
-				isRscRequest: true,
-				renderMode: "navigation"
-			},
-			request: new Request(new URL(createCanonicalRscRequestUrl(identityRequest.url), identityRequest.url), { headers: createCanonicalRscRequestHeaders() })
-		} : void 0;
+		const otherPart = isWarmup || options.cacheIdentity?.queryFree ? otherPagePart(identityRequest, identityProps) : void 0;
+		const rscKey = isWarmup && otherPart?.kind === "rsc" ? await cacheRequest(otherPart.invocation) : void 0;
 		const invocation = prepareInvocation(identityRequest, identityProps);
-		const rscInvocation = rscSeed ? prepareInvocation(rscSeed.request, rscSeed.props) : void 0;
-		const rscKey = rscInvocation ? await cacheRequest(rscInvocation) : void 0;
 		const key = await cacheRequest(invocation);
 		const stored = await readStoredResponse(key);
 		if (stored) {
@@ -297,8 +428,12 @@ const handler = { async fetch(request, env, ctx) {
 			}
 			stored.body?.cancel().catch(() => {});
 		}
-		const capture = rscSeed ? { captureRscData: true } : isWarmup ? {} : { streamResponse: true };
+		const capture = {
+			...isWarmup ? {} : { streamResponse: true },
+			...otherPagePartCapture(otherPart)
+		};
 		const serializedInvocation = JSON.stringify(invocation);
+		const revalidatorInvocation = !options.cacheIdentity ? serializeDispatchInvocation(invocation) : options.cacheIdentity.regenerateFromDispatch ? serializeDispatchInvocation(prepareInvocation(stageRequest, props)) : serializedInvocation;
 		const rendered = await invokeResponseStage(stageRequest, props, env, ctx, isWarmup ? {
 			cache: "shared",
 			renderWholeDocument: true
@@ -311,14 +446,19 @@ const handler = { async fetch(request, env, ctx) {
 			ctx.waitUntil(capture.admittedResponse.then(async (admitted) => {
 				if (!isCacheable(admitted)) {
 					await admitted.body?.cancel().catch(() => {});
+					capture.rscData?.catch(() => {});
 					return;
 				}
-				await responseStore.put(key, withoutRequestScopedHeaders(admitted, props), {
+				const stored = withoutRequestScopedHeaders(admitted, props);
+				try {
+					await putOtherPagePart(otherPart, capture, stored);
+				} catch (error) {
+					await stored.body?.cancel().catch(() => {});
+					throw error;
+				}
+				await responseStore.put(key, stored, {
 					coalesce: true,
-					revalidator: {
-						id: ROUTE_REVALIDATOR_ID,
-						args: [serializedInvocation]
-					}
+					revalidator: routeRevalidator(revalidatorInvocation, otherPart !== void 0)
 				});
 			}).catch((error) => {
 				console.error(JSON.stringify({
@@ -335,22 +475,20 @@ const handler = { async fetch(request, env, ctx) {
 			}), "MISS", props) : publicResponse(notModified, "MISS", props, true);
 		}
 		if (!isCacheable(rendered)) {
-			capture?.rscData?.catch(() => {});
+			capture.rscData?.catch(() => {});
 			return publicResponse(foreground(rendered), "BYPASS", props);
 		}
-		if (rscSeed && !capture?.rscData) {
+		if (rscKey && !capture.rscData) {
 			await rendered.body?.cancel();
 			throw new Error("Vinext response-store warmup did not capture the App page RSC payload");
 		}
 		const [foregroundBody, cacheBody] = rendered.body ? rendered.body.tee() : [null, null];
 		const cacheResponse = withoutRequestScopedHeaders(new Response(cacheBody, rendered), props);
 		try {
+			await putOtherPagePart(otherPart, capture, cacheResponse);
 			await responseStore.put(key, cacheResponse, {
 				coalesce: true,
-				revalidator: {
-					id: ROUTE_REVALIDATOR_ID,
-					args: [serializedInvocation]
-				}
+				revalidator: routeRevalidator(revalidatorInvocation, otherPart !== void 0)
 			});
 		} catch (error) {
 			if (isWarmup) throw error;
@@ -360,31 +498,6 @@ const handler = { async fetch(request, env, ctx) {
 				error: error instanceof Error ? error.message : String(error)
 			}));
 		}
-		if (rscSeed && rscInvocation && rscKey && capture?.rscData) {
-			const rscData = await capture.rscData;
-			const rscHeaders = new Headers(rendered.headers);
-			rscHeaders.delete("Content-Length");
-			rscHeaders.delete("Link");
-			rscHeaders.delete("X-Vinext-Response-Store-Replayable");
-			rscHeaders.delete(VINEXT_PARAMS_HEADER);
-			rscHeaders.delete(VINEXT_RENDERED_PATH_AND_SEARCH_HEADER);
-			rscHeaders.set("Content-Type", VINEXT_RSC_CONTENT_TYPE);
-			rscHeaders.set("Vary", VINEXT_RSC_VARY_HEADER$1);
-			applyRscCompatibilityIdHeader(rscHeaders);
-			applyRscDeploymentIdHeader(rscHeaders);
-			if (isStoredErrorStatus(rendered.status)) rscHeaders.set(VINEXT_SPECIAL_ERROR_STATUS_HEADER, String(rendered.status));
-			const serializedRscInvocation = JSON.stringify(rscInvocation);
-			await responseStore.put(rscKey, new Response(rscData, {
-				headers: rscHeaders,
-				status: rendered.status >= 300 && rendered.status < 400 ? 200 : rendered.status
-			}), {
-				coalesce: true,
-				revalidator: {
-					id: ROUTE_REVALIDATOR_ID,
-					args: [serializedRscInvocation]
-				}
-			});
-		}
 		return publicResponse(foreground(new Response(foregroundBody, rendered)), "MISS", props);
 	};
 	const { handleRequestStage } = await loadVinextRequestStage();

package/dist/cache/response-store-cdn.runtime.js

@@ -1,5 +1,5 @@
 import createCloudflareCdnCacheAdapter from "./cdn-adapter.runtime.js";
-import { captureResponseStoreRscData, deferResponseStoreAdmission, deferResponseStoreNotModified } from "./response-store-data.runtime.js";
+import { captureResponseStoreAppPageDocument, captureResponseStoreRscData, deferResponseStoreAdmission, deferResponseStoreNotModified } from "./response-store-data.runtime.js";
 //#region src/cache/response-store-cdn.runtime.ts
 /** Response Store owns page serving and SWR; vinext only emits admitted response policy. */
 var ResponseStoreCdnCacheAdapter = class {
@@ -33,6 +33,9 @@ var ResponseStoreCdnCacheAdapter = class {
 	captureAppPageRscData(rscData) {
 		captureResponseStoreRscData(rscData);
 	}
+	captureAppPageDocument() {
+		return captureResponseStoreAppPageDocument();
+	}
 	deferNotModifiedResponse() {
 		return deferResponseStoreNotModified();
 	}

package/dist/cache/response-store-data.runtime.d.ts

@@ -1,9 +1,14 @@
+import { CdnAppPageDocument } from "vinext/shims/cdn-cache";
 import { WorkersResponseStore } from "@cloudflare/workers-response-store";
 import { CacheHandler, CacheHandlerValue, IncrementalCacheValue } from "vinext/shims/cache";
 //#region src/cache/response-store-data.runtime.d.ts
 export type ResponseStoreInvocationCapture = {
   admittedResponse?: Promise<Response>;
+  /** Store the page's document beside an App page RSC response. */
+  captureDocument?: boolean;
   captureRscData?: boolean;
+  /** The page's document, set before admission completes the response. */
+  document?: CdnAppPageDocument;
   /** The render matched the request's If-None-Match; the adapter sends the 304. */
   notModified?: boolean;
   rscData?: Promise<ArrayBuffer>;
@@ -17,15 +22,24 @@ export declare function setResponseStore(store: WorkersResponseStore): void;
 export declare function runWithResponseStoreInvocation<T>(serialized: string, replayable: boolean, callback: () => T, capture?: ResponseStoreInvocationCapture): T;
 /** Retain the RSC side stream only when the outer response-store invocation requested it. */
 export declare function captureResponseStoreRscData(rscData: Promise<ArrayBuffer>): void;
+/**
+ * Retain the page's document only when the outer response-store invocation
+ * requested it. Admission settles it before it completes the response.
+ */
+export declare function captureResponseStoreAppPageDocument(): ((document: CdnAppPageDocument | null) => void) | undefined;
 /** A shared invocation stores the page, so its adapter sends the page's 304. */
 export declare function deferResponseStoreNotModified(): boolean;
 /** Stream the foreground body while retaining an independent admission branch. */
 export declare function deferResponseStoreAdmission(response: Response, complete: (response: Response) => Promise<Response>): Response | null;
+/** Keeps work a regeneration hands to waitUntil inside the regeneration. */
+export declare function trackResponseStoreRegenerationWork(work: Promise<unknown>): void;
 /** Re-render an invocation and return the exact rewritten data-cache entry. */
 export declare function captureResponseStoreDataRegeneration(key: string, callback: () => Promise<void>): Promise<Response>;
 export declare class WorkersResponseStoreCacheHandler implements CacheHandler {
   private readonly store;
   private readonly tagExpirations;
+  /** The revision behind each entry returned stale by the Store, for the write refreshing it. */
+  private readonly staleRevisions;
   constructor(store?: WorkersResponseStore);
   get(key: string, context?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
   set(key: string, value: IncrementalCacheValue | null, context?: Record<string, unknown>): Promise<void>;

package/dist/cache/response-store-data.runtime.js

@@ -1,5 +1,6 @@
 import { isStaleTagInvalidation } from "./workers-cache-invalidation.js";
 import { encodeCloudflareCacheTag } from "./cdn-adapter.runtime.js";
+import { readCacheTimestamp } from "../utils/cache-control-metadata.js";
 import { Buffer } from "node:buffer";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { cacheForRequest } from "vinext/cache";
@@ -8,6 +9,8 @@ const ARRAY_BUFFER_MARKER = "$vinextArrayBuffer";
 const CACHE_MAX_AGE_SECONDS = 31536e4;
 const DATA_ENTRY_PATH = "__vinext_data";
 const REPLAYABLE_HEADER = "X-Vinext-Response-Store-Replayable";
+/** The Store's internal header for when a response's generation started. */
+const GENERATED_AT_HEADER = "X-Workers-Response-Store-Generated-At";
 const MAX_CACHE_TAG_HEADER_BYTES = 16384;
 /** How long past its revalidate a current Store's hit can still be marked fresh: write latency. */
 const STALE_FRESH_HIT_GRACE_MS = 5e3;
@@ -34,6 +37,17 @@ function captureResponseStoreRscData(rscData) {
 	if (capture?.captureRscData) capture.rscData = rscData;
 	else rscData.catch(() => {});
 }
+/**
+* Retain the page's document only when the outer response-store invocation
+* requested it. Admission settles it before it completes the response.
+*/
+function captureResponseStoreAppPageDocument() {
+	const capture = invocationStorage.getStore()?.capture;
+	if (!capture?.captureDocument) return void 0;
+	return (document) => {
+		capture.document = document ?? void 0;
+	};
+}
 /** A shared invocation stores the page, so its adapter sends the page's 304. */
 function deferResponseStoreNotModified() {
 	const capture = invocationStorage.getStore()?.capture;
@@ -143,6 +157,10 @@ function deferResponseStoreAdmission(response, complete) {
 	writer.closed.catch((error) => finishAdmission({ reason: error }));
 	return new Response(foreground, response);
 }
+/** Keeps work a regeneration hands to waitUntil inside the regeneration. */
+function trackResponseStoreRegenerationWork(work) {
+	regenerationStorage.getStore()?.sideWrites.push(work.then(() => void 0, () => void 0));
+}
 /** Re-render an invocation and return the exact rewritten data-cache entry. */
 async function captureResponseStoreDataRegeneration(key, callback) {
 	const scope = {
@@ -202,6 +220,8 @@ function cachePolicy(revalidate, expire) {
 var WorkersResponseStoreCacheHandler = class {
 	store;
 	tagExpirations = cacheForRequest(() => /* @__PURE__ */ new Map());
+	/** The revision behind each entry returned stale by the Store, for the write refreshing it. */
+	staleRevisions = /* @__PURE__ */ new WeakMap();
 	constructor(store = responseStore) {
 		this.store = store;
 		if (!store) throw new Error("[vinext] The Workers Response Store adapter must run through its generated Cloudflare worker entry.");
@@ -238,10 +258,15 @@ var WorkersResponseStoreCacheHandler = class {
 				await this.store.purge({ pathPrefixes: [new URL(request.url).pathname] });
 				return null;
 			}
+			let tagExpiration;
 			if (softTags.length) {
 				const expiration = eagerExpiration ? await eagerExpiration : { value: await getTagExpiration() };
 				if ("error" in expiration) throw expiration.error;
 				if (expiration.value >= entry.lastModified) return null;
+				tagExpiration = {
+					tags: softTags,
+					expiration: expiration.value
+				};
 			}
 			const age = Date.now() - entry.lastModified;
 			const requestedRevalidate = readCacheControlField(context, "revalidate");
@@ -252,12 +277,18 @@ var WorkersResponseStoreCacheHandler = class {
 				if (requestedStale && storeStatus !== "BLOB-STALE") cacheState = "stale";
 			} else if (typeof entry.cacheControl?.expire === "number" && age > entry.cacheControl.expire * 1e3) cacheState = "expired";
 			else if (storeStatus === "BLOB-STALE" || requestedStale && typeof requestedRevalidate === "number" && (typeof storedRevalidate !== "number" || requestedRevalidate < storedRevalidate) || typeof storedRevalidate === "number" && storedRevalidate > 0 && age > storedRevalidate * 1e3 + STALE_FRESH_HIT_GRACE_MS) cacheState = "stale";
-			return {
+			const value = {
 				lastModified: entry.lastModified,
 				value: entry.value,
 				...cacheState ? { cacheState } : {},
 				...entry.cacheControl ? { cacheControl: entry.cacheControl } : {}
 			};
+			const revision = Number(response.headers.get("X-Workers-Response-Store-Revision"));
+			if (cacheState && storeStatus === "BLOB-STALE" && Number.isSafeInteger(revision) && revision > 0) this.staleRevisions.set(value, {
+				revision,
+				...tagExpiration ? { tagExpiration } : {}
+			});
+			return value;
 		} catch (error) {
 			console.error(JSON.stringify({
 				message: "Vinext response-store data lookup failed; treating as a cache miss",
@@ -268,8 +299,7 @@ var WorkersResponseStoreCacheHandler = class {
 	}
 	set(key, value, context) {
 		const write = this.write(key, value, context);
-		const regeneration = regenerationStorage.getStore();
-		if (regeneration && regeneration.targetKey !== key) regeneration.sideWrites.push(write);
+		regenerationStorage.getStore()?.sideWrites.push(write);
 		return write;
 	}
 	async write(key, value, context) {
@@ -302,11 +332,13 @@ var WorkersResponseStoreCacheHandler = class {
 			id: DATA_REVALIDATOR_ID,
 			args: [key, invocation.serialized]
 		} : void 0;
+		const lastModified = readCacheTimestamp(context, Date.now());
 		const response = new Response(serialize({
 			...cacheControl ? { cacheControl } : {},
-			lastModified: Date.now(),
+			lastModified,
 			value
 		}), { headers: {
+			...lastModified === context?.timestamp ? { [GENERATED_AT_HEADER]: String(lastModified) } : {},
 			"Cache-Control": cachePolicy(revalidate, expire),
 			...tagHeader ? { "Cache-Tag": tagHeader } : {},
 			"Content-Type": "application/json",
@@ -318,11 +350,17 @@ var WorkersResponseStoreCacheHandler = class {
 			return;
 		}
 		if (regeneration && !revalidator) return;
+		const staleEntry = context?.staleEntry;
+		const replaces = staleEntry && typeof staleEntry === "object" ? this.staleRevisions.get(staleEntry) : void 0;
 		await this.store.put(await cacheRequest(key), response, {
 			...revalidator ? { revalidator } : {},
 			...revalidator?.id !== "vinext:cache-function" ? { expiryBehavior: "miss" } : {},
 			coalesce: true,
-			purgeExisting: true
+			purgeExisting: true,
+			...replaces ? {
+				replacesRevision: replaces.revision,
+				...replaces.tagExpiration ? { replacesTagExpiration: replaces.tagExpiration } : {}
+			} : {}
 		});
 	}
 	async revalidateTag(tags, durations) {
@@ -339,4 +377,4 @@ function createResponseStoreDataCacheAdapter() {
 	return new WorkersResponseStoreCacheHandler();
 }
 //#endregion
-export { CACHE_FUNCTION_REVALIDATOR_ID, DATA_REVALIDATOR_ID, WorkersResponseStoreCacheHandler, captureResponseStoreDataRegeneration, captureResponseStoreRscData, createResponseStoreDataCacheAdapter as default, deferResponseStoreAdmission, deferResponseStoreNotModified, runWithResponseStoreInvocation, setResponseStore };
+export { CACHE_FUNCTION_REVALIDATOR_ID, DATA_REVALIDATOR_ID, WorkersResponseStoreCacheHandler, captureResponseStoreAppPageDocument, captureResponseStoreDataRegeneration, captureResponseStoreRscData, createResponseStoreDataCacheAdapter as default, deferResponseStoreAdmission, deferResponseStoreNotModified, runWithResponseStoreInvocation, setResponseStore, trackResponseStoreRegenerationWork };

package/dist/cli.js

@@ -45,6 +45,7 @@ async function deployCommand() {
 		preview: parsed.preview,
 		env: parsed.env,
 		config: parsed.config,
+		viteConfig: parsed.viteConfig,
 		skipBuild: parsed.skipBuild,
 		dryRun: parsed.dryRun,
 		verbose: parsed.verbose,
@@ -92,6 +93,7 @@ async function previewsCommand() {
 		root: process.cwd(),
 		env: options.mode,
 		skipBuild: options.skipBuild,
+		viteConfig: options.viteConfig,
 		target: {
 			type: "preview",
 			name: options.name

package/dist/deploy-config.d.ts

@@ -8,7 +8,7 @@ import { VinextCacheConfig } from "vinext/internal/config/prerender";
  * Returns true when the config both imports the package and invokes
  * `cloudflare(...)` in the plugin list.
  */
-export declare function viteConfigHasCloudflarePlugin(root: string): boolean;
+export declare function viteConfigHasCloudflarePlugin(root: string, configFile?: string): boolean;
 /**
  * Detect whether the Vite config assigns a CDN or data cache adapter — i.e. the
  * `cdn` or `data` field of the `vinext({ cache })` option is given a value.
@@ -17,12 +17,12 @@ export declare function viteConfigHasCloudflarePlugin(root: string): boolean;
  * an unreadable or absent config is treated as configured so a deploy is never
  * blocked on a false negative.
  */
-export declare function viteConfigHasCacheAdapter(root: string): boolean;
+export declare function viteConfigHasCacheAdapter(root: string, configFile?: string): boolean;
 export type ResolvedCdnAdapterConfig = {
   versionMetadataBinding: string;
 };
 export declare function resolveCdnAdapterConfig(cache: VinextCacheConfig | null | undefined): ResolvedCdnAdapterConfig | null;
-export declare function viteConfigHasImageAdapter(root: string): boolean;
+export declare function viteConfigHasImageAdapter(root: string, configFile?: string): boolean;
 /**
  * Detect whether an existing user-authored Worker entry wires up a cache
  * backend imperatively via one of the `setCacheHandler` / `setDataCacheHandler`
@@ -48,5 +48,5 @@ export declare function formatMissingCacheAdapterError(options: {
   configFile?: string;
   typedConfig?: boolean;
 }): string;
-export declare function formatImageOptimizationHint(typedConfig?: boolean): string;
+export declare function formatImageOptimizationHint(typedConfig?: boolean, configFile?: string): string;
 //#endregion

package/dist/deploy-config.js

@@ -15,8 +15,8 @@ function escapeRegExp(value) {
 * Returns true when the config both imports the package and invokes
 * `cloudflare(...)` in the plugin list.
 */
-function viteConfigHasCloudflarePlugin(root) {
-	const configPath = findViteConfigPath(root);
+function viteConfigHasCloudflarePlugin(root, configFile) {
+	const configPath = configFile ?? findViteConfigPath(root);
 	if (!configPath) return false;
 	try {
 		const content = fs.readFileSync(configPath, "utf-8").replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
@@ -75,8 +75,8 @@ function cacheFieldAssigned(cacheBlock, field) {
 * an unreadable or absent config is treated as configured so a deploy is never
 * blocked on a false negative.
 */
-function viteConfigHasCacheAdapter(root) {
-	const configPath = findViteConfigPath(root);
+function viteConfigHasCacheAdapter(root, configFile) {
+	const configPath = configFile ?? findViteConfigPath(root);
 	if (!configPath) return true;
 	let content;
 	try {
@@ -104,8 +104,8 @@ function resolveCdnAdapterConfig(cache) {
 	const options = cdn.options;
 	return { versionMetadataBinding: typeof options?.versionMetadataBinding === "string" && options.versionMetadataBinding.length > 0 ? options.versionMetadataBinding : DEFAULT_CDN_VERSION_METADATA_BINDING };
 }
-function viteConfigHasImageAdapter(root) {
-	const configPath = findViteConfigPath(root);
+function viteConfigHasImageAdapter(root, configFile) {
+	const configPath = configFile ?? findViteConfigPath(root);
 	if (!configPath) return true;
 	try {
 		const content = fs.readFileSync(configPath, "utf-8");
@@ -161,7 +161,10 @@ function formatMissingCacheAdapterError(options) {
 	const configRef = options.configFile ? options.configFile : "your Vite config";
 	return `[vinext] This app uses ISR / caching but no cache adapter is configured in ${configRef}.\n\n  Production deployments need a persistent cache backend. Declare one on the\n  vinext() plugin in ${configRef}:\n\n    import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";\n\n    export default defineConfig({\n      plugins: [\n        vinext({\n          cache: {\n            data: kvDataAdapter(), // KV-backed data cache (binding: VINEXT_KV_CACHE)\n          },\n        }),\n        cloudflare(),\n      ],\n    });\n\n` + (options.typedConfig ? `  Configure the VINEXT_KV_CACHE namespace binding in cloudflare.config.ts.` : "  The VINEXT_KV_CACHE namespace binding is added to wrangler.jsonc for you.\n  Create the namespace with:\n\n    npx wrangler kv namespace create VINEXT_KV_CACHE");
 }
-function formatImageOptimizationHint(typedConfig = false) {
+function formatImageOptimizationHint(typedConfig = false, configFile) {
+	if (configFile) return `  [vinext] next/image is served unoptimized. To enable edge image
+  optimization via Cloudflare Images, configure imagesOptimizer() in
+  ${configFile} and the IMAGES binding in ${typedConfig ? "cloudflare.config.ts" : "your Wrangler config"}.`;
 	if (typedConfig) return "  [vinext] next/image is served unoptimized. To enable edge image\n  optimization via Cloudflare Images, configure imagesOptimizer() in your\n  Vite config and the IMAGES binding in cloudflare.config.ts.";
 	return "  [vinext] next/image is served unoptimized. To enable edge image\n  optimization via Cloudflare Images, run:\n\n    vinext init --platform=cloudflare --image-optimization=cloudflare-images\n\n  This adds the imagesOptimizer() option to your Vite config and the matching\n  IMAGES binding to your Wrangler config without replacing existing settings.";
 }

package/dist/deploy-help.js

@@ -16,6 +16,7 @@ function formatDeployHelp() {
     --env <name>             Cloudflare mode for typed config; Wrangler environment otherwise
     --name <name>            Custom Worker name for Wrangler config projects
     --config <path>          Wrangler config path (default: wrangler.jsonc/json/toml)
+    --vite-config <path>     Vite config file to build with (default: vite.config.*)
     --skip-build             Skip the build step (use existing dist/)
     --dry-run                Validate setup without building or deploying
     --verbose                Print raw output from internal Cloudflare CLI commands
@@ -129,9 +130,10 @@ function formatPreviewsDeployHelp() {
     preview-name    Optional Preview name (cf uses the CI or Git branch if omitted)
 
   Options:
-    --mode <mode>   Vite mode to build and deploy in (default: production)
-    --skip-build    Deploy existing Preview Build Output without rebuilding
-    -h, --help      Show this help
+    --mode <mode>          Vite mode to build and deploy in (default: production)
+    --skip-build           Deploy existing Preview Build Output without rebuilding
+    --vite-config <path>   Vite config file to build with (default: vite.config.*)
+    -h, --help             Show this help
 
   Examples:
     vinext-cloudflare previews deploy

package/dist/deploy.d.ts

@@ -23,6 +23,8 @@ export type DeployOptions = {
   name?: string;
   /** Wrangler config path, relative to root unless absolute */
   config?: string;
+  /** Vite config file used to build and read deploy metadata, relative to root unless absolute */
+  viteConfig?: string;
   /** Skip the build step (assume already built) */
   skipBuild?: boolean;
   /** Dry run — validate setup but don't build or deploy */
@@ -85,6 +87,7 @@ export declare function parseDeployArgs(args: string[]): {
   env: string | undefined;
   name: string | undefined;
   config: string | undefined;
+  viteConfig: string | undefined;
   skipBuild: boolean;
   dryRun: boolean;
   verbose: boolean;