vinext 1.3.1 → 1.4.1

package/dist/shims/navigation.js

@@ -11,24 +11,24 @@ import { resolveDirectHybridClientRouteOwner } from "./internal/hybrid-client-ro
 import { isHashOnlyBrowserUrlChange, toCanonicalBrowserNavigationHref, toSameOriginAppPath, withBasePath } from "./url-utils.js";
 import { disableSmoothScrollDuringRouteTransition } from "./disable-smooth-scroll.js";
 import { retryScrollTo, scrollToHashTarget } from "./hash-scroll.js";
-import { AppElementsWire } from "../server/app-elements-wire.js";
-import "../server/app-elements.js";
-import { GLOBAL_ACCESSORS_KEY, ServerInsertedHTMLContext, _registerStateAccessors, clearClientHydrationContext, clearServerInsertedHTML, flushServerInsertedHTML, getBfcacheIdMapContext, getBfcacheSegmentIdContext, getLayoutSegmentContext, getNavigationContext, registerServerInsertedHTMLCallback, renderServerInsertedHTML, setNavigationContext } from "./navigation-context-state.js";
-import { BailoutToCSRError, DynamicServerError, HTTP_ERROR_FALLBACK_ERROR_CODE, RedirectType, decodeRedirectError, forbidden, getAccessFallbackHTTPStatus, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, notFound, permanentRedirect, redirect, unauthorized, unstable_rethrow } from "./navigation-errors.js";
+import { VINEXT_RSC_COMPATIBILITY_ID_HEADER, VINEXT_RSC_CONTENT_TYPE, createRscRequestHeaders, createRscRequestUrl, formatRscRequestPath, parseRscRequestPath, stripRscCacheBustingSearchParam } from "../server/app-rsc-cache-busting.js";
 import { clearAppNavigationFailureTarget, stageAppNavigationFailureTarget } from "../client/app-nav-failure-handler.js";
-import { beginAppRouterScrollIntent, clearAppRouterScrollIntent, consumeAppRouterScrollIntent, getPendingAppRouterScrollIntent, isLatestAppRouterScrollIntent } from "./app-router-scroll-state.js";
-import { VINEXT_RSC_COMPATIBILITY_ID_HEADER, VINEXT_RSC_CONTENT_TYPE, createRscRequestHeaders, createRscRequestUrl, formatRscRequestPath, parseRscRequestPath, stripRscCacheBustingSearchParam, stripRscSuffix } from "../server/app-rsc-cache-busting.js";
 import { notifyAppRouterTransitionStart } from "../client/instrumentation-client-state.js";
 import { getNavigationRuntime, hasAppNavigationRuntime, loadNavigationRuntimeRouteManifest } from "../client/navigation-runtime.js";
 import { UnrecognizedActionError, unstable_isUnrecognizedActionError } from "./unrecognized-action-error.js";
+import { AppElementsWire } from "../server/app-elements-wire.js";
+import "../server/app-elements.js";
 import { PUBLIC_INITIAL_BFCACHE_ID } from "../server/app-bfcache-id.js";
 import { resolveManifestNavigationInterceptionContext } from "../server/app-browser-interception-context.js";
-import { createExternalHistoryStatePreservingMetadata, createHashOnlyHistoryStatePreservingNavigationMetadata, isAppOwnedHistoryState } from "../server/app-history-state.js";
+import { createExternalHistoryStatePreservingMetadata, createHashOnlyHistoryStatePreservingNavigationMetadata, isAppOwnedHistoryState, readHistoryStateTraversalIndex } from "../server/app-history-state.js";
 import { hasPendingAppRouterPageRedirect } from "../server/app-browser-mpa-navigation.js";
 import { extractRscCompletionMetadata } from "../server/rsc-completion-metadata.js";
 import { navigationPlanner } from "../server/navigation-planner.js";
 import { ReadonlyURLSearchParams } from "./readonly-url-search-params.js";
+import { BailoutToCSRError, DynamicServerError, HTTP_ERROR_FALLBACK_ERROR_CODE, RedirectType, decodeRedirectError, forbidden, getAccessFallbackHTTPStatus, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, notFound, permanentRedirect, redirect, unauthorized, unstable_rethrow } from "./navigation-errors.js";
 import { getPagesNavigationContext } from "./internal/pages-router-accessor.js";
+import { beginAppRouterScrollIntent, clearAppRouterScrollIntent, consumeAppRouterScrollIntent, getPendingAppRouterScrollIntent, isLatestAppRouterScrollIntent } from "./app-router-scroll-state.js";
+import { GLOBAL_ACCESSORS_KEY, ServerInsertedHTMLContext, _registerStateAccessors, clearClientHydrationContext, clearServerInsertedHTML, flushServerInsertedHTML, getBfcacheIdMapContext, getBfcacheSegmentIdContext, getLayoutSegmentContext, getNavigationContext, registerServerInsertedHTMLCallback, renderServerInsertedHTML, setNavigationContext } from "./navigation-context-state.js";
 import { cancelAppPrefetchFetch, promoteAppPrefetchFetch, releaseAppPrefetchFetchSlot, scheduleAppPrefetchFetch } from "./internal/app-prefetch-fetch-queue.js";
 import * as React$1 from "react";
 //#region src/shims/navigation.ts
