vinext 1.0.0-beta.9 → 1.0.0

package/dist/shims/cache.js

@@ -1,16 +1,16 @@
 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 { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 import { getCdnCacheAdapter } from "./cdn-cache.js";
+import { isStagedCacheabilityProbeActive } from "./cacheability-classification.js";
 import { fnv1a64 } from "../utils/hash.js";
+import { MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, registerDataCacheHandler, registerLazyDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
 import { encodeCacheTag, encodeCacheTags } from "../utils/encode-cache-tag.js";
 import { makeHangingPromise } from "./internal/make-hanging-promise.js";
 import { getHeadersAccessPhase, isDraftModeEnabled, markDynamicUsage } from "./headers.js";
 import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
 import { addCollectedRequestTags, getCurrentFetchSoftTags } from "./fetch-cache.js";
-import { isStagedCacheabilityProbeActive } from "./cacheability-classification.js";
-import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 //#region src/shims/cache.ts
 /**
 * next/cache shim
@@ -29,8 +29,7 @@ import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 *   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.
+* deprecated for consumers and retained for backwards compatibility.
 */
 const _g = globalThis;
 function scheduleRevalidation(promise) {
@@ -104,7 +103,8 @@ function revalidatePath(path, type) {
 	}
 	markActionRevalidation(1);
 	const stem = path.endsWith("/") ? path.slice(0, -1) : path;
-	const encodedTag = encodeCacheTag(type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`);
+	const tag = type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`;
+	const encodedTag = encodeCacheTag(tag);
 	_markPendingRevalidatedTag(encodedTag);
 	return scheduleRevalidation(_invalidateEncodedTag(encodedTag));
 }
@@ -418,12 +418,14 @@ function unstable_cache(fn, keyParts, options) {
 			});
 			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;
+				if (cached.ok) {
+					if (existing.cacheState === "stale") {
+						if (shouldServeStaleUnstableCacheEntry()) {
+							scheduleUnstableCacheBackgroundRevalidation(cacheKey, () => refreshUnstableCacheResult(fn, args, cacheKey, tags, revalidateSeconds));
+							return cached.value;
+						}
+					} else return cached.value;
+				}
 			}
 		}
 		if (isDraftMode) return await _unstableCacheAls.run(true, () => fn(...args));
@@ -432,4 +434,4 @@ function unstable_cache(fn, keyParts, options) {
 	return cachedFn;
 }
 //#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, MemoryCacheHandler, NoOpCacheHandler, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _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 };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, MemoryCacheHandler, NoOpCacheHandler, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, recordUnstableCacheObservation, refresh, registerDataCacheHandler, registerLazyDataCacheHandler, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };

package/dist/shims/cacheability-classification.d.ts

@@ -1,16 +1,18 @@
 //#region src/shims/cacheability-classification.d.ts
