@vinext/cloudflare 1.2.1 → 1.3.0

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

@@ -0,0 +1,13 @@
+//#region src/cache/app-page-parts.d.ts
+/**
+ * Whether the response-stage props select an App page's own document or RSC
+ * payload, the two parts Next.js keeps in one entry, rather than a variant.
+ */
+export declare function isCanonicalAppPage(responseStageProps: unknown, isRscRequest: boolean): boolean;
+/**
+ * Whether a canonical RSC request has a document part. A `.rsc` path reaches
+ * its page's HTML path only through the app's trailingSlash policy, and
+ * vinext's client never sends one, so it stores its payload alone.
+ */
+export declare function hasDocumentPart(rscRequestUrl: string): boolean;
+//#endregion

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

@@ -0,0 +1,18 @@
+//#region src/cache/app-page-parts.ts
+/**
+* Whether the response-stage props select an App page's own document or RSC
+* payload, the two parts Next.js keeps in one entry, rather than a variant.
+*/
+function isCanonicalAppPage(responseStageProps, isRscRequest) {
+	return responseStageProps !== null && typeof responseStageProps === "object" && Reflect.get(responseStageProps, "kind") === "app-page" && Reflect.get(responseStageProps, "isRscRequest") === isRscRequest && (Reflect.get(responseStageProps, "matchKind") === "request" || Reflect.get(responseStageProps, "matchKind") === "resolved") && (!isRscRequest || Reflect.get(responseStageProps, "renderMode") === "navigation") && Reflect.get(responseStageProps, "interceptionContext") === null && Reflect.get(responseStageProps, "interceptionId") === null && Reflect.get(responseStageProps, "mountedSlotsHeader") === null;
+}
+/**
+* Whether a canonical RSC request has a document part. A `.rsc` path reaches
+* its page's HTML path only through the app's trailingSlash policy, and
+* vinext's client never sends one, so it stores its payload alone.
+*/
+function hasDocumentPart(rscRequestUrl) {
+	return !new URL(rscRequestUrl).pathname.endsWith(".rsc");
+}
+//#endregion
+export { hasDocumentPart, isCanonicalAppPage };

package/dist/cache/cdn-adapter.runtime.d.ts

