vinext 0.1.2 → 0.1.4

package/dist/shims/link.js

@@ -8,15 +8,16 @@ import { APP_RSC_RENDER_MODE_PREFETCH_LOADING_SHELL } from "../server/app-rsc-re
 import "../server/app-elements.js";
 import { addLocalePrefix, getDomainLocaleUrl } from "../utils/domain-locale.js";
 import { prefetchPagesData, resolvePagesDataNavigationTarget } from "./internal/pages-data-target.js";
-import { markAppRouteDetectedOnPrefetch } from "./internal/app-route-detection.js";
-import { isAbsoluteOrProtocolRelativeUrl, normalizePathTrailingSlash, resolveRelativeHref, toBrowserNavigationHref, toSameOriginAppPath, withBasePath } from "./url-utils.js";
 import { appendSearchParamsToUrl, urlQueryToSearchParams } from "../utils/query.js";
+import { resolveHybridClientRouteOwner } from "./internal/hybrid-client-route-owner.js";
+import { markAppRouteDetectedOnPrefetch } from "./internal/app-route-detection.js";
+import { isAbsoluteOrProtocolRelativeUrl, normalizePathTrailingSlash, toBrowserNavigationHref, toSameOriginAppPath, withBasePath } from "./url-utils.js";
 import { getCurrentBrowserLocale } from "./client-locale.js";
 import { getCurrentRoutePathnameForWarning } from "./internal/route-pattern-for-warning.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, hasPrefetchCacheEntryForNavigation, navigateClientSide, prefetchRscResponse } from "./navigation.js";
-import { navigatePagesRouterLink } from "../client/pages-router-link-navigation.js";
+import { navigatePagesRouterLinkWithFallback, resolvePagesRouterQueryOnlyHref } from "../client/pages-router-link-navigation.js";
 import { getI18nContext } from "./i18n-context.js";
 import { canLinkIntentPrefetch, canLinkPrefetch, getLinkPrefetchHref } from "./link-prefetch.js";
 import { clearLinkForCurrentNavigation, notifyLinkNavigationStart, setLinkForCurrentNavigation } from "./internal/link-status-registry.js";
@@ -55,6 +56,19 @@ function resolveHref(href) {
 	}
 	return url;
 }
