vinext 1.0.0 → 1.1.0

package/dist/shims/cache-runtime.js

@@ -6,12 +6,16 @@ import { isRouteCacheabilityProbe, recordRouteCacheabilityProbeBailout } from ".
 import { getDataCacheHandler } from "./cache-handler.js";
 import { suppressHangingPromiseAbortRejections } from "./internal/make-hanging-promise.js";
 import { createPprFallbackShellSuspensePromise, trackPprFallbackShellCacheTask } from "./ppr-fallback-shell.js";
-import { isDraftModeEnabled, markDynamicUsage, throwIfInsideCacheScope } from "./headers.js";
-import { _hasPendingRevalidatedTag, _registerCacheContextAccessor, _setRequestScopedCacheLife, cacheLifeProfiles } from "./cache-request-state.js";
-import { addCollectedRequestTags, getCurrentFetchSoftTags } from "./fetch-cache.js";
-import { makeThenableParams } from "./thenable-params.js";
-import { APP_PAGE_USE_CACHE_MARKER, hasUseCachePageMarker, isMarkedAppPagePropsObject, isUseCacheFunctionReference, markAppPagePropsForUseCache } from "./internal/app-page-props-cache-key.js";
+import { markDynamicUsage, throwIfInsideCacheScope } 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 { addCollectedRequestTags, getCurrentFetchSoftTags, runWithDetachedFetchObservations } from "./fetch-cache.js";
+import { hasUseCacheLayoutMarker, hasUseCachePageMarker, isUseCacheFunctionReference, withoutUseCacheSegmentMarker } from "./internal/app-page-props-cache-key.js";
+import { getFallbackParamsSnapshot, makeThenableParams, restoreThenableParams } from "./thenable-params.js";
 import { getCurrentRootParams } from "./root-params.js";
+import { flightArgumentsKey, restoreFlightReply, snapshotFlightReply } from "./cache-flight-arguments.js";
+import { cache } from "react";
 //#region src/shims/cache-runtime.ts
 /**
 * "use cache" runtime
@@ -34,14 +38,17 @@ import { getCurrentRootParams } from "./root-params.js";
 * and all RSC-serializable types — unlike JSON.stringify which silently
 * drops $$typeof Symbols and function values.
 *
-* When RSC APIs are unavailable (e.g. in unit tests), falls back to
-* JSON.stringify/parse with the same stableStringify cache key generation.
-*
 * Cache variants:
 * - "use cache"           — shared cache (default profile)
 * - "use cache: remote"   — shared cache (explicit)
 * - "use cache: private"  — per-request cache (not shared across requests)
 */
