@vinext/cloudflare 1.0.0-beta.9 → 1.0.0

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

@@ -1,5 +1,6 @@
 import { captureResponseStoreDataRegeneration, runWithResponseStoreInvocation, setResponseStore } from "./response-store-data.runtime.js";
-import { VINEXT_RSC_CONTENT_TYPE, VINEXT_RSC_VARY_HEADER, applyRscCompatibilityIdHeader, applyRscDeploymentIdHeader, createCanonicalRscRequestHeaders, createCanonicalRscRequestUrl } from "vinext/internal/server/app-rsc-cache-busting";
+import { VINEXT_PARAMS_HEADER, VINEXT_RENDERED_PATH_AND_SEARCH_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 { isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
 import { loadVinextRequestStage } from "vinext/server/request-stage";
 import { loadVinextResponseStage } from "vinext/server/response-stage";
@@ -9,7 +10,7 @@ const ROUTE_REVALIDATOR_ID = "vinext:response";
 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";
-const REPLAY_REQUEST_HEADERS = VINEXT_RSC_VARY_HEADER.split(",").map((name) => name.trim().toLowerCase());
+const REPLAY_REQUEST_HEADERS = VINEXT_RSC_VARY_HEADER$1.split(",").map((name) => name.trim().toLowerCase());
 const CACHE_REQUEST_VARY_HEADERS = REPLAY_REQUEST_HEADERS.map((name) => [name, "vinext-keyed"]);
 function stageContext(ctx, env) {
 	const assets = Reflect.get(env, "ASSETS");
@@ -42,15 +43,18 @@ function isReplayableInvocation(request, props) {
 	if (request.headers.has("authorization") || request.headers.has("cookie")) return false;
 	return !(props && typeof props === "object" && ["draftModeCookie", "middlewareCookieOverlay"].some((name) => name in props && Reflect.get(props, name) !== null));
 }
-function serializeInvocation(request, props) {
-	return JSON.stringify({
+function prepareInvocation(request, props) {
+	return {
 		props: safeProps(props),
 		request: {
 			headers: replayHeaders(request),
 			method: request.method,
 			url: request.url
 		}
-	});
+	};
+}
+function serializeInvocation(request, props) {
+	return JSON.stringify(prepareInvocation(request, props));
 }
 function parseInvocation(value) {
 	if (typeof value !== "string") throw new TypeError("Invalid vinext response-store invocation");
@@ -68,17 +72,23 @@ async function invokeRequestStage(request, env, ctx) {
 	const { handleRequestStage } = await loadVinextRequestStage();
 	return handleRequestStage(request, env, stageContext(ctx, env), (request, props, options) => invokeResponseStage(request, props, env, ctx, options.cache));
 }
-async function invokeResponseStage(request, props, env, ctx, cache, capture) {
+async function invokeResponseStage(request, props, env, ctx, cache, capture, invocation) {
 	const context = stageContext(ctx, env);
 	const dispatchRequestStage = (request) => invokeRequestStage(request, env, ctx);
 	const { handleResponseStage } = await loadVinextResponseStage();
-	const serialized = serializeInvocation(request, props);
-	return runWithResponseStoreInvocation(serialized, isReplayableInvocation(request, props), () => handleResponseStage(request, env, context, props, dispatchRequestStage, { cache }), capture);
+	const storedInvocation = invocation ?? {
+		replayable: isReplayableInvocation(request, props),
+		serialized: serializeInvocation(request, props)
+	};
+	return runWithResponseStoreInvocation(storedInvocation.serialized, storedInvocation.replayable, () => handleResponseStage(request, env, context, props, dispatchRequestStage, { cache }), capture);
 }
 function createVinextResponseStoreOptions(configuration) {
+	const locationHint = configuration?.locationHint;
+	if (locationHint !== void 0 && typeof locationHint !== "string") throw new TypeError("Workers Response Store locationHint must be a string");
 	const shards = configuration?.shards;
 	if (shards !== void 0 && typeof shards !== "number") throw new TypeError("Workers Response Store shards must be a number");
 	return {
+		...locationHint === void 0 ? {} : { locationHint },
 		...shards === void 0 ? {} : { shards },
 		async regenerate(input, { env, ctx }) {
 			if (input.id === ROUTE_REVALIDATOR_ID) {
@@ -88,7 +98,7 @@ function createVinextResponseStoreOptions(configuration) {
 					await response.body?.cancel().catch(() => {});
 					throw new Error("Vinext response-stage regeneration was not cacheable");
 				}
-				return response;
+				return withoutRequestScopedHeaders(response, invocation.props);
 			}
 			if (input.id === "vinext:cache-function" && typeof input.args[0] === "string" && typeof input.args[1] === "string") {
 				const invocation = JSON.parse(input.args[1]);
@@ -109,27 +119,56 @@ function createVinextResponseStoreOptions(configuration) {
 		}
 	};
 }
-async function cacheRequest(request, props) {
+async function cacheRequest(invocation) {
 	const identity = JSON.stringify([
-		request.method,
-		request.url,
-		safeProps(props),
-		replayHeaders(request)
+		invocation.request.method,
+		invocation.request.url,
+		invocation.props,
+		invocation.request.headers
 	]);
 	const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(identity)));
-	const url = new URL(request.url);
+	const url = new URL(invocation.request.url);
 	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"
 	});
 }
+/**
+* The request stage recomposes the routed params and path on every App page
+* RSC response, HITs included, so such an entry shared across queries must not
+* carry the values of the request that filled it. Every other response kind
+* (route handlers, metadata routes, HTML, Pages) keeps its headers as rendered.
+*/
+function withoutRequestScopedHeaders(response, responseStageProps) {
+	if (responseStageProps === null || typeof responseStageProps !== "object" || Reflect.get(responseStageProps, "kind") !== "app-page" || Reflect.get(responseStageProps, "isRscRequest") !== true) return response;
+	const headers = new Headers(response.headers);
+	headers.delete(VINEXT_PARAMS_HEADER);
+	headers.delete(VINEXT_RENDERED_PATH_AND_SEARCH_HEADER);
+	return new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+}
 function isCacheable(response) {
 	const policy = response.headers.get("Cloudflare-CDN-Cache-Control") ?? response.headers.get("CDN-Cache-Control") ?? response.headers.get("Cache-Control");
 	return response.status >= 200 && response.status < 400 && policy !== null && !isNonCacheableCacheControl(policy);
 }
-function isResponseStoreMiss(response) {
-	return response.status === 404 && response.headers.get("X-Workers-Response-Store") === "MISS";
+async function readStoredResponse(key) {
+	try {
+		const response = await responseStore.fetch(key);
+		if (response.status >= 200 && response.status < 400) return response;
+		response.body?.cancel().catch(() => {});
+		if (response.status === 404 && response.headers.get("X-Workers-Response-Store") === "MISS") return null;
+		throw new Error(`Workers Response Store returned ${response.status}`);
+	} catch (error) {
+		console.error(JSON.stringify({
+			message: "Vinext response-store response lookup failed; treating as a cache miss",
+			error: error instanceof Error ? error.message : String(error)
+		}));
+		return null;
+	}
 }
 function publicResponse(response, cacheStatus, responseStageProps) {
 	const headers = new Headers(response.headers);
@@ -170,42 +209,49 @@ function createVinextResponseStoreHandler(store) {
 const handler = { async fetch(request, env, ctx) {
 	const context = stageContext(ctx, env);
 	const dispatchResponseStage = async (stageRequest, props, options) => {
-		const invocation = serializeInvocation(stageRequest, props);
 		if (options.cache === "bypass" || stageRequest.method !== "GET" && stageRequest.method !== "HEAD") return publicResponse(await invokeResponseStage(stageRequest, props, env, ctx, "bypass"), "BYPASS", props);
+		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: {
-				...props,
+				...identityProps,
 				isRscRequest: true,
 				renderMode: "navigation"
 			},
-			request: new Request(new URL(createCanonicalRscRequestUrl(stageRequest.url), stageRequest.url), { headers: createCanonicalRscRequestHeaders() })
+			request: new Request(new URL(createCanonicalRscRequestUrl(identityRequest.url), identityRequest.url), { headers: createCanonicalRscRequestHeaders() })
 		} : void 0;
-		const rscKey = rscSeed ? await cacheRequest(rscSeed.request, rscSeed.props) : void 0;
-		const key = await cacheRequest(stageRequest, props);
-		const stored = await responseStore.fetch(key);
-		if (!isResponseStoreMiss(stored)) {
+		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) {
 			if (!rscKey) return publicResponse(stored, "HIT", props);
-			const storedRsc = await responseStore.fetch(rscKey);
-			if (!isResponseStoreMiss(storedRsc)) {
-				await storedRsc.body?.cancel();
+			const storedRsc = await readStoredResponse(rscKey);
+			if (storedRsc) {
+				storedRsc.body?.cancel().catch(() => {});
 				return publicResponse(stored, "HIT", props);
 			}
-			await Promise.all([stored.body?.cancel(), storedRsc.body?.cancel()]);
+			stored.body?.cancel().catch(() => {});
 		}
 		const capture = rscSeed ? { captureRscData: true } : isWarmup ? {} : { streamResponse: true };
-		const rendered = await invokeResponseStage(stageRequest, props, env, ctx, "shared", capture);
+		const serializedInvocation = JSON.stringify(invocation);
+		const rendered = await invokeResponseStage(stageRequest, props, env, ctx, "shared", capture, {
+			replayable: isReplayableInvocation(stageRequest, props),
+			serialized: options.cacheIdentity ? serializeInvocation(stageRequest, props) : serializedInvocation
+		});
 		if (capture.admittedResponse) {
 			ctx.waitUntil(capture.admittedResponse.then(async (admitted) => {
 				if (!isCacheable(admitted)) {
 					await admitted.body?.cancel().catch(() => {});
 					return;
 				}
-				await responseStore.put(key, admitted, {
+				await responseStore.put(key, withoutRequestScopedHeaders(admitted, props), {
 					coalesce: true,
 					revalidator: {
 						id: ROUTE_REVALIDATOR_ID,
-						args: [invocation]
+						args: [serializedInvocation]
 					}
 				});
 			}).catch((error) => {
@@ -225,25 +271,36 @@ const handler = { async fetch(request, env, ctx) {
 			throw new Error("Vinext response-store warmup did not capture the App page RSC payload");
 		}
 		const [foreground, cacheBody] = rendered.body ? rendered.body.tee() : [null, null];
-		const cacheResponse = new Response(cacheBody, rendered);
-		await responseStore.put(key, cacheResponse, {
-			coalesce: true,
-			revalidator: {
-				id: ROUTE_REVALIDATOR_ID,
-				args: [invocation]
-			}
-		});
-		if (rscSeed && rscKey && capture?.rscData) {
+		const cacheResponse = withoutRequestScopedHeaders(new Response(cacheBody, rendered), props);
+		try {
+			await responseStore.put(key, cacheResponse, {
+				coalesce: true,
+				revalidator: {
+					id: ROUTE_REVALIDATOR_ID,
+					args: [serializedInvocation]
+				}
+			});
+		} catch (error) {
+			if (isWarmup) throw error;
+			cacheResponse.body?.cancel().catch(() => {});
+			console.error(JSON.stringify({
+				message: "Vinext response-store response fill failed; serving the rendered response",
+				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);
+			rscHeaders.set("Vary", VINEXT_RSC_VARY_HEADER$1);
 			applyRscCompatibilityIdHeader(rscHeaders);
 			applyRscDeploymentIdHeader(rscHeaders);
-			const rscInvocation = serializeInvocation(rscSeed.request, rscSeed.props);
+			const serializedRscInvocation = JSON.stringify(rscInvocation);
 			await responseStore.put(rscKey, new Response(rscData, {
 				headers: rscHeaders,
 				status: 200
@@ -251,7 +308,7 @@ const handler = { async fetch(request, env, ctx) {
 				coalesce: true,
 				revalidator: {
 					id: ROUTE_REVALIDATOR_ID,
-					args: [rscInvocation]
+					args: [serializedRscInvocation]
 				}
 			});
 		}

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

@@ -6,6 +6,7 @@ var ResponseStoreCdnCacheAdapter = class {
 	headers;
 	ownsBackgroundRevalidation = false;
 	requiresCompletedResponseAdmission = true;
+	responseStageCacheIdentity = "query-free";
 	responsePolicy;
 	constructor(headers) {
 		this.headers = headers;

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

@@ -192,39 +192,61 @@ var WorkersResponseStoreCacheHandler = class {
 	async get(key, context) {
 		if (regenerationStorage.getStore()?.targetKey === key) return null;
 		const request = await cacheRequest(key);
-		const response = await this.store.fetch(request);
-		if (response.status === 404 && response.headers.get("X-Workers-Response-Store") === "MISS") return null;
-		if (!response.ok) throw new Error(`Workers Response Store returned ${response.status}`);
-		const entry = deserialize(await response.text());
-		if (!entry) {
-			await this.store.purge({ pathPrefixes: [new URL(request.url).pathname] });
-			return null;
-		}
-		const softTags = [...new Set(readStringArrayField(context, "softTags").map(encodeCloudflareCacheTag))].sort();
-		if (softTags.length) {
-			const key = softTags.join(",");
-			const expirations = this.tagExpirations();
-			let expiration = expirations.get(key);
-			if (!expiration) {
-				expiration = this.store.getTagExpiration(softTags);
-				expirations.set(key, expiration);
+		try {
+			const response = await this.store.fetch(request);
+			if (!response.ok) {
+				response.body?.cancel().catch(() => {});
+				if (response.status === 404 && response.headers.get("X-Workers-Response-Store") === "MISS") return null;
+				throw new Error(`Workers Response Store returned ${response.status}`);
 			}
-			if (await expiration >= entry.lastModified) return null;
+			const softTags = [...new Set(readStringArrayField(context, "softTags").map(encodeCloudflareCacheTag))].sort();
+			const getTagExpiration = () => {
+				const key = softTags.join(",");
+				const expirations = this.tagExpirations();
+				let expiration = expirations.get(key);
+				if (!expiration) {
+					expiration = Promise.resolve().then(() => this.store.getTagExpiration(softTags));
+					expirations.set(key, expiration);
+					expiration.catch(() => {
+						if (expirations.get(key) === expiration) expirations.delete(key);
+					});
+				}
+				return expiration;
+			};
+			const storeStatus = response.headers.get("X-Workers-Response-Store");
+			const body = response.text();
+			const eagerExpiration = softTags.length && (storeStatus === "BLOB-FRESH" || storeStatus === "BLOB-STALE") ? getTagExpiration().then((value) => ({ value }), (error) => ({ error })) : void 0;
+			const entry = deserialize(await body);
+			if (!entry) {
+				await this.store.purge({ pathPrefixes: [new URL(request.url).pathname] });
+				return null;
+			}
+			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;
+			}
+			const age = Date.now() - entry.lastModified;
+			const requestedRevalidate = readCacheControlField(context, "revalidate");
+			const requestedStale = typeof requestedRevalidate === "number" && requestedRevalidate > 0 && age > requestedRevalidate * 1e3;
+			let cacheState;
+			if (response.headers.get(REPLAYABLE_HEADER) === "1") {
+				if (requestedStale) cacheState = "stale";
+			} else if (typeof entry.cacheControl?.expire === "number" && age > entry.cacheControl.expire * 1e3) cacheState = "expired";
+			else if (requestedStale || typeof entry.cacheControl?.revalidate === "number" && entry.cacheControl.revalidate > 0 && age > entry.cacheControl.revalidate * 1e3) cacheState = "stale";
+			return {
+				lastModified: entry.lastModified,
+				value: entry.value,
+				...cacheState ? { cacheState } : {},
+				...entry.cacheControl ? { cacheControl: entry.cacheControl } : {}
+			};
+		} catch (error) {
+			console.error(JSON.stringify({
+				message: "Vinext response-store data lookup failed; treating as a cache miss",
+				error: error instanceof Error ? error.message : String(error)
+			}));
+			return null;
 		}
-		const age = Date.now() - entry.lastModified;
-		const requestedRevalidate = readCacheControlField(context, "revalidate");
-		const requestedStale = typeof requestedRevalidate === "number" && requestedRevalidate > 0 && age > requestedRevalidate * 1e3;
-		let cacheState;
-		if (response.headers.get(REPLAYABLE_HEADER) === "1") {
-			if (requestedStale) cacheState = "stale";
-		} else if (typeof entry.cacheControl?.expire === "number" && age > entry.cacheControl.expire * 1e3) cacheState = "expired";
-		else if (requestedStale || typeof entry.cacheControl?.revalidate === "number" && entry.cacheControl.revalidate > 0 && age > entry.cacheControl.revalidate * 1e3) cacheState = "stale";
-		return {
-			lastModified: entry.lastModified,
-			value: entry.value,
-			...cacheState ? { cacheState } : {},
-			...entry.cacheControl ? { cacheControl: entry.cacheControl } : {}
-		};
 	}
 	async set(key, value, context) {
 		let revalidate = readCacheControlField(context, "revalidate");

package/dist/cache/static-assets-adapter.build.d.ts

@@ -0,0 +1,6 @@
+//#region src/cache/static-assets-adapter.build.d.ts
+/** Package App Router prerender output as immutable Workers Static Assets. */
+export declare function finalizeStaticAssetsPrerenderOutput(root: string, options?: {
+  clientOutDir?: string;
+}): number;
+//#endregion

package/dist/cache/static-assets-adapter.build.js

@@ -0,0 +1,65 @@
+import { STATIC_ASSET_CACHE_PATH } from "./static-assets-adapter.shared.js";
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { readPrerenderManifest } from "vinext/internal/server/prerender-manifest";
+import { appIsrCacheKey } from "vinext/internal/server/isr-cache";
+import { normalizePregeneratedPathname } from "vinext/internal/server/pregenerated-concrete-paths";
+import { getAppRouteOutputPath, getOutputPath, getRscOutputPath } from "vinext/internal/utils/prerender-output-paths";
+//#region src/cache/static-assets-adapter.build.ts
+function cacheAssetId(key) {
+	return createHash("sha256").update(key).digest("hex");
+}
+function cacheControl(route) {
+	if (route.revalidate === void 0) return void 0;
+	return {
+		revalidate: route.revalidate,
+		...route.expire === void 0 ? {} : { expire: route.expire },
+		...route.stale === void 0 ? {} : { stale: route.stale }
+	};
+}
+function writeCacheAsset(outputDir, index, key, kind, sourcePath, route) {
+	if (!fs.existsSync(sourcePath)) return false;
+	const id = cacheAssetId(key);
+	const extension = kind === "html" ? "html" : kind === "rsc" ? "rsc" : "route";
+	const policy = cacheControl(route);
+	const metadata = {
+		kind,
+		lastModified: fs.statSync(sourcePath).mtimeMs,
+		...policy ? { cacheControl: policy } : {},
+		...kind !== "rsc" && route.headers ? { headers: route.headers } : {},
+		...kind !== "rsc" && route.responseStatus !== void 0 ? { status: route.responseStatus } : {}
+	};
+	fs.mkdirSync(outputDir, { recursive: true });
+	fs.copyFileSync(sourcePath, path.join(outputDir, `${id}.${extension}`));
+	index[id] = metadata;
+	return true;
+}
+/** Package App Router prerender output as immutable Workers Static Assets. */
+function finalizeStaticAssetsPrerenderOutput(root, options = {}) {
+	const serverDir = path.join(root, "dist", "server");
+	const prerenderDir = path.join(serverDir, "prerendered-routes");
+	const outputDir = path.join(options.clientOutDir ?? path.join(root, "dist", "client"), STATIC_ASSET_CACHE_PATH.replace(/^\//, ""));
+	fs.rmSync(outputDir, {
+		recursive: true,
+		force: true
+	});
+	const manifest = readPrerenderManifest(path.join(serverDir, "vinext-prerender.json"));
+	if (!manifest?.buildId || !manifest.routes || !fs.existsSync(prerenderDir)) return 0;
+	const index = {};
+	let count = 0;
+	for (const route of manifest.routes) {
+		if (route.status !== "rendered") continue;
+		if (typeof route.revalidate === "number" && route.revalidate <= 0) continue;
+		const pathname = route.path ?? route.route;
+		const cachePathname = normalizePregeneratedPathname(pathname);
+		if (route.router === "app") {
+			count += Number(writeCacheAsset(outputDir, index, appIsrCacheKey(cachePathname, "html", manifest.buildId), "html", path.join(prerenderDir, getOutputPath(pathname, manifest.trailingSlash ?? false)), route));
+			count += Number(writeCacheAsset(outputDir, index, appIsrCacheKey(cachePathname, "rsc", manifest.buildId), "rsc", path.join(prerenderDir, getRscOutputPath(pathname)), route));
+		} else if (route.router === "metadata") count += Number(writeCacheAsset(outputDir, index, appIsrCacheKey(cachePathname, "route", manifest.buildId), "route", path.join(prerenderDir, getAppRouteOutputPath(pathname)), route));
+	}
+	if (count > 0) fs.writeFileSync(path.join(outputDir, "index.json"), JSON.stringify(index));
+	return count;
+}
+//#endregion
+export { finalizeStaticAssetsPrerenderOutput };

package/dist/cache/static-assets-adapter.d.ts

@@ -0,0 +1,27 @@
+//#region src/cache/static-assets-adapter.d.ts
+export type StaticAssetsAdapterOptions = {
+  /** Workers Static Assets binding name. @default "ASSETS" */
+  binding?: string;
+};
+/**
+ * Read-only page cache backed by Workers Static Assets.
+ *
+ * Locally prerendered App Router HTML, RSC, and metadata responses are copied
+ * into `dist/client` after the build. Runtime cache writes and invalidations are
+ * intentionally no-ops; a new deployment replaces the cache contents.
+ */
+export declare function staticAssetsAdapter(options?: StaticAssetsAdapterOptions): {
+  adapter: string;
+  options: StaticAssetsAdapterOptions | undefined;
+  output: {
+    finalizePrerenderOutput({ root, clientOutDir }: {
+      root: string;
+      clientOutDir: string;
+    }): void;
+  };
+  capabilities: {
+    buildIdentity: "response-header";
+    warmup: "data-cache";
+  };
+};
+//#endregion

package/dist/cache/static-assets-adapter.js

@@ -0,0 +1,26 @@
+import { finalizeStaticAssetsPrerenderOutput } from "./static-assets-adapter.build.js";
+import { fileURLToPath } from "node:url";
+//#region src/cache/static-assets-adapter.ts
+/**
+* Read-only page cache backed by Workers Static Assets.
+*
+* Locally prerendered App Router HTML, RSC, and metadata responses are copied
+* into `dist/client` after the build. Runtime cache writes and invalidations are
+* intentionally no-ops; a new deployment replaces the cache contents.
+*/
+function staticAssetsAdapter(options) {
+	if (options?.binding !== void 0 && (typeof options.binding !== "string" || options.binding.length === 0)) throw new TypeError("[vinext] staticAssetsAdapter({ binding }) must be a non-empty string binding name.");
+	return {
+		adapter: fileURLToPath(import.meta.resolve("./static-assets-adapter.runtime.js")),
+		options,
+		output: { finalizePrerenderOutput({ root, clientOutDir }) {
+			finalizeStaticAssetsPrerenderOutput(root, { clientOutDir });
+		} },
+		capabilities: {
+			buildIdentity: "response-header",
+			warmup: "data-cache"
+		}
+	};
+}
+//#endregion
+export { staticAssetsAdapter };

package/dist/cache/static-assets-adapter.runtime.d.ts

@@ -0,0 +1,26 @@
+import { StaticAssetsAdapterOptions } from "./static-assets-adapter.js";
+import { CdnCacheAdapter, CdnCacheableHeaderInput, CdnResponseHeaders } from "vinext/shims/cdn-cache";
+import { CacheHandlerValue, IncrementalCacheValue } from "vinext/shims/cache-handler";
+//#region src/cache/static-assets-adapter.runtime.d.ts
+type AssetFetcher = {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+};
+export declare class StaticAssetsCacheAdapter implements CdnCacheAdapter {
+  private readonly assets;
+  readonly ownsBackgroundRevalidation = false;
+  private indexPromise;
+  constructor(assets: AssetFetcher);
+  private loadIndex;
+  get(key: string): Promise<CacheHandlerValue | null>;
+  set(_key: string, _data: IncrementalCacheValue | null, _ctx?: Record<string, unknown>): Promise<void>;
+  buildResponseHeaders(input: CdnCacheableHeaderInput): CdnResponseHeaders;
+  buildResponseIdentityHeaders(): CdnResponseHeaders;
+  revalidateTag(_tags: string | string[], _durations?: {
+    expire?: number;
+  }): Promise<void>;
+}
+export default function createStaticAssetsCacheAdapter({ env, options }?: {
+  env?: Record<string, unknown>;
+  options?: StaticAssetsAdapterOptions;
+}): CdnCacheAdapter;
+//#endregion

package/dist/cache/static-assets-adapter.runtime.js

@@ -0,0 +1,77 @@
+import { STATIC_ASSET_CACHE_PATH } from "./static-assets-adapter.shared.js";
+import { DefaultCdnCacheAdapter } from "vinext/shims/cdn-cache";
+//#region src/cache/static-assets-adapter.runtime.ts
+async function cacheAssetId(key) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(key));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function isMetadata(value) {
+	return value !== null && typeof value === "object" && "kind" in value && (value.kind === "html" || value.kind === "rsc" || value.kind === "route") && "lastModified" in value && typeof value.lastModified === "number";
+}
+var StaticAssetsCacheAdapter = class {
+	assets;
+	ownsBackgroundRevalidation = false;
+	indexPromise;
+	constructor(assets) {
+		this.assets = assets;
+	}
+	loadIndex() {
+		return this.indexPromise ??= this.assets.fetch(`https://vinext.invalid${STATIC_ASSET_CACHE_PATH}/index.json`).then(async (response) => response.ok ? await response.json() : null).then((value) => value !== null && typeof value === "object" ? value : null);
+	}
+	async get(key) {
+		const id = await cacheAssetId(key);
+		const metadata = (await this.loadIndex())?.[id];
+		if (!isMetadata(metadata)) return null;
+		const extension = metadata.kind === "html" ? "html" : metadata.kind === "rsc" ? "rsc" : "route";
+		const bodyResponse = await this.assets.fetch(`https://vinext.invalid${STATIC_ASSET_CACHE_PATH}/${id}.${extension}`);
+		if (!bodyResponse.ok) return null;
+		let value;
+		if (metadata.kind === "html") value = {
+			kind: "APP_PAGE",
+			html: await bodyResponse.text(),
+			rscData: void 0,
+			headers: metadata.headers,
+			postponed: void 0,
+			prerendered: true,
+			status: metadata.status
+		};
+		else if (metadata.kind === "rsc") value = {
+			kind: "APP_PAGE",
+			html: "",
+			rscData: await bodyResponse.arrayBuffer(),
+			headers: void 0,
+			postponed: void 0,
+			prerendered: true,
+			status: void 0
+		};
+		else value = {
+			kind: "APP_ROUTE",
+			body: await bodyResponse.arrayBuffer(),
+			headers: metadata.headers ?? {},
+			status: metadata.status ?? 200
+		};
+		return {
+			lastModified: metadata.lastModified,
+			...metadata.cacheControl ? { cacheControl: metadata.cacheControl } : {},
+			value
+		};
+	}
+	async set(_key, _data, _ctx) {}
+	buildResponseHeaders(input) {
+		return { "Cache-Control": input.pendingDynamicCheck ? "no-store, must-revalidate" : input.cacheControl };
+	}
+	buildResponseIdentityHeaders() {
+		const buildId = process.env.__VINEXT_RSC_BUILD_IDENTITY || process.env.__VINEXT_BUILD_ID;
+		return buildId ? { "X-Vinext-Build-Id": buildId } : {};
+	}
+	async revalidateTag(_tags, _durations) {}
+};
+function createStaticAssetsCacheAdapter({ env, options } = {}) {
+	if (process.env.VINEXT_PRERENDER === "1") return new DefaultCdnCacheAdapter(process.env.__VINEXT_RSC_BUILD_IDENTITY || process.env.__VINEXT_BUILD_ID);
+	const binding = options?.binding ?? "ASSETS";
+	const assets = env?.[binding];
+	if (!assets || typeof assets !== "object" || !("fetch" in assets) || typeof assets.fetch !== "function") throw new Error(`[vinext] Static Assets binding \`${binding}\` is not configured.`);
+	return new StaticAssetsCacheAdapter(assets);
+}
+//#endregion
+export { StaticAssetsCacheAdapter, createStaticAssetsCacheAdapter as default };

package/dist/cache/static-assets-adapter.shared.d.ts

@@ -0,0 +1,12 @@
+import { CacheControlMetadata } from "vinext/shims/cache-handler";
+//#region src/cache/static-assets-adapter.shared.d.ts
+export declare const STATIC_ASSET_CACHE_PATH = "/_vinext/static-cache";
+export type StaticAssetCacheMetadata = {
+  kind: "html" | "rsc" | "route";
+  lastModified: number;
+  cacheControl?: CacheControlMetadata;
+  headers?: Record<string, string | string[]>;
+  status?: number;
+};
+export type StaticAssetCacheIndex = Record<string, StaticAssetCacheMetadata>;
+//#endregion

package/dist/cache/static-assets-adapter.shared.js

@@ -0,0 +1,4 @@
+//#region src/cache/static-assets-adapter.shared.ts
+const STATIC_ASSET_CACHE_PATH = "/_vinext/static-cache";
+//#endregion
+export { STATIC_ASSET_CACHE_PATH };