@vinext/cloudflare 1.0.0-beta.9 → 1.0.1

package/README.md

@@ -8,7 +8,7 @@ This package provides Cloudflare-specific cache and image backends for vinext:
 - **`kvDataAdapter()`** (`@vinext/cloudflare/cache/kv-data-adapter`) — backs the
   data cache (`fetch`, `"use cache"`, `unstable_cache`) with a Workers KV
   namespace.
-- **`cdnAdapter()`** (`@vinext/cloudflare/cache/cdn-adapter`) — delegates
+- **`workersCacheCdnAdapter()`** (`@vinext/cloudflare/cache/workers-cache-cdn-adapter`) — delegates
   page-level ISR serving and revalidation to Cloudflare Workers Cache through
   an automatically generated cache-enabled response entrypoint.
 - **`responseStoreAdapter()`** (`@vinext/cloudflare/cache/response-store-adapter`) —
@@ -19,78 +19,156 @@ This package provides Cloudflare-specific cache and image backends for vinext:
 
 ## Usage
 
-Declare the adapters on the `vinext()` plugin in your Vite config:
+These snippets extend the config generated by `vinext init`. Declare adapters on
+the existing `vinext()` plugin in your Vite config:
 
 ```ts
 import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";
 import { imagesOptimizer } from "@vinext/cloudflare/images/images-optimizer";
 
-export default defineConfig({
-  plugins: [
-    vinext({
-      cache: {
-        data: kvDataAdapter(), // KV-backed data cache (binding: VINEXT_KV_CACHE)
-      },
-      images: { optimizer: imagesOptimizer() }, // Cloudflare Images binding: IMAGES
-    }),
-    cloudflare(),
-  ],
+vinext({
+  cache: { data: kvDataAdapter() },
+  images: { optimizer: imagesOptimizer() },
 });
 ```
 
+Add the bindings to your Worker's `env` in `cloudflare.config.ts`:
+
+```ts
+import { bindings } from "cf/config";
+
+env: {
+  // ...existing bindings
+  VINEXT_KV_CACHE: bindings.kv(),
+  IMAGES: bindings.images(),
+},
+```
+
 ### Workers Cache
 
-`cdnAdapter()` is optional. Configuring it asks the Cloudflare build for two
+`workersCacheCdnAdapter()` is optional. Configuring it asks the Cloudflare build for two
 Worker entrypoints: the default entrypoint runs middleware and request-time
 routing with caching disabled, while `VinextCachedResponse` lazily loads the
-render stage with Workers Cache enabled. These settings are written to the
-generated `dist/server/wrangler.json`; do not enable Workers Cache on the
-default entrypoint in your source config. The generated config also declares
-the version metadata binding used for staged warmup.
+render stage with Workers Cache enabled.
 
 ```ts
-import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
+import { workersCacheCdnAdapter } from "@vinext/cloudflare/cache/workers-cache-cdn-adapter";
 
-vinext({ cache: { cdn: cdnAdapter() } });
+vinext({ cache: { cdn: workersCacheCdnAdapter() } });
+```
+
+Cloudflare Vite plugin v2 uses Build Output and treats `cloudflare.config.ts`
+as the deployment source of truth. Declare the equivalent policies there.
+In these snippets, `existingExports` is your current Worker's `exports` object,
+or `{}` if it has none:
+
+```ts
+import { createWorkersCacheConfig } from "@vinext/cloudflare/cache/config";
+
+const workersCache = await createWorkersCacheConfig();
+
+defineWorker({
+  // ...existing Worker settings
+  ...workersCache,
+  env: { /* existing bindings, */ ...workersCache.env },
+  exports: { ...existingExports, ...workersCache.exports },
+});
 ```
 
 The generated version metadata binding lets staged warmup prove that every
 discovery, probe, and fill request reached the uploaded Worker version. Pass
-`versionMetadataBinding` to `cdnAdapter()` only when the deployment needs a
-custom binding name.
+the same `versionMetadataBinding` to `workersCacheCdnAdapter()` and
+`createWorkersCacheConfig()` only when the deployment needs a custom binding
+name.
 
-Use `--experimental-warm-cdn-cache` for the two-stage deploy. The default flow
-makes one final fill request per admitted identity. Add `--warm-cdn-certify`
+Use `--warm-cache` for the two-stage deploy. The default flow
+makes one final fill request per admitted identity. Add `--warm-cache-certify`
 only when you want an opt-in second, header-only request that must prove every
 planned entry reusable before promotion.
 
 The response entrypoint hashes the complete transport identity into its
