vinext 1.3.1 → 1.4.1

package/dist/shims/cache-runtime.js

@@ -1,6 +1,7 @@
 import { getOrCreateAls } from "./internal/als-registry.js";
 import { getRequestContext, isInsideUnifiedScope, runWithUnifiedStateMutation } from "./unified-request-context.js";
 import { VINEXT_RSC_MARKER_HEADER } from "../server/headers.js";
+import { isInsideWorkStoreScope } from "./internal/work-store-scope.js";
 import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 import { isRouteCacheabilityProbe, recordRouteCacheabilityProbeBailout } from "./cacheability-classification.js";
 import { shareIsolatePromise } from "../server/isolate-shared-promise.js";
@@ -11,7 +12,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";
@@ -189,22 +190,46 @@ async function serializeCacheResult(result, rsc) {
 		throw serializationError?.value ?? error;
 	}
 }
+const CACHE_LIFE_FIELDS = [
+	"stale",
+	"revalidate",
+	"expire"
+];
+/** Per field, the smallest value any config sets. */
+function minimumCacheLife(configs) {
+	const result = {};
+	for (const config of configs) for (const field of CACHE_LIFE_FIELDS) {
+		const value = config[field];
+		const current = result[field];
+		if (value !== void 0 && (current === void 0 || value < current)) result[field] = value;
+	}
+	return result;
+}
 /**
-* Resolve collected cacheLife configs into a single effective config.
-* The "minimum-wins" rule: if multiple cacheLife() calls are made,
-* each field takes the smallest value across all calls.
+* Resolve a cache scope's effective life, like Next.js's `collectResult`
+* (use-cache-wrapper.ts). A field set by `cacheLife()` takes the minimum
+* across those calls and wins over nested caches. Any other field takes the
+* minimum of the default profile and the nested caches' lives.
 */
