@qzsy/vinext 0.1.7

package/dist/shims/cache.js

@@ -0,0 +1,401 @@
+import { getOrCreateAls } from "./internal/als-registry.js";
+import { getRequestContext, isInsideUnifiedScope } from "./unified-request-context.js";
+import { getRequestExecutionContext, runWithExecutionContext } from "./request-context.js";
+import { MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
+import { getCdnCacheAdapter } from "./cdn-cache.js";
+import { fnv1a64 } from "../utils/hash.js";
+import { makeHangingPromise } from "./internal/make-hanging-promise.js";
+import { getHeadersAccessPhase, markDynamicUsage } from "./headers.js";
+import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
+import { encodeCacheTag, encodeCacheTags } from "../utils/encode-cache-tag.js";
+import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
+//#region src/shims/cache.ts
+/**
+* next/cache shim
+*
+* Provides the Next.js caching API surface: revalidateTag, revalidatePath,
+* unstable_cache. Backed by a pluggable CacheHandler that defaults to
+* in-memory but can be swapped for Cloudflare KV, Redis, DynamoDB, etc.
+*
+* The CacheHandler interface matches Next.js 16's CacheHandler class, so
+* existing community adapters (@neshca/cache-handler, @opennextjs/aws, etc.)
+* can be used directly.
+*
+* 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' }) } })
+*
+* The imperative `setCacheHandler` / `setDataCacheHandler` setters are
+* deprecated for consumers and retained only as the internal registration
+* target used by the generated cache-adapter module.
+*/
+const _g = globalThis;
+/**
+* Revalidate cached data associated with a specific cache tag.
+*
+* Works with both `fetch(..., { next: { tags: ['myTag'] } })` and
+* `unstable_cache(fn, keys, { tags: ['myTag'] })`.
+*
+* Next.js 16 updated signature: accepts a cacheLife profile as second argument
+* for stale-while-revalidate (SWR) behavior. The single-argument form is
+* deprecated but still supported for backward compatibility.
+*
+* @param tag - Cache tag to revalidate
+* @param profile - cacheLife profile name (e.g. 'max', 'hours') or inline { expire: number }
+*/
+async function revalidateTag(tag, profile) {
+	let durations;
+	if (typeof profile === "string") {
+		const resolved = cacheLifeProfiles[profile];
+		if (resolved) durations = { expire: resolved.expire };
+	} else if (profile && typeof profile === "object") durations = profile;
+	if (!profile || !durations || durations.expire === 0) markActionRevalidation(1);
+	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 getDataCacheHandler().revalidateTag(encoded, durations);
+	await getCdnCacheAdapter().revalidateTag(encoded, durations);
+}
+/**
+* Revalidate cached data associated with a specific path.
+*
+* Invalidation works through implicit tags generated at render time by
+* `buildAppPageCacheTags`, matching Next.js's getDerivedTags:
+*
+* - `type: "layout"` → invalidates `_N_T_<path>/layout`, cascading to all
+*   descendant pages (they carry ancestor layout tags from render time).
+* - `type: "page"` → invalidates `_N_T_<path>/page`, targeting only the
+*   exact route's page component.
+* - No type → invalidates `_N_T_<path>` (broader, exact path).
+*
+* The `type` parameter is App Router only — Pages Router does not generate
+* layout/page hierarchy tags, so only no-type invalidation applies there.
+*/
+async function revalidatePath(path, type) {
+	markActionRevalidation(1);
+	const stem = path.endsWith("/") ? path.slice(0, -1) : path;
+	await _invalidateEncodedTag(encodeCacheTag(type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`));
+}
+/**
+* No-op shim for API compatibility.
+*
+* In Next.js, calling `refresh()` inside a Server Action triggers a
+* client-side router refresh so the user immediately sees updated data.
+* vinext reports the dynamic-only invalidation through the Server Action
+* response header that the client router already understands.
+*/
+function refresh() {
+	markActionRevalidation(2);
+}
+/**
+* Expire a cache tag immediately (Next.js 16).
+*
+* Server Actions-only API that expires a tag so the next request
+* fetches fresh data. Unlike `revalidateTag`, which uses stale-while-revalidate,
+* `updateTag` invalidates synchronously within the same request context.
+*
+* Throws if called outside a Server Action — e.g. from a Route Handler or
+* during render — matching Next.js's enforcement. For Route Handlers, callers
+* should use `revalidateTag` instead.
+*
+* @see https://nextjs.org/docs/app/api-reference/functions/updateTag
+*/
+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(1);
+	await _invalidateEncodedTag(encodeCacheTag(tag));
+}
+/**
+* Opt out of static rendering and indicate a particular component should not be cached.
+*
+* In Next.js, calling noStore() inside a Server Component ensures the component
+* is dynamically rendered. In our implementation, this is a no-op since we don't
+* have the same static/dynamic rendering split — all server rendering is on-demand.
+* It's provided for API compatibility so apps importing it don't break.
+*/
+function unstable_noStore() {
+	markDynamicUsage();
+}
+/**
+* A fulfilled thenable that React can unwrap synchronously via `use()`
+* without ever suspending. Reusing a single instance avoids allocating
+* on every call — matching Next.js's browser/client implementation.
+*
+* @see https://github.com/vercel/next.js/blob/canary/packages/next/src/client/request/io.browser.ts
+*/
+const _resolvedIOPromise = Promise.resolve(void 0);
+_resolvedIOPromise.status = "fulfilled";
+_resolvedIOPromise.value = void 0;
+/**
+* Marks an IO boundary in server components by returning a resolved promise
+* during requests and a hanging promise during prerendering.
+*
+* See: https://github.com/vercel/next.js/pull/92521
+* Guard removed: https://github.com/vercel/next.js/pull/92923
+* Stabilized (renamed from unstable_io): https://github.com/vercel/next.js/pull/93621
+*
+* Ported from Next.js: packages/next/src/server/request/io.ts
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/server/request/io.ts
+*
+* Behavior by work unit type:
+* - request → resolve immediately (no delay needed for dynamic SSR)
+* - prerender / prerender-client / prerender-runtime → hang (prevent
+*   execution past IO boundary during static generation)
+* - cache / private-cache / unstable-cache → resolve immediately
+*   (caches capture IO results at fill time)
+* - generate-static-params → resolve immediately (build time, no prerender to stall)
+* - prerender-legacy → resolve immediately (no cache components)
+*
+* When no work unit store is present (e.g. client-side, standalone script),
+* resolves immediately — matching the browser/client implementation.
+*/
+function io() {
+	const workUnitStore = workUnitAsyncStorage.getStore();
+	if (workUnitStore) switch (workUnitStore.type) {
+		case "request": return _resolvedIOPromise;
+		case "prerender":
+		case "prerender-client":
+		case "prerender-runtime": return makeHangingPromise(workUnitStore.renderSignal, workUnitStore.route ?? "unknown", "`io()`");
+		case "cache":
+		case "private-cache":
+		case "unstable-cache":
+		case "generate-static-params":
+		case "prerender-legacy": return _resolvedIOPromise;
+		default: return _resolvedIOPromise;
+	}
+	return _resolvedIOPromise;
+}
+/**
+* @deprecated Use `io` instead. Kept as a transitional alias since vinext
+* shipped the unstable name longer than upstream Next.js (see #805). Will be
+* removed in a future minor.
+*/
+function unstable_io() {
+	if (!_unstableIoWarned) {
+		_unstableIoWarned = true;
+		console.warn("[vinext] `unstable_io` is deprecated. Import `io` from 'next/cache' instead.");
+	}
+	return io();
+}
+let _unstableIoWarned = false;
+/**
+* Set the cache lifetime for a "use cache" function.
+*
+* Accepts either a built-in profile name (e.g., "hours", "days") or a custom
+* configuration object. In Next.js, this only works inside "use cache" functions.
+*
+* When called inside a "use cache" function, this sets the cache TTL.
+* The "minimum-wins" rule applies: if called multiple times, the shortest
+* duration for each field wins.
+*
+* When called outside a "use cache" context, this is a validated no-op.
+*/
+function cacheLife(profile) {
+	let resolvedConfig;
+	if (typeof profile === "string") {
+		if (!cacheLifeProfiles[profile]) {
+			console.warn(`[vinext] cacheLife: unknown profile "${profile}". Available profiles: ${Object.keys(cacheLifeProfiles).join(", ")}`);
+			return;
+		}
+		resolvedConfig = { ...cacheLifeProfiles[profile] };
+	} else if (typeof profile === "object" && profile !== null) {
+		if (profile.expire !== void 0 && profile.revalidate !== void 0 && profile.expire < profile.revalidate) console.warn("[vinext] cacheLife: expire must be >= revalidate");
+		resolvedConfig = {
+			...cacheLifeProfiles.default,
+			...profile
+		};
+	} else return;
+	try {
+		const ctx = getRegisteredCacheContext();
+		if (ctx) {
+			ctx.lifeConfigs.push(resolvedConfig);
+			if (resolvedConfig.revalidate !== void 0) ctx.hasExplicitRevalidate = true;
+			if (resolvedConfig.expire !== void 0) ctx.hasExplicitExpire = true;
+			_setRequestScopedCacheLife(resolvedConfig);
+			return;
+		}
+	} catch {}
+	_setRequestScopedCacheLife(resolvedConfig);
+}
+/**
+* Tag a "use cache" function's cached result for on-demand revalidation.
+*
+* Tags set here can be invalidated via revalidateTag(). In Next.js, this only
+* works inside "use cache" functions.
+*
+* When called inside a "use cache" function, tags are attached to the cached
+* entry. They can later be invalidated via revalidateTag().
+*
+* When called outside a "use cache" context, this is a no-op.
+*/
+function cacheTag(...tags) {
+	try {
+		const ctx = getRegisteredCacheContext();
+		if (ctx) ctx.tags.push(...encodeCacheTags(tags));
+	} catch {}
+}
+/**
+* @deprecated Use `cacheLife` instead. `unstable_cacheLife` was stabilized
+* upstream and the `unstable_`-prefixed name will be removed in a future
+* version of Next.js. Kept as a delegating alias for parity.
+*
+* Emits a one-time deprecation warning via `console.error` (matching Next.js),
+* then delegates to `cacheLife`.
+*
+* Ported from Next.js: packages/next/cache.js
+* https://github.com/vercel/next.js/blob/canary/packages/next/cache.js
+*
+* Asserted by Next.js test:
+* test/e2e/app-dir/cache-components-errors/cache-components-unstable-deprecations.test.ts
+*/
+let _unstableCacheLifeWarned = false;
+function unstable_cacheLife(profile) {
+	if (!_unstableCacheLifeWarned) {
+		_unstableCacheLifeWarned = true;
+		console.error(/* @__PURE__ */ new Error("`unstable_cacheLife` was recently stabilized and should be imported as `cacheLife`. The `unstable` prefixed form will be removed in a future version of Next.js."));
+	}
+	return cacheLife(profile);
+}
+/**
+* @deprecated Use `cacheTag` instead. `unstable_cacheTag` was stabilized
+* upstream and the `unstable_`-prefixed name will be removed in a future
+* version of Next.js. Kept as a delegating alias for parity.
+*
+* Emits a one-time deprecation warning via `console.error` (matching Next.js),
+* then delegates to `cacheTag`.
+*
+* Ported from Next.js: packages/next/cache.js
+* https://github.com/vercel/next.js/blob/canary/packages/next/cache.js
+*
+* Asserted by Next.js test:
+* test/e2e/app-dir/cache-components-errors/cache-components-unstable-deprecations.test.ts
+*/
+let _unstableCacheTagWarned = false;
+function unstable_cacheTag(...tags) {
+	if (!_unstableCacheTagWarned) {
+		_unstableCacheTagWarned = true;
+		console.error(/* @__PURE__ */ new Error("`unstable_cacheTag` was recently stabilized and should be imported as `cacheTag`. The `unstable` prefixed form will be removed in a future version of Next.js."));
+	}
+	return cacheTag(...tags);
+}
+/**
+* AsyncLocalStorage to track whether we're inside an unstable_cache() callback.
+* Stored on globalThis via Symbol so headers.ts can detect the scope without
+* a direct import (avoiding circular dependencies).
+*/
+const _unstableCacheAls = getOrCreateAls("vinext.unstableCache.als");
+function serializeUnstableCacheResult(value) {
+	return JSON.stringify(value === void 0 ? { undef: true } : { v: value });
+}
+function deserializeUnstableCacheResult(body) {
+	const wrapper = JSON.parse(body);
+	return "undef" in wrapper ? void 0 : wrapper.v;
+}
+function tryDeserializeUnstableCacheResult(body) {
+	try {
+		return {
+			ok: true,
+			value: deserializeUnstableCacheResult(body)
+		};
+	} catch {
+		return { ok: false };
+	}
+}
+/**
+* Check if the current execution context is inside an unstable_cache() callback.
+* Used by headers(), cookies(), and connection() to throw errors when
+* dynamic request APIs are called inside a cache scope.
+*/
+function isInsideUnstableCacheScope() {
+	return _unstableCacheAls.getStore() === true;
+}
+const _UNSTABLE_CACHE_PENDING_REVALIDATIONS_KEY = Symbol.for("vinext.unstableCache.pendingRevalidations");
+function getPendingUnstableCacheRevalidations() {
+	const existing = _g[_UNSTABLE_CACHE_PENDING_REVALIDATIONS_KEY];
+	if (existing instanceof Map) return existing;
+	const pending = /* @__PURE__ */ new Map();
+	_g[_UNSTABLE_CACHE_PENDING_REVALIDATIONS_KEY] = pending;
+	return pending;
+}
+function waitUntilUnstableCacheRevalidation(promise) {
+	if (!isInsideUnifiedScope()) return;
+	getRequestContext().executionContext?.waitUntil(promise);
+}
+function scheduleUnstableCacheBackgroundRevalidation(cacheKey, refresh) {
+	const pending = getPendingUnstableCacheRevalidations();
+	if (pending.has(cacheKey)) return;
+	const trackedRevalidation = refresh().then(() => void 0).catch((err) => {
+		console.error(`[vinext] unstable_cache background revalidation failed for ${cacheKey}:`, err);
+	}).finally(() => {
+		if (pending.get(cacheKey) === trackedRevalidation) pending.delete(cacheKey);
+	});
+	pending.set(cacheKey, trackedRevalidation);
+	waitUntilUnstableCacheRevalidation(trackedRevalidation);
+}
+async function refreshUnstableCacheResult(fn, args, cacheKey, tags, revalidateSeconds) {
+	const result = await _unstableCacheAls.run(true, () => fn(...args));
+	const cacheValue = {
+		kind: "FETCH",
+		data: {
+			headers: {},
+			body: serializeUnstableCacheResult(result),
+			url: cacheKey
+		},
+		tags,
+		revalidate: typeof revalidateSeconds === "number" ? revalidateSeconds : false
+	};
+	await getDataCacheHandler().set(cacheKey, cacheValue, {
+		fetchCache: true,
+		tags,
+		revalidate: revalidateSeconds
+	});
+	return result;
+}
+/**
+* Wrap an async function with caching.
+*
+* Returns a new function that caches results. The cache key is derived
+* from keyParts + serialized arguments.
+*/
+function unstable_cache(fn, keyParts, options) {
+	const baseKey = keyParts ? keyParts.join(":") : fnv1a64(fn.toString());
+	const tags = encodeCacheTags(options?.tags ?? []);
+	const revalidateSeconds = options?.revalidate;
+	const cachedFn = async (...args) => {
+		const cacheKey = `unstable_cache:${baseKey}:${JSON.stringify(args)}`;
+		recordUnstableCacheObservation({
+			kind: "unstable_cache",
+			keyHash: fnv1a64(cacheKey),
+			revalidate: typeof revalidateSeconds === "number" ? revalidateSeconds : revalidateSeconds === false ? false : null,
+			tagCount: tags.length,
+			tagHash: tags.length > 0 ? fnv1a64(JSON.stringify(tags)) : null
+		});
+		const existing = await getDataCacheHandler().get(cacheKey, {
+			kind: "FETCH",
+			tags
+		});
+		if (existing?.value && existing.value.kind === "FETCH") {
+			const cached = tryDeserializeUnstableCacheResult(existing.value.data.body);
+			if (cached.ok) if (existing.cacheState === "stale") {
+				if (shouldServeStaleUnstableCacheEntry()) {
+					scheduleUnstableCacheBackgroundRevalidation(cacheKey, () => refreshUnstableCacheResult(fn, args, cacheKey, tags, revalidateSeconds));
+					return cached.value;
+				}
+			} else return cached.value;
+		}
+		return await refreshUnstableCacheResult(fn, args, cacheKey, tags, revalidateSeconds);
+	};
+	return cachedFn;
+}
+//#endregion
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, MemoryCacheHandler, NoOpCacheHandler, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, recordUnstableCacheObservation, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, 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-handler.js";
+
+//#region src/shims/cdn-cache.d.ts
+/** A map of response header name -> value the adapter wants applied or removed. */
+type CdnResponseHeaders = Record<string, string | null>;
+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 policy. Returns a map so an
+   * adapter can emit more than one header (e.g. `Cache-Control` +
+   * `CDN-Cache-Control`) and remove stale adapter-owned headers with `null`.
+   */
+  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-handler.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

@@ -0,0 +1,13 @@
+//#region src/shims/client-hook-error.d.ts
+/**
+ * Shared error helper for client-only hooks called in Server Components.
+ *
+ * Used by `.react-server.ts` shim variants to provide a clear, actionable
+ * error message when a developer forgets the "use client" directive.
+ *
+ * @see https://github.com/cloudflare/vinext/issues/834
+ */
+declare function buildClientHookErrorMessage(hookName: string): string;
+declare function throwClientHookError(hookName: string): never;
+//#endregion
+export { buildClientHookErrorMessage, throwClientHookError };

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

@@ -0,0 +1,17 @@
+//#region src/shims/client-hook-error.ts
+/**
+* Shared error helper for client-only hooks called in Server Components.
+*
+* Used by `.react-server.ts` shim variants to provide a clear, actionable
+* error message when a developer forgets the "use client" directive.
+*
+* @see https://github.com/cloudflare/vinext/issues/834
+*/
+function buildClientHookErrorMessage(hookName) {
+	return `${hookName} only works in Client Components. Add the "use client" directive at the top of the file to use it. Read more: https://nextjs.org/docs/messages/react-client-hook-in-server-component`;
+}
+function throwClientHookError(hookName) {
+	throw new Error(buildClientHookErrorMessage(hookName));
+}
+//#endregion
+export { buildClientHookErrorMessage, throwClientHookError };

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

@@ -0,0 +1,14 @@
+import { DomainLocale } from "../utils/domain-locale.js";
+
+//#region src/shims/client-locale.d.ts
+declare function getCurrentBrowserLocale({
+  basePath,
+  domainLocales,
+  hostname
+}: {
+  basePath: string;
+  domainLocales: readonly DomainLocale[] | undefined;
+  hostname: string | null | undefined;
+}): string | undefined;
+//#endregion
+export { getCurrentBrowserLocale };