+function resolvePagesQueryOnlyHref(href) {
+	if (!href.startsWith("?") || typeof window === "undefined") return href;
+	const pagesRouter = window.next?.appDir === true ? void 0 : window.next?.router;
+	return resolvePagesRouterQueryOnlyHref(href, {
+		asPath: pagesRouter && "reload" in pagesRouter && "asPath" in pagesRouter && typeof pagesRouter.asPath === "string" ? pagesRouter.asPath : void 0,
+		basePath: __basePath,
+		fallbackHref: window.location.href,
+		locales: window.__VINEXT_LOCALES__
+	});
+}
+function resolvePagesLinkNavigationHref(href, locale) {
+	return normalizePathTrailingSlash(applyLocaleToHref(resolvePagesQueryOnlyHref(href), locale), __trailingSlash);
+}
 /**
 * Collapse repeated forward-slashes (and convert backslashes to forward-slashes)
 * in the path portion of a URL, preserving any query string.
@@ -122,7 +136,7 @@ function getLinkPrefetchRouterMode() {
 }
 function resolveMatchedAutoAppRoutePrefetch(route) {
 	return {
-		cacheForNavigation: !(route.isDynamic && route.canPrefetchLoadingShell),
+		cacheForNavigation: !route.canPrefetchLoadingShell,
 		prefetchShellFirst: !route.isDynamic,
 		shouldPrefetch: true
 	};
@@ -189,6 +203,8 @@ function prefetchUrl(href, mode, priority = "low") {
 	} : window.requestIdleCallback ?? ((fn) => setTimeout(fn, 100)))(() => {
 		(async () => {
 			if (hasAppNavigationRuntime()) {
+				const hybridOwner = resolveHybridClientRouteOwner(prefetchHref, __basePath);
+				if (hybridOwner === "pages" || hybridOwner === "document") return;
 				const autoPrefetch = mode === "auto" ? resolveAutoAppRoutePrefetch(prefetchHref) : {
 					cacheForNavigation: true,
 					prefetchShellFirst: true,
@@ -490,8 +506,9 @@ const Link = forwardRef(function Link({ href, as, replace = false, prefetch: pre
 			navigateHref = localPath;
 		}
 		e.preventDefault();
-		const absoluteHref = resolveRelativeHref(navigateHref, window.location.href, __basePath);
-		const absoluteFullHref = toBrowserNavigationHref(navigateHref, window.location.href, __basePath);
+		const hasAppNavigationRuntime = Boolean(getNavigationRuntime()?.functions.navigate);
+		const pagesNavigateHref = resolvedHref.startsWith("?") ? resolvePagesLinkNavigationHref(resolvedHref, locale) : navigateHref;
+		const absoluteFullHref = toBrowserNavigationHref(hasAppNavigationRuntime ? navigateHref : pagesNavigateHref, window.location.href, __basePath);
 		if (onNavigate) try {
 			const navUrl = new URL(absoluteFullHref, window.location.origin);
 			let prevented = false;
@@ -507,7 +524,12 @@ const Link = forwardRef(function Link({ href, as, replace = false, prefetch: pre
 			onNavigate(navEvent);
 			if (navEvent.defaultPrevented) return;
 		} catch {}
-		if (getNavigationRuntime()?.functions.navigate) {
+		if (hasAppNavigationRuntime && ["pages", "document"].includes(resolveHybridClientRouteOwner(navigateHref, __basePath) ?? "")) {
+			if (replace) window.location.replace(absoluteFullHref);
+			else window.location.assign(absoluteFullHref);
+			return;
+		}
+		if (hasAppNavigationRuntime) {
 			const setter = setPendingRef.current;
 			if (setter) setLinkForCurrentNavigation(setter);
 			setPending(true);
@@ -518,19 +540,25 @@ const Link = forwardRef(function Link({ href, as, replace = false, prefetch: pre
 				});
 			});
 			return;
-		} else try {
-			const Router = (await import("next/router.js")).default;
-			await navigatePagesRouterLink(Router, {
-				href: absoluteHref,
-				replace,
-				scroll,
-				shallow,
-				locale
+		} else {
+			const Router = window.next?.appDir === true ? void 0 : window.next?.router;
+			await navigatePagesRouterLinkWithFallback({
+				router: Router && "reload" in Router ? Router : void 0,
+				loadRouter: async () => (await import("next/router.js")).default,
+				navigation: {
+					href: pagesNavigateHref,
+					replace,
+					scroll,
+					shallow,
+					locale,
+					interpolateDynamicRoute: resolvedHref.startsWith("?")
+				},
+				fallback: () => {
+					if (replace) window.history.replaceState({}, "", absoluteFullHref);
+					else window.history.pushState({}, "", absoluteFullHref);
+					window.dispatchEvent(new PopStateEvent("popstate"));
+				}
 			});
-		} catch {
-			if (replace) window.history.replaceState({}, "", absoluteFullHref);
-			else window.history.pushState({}, "", absoluteFullHref);
-			window.dispatchEvent(new PopStateEvent("popstate"));
 		}
 	};
 	const anchorProps = restWithoutLocale;

package/dist/shims/metadata.js

@@ -621,7 +621,7 @@ function MetadataHead({ metadata, pathname = "/", trailingSlash }) {
 				}
 			}
 		}
-		if (tw.players) {
+		if (tw.card === "player" && tw.players) {
 			const players = Array.isArray(tw.players) ? tw.players : [tw.players];
 			for (const player of players) {
 				const playerUrl = player.playerUrl.toString();
@@ -644,7 +644,7 @@ function MetadataHead({ metadata, pathname = "/", trailingSlash }) {
 				}, key++));
 			}
 		}
-		if (tw.app) {
+		if (tw.card === "app" && tw.app) {
 			const { app } = tw;
 			for (const platform of [
 				"iphone",
@@ -655,11 +655,11 @@ function MetadataHead({ metadata, pathname = "/", trailingSlash }) {
 					name: `twitter:app:name:${platform}`,
 					content: app.name
 				}, key++));
-				if (app.id[platform] !== void 0) elements.push(/* @__PURE__ */ jsx("meta", {
+				if (app.id[platform]) elements.push(/* @__PURE__ */ jsx("meta", {
 					name: `twitter:app:id:${platform}`,
 					content: String(app.id[platform])
 				}, key++));
-				if (app.url?.[platform] !== void 0) {
+				if (app.url?.[platform]) {
 					const appUrl = app.url[platform].toString();
 					elements.push(/* @__PURE__ */ jsx("meta", {
 						name: `twitter:app:url:${platform}`,

package/dist/shims/navigation.d.ts

@@ -1,3 +1,4 @@
+import { AppRouterScrollIntent } from "./app-router-scroll-state.js";
 import { NavigationRuntimeVisibleCommitMode } from "../client/navigation-runtime.js";
 import { AppRouterInstance, NavigateOptions, PrefetchOptions as PrefetchOptions$1 } from "./internal/app-router-context.js";
 import { ReadonlyURLSearchParams } from "./readonly-url-search-params.js";
@@ -97,7 +98,9 @@ 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 hasPrefetchCacheEntryForNavigation(rscUrl: string, interceptionContext?: string | null, mountedSlotsHeader?: string | null, options?: {
+  notifyInvalidation?: boolean;
+}): boolean;
 declare function invalidatePrefetchCache(): void;
 /**
  * Store a prefetched RSC response in the cache by snapshotting it to an
@@ -205,6 +208,8 @@ type ClientNavigationRenderSnapshot = {
   params: Record<string, string | string[]>;
 };
 declare function getClientNavigationRenderContext(): React$1.Context<ClientNavigationRenderSnapshot | null> | null;
+/** @internal */
+declare function useClientNavigationRenderSnapshot(): ClientNavigationRenderSnapshot | null;
 declare function createClientNavigationRenderSnapshot(href: string, params: Record<string, string | string[]>): ClientNavigationRenderSnapshot;
 declare function createSnapshotPathAndSearch(snapshot: ClientNavigationRenderSnapshot): string;
 declare function setClientParams(params: Record<string, string | string[]>): void;
@@ -255,6 +260,7 @@ declare function replaceHistoryStateWithoutNotify(data: unknown, unused: string,
  * history.replaceState interception (which would cause spurious re-renders).
  */
 declare function saveScrollPosition(): void;
+declare function applyAppRouterScrollFallback(intent: AppRouterScrollIntent): void;
 /**
  * Navigate to a URL, handling external URLs, hash-only changes, and RSC navigation.
  */
@@ -565,4 +571,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, createSnapshotPathAndSearch, 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 };
+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, applyAppRouterScrollFallback, clearPendingPathname, clearServerInsertedHTML, commitClientNavigationState, consumePrefetchResponse, consumePrefetchResponseForNavigation, createCachedRscResponseSnapshot, createClientNavigationRenderSnapshot, createSnapshotPathAndSearch, 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, useClientNavigationRenderSnapshot, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };

package/dist/shims/navigation.js

@@ -1,13 +1,16 @@
 import { stripBasePath } from "../utils/base-path.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 { markPprFallbackShellDynamicBoundary } from "./ppr-fallback-shell.js";
 import { AppElementsWire } from "../server/app-elements-wire.js";
 import "../server/app-elements.js";
 import { AppRouterContext } from "./internal/app-router-context.js";
+import { resolveHybridClientRouteOwner } from "./internal/hybrid-client-route-owner.js";
 import { isAbsoluteOrProtocolRelativeUrl, toBrowserNavigationHref, toSameOriginAppPath, withBasePath } from "./url-utils.js";
 import { retryScrollTo, scrollToHashTarget } from "./hash-scroll.js";
 import { getNavigationRuntime, hasAppNavigationRuntime } from "../client/navigation-runtime.js";
 import { notifyAppRouterTransitionStart } from "../client/instrumentation-client-state.js";
+import { clearAppNavigationFailureTarget, stageAppNavigationFailureTarget } from "../client/app-nav-failure-handler.js";
 import { PUBLIC_INITIAL_BFCACHE_ID } from "../server/app-bfcache-id.js";
 import { resolveManifestNavigationInterceptionContext } from "../server/app-browser-interception-context.js";
 import { createExternalHistoryStatePreservingMetadata, createHashOnlyHistoryStatePreservingNavigationMetadata } from "../server/app-history-state.js";
@@ -15,7 +18,8 @@ import { VINEXT_RSC_COMPATIBILITY_ID_HEADER, createRscRequestHeaders, createRscR
 import { hasPendingAppRouterPageRedirect } from "../server/app-browser-mpa-navigation.js";
 import { navigationPlanner } from "../server/navigation-planner.js";
 import { ReadonlyURLSearchParams } from "./readonly-url-search-params.js";
-import { beginAppRouterScrollIntent, clearAppRouterScrollIntent, consumeAppRouterScrollIntent } from "./app-router-scroll-state.js";
+import { getPagesNavigationContext } from "./internal/pages-router-accessor.js";
+import { beginAppRouterScrollIntent, clearAppRouterScrollIntent, consumeAppRouterScrollIntent, getPendingAppRouterScrollIntent } from "./app-router-scroll-state.js";
 import { UnrecognizedActionError, unstable_isUnrecognizedActionError } from "./unrecognized-action-error.js";
 import * as React$1 from "react";
 //#region src/shims/navigation.ts
@@ -131,17 +135,7 @@ function _registerStateAccessors(accessors) {
 	_getInsertedHTMLCallbacks = accessors.getInsertedHTMLCallbacks;
 	_clearInsertedHTMLCallbacks = accessors.clearInsertedHTMLCallbacks;
 }
-const PAGES_NAVIGATION_ACCESSOR_KEY = Symbol.for("vinext.navigation.pagesNavigationContextAccessor");
 const PAGES_NAVIGATION_NOTIFY_KEY = Symbol.for("vinext.navigation.pagesNavigationNotify");
-function _getPagesNavigationContext() {
-	const accessor = globalThis[PAGES_NAVIGATION_ACCESSOR_KEY];
-	if (!accessor) return null;
-	try {
-		return accessor();
-	} catch {
-		return null;
-	}
-}
 /**
 * Get the navigation context for the current SSR/RSC render.
 * Reads from AsyncLocalStorage when available (concurrent-safe),
@@ -299,12 +293,12 @@ function findPrefetchCacheEntryForNavigation(rscUrl, interceptionContext, mounte
 	}
 	return null;
 }
-function hasPrefetchCacheEntryForNavigation(rscUrl, interceptionContext = null, mountedSlotsHeader = null) {
+function hasPrefetchCacheEntryForNavigation(rscUrl, interceptionContext = null, mountedSlotsHeader = null, options = {}) {
 	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);
+	deletePrefetchCacheEntry(getPrefetchCache(), getPrefetchedUrls(), match.cacheKey, match.entry, options.notifyInvalidation ?? true);
 	return false;
 }
 /**
@@ -617,7 +611,7 @@ function getReadonlyPagesSearchParams(searchParams) {
 * be visible until the next commit.
 */
 function getPathnameSnapshot() {
-	const pagesCtx = _getPagesNavigationContext();
+	const pagesCtx = getPagesNavigationContext();
 	if (pagesCtx) return pagesCtx.pathname;
 	return getClientNavigationState()?.cachedPathname ?? "/";
 }
@@ -632,7 +626,7 @@ let _cachedEmptyClientSearchParams = null;
 */
 function getSearchParamsSnapshot() {
 	if (_getServerContext()) return getServerSearchParamsSnapshot();
-	const pagesCtx = _getPagesNavigationContext();
+	const pagesCtx = getPagesNavigationContext();
 	if (pagesCtx) return getReadonlyPagesSearchParams(pagesCtx.searchParams);
 	const cached = getClientNavigationState()?.cachedReadonlySearchParams;
 	if (cached) return cached;
@@ -659,7 +653,7 @@ function syncCommittedUrlStateFromLocation() {
 function getServerSearchParamsSnapshot() {
 	const ctx = _getServerContext();
 	if (!ctx) {
-		const pagesCtx = _getPagesNavigationContext();
+		const pagesCtx = getPagesNavigationContext();
 		if (pagesCtx) return getReadonlyPagesSearchParams(pagesCtx.searchParams);
 		if (_cachedEmptyServerSearchParams === null) _cachedEmptyServerSearchParams = new ReadonlyURLSearchParams();
 		return _cachedEmptyServerSearchParams;
@@ -698,6 +692,7 @@ function getClientNavigationRenderContext() {
 	if (!globalState[_CLIENT_NAV_RENDER_CTX_KEY]) globalState[_CLIENT_NAV_RENDER_CTX_KEY] = React$1.createContext(null);
 	return globalState[_CLIENT_NAV_RENDER_CTX_KEY] ?? null;
 }
+/** @internal */
 function useClientNavigationRenderSnapshot() {
 	const ctx = getClientNavigationRenderContext();
 	if (!ctx || typeof React$1.useContext !== "function") return null;
@@ -783,14 +778,14 @@ function getClientParamsSnapshot() {
 	const state = getClientNavigationState();
 	const ctx = _getServerContext();
 	if (ctx) return ctx.params;
-	const pagesCtx = _getPagesNavigationContext();
+	const pagesCtx = getPagesNavigationContext();
 	if (pagesCtx) return pagesCtx.params;
 	return state?.clientParams ?? _EMPTY_PARAMS;
 }
 function getServerParamsSnapshot() {
 	const ctx = _getServerContext();
 	if (ctx) return ctx.params;
-	const pagesCtx = _getPagesNavigationContext();
+	const pagesCtx = getPagesNavigationContext();
 	if (pagesCtx) return pagesCtx.params;
 	return _EMPTY_PARAMS;
 }
@@ -808,16 +803,17 @@ function subscribeToNavigation(cb) {
 */
 function usePathname() {
 	if (isServer) {
+		markPprFallbackShellDynamicBoundary();
 		const ctx = _getServerContext();
 		if (ctx) return ctx.pathname;
-		const pagesCtx = _getPagesNavigationContext();
+		const pagesCtx = getPagesNavigationContext();
 		return pagesCtx ? pagesCtx.pathname : "/";
 	}
 	const renderSnapshot = useClientNavigationRenderSnapshot();
 	const pathname = React$1.useSyncExternalStore(subscribeToNavigation, getPathnameSnapshot, () => {
 		const ctx = _getServerContext();
 		if (ctx) return ctx.pathname;
-		const pagesCtx = _getPagesNavigationContext();
+		const pagesCtx = getPagesNavigationContext();
 		return pagesCtx ? pagesCtx.pathname : "/";
 	});
 	if (renderSnapshot && (getClientNavigationState()?.navigationSnapshotActiveCount ?? 0) > 0) return renderSnapshot.pathname;
@@ -827,7 +823,10 @@ function usePathname() {
 * Returns the current search params as a read-only URLSearchParams.
 */
 function useSearchParams() {
-	if (isServer) return getServerSearchParamsSnapshot();
+	if (isServer) {
+		markPprFallbackShellDynamicBoundary();
+		return getServerSearchParamsSnapshot();
+	}
 	const renderSnapshot = useClientNavigationRenderSnapshot();
 	const searchParams = React$1.useSyncExternalStore(subscribeToNavigation, getSearchParamsSnapshot, getServerSearchParamsSnapshot);
 	if (renderSnapshot && (getClientNavigationState()?.navigationSnapshotActiveCount ?? 0) > 0) return renderSnapshot.searchParams;
@@ -837,7 +836,10 @@ function useSearchParams() {
 * Returns the dynamic params for the current route.
 */
 function useParams() {
-	if (isServer) return getServerParamsSnapshot();
+	if (isServer) {
+		markPprFallbackShellDynamicBoundary();
+		return getServerParamsSnapshot();
+	}
 	const renderSnapshot = useClientNavigationRenderSnapshot();
 	const params = React$1.useSyncExternalStore(subscribeToNavigation, getClientParamsSnapshot, getServerParamsSnapshot);
 	if (renderSnapshot && (getClientNavigationState()?.navigationSnapshotActiveCount ?? 0) > 0) return renderSnapshot.params;
@@ -930,8 +932,17 @@ function applyAppRouterScrollFallback(intent) {
 		scrollToHashTarget(intent.hash);
 		return;
 	}
+	if (intent.targetHoistedInHead) return;
 	document.documentElement.scrollTop = 0;
 }
+function scheduleAppRouterScrollFallback(intent) {
+	queueMicrotask(() => {
+		const pendingIntent = getPendingAppRouterScrollIntent();
+		if (pendingIntent === null || pendingIntent.id !== intent.id) return;
+		const fallbackIntent = consumeAppRouterScrollIntent(intent);
+		if (fallbackIntent) applyAppRouterScrollFallback(fallbackIntent);
+	});
+}
 /**
 * Restore scroll position from a history state object (used on popstate).
 *
@@ -958,6 +969,15 @@ function restoreScrollPosition(state) {
 	}
 }
 /**
+* Hard-navigate to a URL via `window.location`, preserving push/replace
+* semantics. Used for URLs the App Router cannot serve (Pages-owned
+* targets in a hybrid build) and for catch-all RSC failures.
+*/
+function hardNavigateTo(fullHref, mode) {
+	if (mode === "replace") window.location.replace(fullHref);
+	else window.location.assign(fullHref);
+}
+/**
 * Navigate to a URL, handling external URLs, hash-only changes, and RSC navigation.
 */
 async function navigateClientSide(href, mode, scroll, programmaticTransition = false, visibleCommitMode = "transition") {
@@ -972,14 +992,23 @@ async function navigateClientSide(href, mode, scroll, programmaticTransition = f
 				await externalNavigate(href, mode);
 				return;
 			}
-			if (mode === "replace") window.location.replace(href);
-			else window.location.assign(href);
+			hardNavigateTo(href, mode);
 			await new Promise(() => {});
 			return;
 		}
 		normalizedHref = localPath;
 	}
+	const hybridOwner = resolveHybridClientRouteOwner(normalizedHref, __basePath);
+	if (hybridOwner === "pages" || hybridOwner === "document") {
+		const fullHref = toBrowserNavigationHref(normalizedHref, window.location.href, __basePath);
+		notifyAppRouterTransitionStart(fullHref, mode);
+		if (mode === "push") saveScrollPosition();
+		hardNavigateTo(fullHref, mode);
+		await new Promise(() => {});
+		return;
+	}
 	const fullHref = toBrowserNavigationHref(normalizedHref, window.location.href, __basePath);
+	stageAppNavigationFailureTarget(fullHref);
 	notifyAppRouterTransitionStart(fullHref, mode);
 	if (mode === "push") saveScrollPosition();
 	const earlyIntent = navigationPlanner.classifyEarlyNavigationIntent({
@@ -990,7 +1019,9 @@ async function navigateClientSide(href, mode, scroll, programmaticTransition = f
 		targetHref: fullHref
 	});
 	if (earlyIntent.kind === "sameDocumentScroll") {
+		clearAppRouterScrollIntent();
 		commitHashOnlyHistoryState(fullHref, earlyIntent.mode, earlyIntent.scroll);
+		clearAppNavigationFailureTarget(fullHref);
 		commitClientNavigationState();
 		if (earlyIntent.scroll) scrollToHashTarget(earlyIntent.hash);
 		return;
@@ -1001,8 +1032,7 @@ async function navigateClientSide(href, mode, scroll, programmaticTransition = f
 			await mpaNavigate(fullHref, mode);
 			return;
 		}
-		if (mode === "replace") window.location.replace(fullHref);
-		else window.location.assign(fullHref);
+		hardNavigateTo(fullHref, mode);
 		await new Promise(() => {});
 		return;
 	}
@@ -1022,10 +1052,7 @@ async function navigateClientSide(href, mode, scroll, programmaticTransition = f
 		if (scrollIntent) consumeAppRouterScrollIntent(scrollIntent);
 		throw error;
 	}
-	if (scrollIntent) {
-		const fallbackIntent = consumeAppRouterScrollIntent(scrollIntent);
-		if (fallbackIntent) applyAppRouterScrollFallback(fallbackIntent);
-	}
+	if (scrollIntent) scheduleAppRouterScrollFallback(scrollIntent);
 }
 let scheduledAppRouterNavigationCount = 0;
 function trackScheduledAppRouterNavigation() {
@@ -1057,6 +1084,7 @@ const _appRouter = {
 	push(href, options) {
 		assertSafeNavigationUrl(href);
 		if (isServer) return;
+		getNavigationRuntime()?.functions.notifyLinkNavigationStart?.();
 		const releaseNavigation = trackScheduledAppRouterNavigation();
 		try {
 			React$1.startTransition(() => {
@@ -1071,6 +1099,7 @@ const _appRouter = {
 	replace(href, options) {
 		assertSafeNavigationUrl(href);
 		if (isServer) return;
+		getNavigationRuntime()?.functions.notifyLinkNavigationStart?.();
 		const releaseNavigation = trackScheduledAppRouterNavigation();
 		try {
 			React$1.startTransition(() => {
@@ -1117,6 +1146,8 @@ const _appRouter = {
 				if (localPath == null) return;
 				prefetchHref = localPath;
 			}
+			const hybridOwner = resolveHybridClientRouteOwner(prefetchHref, __basePath);
+			if (hybridOwner === "pages" || hybridOwner === "document") return;
 			const fullHref = toBrowserNavigationHref(prefetchHref, window.location.href, __basePath);
 			const interceptionContext = getPrefetchInterceptionContext(fullHref);
 			const mountedSlotsHeader = getMountedSlotsHeader();
@@ -1220,6 +1251,7 @@ function useSelectedLayoutSegment(parallelRoutesKey) {
 * @param parallelRoutesKey - Which parallel route to read (default: "children")
 */
 function useSelectedLayoutSegments(parallelRoutesKey) {
+	if (isServer) markPprFallbackShellDynamicBoundary();
 	return useChildSegments(parallelRoutesKey);
 }
 /**
@@ -1602,4 +1634,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, createSnapshotPathAndSearch, 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 };
+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, applyAppRouterScrollFallback, clearPendingPathname, clearServerInsertedHTML, commitClientNavigationState, consumePrefetchResponse, consumePrefetchResponseForNavigation, createCachedRscResponseSnapshot, createClientNavigationRenderSnapshot, createSnapshotPathAndSearch, 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, useClientNavigationRenderSnapshot, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };

package/dist/shims/ppr-fallback-shell.d.ts

@@ -1,10 +1,12 @@
 //#region src/shims/ppr-fallback-shell.d.ts
 type PprFallbackShellState = {
   abortController: AbortController;
+  reactAbortController: AbortController;
   cacheEpoch: number;
   cacheReadyResolvers: Array<() => void>;
   fallbackParamNames: ReadonlySet<string>;
   hasDynamicBoundary: boolean;
+  isFinalRenderStarted: boolean;
   isAbortScheduled: boolean;
   pendingAbortCleanup: (() => void) | null;
   pendingCacheReadyCleanup: (() => void) | null;
@@ -21,9 +23,11 @@ declare function runWithPprFallbackShellState<T>(state: PprFallbackShellState, f
 declare function getPprFallbackShellState(): PprFallbackShellState | null;
 declare function trackPprFallbackShellCacheTask<T>(fn: () => Promise<T>, cacheVariant: string): Promise<T>;
 declare function createPprFallbackShellSuspensePromiseForState<T>(state: PprFallbackShellState, expression: string): Promise<T>;
+declare function markPprFallbackShellDynamicBoundary(): void;
 declare function createPprFallbackShellSuspensePromise<T>(expression: string): Promise<T> | null;
 declare function waitForPprFallbackShellCacheReady(state: PprFallbackShellState): Promise<void>;
 declare function preparePprFallbackShellFinalRender(state: PprFallbackShellState): void;
+declare function beginPprFallbackShellFinalRender(state: PprFallbackShellState): void;
 declare function isPprFallbackShellAbortError(error: unknown): boolean;
 //#endregion
-export { PprFallbackShellState, createPprFallbackShellState, createPprFallbackShellSuspensePromise, createPprFallbackShellSuspensePromiseForState, getPprFallbackShellState, isPprFallbackShellAbortError, preparePprFallbackShellFinalRender, runWithPprFallbackShellState, trackPprFallbackShellCacheTask, waitForPprFallbackShellCacheReady };
+export { PprFallbackShellState, beginPprFallbackShellFinalRender, createPprFallbackShellState, createPprFallbackShellSuspensePromise, createPprFallbackShellSuspensePromiseForState, getPprFallbackShellState, isPprFallbackShellAbortError, markPprFallbackShellDynamicBoundary, preparePprFallbackShellFinalRender, runWithPprFallbackShellState, trackPprFallbackShellCacheTask, waitForPprFallbackShellCacheReady };

package/dist/shims/ppr-fallback-shell.js

@@ -43,12 +43,15 @@ function scheduleCacheReadyIfSettled(state) {
 	});
 }
 function scheduleAbortIfReady(state) {
-	if (state.phase !== "final" || !state.hasDynamicBoundary || state.pendingCacheTasks > 0 || state.pendingCacheReadyCleanup !== null || state.isAbortScheduled) return;
+	if (state.phase !== "final" || !state.isFinalRenderStarted || !state.hasDynamicBoundary || state.pendingCacheTasks > 0 || state.pendingCacheReadyCleanup !== null || state.isAbortScheduled) return;
 	state.isAbortScheduled = true;
 	state.pendingAbortCleanup = scheduleAfterTask(() => {
 		state.pendingAbortCleanup = null;
 		state.isAbortScheduled = false;
-		if (state.phase === "final" && state.hasDynamicBoundary && state.pendingCacheTasks === 0 && state.pendingCacheReadyCleanup === null && !state.abortController.signal.aborted) state.abortController.abort();
+		if (state.phase === "final" && state.hasDynamicBoundary && state.pendingCacheTasks === 0 && state.pendingCacheReadyCleanup === null && !state.reactAbortController.signal.aborted) {
+			state.reactAbortController.abort();
+			state.abortController.abort();
+		}
 	});
 }
 function completeCacheTask(state, task) {
@@ -64,12 +67,15 @@ function ignoreCacheTask(state, task) {
 	completeCacheTask(state, task);
 }
 function createPprFallbackShellState(options) {
+	const abortController = new AbortController();
 	return {
-		abortController: new AbortController(),
+		abortController,
+		reactAbortController: abortController,
 		cacheEpoch: 0,
 		cacheReadyResolvers: [],
 		fallbackParamNames: new Set(options.fallbackParamNames),
 		hasDynamicBoundary: false,
+		isFinalRenderStarted: false,
 		isAbortScheduled: false,
 		pendingAbortCleanup: null,
 		pendingCacheReadyCleanup: null,
@@ -107,14 +113,22 @@ function trackPprFallbackShellCacheTask(fn, cacheVariant) {
 	});
 }
 function createPprFallbackShellSuspensePromiseForState(state, expression) {
-	state.hasDynamicBoundary = true;
-	for (const task of pprFallbackShellCacheTaskStackAls.getStore() ?? []) ignoreCacheTask(state, task);
-	scheduleCacheReadyIfSettled(state);
+	markPprFallbackShellDynamicBoundaryForState(state);
 	if (state.phase === "final") scheduleAbortIfReady(state);
 	const promise = makeHangingPromise(state.abortController.signal, state.routePattern, expression);
 	promise.catch(noop);
 	return promise;
 }
+function markPprFallbackShellDynamicBoundaryForState(state) {
+	state.hasDynamicBoundary = true;
+	for (const task of pprFallbackShellCacheTaskStackAls.getStore() ?? []) ignoreCacheTask(state, task);
+	scheduleCacheReadyIfSettled(state);
+}
+function markPprFallbackShellDynamicBoundary() {
+	const state = getPprFallbackShellState();
+	if (state === null || state.fallbackParamNames.size === 0) return;
+	markPprFallbackShellDynamicBoundaryForState(state);
+}
 function createPprFallbackShellSuspensePromise(expression) {
 	const state = getPprFallbackShellState();
 	if (state === null) return null;
@@ -134,16 +148,23 @@ function preparePprFallbackShellFinalRender(state) {
 		state.pendingAbortCleanup = null;
 	}
 	state.abortController = new AbortController();
+	state.reactAbortController = new AbortController();
 	state.cacheEpoch++;
 	state.cacheReadyResolvers.length = 0;
 	state.hasDynamicBoundary = false;
+	state.isFinalRenderStarted = false;
 	state.isAbortScheduled = false;
 	state.pendingCacheTasks = 0;
 	state.phase = "final";
 }
+function beginPprFallbackShellFinalRender(state) {
+	if (state.phase !== "final") return;
+	state.isFinalRenderStarted = true;
+	scheduleAbortIfReady(state);
+}
 function isPprFallbackShellAbortError(error) {
 	if (typeof DOMException !== "undefined" && error instanceof DOMException && error.name === "AbortError") return true;
 	return error instanceof Error && error.name === "HangingPromiseRejectionError";
 }
 //#endregion
-export { createPprFallbackShellState, createPprFallbackShellSuspensePromise, createPprFallbackShellSuspensePromiseForState, getPprFallbackShellState, isPprFallbackShellAbortError, preparePprFallbackShellFinalRender, runWithPprFallbackShellState, trackPprFallbackShellCacheTask, waitForPprFallbackShellCacheReady };
+export { beginPprFallbackShellFinalRender, createPprFallbackShellState, createPprFallbackShellSuspensePromise, createPprFallbackShellSuspensePromiseForState, getPprFallbackShellState, isPprFallbackShellAbortError, markPprFallbackShellDynamicBoundary, preparePprFallbackShellFinalRender, runWithPprFallbackShellState, trackPprFallbackShellCacheTask, waitForPprFallbackShellCacheReady };

package/dist/shims/router.d.ts

@@ -34,11 +34,15 @@ type NextRouter = {
 type UrlObject = {
   pathname?: string;
   query?: UrlQuery;
+  search?: string;
+  hash?: string;
 };
 type TransitionOptions = {
+  _h?: 1;
   shallow?: boolean;
   scroll?: boolean;
   locale?: string | false;
+  _vinextInterpolateDynamicRoute?: boolean;
 };
 type RouterEvents = {
   on(event: string, handler: (...args: unknown[]) => void): void;
@@ -49,7 +53,7 @@ type RouterEvents = {
  * Apply locale prefix to a URL for client-side navigation.
  * Same logic as Link's applyLocaleToHref but reads from window globals.
  */
-declare function applyNavigationLocale(url: string, locale?: string): string;
+declare function applyNavigationLocale(url: string, locale?: string, replaceExistingLocale?: boolean): string;
 /** Check if a URL is external (any URL scheme per RFC 3986, or protocol-relative) */
 declare function isExternalUrl(url: string): boolean;
 /** Check if a href is only a hash change relative to the current URL */
@@ -108,6 +112,8 @@ type PagesNavigationContextShape = {
  */
 declare function getPagesNavigationContext(): PagesNavigationContextShape | null;
 declare function getPagesNavigationIsReadyFromSerializedState(routePattern: string | undefined, searchString: string, nextData?: VinextNextData): boolean;
+declare function markPagesRouterReady(): boolean;
+declare function initializePagesRouterReadyFromNextData(nextData: VinextNextData): void;
 /**
  * useRouter hook - Pages Router compatible.
  *
@@ -122,8 +128,17 @@ declare function useRouter(): NextRouter;
  * The provider owns the reactive Pages Router snapshot so next/router and
  * next/compat/router consumers share one context value instead of each hook
  * installing its own global URL-change listener.
+ *
+ * The PagesRouterCommitBoundary exists for client navigations: its layout
+ * callback runs scroll restoration at commit time and resolves the navigation
+ * at the same root-commit boundary Next.js awaits before routeChangeComplete.
+ * Its onError rejection drives the hard-navigation fallback in runNavigateClient.
+ * The same boundary intentionally also wraps SSR and initial hydration, where
+ * callbacks default to noopCommit: a hydration-time render error is caught
+ * here (React still console.error's it) instead of propagating, matching the
+ * navigation-path containment.
  */
-declare function wrapWithRouterContext(element: ReactElement): ReactElement;
+declare function wrapWithRouterContext(element: ReactElement, onCommit?: () => void, onError?: (error: Error) => void): ReactElement;
 /**
  * Props injected by `withRouter` into the wrapped component.
  *
@@ -176,4 +191,4 @@ declare const RouterMethods: {
 };
 declare const Router: typeof RouterMethods & Omit<NextRouter, keyof typeof RouterMethods>;
 //#endregion
-export { ExcludeRouterProps, NextRouter, WithRouterProps, _registerRouterStateAccessors, applyNavigationLocale, Router as default, getPagesNavigationContext, getPagesNavigationIsReadyFromSerializedState, isExternalUrl, isHashOnlyChange, setSSRContext, useRouter, withRouter, wrapWithRouterContext };
+export { ExcludeRouterProps, NextRouter, WithRouterProps, initializePagesRouterReadyFromNextData as _initializePagesRouterReadyFromNextData, markPagesRouterReady as _markPagesRouterReady, _registerRouterStateAccessors, applyNavigationLocale, Router as default, getPagesNavigationContext, getPagesNavigationIsReadyFromSerializedState, isExternalUrl, isHashOnlyChange, setSSRContext, useRouter, withRouter, wrapWithRouterContext };