-function resolveCacheLife(configs) {
-	if (configs.length === 0) return { ...cacheLifeProfiles.default };
-	if (configs.length === 1) return { ...configs[0] };
+function resolveCacheLife(ctx) {
+	const explicit = minimumCacheLife(ctx.lifeConfigs);
+	const collected = minimumCacheLife([cacheLifeProfiles.default, ...ctx.nestedLifeConfigs]);
 	const result = {};
-	for (const config of configs) {
-		if (config.stale !== void 0) result.stale = result.stale !== void 0 ? Math.min(result.stale, config.stale) : config.stale;
-		if (config.revalidate !== void 0) result.revalidate = result.revalidate !== void 0 ? Math.min(result.revalidate, config.revalidate) : config.revalidate;
-		if (config.expire !== void 0) result.expire = result.expire !== void 0 ? Math.min(result.expire, config.expire) : config.expire;
+	for (const field of CACHE_LIFE_FIELDS) {
+		const value = explicit[field] ?? collected[field];
+		if (value !== void 0) result[field] = value;
 	}
 	return result;
 }
+/**
+* Hand a finished cache scope's life to what encloses it, like Next.js's
+* `propagateCacheEntryMetadata`: an enclosing cache collects it as a nested
+* life, and only an outermost cache reaches the request.
+*/
+function propagateCacheLife(parentCtx, life) {
+	if (parentCtx) parentCtx.nestedLifeConfigs.push(life);
+	else _setRequestScopedCacheLife(life);
+}
 const _PRIVATE_FALLBACK_KEY = Symbol.for("vinext.cacheRuntime.privateFallback");
 const _g = globalThis;
 const _privateAls = getOrCreateAls("vinext.cacheRuntime.privateAls");
@@ -389,7 +414,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 +423,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,13 +437,11 @@ 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) {
-					recordRequestScopedCacheLife(effectiveLife);
-					propagateCacheTagsToRequest(ctx.tags);
-				}
+				if (propagate) propagateCacheTagsToRequest(ctx.tags);
 				const revalidateSeconds = effectiveLife.revalidate ?? cacheLifeProfiles.default.revalidate ?? 900;
 				if (collectedResult?.cacheEntry) try {
 					let cacheFunctionInvocation;
@@ -442,6 +467,7 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 					const cacheContext = {
 						fetchCache: true,
 						tags: ctx.tags,
+						timestamp,
 						...cacheFunctionInvocation ? { cacheFunctionInvocation } : {},
 						cacheControl: {
 							revalidate: revalidateSeconds,
@@ -449,25 +475,39 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 							stale: effectiveLife.stale
 						}
 					};
+					let write;
 					if (rootParamNames && rootParamNames.size > 0 && rootParams) {
 						const specificCacheKey = coarseCacheKey + computeRootParamsCacheKeySuffix(rootParams, rootParamNames);
 						const redirectTags = [...ctx.tags, ...[...rootParamNames].map((name) => ROOT_PARAM_TAG_PREFIX + name)];
-						await handler.set(coarseCacheKey, {
-							kind: "FETCH",
-							data: {
-								headers: { [ROOT_PARAM_REDIRECT_HEADER]: "1" },
-								body: "",
-								url: coarseCacheKey
-							},
-							tags: redirectTags,
-							revalidate: revalidateSeconds
-						}, {
+						try {
+							await handler.set(coarseCacheKey, {
+								kind: "FETCH",
+								data: {
+									headers: { [ROOT_PARAM_REDIRECT_HEADER]: "1" },
+									body: "",
+									url: coarseCacheKey
+								},
+								tags: redirectTags,
+								revalidate: revalidateSeconds
+							}, {
+								...cacheContext,
+								tags: redirectTags,
+								...coarseCacheKey === cacheKey ? staleEntry && { staleEntry } : staleRedirect && { staleEntry: staleRedirect }
+							});
+						} catch {}
+						cacheValue.data.url = specificCacheKey;
+						write = handler.set(specificCacheKey, cacheValue, {
 							...cacheContext,
-							tags: redirectTags
+							...staleEntry && specificCacheKey === cacheKey ? { staleEntry } : {}
 						});
-						cacheValue.data.url = specificCacheKey;
-						await handler.set(specificCacheKey, cacheValue, cacheContext);
-					} else await handler.set(cacheKey, cacheValue, cacheContext);
+					} else write = handler.set(cacheKey, cacheValue, {
+						...cacheContext,
+						...staleEntry ? { staleEntry } : {}
+					});
+					const stored = write.then(() => void 0, () => {});
+					if (propagate && isInsideWorkStoreScope()) {
+						if (isInsideUnifiedScope()) getRequestContext().executionContext?.waitUntil(stored);
+					} else await stored;
 				} catch {}
 				return collectedResult ? collectedResult.result : result;
 			};
@@ -476,10 +516,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));
@@ -525,16 +568,12 @@ function recordRequestScopedCacheControl(cacheControl) {
 		stale: cacheControl.stale
 	};
 	const parentCtx = cacheContextStorage.getStore();
-	parentCtx?.lifeConfigs.push(life);
+	propagateCacheLife(parentCtx, life);
 	if (parentCtx && parentCtx.variant !== "private" && (cacheControl.revalidate === 0 || cacheControl.expire !== void 0 && cacheControl.expire < DYNAMIC_EXPIRE)) {
 		const error = new NestedDynamicUseCacheError();
 		if (typeof Error.captureStackTrace === "function") Error.captureStackTrace(error, recordRequestScopedCacheControl);
 		parentCtx.dynamicNestedCacheError ??= error;
 	}
-	_setRequestScopedCacheLife(life);
-}
-function recordRequestScopedCacheLife(cacheLife) {
-	_setRequestScopedCacheLife(cacheLife);
 }
 /**
 * Bubble a `"use cache"` scope's tags toward where they can drive invalidation.
@@ -561,8 +600,7 @@ function propagateCacheTagsToRequest(tags) {
 	addCollectedRequestTags(tags);
 }
 async function executeWithContext(fn, args, variant, rsc) {
-	const { result, ctx: _ctx, effectiveLife, collectedResult } = await runCachedFunctionWithContext(fn, args, variant, (value) => serializeCacheResult(value, rsc));
-	recordRequestScopedCacheLife(effectiveLife);
+	const { result, collectedResult } = await runCachedFunctionWithContext(fn, args, variant, (value) => serializeCacheResult(value, rsc));
 	return {
 		result: collectedResult ? collectedResult.result : result,
 		cacheable: collectedResult?.cacheEntry !== null,
@@ -579,6 +617,7 @@ async function runCachedFunctionWithContext(fn, args, variant, collectResult) {
 	const ctx = {
 		tags: [],
 		lifeConfigs: [],
+		nestedLifeConfigs: [],
 		variant: variant || "default",
 		readRootParamNames: /* @__PURE__ */ new Set(),
 		hasExplicitRevalidate: false,