@@ -13,6 +13,7 @@ export declare class CloudflareCdnCacheAdapter implements CdnCacheAdapter {
   private readonly versionMetadata?;
   private readonly versionMetadataBinding;
   readonly requiresCompletedResponseAdmission = true;
+  readonly responseStageCacheIdentity: "host-free";
   readonly responseVary: "verbatim";
   readonly responsePolicy: {
     isHeader(name: string): boolean;

package/dist/cache/cdn-adapter.runtime.js

@@ -150,6 +150,7 @@ var CloudflareCdnCacheAdapter = class {
 	versionMetadata;
 	versionMetadataBinding;
 	requiresCompletedResponseAdmission = true;
+	responseStageCacheIdentity = "host-free";
 	responseVary = "verbatim";
 	responsePolicy = {
 		isHeader(name) {

package/dist/cache/cdn-adapter.worker.js

@@ -1,7 +1,9 @@
 import { VINEXT_CDN_BUILD_ID_HEADER, getVinextCdnBuildIdentity } from "./cdn-build-id.js";
+import { hasDocumentPart, isCanonicalAppPage } from "./app-page-parts.js";
 import { SHARED_RESPONSE_STAGE_HEADER, finalizeGatewayResponse } from "./browser-cache-policy.js";
 import { hasCacheMethod, invalidateOrPurge } from "./workers-cache-invalidation.js";
 import { VINEXT_PRERENDER_READINESS_PATH, VINEXT_RSC_VARY_HEADER } from "vinext/internal/server/headers";
+import { createCanonicalRscRequestHeaders, createCanonicalRscRequestUrl, stripRscCacheBustingSearchParam } from "vinext/internal/server/app-rsc-cache-busting";
 import { isNonCacheableCacheControl, splitCacheControlDirectives } from "vinext/shims/cdn-cache";
 import { WorkerEntrypoint } from "cloudflare:workers";
 import "vinext/internal/server/cloudflare-workers-tracing";
@@ -15,11 +17,29 @@ const AUTHORIZATION_TRANSPORT_HEADER = "x-vinext-internal-authorization";
 const REQUEST_CACHE_CONTROL_TRANSPORT_HEADER = "x-vinext-internal-request-cache-control";
 const REQUEST_CF_TRANSPORT_HEADER = "x-vinext-internal-request-cf";
 const REQUEST_PRAGMA_TRANSPORT_HEADER = "x-vinext-internal-request-pragma";
+const RENDER_WHOLE_DOCUMENT_TRANSPORT_HEADER = "x-vinext-internal-render-whole-document";
+const DISPATCH_TRANSPORT_HEADER = "x-vinext-internal-dispatch";
+/** The stage props a host-free cache identity replaces. */
+const HOST_BEARING_PROPS = /* @__PURE__ */ new Set([
+	"requestHost",
+	"requestOrigin",
+	"requestUrl"
+]);
 const WARMUP_USER_AGENT = "vinext-cloudflare-cdn-warm";
 const RESPONSE_STAGE_WIRE_CACHE = {
 	bypass: "vinext-cloudflare-v1:bypass",
 	shared: "vinext-cloudflare-v1:shared"
 };
+/**
+* The statuses of a part Workers Cache just rendered for its entry, inline or
+* as a background refresh of a stale one.
+* https://developers.cloudflare.com/workers/cache/debugging/
+*/
+const RENDERED_ENTRY_CACHE_STATUSES = /* @__PURE__ */ new Set([
+	"EXPIRED",
+	"MISS",
+	"UPDATING"
+]);
 const FRAMEWORK_RESPONSE_VARY_FIELDS = new Set(VINEXT_RSC_VARY_HEADER.split(",").map((name) => name.trim().toLowerCase()));
 function isResponseStageReadinessRequest(request) {
 	return request.url.includes(VINEXT_PRERENDER_READINESS_PATH) && new URL(request.url).pathname === VINEXT_PRERENDER_READINESS_PATH;
@@ -63,20 +83,25 @@ function validateResponseStageBuildIdentity(response) {
 	return responseStageUnavailable();
 }
 function stripUntrustedTransportHeaders(request) {
-	if (!request.headers.has(AUTHORIZATION_TRANSPORT_HEADER) && !request.headers.has(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER) && !request.headers.has(REQUEST_CF_TRANSPORT_HEADER) && !request.headers.has(REQUEST_PRAGMA_TRANSPORT_HEADER)) return request;
+	if (!request.headers.has(AUTHORIZATION_TRANSPORT_HEADER) && !request.headers.has(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER) && !request.headers.has(REQUEST_CF_TRANSPORT_HEADER) && !request.headers.has(REQUEST_PRAGMA_TRANSPORT_HEADER) && !request.headers.has(RENDER_WHOLE_DOCUMENT_TRANSPORT_HEADER) && !request.headers.has(DISPATCH_TRANSPORT_HEADER)) return request;
 	const headers = new Headers(request.headers);
 	headers.delete(AUTHORIZATION_TRANSPORT_HEADER);
 	headers.delete(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER);
 	headers.delete(REQUEST_CF_TRANSPORT_HEADER);
 	headers.delete(REQUEST_PRAGMA_TRANSPORT_HEADER);
-	const sanitized = new Request(request, { headers });
-	const requestCf = Reflect.get(request, "cf");
-	if (requestCf !== void 0) Object.defineProperty(sanitized, "cf", {
+	headers.delete(RENDER_WHOLE_DOCUMENT_TRANSPORT_HEADER);
+	headers.delete(DISPATCH_TRANSPORT_HEADER);
+	return withRequestCf(new Request(request, { headers }), request);
+}
+/** Give a request built from another the platform's `request.cf` of that one. */
+function withRequestCf(request, source) {
+	const requestCf = Reflect.get(source, "cf");
+	if (requestCf !== void 0) Object.defineProperty(request, "cf", {
 		configurable: true,
 		enumerable: true,
 		value: requestCf
 	});
-	return sanitized;
+	return request;
 }
 function withWorkerHostRuntime(context, env) {
 	const candidateAssets = env && typeof env === "object" && Reflect.has(env, "ASSETS") ? Reflect.get(env, "ASSETS") : void 0;
@@ -100,7 +125,7 @@ function getResponseStageBinding(context, exportName, serializedInvocation) {
 	const target = binding({ props: JSON.parse(serializedInvocation) });
 	return hasFetch(target) ? target : null;
 }
-async function createCacheFacingRequest(request, serializedInvocation) {
+async function createCacheFacingRequest(request, serializedInvocation, identityRequest, dispatchRestore) {
 	const authorization = request.headers.get("Authorization");
 	let serializedRequestCf = null;
 	const requestCf = Reflect.get(request, "cf");
@@ -109,9 +134,9 @@ async function createCacheFacingRequest(request, serializedInvocation) {
 		if (json !== void 0) serializedRequestCf = encodeURIComponent(json);
 	} catch {}
 	const authorizationIdentity = authorization === null ? "absent" : `present:${authorization.length}:${authorization}`;
-	const frameworkVaryIdentity = JSON.stringify([...FRAMEWORK_RESPONSE_VARY_FIELDS].map((name) => [name, request.headers.get(name)]));
+	const frameworkVaryIdentity = JSON.stringify([...FRAMEWORK_RESPONSE_VARY_FIELDS].map((name) => [name, identityRequest.headers.get(name)]));
 	const responseStageBuildIdentity = getVinextCdnBuildIdentity() ?? "";
-	const bytes = new TextEncoder().encode(`${request.url}\0${serializedInvocation}\0${authorizationIdentity}\0${frameworkVaryIdentity}\0${responseStageBuildIdentity}`);
+	const bytes = new TextEncoder().encode(`${identityRequest.url}\0${serializedInvocation}\0${authorizationIdentity}\0${frameworkVaryIdentity}\0${responseStageBuildIdentity}`);
 	const key = [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 	const url = new URL(request.url);
 	url.searchParams.set("__vinext_cache_key", key);
@@ -125,7 +150,9 @@ async function createCacheFacingRequest(request, serializedInvocation) {
 	headers.delete(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER);
 	headers.delete(REQUEST_CF_TRANSPORT_HEADER);
 	headers.delete(REQUEST_PRAGMA_TRANSPORT_HEADER);
+	headers.delete(DISPATCH_TRANSPORT_HEADER);
 	if (authorization !== null) headers.set(AUTHORIZATION_TRANSPORT_HEADER, encodeURIComponent(authorization));
+	if (dispatchRestore !== null) headers.set(DISPATCH_TRANSPORT_HEADER, encodeURIComponent(JSON.stringify(dispatchRestore)));
 	if (serializedRequestCf !== null) headers.set(REQUEST_CF_TRANSPORT_HEADER, serializedRequestCf);
 	if (requestCacheControl !== null) headers.set(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER, encodeURIComponent(requestCacheControl));
 	if (requestPragma !== null) headers.set(REQUEST_PRAGMA_TRANSPORT_HEADER, encodeURIComponent(requestPragma));
@@ -149,6 +176,8 @@ function restoreResponseStageRequest(request, requestUrl, requestMethod) {
 	headers.delete(REQUEST_CACHE_CONTROL_TRANSPORT_HEADER);
 	headers.delete(REQUEST_CF_TRANSPORT_HEADER);
 	headers.delete(REQUEST_PRAGMA_TRANSPORT_HEADER);
+	headers.delete(RENDER_WHOLE_DOCUMENT_TRANSPORT_HEADER);
+	headers.delete(DISPATCH_TRANSPORT_HEADER);
 	if (serializedAuthorization !== null) try {
 		headers.set("Authorization", decodeURIComponent(serializedAuthorization));
 	} catch {}
@@ -199,11 +228,11 @@ function revalidatesStoredEntry(request) {
 	return request.headers.has("If-None-Match") || request.headers.has("If-Modified-Since");
 }
 /**
-* No client waits on a deployment warm-up or on a revalidation, as with the
-* Response Store's.
+* No client waits on a deployment warm-up, on a revalidation, as with the
+* Response Store's, or on the gateway's fill of a page's document.
 */
 function rendersWholeDocument(request) {
-	return request.headers.get("user-agent") === WARMUP_USER_AGENT || revalidatesStoredEntry(request);
+	return request.headers.get("user-agent") === WARMUP_USER_AGENT || request.headers.has(RENDER_WHOLE_DOCUMENT_TRANSPORT_HEADER) || revalidatesStoredEntry(request);
 }
 /**
 * A conditional revalidation of a Pages page skips getStaticPaths(), so only a
@@ -328,6 +357,8 @@ function getResponseStageInvocation(value, expectedCache) {
 	} catch {
 		return null;
 	}
+	const restoresDispatch = Reflect.get(value, "restoresDispatch");
+	if (restoresDispatch !== void 0 && restoresDispatch !== true) return null;
 	return {
 		...typeof expectedResponseStageBuildIdentity === "string" ? { expectedResponseStageBuildIdentity } : {},
 		options: {
@@ -336,6 +367,117 @@ function getResponseStageInvocation(value, expectedCache) {
 		},
 		props: Reflect.get(value, "props"),
 		requestMethod,
+		requestUrl,
+		...restoresDispatch ? { restoresDispatch } : {}
+	};
+}
+/**
+* The dispatch of the other part of the page a canonical App page part belongs
+* to. Next.js keeps a page's document and RSC payload in one entry, so the two
+* dispatches differ only in the RSC request selectors, the URL's `_rsc` and the
+* request type in the props. The request keeps the client's other headers,
+* minus those that would make the fetch conditional or partial. No client
+* waits on a document fetched this way, so it is rendered whole, marked by a
+* header that, unlike the props, does not key its entry.
+*/
+function otherPagePartDispatch(request, props) {
+	const isRscRequest = isCanonicalAppPage(props, true);
+	if (!isRscRequest && !isCanonicalAppPage(props, false)) return null;
+	if (isRscRequest && !hasDocumentPart(request.url)) return null;
+	const headers = new Headers(request.headers);
+	for (const name of FRAMEWORK_RESPONSE_VARY_FIELDS) headers.delete(name);
+	for (const name of [
+		"If-Match",
+		"If-Modified-Since",
+		"If-None-Match",
+		"If-Range",
+		"If-Unmodified-Since",
+		"Range"
+	]) headers.delete(name);
+	if (isRscRequest) {
+		const url = new URL(request.url);
+		stripRscCacheBustingSearchParam(url);
+		headers.delete("x-deployment-id");
+		headers.set("Accept", "text/html");
+		headers.set(RENDER_WHOLE_DOCUMENT_TRANSPORT_HEADER, "1");
+		return {
+			props: {
+				...props,
+				isRscRequest: false
+			},
+			request: withRequestCf(new Request(url, { headers }), request)
+		};
+	}
+	for (const [name, value] of createCanonicalRscRequestHeaders()) headers.set(name, value);
+	return {
+		props: {
+			...props,
+			isRscRequest: true,
+			renderMode: "navigation"
+		},
+		request: withRequestCf(new Request(new URL(createCanonicalRscRequestUrl(request.url), request.url), { headers }), request)
+	};
+}
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function pathAndSearch(url) {
+	return `${url.pathname}${url.search}`;
+}
+/**
+* What a shared dispatch's host-free identity replaced: the request URL, and
+* the top-level props that name the host. Null when the identity is anything
+* else, so the dispatch keys itself, host and all.
+*/
+function getDispatchRestore(request, props, identity) {
+	if (identity.request.method !== request.method || pathAndSearch(new URL(identity.request.url)) !== pathAndSearch(new URL(request.url))) return null;
+	const dispatched = JSON.parse(JSON.stringify(props) ?? "null");
+	const keyed = JSON.parse(JSON.stringify(identity.props) ?? "null");
+	if (!isPlainObject(dispatched) || !isPlainObject(keyed)) return null;
+	if (Object.keys(keyed).some((name) => !Object.hasOwn(dispatched, name))) return null;
+	const replaced = {};
+	for (const [name, value] of Object.entries(dispatched)) {
+		if (JSON.stringify(value) === JSON.stringify(keyed[name])) continue;
+		if (!HOST_BEARING_PROPS.has(name)) return null;
+		replaced[name] = value;
+	}
+	return {
+		props: replaced,
+		requestUrl: request.url
+	};
+}
+/**
+* Rebuild the dispatch a host-free invocation keys from the restore header
+* the gateway sent. Null when an identity invocation has no valid restore.
+*/
+function restoreDispatchInvocation(request, invocation) {
+	if (!invocation.restoresDispatch) return invocation;
+	const serialized = request.headers.get(DISPATCH_TRANSPORT_HEADER);
+	if (serialized === null || !isPlainObject(invocation.props)) return null;
+	let restore;
+	try {
+		restore = JSON.parse(decodeURIComponent(serialized));
+	} catch {
+		return null;
+	}
+	if (!isPlainObject(restore) || !isPlainObject(restore.props)) return null;
+	if (Object.keys(restore.props).some((name) => !HOST_BEARING_PROPS.has(name))) return null;
+	const requestUrl = restore.requestUrl;
+	if (typeof requestUrl !== "string") return null;
+	let url;
+	try {
+		url = new URL(requestUrl);
+	} catch {
+		return null;
+	}
+	if (pathAndSearch(url) !== pathAndSearch(new URL(invocation.requestUrl))) return null;
+	const { restoresDispatch: _restoresDispatch, ...dispatch } = invocation;
+	return {
+		...dispatch,
+		props: {
+			...invocation.props,
+			...restore.props
+		},
 		requestUrl
 	};
 }
@@ -363,22 +505,27 @@ var VinextCachedResponse = class extends WorkerEntrypoint {
 			headers: { "Cache-Control": "no-store" }
 		}));
 		if (invocation.expectedResponseStageBuildIdentity !== void 0 && invocation.expectedResponseStageBuildIdentity !== getVinextCdnBuildIdentity()) return stampResponseStageBuildIdentity(responseStageUnavailable());
-		const restored = restoreResponseStageRequest(request, invocation.requestUrl, invocation.requestMethod);
-		const isAppPageDocument = isAppPageDocumentInvocation(invocation);
-		const isPagesPage = isPagesPageInvocation(invocation);
+		const dispatch = restoreDispatchInvocation(request, invocation);
+		if (!dispatch) return stampResponseStageBuildIdentity(new Response("Invalid vinext response-stage invocation", {
+			status: 400,
+			headers: { "Cache-Control": "no-store" }
+		}));
+		const restored = restoreResponseStageRequest(request, dispatch.requestUrl, dispatch.requestMethod);
+		const isAppPageDocument = isAppPageDocumentInvocation(dispatch);
+		const isPagesPage = isPagesPageInvocation(dispatch);
 		const response = await invokeResponseStage(restored.request, this.env, context, isAppPageDocument && rendersWholeDocument(request) ? {
-			...invocation,
+			...dispatch,
 			options: {
-				...invocation.options,
+				...dispatch.options,
 				renderWholeDocument: true
 			}
 		} : isPagesPage && revalidatesStoredEntry(request) ? {
-			...invocation,
+			...dispatch,
 			options: {
-				...invocation.options,
+				...dispatch.options,
 				regeneratesStoredEntry: true
 			}
-		} : invocation);
+		} : dispatch);
 		return stampResponseStageBuildIdentity(restored.didAccessRequestCf() || hasTaggedCustomVary(response) ? preventResponseCaching(response) : isAppPageDocument ? withRevalidationValidator(response) : isPagesPage ? withPagesRevalidationValidator(response) : response);
 	}
 	async purge(options) {
@@ -408,30 +555,71 @@ var cdn_adapter_worker_default = { async fetch(request, env, context) {
 	request = stripUntrustedTransportHeaders(request);
 	const sharedResponses = /* @__PURE__ */ new Map();
 	const stageContext = withResponseStageCache(withWorkerHostRuntime(context, env));
-	const dispatchResponseStage = async (stageRequest, props, options) => {
+	const createInvocation = (stageRequest, props, options) => {
 		const expectedResponseStageBuildIdentity = getVinextCdnBuildIdentity();
-		const invocation = {
+		const { cacheIdentity: _cacheIdentity, ...stageOptions } = options;
+		return {
 			...expectedResponseStageBuildIdentity === null ? {} : { expectedResponseStageBuildIdentity },
-			options,
+			options: stageOptions,
 			props,
 			requestMethod: stageRequest.method,
 			requestUrl: stageRequest.url
 		};
+	};
+	/** Fetch a response stage through its named entrypoint, the cached one for a shared dispatch. */
+	const fetchResponseStageEntrypoint = async (stageRequest, props, options) => {
+		const invocation = createInvocation(stageRequest, props, options);
+		const usesSharedCache = options.cache === "shared";
+		const { cacheIdentity } = options;
+		const dispatchRestore = usesSharedCache && cacheIdentity ? getDispatchRestore(stageRequest, props, cacheIdentity) : null;
+		const keyedRequest = dispatchRestore ? cacheIdentity.request : stageRequest;
+		const serializedInvocation = JSON.stringify({
+			...invocation,
+			...dispatchRestore ? {
+				props: cacheIdentity.props,
+				requestMethod: keyedRequest.method,
+				requestUrl: keyedRequest.url,
+				restoresDispatch: true
+			} : {},
+			options: invocation.expectedResponseStageBuildIdentity === void 0 ? invocation.options : {
+				...invocation.options,
+				cache: RESPONSE_STAGE_WIRE_CACHE[options.cache]
+			}
+		});
+		const binding = getResponseStageBinding(stageContext, usesSharedCache ? CACHED_RESPONSE_STAGE_EXPORT : UNCACHED_RESPONSE_STAGE_EXPORT, serializedInvocation);
+		if (!binding) return responseStageUnavailable();
+		const entrypointRequest = usesSharedCache ? await createCacheFacingRequest(stageRequest, serializedInvocation, keyedRequest, dispatchRestore) : stageRequest;
+		return validateResponseStageBuildIdentity(await binding.fetch(entrypointRequest));
+	};
+	/**
+	* Fetch the other part of a canonical App page part Workers Cache just
+	* rendered, so its entry is filled or refreshed too. Workers Cache stores
+	* only what its entrypoint returns, so the other part renders on its own.
+	* A deployment warm-up already requests both parts, and this fetch reaches
+	* the entrypoint directly, so it never fetches another part itself.
+	*/
+	const storeOtherPagePart = (stageRequest, props, options, cacheStatus) => {
+		if (cacheStatus === null || !RENDERED_ENTRY_CACHE_STATUSES.has(cacheStatus) || stageRequest.headers.get("user-agent") === WARMUP_USER_AGENT || typeof stageContext.waitUntil !== "function") return;
+		stageContext.waitUntil((async () => {
+			const otherPart = otherPagePartDispatch(stageRequest, props);
+			if (!otherPart) return;
+			const { cacheIdentity, ...otherOptions } = options;
+			const otherIdentity = cacheIdentity ? otherPagePartDispatch(cacheIdentity.request, cacheIdentity.props) : null;
+			await (await fetchResponseStageEntrypoint(otherPart.request, otherPart.props, otherIdentity ? {
+				...otherOptions,
+				cacheIdentity: otherIdentity
+			} : otherOptions)).body?.pipeTo(new WritableStream());
+		})().catch((error) => {
+			console.error("[vinext] Workers Cache could not store a page's other part:", error);
+		}));
+	};
+	const dispatchResponseStage = async (stageRequest, props, options) => {
 		const usesSharedCache = options.cache === "shared";
 		try {
-			if (!usesSharedCache && !isResponseStageReadinessRequest(stageRequest)) return stampResponseStageBuildIdentity(await invokeResponseStage(stageRequest, env, stageContext, invocation));
-			const serializedInvocation = JSON.stringify({
-				...invocation,
-				options: expectedResponseStageBuildIdentity === null ? options : {
-					...options,
-					cache: RESPONSE_STAGE_WIRE_CACHE[options.cache]
-				}
-			});
-			const binding = getResponseStageBinding(stageContext, usesSharedCache ? CACHED_RESPONSE_STAGE_EXPORT : UNCACHED_RESPONSE_STAGE_EXPORT, serializedInvocation);
-			if (!binding) return responseStageUnavailable();
-			const entrypointRequest = usesSharedCache ? await createCacheFacingRequest(stageRequest, serializedInvocation) : stageRequest;
-			const response = validateResponseStageBuildIdentity(await binding.fetch(entrypointRequest));
+			if (!usesSharedCache && !isResponseStageReadinessRequest(stageRequest)) return stampResponseStageBuildIdentity(await invokeResponseStage(stageRequest, env, stageContext, createInvocation(stageRequest, props, options)));
+			const response = await fetchResponseStageEntrypoint(stageRequest, props, options);
 			if (!usesSharedCache) return response;
+			storeOtherPagePart(stageRequest, props, options, response.headers.get("CF-Cache-Status"));
 			const shared = markSharedResponseStage(response, crypto.randomUUID(), props, true);
 			sharedResponses.set(shared.headers.get(SHARED_RESPONSE_STAGE_HEADER), { headers: new Headers(shared.headers) });
 			return shared;

package/dist/cache/kv-data-adapter.runtime.js

@@ -1,5 +1,5 @@
 import { isStaleTagInvalidation } from "./workers-cache-invalidation.js";
-import { isUnknownRecord, readCacheControlNumberField } from "../utils/cache-control-metadata.js";
+import { isUnknownRecord, readCacheControlNumberField, readCacheTimestamp } from "../utils/cache-control-metadata.js";
 import { ENTRY_PREFIX, createKvKeySpace, resolveKvExpirationTtlSeconds } from "./kv-key.js";
 import { Buffer } from "node:buffer";
 import { getRequestExecutionContext } from "vinext/shims/request-context";
@@ -308,7 +308,7 @@ var KVCacheHandler = class {
 		const effectiveStale = readCacheControlNumberField(ctx, "stale");
 		if (data && "revalidate" in data && typeof data.revalidate === "number") effectiveRevalidate = data.revalidate;
 		if (effectiveRevalidate === 0) return Promise.resolve();
-		const now = Date.now();
+		const now = readCacheTimestamp(ctx, Date.now());
 		const revalidateAt = typeof effectiveRevalidate === "number" && effectiveRevalidate > 0 && Number.isFinite(effectiveRevalidate) ? now + effectiveRevalidate * 1e3 : null;
 		const expireAt = typeof effectiveExpire === "number" && effectiveExpire > 0 ? now + effectiveExpire * 1e3 : null;
 		const cacheControl = typeof effectiveRevalidate === "number" ? {

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

@@ -1,7 +1,8 @@
+import { hasDocumentPart, 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 { 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";
@@ -58,6 +61,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 +107,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 +162,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 +183,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) && hasDocumentPart(identityRequest.url)) 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 +411,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 +425,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 +443,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 +472,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 +495,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,6 +22,11 @@ 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. */
@@ -26,6 +36,8 @@ export declare function captureResponseStoreDataRegeneration(key: string, callba
 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;
@@ -202,6 +216,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 +254,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 +273,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",
@@ -302,11 +329,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 +347,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 +374,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 };

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;

package/dist/deploy.js

@@ -99,6 +99,7 @@ const deployArgOptions = {
 	env: { type: "string" },
 	name: { type: "string" },
 	config: { type: "string" },
+	"vite-config": { type: "string" },
 	"skip-build": {
 		type: "boolean",
 		default: false
@@ -249,6 +250,7 @@ function parseDeployArgs(args) {
 		env: values.env?.trim() || void 0,
 		name: values.name?.trim() || void 0,
 		config: values.config?.trim() || void 0,
+		viteConfig: values["vite-config"]?.trim() || void 0,
 		skipBuild: values["skip-build"],
 		dryRun: values["dry-run"],
 		verbose: values.verbose,
@@ -339,11 +341,11 @@ async function loadProjectWranglerApi(root) {
 function resolveViteBuildMode(deploymentTool, env) {
 	return deploymentTool === "cf" ? env ?? "production" : "production";
 }
-async function loadDeployViteConfigMetadata(root, mode) {
+async function loadDeployViteConfigMetadata(root, mode, configFile) {
 	const plugins = (await (await loadProjectViteApi(root)).loadConfigFromFile({
 		command: "build",
 		mode
-	}, void 0, root))?.config.plugins;
+	}, configFile, root))?.config.plugins;
 	return {
 		cacheConfig: await findVinextCacheConfigInPlugins(plugins),
 		nextConfig: await findVinextNextConfigInPlugins(plugins),
@@ -351,7 +353,7 @@ async function loadDeployViteConfigMetadata(root, mode) {
 		routeRootConfig: await findVinextRouteRootConfigInPlugins(plugins)
 	};
 }
-async function runBuild(info, env, mode) {
+async function runBuild(info, env, mode, configFile) {
 	console.log("\n  Building for Cloudflare Workers...\n");
 	const { createBuilder } = await loadProjectViteApi(info.root);
 	let completed = false;
@@ -362,6 +364,7 @@ async function runBuild(info, env, mode) {
 		await (await createBuilder({
 			root: info.root,
 			mode,
+			configFile,
 			[VINEXT_BUILD_LIFECYCLE_CONFIG]: invocation
 		})).buildApp();
 	});
@@ -1190,6 +1193,7 @@ async function deploy(options) {
 	if (isPreview && deploymentTool !== "cf") throw new Error("Worker Previews require a cloudflare.config.ts project and the cf CLI.");
 	if (deploymentTool === "cf" && options.name) throw new Error("--name is not supported for cloudflare.config.ts projects. Set `name` in cloudflare.config.ts instead.");
 	const viteMode = resolveViteBuildMode(deploymentTool, deployEnv);
+	const viteConfigFile = options.viteConfig ? path.resolve(root, options.viteConfig) : void 0;
 	const wranglerFallbackEnv = deploymentTool === "cf" ? void 0 : deployEnv;
 	if (!process.env.NODE_ENV) Reflect.set(process.env, "NODE_ENV", "production");
 	loadDotenv({
@@ -1210,16 +1214,25 @@ async function deploy(options) {
 	console.log(`  Project: ${info.projectName}`);
 	console.log(`  Router:  ${info.isAppRouter ? "App Router" : "Pages Router"}`);
 	console.log(`  ISR:     ${info.hasISR ? "detected" : "none"}`);
-	const missingScaffolding = [!info.hasViteConfig && "Vite config", !info.hasWranglerConfig && "Wrangler config"].filter((value) => Boolean(value));
+	if (viteConfigFile && !fs.existsSync(viteConfigFile)) throw new Error(`Vite config file not found: ${viteConfigFile}`);
+	const hasViteConfig = Boolean(viteConfigFile) || info.hasViteConfig;
+	const missingScaffolding = [!hasViteConfig && "Vite config", !info.hasWranglerConfig && "Wrangler config"].filter((value) => Boolean(value));
 	if (missingScaffolding.length > 0) throw new Error(`Missing Cloudflare deployment setup: ${missingScaffolding.join(", ")}. Run \`vinext init --platform=cloudflare\` first.`);
 	const missingDeps = getMissingDeps(info);
 	if (missingDeps.length > 0) throw new Error(`Missing deployment dependencies: ${missingDeps.map((dependency) => dependency.name).join(", ")}. Run \`vinext init --platform=cloudflare\` first.`);
 	if (deploymentTool === "cf" && !isCfCliInstalled(root)) throw new Error("Missing deployment dependencies: cf. Run `vinext init --platform=cloudflare` first.");
-	if (info.hasViteConfig && !viteConfigHasCloudflarePlugin(root)) throw new Error(formatMissingCloudflarePluginError({ isAppRouter: info.isAppRouter }));
-	if (info.hasISR && !viteConfigHasCacheAdapter(root) && !workerEntryHasCacheHandler(root)) throw new Error(formatMissingCacheAdapterError({ typedConfig: deploymentTool === "cf" }));
-	if (!viteConfigHasImageAdapter(root)) {
+	if (hasViteConfig && !viteConfigHasCloudflarePlugin(root, viteConfigFile)) throw new Error(formatMissingCloudflarePluginError({
+		isAppRouter: info.isAppRouter,
+		configFile: viteConfigFile,
+		initUpdatesConfig: !viteConfigFile
+	}));
+	if (info.hasISR && !viteConfigHasCacheAdapter(root, viteConfigFile) && !workerEntryHasCacheHandler(root)) throw new Error(formatMissingCacheAdapterError({
+		configFile: viteConfigFile,
+		typedConfig: deploymentTool === "cf"
+	}));
+	if (!viteConfigHasImageAdapter(root, viteConfigFile)) {
 		console.log();
-		console.log(formatImageOptimizationHint(deploymentTool === "cf"));
+		console.log(formatImageOptimizationHint(deploymentTool === "cf", viteConfigFile));
 	}
 	if (options.dryRun) {
 		console.log("\n  Dry run complete. No build or deploy performed.\n");
@@ -1233,7 +1246,7 @@ async function deploy(options) {
 		}));
 		return;
 	}
-	const viteConfigMetadata = await withBuildContext(() => loadDeployViteConfigMetadata(info.root, viteMode));
+	const viteConfigMetadata = await withBuildContext(() => loadDeployViteConfigMetadata(info.root, viteMode, viteConfigFile));
 	const cdnAdapterConfig = resolveCdnAdapterConfig(viteConfigMetadata.cacheConfig);
 	const nextConfig = await withBuildContext(async () => {
 		const inlineNextConfig = viteConfigMetadata.nextConfig;
@@ -1259,7 +1272,7 @@ async function deploy(options) {
 		const replacement = isPreview ? "Preview deployments render these routes on request." : options.warmCdnCache ? "Routes will be rendered and warmed through the staged Worker instead." : "Use --warm-cache to render and warm routes through the deployed Worker instead.";
 		console.warn(`\n  Warning: ${trigger} is ignored by Cloudflare deploy. ${replacement}`);
 	}
-	if (!options.skipBuild) await withBuildContext(() => runBuild(info, cloudflareEnv, viteMode));
+	if (!options.skipBuild) await withBuildContext(() => runBuild(info, cloudflareEnv, viteMode, viteConfigFile));
 	else console.log("\n  Skipping build (--skip-build)");
 	const prerenderOutputDirs = resolvePrerenderOutputDirs(info.root, deploymentTool, viteConfigMetadata.routeRootConfig);
 	const canWarmTpr = options.experimentalTPR && !shouldPrerenderLocally && hasBuildIdentityHeader;

package/dist/previews-deploy.d.ts

@@ -5,5 +5,6 @@ export declare function parsePreviewsDeployArgs(args: string[]): {
   name: string | undefined;
   mode: string | undefined;
   skipBuild: boolean;
+  viteConfig: string | undefined;
 };
 //#endregion

package/dist/previews-deploy.js

@@ -28,7 +28,8 @@ function parsePreviewsDeployArgs(args) {
 			"skip-build": {
 				type: "boolean",
 				default: false
-			}
+			},
+			"vite-config": { type: "string" }
 		}
 	});
 	if (positionals.length > 1) throw new Error("Expected at most one Preview name: previews deploy [preview-name].");
@@ -36,7 +37,8 @@ function parsePreviewsDeployArgs(args) {
 		help: values.help,
 		name: positionals[0] === void 0 ? void 0 : validatePreviewName(positionals[0]),
 		mode: values.mode === void 0 ? void 0 : validateMode(values.mode),
-		skipBuild: values["skip-build"]
+		skipBuild: values["skip-build"],
+		viteConfig: values["vite-config"]?.trim() || void 0
 	};
 }
 //#endregion

package/dist/utils/cache-control-metadata.d.ts

@@ -6,5 +6,10 @@
  * helpers in the vinext core).
  */
 export declare function isUnknownRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * When a `"use cache"` entry's generation started (`ctx.timestamp`), which dates
+ * the entry like Next.js does. Absent, malformed or future values fall back to `now`.
+ */
+export declare function readCacheTimestamp(ctx: Record<string, unknown> | undefined, now: number): number;
 export declare function readCacheControlNumberField(ctx: Record<string, unknown> | undefined, field: string): number | undefined;
 //#endregion

package/dist/utils/cache-control-metadata.js

@@ -12,9 +12,17 @@ function readRecordField(ctx, field) {
 	const value = ctx?.[field];
 	return isUnknownRecord(value) ? value : void 0;
 }
+/**
+* When a `"use cache"` entry's generation started (`ctx.timestamp`), which dates
+* the entry like Next.js does. Absent, malformed or future values fall back to `now`.
+*/
+function readCacheTimestamp(ctx, now) {
+	const value = ctx?.timestamp;
+	return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= now ? value : now;
+}
 function readCacheControlNumberField(ctx, field) {
 	const value = readRecordField(ctx, "cacheControl")?.[field] ?? ctx?.[field];
 	return typeof value === "number" ? value : void 0;
 }
 //#endregion
-export { isUnknownRecord, readCacheControlNumberField };
+export { isUnknownRecord, readCacheControlNumberField, readCacheTimestamp };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vinext/cloudflare",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Cloudflare cache and image adapters for vinext.",
   "homepage": "https://vinext.dev/",
   "license": "MIT",
@@ -48,7 +48,7 @@
     }
   },
   "dependencies": {
-    "@cloudflare/workers-response-store": "1.1.3"
+    "@cloudflare/workers-response-store": "1.1.4"
   },
   "devDependencies": {
     "@types/node": "^25.9.2",
@@ -56,12 +56,12 @@
     "miniflare": "5.20260730.0-alpha",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
     "vite-plus": "1.3.0",
-    "vinext": "1.3.1"
+    "vinext": "1.4.0"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "*",
     "cf": "*",
-    "vinext": "^1.3.1"
+    "vinext": "^1.4.0"
   },
   "peerDependenciesMeta": {
     "@cloudflare/vite-plugin": {