-Workers Cache URL, independently of zone Cache Rules, so distinct query and
-representation variants cannot collide.
+Workers Cache URL, independently of zone Cache Rules, so distinct
+representation, rewrite and interception variants cannot collide. For App
+Router pages that the cacheability manifest of a staged
+`--warm-cache` deploy marks `static-candidate`, the identity
+leaves out the query string, so every query of the page shares one entry, as in
+Next.js. Other requests, and responses that a `next.config` `headers()` rule
+makes cacheable, keep the query in their identity. See
+[the caching guide](https://vinext.dev/docs/guides/caching#query-strings).
 
 ### Workers Response Store
 
-`responseStoreAdapter()` replaces both `cdnAdapter()` and `kvDataAdapter()`.
+`responseStoreAdapter()` replaces both `workersCacheCdnAdapter()` and `kvDataAdapter()`.
 It defaults to a separate cache Worker reached through the `RESPONSE_STORE`
-service binding. `vinext init` writes two collocated source configs:
-`wrangler.jsonc` for the application and `wrangler.response-store.jsonc` for the
-cache Worker. The latter points directly at the installed
-`@cloudflare/workers-response-store` implementation and owns its R2 bucket,
-SQLite Durable Object, Worker name, and cache settings. Edit those configs to
-choose or reuse names, keeping the application service binding aligned with the
-cache Worker name.
+service binding. `vinext init` defines both Workers in `cloudflare.config.ts`.
+The service-binding helper points directly at the installed
+`@cloudflare/workers-response-store` implementation and configures its R2 binding,
+SQLite Durable Object, Worker name, and cache settings, along with the application's
+service binding and version metadata.
 
 The two Workers are deliberately deployed separately. Deploy the Response Store
 when its package or config changes, then deploy the application normally:
 
 ```sh
-npx wrangler deploy --config wrangler.response-store.jsonc
+pnpm run build:vinext
+pnpm run deploy:response-store
 npx @vinext/cloudflare deploy
 ```
 
 `vinext-cloudflare deploy` never creates, rewrites, or deploys the Response
 Store Worker.
 
+`cf deploy` creates the named R2 bucket if it does not already exist. `create-vinext-app`
+uses `build` instead of `build:vinext`. The source config uses the shared helper:
+
+```ts
+import { createWorkersResponseStoreServiceBindingConfig } from "@vinext/cloudflare/cache/config";
+
+const responseStore = await createWorkersResponseStoreServiceBindingConfig({
+  worker: {
+    name: "example-response-store",
+    compatibilityDate: "2026-09-15",
+    compatibilityFlags: ["nodejs_compat"],
+  },
+  bucket: "example-response-store-cache-bodies",
+});
+
+export const responseStoreServiceBinding = responseStore.serviceBindingWorker;
+```
+
+Merge the helper's application settings into your existing Worker:
+
+```ts
+defineWorker({
+  // ...existing Worker settings
+  ...responseStore.applicationWorker,
+  env: {
+    // ...existing bindings
+    ...responseStore.applicationWorker.env,
+  },
+});
+```
+
+`worker.observability` accepts the full observability configuration supported by
+your installed `cf` package, including logs and traces settings.
+The optional `accountId` is returned as `responseStore.accountId`: pass it to `defineConfig`,
+not to either Worker. It applies to both Workers in the project.
+
+The async config helpers import bindings and exports from your installed
+`cf/config`. The `cf` package is an optional peer dependency of `@vinext/cloudflare`;
+install it when using these helpers.
+
+Add the exported auxiliary Worker to your existing Cloudflare Vite plugin options:
+
+```ts
+import { responseStoreServiceBinding } from "./cloudflare.config";
+
+cloudflare({
+  // ...existing plugin options
+  auxiliaryWorkers: [{ config: responseStoreServiceBinding }],
+});
+```
+
 Metadata sharding is opt-in and works in either deployment mode:
 
 ```ts
@@ -100,6 +178,18 @@ vinext({ cache: responseStoreAdapter({ shards: 16 }) });
 Keys remain pinned to one shard while tag/path mutations fan out across every
 shard. Omit `shards` to retain the original single metadata Durable Object.
 
+To place newly created metadata Durable Objects near a stable traffic and R2
+region, pass a Cloudflare location hint:
+
+```ts
+vinext({ cache: responseStoreAdapter({ locationHint: "weur" }) });
+```
+
+The hint works in both deployment modes, is best-effort, and only affects each
+Durable Object's first creation. Changing it does not relocate existing
+objects; treat the change as a cache-cold deployment and align it with the R2
+bucket's location.
+
 To deploy storage and cache entrypoints with the application instead, select
 self-contained mode:
 
@@ -109,9 +199,27 @@ import { responseStoreAdapter } from "@vinext/cloudflare/cache/response-store-ad
 vinext({ cache: responseStoreAdapter({ mode: "self-contained" }) });
 ```
 
-In this mode `vinext init` places the required R2, SQLite Durable Object,
-Workers Cache entrypoint, and version-metadata configuration in
-`wrangler.jsonc`; no second Wrangler config is required.
+Use the matching helper in `cloudflare.config.ts`:
+
+```ts
+import { createWorkersResponseStoreSelfContainedConfig } from "@vinext/cloudflare/cache/config";
+
+const cache = await createWorkersResponseStoreSelfContainedConfig({
+  worker: "example",
+  bucket: "example-response-store-cache-bodies",
+});
+
+defineWorker({
+  // ...existing Worker settings
+  ...cache,
+  env: { /* existing bindings, */ ...cache.env },
+  exports: { ...existingExports, ...cache.exports },
+});
+```
+
+The adapter generates the required exports during the build. This config declares
+the R2 and SQLite Durable Object bindings, Workers Cache entrypoint, and version
+metadata on the application Worker; no auxiliary Worker or separate deployment is needed.
 
 ## Deploy
 
@@ -121,5 +229,25 @@ Deploy Cloudflare Workers projects with the package CLI:
 npx @vinext/cloudflare deploy
 ```
 
+Cloudflare init and create-vinext-app use `cloudflare.config.ts`, Cloudflare Vite
+plugin v2, and `cf` by default. The deploy command builds and deploys the generated
+Cloudflare Build Output. Source config remains authoritative for bindings and
+cache policies.
+
+`vinext-cloudflare deploy` only deploys the entry Worker. It never deploys named
+auxiliary Workers, including during staged warming or `--no-promote` uploads.
+Deploy a configured Response Store Worker explicitly after building, when first
+setting it up or when its code/config changes:
+
+```sh
+cf deploy --prebuilt --mode production --worker example-response-store
+```
+
+Use the mode and Worker name from your build. `cloudflare.config.ts` remains the
+source of truth.
+
+Staged cache warming uses `cf` to upload a version, read deployment
+status, stage and promote traffic, and apply triggers.
+
 With Vite+, use `vpx @vinext/cloudflare deploy`, or
 `vp exec vinext-cloudflare deploy` when running the locally installed bin.

package/dist/cache/browser-cache-policy.d.ts

@@ -0,0 +1,7 @@
+//#region src/cache/browser-cache-policy.d.ts
+export type SharedResponseStage = {
+  headers: Headers;
+};
+export declare const SHARED_RESPONSE_STAGE_HEADER = "x-vinext-cloudflare-shared-response-stage";
+export declare function finalizeGatewayResponse(response: Response, sharedResponses: Map<string, SharedResponseStage>, cacheStatusHeader?: string): Response;
+//#endregion

package/dist/cache/browser-cache-policy.js

@@ -0,0 +1,39 @@
+import { NEXTJS_CACHE_HEADER, VINEXT_CACHE_HEADER } from "vinext/internal/server/headers";
+//#region src/cache/browser-cache-policy.ts
+const CLOUDFLARE_EDGE_POLICY_HEADER = "Cloudflare-CDN-Cache-Control";
+const SHARED_RESPONSE_STAGE_HEADER = "x-vinext-cloudflare-shared-response-stage";
+const PRIVATE_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
+	SHARED_RESPONSE_STAGE_HEADER,
+	CLOUDFLARE_EDGE_POLICY_HEADER.toLowerCase(),
+	"cdn-cache-control",
+	"cache-tag",
+	VINEXT_CACHE_HEADER.toLowerCase(),
+	NEXTJS_CACHE_HEADER.toLowerCase()
+]);
+function finalizeGatewayResponse(response, sharedResponses, cacheStatusHeader = "CF-Cache-Status") {
+	const provenance = response.headers.get(SHARED_RESPONSE_STAGE_HEADER);
+	const sharedResponse = provenance === null ? void 0 : sharedResponses.get(provenance);
+	const usedSharedResponseStage = sharedResponse !== void 0;
+	const sharedResponseStageCollision = provenance !== null && !usedSharedResponseStage;
+	if (!response.headers.has(CLOUDFLARE_EDGE_POLICY_HEADER) && !usedSharedResponseStage && !sharedResponseStageCollision) return response;
+	const headers = new Headers(response.headers);
+	headers.delete(SHARED_RESPONSE_STAGE_HEADER);
+	headers.delete(CLOUDFLARE_EDGE_POLICY_HEADER);
+	if (usedSharedResponseStage || sharedResponseStageCollision) {
+		for (const name of PRIVATE_RESPONSE_HEADERS) headers.delete(name);
+		if (sharedResponseStageCollision) headers.set("Cache-Control", "no-store");
+		else if (!headers.has("Cache-Control")) headers.set("Cache-Control", "private, max-age=0, must-revalidate");
+	}
+	const cacheStatus = sharedResponse?.headers.get(cacheStatusHeader);
+	if (cacheStatus) {
+		headers.set(VINEXT_CACHE_HEADER, cacheStatus);
+		headers.set(NEXTJS_CACHE_HEADER, cacheStatus);
+	}
+	return new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+}
+//#endregion
+export { SHARED_RESPONSE_STAGE_HEADER, finalizeGatewayResponse };

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

@@ -21,7 +21,8 @@ export declare function configureCdnVersionMetadata(config: WranglerOutputConfig
 /** Add the per-entrypoint Workers Cache policy to an emitted Wrangler config. */
 export declare function configureWorkersCacheEntrypoints(config: WranglerOutputConfig): WranglerOutputConfig;
 /** Apply the complete CDN adapter policy to the primary generated config. */
-export declare function finalizeCdnAdapterBuildOutput({ outDir, isPrimaryServerOutput, binding, bindingIsExplicit }: {
+export declare function finalizeCdnAdapterBuildOutput({ root, outDir, isPrimaryServerOutput, binding, bindingIsExplicit }: {
+  root: string;
   outDir: string;
   isPrimaryServerOutput: boolean;
   binding: string;

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

@@ -16,7 +16,7 @@ function configureCdnVersionMetadata(config, options) {
 	const existingBinding = config.version_metadata.binding;
 	if (typeof existingBinding !== "string" || existingBinding.length === 0) throw new Error("[vinext] The generated Wrangler config has an invalid version_metadata.binding value.");
 	if (existingBinding === options.binding) return config;
-	if (!options.bindingIsExplicit) throw new Error(`[vinext] cdnAdapter() uses the default version metadata binding ${JSON.stringify(options.binding)}, but the generated Wrangler config already declares ${JSON.stringify(existingBinding)}. Align the Wrangler binding or configure cdnAdapter({ versionMetadataBinding: ${JSON.stringify(existingBinding)} }).`);
+	if (!options.bindingIsExplicit) throw new Error(`[vinext] workersCacheCdnAdapter() uses the default version metadata binding ${JSON.stringify(options.binding)}, but the generated Wrangler config already declares ${JSON.stringify(existingBinding)}. Align the Wrangler binding or configure workersCacheCdnAdapter({ versionMetadataBinding: ${JSON.stringify(existingBinding)} }).`);
 	return {
 		...config,
 		version_metadata: { binding: options.binding }
@@ -26,7 +26,7 @@ function configureCdnVersionMetadata(config, options) {
 function configureWorkersCacheEntrypoints(config) {
 	const configuredExports = config.exports ?? {};
 	const compatibilityFlags = config.compatibility_flags ?? [];
-	if (compatibilityFlags.includes("disable_ctx_exports")) throw new Error("[vinext] cdnAdapter() requires ctx.exports, but the generated Wrangler config explicitly disables it with disable_ctx_exports.");
+	if (compatibilityFlags.includes("disable_ctx_exports")) throw new Error("[vinext] workersCacheCdnAdapter() requires ctx.exports, but the generated Wrangler config explicitly disables it with disable_ctx_exports.");
 	const configuredCompatibilityFlags = config.compatibility_date === void 0 || config.compatibility_date < CTX_EXPORTS_DEFAULT_DATE ? compatibilityFlags.includes("enable_ctx_exports") ? compatibilityFlags : [...compatibilityFlags, "enable_ctx_exports"] : compatibilityFlags.filter((flag) => flag !== "enable_ctx_exports");
 	for (const name of [
 		"default",
@@ -34,7 +34,7 @@ function configureWorkersCacheEntrypoints(config) {
 		UNCACHED_RESPONSE_STAGE_EXPORT
 	]) {
 		const existing = configuredExports[name];
-		if (existing?.type !== void 0 && existing.type !== "worker") throw new Error(`[vinext] cdnAdapter() cannot configure the reserved Worker export ${JSON.stringify(name)} because it is already declared as ${JSON.stringify(existing.type)}.`);
+		if (existing?.type !== void 0 && existing.type !== "worker") throw new Error(`[vinext] workersCacheCdnAdapter() cannot configure the reserved Worker export ${JSON.stringify(name)} because it is already declared as ${JSON.stringify(existing.type)}.`);
 	}
 	return {
 		...config,
@@ -72,11 +72,19 @@ async function readGeneratedConfig(generatedConfigPath, allowMissing) {
 async function writeGeneratedConfig(generatedConfigPath, config) {
 	await fs.writeFile(generatedConfigPath, `${JSON.stringify(config, null, 2)}\n`);
 }
+async function usesCloudflareBuildOutput(root) {
+	try {
+		return (await fs.stat(path.resolve(root, "cloudflare.config.ts"))).isFile();
+	} catch (cause) {
+		if (cause !== null && typeof cause === "object" && "code" in cause && cause.code === "ENOENT") return false;
+		throw cause;
+	}
+}
 /** Apply the complete CDN adapter policy to the primary generated config. */
-async function finalizeCdnAdapterBuildOutput({ outDir, isPrimaryServerOutput, binding, bindingIsExplicit }) {
+async function finalizeCdnAdapterBuildOutput({ root, outDir, isPrimaryServerOutput, binding, bindingIsExplicit }) {
 	if (!isPrimaryServerOutput) return;
 	const generatedConfigPath = path.resolve(outDir, "wrangler.json");
-	const generatedConfig = await readGeneratedConfig(generatedConfigPath, false);
+	const generatedConfig = await readGeneratedConfig(generatedConfigPath, await usesCloudflareBuildOutput(root));
 	if (!generatedConfig) return;
 	await writeGeneratedConfig(generatedConfigPath, configureWorkersCacheEntrypoints(configureCdnVersionMetadata(generatedConfig, {
 		binding,

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

@@ -1,57 +1,6 @@
+import { CdnAdapterOptions, DEFAULT_CDN_VERSION_METADATA_BINDING, workersCacheCdnAdapter } from "./workers-cache-cdn-adapter.js";
 //#region src/cache/cdn-adapter.d.ts
-export declare const DEFAULT_CDN_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
-/** Options accepted by {@link cdnAdapter}, forwarded to the runtime factory. */
-export type CdnAdapterOptions = {
-  /** Version metadata binding used to verify version-overridden requests. */
-  versionMetadataBinding?: string;
-};
-/**
- * Cloudflare CDN cache adapter - edge-managed page-level ISR backed by the
- * Cloudflare Workers Cache.
- *
- * Unlike the data adapter (which stores cache entries in a durable store and
- * serves HIT/STALE itself), this adapter delegates serving to Workers Cache on
- * a named Worker entrypoint. The default entrypoint always runs middleware and
- * request-time routing before dispatching to cached or uncached response-stage
- * entrypoints.
- *
- * The emitted Wrangler configuration enables Workers Cache only for that
- * response-stage export, so cache hits do not start the application stage.
- * The generated deployment config automatically enables Workers Cache for the
- * cached response entrypoint and adds the version metadata binding used by
- * warmup. The uncached response entrypoint keeps bypass and probe renders out
- * of the gateway without enabling Workers Cache for them.
- *
- * The adapter adds a transport-only URL digest so distinct response-stage
- * identities cannot collide. Workers Cache owns this key independently of
- * zone Cache Rules.
- */
-export declare function cdnAdapter(options?: CdnAdapterOptions): {
-  adapter: string;
-  options: CdnAdapterOptions | undefined;
-  output: {
-    entry: string;
-    matchesBuild({ plugins }: {
-      plugins: readonly {
-        name?: string;
-      }[];
-    }): boolean;
-    transformHostEntry({ code, id }: {
-      code: string;
-      id: string;
-    }): string | null;
-    finalizeBuildOutput({ outDir, isPrimaryServerOutput }: {
-      outDir: string;
-      isPrimaryServerOutput: boolean;
-    }): Promise<void>;
-    type: "multi-stage";
-  };
-  capabilities: {
-    buildIdentity: "response-header";
-    isResponsePolicyHeader: (name: string) => boolean;
-    requestRouting: "uncached-stage";
-    responseVary: "verbatim";
-    routeCacheability: "probe-manifest";
-  };
-};
-//#endregion
+/** @deprecated Use {@link workersCacheCdnAdapter} from `@vinext/cloudflare/cache/workers-cache-cdn-adapter` instead. */
+export declare const cdnAdapter: typeof workersCacheCdnAdapter;
+//#endregion
+export { type CdnAdapterOptions, DEFAULT_CDN_VERSION_METADATA_BINDING };

package/dist/cache/cdn-adapter.js

@@ -1,64 +1,6 @@
-import { finalizeCdnAdapterBuildOutput } from "./cdn-adapter-config.js";
-import { fileURLToPath } from "node:url";
+import { DEFAULT_CDN_VERSION_METADATA_BINDING, workersCacheCdnAdapter } from "./workers-cache-cdn-adapter.js";
 //#region src/cache/cdn-adapter.ts
-const DEFAULT_CDN_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
-const CLOUDFLARE_WORKER_ENTRY_ID = "virtual:cloudflare/worker-entry";
-/**
-* Cloudflare CDN cache adapter - edge-managed page-level ISR backed by the
-* Cloudflare Workers Cache.
-*
-* Unlike the data adapter (which stores cache entries in a durable store and
-* serves HIT/STALE itself), this adapter delegates serving to Workers Cache on
-* a named Worker entrypoint. The default entrypoint always runs middleware and
-* request-time routing before dispatching to cached or uncached response-stage
-* entrypoints.
-*
-* The emitted Wrangler configuration enables Workers Cache only for that
-* response-stage export, so cache hits do not start the application stage.
-* The generated deployment config automatically enables Workers Cache for the
-* cached response entrypoint and adds the version metadata binding used by
-* warmup. The uncached response entrypoint keeps bypass and probe renders out
-* of the gateway without enabling Workers Cache for them.
-*
-* The adapter adds a transport-only URL digest so distinct response-stage
-* identities cannot collide. Workers Cache owns this key independently of
-* zone Cache Rules.
-*/
-function cdnAdapter(options) {
-	if (options?.versionMetadataBinding !== void 0 && (typeof options.versionMetadataBinding !== "string" || options.versionMetadataBinding.length === 0)) throw new TypeError("[vinext] cdnAdapter({ versionMetadataBinding }) must be a non-empty string binding name.");
-	const versionMetadataBinding = options?.versionMetadataBinding ?? "CF_VERSION_METADATA";
-	const bindingIsExplicit = options?.versionMetadataBinding !== void 0;
-	const workerEntry = fileURLToPath(import.meta.resolve("./cdn-adapter.worker.js"));
-	return {
-		adapter: fileURLToPath(import.meta.resolve("./cdn-adapter.runtime.js")),
-		options,
-		output: {
-			entry: workerEntry,
-			matchesBuild({ plugins }) {
-				return plugins.some(({ name }) => name === "vite-plugin-cloudflare" || name?.startsWith("vite-plugin-cloudflare:"));
-			},
-			transformHostEntry({ code, id }) {
-				if ((id.charCodeAt(0) === 0 ? id.slice(1) : id) !== CLOUDFLARE_WORKER_ENTRY_ID) return null;
-				return `${code}\nexport { VinextCachedResponse, VinextUncachedResponse } from ${JSON.stringify(workerEntry)};\n`;
-			},
-			finalizeBuildOutput({ outDir, isPrimaryServerOutput }) {
-				return finalizeCdnAdapterBuildOutput({
-					outDir,
-					isPrimaryServerOutput,
-					binding: versionMetadataBinding,
-					bindingIsExplicit
-				});
-			},
-			type: "multi-stage"
-		},
-		capabilities: {
-			buildIdentity: "response-header",
-			isResponsePolicyHeader: (name) => name.toLowerCase() === "cdn-cache-control" || name.toLowerCase() === "cloudflare-cdn-cache-control",
-			requestRouting: "uncached-stage",
-			responseVary: "verbatim",
-			routeCacheability: "probe-manifest"
-		}
-	};
-}
+/** @deprecated Use {@link workersCacheCdnAdapter} from `@vinext/cloudflare/cache/workers-cache-cdn-adapter` instead. */
+const cdnAdapter = workersCacheCdnAdapter;
 //#endregion
 export { DEFAULT_CDN_VERSION_METADATA_BINDING, cdnAdapter };

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

@@ -17,6 +17,7 @@ export declare class CloudflareCdnCacheAdapter implements CdnCacheAdapter {
   readonly responsePolicy: {
     isHeader(name: string): boolean;
     readCacheControl(headers: Headers): string | null;
+    readCacheControlHeaderName(headers: Headers): string | null;
     hasExplicitNonCacheablePolicy(headers: Headers, baseline?: Headers): boolean;
   };
   constructor(versionMetadata?: WorkerVersionMetadata | undefined, versionMetadataBinding?: string);

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

@@ -1,8 +1,8 @@
 import { VINEXT_CDN_BUILD_ID_HEADER, getVinextCdnBuildIdentity } from "./cdn-build-id.js";
 import { VINEXT_EXPECTED_WORKER_VERSION_HEADER } from "../version-headers.js";
-import { isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
-import { fnv1a64 } from "vinext/internal/utils/hash";
+import { isNonCacheableCacheControl, splitCacheControlDirectives } from "vinext/shims/cdn-cache";
 import { getRequestExecutionContext } from "vinext/shims/request-context";
+import { fnv1a64 } from "vinext/internal/utils/hash";
 //#region src/cache/cdn-adapter.runtime.ts
 /**
 * Cloudflare CDN cache adapter — edge-managed page-level ISR backed by the
@@ -19,11 +19,9 @@ import { getRequestExecutionContext } from "vinext/shims/request-context";
 *   cache headers, so there is nothing to persist at the origin.
 * - `buildResponseHeaders` emits the SWR policy as `Cloudflare-CDN-Cache-Control`
 *   (`public, max-age=…, stale-while-revalidate=…`) so the edge caches and
-*   revalidates. The inner response's `Cache-Control` is
-*   `public, max-age=0, must-revalidate` so a browser never serves a stored copy
-*   without revalidating against the edge; the uncached gateway changes that to
-*   `private, max-age=0, must-revalidate` before public egress so personalized
-*   request-stage headers cannot enter another shared cache. A `Cache-Tag`
+*   revalidates. Explicit endpoint Cache-Control is preserved for clients,
+*   independently of shared admission. Framework-managed responses default to
+*   `private, max-age=0, must-revalidate`. A `Cache-Tag`
 *   header lets entries be purged by tag. Note the edge directive uses `max-age`
 *   (not `s-maxage`):
 *   the framework computes the policy with `s-maxage` for shared caches, but
@@ -37,7 +35,7 @@ import { getRequestExecutionContext } from "vinext/shims/request-context";
 *
 * The default export is the adapter factory the generated
 * `virtual:vinext-cache-adapters` registration imports; configure it from
-* vite.config via the {@link cdnAdapter} builder in `./cdn-adapter.ts` (which
+* vite.config via the {@link workersCacheCdnAdapter} builder in `./workers-cache-cdn-adapter.ts` (which
 * `require.resolve`s this file).
 */
 const DEFAULT_VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
@@ -54,13 +52,13 @@ function getBuildIdentityResponseHeader() {
 	const buildId = getVinextCdnBuildIdentity();
 	return buildId ? { [VINEXT_CDN_BUILD_ID_HEADER]: buildId } : {};
 }
-/** Remove every response header whose cache semantics are owned by Cloudflare. */
-function clearCloudflareCdnResponseHeaders(cacheControl) {
+/** Disable shared caching while preserving an explicit client policy. */
+function clearCloudflareCdnResponseHeaders(cacheControl, browserCacheControl) {
 	return {
 		...getBuildIdentityResponseHeader(),
-		"Cache-Control": cacheControl,
+		"Cache-Control": browserCacheControl ?? cacheControl,
 		"CDN-Cache-Control": null,
-		"Cloudflare-CDN-Cache-Control": null,
+		"Cloudflare-CDN-Cache-Control": browserCacheControl !== void 0 && !isNonCacheableCacheControl(browserCacheControl) ? "no-store" : null,
 		"Cache-Tag": null
 	};
 }
@@ -72,8 +70,19 @@ function hasExplicitCloudflareNonCacheableResponsePolicy(headers) {
 	const browserPolicy = headers.get("Cache-Control");
 	return Boolean(!hasCacheableEdgePolicy && browserPolicy && isNonCacheableCacheControl(browserPolicy));
 }
+/** Shared-cache policy headers in the order Cloudflare honors them. */
+const RESPONSE_POLICY_PRECEDENCE = [
+	"Cloudflare-CDN-Cache-Control",
+	"CDN-Cache-Control",
+	"Cache-Control"
+];
+/** Name the highest-precedence policy header Cloudflare honors on a response. */
+function readCloudflareResponsePolicyHeaderName(headers) {
+	return RESPONSE_POLICY_PRECEDENCE.find((name) => headers.has(name)) ?? null;
+}
 function readCloudflareResponseCacheControl(headers) {
-	return headers.get("Cloudflare-CDN-Cache-Control") ?? headers.get("CDN-Cache-Control") ?? headers.get("Cache-Control");
+	const name = readCloudflareResponsePolicyHeaderName(headers);
+	return name ? headers.get(name) : null;
 }
 function getWorkersCache() {
 	const cache = getRequestExecutionContext()?.cache;
@@ -88,7 +97,7 @@ const NO_STORE = "no-store";
 * revalidate (against the edge) rather than serving a stored copy — so the user
 * always sees edge-fresh content while still permitting conditional 304s.
 */
-const BROWSER_REVALIDATE = "public, max-age=0, must-revalidate";
+const BROWSER_REVALIDATE = "private, max-age=0, must-revalidate";
 /**
 * A concrete stale window (1 year) substituted for a value-less
 * `stale-while-revalidate`. The framework emits a bare `stale-while-revalidate`
@@ -108,8 +117,10 @@ const UNBOUNDED_SWR_SECONDS = 31536e3;
 * `public`.
 */
 function toEdgeCacheControl(cacheControl) {
-	const withMaxAge = cacheControl.replace(/\bs-maxage=/g, "max-age=").replace(/\bstale-while-revalidate\b(?!=)/g, `stale-while-revalidate=${UNBOUNDED_SWR_SECONDS}`);
-	return /\bpublic\b/.test(withMaxAge) ? withMaxAge : `public, ${withMaxAge}`;
+	const directives = splitCacheControlDirectives(cacheControl);
+	const hasSharedMaxAge = directives.some((directive) => /^s-maxage\s*=/i.test(directive));
+	const withMaxAge = directives.filter((directive) => !hasSharedMaxAge || !/^max-age\s*=/i.test(directive)).map((directive) => directive.replace(/^s-maxage\s*=/i, "max-age=").replace(/^stale-while-revalidate$/i, `stale-while-revalidate=${UNBOUNDED_SWR_SECONDS}`)).join(", ");
+	return directives.some((directive) => /^public$/i.test(directive)) ? withMaxAge : `public, ${withMaxAge}`;
 }
 /**
 * Cloudflare's `Cache-Tag` header budget is 16 KB total. Fixed-size digests let
@@ -143,6 +154,9 @@ var CloudflareCdnCacheAdapter = class {
 		readCacheControl(headers) {
 			return readCloudflareResponseCacheControl(headers);
 		},
+		readCacheControlHeaderName(headers) {
+			return readCloudflareResponsePolicyHeaderName(headers);
+		},
 		hasExplicitNonCacheablePolicy(headers, baseline) {
 			if (baseline) {
 				for (const name of EDGE_POLICY_HEADERS) {
@@ -183,12 +197,12 @@ var CloudflareCdnCacheAdapter = class {
 	buildResponseHeaders(input) {
 		if (input.pendingDynamicCheck) return clearCloudflareCdnResponseHeaders(NO_STORE);
 		if (!input.cacheControl) return clearCloudflareCdnResponseHeaders(NO_STORE);
-		if (isNonCacheableCacheControl(input.cacheControl)) return clearCloudflareCdnResponseHeaders(input.cacheControl);
+		if (isNonCacheableCacheControl(input.cacheControl)) return clearCloudflareCdnResponseHeaders(input.cacheControl, input.browserCacheControl);
 		const cacheTag = input.tags?.length ? formatCacheTag(input.tags) : null;
-		if (input.tags?.length && !cacheTag) return clearCloudflareCdnResponseHeaders(NO_STORE);
+		if (input.tags?.length && !cacheTag) return clearCloudflareCdnResponseHeaders(NO_STORE, input.browserCacheControl);
 		return {
 			...getBuildIdentityResponseHeader(),
-			"Cache-Control": BROWSER_REVALIDATE,
+			"Cache-Control": input.browserCacheControl ?? BROWSER_REVALIDATE,
 			"CDN-Cache-Control": null,
 			"Cloudflare-CDN-Cache-Control": toEdgeCacheControl(input.cacheControl),
 			"Cache-Tag": cacheTag

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

@@ -19,7 +19,7 @@ export declare class VinextCachedResponse extends WorkerEntrypoint<unknown, unkn
   fetch(request: Request): Promise<Response>;
   purge(options: CachePurgeOptions): Promise<unknown>;
 }
-/** Uncached response entrypoint. Bypass and probe renders execute only here. */
+/** Uncached response entrypoint retained for deployment readiness probes. */
 export declare class VinextUncachedResponse extends WorkerEntrypoint<unknown, unknown> {
   fetch(request: Request): Promise<Response>;
 }