vinext 0.0.55 → 0.1.0

package/dist/shims/cache-runtime.js

@@ -2,7 +2,7 @@ import { getOrCreateAls } from "./internal/als-registry.js";
 import { getRequestContext, isInsideUnifiedScope, runWithUnifiedStateMutation } from "./unified-request-context.js";
 import { VINEXT_RSC_MARKER_HEADER } from "../server/headers.js";
 import { markDynamicUsage } from "./headers.js";
-import { _registerCacheContextAccessor, _setRequestScopedCacheLife, cacheLifeProfiles, getCacheHandler } from "./cache.js";
+import { _registerCacheContextAccessor, _setRequestScopedCacheLife, cacheLifeProfiles, getDataCacheHandler } from "./cache.js";
 //#region src/shims/cache-runtime.ts
 /**
 * "use cache" runtime
@@ -33,6 +33,7 @@ import { _registerCacheContextAccessor, _setRequestScopedCacheLife, cacheLifePro
 * - "use cache: remote"   — shared cache (explicit)
 * - "use cache: private"  — per-request cache (not shared across requests)
 */
+const APP_PAGE_PROPS_CACHE_KEY_MARKER = Symbol.for("vinext.appPagePropsCacheKeyMarker");
 /** Threshold below which expire is considered "dynamic" (5 minutes in seconds). */
 const DYNAMIC_EXPIRE = 300;
 /**
@@ -219,6 +220,15 @@ function clearPrivateCache() {
 	if (state) state._privateCache = /* @__PURE__ */ new Map();
 	else _privateFallbackState._privateCache = /* @__PURE__ */ new Map();
 }
+function markAppPagePropsForUseCache(props) {
+	Object.defineProperty(props, APP_PAGE_PROPS_CACHE_KEY_MARKER, {
+		configurable: false,
+		enumerable: false,
+		value: true,
+		writable: false
+	});
+	return props;
+}
 /**
 * Register a function as a cached function. This is called by the Vite
 * transform for each "use cache" function.
@@ -228,19 +238,20 @@ function clearPrivateCache() {
 * @param variant - Cache variant: "" (default/shared), "remote", "private"
 * @returns A wrapper function that checks cache before calling the original
 */
