vinext 1.3.1 → 1.4.0

package/dist/shims/cache-runtime.js

@@ -11,7 +11,7 @@ import { createPprFallbackShellSuspensePromise, trackPprFallbackShellCacheTask }
 import { createUseCacheAccessError, markDynamicUsage, recordInvalidDynamicUsageError } from "./internal/headers-state.js";
 import { isDraftModeEnabled } from "./headers.js";
 import { _registerCacheContextAccessor } from "./internal/cache-context-accessor.js";
-import { _hasPendingRevalidatedTag, _setRequestScopedCacheLife, cacheLifeProfiles, runWithDetachedCacheObservations, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
+import { _hasPendingRevalidatedTag, _isOnDemandRevalidate, _setRequestScopedCacheLife, cacheLifeProfiles, runWithDetachedCacheObservations, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
 import "./fetch-cache.js";
 import { hasUseCacheLayoutMarker, hasUseCachePageMarker, isUseCacheFunctionReference, withoutUseCacheSegmentMarker } from "./internal/app-page-props-cache-key.js";
 import { isWellKnownProperty } from "./internal/thenable-well-known-properties.js";
@@ -389,7 +389,7 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 			if (knownRootParamNames && rootParams) cacheKey += computeRootParamsCacheKeySuffix(rootParams, knownRootParamNames);
 			const softTags = getCurrentFetchSoftTags();
 			let existing = null;
-			if (!_hasPendingRevalidatedTag(softTags)) try {
+			if (!_hasPendingRevalidatedTag(softTags) && !_isOnDemandRevalidate()) try {
 				existing = await handler.get(cacheKey, {
 					kind: "FETCH",
 					softTags
@@ -398,8 +398,10 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 				console.error("[vinext] use cache: handler.get failed; treating as a cache miss:", error);
 			}
 			const redirectValue = existing?.value;
+			let staleRedirect;
 			if (isRootParamRedirect(existing) && isServableCacheState(existing?.cacheState) && rootParams && redirectValue?.kind === "FETCH" && !_hasPendingRevalidatedTag([...redirectValue.tags ?? [], ...softTags])) {
 				cacheKey = coarseCacheKey + computeRootParamsCacheKeySuffix(rootParams, addKnownRootParamNames(id, rootParamNamesFromTags(redirectValue.tags)));
+				if (existing?.cacheState) staleRedirect = existing;
 				try {
 					existing = await handler.get(cacheKey, {
 						kind: "FETCH",
@@ -410,7 +412,8 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 					existing = null;
 				}
 			}
-			const generate = async (propagate) => {
+			const generate = async (propagate, staleEntry) => {
+				const timestamp = Date.now();
 				const { result, ctx, effectiveLife, collectedResult } = await runCachedFunctionWithContext(callFn, callArgs, cacheVariant, (value) => serializeCacheResult(value, rsc));
 				const rootParamNames = ctx.readRootParamNames && ctx.readRootParamNames.size > 0 ? addKnownRootParamNames(id, ctx.readRootParamNames) : knownRootParamsByFunctionId.get(id);
 				if (propagate) {
@@ -442,6 +445,7 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 					const cacheContext = {
 						fetchCache: true,
 						tags: ctx.tags,
+						timestamp,
 						...cacheFunctionInvocation ? { cacheFunctionInvocation } : {},
 						cacheControl: {
 							revalidate: revalidateSeconds,
@@ -463,11 +467,18 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 							revalidate: revalidateSeconds
 						}, {
 							...cacheContext,
-							tags: redirectTags
+							tags: redirectTags,
+							...coarseCacheKey === cacheKey ? staleEntry && { staleEntry } : staleRedirect && { staleEntry: staleRedirect }
 						});
 						cacheValue.data.url = specificCacheKey;
-						await handler.set(specificCacheKey, cacheValue, cacheContext);
-					} else await handler.set(cacheKey, cacheValue, cacheContext);
+						await handler.set(specificCacheKey, cacheValue, {
+							...cacheContext,
+							...staleEntry && specificCacheKey === cacheKey ? { staleEntry } : {}
+						});
+					} else await handler.set(cacheKey, cacheValue, {
+						...cacheContext,
+						...staleEntry ? { staleEntry } : {}
+					});
 				} catch {}
 				return collectedResult ? collectedResult.result : result;
 			};
@@ -476,10 +487,13 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 				propagateCacheTagsToRequest(existing.value.tags);
 				const result = await rsc.createFromReadableStream(uint8ToStream(base64ToUint8(existing.value.data.body)), {}, { preserveServerReferences: true });
 				recordRequestScopedCacheControl(existing.cacheControl);
-				if (existing.cacheState === "stale") regenerateInBackground(id, () => generate(false));
+				if (existing.cacheState === "stale") {
+					const staleEntry = existing;
+					regenerateInBackground(id, () => generate(false, staleEntry));
+				}
 				return result;
 			} catch {}
-			return generate(true);
+			return generate(true, existing?.cacheState ? existing : void 0);
 		}, cacheVariant);
 	};
 	const cachedFn = memoizeInCacheScope((...args) => invoke(args));
@@ -589,9 +603,11 @@ async function runCachedFunctionWithContext(fn, args, variant, collectResult) {
 	let collectedResult;
 	const workUnitType = variant === "private" ? "private-cache" : "cache";
 	const result = await workUnitAsyncStorage.run({ type: workUnitType }, () => cacheContextStorage.run(ctx, async () => {
-		const value = await fn(...args);
-		if (collectResult) collectedResult = await collectResult(value, ctx);
-		return value;
+		if (!collectResult) return await fn(...args);
+		let value;
+		const lazyValue = { then: (onFulfilled, onRejected) => (value ??= new Promise((resolve) => resolve(fn(...args)))).then(onFulfilled, onRejected) };
+		collectedResult = await collectResult(lazyValue, ctx);
+		return await lazyValue;
 	}));
 	if (ctx.invalidDynamicUsageError) throw ctx.invalidDynamicUsageError;
 	const effectiveLife = resolveCacheLife(ctx.lifeConfigs);

package/dist/shims/cache.d.ts

@@ -1,7 +1,7 @@
 import { ExecutionContextLike, getRequestExecutionContext, runWithExecutionContext } from "./request-context.js";
-import { _recordUseCacheRootParamRead, _registerCacheContextAccessor, getRegisteredCacheContext } from "./internal/cache-context-accessor.js";
-import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheLifeSink, CacheState, PendingCdnTagInvalidation, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingCdnTagInvalidation, _queuePendingRevalidation, _revalidateCdnTags, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, markActionRevalidation, recordUnstableCacheObservation, runWithDetachedCacheObservations, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
 import { CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, registerDataCacheHandler, registerLazyDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
+import { _recordUseCacheRootParamRead, _registerCacheContextAccessor, getRegisteredCacheContext } from "./internal/cache-context-accessor.js";
+import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheState, PendingCdnTagInvalidation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _isOnDemandRevalidate, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _queuePendingCdnTagInvalidation, _queuePendingRevalidation, _revalidateCdnTags, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, markActionRevalidation, runWithDetachedCacheObservations, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
 //#region src/shims/cache.d.ts
 /**
  * Revalidate cached data associated with a specific cache tag.
@@ -61,10 +61,11 @@ export declare function updateTag(tag: string): undefined;
 /**
  * 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.
+ * Without Cache Components this marks the render dynamic, so the page is not
+ * stored. With Cache Components it does nothing, as in Next.js: its prerenders
+ * ignore it, and on a request it doesn't make the page dynamic, so the page
+ * stays static and cacheable.
+ * Source: https://github.com/vercel/next.js/blob/canary/packages/next/src/server/web/spec-extension/unstable-no-store.ts
  */
 export declare function unstable_noStore(): void;
 /**
@@ -142,4 +143,4 @@ type UnstableCacheOptions = {
  */
 export declare function unstable_cache<T extends (...args: any[]) => Promise<any>>(fn: T, keyParts?: string[], options?: UnstableCacheOptions): T;
 //#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CacheLifeConfig, CacheLifeSink, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, PendingCdnTagInvalidation, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingCdnTagInvalidation, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _revalidateCdnTags, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, markActionRevalidation, unstable_noStore as noStore, recordUnstableCacheObservation, registerDataCacheHandler, registerLazyDataCacheHandler, runWithDetachedCacheObservations, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CacheLifeConfig, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, PendingCdnTagInvalidation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _isOnDemandRevalidate, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _queuePendingCdnTagInvalidation, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _revalidateCdnTags, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, markActionRevalidation, unstable_noStore as noStore, registerDataCacheHandler, registerLazyDataCacheHandler, runWithDetachedCacheObservations, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry };

package/dist/shims/cache.js

@@ -6,13 +6,13 @@ import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 import { isStagedCacheabilityProbeActive } from "./cacheability-classification.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 { fnv1a64, sha256Hex } from "../utils/hash.js";
+import { sha256Hex } from "../utils/hash.js";
 import { addCollectedRequestTags, getCurrentFetchSoftTags, runWithDetachedFetchObservations } from "./fetch-cache-state.js";
 import { makeHangingPromise } from "./internal/make-hanging-promise.js";
 import { getHeadersAccessPhase, markDynamicUsage } from "./internal/headers-state.js";
 import { isDraftModeEnabled } from "./headers.js";
 import { _recordUseCacheRootParamRead, _registerCacheContextAccessor, getRegisteredCacheContext } from "./internal/cache-context-accessor.js";
-import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingCdnTagInvalidation, _queuePendingRevalidation, _revalidateCdnTags, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, markActionRevalidation, recordUnstableCacheObservation, runWithDetachedCacheObservations, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
+import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _isOnDemandRevalidate, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _queuePendingCdnTagInvalidation, _queuePendingRevalidation, _revalidateCdnTags, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, markActionRevalidation, runWithDetachedCacheObservations, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
 import { isPathKnownNotEdgeCached } from "./cdn-purge-routes.js";
 //#region src/shims/cache.ts
 /**
@@ -154,13 +154,15 @@ function updateTag(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.
+* Without Cache Components this marks the render dynamic, so the page is not
+* stored. With Cache Components it does nothing, as in Next.js: its prerenders
+* ignore it, and on a request it doesn't make the page dynamic, so the page
+* stays static and cacheable.
+* Source: https://github.com/vercel/next.js/blob/canary/packages/next/src/server/web/spec-extension/unstable-no-store.ts
 */
 function unstable_noStore() {
 	if (isInsideUnstableCacheScope()) return;
+	if (String(process.env.__NEXT_CACHE_COMPONENTS) === "true") return;
 	markDynamicUsage();
 }
 /**
@@ -394,7 +396,7 @@ function scheduleUnstableCacheBackgroundRevalidation(cacheKey, refresh) {
 	pending.set(cacheKey, trackedRevalidation);
 	waitUntilUnstableCacheRevalidation(trackedRevalidation);
 }
-async function refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, revalidateSeconds) {
+async function refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, revalidateSeconds, staleEntry) {
 	const argsUnchanged = serializeArgsOrNull(args) === keyedArgs;
 	const result = await _unstableCacheAls.run(true, () => _unstableCacheCallbackAls.run({ useCacheContext: _useCacheContextAls.getStore() }, () => fn(...args)));
 	if (!argsUnchanged) return result;
@@ -411,7 +413,8 @@ async function refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, r
 	await getDataCacheHandler().set(cacheKey, cacheValue, {
 		fetchCache: true,
 		tags,
-		revalidate: revalidateSeconds
+		revalidate: revalidateSeconds,
+		...staleEntry ? { staleEntry } : {}
 	});
 	return result;
 }
@@ -439,16 +442,10 @@ function unstable_cache(fn, keyParts, options) {
 		const keyedArgs = JSON.stringify(args);
 		const invocationKey = `${fixedKey}${keyedArgs}`;
 		addCollectedRequestTags(tags);
-		recordUnstableCacheObservation({
-			kind: "unstable_cache",
-			keyHash: fnv1a64(invocationKey),
-			revalidate: typeof revalidateSeconds === "number" ? revalidateSeconds : revalidateSeconds === false ? false : null,
-			tagCount: tags.length,
-			tagHash: tags.length > 0 ? fnv1a64(JSON.stringify(tags)) : null
-		});
 		const cacheKey = `${UNSTABLE_CACHE_KEY_PREFIX}:${await sha256Hex(invocationKey)}`;
 		const isDraftMode = isDraftModeEnabled();
-		if (!isDraftMode && !isNestedUnstableCacheCall()) {
+		let staleEntry;
+		if (!isDraftMode && !isNestedUnstableCacheCall() && !_isOnDemandRevalidate()) {
 			const softTags = getCurrentFetchSoftTags();
 			const existing = _hasPendingRevalidatedTag([...tags, ...softTags]) ? null : await getDataCacheHandler().get(cacheKey, {
 				kind: "FETCH",
@@ -457,10 +454,11 @@ function unstable_cache(fn, keyParts, options) {
 			});
 			if (existing?.value && existing.value.kind === "FETCH") {
 				const cached = tryDeserializeUnstableCacheResult(existing.value.data.body);
+				if (existing.cacheState === "stale") staleEntry = existing;
 				if (cached.ok) {
 					if (existing.cacheState === "stale") {
 						if (shouldServeStaleUnstableCacheEntry()) {
-							scheduleUnstableCacheBackgroundRevalidation(cacheKey, () => refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, revalidateSeconds));
+							scheduleUnstableCacheBackgroundRevalidation(cacheKey, () => refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, revalidateSeconds, staleEntry));
 							return cached.value;
 						}
 					} else return cached.value;
@@ -468,9 +466,9 @@ function unstable_cache(fn, keyParts, options) {
 			}
 		}
 		if (isDraftMode) return await _unstableCacheAls.run(true, () => fn(...args));
-		return await refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, revalidateSeconds);
+		return await refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, revalidateSeconds, staleEntry);
 	};
 	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, _queuePendingCdnTagInvalidation, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _revalidateCdnTags, _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, runWithDetachedCacheObservations, 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, _isOnDemandRevalidate, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _queuePendingCdnTagInvalidation, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _revalidateCdnTags, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, refresh, registerDataCacheHandler, registerLazyDataCacheHandler, revalidatePath, revalidateTag, runWithDetachedCacheObservations, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };

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

@@ -17,6 +17,8 @@ export type RouteCacheabilityOutcome = {
    */
   status?: number;
   headers?: Readonly<Record<string, string>>;
+  /** App pages: the client-router stale time from the completed render's cacheLife. */
+  staleTimeSeconds?: number;
   tags?: readonly string[];
 };
 export type RouteCacheabilityState = {

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

@@ -32,6 +32,12 @@ export type CdnCacheableHeaderInput = {
    */
   tags?: readonly string[];
 };
+/** A page's document, rendered from an RSC request's payload. */
+export type CdnAppPageDocument = {
+  html: string;
+  /** The renderer's own `Link` header. */
+  linkHeader?: string;
+};
 export type CdnResponsePolicy = {
   /** Whether a provider-specific response header controls shared caching. */
   isHeader(name: string): boolean;
@@ -76,12 +82,15 @@ export type CdnCacheAdapter = {
    */
   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.
+   * This adapter's response-stage transport keys shared 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 host-free identity, and
+   * a page's query-free one, safe. `"query-free"` also drops the user query
+   * from App page identities; `"host-free"` keeps every dispatch's query, for
+   * a transport whose cache keys the dispatched query itself.
    */
-  readonly responseStageCacheIdentity?: "query-free";
+  readonly responseStageCacheIdentity?: "host-free" | "query-free";
   /**
    * Optionally return a foreground page response while completed-response
    * admission continues on an independent body branch. Returning `null` keeps
@@ -90,6 +99,14 @@ export type CdnCacheAdapter = {
   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;
+  /**
+   * Store the page's document beside an RSC request's completed response, as
+   * Next.js keeps a page's document and RSC payload in one entry. Returns the
+   * callback admission calls with the document the render rendered from its
+   * payload, or with `null` when the page has no document to store, or
+   * `undefined` when this render's response stores no document.
+   */
+  captureAppPageDocument?(): ((document: CdnAppPageDocument | null) => void) | undefined;
   /**
    * Whether this adapter sends the 304 for a Pages render whose If-None-Match
    * matches. When it does, the render returns the page, so an adapter that

package/dist/shims/client-page-root.js

@@ -1,10 +1,10 @@
 "use client";
 import { searchParamsToRecord } from "../utils/query.js";
 import { getNavigationContext } from "./navigation-context-state.js";
+import { getClientNavigationRenderContext, useSearchParams } from "./navigation.js";
 import "./navigation-server.js";
-import { isOwnPropertyCheck, isWellKnownProperty } from "./internal/thenable-well-known-properties.js";
 import { RenderedSearchContext } from "./slot.js";
-import { getClientNavigationRenderContext, useSearchParams } from "./navigation.js";
+import { isOwnPropertyCheck, isWellKnownProperty } from "./internal/thenable-well-known-properties.js";
 import { createElement, use, useMemo } from "react";
 //#region src/shims/client-page-root.tsx
 /**

package/dist/shims/dynamic.js

@@ -89,9 +89,11 @@ function createElementWithProps(Component, props) {
 }
 /**
 * Lightweight error boundary that renders the loading component with the error
-* when a dynamic() loader rejects. Without this, loader failures would propagate
-* uncaught through React's rendering — this preserves the Next.js behavior where
-* the `loading` component can display errors.
+* when a dynamic() loader rejects, as the Pages Router's react-loadable does by
+* passing `error` to `loading`. App Router trees never get it: Next.js's App
+* Router next/dynamic is React.lazy inside Suspense with no boundary of its own,
+* so loader and render errors reach the nearest error.tsx.
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/lazy-dynamic/loadable.tsx
 *
 * Lazily created because React.Component is not available in the RSC environment
 * (server components use a slimmed-down React that doesn't include class components).
@@ -202,6 +204,7 @@ function dynamic(dynamicInput, options) {
 		}
 		const InitialLazyComponent = createLazyComponent(loader);
 		const ClientSSRFalse = (props) => {
+			const isAppRouterTree = useIsAppRouterTree();
 			const [mounted, setMounted] = React.useState(false);
 			const { LazyComponent, retry, retryKey } = useRetryableLazyComponent(loader, InitialLazyComponent);
 			React.useEffect(() => setMounted(true), []);
@@ -209,7 +212,7 @@ function dynamic(dynamicInput, options) {
 			const fallback = LoadingComponent ? React.createElement(LoadingComponent, createDynamicLoadingProps({ retry })) : null;
 			const lazyElement = createElementWithProps(LazyComponent, props);
 			let content = lazyElement;
-			if (LoadingComponent) {
+			if (LoadingComponent && !isAppRouterTree) {
 				const ErrorBoundary = getDynamicErrorBoundary();
 				if (ErrorBoundary) content = React.createElement(ErrorBoundary, {
 					fallback: LoadingComponent,
@@ -237,7 +240,7 @@ function dynamic(dynamicInput, options) {
 			const fallback = LoadingComponent ? React.createElement(LoadingComponent, createDynamicLoadingProps()) : null;
 			const lazyElement = createElementWithProps(LazyServer, props);
 			let content = lazyElement;
-			if (LoadingComponent) {
+			if (LoadingComponent && !isAppRouterTree) {
 				const ErrorBoundary = getDynamicErrorBoundary();
 				if (ErrorBoundary) content = React.createElement(ErrorBoundary, {
 					fallback: LoadingComponent,
@@ -257,7 +260,7 @@ function dynamic(dynamicInput, options) {
 		const fallback = LoadingComponent ? React.createElement(LoadingComponent, createDynamicLoadingProps({ retry })) : null;
 		const lazyElement = createElementWithProps(LazyComponent, props);
 		let content = lazyElement;
-		if (LoadingComponent) {
+		if (LoadingComponent && !isAppRouterTree) {
 			const ErrorBoundary = getDynamicErrorBoundary();
 			if (ErrorBoundary) content = React.createElement(ErrorBoundary, {
 				fallback: LoadingComponent,

package/dist/shims/error-boundary.js

@@ -1,11 +1,11 @@
 "use client";
 import { isNavigationSignalError } from "../utils/navigation-signal.js";
+import { handleAppNavigationFailure } from "../client/app-nav-failure-handler.js";
+import { VINEXT_DEV_ERROR_RECOVERY_EVENT } from "../utils/dev-error-recovery-event.js";
 import { decodeRedirectError, forbidden, isRedirectError, notFound, unauthorized } from "./navigation-errors.js";
 import "./navigation-server.js";
 import { isRedirectToCurrentUrl, useErrorBoundaryPathname, useErrorBoundaryRouter } from "./error-boundary-navigation.js";
 import DefaultGlobalError from "./default-global-error.js";
-import { handleAppNavigationFailure } from "../client/app-nav-failure-handler.js";
-import { VINEXT_DEV_ERROR_RECOVERY_EVENT } from "../utils/dev-error-recovery-event.js";
 import { consumeCaughtNotFoundBoundary, useCaughtNotFoundBoundary } from "./caught-not-found-boundaries.js";
 import React from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";

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

@@ -11,12 +11,16 @@ export type FetchDedupeEntry = {
   response: Response | null;
 };
 export type FetchCacheState = {
-  cacheableFetchUrls: Set<string>;
   currentRequestTags: string[];
   currentFetchSoftTags: string[];
   currentFetchCacheMode: FetchCacheMode | null;
   currentFetchRevalidate: number | null;
   currentForceDynamicFetchDefault: boolean;
+  /**
+   * Pages Router preview/draft render. App Router draft state is read from the
+   * headers context instead; Pages renders don't have one.
+   */
+  isDraftMode: boolean;
   dynamicFetchUrls: Set<string>;
   refreshStaleFetchesInForeground: boolean;
   isFetchDedupeActive: boolean;

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

@@ -11,12 +11,12 @@ const _FALLBACK_KEY = Symbol.for("vinext.fetchCache.fallback");
 const fetchCacheAls = getOrCreateAls("vinext.fetchCache.als");
 function createFetchCacheState() {
 	return {
-		cacheableFetchUrls: /* @__PURE__ */ new Set(),
 		currentRequestTags: [],
 		currentFetchSoftTags: [],
 		currentFetchCacheMode: null,
 		currentFetchRevalidate: null,
 		currentForceDynamicFetchDefault: false,
+		isDraftMode: false,
 		dynamicFetchUrls: /* @__PURE__ */ new Set(),
 		refreshStaleFetchesInForeground: false,
 		isFetchDedupeActive: false,
@@ -77,13 +77,11 @@ function getCurrentFetchSoftTags() {
 */
 function runWithDetachedFetchObservations(fn) {
 	if (isInsideUnifiedScope()) return runWithUnifiedStateMutation((uCtx) => {
-		uCtx.cacheableFetchUrls = /* @__PURE__ */ new Set();
 		uCtx.currentRequestTags = [];
 		uCtx.dynamicFetchUrls = /* @__PURE__ */ new Set();
 	}, fn);
 	return fetchCacheAls.run({
 		...getFetchCacheState(),
-		cacheableFetchUrls: /* @__PURE__ */ new Set(),
 		currentRequestTags: [],
 		dynamicFetchUrls: /* @__PURE__ */ new Set()
 	}, fn);

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

@@ -11,7 +11,6 @@ declare global {
 }
 /** @internal Reset dedup state — exposed for test isolation only. */
 export declare function _resetPendingRefetches(): void;
-export declare function peekCacheableFetchObservations(): string[];
 export declare function peekDynamicFetchObservations(): string[];
 export declare function consumeDynamicFetchObservations(): string[];
 /**
@@ -31,6 +30,8 @@ export declare function setCurrentFetchSoftTags(tags: string[]): void;
 export declare function setCurrentFetchCacheMode(mode: FetchCacheMode | null): void;
 export declare function setCurrentFetchRevalidate(revalidate: number | null): void;
 export declare function setCurrentForceDynamicFetchDefault(enabled: boolean): void;
+/** Mark the current Pages Router render as a preview/draft render. */
+export declare function setCurrentFetchDraftMode(enabled: boolean): void;
 export declare function setRefreshStaleFetchesInForeground(enabled: boolean): void;
 /**
  * Install the patched fetch and reset per-request tag state.

package/dist/shims/fetch-cache.js

@@ -6,8 +6,8 @@ import { sha256Hex } from "../utils/hash.js";
 import { traceAppFetch } from "../server/app-fetch-tracing.js";
 import { addCollectedRequestTags, fallbackFetchCacheState, fetchCacheAls, getCurrentFetchSoftTags, getFetchCacheState, resetFallbackFetchCacheState, runWithDetachedFetchObservations } from "./fetch-cache-state.js";
 import { isInsideAnyCacheScope, markDynamicUsage } from "./internal/headers-state.js";
-import { getHeadersContext } from "./headers.js";
-import { _hasPendingRevalidatedTag, _setRequestScopedCacheLife } from "./cache-request-state.js";
+import { getHeadersContext, isDraftModeEnabled } from "./headers.js";
+import { _hasPendingRevalidatedTag, _isOnDemandRevalidate, _setRequestScopedCacheLife } from "./cache-request-state.js";
 import { Buffer } from "node:buffer";
 //#region src/shims/fetch-cache.ts
 /**
@@ -463,9 +463,6 @@ function markUncachedFetchForPageOutput(input) {
 	if (getHeadersContext()?.forceStatic !== true) getFetchCacheState().currentFetchRevalidate = 0;
 	markDynamicUsage();
 }
-function recordCacheableFetchObservation(input) {
-	getFetchCacheState().cacheableFetchUrls.add(getFetchObservationUrl(input));
-}
 function recordFiniteFetchRevalidate(revalidateSeconds) {
 	if (Number.isFinite(revalidateSeconds) && revalidateSeconds > 0) _setRequestScopedCacheLife({ revalidate: revalidateSeconds });
 }
@@ -503,7 +500,8 @@ async function writeFetchCacheResponse(handler, cacheKey, response, tags, revali
 	await handler.set(cacheKey, cacheValue, {
 		fetchCache: true,
 		tags,
-		revalidate: revalidateSeconds
+		revalidate: revalidateSeconds,
+		...options?.staleEntry ? { staleEntry: options.staleEntry } : {}
 	});
 }
 async function lowerFetchCacheRevalidateIfNeeded(handler, cacheKey, cachedValue, tags, revalidateSeconds) {
@@ -520,9 +518,6 @@ async function lowerFetchCacheRevalidateIfNeeded(handler, cacheKey, cachedValue,
 		revalidate: revalidateSeconds
 	});
 }
-function peekCacheableFetchObservations() {
-	return [...getFetchCacheState().cacheableFetchUrls].sort();
-}
 function peekDynamicFetchObservations() {
 	return [...getFetchCacheState().dynamicFetchUrls].sort();
 }
@@ -559,6 +554,10 @@ function setCurrentFetchRevalidate(revalidate) {
 function setCurrentForceDynamicFetchDefault(enabled) {
 	getFetchCacheState().currentForceDynamicFetchDefault = enabled;
 }
+/** Mark the current Pages Router render as a preview/draft render. */
+function setCurrentFetchDraftMode(enabled) {
+	getFetchCacheState().isDraftMode = enabled;
+}
 function setRefreshStaleFetchesInForeground(enabled) {
 	getFetchCacheState().refreshStaleFetchesInForeground = enabled;
 }
@@ -705,8 +704,12 @@ function dedupeFetch(input, init) {
 */
 function createPatchedFetch() {
 	const patchedFetch = async function patchedFetch(input, init, span) {
-		const nextOpts = init?.next;
 		const state = getFetchCacheState();
+		if (state.isDraftMode || isDraftModeEnabled()) {
+			recordDynamicFetchObservation(input);
+			return dedupeFetch(input, init);
+		}
+		const nextOpts = init?.next;
 		const fetchIdx = isInsideUnifiedScope() || fetchCacheAls.getStore() !== void 0 || fallbackFetchCacheState.isFetchDedupeActive ? (state.nextFetchId ?? 1) + 1 : void 0;
 		if (fetchIdx !== void 0) state.nextFetchId = fetchIdx;
 		const recordFetchOutcome = (response, cacheStatus, cacheReason) => {
@@ -753,7 +756,6 @@ function createPatchedFetch() {
 			return recordFetchOutcome(await dedupeFetch(input, cleanInit), "skip", "auto no cache");
 		}
 		const cacheReason = fetchCacheMode === "force-cache" || fetchCacheMode === "default-cache" ? `fetchCache = ${fetchCacheMode}` : `revalidate: ${nextOpts?.revalidate === false || cacheDirective === "force-cache" ? 4294967294 : revalidateSeconds}`;
-		recordCacheableFetchObservation(input);
 		if (typeof nextOpts?.revalidate === "number" && nextOpts.revalidate > 0) {
 			lowerCurrentFetchRevalidate(nextOpts.revalidate);
 			recordFiniteFetchRevalidate(nextOpts.revalidate);
@@ -785,8 +787,9 @@ function createPatchedFetch() {
 		}
 		const handler = getDataCacheHandler();
 		let mustBypassPendingRevalidation = _hasPendingRevalidatedTag([...tags, ...softTags]);
+		let staleEntry;
 		try {
-			let cached = mustBypassPendingRevalidation ? null : await handler.get(cacheKey, {
+			let cached = mustBypassPendingRevalidation || _isOnDemandRevalidate() ? null : await handler.get(cacheKey, {
 				kind: "FETCH",
 				tags,
 				softTags,
@@ -806,15 +809,19 @@ function createPatchedFetch() {
 				return recordFetchOutcome(buildCachedFetchResponse(cachedData, input), "hit", cacheReason);
 			}
 			if (cached?.value && cached.value.kind === "FETCH" && cached.cacheState === "stale") {
+				staleEntry = cached;
 				if (shouldRefreshStaleFetchInForeground()) {
 					const freshResponse = await dedupeFetch(input, fetchInit);
-					await writeFetchCacheResponse(handler, cacheKey, freshResponse, tags, revalidateSeconds);
+					await writeFetchCacheResponse(handler, cacheKey, freshResponse, tags, revalidateSeconds, { staleEntry: cached });
 					return recordFetchOutcome(freshResponse, "miss", cacheReason);
 				}
 				const staleData = cached.value.data;
 				if (!pendingRefetches.has(cacheKey)) {
 					const refetchPromise = originalFetch(input, fetchInit).then(async (freshResp) => {
-						await writeFetchCacheResponse(handler, cacheKey, freshResp, tags, revalidateSeconds, { cloneForReturn: false });
+						await writeFetchCacheResponse(handler, cacheKey, freshResp, tags, revalidateSeconds, {
+							cloneForReturn: false,
+							staleEntry: cached
+						});
 					}).catch((err) => {
 						const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
 						console.error(`[vinext] fetch cache background revalidation failed for ${url} (key=${cacheKey.slice(0, 12)}...):`, err);
@@ -835,13 +842,17 @@ function createPatchedFetch() {
 		}
 		const response = await (mustBypassPendingRevalidation ? originalFetch(input, fetchInit) : dedupeFetch(input, fetchInit));
 		const cacheValue = await buildFetchCacheValue(response, tags, revalidateSeconds);
-		if (cacheValue) handler.set(cacheKey, cacheValue, {
-			fetchCache: true,
-			tags,
-			revalidate: revalidateSeconds
-		}).catch((err) => {
-			console.error("[vinext] fetch cache write error:", err);
-		});
+		if (cacheValue) {
+			const write = handler.set(cacheKey, cacheValue, {
+				fetchCache: true,
+				tags,
+				revalidate: revalidateSeconds,
+				...staleEntry ? { staleEntry } : {}
+			}).catch((err) => {
+				console.error("[vinext] fetch cache write error:", err);
+			});
+			getRequestExecutionContext()?.waitUntil(write);
+		}
 		return recordFetchOutcome(response, "miss", cacheReason);
 	};
 	return ((input, init) => {
@@ -894,7 +905,6 @@ function withFetchCache() {
 async function runWithFetchCache(fn) {
 	_ensurePatchInstalled();
 	if (isInsideUnifiedScope()) return await runWithUnifiedStateMutation((uCtx) => {
-		uCtx.cacheableFetchUrls = /* @__PURE__ */ new Set();
 		uCtx.currentRequestTags = [];
 		uCtx.currentFetchSoftTags = [];
 		uCtx.dynamicFetchUrls = /* @__PURE__ */ new Set();
@@ -904,12 +914,12 @@ async function runWithFetchCache(fn) {
 		uCtx.nextFetchId = 1;
 	}, fn);
 	return fetchCacheAls.run({
-		cacheableFetchUrls: /* @__PURE__ */ new Set(),
 		currentRequestTags: [],
 		currentFetchSoftTags: [],
 		currentFetchCacheMode: null,
 		currentFetchRevalidate: null,
 		currentForceDynamicFetchDefault: false,
+		isDraftMode: false,
 		dynamicFetchUrls: /* @__PURE__ */ new Set(),
 		refreshStaleFetchesInForeground: false,
 		isFetchDedupeActive: true,
@@ -950,4 +960,4 @@ function getOriginalFetch() {
 	return originalFetch;
 }
 //#endregion
-export { _resetPendingRefetches, addCollectedRequestTags, consumeDynamicFetchObservations, ensureFetchPatch, getCollectedFetchTags, getCurrentFetchSoftTags, getOriginalFetch, peekCacheableFetchObservations, peekDynamicFetchObservations, runWithDetachedFetchObservations, runWithFetchCache, runWithFetchDedupe, setCurrentFetchCacheMode, setCurrentFetchRevalidate, setCurrentFetchSoftTags, setCurrentForceDynamicFetchDefault, setRefreshStaleFetchesInForeground, withFetchCache };
+export { _resetPendingRefetches, addCollectedRequestTags, consumeDynamicFetchObservations, ensureFetchPatch, getCollectedFetchTags, getCurrentFetchSoftTags, getOriginalFetch, peekDynamicFetchObservations, runWithDetachedFetchObservations, runWithFetchCache, runWithFetchDedupe, setCurrentFetchCacheMode, setCurrentFetchDraftMode, setCurrentFetchRevalidate, setCurrentFetchSoftTags, setCurrentForceDynamicFetchDefault, setRefreshStaleFetchesInForeground, withFetchCache };

package/dist/shims/form.js

@@ -5,10 +5,10 @@ import "../server/headers.js";
 import { assertSafeNavigationUrl } from "./url-safety.js";
 import { APP_RSC_RENDER_MODE_PREFETCH_LOADING_SHELL } from "../server/app-rsc-render-mode.js";
 import { withBasePath } from "./url-utils.js";
-import { AppElementsWire } from "../server/app-elements-wire.js";
-import "../server/app-elements.js";
 import { createRscRequestHeaders, createRscRequestUrl } from "../server/app-rsc-cache-busting.js";
 import { hasAppNavigationRuntime, loadNavigationRuntimeRouteManifest } from "../client/navigation-runtime.js";
+import { AppElementsWire } from "../server/app-elements-wire.js";
+import "../server/app-elements.js";
 import { getMountedSlotsHeader, getPrefetchInterceptionContext, getPrefetchedUrls, hasPrefetchCacheEntryForNavigation, navigateClientSide, prefetchRscResponse } from "./navigation.js";
 import { useMergedRef } from "./use-merged-ref.js";
 import { forwardRef, useActionState, useCallback, useEffect, useRef } from "react";