+const replayableFunctions = /* @__PURE__ */ new WeakMap();
+function replayCachedFunction(fn, args) {
+	const replay = replayableFunctions.get(fn);
+	if (!replay || args.version !== 1) throw new Error("Invalid cache function arguments");
+	return replay(args);
+}
 /** Threshold below which expire is considered "dynamic" (5 minutes in seconds). */
 const DYNAMIC_EXPIRE = 300;
 /**
@@ -122,16 +129,9 @@ function buildUseCacheKey(id, keySeed, argsKey) {
 	const scopedId = keySeed ? `build:${encodeURIComponent(keySeed)}:${id}` : id;
 	return argsKey === void 0 ? `use-cache:${scopedId}` : `use-cache:${scopedId}:${argsKey}`;
 }
-const NOT_LOADED = Symbol("not-loaded");
-let _rscModule = NOT_LOADED;
-async function getRscModule() {
-	if (_rscModule !== NOT_LOADED) return _rscModule;
-	try {
-		_rscModule = await import("@vitejs/plugin-rsc/react/rsc");
-	} catch {
-		_rscModule = null;
-	}
-	return _rscModule;
+let _rscModule;
+function getRscModule() {
+	return _rscModule ??= import("@vitejs/plugin-rsc/react/rsc");
 }
 /** Collect a ReadableStream<Uint8Array> into a single Uint8Array. */
 async function collectStream(stream) {
@@ -169,55 +169,22 @@ function uint8ToStream(bytes) {
 	} });
 }
 async function serializeCacheResult(result, rsc) {
-	if (rsc) {
-		let serializationError;
-		const [returnStream, savedStream] = rsc.renderToReadableStream(result, { onError(error) {
-			serializationError ??= { value: error };
-		} }).tee();
-		try {
-			const [deserializedResult, bytes] = await Promise.all([rsc.createFromReadableStream(returnStream, {}, { preserveServerReferences: true }), collectStream(savedStream)]);
-			return {
-				result: deserializedResult,
-				cacheEntry: serializationError ? null : {
-					body: uint8ToBase64(bytes),
-					headers: { [VINEXT_RSC_MARKER_HEADER]: "1" }
-				}
-			};
-		} catch (error) {
-			throw serializationError?.value ?? error;
-		}
-	}
-	const body = JSON.stringify(result);
-	return body === void 0 ? null : {
-		result,
-		cacheEntry: {
-			body,
-			headers: {}
-		}
-	};
-}
-/**
-* Convert an encodeReply result (string | FormData) to a cache key string.
-* For FormData (binary args), produces a deterministic SHA-256 hash over
-* the sorted entries. We can't hash `new Response(formData).arrayBuffer()`
-* because multipart boundaries are non-deterministic across serializations.
-*
-* Exported for testing.
-*/
-async function replyToCacheKey(reply) {
-	if (typeof reply === "string") return reply;
-	const entries = [...reply.entries()];
-	const valStr = (v) => typeof v === "string" ? v : v.name;
-	entries.sort((a, b) => a[0].localeCompare(b[0]) || valStr(a[1]).localeCompare(valStr(b[1])));
-	const parts = [];
-	for (const [name, value] of entries) if (typeof value === "string") parts.push(`${name}=s:${value}`);
-	else {
-		const bytes = new Uint8Array(await value.arrayBuffer());
-		parts.push(`${name}=b:${value.type}:${value.size}:${Buffer.from(bytes).toString("base64")}`);
+	let serializationError;
+	const [returnStream, savedStream] = rsc.renderToReadableStream(result, { onError(error) {
+		serializationError ??= { value: error };
+	} }).tee();
+	try {
+		const [deserializedResult, bytes] = await Promise.all([rsc.createFromReadableStream(returnStream, {}, { preserveServerReferences: true }), collectStream(savedStream)]);
+		return {
+			result: deserializedResult,
+			cacheEntry: serializationError ? null : {
+				body: uint8ToBase64(bytes),
+				headers: { [VINEXT_RSC_MARKER_HEADER]: "1" }
+			}
+		};
+	} catch (error) {
+		throw serializationError?.value ?? error;
 	}
-	const payload = new TextEncoder().encode(parts.join("\0"));
-	const hashBuffer = await crypto.subtle.digest("SHA-256", payload);
-	return Buffer.from(new Uint8Array(hashBuffer)).toString("base64url");
 }
 /**
 * Resolve collected cacheLife configs into a single effective config.
@@ -299,6 +266,17 @@ function propagateRootParamNamesToParent(names) {
 	if (!parent || parent.variant === "private") return;
 	for (const name of names) parent.readRootParamNames?.add(name);
 }
+function isServableCacheState(cacheState) {
+	if (cacheState === "expired") return false;
+	if (cacheState !== "stale") return true;
+	return shouldServeStaleUnstableCacheEntry() && process.env.VINEXT_PRERENDER !== "1" && !isRouteCacheabilityProbe();
+}
+function regenerateInBackground(id, regenerate) {
+	const regeneration = runWithDetachedCacheObservations(() => runWithDetachedFetchObservations(() => cacheContextStorage.exit(regenerate))).then(() => void 0, (error) => {
+		console.error(`[vinext] use cache: background regeneration failed for ${id}:`, error);
+	});
+	if (isInsideUnifiedScope()) getRequestContext().executionContext?.waitUntil(regeneration);
+}
 /**
 * Register a function as a cached function. This is called by the Vite
 * transform for each "use cache" function.
@@ -313,7 +291,7 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 	const omitAppPageSearchParams = cacheVariant !== "private";
 	const cacheFunctionId = options.serverReferenceId ? JSON.stringify([id, options.serverReferenceId]) : id;
 	const isDev = typeof process !== "undefined" && process.env.NODE_ENV === "development";
-	const cachedFn = (...args) => {
+	const invoke = (args, replay) => {
 		if (cacheVariant === "private") {
 			const parentCtx = cacheContextStorage.getStore();
 			if (parentCtx && parentCtx.variant !== "private") throwPrivateUseCacheInsidePublicUseCacheError();
@@ -344,40 +322,60 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 			}
 		}
 		return trackPprFallbackShellCacheTask(async () => {
-			const rsc = await getRscModule();
+			const codec = await getRscModule();
+			const clientReferences = codec.createClientTemporaryReferenceSet();
+			const serverReferences = codec.createTemporaryReferenceSet();
+			const rsc = {
+				...codec,
+				renderToReadableStream: (value, options) => codec.renderToReadableStream(value, {
+					...options,
+					temporaryReferences: serverReferences
+				}),
+				createFromReadableStream: (stream, options, context) => codec.createFromReadableStream(stream, {
+					...options,
+					temporaryReferences: clientReferences
+				}, context)
+			};
 			const keySeed = getUseCacheKeySeed();
-			const captures = options.decryptCaptures ? await options.decryptCaptures(args[0]) : void 0;
+			const captures = !replay && options.decryptCaptures ? await options.decryptCaptures(args[0]) : void 0;
 			const hasCaptureEnvelope = captures !== void 0;
-			const pagePropsArgIndex = args.findIndex(hasUseCachePageMarker);
+			const limitedArgs = options.argumentCount === void 0 ? args : hasCaptureEnvelope ? [args[0], ...args.slice(1, 1 + options.argumentCount)] : args.slice(0, options.argumentCount);
+			const pagePropsArgIndex = replay?.pagePropsIndex ?? limitedArgs.findIndex(hasUseCachePageMarker);
+			const layoutPropsArgIndex = replay?.layoutPropsIndex ?? limitedArgs.findIndex(hasUseCacheLayoutMarker);
 			const isPageInvocation = pagePropsArgIndex !== -1;
-			const invocationArgs = isPageInvocation ? replaceArgument(args, pagePropsArgIndex, withoutUseCachePageMarker(args[pagePropsArgIndex])) : args;
-			const admittedArgs = options.argumentCount === void 0 ? invocationArgs : hasCaptureEnvelope ? [invocationArgs[0], ...invocationArgs.slice(1, 1 + options.argumentCount)] : invocationArgs.slice(0, options.argumentCount);
+			const segmentPropsIndex = isPageInvocation ? pagePropsArgIndex : layoutPropsArgIndex;
+			const admittedArgs = segmentPropsIndex !== -1 && !replay ? replaceArgument(limitedArgs, segmentPropsIndex, withoutUseCacheSegmentMarker(limitedArgs[segmentPropsIndex], isPageInvocation)) : limitedArgs;
 			const executionArgs = hasCaptureEnvelope ? [captures, ...admittedArgs.slice(1)] : admittedArgs;
+			const outerParams = !replay && segmentPropsIndex !== -1 ? executionArgs[segmentPropsIndex].params : void 0;
+			const fallbackParams = getFallbackParamsSnapshot(outerParams);
+			const serializationArgs = fallbackParams ? replaceArgument(executionArgs, segmentPropsIndex, {
+				...executionArgs[segmentPropsIndex],
+				params: fallbackParams
+			}) : executionArgs;
 			const pagePropsIndex = omitAppPageSearchParams && isPageInvocation ? pagePropsArgIndex : void 0;
-			const callArgs = pagePropsIndex === void 0 ? executionArgs : withErroringPageSearchParams(executionArgs, pagePropsIndex);
-			let cacheKey;
-			try {
-				const processedArgs = executionArgs.length > 0 ? unwrapThenableObjectArray(executionArgs, {
-					pagePropsIndex,
-					omitMarkedAppPageSearchParams: omitAppPageSearchParams
-				}) : [];
-				if (rsc && executionArgs.length > 0) {
-					const tempRefs = rsc.createClientTemporaryReferenceSet();
-					const encoded = await rsc.encodeReply(processedArgs, { temporaryReferences: tempRefs });
-					cacheKey = buildUseCacheKey(cacheFunctionId, keySeed, await replyToCacheKey(encoded));
-				} else {
-					const argsKey = processedArgs.length > 0 ? stableStringify(processedArgs) : void 0;
-					cacheKey = buildUseCacheKey(cacheFunctionId, keySeed, argsKey);
-				}
-			} catch {
-				return (await executeWithContext(fn, callArgs, cacheVariant)).result;
+			const keyArgs = pagePropsIndex === void 0 ? serializationArgs : toReplayablePageArgs(serializationArgs, pagePropsIndex);
+			const flightArguments = replay ?? await snapshotFlightReply(await rsc.encodeReply(keyArgs, { temporaryReferences: clientReferences }), isPageInvocation ? pagePropsArgIndex : void 0);
+			if (!replay && layoutPropsArgIndex !== -1) flightArguments.layoutPropsIndex = layoutPropsArgIndex;
+			let cacheKey = buildUseCacheKey(cacheFunctionId, keySeed, flightArgumentsKey(flightArguments));
+			let callArgs = await rsc.decodeReply(restoreFlightReply(flightArguments), { temporaryReferences: serverReferences });
+			if (segmentPropsIndex !== -1) {
+				const props = callArgs[segmentPropsIndex];
+				callArgs = replaceArgument(callArgs, segmentPropsIndex, {
+					...props,
+					params: restoreThenableParams(await props.params, outerParams)
+				});
+				if (pagePropsIndex !== void 0) callArgs = withErroringPageSearchParams(callArgs, pagePropsIndex);
 			}
+			if (fallbackParams) return (await executeWithContext(fn, callArgs, cacheVariant, rsc)).result;
 			if (cacheVariant === "private") {
 				const privateCache = _getPrivateState()._privateCache;
 				const privateHit = privateCache.get(cacheKey);
-				if (privateHit !== void 0) return privateHit;
+				if (privateHit !== void 0) {
+					if (privateHit.serialized) return rsc.createFromReadableStream(uint8ToStream(base64ToUint8(privateHit.serialized.body)), {}, { preserveServerReferences: true });
+					return privateHit.result;
+				}
 				const execution = await executeWithContext(fn, callArgs, cacheVariant, rsc);
-				if (execution.cacheable) privateCache.set(cacheKey, execution.result);
+				if (execution.cacheable) privateCache.set(cacheKey, execution);
 				return execution.result;
 			}
 			if (isDev || isDraftModeEnabled()) return (await executeWithContext(fn, callArgs, cacheVariant, rsc)).result;
@@ -397,7 +395,7 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 				console.error("[vinext] use cache: handler.get failed; treating as a cache miss:", error);
 			}
 			const redirectValue = existing?.value;
-			if (isRootParamRedirect(existing) && existing?.cacheState !== "stale" && rootParams && redirectValue?.kind === "FETCH" && !_hasPendingRevalidatedTag([...redirectValue.tags ?? [], ...softTags])) {
+			if (isRootParamRedirect(existing) && isServableCacheState(existing?.cacheState) && rootParams && redirectValue?.kind === "FETCH" && !_hasPendingRevalidatedTag([...redirectValue.tags ?? [], ...softTags])) {
 				cacheKey = coarseCacheKey + computeRootParamsCacheKeySuffix(rootParams, addKnownRootParamNames(id, rootParamNamesFromTags(redirectValue.tags)));
 				try {
 					existing = await handler.get(cacheKey, {
@@ -409,78 +407,80 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 					existing = null;
 				}
 			}
-			if (existing?.value && existing.value.kind === "FETCH" && existing.cacheState !== "stale" && !_hasPendingRevalidatedTag([...existing.value.tags ?? [], ...softTags])) try {
-				propagateRootParamNamesToParent(knownRootParamsByFunctionId.get(id));
-				propagateCacheTagsToRequest(existing.value.tags);
-				if (rsc && existing.value.data.headers["x-vinext-rsc"] === "1") {
-					const stream = uint8ToStream(base64ToUint8(existing.value.data.body));
-					const result = await rsc.createFromReadableStream(stream, {}, { preserveServerReferences: true });
-					recordRequestScopedCacheControl(existing.cacheControl);
-					return result;
+			const generate = async (propagate) => {
+				const { result, ctx, effectiveLife, collectedResult } = await runCachedFunctionWithContext(fn, 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);
 				}
-				const result = JSON.parse(existing.value.data.body);
-				recordRequestScopedCacheControl(existing.cacheControl);
-				return result;
-			} catch {}
-			const { result, ctx, effectiveLife, collectedResult } = await runCachedFunctionWithContext(fn, callArgs, cacheVariant, (value) => serializeCacheResult(value, rsc));
-			const rootParamNames = ctx.readRootParamNames && ctx.readRootParamNames.size > 0 ? addKnownRootParamNames(id, ctx.readRootParamNames) : knownRootParamsByFunctionId.get(id);
-			recordRequestScopedCacheLife(effectiveLife);
-			propagateCacheTagsToRequest(ctx.tags);
-			const revalidateSeconds = effectiveLife.revalidate ?? cacheLifeProfiles.default.revalidate ?? 900;
-			if (collectedResult?.cacheEntry) try {
-				let cacheFunctionInvocation;
-				if (options.serverReferenceId && options.encodeInvocationArgs) try {
-					cacheFunctionInvocation = {
-						encryptedArgs: await options.encodeInvocationArgs(pagePropsIndex === void 0 ? admittedArgs : toReplayablePageArgs(admittedArgs, pagePropsIndex)),
-						referenceId: options.serverReferenceId,
-						rootParams: Object.fromEntries(Object.entries(rootParams ?? {}).filter((entry) => entry[1] !== void 0)),
-						softTags
-					};
-				} catch {}
-				const serialized = collectedResult.cacheEntry;
-				const cacheValue = {
-					kind: "FETCH",
-					data: {
-						headers: serialized.headers,
-						body: serialized.body,
-						url: cacheKey
-					},
-					tags: ctx.tags,
-					revalidate: revalidateSeconds
-				};
-				const cacheContext = {
-					fetchCache: true,
-					tags: ctx.tags,
-					...cacheFunctionInvocation ? { cacheFunctionInvocation } : {},
-					cacheControl: {
-						revalidate: revalidateSeconds,
-						expire: effectiveLife.expire,
-						stale: effectiveLife.stale
-					}
-				};
-				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, {
+				const revalidateSeconds = effectiveLife.revalidate ?? cacheLifeProfiles.default.revalidate ?? 900;
+				if (collectedResult?.cacheEntry) try {
+					let cacheFunctionInvocation;
+					if (options.serverReferenceId && options.encodeInvocation) try {
+						cacheFunctionInvocation = {
+							encryptedArgs: await options.encodeInvocation(flightArguments),
+							referenceId: options.serverReferenceId,
+							rootParams: Object.fromEntries(Object.entries(rootParams ?? {}).filter((entry) => entry[1] !== void 0)),
+							softTags
+						};
+					} catch {}
+					const serialized = collectedResult.cacheEntry;
+					const cacheValue = {
 						kind: "FETCH",
 						data: {
-							headers: { [ROOT_PARAM_REDIRECT_HEADER]: "1" },
-							body: "",
-							url: coarseCacheKey
+							headers: serialized.headers,
+							body: serialized.body,
+							url: cacheKey
 						},
-						tags: redirectTags,
+						tags: ctx.tags,
 						revalidate: revalidateSeconds
-					}, {
-						...cacheContext,
-						tags: redirectTags
-					});
-					cacheValue.data.url = specificCacheKey;
-					await handler.set(specificCacheKey, cacheValue, cacheContext);
-				} else await handler.set(cacheKey, cacheValue, cacheContext);
+					};
+					const cacheContext = {
+						fetchCache: true,
+						tags: ctx.tags,
+						...cacheFunctionInvocation ? { cacheFunctionInvocation } : {},
+						cacheControl: {
+							revalidate: revalidateSeconds,
+							expire: effectiveLife.expire,
+							stale: effectiveLife.stale
+						}
+					};
+					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
+						}, {
+							...cacheContext,
+							tags: redirectTags
+						});
+						cacheValue.data.url = specificCacheKey;
+						await handler.set(specificCacheKey, cacheValue, cacheContext);
+					} else await handler.set(cacheKey, cacheValue, cacheContext);
+				} catch {}
+				return collectedResult ? collectedResult.result : result;
+			};
+			if (existing?.value && existing.value.kind === "FETCH" && existing.value.data.headers["x-vinext-rsc"] === "1" && isServableCacheState(existing.cacheState) && !_hasPendingRevalidatedTag([...existing.value.tags ?? [], ...softTags])) try {
+				propagateRootParamNamesToParent(knownRootParamsByFunctionId.get(id));
+				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));
+				return result;
 			} catch {}
-			return collectedResult ? collectedResult.result : result;
+			return generate(true);
 		}, cacheVariant);
 	};
+	const cachedFn = memoizeInCacheScope((...args) => invoke(args));
+	replayableFunctions.set(cachedFn, (data) => invoke([], data));
 	Object.defineProperty(cachedFn, "length", {
 		value: fn.length,
 		configurable: true
@@ -489,6 +489,11 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 	if (options.acceptsSecondArgument !== void 0) Reflect.set(cachedFn, USE_CACHE_ACCEPTS_SECOND_ARGUMENT_SYMBOL, options.acceptsSecondArgument);
 	return cachedFn;
 }
+/** Memoize in one React render without skipping cache guards or scoped serialization. */
+function memoizeInCacheScope(fn) {
+	const memoized = cache((_parent, _workUnit, _unstable, ...args) => fn(...args));
+	return (...args) => memoized(cacheContextStorage.getStore(), workUnitAsyncStorage.getStore(), unstableCacheContextStorage.getStore() === true, ...args);
+}
 /** @internal Symbol used to identify "use cache" wrapper functions. */
 const USE_CACHE_FUNCTION_SYMBOL = Symbol.for("vinext.useCacheFunction");
 /** @internal Symbol carrying transform-derived cached function argument metadata. */
@@ -553,11 +558,12 @@ function propagateCacheTagsToRequest(tags) {
 	addCollectedRequestTags(tags);
 }
 async function executeWithContext(fn, args, variant, rsc) {
-	const { result, ctx: _ctx, effectiveLife, collectedResult } = await runCachedFunctionWithContext(fn, args, variant, rsc ? (value) => serializeCacheResult(value, rsc) : void 0);
+	const { result, ctx: _ctx, effectiveLife, collectedResult } = await runCachedFunctionWithContext(fn, args, variant, (value) => serializeCacheResult(value, rsc));
 	recordRequestScopedCacheLife(effectiveLife);
 	return {
 		result: collectedResult ? collectedResult.result : result,
-		cacheable: collectedResult?.cacheEntry !== null
+		cacheable: collectedResult?.cacheEntry !== null,
+		serialized: collectedResult?.cacheEntry
 	};
 }
 async function runCachedFunctionWithContext(fn, args, variant, collectResult) {
@@ -603,31 +609,6 @@ async function runCachedFunctionWithContext(fn, args, variant, collectResult) {
 		collectedResult
 	};
 }
-function unwrapThenableObjects(value, options) {
-	if (value === null || value === void 0 || typeof value !== "object") return value;
-	const childOptions = { omitMarkedAppPageSearchParams: options.omitMarkedAppPageSearchParams };
-	if (Array.isArray(value)) return value.map((item) => unwrapThenableObjects(item, childOptions));
-	if (isThenableObject(value)) {
-		const plain = {};
-		for (const key of Object.keys(value)) plain[key] = unwrapThenableObjects(value[key], childOptions);
-		return plain;
-	}
-	if (typeof value.then === "function") return value;
-	const result = {};
-	for (const key of Object.keys(value)) {
-		if (key === "searchParams" && (options.omitAppPageSearchParamsAtRoot || options.omitMarkedAppPageSearchParams && isMarkedAppPagePropsObject(value))) continue;
-		result[key] = unwrapThenableObjects(value[key], childOptions);
-	}
-	return result;
-}
-/**
-* A thenable (not an array) with own enumerable properties — the
-* `Object.assign(Promise.resolve(obj), obj)` pattern Next.js params use. The
-* cache key is built from its fields instead of the promise.
-*/
-function isThenableObject(value) {
-	return !Array.isArray(value) && "then" in value && typeof value.then === "function" && Object.keys(value).length > 0;
-}
 function isPagePropsObject(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -636,26 +617,17 @@ function replaceArgument(args, index, value) {
 	result[index] = value;
 	return result;
 }
-/** Remove the `$$isPage` invocation marker before props reach the key or user code. */
-function withoutUseCachePageMarker(props) {
-	const { [APP_PAGE_USE_CACHE_MARKER]: _marker, ...pageProps } = props;
-	return isMarkedAppPagePropsObject(props) ? markAppPagePropsForUseCache(pageProps) : pageProps;
-}
 /**
 * Response Store replay args for a public page cache: drop `searchParams` from
 * the page props at `index` (after a capture envelope, if any), as Next.js does
-* for the serialized arguments (use-cache-wrapper.ts, `isPageSegmentFunction`),
-* and keep the `$$isPage` marker so a replay regains page semantics, including
-* the erroring searchParams fallback.
+* for the serialized arguments (use-cache-wrapper.ts, `isPageSegmentFunction`).
+* The replay regains page semantics from `CacheFlightArguments.pagePropsIndex`.
 */
 function toReplayablePageArgs(args, index) {
 	const props = args[index];
 	if (!isPagePropsObject(props)) return [...args];
 	const { searchParams: _searchParams, ...pageProps } = props;
-	return replaceArgument(args, index, {
-		...pageProps,
-		[APP_PAGE_USE_CACHE_MARKER]: true
-	});
+	return replaceArgument(args, index, pageProps);
 }
 /**
 * Give page props at `index` without `searchParams` (a Response Store replay of
@@ -671,35 +643,5 @@ function withErroringPageSearchParams(args, index) {
 		searchParams: makeThenableParams({}, { observeParamAccess: () => throwIfInsideCacheScope("searchParams") })
 	});
 }
-function unwrapThenableObjectArray(values, options) {
-	return values.map((value, index) => unwrapThenableObjects(value, {
-		omitAppPageSearchParamsAtRoot: index === options.pagePropsIndex,
-		omitMarkedAppPageSearchParams: options.omitMarkedAppPageSearchParams
-	}));
-}
-function stableStringify(value, seen) {
-	if (value === void 0) return "undefined";
-	if (value === null) return "null";
-	if (typeof value === "function") throw new Error("Cannot serialize function");
-	if (typeof value === "symbol") throw new Error("Cannot serialize symbol");
-	if (Array.isArray(value)) {
-		if (!seen) seen = /* @__PURE__ */ new Set();
-		if (seen.has(value)) throw new Error("Circular reference");
-		seen.add(value);
-		const result = "[" + value.map((v) => stableStringify(v, seen)).join(",") + "]";
-		seen.delete(value);
-		return result;
-	}
-	if (typeof value === "object" && value !== null) {
-		if (value instanceof Date) return `Date(${value.getTime()})`;
-		if (!seen) seen = /* @__PURE__ */ new Set();
-		if (seen.has(value)) throw new Error("Circular reference");
-		seen.add(value);
-		const result = "{" + Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(value[k], seen)}`).join(",") + "}";
-		seen.delete(value);
-		return result;
-	}
-	return JSON.stringify(value);
-}
 //#endregion
-export { NestedDynamicUseCacheError, buildUseCacheKey, cacheContextStorage, clearPrivateCache, getCacheContext, isThenableObject, isUseCacheFunction, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };
+export { NestedDynamicUseCacheError, buildUseCacheKey, cacheContextStorage, clearPrivateCache, getCacheContext, isUseCacheFunction, memoizeInCacheScope, registerCachedFunction, replayCachedFunction, runWithPrivateCache };

package/dist/shims/cache.d.ts

@@ -1,5 +1,6 @@
 import { ExecutionContextLike, getRequestExecutionContext, runWithExecutionContext } from "./request-context.js";
-import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheState, UnstableCacheObservation, UnstableCacheRevalidationMode, _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 { _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, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _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";
 //#region src/shims/cache.d.ts
 /**
@@ -141,4 +142,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, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, markActionRevalidation, unstable_noStore as noStore, recordUnstableCacheObservation, registerDataCacheHandler, registerLazyDataCacheHandler, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry };
+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, UnstableCacheObservation, UnstableCacheRevalidationMode, _captureRequestScopedCacheLifeAccessors, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _recordUseCacheRootParamRead, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, markActionRevalidation, unstable_noStore as noStore, recordUnstableCacheObservation, registerDataCacheHandler, registerLazyDataCacheHandler, runWithDetachedCacheObservations, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry };

package/dist/shims/cache.js

@@ -8,9 +8,11 @@ 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 { 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, _queuePendingRevalidation, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, markActionRevalidation, recordUnstableCacheObservation, runWithDetachedCacheObservations, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
+import { addCollectedRequestTags, getCurrentFetchSoftTags, runWithDetachedFetchObservations } from "./fetch-cache.js";
 //#region src/shims/cache.ts
 /**
 * next/cache shim
@@ -320,6 +322,7 @@ const UNSTABLE_CACHE_KEY_PREFIX = "unstable_cache:v2";
 * a direct import (avoiding circular dependencies).
 */
 const _unstableCacheAls = getOrCreateAls("vinext.unstableCache.als");
+const _useCacheContextAls = getOrCreateAls("vinext.cacheRuntime.contextAls");
 function serializeUnstableCacheResult(value) {
 	return JSON.stringify(value === void 0 ? { undef: true } : { v: value });
 }
@@ -360,7 +363,7 @@ function waitUntilUnstableCacheRevalidation(promise) {
 function scheduleUnstableCacheBackgroundRevalidation(cacheKey, refresh) {
 	const pending = getPendingUnstableCacheRevalidations();
 	if (pending.has(cacheKey)) return;
-	const trackedRevalidation = refresh().then(() => void 0).catch((err) => {
+	const trackedRevalidation = runWithDetachedCacheObservations(() => runWithDetachedFetchObservations(() => _useCacheContextAls.exit(refresh))).then(() => void 0).catch((err) => {
 		console.error(`[vinext] unstable_cache background revalidation failed for ${cacheKey}:`, err);
 	}).finally(() => {
 		if (pending.get(cacheKey) === trackedRevalidation) pending.delete(cacheKey);
@@ -434,4 +437,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, registerDataCacheHandler, registerLazyDataCacheHandler, 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, runWithDetachedCacheObservations, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };

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

@@ -10,6 +10,13 @@ export type RouteCacheabilityOutcome = {
   searchParamsUnread?: true;
   /** A transient classification failure that may succeed on another bounded attempt. */
   retryable?: true;
+  /**
+   * App page RSC: the status and headers that replace the streamed 200 of a
+   * render whose special error rejected its document's shell, once the
+   * response is complete.
+   */
+  status?: number;
+  headers?: Readonly<Record<string, string>>;
   tags?: readonly string[];
 };
 export type RouteCacheabilityState = {
@@ -86,7 +93,7 @@ export declare function markRouteCacheabilityExplicitConfigPolicy(): void;
 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. */
+/** Record an explicit cache policy supplied by the Route Handler itself. */
 export declare function markRouteCacheabilityExplicitResponsePolicy(): void;
 /** Record that the response body reached clean EOF and is now a replay stream. */
 export declare function markRouteCacheabilityResponseBodyComplete(): void;

package/dist/shims/cacheability-classification.js

@@ -84,10 +84,10 @@ function recordConfigCdnCachePolicyHeader(state, name, value) {
 	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. */
+/** Record an explicit cache policy supplied by the Route Handler itself. */
 function markRouteCacheabilityExplicitResponsePolicy() {
 	const state = readRouteCacheabilityState();
-	if (!state || state.mode !== "admit") return;
+	if (!state) return;
 	state.explicitResponseCachePolicy = true;
 }
 /** Record that the response body reached clean EOF and is now a replay stream. */