-function registerCachedFunction(fn, id, variant) {
+function registerCachedFunction(fn, id, variant, options = {}) {
 	const cacheVariant = variant ?? "";
+	const omitAppPageSearchParamsFromFirstArg = options.appPageDefaultExport === true;
 	const isDev = typeof process !== "undefined" && process.env.NODE_ENV === "development";
 	const cachedFn = async (...args) => {
 		const rsc = await getRscModule();
 		const keySeed = getUseCacheKeySeed();
 		let cacheKey;
 		try {
+			const processedArgs = args.length > 0 ? unwrapThenableObjectArray(args, { omitAppPageSearchParamsFromFirstArg }) : [];
 			if (rsc && args.length > 0) {
 				const tempRefs = rsc.createClientTemporaryReferenceSet();
-				const processedArgs = unwrapThenableObjectArray(args);
 				cacheKey = buildUseCacheKey(id, keySeed, await replyToCacheKey(await rsc.encodeReply(processedArgs, { temporaryReferences: tempRefs })));
-			} else cacheKey = buildUseCacheKey(id, keySeed, args.length > 0 ? stableStringify(args) : void 0);
+			} else cacheKey = buildUseCacheKey(id, keySeed, processedArgs.length > 0 ? stableStringify(processedArgs) : void 0);
 		} catch {
 			return fn(...args);
 		}
@@ -256,7 +267,7 @@ function registerCachedFunction(fn, id, variant) {
 			return result;
 		}
 		if (isDev) return executeWithContext(fn, args, cacheVariant);
-		const handler = getCacheHandler();
+		const handler = getDataCacheHandler();
 		const existing = await handler.get(cacheKey, { kind: "FETCH" });
 		if (existing?.value && existing.value.kind === "FETCH" && existing.cacheState !== "stale") try {
 			if (rsc && existing.value.data.headers["x-vinext-rsc"] === "1") {
@@ -303,6 +314,10 @@ function registerCachedFunction(fn, id, variant) {
 		} catch {}
 		return result;
 	};
+	Object.defineProperty(cachedFn, "length", {
+		value: fn.length,
+		configurable: true
+	});
 	return cachedFn;
 }
 function throwPrivateUseCacheInsidePublicUseCacheError() {
@@ -339,9 +354,11 @@ async function runCachedFunctionWithContext(fn, args, variant) {
 		variant: variant || "default",
 		hasExplicitRevalidate: false,
 		hasExplicitExpire: false,
-		dynamicNestedCacheError: void 0
+		dynamicNestedCacheError: void 0,
+		invalidDynamicUsageError: void 0
 	};
 	const result = await cacheContextStorage.run(ctx, () => fn(...args));
+	if (ctx.invalidDynamicUsageError) throw ctx.invalidDynamicUsageError;
 	const effectiveLife = resolveCacheLife(ctx.lifeConfigs);
 	if (parentCtx) parentCtx.lifeConfigs.push(effectiveLife);
 	if (parentCtx && eagerError && (effectiveLife.revalidate === 0 || effectiveLife.expire !== void 0 && effectiveLife.expire < DYNAMIC_EXPIRE)) parentCtx.dynamicNestedCacheError ??= eagerError;
@@ -355,25 +372,9 @@ async function runCachedFunctionWithContext(fn, args, variant) {
 		effectiveLife
 	};
 }
-/**
-* Recursively unwrap "thenable objects" — values created by
-* `Object.assign(Promise.resolve(obj), obj)` — into plain objects.
-*
-* Next.js 16 params and searchParams are passed as Promise-augmented objects
-* that work both as `await params` and `params.key`. When these are fed to
-* `encodeReply` with `temporaryReferences`, the Promise is treated as a
-* temporary reference and its actual values are **excluded** from the
-* serialized output. This means different param values (e.g.,
-* `section:"sports"` vs `section:"electronics"`) produce identical cache keys.
-*
-* This function extracts the own enumerable properties into plain objects
-* so `encodeReply` can serialize the actual values into the cache key.
-* Only used for cache key generation — the original Promise-augmented
-* objects are still passed to the actual function on cache miss.
-*/
-function unwrapThenableObjects(value) {
+function unwrapThenableObjects(value, options = {}) {
 	if (value === null || value === void 0 || typeof value !== "object") return value;
-	if (Array.isArray(value)) return value.map(unwrapThenableObjects);
+	if (Array.isArray(value)) return value.map((item) => unwrapThenableObjects(item));
 	if (typeof value.then === "function") {
 		const keys = Object.keys(value);
 		if (keys.length > 0) {
@@ -384,11 +385,17 @@ function unwrapThenableObjects(value) {
 		return value;
 	}
 	const result = {};
-	for (const key of Object.keys(value)) result[key] = unwrapThenableObjects(value[key]);
+	for (const key of Object.keys(value)) {
+		if (key === "searchParams" && (options.omitAppPageSearchParamsAtRoot || isMarkedAppPagePropsObject(value))) continue;
+		result[key] = unwrapThenableObjects(value[key]);
+	}
 	return result;
 }
-function unwrapThenableObjectArray(values) {
-	return values.map(unwrapThenableObjects);
+function isMarkedAppPagePropsObject(value) {
+	return Reflect.get(value, APP_PAGE_PROPS_CACHE_KEY_MARKER) === true;
+}
+function unwrapThenableObjectArray(values, options) {
+	return values.map((value, index) => unwrapThenableObjects(value, { omitAppPageSearchParamsAtRoot: index === 0 && options.omitAppPageSearchParamsFromFirstArg }));
 }
 function stableStringify(value, seen) {
 	if (value === void 0) return "undefined";
@@ -415,6 +422,4 @@ function stableStringify(value, seen) {
 	return JSON.stringify(value);
 }
 //#endregion
-export { NestedDynamicUseCacheError, cacheContextStorage, clearPrivateCache, getCacheContext, registerCachedFunction, replyToCacheKey, runWithPrivateCache };
-
-//# sourceMappingURL=cache-runtime.js.map
+export { NestedDynamicUseCacheError, cacheContextStorage, clearPrivateCache, getCacheContext, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };

package/dist/shims/cache.d.ts

@@ -97,6 +97,16 @@ declare class NoOpCacheHandler implements CacheHandler {
 type MemoryCacheHandlerOptions = Pick<CacheHandlerContext, "maxMemoryCacheSize"> & {
   cacheMaxMemorySize?: number;
 };
+/**
+ * In-memory data cache handler. This is the built-in default — vinext installs
+ * it automatically, so consumers should not construct or register it by hand.
+ *
+ * @deprecated Consumers should not instantiate cache handlers directly.
+ * Configure caching declaratively via the `cache` option on the `vinext()`
+ * plugin (see {@link setDataCacheHandler}); the in-memory handler is the
+ * default when nothing is configured, and its size is tuned via the
+ * `cacheMaxMemorySize` plugin option.
+ */
 declare class MemoryCacheHandler implements CacheHandler {
   private store;
   private tagRevalidatedAt;
@@ -116,15 +126,47 @@ declare class MemoryCacheHandler implements CacheHandler {
 }
 declare function configureMemoryCacheHandler(options?: MemoryCacheHandlerOptions): void;
 /**
- * Set a custom CacheHandler. Call this during server startup to
- * plug in Cloudflare KV, Redis, DynamoDB, or any other backend.
+ * Set the **data cache** handler. This backs all data-cache concerns —
+ * `fetch` caching, `"use cache"`, `unstable_cache` — and is also the default
+ * underlying store for page-level ISR (via the default CDN cache adapter).
+ *
+ * The handler must implement the CacheHandler interface (same shape as
+ * Next.js 16's CacheHandler class).
+ *
+ * @deprecated Don't wire up the data cache imperatively. Configure it
+ * declaratively via the `cache.data` option on the `vinext()` plugin in your
+ * `vite.config.ts`, using a config-time adapter builder. On Cloudflare Workers:
+ *
+ * ```ts
+ * import { vinext } from "vinext";
+ * import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";
  *
- * The handler must implement the CacheHandler interface (same shape
- * as Next.js 16's CacheHandler class).
+ * export default defineConfig({
+ *   plugins: [vinext({ cache: { data: kvDataAdapter({ binding: "VINEXT_KV_CACHE" }) } })],
+ * });
+ * ```
+ *
+ * The plugin defers instantiation to the first request and registers the
+ * handler across every runtime/router entry, so you don't have to call this
+ * from a worker entry. This setter remains as the internal registration target
+ * and for backwards compatibility, but is not the recommended consumer API.
+ */
+declare function setDataCacheHandler(handler: CacheHandler): void;
+/**
+ * Get the active data cache handler (for internal use or testing).
+ */
+declare function getDataCacheHandler(): CacheHandler;
+/**
+ * @deprecated Don't wire up the data cache imperatively. Configure it
+ * declaratively via the `cache.data` option on the `vinext()` plugin (e.g.
+ * `kvDataAdapter()` from `@vinext/cloudflare/cache/kv-data-adapter`). See
+ * {@link setDataCacheHandler} for the migration example. Retained as a
+ * backwards-compatible alias — `setCacheHandler` has always configured the
+ * data cache handler.
  */
 declare function setCacheHandler(handler: CacheHandler): void;
 /**
- * Get the active CacheHandler (for internal use or testing).
+ * @deprecated Prefer {@link getDataCacheHandler}.
  */
 declare function getCacheHandler(): CacheHandler;
 /**
@@ -327,5 +369,4 @@ type UnstableCacheOptions = {
  */
 declare function unstable_cache<T extends (...args: any[]) => Promise<any>>(fn: T, keyParts?: string[], options?: UnstableCacheOptions): T;
 //#endregion
-export { ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CacheLifeConfig, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, UnstableCacheObservation, UnstableCacheRevalidationMode, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getRequestExecutionContext, io, isInsideUnstableCacheScope, unstable_noStore as noStore, unstable_noStore, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };
-//# sourceMappingURL=cache.d.ts.map
+export { ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CacheLifeConfig, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, UnstableCacheObservation, UnstableCacheRevalidationMode, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRequestExecutionContext, io, isInsideUnstableCacheScope, unstable_noStore as noStore, unstable_noStore, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };

package/dist/shims/cache.js

@@ -7,6 +7,7 @@ import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 import { makeHangingPromise } from "./internal/make-hanging-promise.js";
 import { readCacheControlNumberField } from "../utils/cache-control-metadata.js";
 import { encodeCacheTag, encodeCacheTags } from "../utils/encode-cache-tag.js";
+import { getCdnCacheAdapter } from "./cdn-cache.js";
 //#region src/shims/cache.ts
 /**
 * next/cache shim
@@ -19,12 +20,14 @@ import { encodeCacheTag, encodeCacheTags } from "../utils/encode-cache-tag.js";
 * existing community adapters (@neshca/cache-handler, @opennextjs/aws, etc.)
 * can be used directly.
 *
-* Configuration (in vite.config.ts or next.config.js):
-*   vinext({ cacheHandler: './my-cache-handler.ts' })
+* Recommended configuration is declarative, via the `cache` option on the
+* `vinext()` plugin in vite.config.ts:
+*   import { kvDataAdapter } from '@vinext/cloudflare/cache/kv-data-adapter';
+*   vinext({ cache: { data: kvDataAdapter({ binding: 'VINEXT_KV_CACHE' }) } })
 *
-* Or set at runtime:
-*   import { setCacheHandler } from 'next/cache';
-*   setCacheHandler(new MyCacheHandler());
+* The imperative `setCacheHandler` / `setDataCacheHandler` setters are
+* deprecated for consumers and retained only as the internal registration
+* target used by the generated cache-adapter module.
 */
 /** @internal Set by cache-runtime.ts on import to avoid circular dependency */
 let _getCacheContextFn = null;
@@ -77,6 +80,16 @@ function readStringArrayField(ctx, field) {
 	if (!Array.isArray(value)) return [];
 	return value.filter((item) => typeof item === "string");
 }
+/**
+* In-memory data cache handler. This is the built-in default — vinext installs
+* it automatically, so consumers should not construct or register it by hand.
+*
+* @deprecated Consumers should not instantiate cache handlers directly.
+* Configure caching declaratively via the `cache` option on the `vinext()`
+* plugin (see {@link setDataCacheHandler}); the in-memory handler is the
+* default when nothing is configured, and its size is tuned via the
+* `cacheMaxMemorySize` plugin option.
+*/
 var MemoryCacheHandler = class {
 	store = /* @__PURE__ */ new Map();
 	tagRevalidatedAt = /* @__PURE__ */ new Map();
@@ -198,22 +211,58 @@ function configureMemoryCacheHandler(options) {
 	_gHandler[_HANDLER_KEY] = new MemoryCacheHandler(options);
 }
 /**
-* Set a custom CacheHandler. Call this during server startup to
-* plug in Cloudflare KV, Redis, DynamoDB, or any other backend.
-*
-* The handler must implement the CacheHandler interface (same shape
-* as Next.js 16's CacheHandler class).
+* Set the **data cache** handler. This backs all data-cache concerns —
+* `fetch` caching, `"use cache"`, `unstable_cache` — and is also the default
+* underlying store for page-level ISR (via the default CDN cache adapter).
+*
+* The handler must implement the CacheHandler interface (same shape as
+* Next.js 16's CacheHandler class).
+*
+* @deprecated Don't wire up the data cache imperatively. Configure it
+* declaratively via the `cache.data` option on the `vinext()` plugin in your
+* `vite.config.ts`, using a config-time adapter builder. On Cloudflare Workers:
+*
+* ```ts
+* import { vinext } from "vinext";
+* import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter";
+*
+* export default defineConfig({
+*   plugins: [vinext({ cache: { data: kvDataAdapter({ binding: "VINEXT_KV_CACHE" }) } })],
+* });
+* ```
+*
+* The plugin defers instantiation to the first request and registers the
+* handler across every runtime/router entry, so you don't have to call this
+* from a worker entry. This setter remains as the internal registration target
+* and for backwards compatibility, but is not the recommended consumer API.
 */
-function setCacheHandler(handler) {
+function setDataCacheHandler(handler) {
 	_gHandler[_HANDLER_KEY] = handler;
 }
 /**
-* Get the active CacheHandler (for internal use or testing).
+* Get the active data cache handler (for internal use or testing).
 */
-function getCacheHandler() {
+function getDataCacheHandler() {
 	return _getActiveHandler();
 }
 /**
+* @deprecated Don't wire up the data cache imperatively. Configure it
+* declaratively via the `cache.data` option on the `vinext()` plugin (e.g.
+* `kvDataAdapter()` from `@vinext/cloudflare/cache/kv-data-adapter`). See
+* {@link setDataCacheHandler} for the migration example. Retained as a
+* backwards-compatible alias — `setCacheHandler` has always configured the
+* data cache handler.
+*/
+function setCacheHandler(handler) {
+	setDataCacheHandler(handler);
+}
+/**
+* @deprecated Prefer {@link getDataCacheHandler}.
+*/
+function getCacheHandler() {
+	return getDataCacheHandler();
+}
+/**
 * Revalidate cached data associated with a specific cache tag.
 *
 * Works with both `fetch(..., { next: { tags: ['myTag'] } })` and
@@ -233,7 +282,20 @@ async function revalidateTag(tag, profile) {
 		if (resolved) durations = { expire: resolved.expire };
 	} else if (profile && typeof profile === "object") durations = profile;
 	if (!profile || !durations || durations.expire === 0) markActionRevalidation(ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC);
-	await _getActiveHandler().revalidateTag(encodeCacheTag(tag), durations);
+	await _invalidateEncodedTag(encodeCacheTag(tag), durations);
+}
+/**
+* Invalidate one already-encoded tag across both cache layers.
+*
+* Ordering is intentional and load-bearing: invalidate the data cache store
+* FIRST (covers fetch data, `"use cache"`, and page entries stored there by the
+* default CDN adapter), THEN ask the CDN adapter to purge its edge (a no-op for
+* the default adapter). Purging the edge before the store is invalidated would
+* let the edge re-fetch and re-cache stale data.
+*/
+async function _invalidateEncodedTag(encoded, durations) {
+	await _getActiveHandler().revalidateTag(encoded, durations);
+	await getCdnCacheAdapter().revalidateTag(encoded, durations);
 }
 /**
 * Revalidate cached data associated with a specific path.
@@ -253,8 +315,7 @@ async function revalidateTag(tag, profile) {
 async function revalidatePath(path, type) {
 	markActionRevalidation(ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC);
 	const stem = path.endsWith("/") ? path.slice(0, -1) : path;
-	const tag = type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`;
-	await _getActiveHandler().revalidateTag(encodeCacheTag(tag));
+	await _invalidateEncodedTag(encodeCacheTag(type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`));
 }
 /**
 * No-op shim for API compatibility.
@@ -283,7 +344,7 @@ function refresh() {
 async function updateTag(tag) {
 	if (getHeadersAccessPhase() !== "action") throw new Error("updateTag can only be called from within a Server Action. To invalidate cache tags in Route Handlers or other contexts, use revalidateTag instead. See more info here: https://nextjs.org/docs/app/api-reference/functions/updateTag");
 	markActionRevalidation(ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC);
-	await _getActiveHandler().revalidateTag(encodeCacheTag(tag));
+	await _invalidateEncodedTag(encodeCacheTag(tag));
 }
 /**
 * Opt out of static rendering and indicate a particular component should not be cached.
@@ -703,6 +764,4 @@ function unstable_cache(fn, keyParts, options) {
 	return cachedFn;
 }
 //#endregion
-export { MemoryCacheHandler, NoOpCacheHandler, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getRequestExecutionContext, io, isInsideUnstableCacheScope, unstable_noStore as noStore, unstable_noStore, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };
-
-//# sourceMappingURL=cache.js.map
+export { MemoryCacheHandler, NoOpCacheHandler, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRequestExecutionContext, io, isInsideUnstableCacheScope, unstable_noStore as noStore, unstable_noStore, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };

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

@@ -0,0 +1,125 @@
+import { CacheHandlerValue, IncrementalCacheValue } from "./cache.js";
+
+//#region src/shims/cdn-cache.d.ts
+/** A map of response header name -> value the adapter wants applied. */
+type CdnResponseHeaders = Record<string, string>;
+type CdnCacheableHeaderInput = {
+  /**
+   * The cacheable `Cache-Control` value the framework computed for shared
+   * caches (e.g. `s-maxage=60, stale-while-revalidate`). May be an empty string
+   * when no cacheable policy applies.
+   */
+  cacheControl: string;
+  /**
+   * True when this is a freshly-rendered **streaming** response whose
+   * dynamic-ness is not yet proven (late Server Component request-API usage can
+   * only be detected after the stream drains).
+   *
+   * The default adapter forces `no-store` for the browser in this case — the
+   * page is instead served from the origin store on subsequent requests. Edge
+   * adapters may instead emit edge-only cache headers (e.g. `CDN-Cache-Control`)
+   * so the CDN performs SWR while the browser still sees `no-store`.
+   */
+  pendingDynamicCheck?: boolean;
+  /**
+   * The cache tags associated with this page/route, already canonicalised
+   * (e.g. via `encodeCacheTag`). Edge adapters use these to emit a tag header
+   * (e.g. a `Cache-Tag` header) so tag-based purging can target the response.
+   * The default adapter ignores them.
+   */
+  tags?: readonly string[];
+};
+/**
+ * The serving strategy for page-level ISR. Implement this to delegate
+ * page/route/image caching to a CDN edge instead of the origin store.
+ */
+type CdnCacheAdapter = {
+  /**
+   * Read a page-level artifact. Returning a value lets the origin serve it
+   * (HIT/STALE); returning `null` makes the origin render fresh.
+   *
+   * Default: reads the data cache. Edge adapters typically return `null` so the
+   * edge owns serving.
+   */
+  get(key: string, ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
+  /**
+   * Persist a freshly-rendered page-level artifact.
+   *
+   * Default: writes to the data cache. Edge adapters that rely entirely on the
+   * CDN may make this a no-op.
+   */
+  set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
+  /**
+   * Build the response cache headers for a given cacheable policy. Returns a map
+   * so an adapter can emit more than one header (e.g. `Cache-Control` +
+   * `CDN-Cache-Control`).
+   */
+  buildResponseHeaders(input: CdnCacheableHeaderInput): CdnResponseHeaders;
+  /**
+   * Whether the **origin** runs in-process background regeneration when a stale
+   * entry is served. Edge adapters set this to `false` because the CDN
+   * revalidates by re-requesting the origin.
+   */
+  readonly ownsBackgroundRevalidation: boolean;
+  /**
+   * Propagate a tag/path invalidation to the CDN edge (purge). Called *in
+   * addition to* the data cache's own tag invalidation, so the default
+   * implementation is a no-op (the data cache already invalidated its entries).
+   *
+   * Edge adapters implement this to purge the edge cache — typically firing the
+   * purge through the request execution context (`ctx.waitUntil`).
+   */
+  revalidateTag(tags: string | string[], durations?: {
+    expire?: number;
+  }): Promise<void>;
+};
+/**
+ * Default origin-managed ISR strategy: store page artifacts in the data cache,
+ * serve HIT/STALE from it, run in-process background regeneration, and emit the
+ * framework's standard `Cache-Control` headers.
+ */
+declare class DefaultCdnCacheAdapter implements CdnCacheAdapter {
+  readonly ownsBackgroundRevalidation = true;
+  get(key: string, ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
+  set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
+  buildResponseHeaders(input: CdnCacheableHeaderInput): CdnResponseHeaders;
+  revalidateTag(_tags: string | string[], _durations?: {
+    expire?: number;
+  }): Promise<void>;
+}
+/**
+ * Set a custom CDN cache adapter to delegate page-level ISR to a CDN edge. An
+ * explicit adapter always wins over the built-in request-context / default
+ * selection.
+ *
+ * @deprecated Don't wire up the CDN cache adapter imperatively. Configure it
+ * declaratively via the `cache.cdn` option on the `vinext()` plugin in your
+ * `vite.config.ts`, using a config-time adapter builder. On Cloudflare Workers:
+ *
+ * ```ts
+ * import { vinext } from "vinext";
+ * import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
+ *
+ * export default defineConfig({
+ *   plugins: [vinext({ cache: { cdn: cdnAdapter() } })],
+ * });
+ * ```
+ *
+ * The plugin registers the adapter across every runtime/router entry, so you
+ * don't have to call this from a worker entry. This setter remains as the
+ * internal registration target and for backwards compatibility, but is not the
+ * recommended consumer API.
+ */
+declare function setCdnCacheAdapter(adapter: CdnCacheAdapter): void;
+/**
+ * Get the active CDN cache adapter. See the precedence note above:
+ * explicit (or an already-resolved auto-detected edge adapter) → origin-managed
+ * {@link DefaultCdnCacheAdapter}.
+ *
+ * Auto-detection of the Cloudflare Workers Cache (`ctx.cache`) only runs when
+ * `VINEXT_CDN_CACHE_AUTO_DETECT === "1"`; otherwise the default adapter is used
+ * unless an adapter was set explicitly.
+ */
+declare function getCdnCacheAdapter(): CdnCacheAdapter;
+//#endregion
+export { CdnCacheAdapter, CdnCacheableHeaderInput, CdnResponseHeaders, DefaultCdnCacheAdapter, getCdnCacheAdapter, setCdnCacheAdapter };

package/dist/shims/cdn-cache.js

@@ -0,0 +1,100 @@
+import { getRequestExecutionContext } from "./request-context.js";
+import { getDataCacheHandler } from "./cache.js";
+import { CloudflareCdnCacheAdapter } from "../cloudflare/src/cache/cdn-adapter.runtime.js";
+//#region src/shims/cdn-cache.ts
+/**
+* CDN cache adapter — owns the *page-level ISR serving strategy*.
+*
+* This is deliberately distinct from the data cache handler (see `./cache.ts`):
+*
+* - The **data cache** stores cached data (fetch, `"use cache"`,
+*   `unstable_cache`, route-handler data). It is a pure key/value store.
+*
+* - The **CDN cache adapter** decides *how page-level ISR is served*: where the
+*   rendered page/route/image artifacts live, what cache headers the response
+*   carries, whether the origin runs background regeneration, and how
+*   invalidation propagates to a CDN edge.
+*
+* Two strategies sit behind one interface:
+*
+* | Concern            | DefaultCdnCacheAdapter (origin-managed) | Edge adapter (CDN-managed)                  |
+* | ------------------ | --------------------------------------- | ------------------------------------------- |
+* | Serve from store?  | Yes — reads the data cache              | No — origin renders fresh, edge caches      |
+* | Background regen   | In-process via `waitUntil`              | Edge re-requests origin                     |
+* | Response headers   | `Cache-Control` (SWR)                   | `Cache-Control: no-store` + `CDN-Cache-Control: <SWR>` |
+* | Invalidation       | (data cache handles tag invalidation)   | purge / revalidate via request context      |
+*
+* The default adapter is a thin shim over the data cache + the framework's
+* existing header logic, so default behavior is byte-for-byte identical to the
+* pre-split implementation.
+*/
+const PENDING_DYNAMIC_CACHE_CONTROL = "no-store, must-revalidate";
+/**
+* Default origin-managed ISR strategy: store page artifacts in the data cache,
+* serve HIT/STALE from it, run in-process background regeneration, and emit the
+* framework's standard `Cache-Control` headers.
+*/
+var DefaultCdnCacheAdapter = class {
+	ownsBackgroundRevalidation = true;
+	async get(key, ctx) {
+		return getDataCacheHandler().get(key, ctx);
+	}
+	async set(key, data, ctx) {
+		await getDataCacheHandler().set(key, data, ctx);
+	}
+	buildResponseHeaders(input) {
+		if (input.pendingDynamicCheck) return { "Cache-Control": PENDING_DYNAMIC_CACHE_CONTROL };
+		return { "Cache-Control": input.cacheControl };
+	}
+	async revalidateTag(_tags, _durations) {}
+};
+const _CDN_KEY = Symbol.for("vinext.cdnCacheAdapter");
+const _gCdn = globalThis;
+let _defaultAdapter = null;
+/**
+* Set a custom CDN cache adapter to delegate page-level ISR to a CDN edge. An
+* explicit adapter always wins over the built-in request-context / default
+* selection.
+*
+* @deprecated Don't wire up the CDN cache adapter imperatively. Configure it
+* declaratively via the `cache.cdn` option on the `vinext()` plugin in your
+* `vite.config.ts`, using a config-time adapter builder. On Cloudflare Workers:
+*
+* ```ts
+* import { vinext } from "vinext";
+* import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
+*
+* export default defineConfig({
+*   plugins: [vinext({ cache: { cdn: cdnAdapter() } })],
+* });
+* ```
+*
+* The plugin registers the adapter across every runtime/router entry, so you
+* don't have to call this from a worker entry. This setter remains as the
+* internal registration target and for backwards compatibility, but is not the
+* recommended consumer API.
+*/
+function setCdnCacheAdapter(adapter) {
+	_gCdn[_CDN_KEY] = adapter;
+}
+/**
+* Get the active CDN cache adapter. See the precedence note above:
+* explicit (or an already-resolved auto-detected edge adapter) → origin-managed
+* {@link DefaultCdnCacheAdapter}.
+*
+* Auto-detection of the Cloudflare Workers Cache (`ctx.cache`) only runs when
+* `VINEXT_CDN_CACHE_AUTO_DETECT === "1"`; otherwise the default adapter is used
+* unless an adapter was set explicitly.
+*/
+function getCdnCacheAdapter() {
+	const active = _gCdn[_CDN_KEY];
+	if (active) return active;
+	if (process.env.VINEXT_CDN_CACHE_AUTO_DETECT === "1" && getRequestExecutionContext()?.cache) {
+		const edge = new CloudflareCdnCacheAdapter();
+		_gCdn[_CDN_KEY] = edge;
+		return edge;
+	}
+	return _defaultAdapter ??= new DefaultCdnCacheAdapter();
+}
+//#endregion
+export { DefaultCdnCacheAdapter, getCdnCacheAdapter, setCdnCacheAdapter };

package/dist/shims/client-hook-error.d.ts

@@ -10,5 +10,4 @@
 declare function buildClientHookErrorMessage(hookName: string): string;
 declare function throwClientHookError(hookName: string): never;
 //#endregion
-export { buildClientHookErrorMessage, throwClientHookError };
-//# sourceMappingURL=client-hook-error.d.ts.map
+export { buildClientHookErrorMessage, throwClientHookError };

package/dist/shims/client-hook-error.js

@@ -15,5 +15,3 @@ function throwClientHookError(hookName) {
 }
 //#endregion
 export { buildClientHookErrorMessage, throwClientHookError };
-
-//# sourceMappingURL=client-hook-error.js.map

package/dist/shims/client-locale.d.ts

@@ -11,5 +11,4 @@ declare function getCurrentBrowserLocale({
   hostname: string | null | undefined;
 }): string | undefined;
 //#endregion
-export { getCurrentBrowserLocale };
-//# sourceMappingURL=client-locale.d.ts.map
+export { getCurrentBrowserLocale };

package/dist/shims/client-locale.js

@@ -5,9 +5,7 @@ function getCurrentBrowserLocale({ basePath, domainLocales, hostname }) {
 	if (typeof window === "undefined") return void 0;
 	const pathnameLocale = getLocalePathPrefix(stripBasePath(window.location.pathname, basePath), window.__VINEXT_LOCALES__);
 	if (pathnameLocale) return pathnameLocale;
-	return detectDomainLocale(domainLocales, hostname ?? void 0)?.defaultLocale ?? window.__VINEXT_DEFAULT_LOCALE__ ?? window.__VINEXT_LOCALE__;
+	return detectDomainLocale(domainLocales, hostname ?? void 0)?.defaultLocale ?? window.__VINEXT_LOCALE__ ?? window.__VINEXT_DEFAULT_LOCALE__;
 }
 //#endregion
 export { getCurrentBrowserLocale };
-
-//# sourceMappingURL=client-locale.js.map

package/dist/shims/compat-router.d.ts

@@ -13,5 +13,4 @@ import { NextRouter } from "./router.js";
  */
 declare function useRouter(): NextRouter | null;
 //#endregion
-export { useRouter };
-//# sourceMappingURL=compat-router.d.ts.map
+export { useRouter };

package/dist/shims/compat-router.js

@@ -23,5 +23,3 @@ function useRouter() {
 }
 //#endregion
 export { useRouter };
-
-//# sourceMappingURL=compat-router.js.map