vinext 0.0.55 → 0.1.0

package/dist/shims/link.d.ts

@@ -61,6 +61,7 @@ declare function resolveLinkPrefetchMode(prefetchProp: LinkProps["prefetch"], is
 declare function canAutoPrefetchFullAppRoute(href: string): boolean;
 declare function resolveAutoAppRoutePrefetch(href: string): {
   cacheForNavigation: boolean;
+  prefetchShellFirst: boolean;
   shouldPrefetch: boolean;
 };
 declare const Link: React.ForwardRefExoticComponent<{
@@ -98,5 +99,4 @@ declare const Link: React.ForwardRefExoticComponent<{
   children?: React.ReactNode;
 } & Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> & React.RefAttributes<HTMLAnchorElement>>;
 //#endregion
-export { canAutoPrefetchFullAppRoute, Link as default, resolveAutoAppRoutePrefetch, resolveLinkPrefetchMode, useLinkStatus };
-//# sourceMappingURL=link.d.ts.map
+export { canAutoPrefetchFullAppRoute, Link as default, resolveAutoAppRoutePrefetch, resolveLinkPrefetchMode, useLinkStatus };

package/dist/shims/link.js

@@ -14,7 +14,7 @@ import { appendSearchParamsToUrl, urlQueryToSearchParams } from "../utils/query.
 import { getCurrentBrowserLocale } from "./client-locale.js";
 import { getNavigationRuntime, hasAppNavigationRuntime, registerNavigationRuntimeFunctions } from "../client/navigation-runtime.js";
 import { createRscRequestHeaders, createRscRequestUrl, stripRscCacheBustingSearchParam, stripRscSuffix } from "../server/app-rsc-cache-busting.js";
-import { getMountedSlotsHeader, getPrefetchCache, getPrefetchInterceptionContext, getPrefetchedUrls, navigateClientSide, prefetchRscResponse } from "./navigation.js";
+import { getMountedSlotsHeader, getPrefetchCache, getPrefetchInterceptionContext, getPrefetchedUrls, hasPrefetchCacheEntryForNavigation, navigateClientSide, prefetchRscResponse } from "./navigation.js";
 import { navigatePagesRouterLink } from "../client/pages-router-link-navigation.js";
 import { getI18nContext } from "./i18n-context.js";
 import { canLinkIntentPrefetch, canLinkPrefetch, getLinkPrefetchHref } from "./link-prefetch.js";
@@ -115,6 +115,13 @@ function toSameOriginRouteHref(href) {
 function getLinkPrefetchRouterMode() {
 	return hasAppNavigationRuntime() ? "app" : "pages";
 }
+function resolveMatchedAutoAppRoutePrefetch(route) {
+	return {
+		cacheForNavigation: !(route.isDynamic && route.canPrefetchLoadingShell),
+		prefetchShellFirst: !route.isDynamic,
+		shouldPrefetch: true
+	};
+}
 function canAutoPrefetchFullAppRoute(href) {
 	if (typeof window === "undefined") return false;
 	const routes = window.__VINEXT_LINK_PREFETCH_ROUTES__;
@@ -123,32 +130,33 @@ function canAutoPrefetchFullAppRoute(href) {
 	if (routeHref === null) return false;
 	const match = matchRouteWithTrie(routeHref, routes, linkPrefetchRouteTrieCache);
 	if (!match) return false;
-	return !match.route.isDynamic;
+	return resolveMatchedAutoAppRoutePrefetch(match.route).cacheForNavigation;
 }
 function resolveAutoAppRoutePrefetch(href) {
 	if (typeof window === "undefined") return {
 		cacheForNavigation: false,
+		prefetchShellFirst: false,
 		shouldPrefetch: false
 	};
 	const routes = window.__VINEXT_LINK_PREFETCH_ROUTES__;
 	if (!routes) return {
 		cacheForNavigation: false,
+		prefetchShellFirst: false,
 		shouldPrefetch: false
 	};
 	const routeHref = toSameOriginRouteHref(href);
 	if (routeHref === null) return {
 		cacheForNavigation: false,
+		prefetchShellFirst: false,
 		shouldPrefetch: false
 	};
 	const match = matchRouteWithTrie(routeHref, routes, linkPrefetchRouteTrieCache);
 	if (!match) return {
 		cacheForNavigation: false,
+		prefetchShellFirst: false,
 		shouldPrefetch: false
 	};
-	return {
-		cacheForNavigation: !match.route.isDynamic,
-		shouldPrefetch: !match.route.isDynamic || match.route.canPrefetchLoadingShell
-	};
+	return resolveMatchedAutoAppRoutePrefetch(match.route);
 }
 /**
 * Prefetch a URL for faster navigation.
@@ -178,6 +186,7 @@ function prefetchUrl(href, mode, priority = "low") {
 			if (hasAppNavigationRuntime()) {
 				const autoPrefetch = mode === "auto" ? resolveAutoAppRoutePrefetch(prefetchHref) : {
 					cacheForNavigation: true,
+					prefetchShellFirst: true,
 					shouldPrefetch: true
 				};
 				if (!autoPrefetch.shouldPrefetch) return;
@@ -194,14 +203,13 @@ function prefetchUrl(href, mode, priority = "low") {
 				const cacheKey = AppElementsWire.encodeCacheKey(rscUrl, interceptionContext);
 				const prefetched = getPrefetchedUrls();
 				if (prefetched.has(cacheKey)) {
-					if (autoPrefetch.cacheForNavigation) {
-						const existing = getPrefetchCache().get(cacheKey);
-						if (existing?.cacheForNavigation === false) existing.cacheForNavigation = true;
-					}
-					return;
+					if (!autoPrefetch.cacheForNavigation) return;
+					const existing = getPrefetchCache().get(cacheKey);
+					if (existing?.cacheForNavigation === false) existing.cacheForNavigation = true;
 				}
+				if (autoPrefetch.cacheForNavigation && hasPrefetchCacheEntryForNavigation(rscUrl, interceptionContext, mountedSlotsHeader)) return;
 				prefetched.add(cacheKey);
-				prefetchRscResponse(rscUrl, __prefetchInlining && autoPrefetch.cacheForNavigation ? (async () => {
+				prefetchRscResponse(rscUrl, __prefetchInlining && autoPrefetch.cacheForNavigation && autoPrefetch.prefetchShellFirst ? (async () => {
 					const shellHeaders = createRscRequestHeaders({
 						interceptionContext,
 						renderMode: APP_RSC_RENDER_MODE_PREFETCH_LOADING_SHELL
@@ -608,5 +616,3 @@ const Link = forwardRef(function Link({ href, as, replace = false, prefetch: pre
 });
 //#endregion
 export { canAutoPrefetchFullAppRoute, Link as default, resolveAutoAppRoutePrefetch, resolveLinkPrefetchMode, useLinkStatus };
-
-//# sourceMappingURL=link.js.map

package/dist/shims/metadata.d.ts

@@ -1,4 +1,4 @@
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import React from "react";
 
 //#region src/shims/metadata.d.ts
 type Viewport = {
@@ -32,7 +32,7 @@ declare function ViewportHead({
   viewport
 }: {
   viewport: Viewport;
-}): _$react_jsx_runtime0.JSX.Element;
+}): React.JSX.Element;
 type Metadata = {
   title?: string | {
     default?: string;
@@ -276,7 +276,6 @@ declare function renderMetadataToHtml(metadata: Metadata, pathname?: string): st
 declare function MetadataHead({
   metadata,
   pathname
-}: MetadataHeadProps): _$react_jsx_runtime0.JSX.Element;
+}: MetadataHeadProps): React.JSX.Element;
 //#endregion
-export { DEFAULT_VIEWPORT, Metadata, MetadataHead, MetadataMergeEntry, Viewport, ViewportHead, mergeMetadata, mergeMetadataEntries, mergeViewport, postProcessMetadata, renderMetadataToHtml, resolveModuleMetadata, resolveModuleViewport };
-//# sourceMappingURL=metadata.d.ts.map
+export { DEFAULT_VIEWPORT, Metadata, MetadataHead, MetadataMergeEntry, Viewport, ViewportHead, mergeMetadata, mergeMetadataEntries, mergeViewport, postProcessMetadata, renderMetadataToHtml, resolveModuleMetadata, resolveModuleViewport };

package/dist/shims/metadata.js

@@ -220,7 +220,7 @@ async function resolveModuleMetadata(mod, params = {}, searchParams, parent = Pr
 			params: asyncParams,
 			searchParams: makeThenableParams(searchParams)
 		};
-		return await mod.generateMetadata(props, parent);
+		return await (mod.generateMetadata.length >= 2 ? mod.generateMetadata(props, parent) : mod.generateMetadata(props));
 	}
 	if (mod.metadata && typeof mod.metadata === "object") return mod.metadata;
 	return null;
@@ -800,5 +800,3 @@ function MetadataHead({ metadata, pathname = "/" }) {
 }
 //#endregion
 export { DEFAULT_VIEWPORT, MetadataHead, ViewportHead, mergeMetadata, mergeMetadataEntries, mergeViewport, postProcessMetadata, renderMetadataToHtml, resolveModuleMetadata, resolveModuleViewport };
-
-//# sourceMappingURL=metadata.js.map

package/dist/shims/navigation-state.d.ts

@@ -23,5 +23,4 @@ declare function runWithNavigationContext<T>(fn: () => T | Promise<T>): T | Prom
 declare function runWithServerInsertedHTMLState<T>(fn: () => Promise<T>): Promise<T>;
 declare function runWithServerInsertedHTMLState<T>(fn: () => T | Promise<T>): T | Promise<T>;
 //#endregion
-export { NavigationState, runWithNavigationContext, runWithServerInsertedHTMLState };
-//# sourceMappingURL=navigation-state.d.ts.map
+export { NavigationState, runWithNavigationContext, runWithServerInsertedHTMLState };

package/dist/shims/navigation-state.js

@@ -63,5 +63,3 @@ _registerStateAccessors(_accessors);
 globalThis[GLOBAL_ACCESSORS_KEY] = _accessors;
 //#endregion
 export { runWithNavigationContext, runWithServerInsertedHTMLState };
-
-//# sourceMappingURL=navigation-state.js.map

package/dist/shims/navigation.d.ts

@@ -1,4 +1,4 @@
-import { AppRouterInstance } from "./internal/app-router-context.js";
+import { NavigateOptions, PrefetchOptions as PrefetchOptions$1 } from "./internal/app-router-context.js";
 import { ReadonlyURLSearchParams } from "./readonly-url-search-params.js";
 import { UnrecognizedActionError, unstable_isUnrecognizedActionError } from "./unrecognized-action-error.js";
 import * as React$1 from "react";
@@ -21,6 +21,8 @@ declare const ServerInsertedHTMLContext: React$1.Context<((callback: () => unkno
  * Returns null in the RSC environment (createContext unavailable).
  */
 declare function getLayoutSegmentContext(): React$1.Context<SegmentMap> | null;
+declare function getBfcacheIdMapContext(): React$1.Context<Readonly<Record<string, string>> | null> | null;
+declare function getBfcacheSegmentIdContext(): React$1.Context<string | null> | null;
 type NavigationContext = {
   pathname: string;
   searchParams: URLSearchParams;
@@ -59,6 +61,8 @@ type CachedRscResponse = {
   compatibilityIdHeader?: string | null;
   buffer: ArrayBuffer;
   contentType: string;
+  dynamicStaleTimeSeconds?: number;
+  expiresAt?: number;
   mountedSlotsHeader?: string | null;
   paramsHeader: string | null;
   url: string;
@@ -69,7 +73,9 @@ type PrefetchOptions = {
 };
 type PrefetchCacheEntry = {
   cacheForNavigation?: boolean;
+  expiresAt?: number;
   invalidationTimer?: ReturnType<typeof setTimeout>;
+  mountedSlotsHeader?: string | null;
   onInvalidateCallbacks?: Set<() => void>;
   optimisticRouteShell?: boolean;
   outcome: "pending" | "cache-seeded";
@@ -87,6 +93,10 @@ declare function getPrefetchCache(): Map<string, PrefetchCacheEntry>;
  * Keyed by interception-aware cache key so distinct source routes do not alias.
  */
 declare function getPrefetchedUrls(): Set<string>;
+declare function resolveCachedRscResponseTtlMs(cached: Pick<CachedRscResponse, "dynamicStaleTimeSeconds">, fallbackTtlMs: number): number;
+declare function resolveCachedRscResponseExpiresAt(timestamp: number, cached: Pick<CachedRscResponse, "dynamicStaleTimeSeconds" | "expiresAt">, fallbackTtlMs: number): number;
+declare function resolvePrefetchCacheEntryMountedSlotsHeader(entry: PrefetchCacheEntry): string | null;
+declare function hasPrefetchCacheEntryForNavigation(rscUrl: string, interceptionContext?: string | null, mountedSlotsHeader?: string | null): boolean;
 declare function invalidatePrefetchCache(): void;
 /**
  * Store a prefetched RSC response in the cache by snapshotting it to an
@@ -271,11 +281,18 @@ declare const appRouterInstance: {
  * App Router's useRouter — returns push/replace/back/forward/refresh.
  * Different from Pages Router's useRouter (next/router).
  *
- * Returns a stable singleton: the same object reference on every call,
- * matching Next.js behavior so components using referential equality
- * (e.g. useMemo / useEffect deps, React.memo) don't re-render unnecessarily.
+ * Preserves the mounted AppRouterContext router as the authority for methods
+ * and layers the nearest segment's contextual `bfcacheId` on top.
  */
-declare function useRouter(): AppRouterInstance;
+declare function useRouter(): {
+  bfcacheId: string;
+  back(): void;
+  forward(): void;
+  refresh(): void;
+  push(href: string, options?: NavigateOptions): void;
+  replace(href: string, options?: NavigateOptions): void;
+  prefetch(href: string, options?: PrefetchOptions$1): void;
+};
 /**
  * Returns the active child segment one level below the layout where it's called.
  *
@@ -557,5 +574,4 @@ declare function isDynamicServerError(error: unknown): error is DynamicServerErr
  */
 declare function unstable_rethrow(error: unknown): void;
 //#endregion
-export { BailoutToCSRError, CachedRscResponse, ClientNavigationRenderSnapshot, DynamicServerError, GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, MAX_PREFETCH_CACHE_SIZE, NavigationContext, PREFETCH_CACHE_TTL, PrefetchCacheEntry, PrefetchOptions, ReadonlyURLSearchParams, RedirectType, SegmentMap, ServerInsertedHTMLContext, UnrecognizedActionError, __basePath, _registerStateAccessors, activateNavigationSnapshot, appRouterInstance, clearPendingPathname, clearServerInsertedHTML, commitClientNavigationState, consumePrefetchResponse, consumePrefetchResponseForNavigation, createCachedRscResponseSnapshot, createClientNavigationRenderSnapshot, decodeRedirectError, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getClientNavigationRenderContext, getClientNavigationState, getClientParams, getCurrentInterceptionContext, getCurrentNextUrl, getLayoutSegmentContext, getMountedSlotsHeader, getNavigationContext, getPrefetchCache, getPrefetchInterceptionContext, getPrefetchedUrls, invalidatePrefetchCache, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, navigateClientSide, notFound, permanentRedirect, prefetchRscResponse, pushHistoryStateWithoutNotify, redirect, renderServerInsertedHTML, replaceClientParamsWithoutNotify, replaceHistoryStateWithoutNotify, restoreRscResponse, saveScrollPosition, setClientParams, setMountedSlotsHeader, setNavigationContext, setPendingPathname, snapshotRscResponse, storePrefetchResponse, unauthorized, unstable_isUnrecognizedActionError, unstable_rethrow, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };
-//# sourceMappingURL=navigation.d.ts.map
+export { BailoutToCSRError, CachedRscResponse, ClientNavigationRenderSnapshot, DynamicServerError, GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, MAX_PREFETCH_CACHE_SIZE, NavigationContext, PREFETCH_CACHE_TTL, PrefetchCacheEntry, PrefetchOptions, ReadonlyURLSearchParams, RedirectType, SegmentMap, ServerInsertedHTMLContext, UnrecognizedActionError, __basePath, _registerStateAccessors, activateNavigationSnapshot, appRouterInstance, clearPendingPathname, clearServerInsertedHTML, commitClientNavigationState, consumePrefetchResponse, consumePrefetchResponseForNavigation, createCachedRscResponseSnapshot, createClientNavigationRenderSnapshot, decodeRedirectError, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getBfcacheIdMapContext, getBfcacheSegmentIdContext, getClientNavigationRenderContext, getClientNavigationState, getClientParams, getCurrentInterceptionContext, getCurrentNextUrl, getLayoutSegmentContext, getMountedSlotsHeader, getNavigationContext, getPrefetchCache, getPrefetchInterceptionContext, getPrefetchedUrls, hasPrefetchCacheEntryForNavigation, invalidatePrefetchCache, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, navigateClientSide, notFound, permanentRedirect, prefetchRscResponse, pushHistoryStateWithoutNotify, redirect, renderServerInsertedHTML, replaceClientParamsWithoutNotify, replaceHistoryStateWithoutNotify, resolveCachedRscResponseExpiresAt, resolveCachedRscResponseTtlMs, resolvePrefetchCacheEntryMountedSlotsHeader, restoreRscResponse, saveScrollPosition, setClientParams, setMountedSlotsHeader, setNavigationContext, setPendingPathname, snapshotRscResponse, storePrefetchResponse, unauthorized, unstable_isUnrecognizedActionError, unstable_rethrow, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };

package/dist/shims/navigation.js

@@ -1,5 +1,5 @@
 import { stripBasePath } from "../utils/base-path.js";
-import { VINEXT_MOUNTED_SLOTS_HEADER, VINEXT_PARAMS_HEADER } from "../server/headers.js";
+import { VINEXT_DYNAMIC_STALE_TIME_HEADER, VINEXT_MOUNTED_SLOTS_HEADER, VINEXT_PARAMS_HEADER } from "../server/headers.js";
 import { assertSafeNavigationUrl } from "./url-safety.js";
 import { AppElementsWire } from "../server/app-elements-wire.js";
 import "../server/app-elements.js";
@@ -8,9 +8,11 @@ import { isAbsoluteOrProtocolRelativeUrl, isHashOnlyBrowserUrlChange, toBrowserN
 import { retryScrollTo, scrollToHashTarget } from "./hash-scroll.js";
 import { getNavigationRuntime, hasAppNavigationRuntime } from "../client/navigation-runtime.js";
 import { notifyAppRouterTransitionStart } from "../client/instrumentation-client-state.js";
+import { PUBLIC_INITIAL_BFCACHE_ID } from "../server/app-bfcache-id.js";
 import { resolveManifestNavigationInterceptionContext } from "../server/app-browser-interception-context.js";
-import { createExternalHistoryStatePreservingMetadata } from "../server/app-history-state.js";
-import { VINEXT_RSC_COMPATIBILITY_ID_HEADER, createRscRequestHeaders, createRscRequestUrl } from "../server/app-rsc-cache-busting.js";
+import { createExternalHistoryStatePreservingMetadata, createHashOnlyHistoryStatePreservingNavigationMetadata } from "../server/app-history-state.js";
+import { VINEXT_RSC_COMPATIBILITY_ID_HEADER, createRscRequestHeaders, createRscRequestUrl, stripRscCacheBustingSearchParam } from "../server/app-rsc-cache-busting.js";
+import { hasPendingAppRouterPageRedirect } from "../server/app-browser-mpa-navigation.js";
 import { ReadonlyURLSearchParams } from "./readonly-url-search-params.js";
 import { beginAppRouterScrollIntent, clearAppRouterScrollIntent, consumeAppRouterScrollIntent } from "./app-router-scroll-state.js";
 import { UnrecognizedActionError, unstable_isUnrecognizedActionError } from "./unrecognized-action-error.js";
@@ -25,6 +27,8 @@ import * as React$1 from "react";
 */
 const _LAYOUT_SEGMENT_CTX_KEY = Symbol.for("vinext.layoutSegmentContext");
 const _SERVER_INSERTED_HTML_CTX_KEY = Symbol.for("vinext.serverInsertedHTMLContext");
+const _BFCACHE_ID_MAP_CTX_KEY = Symbol.for("vinext.bfcacheIdMapContext");
+const _BFCACHE_SEGMENT_ID_CTX_KEY = Symbol.for("vinext.bfcacheSegmentIdContext");
 function getServerInsertedHTMLContext() {
 	if (typeof React$1.createContext !== "function") return null;
 	const globalState = globalThis;
@@ -42,6 +46,18 @@ function getLayoutSegmentContext() {
 	if (!globalState[_LAYOUT_SEGMENT_CTX_KEY]) globalState[_LAYOUT_SEGMENT_CTX_KEY] = React$1.createContext({ children: [] });
 	return globalState[_LAYOUT_SEGMENT_CTX_KEY] ?? null;
 }
+function getBfcacheIdMapContext() {
+	if (typeof React$1.createContext !== "function") return null;
+	const globalState = globalThis;
+	if (!globalState[_BFCACHE_ID_MAP_CTX_KEY]) globalState[_BFCACHE_ID_MAP_CTX_KEY] = React$1.createContext(null);
+	return globalState[_BFCACHE_ID_MAP_CTX_KEY] ?? null;
+}
+function getBfcacheSegmentIdContext() {
+	if (typeof React$1.createContext !== "function") return null;
+	const globalState = globalThis;
+	if (!globalState[_BFCACHE_SEGMENT_ID_CTX_KEY]) globalState[_BFCACHE_SEGMENT_ID_CTX_KEY] = React$1.createContext(null);
+	return globalState[_BFCACHE_SEGMENT_ID_CTX_KEY] ?? null;
+}
 /**
 * Read the child segments for a parallel route below the current layout.
 * Returns [] if no context is available (RSC environment, outside React tree)
@@ -200,6 +216,91 @@ function getPrefetchedUrls() {
 	if (!window.__VINEXT_RSC_PREFETCHED_URLS__) window.__VINEXT_RSC_PREFETCHED_URLS__ = /* @__PURE__ */ new Set();
 	return window.__VINEXT_RSC_PREFETCHED_URLS__;
 }
+function isDynamicStaleTimeSeconds(value) {
+	return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
+}
+function isCacheExpiresAt(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function parseDynamicStaleTimeSeconds(value) {
+	if (value === null || value === "") return void 0;
+	const seconds = Number(value);
+	return isDynamicStaleTimeSeconds(seconds) ? seconds : void 0;
+}
+function resolveCachedRscResponseTtlMs(cached, fallbackTtlMs) {
+	const seconds = cached.dynamicStaleTimeSeconds;
+	if (!isDynamicStaleTimeSeconds(seconds)) return fallbackTtlMs;
+	return seconds * 1e3;
+}
+function resolveCachedRscResponseExpiresAt(timestamp, cached, fallbackTtlMs) {
+	if (isCacheExpiresAt(cached.expiresAt)) return cached.expiresAt;
+	return timestamp + resolveCachedRscResponseTtlMs(cached, fallbackTtlMs);
+}
+function resolvePrefetchCacheEntryExpiresAt(entry) {
+	if (entry.expiresAt !== void 0) return entry.expiresAt;
+	if (entry.snapshot) return resolveCachedRscResponseExpiresAt(entry.timestamp, entry.snapshot, PREFETCH_CACHE_TTL);
+	return entry.timestamp + PREFETCH_CACHE_TTL;
+}
+function resolvePrefetchCacheEntryMountedSlotsHeader(entry) {
+	if (entry.mountedSlotsHeader !== void 0) return entry.mountedSlotsHeader;
+	return entry.snapshot?.mountedSlotsHeader ?? null;
+}
+function normalizeRscCacheLookupUrl(rscUrl) {
+	try {
+		const url = new URL(rscUrl, "http://vinext.local");
+		stripRscCacheBustingSearchParam(url);
+		return `${url.pathname}${url.search}`;
+	} catch {
+		return null;
+	}
+}
+function parsePrefetchCacheKey(cacheKey) {
+	const separatorIndex = cacheKey.indexOf("\0");
+	if (separatorIndex === -1) return {
+		interceptionContext: null,
+		rscUrl: cacheKey
+	};
+	return {
+		interceptionContext: cacheKey.slice(separatorIndex + 1),
+		rscUrl: cacheKey.slice(0, separatorIndex)
+	};
+}
+function isPrefetchCacheEntryCompatibleWithMountedSlots(entry, mountedSlotsHeader) {
+	if (resolvePrefetchCacheEntryMountedSlotsHeader(entry) === mountedSlotsHeader) return true;
+	return (entry.snapshot?.mountedSlotsHeader ?? null) === mountedSlotsHeader;
+}
+function findPrefetchCacheEntryForNavigation(rscUrl, interceptionContext, mountedSlotsHeader) {
+	const exactCacheKey = AppElementsWire.encodeCacheKey(rscUrl, interceptionContext);
+	const cache = getPrefetchCache();
+	const exactEntry = cache.get(exactCacheKey);
+	if (exactEntry && exactEntry.cacheForNavigation !== false && isPrefetchCacheEntryCompatibleWithMountedSlots(exactEntry, mountedSlotsHeader)) return {
+		cacheKey: exactCacheKey,
+		entry: exactEntry
+	};
+	const normalizedTarget = normalizeRscCacheLookupUrl(rscUrl);
+	if (normalizedTarget === null) return null;
+	for (const [cacheKey, entry] of cache) {
+		if (cacheKey === exactCacheKey) continue;
+		if (entry.cacheForNavigation === false) continue;
+		const source = parsePrefetchCacheKey(cacheKey);
+		if (source.interceptionContext !== interceptionContext) continue;
+		if (normalizeRscCacheLookupUrl(source.rscUrl) !== normalizedTarget) continue;
+		if (!isPrefetchCacheEntryCompatibleWithMountedSlots(entry, mountedSlotsHeader)) continue;
+		return {
+			cacheKey,
+			entry
+		};
+	}
+	return null;
+}
+function hasPrefetchCacheEntryForNavigation(rscUrl, interceptionContext = null, mountedSlotsHeader = null) {
+	const match = findPrefetchCacheEntryForNavigation(rscUrl, interceptionContext, mountedSlotsHeader);
+	if (match === null) return false;
+	if (match.entry.pending !== void 0) return true;
+	if (resolvePrefetchCacheEntryExpiresAt(match.entry) > Date.now()) return true;
+	deletePrefetchCacheEntry(getPrefetchCache(), getPrefetchedUrls(), match.cacheKey, match.entry, true);
+	return false;
+}
 /**
 * Evict prefetch cache entries if at capacity.
 * First sweeps expired entries, then falls back to FIFO eviction.
@@ -209,7 +310,7 @@ function evictPrefetchCacheIfNeeded() {
 	if (cache.size < 50) return;
 	const now = Date.now();
 	const prefetched = getPrefetchedUrls();
-	for (const [key, entry] of cache) if (now - entry.timestamp >= PREFETCH_CACHE_TTL) deletePrefetchCacheEntry(cache, prefetched, key, entry, true);
+	for (const [key, entry] of cache) if (resolvePrefetchCacheEntryExpiresAt(entry) <= now) deletePrefetchCacheEntry(cache, prefetched, key, entry, true);
 	while (cache.size >= 50) {
 		const oldest = cache.keys().next().value;
 		if (oldest !== void 0) {
@@ -258,8 +359,7 @@ function invalidatePrefetchCacheEntry(cacheKey) {
 function schedulePrefetchInvalidation(cacheKey, entry) {
 	if (entry.onInvalidateCallbacks === void 0 || entry.onInvalidateCallbacks.size === 0) return;
 	clearPrefetchInvalidation(entry);
-	const elapsed = Date.now() - entry.timestamp;
-	const delay = Math.max(0, PREFETCH_CACHE_TTL - elapsed);
+	const delay = Math.max(0, resolvePrefetchCacheEntryExpiresAt(entry) - Date.now());
 	entry.invalidationTimer = setTimeout(() => {
 		invalidatePrefetchCacheEntry(cacheKey);
 	}, delay);
@@ -303,12 +403,15 @@ function storePrefetchResponse(rscUrl, response, interceptionContext = null, opt
 	const cacheKey = AppElementsWire.encodeCacheKey(rscUrl, interceptionContext);
 	evictPrefetchCacheIfNeeded();
 	const entry = {
+		mountedSlotsHeader: null,
 		outcome: "pending",
 		timestamp: Date.now()
 	};
 	addPrefetchInvalidationCallback(entry, options?.onInvalidate);
 	entry.pending = snapshotRscResponse(response).then((snapshot) => {
+		entry.mountedSlotsHeader = snapshot.mountedSlotsHeader ?? null;
 		entry.snapshot = snapshot;
+		entry.expiresAt = resolveCachedRscResponseExpiresAt(entry.timestamp, snapshot, PREFETCH_CACHE_TTL);
 	}).catch(() => {
 		deletePrefetchCacheEntry(getPrefetchCache(), getPrefetchedUrls(), cacheKey, entry, false);
 	}).finally(() => {
@@ -321,10 +424,12 @@ function storePrefetchResponse(rscUrl, response, interceptionContext = null, opt
 	getPrefetchCache().set(cacheKey, entry);
 }
 function createCachedRscResponseSnapshot(response, buffer, responseUrl = null) {
+	const dynamicStaleTimeSeconds = parseDynamicStaleTimeSeconds(response.headers.get(VINEXT_DYNAMIC_STALE_TIME_HEADER));
 	return {
 		compatibilityIdHeader: response.headers.get(VINEXT_RSC_COMPATIBILITY_ID_HEADER),
 		buffer,
 		contentType: response.headers.get("content-type") ?? "text/x-component",
+		...dynamicStaleTimeSeconds !== void 0 ? { dynamicStaleTimeSeconds } : {},
 		mountedSlotsHeader: response.headers.get(VINEXT_MOUNTED_SLOTS_HEADER),
 		paramsHeader: response.headers.get(VINEXT_PARAMS_HEADER),
 		url: responseUrl ?? response.url
@@ -356,6 +461,7 @@ function restoreRscResponse(cached, copy = true) {
 	const headers = new Headers({ "content-type": cached.contentType });
 	if (cached.mountedSlotsHeader != null) headers.set(VINEXT_MOUNTED_SLOTS_HEADER, cached.mountedSlotsHeader);
 	if (cached.compatibilityIdHeader != null) headers.set(VINEXT_RSC_COMPATIBILITY_ID_HEADER, cached.compatibilityIdHeader);
+	if (isDynamicStaleTimeSeconds(cached.dynamicStaleTimeSeconds)) headers.set(VINEXT_DYNAMIC_STALE_TIME_HEADER, String(cached.dynamicStaleTimeSeconds));
 	if (cached.paramsHeader != null) headers.set(VINEXT_PARAMS_HEADER, cached.paramsHeader);
 	return new Response(copy ? cached.buffer.slice(0) : cached.buffer, {
 		status: 200,
@@ -376,17 +482,17 @@ function prefetchRscResponse(rscUrl, fetchPromise, interceptionContext = null, m
 	const now = Date.now();
 	const entry = {
 		cacheForNavigation: behavior.cacheForNavigation ?? true,
+		mountedSlotsHeader,
 		optimisticRouteShell: behavior.optimisticRouteShell === true,
 		outcome: "pending",
 		timestamp: now
 	};
 	addPrefetchInvalidationCallback(entry, options?.onInvalidate);
 	entry.pending = fetchPromise.then(async (response) => {
-		if (response.ok) entry.snapshot = {
-			...await snapshotRscResponse(response),
-			mountedSlotsHeader
-		};
-		else deletePrefetchCacheEntry(cache, prefetched, cacheKey, entry, false);
+		if (response.ok) {
+			entry.snapshot = await snapshotRscResponse(response);
+			entry.expiresAt = resolveCachedRscResponseExpiresAt(entry.timestamp, entry.snapshot, PREFETCH_CACHE_TTL);
+		} else deletePrefetchCacheEntry(cache, prefetched, cacheKey, entry, false);
 	}).catch(() => {
 		deletePrefetchCacheEntry(cache, prefetched, cacheKey, entry, false);
 	}).finally(() => {
@@ -405,26 +511,32 @@ function prefetchRscResponse(rscUrl, fetchPromise, interceptionContext = null, m
 * Returns null if the entry is still in flight or doesn't exist.
 */
 function consumePrefetchResponse(rscUrl, interceptionContext = null, mountedSlotsHeader = null) {
-	const cacheKey = AppElementsWire.encodeCacheKey(rscUrl, interceptionContext);
 	const cache = getPrefetchCache();
-	const entry = cache.get(cacheKey);
-	if (!entry) return null;
+	const exactCacheKey = AppElementsWire.encodeCacheKey(rscUrl, interceptionContext);
+	const exactEntry = cache.get(exactCacheKey);
+	if (exactEntry && exactEntry.cacheForNavigation !== false && !isPrefetchCacheEntryCompatibleWithMountedSlots(exactEntry, mountedSlotsHeader)) deletePrefetchCacheEntry(cache, getPrefetchedUrls(), exactCacheKey, exactEntry, false);
+	const match = findPrefetchCacheEntryForNavigation(rscUrl, interceptionContext, mountedSlotsHeader);
+	if (!match) return null;
+	const { cacheKey, entry } = match;
 	if (entry.pending || entry.outcome !== "cache-seeded") return null;
 	if (entry.cacheForNavigation === false) return null;
 	deletePrefetchCacheEntry(cache, getPrefetchedUrls(), cacheKey, entry, false);
 	if (entry.snapshot) {
-		if ((entry.snapshot.mountedSlotsHeader ?? null) !== mountedSlotsHeader) return null;
-		if (Date.now() - entry.timestamp >= PREFETCH_CACHE_TTL) return null;
+		if (!isPrefetchCacheEntryCompatibleWithMountedSlots(entry, mountedSlotsHeader)) return null;
+		if (resolvePrefetchCacheEntryExpiresAt(entry) <= Date.now()) return null;
+		if (entry.expiresAt !== void 0 || entry.snapshot.expiresAt !== void 0) return {
+			...entry.snapshot,
+			expiresAt: resolvePrefetchCacheEntryExpiresAt(entry)
+		};
 		return entry.snapshot;
 	}
 	return null;
 }
 async function consumePrefetchResponseForNavigation(rscUrl, interceptionContext = null, mountedSlotsHeader = null, options) {
-	const cacheKey = AppElementsWire.encodeCacheKey(rscUrl, interceptionContext);
 	const cache = getPrefetchCache();
-	const entry = cache.get(cacheKey);
-	if (!entry) return null;
-	if (entry.cacheForNavigation === false) return null;
+	const match = findPrefetchCacheEntryForNavigation(rscUrl, interceptionContext, mountedSlotsHeader);
+	if (!match) return null;
+	const { cacheKey, entry } = match;
 	if (entry.pending !== void 0) {
 		await entry.pending.catch(() => {});
 		if (cache.get(cacheKey) !== entry) return null;
@@ -733,10 +845,7 @@ function commitClientNavigationState(navId, options) {
 	}
 	const shouldNotify = urlChanged || state.hasPendingNavigationUpdate;
 	state.hasPendingNavigationUpdate = false;
-	if (shouldNotify) {
-		notifyNavigationListeners();
-		getNavigationRuntime()?.functions.pingVisibleLinks?.();
-	}
+	if (shouldNotify) notifyNavigationListeners();
 }
 function pushHistoryStateWithoutNotify(data, unused, url) {
 	withSuppressedUrlNotifications(() => {
@@ -768,8 +877,9 @@ function commitHashOnlyHistoryState(href, mode, scroll) {
 		commitAppRouterHashNavigation(href, mode, scroll);
 		return;
 	}
-	if (mode === "replace") replaceHistoryStateWithoutNotify(null, "", href);
-	else pushHistoryStateWithoutNotify(null, "", href);
+	const historyState = createHashOnlyHistoryStatePreservingNavigationMetadata(window.history.state);
+	if (mode === "replace") replaceHistoryStateWithoutNotify(historyState, "", href);
+	else pushHistoryStateWithoutNotify(historyState, "", href);
 }
 function applyAppRouterScrollFallback(intent) {
 	if (typeof document === "undefined" || typeof window === "undefined") return;
@@ -835,6 +945,17 @@ async function navigateClientSide(href, mode, scroll, programmaticTransition = f
 		if (scroll) scrollToHashTarget(hash);
 		return;
 	}
+	if (hasPendingAppRouterPageRedirect(typeof document === "undefined" ? void 0 : document)) {
+		const mpaNavigate = getNavigationRuntime()?.functions.navigateExternal;
+		if (mpaNavigate) {
+			await mpaNavigate(fullHref, mode);
+			return;
+		}
+		if (mode === "replace") window.location.replace(fullHref);
+		else window.location.assign(fullHref);
+		await new Promise(() => {});
+		return;
+	}
 	const hashIdx = fullHref.indexOf("#");
 	const hash = hashIdx !== -1 ? fullHref.slice(hashIdx) : "";
 	const scrollIntent = scroll ? beginAppRouterScrollIntent(hash || null) : null;
@@ -873,13 +994,15 @@ function releaseScheduledAppRouterNavigationAfterCurrentTask(release) {
 	queueMicrotask(release);
 }
 /**
-* Public App Router instance, exposed for the browser entry so it can wire
-* `window.next.router` to the same singleton returned from `useRouter()`.
+* App Router public router instance. Mirrors Next.js's
+* `publicAppRouterInstance` from
+* `packages/next/src/client/components/app-router-instance.ts`.
 *
-* Mirrors `publicAppRouterInstance` from Next.js's
-* `packages/next/src/client/components/app-router-instance.ts` (line 392).
+* Exported so the App Router browser entry can install it on
+* `window.next.router` for Next.js parity (see `client/window-next.ts`).
+* Internal callers in this file continue to use `_appRouter` for brevity.
 */
-const appRouterInstance = {
+const _appRouter = {
 	bfcacheId: "0",
 	push(href, options) {
 		assertSafeNavigationUrl(href);
@@ -967,19 +1090,47 @@ const appRouterInstance = {
 		});
 	}
 };
+function formatPublicBfcacheId(value) {
+	if (!value || value === "0") return PUBLIC_INITIAL_BFCACHE_ID;
+	return value;
+}
+function readBfcacheIdFromContext() {
+	const segmentContext = getBfcacheSegmentIdContext();
+	const idMapContext = getBfcacheIdMapContext();
+	if (!segmentContext || !idMapContext || typeof React$1.useContext !== "function") return formatPublicBfcacheId(null);
+	try {
+		const segmentId = React$1.useContext(segmentContext);
+		const idMap = React$1.useContext(idMapContext);
+		return formatPublicBfcacheId(segmentId !== null ? idMap?.[segmentId] : null);
+	} catch (error) {
+		if (process.env.NODE_ENV !== "production") console.warn("[vinext] readBfcacheIdFromContext failed:", error);
+		return formatPublicBfcacheId(null);
+	}
+}
+/**
+* Public App Router instance, exposed for the browser entry so it can wire
+* `window.next.router` to the same singleton returned from `useRouter()`.
+*
+* Mirrors `publicAppRouterInstance` from Next.js's
+* `packages/next/src/client/components/app-router-instance.ts` (line 392).
+*/
+const appRouterInstance = _appRouter;
 /**
 * App Router's useRouter — returns push/replace/back/forward/refresh.
 * Different from Pages Router's useRouter (next/router).
 *
-* Returns a stable singleton: the same object reference on every call,
-* matching Next.js behavior so components using referential equality
-* (e.g. useMemo / useEffect deps, React.memo) don't re-render unnecessarily.
+* Preserves the mounted AppRouterContext router as the authority for methods
+* and layers the nearest segment's contextual `bfcacheId` on top.
 */
 function useRouter() {
-	if (!AppRouterContext || typeof React$1.useContext !== "function") throw new Error("invariant expected app router to be mounted");
+	if (!AppRouterContext || typeof React$1.useContext !== "function" || typeof React$1.useMemo !== "function") throw new Error("invariant expected app router to be mounted");
 	const router = React$1.useContext(AppRouterContext);
 	if (router === null) throw new Error("invariant expected app router to be mounted");
-	return router;
+	const bfcacheId = readBfcacheIdFromContext();
+	return React$1.useMemo(() => ({
+		...router,
+		bfcacheId
+	}), [router, bfcacheId]);
 }
 /**
 * Returns the active child segment one level below the layout where it's called.
@@ -1378,6 +1529,4 @@ if (!isServer) {
 	}
 }
 //#endregion
-export { BailoutToCSRError, DynamicServerError, GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, MAX_PREFETCH_CACHE_SIZE, PREFETCH_CACHE_TTL, ReadonlyURLSearchParams, RedirectType, ServerInsertedHTMLContext, UnrecognizedActionError, __basePath, _registerStateAccessors, activateNavigationSnapshot, appRouterInstance, clearPendingPathname, clearServerInsertedHTML, commitClientNavigationState, consumePrefetchResponse, consumePrefetchResponseForNavigation, createCachedRscResponseSnapshot, createClientNavigationRenderSnapshot, decodeRedirectError, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getClientNavigationRenderContext, getClientNavigationState, getClientParams, getCurrentInterceptionContext, getCurrentNextUrl, getLayoutSegmentContext, getMountedSlotsHeader, getNavigationContext, getPrefetchCache, getPrefetchInterceptionContext, getPrefetchedUrls, invalidatePrefetchCache, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, navigateClientSide, notFound, permanentRedirect, prefetchRscResponse, pushHistoryStateWithoutNotify, redirect, renderServerInsertedHTML, replaceClientParamsWithoutNotify, replaceHistoryStateWithoutNotify, restoreRscResponse, saveScrollPosition, setClientParams, setMountedSlotsHeader, setNavigationContext, setPendingPathname, snapshotRscResponse, storePrefetchResponse, unauthorized, unstable_isUnrecognizedActionError, unstable_rethrow, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };
-
-//# sourceMappingURL=navigation.js.map
+export { BailoutToCSRError, DynamicServerError, GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, MAX_PREFETCH_CACHE_SIZE, PREFETCH_CACHE_TTL, ReadonlyURLSearchParams, RedirectType, ServerInsertedHTMLContext, UnrecognizedActionError, __basePath, _registerStateAccessors, activateNavigationSnapshot, appRouterInstance, clearPendingPathname, clearServerInsertedHTML, commitClientNavigationState, consumePrefetchResponse, consumePrefetchResponseForNavigation, createCachedRscResponseSnapshot, createClientNavigationRenderSnapshot, decodeRedirectError, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getBfcacheIdMapContext, getBfcacheSegmentIdContext, getClientNavigationRenderContext, getClientNavigationState, getClientParams, getCurrentInterceptionContext, getCurrentNextUrl, getLayoutSegmentContext, getMountedSlotsHeader, getNavigationContext, getPrefetchCache, getPrefetchInterceptionContext, getPrefetchedUrls, hasPrefetchCacheEntryForNavigation, invalidatePrefetchCache, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, navigateClientSide, notFound, permanentRedirect, prefetchRscResponse, pushHistoryStateWithoutNotify, redirect, renderServerInsertedHTML, replaceClientParamsWithoutNotify, replaceHistoryStateWithoutNotify, resolveCachedRscResponseExpiresAt, resolveCachedRscResponseTtlMs, resolvePrefetchCacheEntryMountedSlotsHeader, restoreRscResponse, saveScrollPosition, setClientParams, setMountedSlotsHeader, setNavigationContext, setPendingPathname, snapshotRscResponse, storePrefetchResponse, unauthorized, unstable_isUnrecognizedActionError, unstable_rethrow, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };

package/dist/shims/navigation.react-server.d.ts

@@ -11,5 +11,4 @@ declare function useSelectedLayoutSegments(): never;
 declare function useServerInsertedHTML(): never;
 declare function unstable_isUnrecognizedActionError(): boolean;
 //#endregion
-export { BailoutToCSRError, DynamicServerError, GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, type NavigationContext, ReadonlyURLSearchParams, RedirectType, type SegmentMap, ServerInsertedHTMLContext, _registerStateAccessors, clearServerInsertedHTML, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getLayoutSegmentContext, getNavigationContext, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, notFound, permanentRedirect, redirect, renderServerInsertedHTML, setNavigationContext, unauthorized, unstable_isUnrecognizedActionError, unstable_rethrow, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };
-//# sourceMappingURL=navigation.react-server.d.ts.map
+export { BailoutToCSRError, DynamicServerError, GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, type NavigationContext, ReadonlyURLSearchParams, RedirectType, type SegmentMap, ServerInsertedHTMLContext, _registerStateAccessors, clearServerInsertedHTML, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getLayoutSegmentContext, getNavigationContext, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, notFound, permanentRedirect, redirect, renderServerInsertedHTML, setNavigationContext, unauthorized, unstable_isUnrecognizedActionError, unstable_rethrow, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };

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

@@ -28,5 +28,3 @@ function unstable_isUnrecognizedActionError() {
 }
 //#endregion
 export { BailoutToCSRError, DynamicServerError, GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, ReadonlyURLSearchParams, RedirectType, ServerInsertedHTMLContext, _registerStateAccessors, clearServerInsertedHTML, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getLayoutSegmentContext, getNavigationContext, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, notFound, permanentRedirect, redirect, renderServerInsertedHTML, setNavigationContext, unauthorized, unstable_isUnrecognizedActionError, unstable_rethrow, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };
-
-//# sourceMappingURL=navigation.react-server.js.map