@@ -588,19 +627,26 @@ 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;
-	}));
+	let result;
+	let effectiveLife;
+	try {
+		result = await workUnitAsyncStorage.run({ type: workUnitType }, () => cacheContextStorage.run(ctx, async () => {
+			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;
+		}));
+	} finally {
+		effectiveLife = resolveCacheLife(ctx);
+		propagateCacheLife(parentCtx, effectiveLife);
+		if (parentCtx && eagerError && (effectiveLife.revalidate === 0 || effectiveLife.expire !== void 0 && effectiveLife.expire < DYNAMIC_EXPIRE)) parentCtx.dynamicNestedCacheError ??= eagerError;
+	}
 	if (ctx.invalidDynamicUsageError) throw ctx.invalidDynamicUsageError;
-	const effectiveLife = resolveCacheLife(ctx.lifeConfigs);
 	if (parentCtx) {
-		parentCtx.lifeConfigs.push(effectiveLife);
 		for (const tag of ctx.tags) if (!parentCtx.tags.includes(tag)) parentCtx.tags.push(tag);
 		if (parentCtx.variant !== "private") for (const name of ctx.readRootParamNames ?? []) parentCtx.readRootParamNames?.add(name);
 	}
-	if (parentCtx && eagerError && (effectiveLife.revalidate === 0 || effectiveLife.expire !== void 0 && effectiveLife.expire < DYNAMIC_EXPIRE)) parentCtx.dynamicNestedCacheError ??= eagerError;
 	if (typeof process !== "undefined" && (process.env.VINEXT_PRERENDER === "1" || process.env.NODE_ENV === "development") && ctx.dynamicNestedCacheError) {
 		if (effectiveLife.revalidate === 0 && !ctx.hasExplicitRevalidate) throw new Error(getNestedCacheZeroRevalidateErrorMessage(), { cause: ctx.dynamicNestedCacheError });
 		if (effectiveLife.expire !== void 0 && effectiveLife.expire < DYNAMIC_EXPIRE && !ctx.hasExplicitExpire) throw new Error(getNestedCacheShortExpireErrorMessage(), { cause: ctx.dynamicNestedCacheError });

package/dist/shims/cache.d.ts

@@ -1,7 +1,8 @@
+import { CacheLifeConfig } from "../utils/cache-life-profiles.js";
 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, 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 +62,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;
 /**
@@ -100,12 +102,16 @@ export declare function unstable_io(): Promise<void>;
 /**
  * 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.
+ * Accepts either a profile name (a built-in like "hours", or one configured
+ * in next.config `cacheLife`) or a custom configuration object; an unknown
+ * profile name throws, like Next.js. 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.
+ * duration for each field wins. Like Next.js, only the fields a call sets are
+ * explicit: the others resolve from the default profile and any nested caches
+ * (see `resolveCacheLife` in cache-runtime.ts).
  *
  * When called outside a "use cache" context, this is a validated no-op.
  */
@@ -142,4 +148,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, type 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();
 }
 /**
@@ -228,29 +230,34 @@ 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.
+* Accepts either a profile name (a built-in like "hours", or one configured
+* in next.config `cacheLife`) or a custom configuration object; an unknown
+* profile name throws, like Next.js. 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.
+* duration for each field wins. Like Next.js, only the fields a call sets are
+* explicit: the others resolve from the default profile and any nested caches
+* (see `resolveCacheLife` in cache-runtime.ts).
 *
 * 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;
+		const configuredProfile = Object.hasOwn(cacheLifeProfiles, profile) ? cacheLifeProfiles[profile] : void 0;
+		if (configuredProfile === void 0) {
+			if (Object.hasOwn(cacheLifeProfiles, profile.trim())) throw new Error(`Unknown \`cacheLife()\` profile "${profile}" is not configured in next.config.js\nDid you mean "${profile.trim()}" without the spaces?`);
+			throw new Error(`Unknown \`cacheLife()\` profile "${profile}" is not configured in next.config.js\nmodule.exports = {
+  cacheLife: {
+    "${profile}": ...\n  }
+}`);
 		}
-		resolvedConfig = { ...cacheLifeProfiles[profile] };
+		resolvedConfig = { ...configuredProfile };
 	} 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
-		};
+		resolvedConfig = { ...profile };
 	} else return;
 	try {
 		const ctx = getRegisteredCacheContext();
@@ -258,11 +265,13 @@ function cacheLife(profile) {
 			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);
+	_setRequestScopedCacheLife(typeof profile === "string" ? resolvedConfig : {
+		...cacheLifeProfiles.default,
+		...profile
+	});
 }
 /**
 * Tag a "use cache" function's cached result for on-demand revalidation.
@@ -325,7 +334,7 @@ function unstable_cacheTag(...tags) {
 	}
 	return cacheTag(...tags);
 }
-const UNSTABLE_CACHE_KEY_PREFIX = "unstable_cache:v2";
+const UNSTABLE_CACHE_KEY_PREFIX = "unstable_cache:v3";
 /**
 * AsyncLocalStorage to track whether we're inside an unstable_cache() callback.
 * Stored on globalThis via Symbol so headers.ts can detect the scope without
@@ -394,7 +403,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, deferWrite) {
 	const argsUnchanged = serializeArgsOrNull(args) === keyedArgs;
 	const result = await _unstableCacheAls.run(true, () => _unstableCacheCallbackAls.run({ useCacheContext: _useCacheContextAls.getStore() }, () => fn(...args)));
 	if (!argsUnchanged) return result;
@@ -408,11 +417,18 @@ async function refreshUnstableCacheResult(fn, args, keyedArgs, cacheKey, tags, r
 		tags,
 		revalidate: typeof revalidateSeconds === "number" ? revalidateSeconds : false
 	};
-	await getDataCacheHandler().set(cacheKey, cacheValue, {
-		fetchCache: true,
-		tags,
-		revalidate: revalidateSeconds
+	const write = new Promise((resolve) => {
+		resolve(getDataCacheHandler().set(cacheKey, cacheValue, {
+			fetchCache: true,
+			tags,
+			revalidate: revalidateSeconds,
+			...staleEntry ? { staleEntry } : {}
+		}));
+	}).catch((err) => {
+		console.error("[vinext] unstable_cache write error:", err);
 	});
+	if (deferWrite) getRequestExecutionContext()?.waitUntil(write);
+	else await write;
 	return result;
 }
 function serializeArgsOrNull(args) {
@@ -439,16 +455,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 +467,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, false));
 							return cached.value;
 						}
 					} else return cached.value;
@@ -468,9 +479,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, !staleEntry && isInsideWorkStoreScope());
 	};
 	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-hook-error.d.ts

@@ -9,4 +9,6 @@
  */
 export declare function buildClientHookErrorMessage(hookName: string): string;
 export declare function throwClientHookError(hookName: string): never;