@@ -245,8 +245,7 @@ function normalizeRscCacheLookupUrl(rscUrl) {
 }
 function normalizeRscCacheLookupPathname(rscUrl) {
 	try {
-		const url = parseRscRequestPath(rscUrl);
-		return stripRscSuffix(url.pathname);
+		return parseRscRequestPath(rscUrl).pathname;
 	} catch {
 		return null;
 	}
@@ -467,9 +466,13 @@ const retainedPrefetchInvalidations = /* @__PURE__ */ new Set();
 function retainPrefetchInvalidationAfterConsume(entry) {
 	const callbacks = entry.onInvalidateCallbacks;
 	if (callbacks === void 0 || callbacks.size === 0) return;
-	const delay = Math.max(0, resolvePrefetchCacheEntryExpiresAt(entry) - Date.now());
+	retainPrefetchInvalidation(callbacks, resolvePrefetchCacheEntryExpiresAt(entry));
+}
+function retainPrefetchInvalidation(callbacks, expiresAt, forVisitedResponse = false) {
+	const delay = Math.max(0, expiresAt - Date.now());
 	const retained = {
 		callbacks,
+		...forVisitedResponse ? { forVisitedResponse: true } : {},
 		timer: setTimeout(() => fireRetainedPrefetchInvalidation(retained), delay)
 	};
 	retainedPrefetchInvalidations.add(retained);
@@ -570,14 +573,37 @@ function attachPrefetchInvalidationCallback(cacheKey, onInvalidate) {
 	if (!entry) return;
 	attachPrefetchInvalidationToEntry(cacheKey, entry, onInvalidate);
 }
-function invalidatePrefetchCache() {
+function invalidatePrefetchCache(options = {}) {
 	cancelPendingPrefetchSetups(null);
 	const cache = getPrefetchCache();
 	const prefetched = getPrefetchedUrls();
 	for (const [cacheKey, entry] of cache) deletePrefetchCacheEntry(cache, prefetched, cacheKey, entry, true);
 	prefetched.clear();
 	for (const retained of retainedPrefetchInvalidations) fireRetainedPrefetchInvalidation(retained);
-	if (!isServer) getNavigationRuntime()?.functions.pingVisibleLinks?.();
+	if (!isServer && options.pingVisibleLinks !== false) getNavigationRuntime()?.functions.pingVisibleLinks?.();
+}
+/**
+* Evict the prefetch entries that may hold dynamic data, for a Server Action
+* that called `refresh()`. Like Next.js's dynamic-only revalidation, which
+* evicts its BFCache but keeps its prefetch cache, this keeps route trees,
+* static prefetches and full prefetches. It drops navigation responses, and
+* automatic prefetches whose page rendered dynamically or hasn't finished
+* rendering, including those only kept to learn a route: Next.js's automatic
+* prefetches never hold dynamic data.
+*/
+function invalidateDynamicPrefetchCache() {
+	const cache = getPrefetchCache();
+	const prefetched = getPrefetchedUrls();
+	const evicted = [];
+	for (const [cacheKey, entry] of cache) if (!(entry.prefetchKind === "route-tree" || entry.prefetchKind !== void 0 && (entry.dynamicStaleTime === "full-prefetch" || entry.snapshot !== void 0 && !isStaleTimeSeconds(entry.snapshot.dynamicStaleTimeSeconds)))) evicted.push([cacheKey, entry]);
+	for (const [cacheKey, entry] of evicted) deletePrefetchCacheEntry(cache, prefetched, cacheKey, entry, true);
+}
+/**
+* Notify the prefetches that stood in for a visited response (see
+* `hasNavigationFreshVisitedResponse`), as the visited responses are cleared.
+*/
+function invalidateVisitedResponsePrefetches() {
+	for (const retained of retainedPrefetchInvalidations) if (retained.forVisitedResponse === true) fireRetainedPrefetchInvalidation(retained);
 }
 /**
 * Prevent completed navigation responses from becoming authoritative again
@@ -593,7 +619,7 @@ function disableNavigationResponsePrefetchCacheReuse() {
 	}
 	if (didDemote && !isServer) getNavigationRuntime()?.functions.pingVisibleLinks?.();
 }
-function seedPrefetchResponseSnapshot(rscUrl, snapshot, interceptionContext = null, mountedSlotsHeader = null, fallbackTtlMs = DYNAMIC_NAVIGATION_CACHE_TTL, reuseAfterHistoryRestore = false) {
+function seedPrefetchResponseSnapshot(rscUrl, snapshot, interceptionContext = null, mountedSlotsHeader = null, fallbackTtlMs = DYNAMIC_NAVIGATION_CACHE_TTL, reuseAfterHistoryRestore = false, expiresAt = resolveCachedRscResponseExpiresAt(Date.now(), snapshot, fallbackTtlMs)) {
 	const cacheKey = AppElementsWire.encodeCacheKey(rscUrl, interceptionContext);
 	const cache = getPrefetchCache();
 	const existing = cache.get(cacheKey);
@@ -602,7 +628,7 @@ function seedPrefetchResponseSnapshot(rscUrl, snapshot, interceptionContext = nu
 	const entry = {
 		cacheForNavigation: true,
 		cacheKeys: /* @__PURE__ */ new Set([cacheKey]),
-		expiresAt: resolveCachedRscResponseExpiresAt(timestamp, snapshot, fallbackTtlMs),
+		expiresAt,
 		mountedSlotsHeader,
 		outcome: "cache-seeded",
 		reuseAfterHistoryRestore,
@@ -616,6 +642,35 @@ function seedPrefetchResponseSnapshot(rscUrl, snapshot, interceptionContext = nu
 	schedulePrefetchInvalidation(cacheKey, entry);
 	evictPrefetchCacheIfNeeded();
 }
+/**
+* Fulfill a full prefetch from the visited response of an earlier navigation,
+* as Next.js does from its BFCache, instead of issuing a request. The data is
+* fresh for the static stale time from the navigation, not the dynamic one
+* (`attemptToFulfillDynamicSegmentFromBFCache`).
+*/
+function seedFullPrefetchFromVisitedResponse(rscUrl, interceptionContext, mountedSlotsHeader, additionalRscUrls = [], onInvalidate) {
+	const visited = getNavigationRuntime()?.functions.readVisitedResponseForFullPrefetch?.([rscUrl, ...additionalRscUrls], interceptionContext, mountedSlotsHeader);
+	if (!visited) return false;
+	const expiresAt = visited.navigatedAt + Math.max(PREFETCH_CACHE_TTL, MIN_PREFETCH_STALE_TIME_MS);
+	if (expiresAt <= Date.now()) return false;
+	seedPrefetchResponseSnapshot(rscUrl, visited.response, interceptionContext, mountedSlotsHeader, void 0, true, expiresAt);
+	const cacheKey = AppElementsWire.encodeCacheKey(rscUrl, interceptionContext);
+	if (getPrefetchCache().get(cacheKey)?.snapshot !== visited.response) return false;
+	attachPrefetchInvalidationCallback(cacheKey, onInvalidate);
+	return true;
+}
+/**
+* Whether a navigation to the URL would reuse the response of an earlier one,
+* so a prefetch has nothing to fetch. Like Next.js, whose navigation keeps the
+* route and its segments for `staleTimes.dynamic`. `onInvalidate` fires when
+* that reuse ends.
+*/
+function hasNavigationFreshVisitedResponse(rscUrl, interceptionContext, mountedSlotsHeader, additionalRscUrls = [], onInvalidate) {
+	const freshUntil = getNavigationRuntime()?.functions.readVisitedResponseForFullPrefetch?.([rscUrl, ...additionalRscUrls], interceptionContext, mountedSlotsHeader)?.navigationFreshUntil;
+	if (freshUntil === void 0 || freshUntil === null) return false;
+	if (onInvalidate !== void 0) retainPrefetchInvalidation(/* @__PURE__ */ new Set([onInvalidate]), freshUntil, true);
+	return true;
+}
 function deletePrefetchResponseSnapshot(rscUrl, snapshot, interceptionContext = null) {
 	const cacheKey = AppElementsWire.encodeCacheKey(rscUrl, interceptionContext);
 	const cache = getPrefetchCache();
@@ -694,6 +749,7 @@ function createCachedRscResponseSnapshot(response, buffer, responseUrl = null) {
 		...dynamicStaleTimeSeconds !== void 0 ? { dynamicStaleTimeSeconds } : {},
 		mountedSlotsHeader: response.headers.get(VINEXT_MOUNTED_SLOTS_HEADER),
 		paramsHeader: response.headers.get(VINEXT_PARAMS_HEADER),
+		receivedAt: Date.now(),
 		...redirectHeader === null ? {} : { redirectHeader },
 		...redirectTypeHeader === null ? {} : { redirectTypeHeader },
 		renderedPathAndSearch: parseRenderedPathAndSearchHeader(response.headers.get(VINEXT_RENDERED_PATH_AND_SEARCH_HEADER)),
@@ -862,7 +918,7 @@ function prefetchRscResponse(rscUrl, fetchPromise, interceptionContext = null, m
 	if (behavior.dynamicStaleTime === "learning-only" && behavior.searchAgnosticShell !== true) {
 		entry.dynamicStaleTime = "learning-only";
 		entry.fallbackTtlMs = behavior.fallbackTtlMs ?? PREFETCH_CACHE_TTL;
-	}
+	} else if (behavior.dynamicStaleTime === "full-prefetch") entry.dynamicStaleTime = "full-prefetch";
 	addPrefetchInvalidationCallback(entry, options?.onInvalidate);
 	entry.fetchPromise = fetchPromise;
 	entry.pending = fetchPromise.then(async (response) => {
@@ -1022,6 +1078,8 @@ function getClientNavigationState() {
 		originalPushState: window.history.pushState.bind(window.history),
 		originalReplaceState: window.history.replaceState.bind(window.history),
 		patchInstalled: false,
+		routerHistoryWriteDepth: 0,
+		routerHistoryWrite: null,
 		hasPendingNavigationUpdate: false,
 		suppressUrlNotifyCount: 0,
 		navigationSnapshotActiveCount: 0
@@ -1365,16 +1423,80 @@ function commitClientNavigationState(navId, options) {
 	if (urlChanged || paramsChanged) clearClientHydrationContext();
 	if (shouldNotify) notifyNavigationListeners();
 }
-function pushHistoryStateWithoutNotify(data, unused, url) {
-	withSuppressedUrlNotifications(() => {
-		getClientNavigationState()?.originalPushState.call(window.history, data, unused, url);
-	});
+/** Whether a history entry's state is the data written to it, cloned by the browser. */
+function isSameHistoryStateData(historyState, data) {
+	try {
+		return JSON.stringify(historyState) === JSON.stringify(data);
+	} catch {
+		return false;
+	}
+}
+/** Writes the in-progress router write if this call is it, consuming its marker. */
+function forwardRouterHistoryWrite(state, method, data, unused, url) {
+	const write = state.routerHistoryWrite;
+	if (write?.method !== method) return false;
+	if (write.threw) {
+		if (url == null || new URL(url, window.location.href).href !== write.href) return false;
+		if (write.data !== data && !(isAppOwnedHistoryState(data) && readHistoryStateTraversalIndex(data) === readHistoryStateTraversalIndex(write.data))) return false;
+	} else if (write.data !== data || write.url !== url) return false;
+	if (write.landed) return true;
+	state.routerHistoryWrite = null;
+	const landing = write.land?.(data);
+	const original = method === "pushState" ? state.originalPushState : state.originalReplaceState;
+	const writtenData = landing ? landing.data : data;
+	const historyStateBeforeWrite = window.history.state;
+	try {
+		original.call(window.history, writtenData, unused, url);
+	} catch (error) {
+		const landed = window.history.state !== historyStateBeforeWrite && window.location.href === write.href && isSameHistoryStateData(window.history.state, writtenData);
+		if (landed) landing?.commit();
+		state.routerHistoryWrite = {
+			...write,
+			threw: true,
+			landed
+		};
+		throw error;
+	}
+	landing?.commit();
+	if (write.threw) state.routerHistoryWrite = {
+		...write,
+		landed: true
+	};
+	return true;
 }
-function replaceHistoryStateWithoutNotify(data, unused, url) {
+function writeRouterHistoryState(method, data, unused, url, land) {
 	withSuppressedUrlNotifications(() => {
-		getClientNavigationState()?.originalReplaceState.call(window.history, data, unused, url);
+		const state = getClientNavigationState();
+		if (!state) return;
+		if (url == null) {
+			(method === "pushState" ? state.originalPushState : state.originalReplaceState).call(window.history, data, unused, url);
+			return;
+		}
+		const previousWrite = state.routerHistoryWrite;
+		state.routerHistoryWriteDepth += 1;
+		state.routerHistoryWrite = {
+			method,
+			data,
+			url,
+			href: new URL(url, window.location.href).href,
+			land,
+			threw: false,
+			landed: false
+		};
+		try {
+			window.history[method](data, unused, url);
+		} finally {
+			state.routerHistoryWriteDepth -= 1;
+			state.routerHistoryWrite = previousWrite;
+		}
 	});
 }
+function pushHistoryStateWithoutNotify(data, unused, url, land) {
+	writeRouterHistoryState("pushState", data, unused, url, land);
+}
+function replaceHistoryStateWithoutNotify(data, unused, url, land) {
+	writeRouterHistoryState("replaceState", data, unused, url, land);
+}
 /**
 * Save the current scroll position into the current history state.
 * Called before every navigation to enable scroll restoration on back/forward.
@@ -1590,6 +1712,32 @@ function hasScheduledAppRouterNavigation() {
 function releaseScheduledAppRouterNavigationAfterCurrentTask(release) {
 	queueMicrotask(release);
 }
+let inFlightAppRouterNavigationCount = 0;
+let visibleLinkPingAwaitsNavigations = false;
+/**
+* Called by the App Router browser entry for each RSC navigation it runs.
+* Returns a release callback for the navigation's settlement.
+*/
+function trackAppRouterNavigationInFlight() {
+	inFlightAppRouterNavigationCount += 1;
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		inFlightAppRouterNavigationCount = Math.max(0, inFlightAppRouterNavigationCount - 1);
+		if (inFlightAppRouterNavigationCount === 0 && visibleLinkPingAwaitsNavigations) {
+			visibleLinkPingAwaitsNavigations = false;
+			getNavigationRuntime()?.functions.pingVisibleLinks?.();
+		}
+	};
+}
+function pingVisibleLinksOnceNavigationsSettle() {
+	if (inFlightAppRouterNavigationCount > 0) {
+		visibleLinkPingAwaitsNavigations = true;
+		return;
+	}
+	getNavigationRuntime()?.functions.pingVisibleLinks?.();
+}
 /**
 * App Router public router instance. Mirrors Next.js's
 * `publicAppRouterInstance` from
@@ -1641,15 +1789,16 @@ const _appRouter = {
 	},
 	refresh() {
 		if (isServer) return;
-		getNavigationRuntime()?.functions.clearNavigationCaches?.();
-		if (hasScheduledAppRouterNavigation()) return;
+		getNavigationRuntime()?.functions.clearNavigationCaches?.({ pingVisibleLinks: false });
 		const rscNavigate = getNavigationRuntime()?.functions.navigate;
-		if (rscNavigate) {
-			const navigate = () => {
-				rscNavigate(window.location.href, 0, "refresh", void 0, void 0, true);
-			};
-			React$1.startTransition(navigate);
+		if (hasScheduledAppRouterNavigation() || !rscNavigate) {
+			getNavigationRuntime()?.functions.pingVisibleLinks?.();
+			return;
 		}
+		const navigate = () => {
+			rscNavigate(window.location.href, 0, "refresh", void 0, void 0, true).finally(pingVisibleLinksOnceNavigationsSettle);
+		};
+		React$1.startTransition(navigate);
 	},
 	prefetch(href, options) {
 		assertSafeNavigationUrl(href);
@@ -1720,7 +1869,9 @@ const _appRouter = {
 					onInvalidate: options?.onInvalidate,
 					onReuse: policy.dynamicStaleTime === "full-prefetch" ? (entry, matchedCacheKey) => promotePrefetchCacheEntryForNavigation(matchedCacheKey, entry) : void 0
 				})) return;
+				if (policy.dynamicStaleTime === "full-prefetch" && seedFullPrefetchFromVisitedResponse(rscUrl, interceptionContext, mountedSlotsHeader, additionalRscUrls, options?.onInvalidate)) return;
 			}
+			if (policy.dynamicStaleTime !== "full-prefetch" && hasNavigationFreshVisitedResponse(rscUrl, interceptionContext, mountedSlotsHeader, additionalRscUrls, options?.onInvalidate)) return;
 			prefetched.add(cacheKey);
 			const fetchFullRscPayload = () => scheduleAppPrefetchFetch((signal) => fetch(rscUrl, {
 				headers,
@@ -1878,7 +2029,8 @@ if (!isServer) {
 			}
 		});
 		window.history.pushState = function patchedPushState(data, unused, url) {
-			getNavigationRuntime()?.functions.flushCommittingNavigationUrl?.();
+			if (forwardRouterHistoryWrite(state, "pushState", data, unused, url)) return;
+			if (state.routerHistoryWriteDepth === 0) getNavigationRuntime()?.functions.flushCommittingNavigationUrl?.();
 			if (isAppOwnedHistoryState(data)) {
 				const previousHistoryState = window.history.state;
 				state.originalPushState.call(window.history, data, unused, url);
@@ -1895,7 +2047,8 @@ if (!isServer) {
 			}
 		};
 		window.history.replaceState = function patchedReplaceState(data, unused, url) {
-			getNavigationRuntime()?.functions.flushCommittingNavigationUrl?.();
+			if (forwardRouterHistoryWrite(state, "replaceState", data, unused, url)) return;
+			if (state.routerHistoryWriteDepth === 0) getNavigationRuntime()?.functions.flushCommittingNavigationUrl?.();
 			if (isAppOwnedHistoryState(data)) {
 				const previousHistoryState = window.history.state;
 				state.originalReplaceState.call(window.history, data, unused, url);
@@ -1914,4 +2067,4 @@ if (!isServer) {
 	}
 }
 //#endregion
-export { BailoutToCSRError, DYNAMIC_NAVIGATION_CACHE_TTL, DynamicServerError, GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, MAX_PREFETCH_CACHE_SIZE, PREFETCH_CACHE_TTL, ReadonlyURLSearchParams, RedirectType, ServerInsertedHTMLContext, UnrecognizedActionError, __basePath, _registerStateAccessors, activateNavigationSnapshot, appRouterInstance, applyAppRouterScrollFallback, clearPendingPathname, clearServerInsertedHTML, commitClientNavigationState, consumePrefetchResponse, consumePrefetchResponseForNavigation, createAppPrefetchRequestHeaders, createCachedRscResponseSnapshot, createClientNavigationRenderSnapshot, createSnapshotPathAndSearch, decodeRedirectError, deletePrefetchResponseSnapshot, disableNavigationResponsePrefetchCacheReuse, discardLearningOnlyPrefetchCacheEntry, fetchRouteTreeGatedPrefetch, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getBfcacheIdMapContext, getBfcacheSegmentIdContext, getClientNavigationRenderContext, getClientNavigationState, getClientParams, getCurrentInterceptionContext, getCurrentNextUrl, getFreshPrefetchCacheEntry, getLayoutSegmentContext, getMountedSlotsHeader, getNavigationContext, getPrefetchCache, getPrefetchInterceptionContext, getPrefetchedUrls, hasFreshLearningOnlyPrefetchCacheEntry, hasPrefetchCacheEntryForNavigation, hasSearchAgnosticPrefetchShellForRoute, invalidatePrefetchCache, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, navigateClientSide, notFound, parseRenderedPathAndSearchHeader, peekPrefetchResponseForNavigation, permanentRedirect, prefetchRscResponse, preloadHybridClientRouteOwner, prepareNavigationPrefetchSnapshot, promotePrefetchCacheEntryForNavigation, pushHistoryStateWithoutNotify, redirect, renderServerInsertedHTML, replaceClientParamsWithoutNotify, replaceHistoryStateWithoutNotify, resolveCachedRscResponseExpiresAt, resolveCachedRscResponseTtlMs, resolveLoadedHybridClientRewriteHref, resolvePrefetchCacheEntryMountedSlotsHeader, restoreRscResponse, saveScrollPosition, seedPrefetchResponseSnapshot, setClientParams, setMountedSlotsHeader, setNavigationContext, setPendingPathname, snapshotRscResponse, storePrefetchResponse, unauthorized, unstable_isUnrecognizedActionError, unstable_rethrow, useClientNavigationRenderSnapshot, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };
+export { BailoutToCSRError, DYNAMIC_NAVIGATION_CACHE_TTL, DynamicServerError, GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, MAX_PREFETCH_CACHE_SIZE, PREFETCH_CACHE_TTL, ReadonlyURLSearchParams, RedirectType, ServerInsertedHTMLContext, UnrecognizedActionError, __basePath, _registerStateAccessors, activateNavigationSnapshot, appRouterInstance, applyAppRouterScrollFallback, clearPendingPathname, clearServerInsertedHTML, commitClientNavigationState, consumePrefetchResponse, consumePrefetchResponseForNavigation, createAppPrefetchRequestHeaders, createCachedRscResponseSnapshot, createClientNavigationRenderSnapshot, createSnapshotPathAndSearch, decodeRedirectError, deletePrefetchResponseSnapshot, disableNavigationResponsePrefetchCacheReuse, discardLearningOnlyPrefetchCacheEntry, fetchRouteTreeGatedPrefetch, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getBfcacheIdMapContext, getBfcacheSegmentIdContext, getClientNavigationRenderContext, getClientNavigationState, getClientParams, getCurrentInterceptionContext, getCurrentNextUrl, getFreshPrefetchCacheEntry, getLayoutSegmentContext, getMountedSlotsHeader, getNavigationContext, getPrefetchCache, getPrefetchInterceptionContext, getPrefetchedUrls, hasFreshLearningOnlyPrefetchCacheEntry, hasNavigationFreshVisitedResponse, hasPrefetchCacheEntryForNavigation, hasSearchAgnosticPrefetchShellForRoute, invalidateDynamicPrefetchCache, invalidatePrefetchCache, invalidateVisitedResponsePrefetches, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, navigateClientSide, notFound, parseRenderedPathAndSearchHeader, peekPrefetchResponseForNavigation, permanentRedirect, prefetchRscResponse, preloadHybridClientRouteOwner, prepareNavigationPrefetchSnapshot, promotePrefetchCacheEntryForNavigation, pushHistoryStateWithoutNotify, redirect, renderServerInsertedHTML, replaceClientParamsWithoutNotify, replaceHistoryStateWithoutNotify, resolveCachedRscResponseExpiresAt, resolveCachedRscResponseTtlMs, resolveLoadedHybridClientRewriteHref, resolvePrefetchCacheEntryMountedSlotsHeader, restoreRscResponse, saveScrollPosition, seedFullPrefetchFromVisitedResponse, seedPrefetchResponseSnapshot, setClientParams, setMountedSlotsHeader, setNavigationContext, setPendingPathname, snapshotRscResponse, storePrefetchResponse, trackAppRouterNavigationInFlight, unauthorized, unstable_isUnrecognizedActionError, unstable_rethrow, useClientNavigationRenderSnapshot, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };

package/dist/shims/navigation.react-server.js

@@ -1,7 +1,7 @@
-import { GLOBAL_ACCESSORS_KEY, ServerInsertedHTMLContext, _registerStateAccessors, clearServerInsertedHTML, flushServerInsertedHTML, getLayoutSegmentContext, getNavigationContext, renderServerInsertedHTML, setNavigationContext } from "./navigation-context-state.js";
+import { ReadonlyURLSearchParams } from "./readonly-url-search-params.js";
 import { BailoutToCSRError, DynamicServerError, HTTP_ERROR_FALLBACK_ERROR_CODE, RedirectType, forbidden, getAccessFallbackHTTPStatus, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, notFound, permanentRedirect, redirect, unauthorized, unstable_rethrow } from "./navigation-errors.js";
+import { GLOBAL_ACCESSORS_KEY, ServerInsertedHTMLContext, _registerStateAccessors, clearServerInsertedHTML, flushServerInsertedHTML, getLayoutSegmentContext, getNavigationContext, renderServerInsertedHTML, setNavigationContext } from "./navigation-context-state.js";
 import "./navigation-server.js";
-import { ReadonlyURLSearchParams } from "./readonly-url-search-params.js";
 import { throwClientHookError } from "./client-hook-error.js";
 //#region src/shims/navigation.react-server.ts
 function usePathname() {

package/dist/shims/request-state-types.d.ts

@@ -1,12 +1,13 @@
-import { ExecutionContextLike } from "./request-context.js";
+import { CacheLifeConfig } from "../utils/cache-life-profiles.js";
 import { NavigationContext } from "./navigation-context-state.js";
 import "./navigation.js";
-import { CacheLifeConfig, CacheState } from "./cache-request-state.js";
+import { ExecutionContextLike } from "./request-context.js";
 import { RootParamsState } from "./root-params.js";
 import { FetchCacheState } from "./fetch-cache-state.js";
 import "./fetch-cache.js";
 import { HeadersAccessPhase, VinextHeadersShimState } from "./internal/headers-state.js";
 import { HeadersContext } from "./headers.js";
+import { CacheState } from "./cache-request-state.js";
 import { RouterState, SSRContext } from "./router-state.js";
 import { PrivateCacheState } from "./cache-runtime.js";
 import { HeadState } from "./head-state.js";

package/dist/shims/slot.d.ts

@@ -40,6 +40,7 @@ type MergeElementsOptions = {
   clearAbsentSlots?: boolean;
   preserveAbsentSlots?: boolean;
   preserveElementIds?: readonly string[];
+  preserveElementSeedIds?: readonly string[];
   preservePreviousSlotIds?: readonly string[];
 };
 export declare function updateBfcacheSlotEntryOrder(previousOrder: readonly string[], activeStateKey: string, maxEntries?: number): string[];
@@ -59,6 +60,21 @@ export declare function BfcacheSegmentBoundary({ children, id, stateKey }: {
   id: string;
   stateKey: string;
 }): React$1.JSX.Element;
+/**
+ * Retains a layout's children across navigations that change which segment
+ * they render. Each child keeps its own wrappers, so a page and a nested layout
+ * give the layout's children different element shapes, and a retention list
+ * inside the child would remount with them. Next.js keeps this Activity list in
+ * the parent's layout router, above the child's boundaries, so a page left for a
+ * sibling with its own layout keeps its state when navigating back.
+ */
+export declare function BfcacheChildrenBoundary({ children, id, stateKey }: {
+  children: React$1.ReactNode;
+  /** The child element whose identity keys the entries. */
+  id?: string;
+  /** A fixed key, for a segment level with no element of its own. */
+  stateKey?: string;
+}): React$1.JSX.Element;
 export declare function getNonCacheComponentsSegmentKey(id: string, activeStateKey: string): string | undefined;
 export declare function resolveBfcacheSegmentStateKey(id: string, identityMap: Readonly<Record<string, string>>, bfcacheIdMap: Readonly<Record<string, string>> | null): string | undefined;
 export declare function mergeElements(prev: AppElements, next: AppElements, options?: MergeElementsOptions | boolean): AppElements;

package/dist/shims/slot.js

@@ -1,10 +1,10 @@
 "use client";
 import { APP_BFCACHE_SEGMENT_IDENTITIES_KEY, AppElementsWire, UNMATCHED_SLOT } from "../server/app-elements-wire.js";
 import "../server/app-elements.js";
-import { getBfcacheIdMapContext, getBfcacheSegmentIdContext } from "./navigation-context-state.js";
+import { isNestedBfcacheSlotSegmentId, isNestedBfcacheSlotSegmentIdFor } from "../server/bfcache-identity.js";
 import { notFound } from "./navigation-errors.js";
+import { getBfcacheIdMapContext, getBfcacheSegmentIdContext } from "./navigation-context-state.js";
 import "./navigation-server.js";
-import { isNestedBfcacheSlotSegmentId, isNestedBfcacheSlotSegmentIdFor } from "../server/bfcache-identity.js";
 import * as React$1 from "react";
 import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
 //#region src/shims/slot.tsx
@@ -92,11 +92,6 @@ function stageBfcacheSlotEntryForRender(committedSnapshots, committedOrder, acti
 		snapshots
 	};
 }
-function isLayoutFlagsValue(value) {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-	const entries = Object.values(value);
-	return entries.length > 0 && entries.every((entry) => entry === "s" || entry === "d");
-}
 function isArtifactCompatibilityEnvelopeValue(value) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
 	return "schemaVersion" in value && "appElementsSchemaVersion" in value && "rscPayloadSchemaVersion" in value && "graphVersion" in value && "deploymentVersion" in value && "rootBoundaryId" in value && "renderEpoch" in value;
@@ -127,7 +122,7 @@ function isCacheEntryReuseProofValue(value) {
 	return "kind" in value && value.kind === "runtime-cache-entry" && "decision" in value;
 }
 function isTransportMetadataValue(id, value) {
-	return isLayoutFlagsValue(value) || isBfcacheSegmentIdentitiesMetadataValue(id, value) || isArtifactCompatibilityEnvelopeValue(value) || isCacheEntryReuseProofValue(value) || isInterceptionMetadataValue(value) || isSkippedLayoutIdsMetadataValue(id, value) || isSlotBindingListValue(value);
+	return isBfcacheSegmentIdentitiesMetadataValue(id, value) || isArtifactCompatibilityEnvelopeValue(value) || isCacheEntryReuseProofValue(value) || isInterceptionMetadataValue(value) || isSkippedLayoutIdsMetadataValue(id, value) || isSlotBindingListValue(value);
 }
 function warnTransportMetadataEntry(id) {
 	if (process.env.NODE_ENV === "production") return;
@@ -210,6 +205,40 @@ function BfcacheSegmentBoundary({ children, id, stateKey }) {
 		stateKeyMap: identityMap
 	});
 }
+/**
+* Retains a layout's children across navigations that change which segment
+* they render. Each child keeps its own wrappers, so a page and a nested layout
+* give the layout's children different element shapes, and a retention list
+* inside the child would remount with them. Next.js keeps this Activity list in
+* the parent's layout router, above the child's boundaries, so a page left for a
+* sibling with its own layout keeps its state when navigating back.
+*/
+function BfcacheChildrenBoundary({ children, id, stateKey }) {
+	if (!BfcacheIdMapContext || !BfcacheSegmentIdContext || !isCacheComponentsEnabled()) return /* @__PURE__ */ jsx(Fragment$1, { children });
+	return /* @__PURE__ */ jsx(BfcacheChildrenActivityBoundary, {
+		id,
+		IdMapContext: BfcacheIdMapContext,
+		SegmentContext: BfcacheSegmentIdContext,
+		stateKey,
+		children
+	});
+}
+function BfcacheChildrenActivityBoundary({ children, id, IdMapContext, SegmentContext, stateKey }) {
+	const elements = React$1.useContext(ElementsContext);
+	const identityMap = React$1.useContext(BfcacheIdentityMapContext);
+	const bfcacheIdMap = React$1.useContext(IdMapContext);
+	const segmentId = React$1.useContext(SegmentContext);
+	const activeStateKey = stateKey ?? (id === void 0 ? void 0 : resolveBfcacheSegmentStateKey(id, identityMap, bfcacheIdMap));
+	if (segmentId === null || activeStateKey === void 0) return /* @__PURE__ */ jsx(Fragment$1, { children });
+	return /* @__PURE__ */ jsx(BfcacheActivitySlotBoundary, {
+		activeStateKey,
+		content: children,
+		elements,
+		id: segmentId,
+		SegmentContext,
+		stateKeyMap: identityMap
+	});
+}
 function getNonCacheComponentsSegmentKey(id, activeStateKey) {
 	const parsed = AppElementsWire.parseElementKey(id);
 	return parsed !== null && parsed.kind !== "route" ? activeStateKey : void 0;
@@ -244,6 +273,7 @@ function mergeElements(prev, next, options = {}) {
 	const clearAbsentSlots = typeof options === "boolean" ? options : options.clearAbsentSlots ?? false;
 	const preserveAbsentSlots = typeof options === "boolean" ? !options : options.preserveAbsentSlots ?? true;
 	const preserveElementIds = typeof options === "boolean" ? [] : options.preserveElementIds ?? [];
+	const preserveElementSeedIds = typeof options === "boolean" ? [] : options.preserveElementSeedIds ?? [];
 	const preservePreviousSlotIds = typeof options === "boolean" ? [] : options.preservePreviousSlotIds ?? [];
 	const merged = { ...next };
 	const preservedIdentityIds = /* @__PURE__ */ new Set();
@@ -254,6 +284,11 @@ function mergeElements(prev, next, options = {}) {
 			preservedIdentityIds.add(id);
 		}
 	}
+	for (const id of preserveElementSeedIds) {
+		if (preservedIdentityIds.has(id) || !Object.hasOwn(prev, id)) continue;
+		const value = prev[id];
+		if (value !== void 0) merged[id] = value;
+	}
 	const slotKeys = new Set([...Object.keys(prev), ...Object.keys(next)].filter((key) => AppElementsWire.isSlotId(key) && !isNestedBfcacheSlotSegmentId(key)));
 	if (clearAbsentSlots) {
 		for (const key of slotKeys) if (!Object.hasOwn(next, key)) delete merged[key];
@@ -340,4 +375,4 @@ function ParallelSlot({ name }) {
 	return React$1.useContext(ParallelSlotsContext)?.[name] ?? null;
 }
 //#endregion
-export { BfcacheIdentityMapContext, BfcacheSegmentBoundary, Children, ChildrenContext, ElementsContext, ParallelSlot, ParallelSlotsContext, RenderedSearchContext, Slot, UNMATCHED_SLOT, bindAppElementsRenderedSearch, getNonCacheComponentsSegmentKey, mergeElements, resolveBfcacheSegmentStateKey, setAppElementsRenderedSearch, stageBfcacheSlotEntryForRender, updateBfcacheSlotEntryOrder };
+export { BfcacheChildrenBoundary, BfcacheIdentityMapContext, BfcacheSegmentBoundary, Children, ChildrenContext, ElementsContext, ParallelSlot, ParallelSlotsContext, RenderedSearchContext, Slot, UNMATCHED_SLOT, bindAppElementsRenderedSearch, getNonCacheComponentsSegmentKey, mergeElements, resolveBfcacheSegmentStateKey, setAppElementsRenderedSearch, stageBfcacheSlotEntryForRender, updateBfcacheSlotEntryOrder };

package/dist/shims/unified-request-context.d.ts

@@ -1,8 +1,8 @@
 import { ExecutionContextLike } from "./request-context.js";
-import { CacheState } from "./cache-request-state.js";
 import { RootParamsState } from "./root-params.js";
 import { FetchCacheState } from "./fetch-cache-state.js";
 import { VinextHeadersShimState } from "./internal/headers-state.js";
+import { CacheState } from "./cache-request-state.js";
 import { RouterState } from "./router-state.js";
 import { markFullyBufferedBody, preserveFullyBufferedBodyMetadata } from "../server/fully-buffered-response.js";
 import { PrivateCacheState } from "./cache-runtime.js";
@@ -30,6 +30,12 @@ export type UnifiedRequestContext = {
   requestCache: WeakMap<(...args: any[]) => any, unknown>;
   /** Shared lifecycle state for work deferred until the response closes. */
   afterContext: AfterRequestContext;
+  /**
+   * Draft-mode state of the headers context this request last cleared. The
+   * render can outlive its headers context (cleared once the response body
+   * closes), and so do after() callbacks; cache bypasses keep reading this.
+   */
+  draftModeAtHeadersClear: boolean;
 } & VinextHeadersShimState & I18nState & NavigationState & CacheState & PrivateCacheState & FetchCacheState & RouterState & HeadState & RootParamsState;
 export type AfterRequestContext = {
   callbacks: Array<() => unknown>;

package/dist/shims/unified-request-context.js

@@ -18,7 +18,7 @@ function createRequestContext(opts) {
 	return {
 		headersContext: null,
 		actionRevalidationKind: 0,
-		cacheLifeSink: null,
+		isOnDemandRevalidate: false,
 		pendingCdnTagInvalidations: [],
 		pendingRevalidatedTags: /* @__PURE__ */ new Set(),
 		pendingRevalidations: /* @__PURE__ */ new Set(),
@@ -37,15 +37,14 @@ function createRequestContext(opts) {
 		serverContext: null,
 		serverInsertedHTMLCallbacks: [],
 		requestScopedCacheLife: null,
-		unstableCacheObservations: /* @__PURE__ */ new Map(),
 		unstableCacheRevalidation: "foreground",
 		_privateCache: null,
-		cacheableFetchUrls: /* @__PURE__ */ new Set(),
 		currentRequestTags: [],
 		currentFetchSoftTags: [],
 		currentFetchCacheMode: null,
 		currentFetchRevalidate: null,
 		currentForceDynamicFetchDefault: false,
+		isDraftMode: false,
 		dynamicFetchUrls: /* @__PURE__ */ new Set(),
 		refreshStaleFetchesInForeground: false,
 		isFetchDedupeActive: false,
@@ -54,6 +53,7 @@ function createRequestContext(opts) {
 		executionContext: _getInheritedExecutionContext(),
 		requestSignal: null,
 		requestCache: /* @__PURE__ */ new WeakMap(),
+		draftModeAtHeadersClear: false,
 		afterContext: {
 			callbacks: [],
 			responseClosed: false,

package/dist/utils/cache-control-metadata.d.ts

@@ -1,5 +1,10 @@
 //#region src/utils/cache-control-metadata.d.ts
 export declare function readCacheControlNumberField(ctx: Record<string, unknown> | undefined, field: string): number | undefined;
+/**
+ * When a `"use cache"` entry's generation started (`ctx.timestamp`), which dates
+ * the entry like Next.js does. Absent, malformed or future values fall back to `now`.
+ */
+export declare function readCacheTimestamp(ctx: Record<string, unknown> | undefined, now: number): number;
 export declare function readCacheControlRevalidateField(ctx: Record<string, unknown> | undefined): number | false | undefined;
 /**
  * Client-reuse seconds from a resolved `cacheLife`. Shared by every emitter

package/dist/utils/cache-control-metadata.js

@@ -8,6 +8,14 @@ function readCacheControlNumberField(ctx, field) {
 	const value = readRecordField(ctx, "cacheControl")?.[field] ?? ctx?.[field];
 	return typeof value === "number" ? value : void 0;
 }
+/**
+* When a `"use cache"` entry's generation started (`ctx.timestamp`), which dates
+* the entry like Next.js does. Absent, malformed or future values fall back to `now`.
+*/
+function readCacheTimestamp(ctx, now) {
+	const value = ctx?.timestamp;
+	return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= now ? value : now;
+}
 function readCacheControlRevalidateField(ctx) {
 	const value = readRecordField(ctx, "cacheControl")?.revalidate ?? ctx?.revalidate;
 	return typeof value === "number" || value === false ? value : void 0;
@@ -29,4 +37,4 @@ function resolveClientStaleTimeSeconds(cacheLife) {
 	return isFiniteNonNegative(stale) ? stale : void 0;
 }
 //#endregion
-export { readCacheControlNumberField, readCacheControlRevalidateField, resolveClientStaleTimeSeconds };
+export { readCacheControlNumberField, readCacheControlRevalidateField, readCacheTimestamp, resolveClientStaleTimeSeconds };

package/dist/utils/cache-life-profiles.d.ts

@@ -0,0 +1,33 @@
+//#region src/utils/cache-life-profiles.d.ts
+export type CacheLifeConfig = {
+  stale?: number;
+  revalidate?: number;
+  expire?: number;
+};
+/** Next.js's built-in profiles (`defaultConfig.cacheLife` in config-shared.ts). */
+export declare const BUILT_IN_CACHE_LIFE_PROFILES: Readonly<Record<string, Readonly<CacheLifeConfig>>>;
+/**
+ * Merge next.config `cacheLife` profiles over the built-ins, as Next.js does
+ * in `assignDefaultsAndValidate` (server/config.ts): a user profile replaces
+ * the built-in of the same name whole, and only `default` gets its missing
+ * fields filled: `stale` from `staleTimes.static`, `revalidate` from the
+ * built-in, `expire` from `expireTime`. That includes the built-in `default`,
+ * whose `stale` is unset in Next.js's defaults too. The other profiles keep
+ * their gaps, which the "use cache" store resolves from `default`.
+ *
+ * Next.js only schema-checks these profiles (fields must be numbers) and
+ * warns; `revalidate > expire` is checked for `cacheLife({...})` calls, not
+ * for config profiles.
+ */
+export declare function resolveCacheLifeProfiles(userProfiles: unknown, defaults: {
+  expireTime: number;
+  staticStaleTime: number;
+}, warn: (message: string) => void): Record<string, CacheLifeConfig>;
+/** Serialize resolved profiles for the `__VINEXT_CACHE_LIFE_PROFILES` define. */
+export declare function serializeCacheLifeProfiles(profiles: Record<string, CacheLifeConfig>): string;
+/**
+ * Read the `__VINEXT_CACHE_LIFE_PROFILES` define. When absent, the profiles a
+ * next.config without `cacheLife` resolves to.
+ */
+export declare function parseCacheLifeProfiles(serialized: string | undefined): Record<string, CacheLifeConfig>;
+//#endregion