-declare const CACHEABILITY_REQUEST_STATE: unique symbol;
-declare const CACHEABILITY_POLICY_HEADERS: readonly ["cache-control", "cdn-cache-control", "cloudflare-cdn-cache-control"];
-type CacheabilityPolicyHeader = (typeof CACHEABILITY_POLICY_HEADERS)[number];
-type RouteCacheabilityOutcome = {
+export declare const CACHEABILITY_REQUEST_STATE: unique symbol;
+export type RouteCacheabilityOutcome = {
   cacheControl?: string;
   cacheable: boolean;
   classificationFailure?: boolean;
   dynamicUsage?: boolean;
   reason?: string;
+  /** App pages: the render proved it left searchParams unread, so its response holds for every query. */
+  searchParamsUnread?: true;
+  /** A transient classification failure that may succeed on another bounded attempt. */
+  retryable?: true;
   tags?: readonly string[];
 };
-type RouteCacheabilityState = {
+export type RouteCacheabilityState = {
   admission?: {
     manifest?: unknown;
     policy: "deny" | "manifest" | "runtime";
@@ -26,60 +28,79 @@ type RouteCacheabilityState = {
   captureDeadlineAt: number;
   complete?: (outcome: RouteCacheabilityOutcome) => void;
   completion?: Promise<RouteCacheabilityOutcome>;
+  /** Canonical framework tags most recently handed to the active CDN adapter. */
+  cdnCacheTags?: readonly string[];
+  /** Private marker surrounding this render's injected client trace metadata. */
+  clientTraceMetadataMarker?: string;
   completedResponseBody?: boolean;
+  /** Whether admission must translate a completed response through the active adapter. */
+  applyCompletedResponsePolicy?: boolean;
+  /** Core- or adapter-owned cache policy headers set by next.config, by lowercased name. */
+  configCdnCachePolicy?: Map<string, string>;
   explicitConfigCachePolicy?: boolean;
   explicitResponseCachePolicy?: boolean;
   finalResponseVetoReason?: string;
   forcedDynamicReason?: string;
   /** A route-config decision that applies to every concrete identity for this pattern. */
   patternDynamicReason?: string;
-  frameworkResponseCachePolicy?: Partial<Record<CacheabilityPolicyHeader, string>>;
+  frameworkResponseCachePolicy?: Headers;
   mode: "admit" | "identity" | "probe";
   outcome?: RouteCacheabilityOutcome;
   preserveResponseCachePolicy?: boolean;
+  /** Whether an API request carried credentials that must not enter shared caching. */
+  credentialedRequest?: boolean;
   /** Cache-key behavior declared by the active CDN adapter. */
   responseVary?: "verbatim";
+  /** Concrete pathname resolved by the trusted request stage before rendering. */
+  resolvedRoutePathname?: string;
   probeBailout?: {
     kind: "private-cache";
     outcome: RouteCacheabilityOutcome;
   };
   route?: {
-    kind: "app-page" | "app-route" | "pages-page";
+    kind: "app-page" | "app-route" | "pages-api" | "pages-page";
     pattern: string;
   };
 };
+/** Retain canonical tags across completed-response admission and adapter header shaping. */
+export declare function recordRouteCacheabilityCdnTags(tags: readonly string[] | undefined): void;
+/** Retain the exact trace metadata marker for completed shared-response admission. */
+export declare function recordRouteCacheabilityClientTraceMetadataMarker(marker: string): void;
 /** Preserve the existing policy when hybrid routing hands the request to Pages Router. */
-declare function preserveRouteCacheabilityResponsePolicy(): void;
-declare function readRouteCacheabilityState(): RouteCacheabilityState | null;
-declare function beginRouteCacheability(kind: "app-page" | "app-route" | "pages-page", pattern: string): boolean;
+export declare function preserveRouteCacheabilityResponsePolicy(): void;
+export declare function readRouteCacheabilityState(): RouteCacheabilityState | null;
+export declare function beginRouteCacheability(kind: "app-page" | "app-route" | "pages-api" | "pages-page", pattern: string): boolean;
 /** Prevent shared caching when request processing before route dispatch was request-specific. */
-declare function markRouteCacheabilityDynamic(reason: string): void;
+export declare function markRouteCacheabilityDynamic(reason: string): void;
 /** Mark an effective route configuration that makes the whole pattern dynamic. */
-declare function markRouteCacheabilityPatternDynamic(reason: string): void;
+export declare function markRouteCacheabilityPatternDynamic(reason: string): void;
 /** Read a request-specific routing veto without making the route globally dynamic. */
-declare function getRouteCacheabilityDynamicReason(): string | null;
+export declare function getRouteCacheabilityDynamicReason(): string | null;
 /** Reuse the active request's bounded response-capture envelope when available. */
-declare function getRouteCacheabilityCaptureOptions(): Pick<RouteCacheabilityState, "captureBudget" | "captureDeadlineAt"> | null;
+export declare function getRouteCacheabilityCaptureOptions(): Pick<RouteCacheabilityState, "captureBudget" | "captureDeadlineAt"> | null;
 /** Keep a completed response private without treating it as static-to-dynamic. */
-declare function markRouteCacheabilityFinalResponseUncacheable(reason: string): void;
+export declare function markRouteCacheabilityFinalResponseUncacheable(reason: string): void;
 /** Record that next.config explicitly owns the final response cache policy. */
-declare function markRouteCacheabilityExplicitConfigPolicy(): void;
+export declare function markRouteCacheabilityExplicitConfigPolicy(): void;
+/** Record a cache policy header, not just Vary, that a next.config rule set. */
+export declare function markRouteCacheabilityConfigCdnCachePolicy(name: string, value: string): void;
+/** Record a next.config cache policy header with the value a response carries. */
+export declare function recordConfigCdnCachePolicyHeader(state: RouteCacheabilityState, name: string, value: string): void;
 /** Record a public cache policy supplied by the Route Handler itself. */
-declare function markRouteCacheabilityExplicitResponsePolicy(): void;
+export declare function markRouteCacheabilityExplicitResponsePolicy(): void;
 /** Record that the response body reached clean EOF and is now a replay stream. */
-declare function markRouteCacheabilityResponseBodyComplete(): void;
+export declare function markRouteCacheabilityResponseBodyComplete(): void;
 /** Record framework-owned policy so admission can identify policy added later. */
-declare function captureRouteCacheabilityResponsePolicy(headers: Headers): void;
+export declare function captureRouteCacheabilityResponsePolicy(headers: Headers): void;
 /** True only for an authenticated probe that must render the matched App Page. */
-declare function isRouteCacheabilityProbe(): boolean;
+export declare function isRouteCacheabilityProbe(): boolean;
 /** True when the outer Worker must decide cache admission after clean EOF. */
-declare function isRouteCacheabilityEvaluation(): boolean;
+export declare function isRouteCacheabilityEvaluation(): boolean;
 /** True for the authenticated routing pass that must not evaluate user components. */
-declare function isRouteCacheabilityIdentityProbe(): boolean;
+export declare function isRouteCacheabilityIdentityProbe(): boolean;
 /** True for every side-effect-free staged Worker observation request. */
-declare function isStagedCacheabilityProbeActive(): boolean;
-declare function deferRouteCacheability(): ((outcome: RouteCacheabilityOutcome) => void) | null;
-declare function recordRouteCacheability(outcome: RouteCacheabilityOutcome): void;
-declare function recordRouteCacheabilityProbeBailout(kind: "private-cache", outcome: RouteCacheabilityOutcome): void;
-//#endregion
-export { CACHEABILITY_POLICY_HEADERS, CACHEABILITY_REQUEST_STATE, RouteCacheabilityOutcome, RouteCacheabilityState, beginRouteCacheability, captureRouteCacheabilityResponsePolicy, deferRouteCacheability, getRouteCacheabilityCaptureOptions, getRouteCacheabilityDynamicReason, isRouteCacheabilityEvaluation, isRouteCacheabilityIdentityProbe, isRouteCacheabilityProbe, isStagedCacheabilityProbeActive, markRouteCacheabilityDynamic, markRouteCacheabilityExplicitConfigPolicy, markRouteCacheabilityExplicitResponsePolicy, markRouteCacheabilityFinalResponseUncacheable, markRouteCacheabilityPatternDynamic, markRouteCacheabilityResponseBodyComplete, preserveRouteCacheabilityResponsePolicy, readRouteCacheabilityState, recordRouteCacheability, recordRouteCacheabilityProbeBailout };
+export declare function isStagedCacheabilityProbeActive(): boolean;
+export declare function deferRouteCacheability(): ((outcome: RouteCacheabilityOutcome) => void) | null;
+export declare function recordRouteCacheability(outcome: RouteCacheabilityOutcome): void;
+export declare function recordRouteCacheabilityProbeBailout(kind: "private-cache", outcome: RouteCacheabilityOutcome): void;
+//#endregion

package/dist/shims/cacheability-classification.js

@@ -1,11 +1,19 @@
 import { getRequestExecutionContext } from "./request-context.js";
 //#region src/shims/cacheability-classification.ts
 const CACHEABILITY_REQUEST_STATE = Symbol.for("vinext.cacheabilityRequestState");
-const CACHEABILITY_POLICY_HEADERS = [
-	"cache-control",
-	"cdn-cache-control",
-	"cloudflare-cdn-cache-control"
-];
+/** Retain canonical tags across completed-response admission and adapter header shaping. */
+function recordRouteCacheabilityCdnTags(tags) {
+	if (tags === void 0) return;
+	const state = readRouteCacheabilityState();
+	if (state?.mode !== "admit") return;
+	state.cdnCacheTags = [...tags];
+}
+/** Retain the exact trace metadata marker for completed shared-response admission. */
+function recordRouteCacheabilityClientTraceMetadataMarker(marker) {
+	const state = readRouteCacheabilityState();
+	if (state?.mode !== "admit") return;
+	state.clientTraceMetadataMarker = marker;
+}
 /** Preserve the existing policy when hybrid routing hands the request to Pages Router. */
 function preserveRouteCacheabilityResponsePolicy() {
 	const state = readRouteCacheabilityState();
@@ -64,6 +72,18 @@ function markRouteCacheabilityExplicitConfigPolicy() {
 	if (!state) return;
 	state.explicitConfigCachePolicy = true;
 }
+/** Record a cache policy header, not just Vary, that a next.config rule set. */
+function markRouteCacheabilityConfigCdnCachePolicy(name, value) {
+	const state = readRouteCacheabilityState();
+	if (!state) return;
+	recordConfigCdnCachePolicyHeader(state, name, value);
+}
+/** Record a next.config cache policy header with the value a response carries. */
+function recordConfigCdnCachePolicyHeader(state, name, value) {
+	state.explicitConfigCachePolicy = true;
+	const applied = new Headers([[name, value]]).get(name) ?? value;
+	(state.configCdnCachePolicy ??= /* @__PURE__ */ new Map()).set(name.toLowerCase(), applied);
+}
 /** Record a public cache policy supplied by the Route Handler itself. */
 function markRouteCacheabilityExplicitResponsePolicy() {
 	const state = readRouteCacheabilityState();
@@ -80,12 +100,7 @@ function markRouteCacheabilityResponseBodyComplete() {
 function captureRouteCacheabilityResponsePolicy(headers) {
 	const state = readRouteCacheabilityState();
 	if (!state || state.mode !== "admit") return;
-	const policy = {};
-	for (const name of CACHEABILITY_POLICY_HEADERS) {
-		const value = headers.get(name);
-		if (value !== null) policy[name] = value;
-	}
-	state.frameworkResponseCachePolicy = policy;
+	state.frameworkResponseCachePolicy = new Headers(headers);
 }
 /** True only for an authenticated probe that must render the matched App Page. */
 function isRouteCacheabilityProbe() {
@@ -143,4 +158,4 @@ function recordRouteCacheabilityProbeBailout(kind, outcome) {
 	state.complete?.(outcome);
 }
 //#endregion
-export { CACHEABILITY_POLICY_HEADERS, CACHEABILITY_REQUEST_STATE, beginRouteCacheability, captureRouteCacheabilityResponsePolicy, deferRouteCacheability, getRouteCacheabilityCaptureOptions, getRouteCacheabilityDynamicReason, isRouteCacheabilityEvaluation, isRouteCacheabilityIdentityProbe, isRouteCacheabilityProbe, isStagedCacheabilityProbeActive, markRouteCacheabilityDynamic, markRouteCacheabilityExplicitConfigPolicy, markRouteCacheabilityExplicitResponsePolicy, markRouteCacheabilityFinalResponseUncacheable, markRouteCacheabilityPatternDynamic, markRouteCacheabilityResponseBodyComplete, preserveRouteCacheabilityResponsePolicy, readRouteCacheabilityState, recordRouteCacheability, recordRouteCacheabilityProbeBailout };
+export { CACHEABILITY_REQUEST_STATE, beginRouteCacheability, captureRouteCacheabilityResponsePolicy, deferRouteCacheability, getRouteCacheabilityCaptureOptions, getRouteCacheabilityDynamicReason, isRouteCacheabilityEvaluation, isRouteCacheabilityIdentityProbe, isRouteCacheabilityProbe, isStagedCacheabilityProbeActive, markRouteCacheabilityConfigCdnCachePolicy, markRouteCacheabilityDynamic, markRouteCacheabilityExplicitConfigPolicy, markRouteCacheabilityExplicitResponsePolicy, markRouteCacheabilityFinalResponseUncacheable, markRouteCacheabilityPatternDynamic, markRouteCacheabilityResponseBodyComplete, preserveRouteCacheabilityResponsePolicy, readRouteCacheabilityState, recordConfigCdnCachePolicyHeader, recordRouteCacheability, recordRouteCacheabilityCdnTags, recordRouteCacheabilityClientTraceMetadataMarker, recordRouteCacheabilityProbeBailout };

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

@@ -0,0 +1,13 @@
+import { CdnCacheAdapter } from "./cdn-cache.js";
+//#region src/shims/cdn-cache-state.d.ts
+/** Register an adapter without loading the origin cache implementation. */
+export declare function setCdnCacheAdapter(adapter: CdnCacheAdapter): void;
+/**
+ * Lazily keep the first declaratively configured adapter shared across
+ * duplicated stage modules. Failed factories remain retryable so a later
+ * entrypoint with the required runtime bindings can register successfully.
+ */
+export declare function registerCdnCacheAdapter(factory: () => CdnCacheAdapter): void;
+/** Read only an explicitly registered adapter; defaults belong to cdn-cache. */
+export declare function getExplicitCdnCacheAdapter(): CdnCacheAdapter | null;
+//#endregion

package/dist/shims/cdn-cache-state.js

@@ -0,0 +1,23 @@
+//#region src/shims/cdn-cache-state.ts
+const CDN_CACHE_ADAPTER_KEY = Symbol.for("vinext.cdnCacheAdapter");
+const globals = globalThis;
+/** Register an adapter without loading the origin cache implementation. */
+function setCdnCacheAdapter(adapter) {
+	globals[CDN_CACHE_ADAPTER_KEY] = adapter;
+}
+/**
+* Lazily keep the first declaratively configured adapter shared across
+* duplicated stage modules. Failed factories remain retryable so a later
+* entrypoint with the required runtime bindings can register successfully.
+*/
+function registerCdnCacheAdapter(factory) {
+	if (globals[CDN_CACHE_ADAPTER_KEY] !== void 0) return;
+	const adapter = factory();
+	if (globals[CDN_CACHE_ADAPTER_KEY] === void 0) globals[CDN_CACHE_ADAPTER_KEY] = adapter;
+}
+/** Read only an explicitly registered adapter; defaults belong to cdn-cache. */
+function getExplicitCdnCacheAdapter() {
+	return globals[CDN_CACHE_ADAPTER_KEY] ?? null;
+}
+//#endregion
+export { getExplicitCdnCacheAdapter, registerCdnCacheAdapter, setCdnCacheAdapter };

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

@@ -1,8 +1,9 @@
 import { CacheHandlerValue, IncrementalCacheValue } from "./cache-handler.js";
+import { setCdnCacheAdapter } from "./cdn-cache-state.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 = {
+export type CdnResponseHeaders = Record<string, string | null>;
+export 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
@@ -28,18 +29,38 @@ type CdnCacheableHeaderInput = {
    */
   tags?: readonly string[];
 };
+export type CdnResponsePolicy = {
+  /** Whether a provider-specific response header controls shared caching. */
+  isHeader(name: string): boolean;
+  /**
+   * Read the effective shared-cache policy from a response. The returned value
+   * uses Cache-Control syntax so core can apply the framework's cacheability
+   * rules without knowing which provider header carried it.
+   */
+  readCacheControl(headers: Headers): string | null;
+  /**
+   * Name the response header `readCacheControl` interpreted, or `null` when
+   * none did. Core uses it to tell which stage owns the effective policy;
+   * without it, core cannot attribute that policy to next.config.
+   */
+  readCacheControlHeaderName?(headers: Headers): string | null;
+  /** Whether provider policy explicitly opts out of storage. */
+  hasExplicitNonCacheablePolicy(headers: Headers, baseline?: Headers): boolean;
+};
 /** Whether a Cache-Control value contains an exact non-cacheable directive. */
-declare function isNonCacheableCacheControl(cacheControl: string): boolean;
+export declare function isNonCacheableCacheControl(cacheControl: string): boolean;
 /**
  * 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 = {
+export type CdnCacheAdapter = {
   /**
    * The shared cache selects response variants using every request header
    * named by `Vary`, comparing values verbatim.
    */
   readonly responseVary?: "verbatim";
+  /** Provider-specific response-policy interpretation, when the adapter has one. */
+  readonly responsePolicy?: CdnResponsePolicy;
   /**
    * Fresh App Page responses must reach clean EOF before this adapter may emit
    * shared-cache headers. Used by edge adapters whose cache sits in front of
@@ -47,6 +68,21 @@ type CdnCacheAdapter = {
    * the completed artifact.
    */
   readonly requiresCompletedResponseAdmission?: boolean;
+  /**
+   * This adapter's response-stage transport keys shared App page dispatches by
+   * `VinextResponseStageDispatchOptions.cacheIdentity` when core supplies one.
+   * Core supplies it only when completed-response admission is also required,
+   * because that admission is what makes a query-free identity safe.
+   */
+  readonly responseStageCacheIdentity?: "query-free";
+  /**
+   * Optionally return a foreground page response while completed-response
+   * admission continues on an independent body branch. Returning `null` keeps
+   * the normal blocking admission path. API responses are never passed here.
+   */
+  deferCompletedPageResponseAdmission?(response: Response, complete: (response: Response) => Promise<Response>): Response | null;
+  /** Capture the full-route RSC side stream while admitting a completed HTML response. */
+  captureAppPageRscData?(rscData: Promise<ArrayBuffer>): void;
   /**
    * Validate provider-specific request routing before the application handles
    * the request. Returning a response short-circuits the request pipeline;
@@ -85,14 +121,6 @@ type CdnCacheAdapter = {
    * paths that do not pass through cache-policy finalization.
    */
   buildResponseIdentityHeaders?(): CdnResponseHeaders;
-  /**
-   * Whether existing response headers explicitly opt out of storage. Adapters
-   * that split browser and provider cache policy should implement this so they
-   * can interpret the provider-specific headers they own.
-   *
-   * When omitted, core inspects only the generic `Cache-Control` header.
-   */
-  hasExplicitNonCacheableResponsePolicy?(headers: Headers): boolean;
   /**
    * Whether the **origin** runs in-process background regeneration when a stale
    * entry is served. Edge adapters set this to `false` because the CDN
@@ -118,11 +146,14 @@ type CdnCacheAdapter = {
  * response headers alone. Deployments where provider headers carry cache
  * semantics must configure the adapter that owns those headers.
  */
-declare class DefaultCdnCacheAdapter implements CdnCacheAdapter {
+export declare class DefaultCdnCacheAdapter implements CdnCacheAdapter {
+  private readonly buildIdentity?;
   readonly ownsBackgroundRevalidation = true;
+  constructor(buildIdentity?: string | undefined);
   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;
+  buildResponseIdentityHeaders(): CdnResponseHeaders;
   revalidateTag(_tags: string | string[], _durations?: {
     expire?: number;
   }): Promise<void>;
@@ -138,23 +169,21 @@ declare class DefaultCdnCacheAdapter implements CdnCacheAdapter {
  *
  * ```ts
  * import { vinext } from "vinext";
- * import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
+ * import { workersCacheCdnAdapter } from "@vinext/cloudflare/cache/workers-cache-cdn-adapter";
  *
  * export default defineConfig({
- *   plugins: [vinext({ cache: { cdn: cdnAdapter() } })],
+ *   plugins: [vinext({ cache: { cdn: workersCacheCdnAdapter() } })],
  * });
  * ```
  *
  * 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.
+ * don't have to call this from a worker entry. This setter remains for
+ * backwards compatibility, but is not the recommended consumer API.
  */
-declare function setCdnCacheAdapter(adapter: CdnCacheAdapter): void;
 /**
  * Get the active CDN cache adapter. An explicitly configured adapter wins;
  * otherwise the origin-managed {@link DefaultCdnCacheAdapter} is used.
  */
-declare function getCdnCacheAdapter(): CdnCacheAdapter;
+export declare function getCdnCacheAdapter(): CdnCacheAdapter;
 //#endregion
-export { CdnCacheAdapter, CdnCacheableHeaderInput, CdnResponseHeaders, DefaultCdnCacheAdapter, getCdnCacheAdapter, isNonCacheableCacheControl, setCdnCacheAdapter };
+export { setCdnCacheAdapter };

package/dist/shims/cdn-cache.js

@@ -1,31 +1,5 @@
-import { getDataCacheHandler } from "./cache-handler.js";
+import { getExplicitCdnCacheAdapter, setCdnCacheAdapter } from "./cdn-cache-state.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   | Framework cache policy                  | Provider-specific cache policy                         |
-* | 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.
-*/
 /** Whether a Cache-Control value contains an exact non-cacheable directive. */
 function isNonCacheableCacheControl(cacheControl) {
 	let start = 0;
@@ -59,21 +33,28 @@ const PENDING_DYNAMIC_CACHE_CONTROL = "no-store, must-revalidate";
 * semantics must configure the adapter that owns those headers.
 */
 var DefaultCdnCacheAdapter = class {
+	buildIdentity;
 	ownsBackgroundRevalidation = true;
+	constructor(buildIdentity) {
+		this.buildIdentity = buildIdentity;
+	}
 	async get(key, ctx) {
+		const { getDataCacheHandler } = await import("./cache-handler.js");
 		return getDataCacheHandler().get(key, ctx);
 	}
 	async set(key, data, ctx) {
+		const { getDataCacheHandler } = await import("./cache-handler.js");
 		await getDataCacheHandler().set(key, data, ctx);
 	}
 	buildResponseHeaders(input) {
 		if (input.pendingDynamicCheck) return { "Cache-Control": PENDING_DYNAMIC_CACHE_CONTROL };
 		return { "Cache-Control": input.cacheControl };
 	}
+	buildResponseIdentityHeaders() {
+		return this.buildIdentity ? { "X-Vinext-Build-Id": this.buildIdentity } : {};
+	}
 	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
@@ -86,27 +67,23 @@ let _defaultAdapter = null;
 *
 * ```ts
 * import { vinext } from "vinext";
-* import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter";
+* import { workersCacheCdnAdapter } from "@vinext/cloudflare/cache/workers-cache-cdn-adapter";
 *
 * export default defineConfig({
-*   plugins: [vinext({ cache: { cdn: cdnAdapter() } })],
+*   plugins: [vinext({ cache: { cdn: workersCacheCdnAdapter() } })],
 * });
 * ```
 *
 * 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.
+* don't have to call this from a worker entry. This setter remains for
+* backwards compatibility, but is not the recommended consumer API.
 */
-function setCdnCacheAdapter(adapter) {
-	_gCdn[_CDN_KEY] = adapter;
-}
 /**
 * Get the active CDN cache adapter. An explicitly configured adapter wins;
 * otherwise the origin-managed {@link DefaultCdnCacheAdapter} is used.
 */
 function getCdnCacheAdapter() {
-	const active = _gCdn[_CDN_KEY];
+	const active = getExplicitCdnCacheAdapter();
 	if (active) return active;
 	return _defaultAdapter ??= new DefaultCdnCacheAdapter();
 }

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

@@ -7,7 +7,6 @@
  *
  * @see https://github.com/cloudflare/vinext/issues/834
  */
-declare function buildClientHookErrorMessage(hookName: string): string;
-declare function throwClientHookError(hookName: string): never;
-//#endregion
-export { buildClientHookErrorMessage, throwClientHookError };
+export declare function buildClientHookErrorMessage(hookName: string): string;
+export declare function throwClientHookError(hookName: string): never;
+//#endregion

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

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

package/dist/shims/client-page-root.d.ts

@@ -0,0 +1,24 @@
+import { ComponentType } from "react";
+//#region src/shims/client-page-root.d.ts
+type ClientPageSearchParams = Record<string, string | string[]>;
+export type ClientPageRootProps = {
+  Component: ComponentType<Record<string, unknown>>;
+  /** The page's other props (`params`, slot props). Never `searchParams`. */
+  pageProps: Readonly<Record<string, unknown>>;
+  /** The page always reads an empty query: `force-static`, or static export. */
+  emptySearchParams?: boolean;
+};
+/**
+ * Build an untracked `searchParams` promise, like Next.js 15's browser
+ * `makeUntrackedExoticSearchParams`: a settled promise whose query keys are
+ * also readable synchronously, except names Promise and React rely on.
+ *
+ * It matches the SSR thenable (`makeThenableParams`) wherever a page could
+ * tell them apart during hydration, so it is a proxy in the same way: the
+ * query keys are virtual, and the promise's methods run on the promise
+ * itself. As real own properties, a `constructor` key would replace the
+ * promise's species, and `await` would throw.
+ */
+export declare function createClientPageSearchParams(searchParams: URLSearchParams | null | undefined): Promise<ClientPageSearchParams>;
+export declare function ClientPageRoot({ Component, pageProps, emptySearchParams }: ClientPageRootProps): import("react").ReactElement<Record<string, unknown>, string | import("react").JSXElementConstructor<any>>;
+//#endregion