+/** Rewrites that TypeError into the actionable message, like Next.js's formatServerError. */
+export declare function rewriteClientHookError(error: Error): void;
 //#endregion

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

@@ -13,5 +13,20 @@ function buildClientHookErrorMessage(hookName) {
 function throwClientHookError(hookName) {
 	throw new Error(buildClientHookErrorMessage(hookName));
 }
+const clientHookPattern = /\b(useState|useEffect|useReducer|useRef|useContext|useLayoutEffect|useInsertionEffect|useSyncExternalStore|useTransition|useImperativeHandle|useDeferredValue|useActionState|useOptimistic|useEffectEvent)\b.*is not a function/;
+/** Rewrites that TypeError into the actionable message, like Next.js's formatServerError. */
+function rewriteClientHookError(error) {
+	const match = error.message.match(clientHookPattern);
+	if (!match) return;
+	const message = buildClientHookErrorMessage(match[1]);
+	try {
+		if (error.stack) {
+			const lines = error.stack.split("\n");
+			lines[0] = message;
+			error.stack = lines.join("\n");
+		}
+		error.message = message;
+	} catch {}
+}
 //#endregion
-export { buildClientHookErrorMessage, throwClientHookError };
+export { buildClientHookErrorMessage, rewriteClientHookError, throwClientHookError };

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
 /**