vinext 0.1.2 → 0.1.3

package/dist/shims/internal/navigation-untracked.js

@@ -0,0 +1,55 @@
+import { getPagesNavigationContext } from "./pages-router-accessor.js";
+import { getClientNavigationState, getNavigationContext, useClientNavigationRenderSnapshot } from "../navigation.js";
+//#region src/shims/internal/navigation-untracked.ts
+/**
+* Internal navigation-untracked pathname hook.
+*
+* Used by `unstable_catchError` error boundaries to avoid subscribing to
+* pathname changes. This is NOT part of the public `next/navigation` API.
+*
+* Ported from Next.js:
+*   https://github.com/vercel/next.js/blob/v16.2.6/packages/next/src/client/components/navigation-untracked.ts
+*/
+const isServer = typeof window === "undefined";
+function getPathnameSnapshot() {
+	const pagesCtx = getPagesNavigationContext();
+	if (pagesCtx) return pagesCtx.pathname;
+	return getClientNavigationState()?.cachedPathname ?? "/";
+}
+/**
+* Returns the current pathname without registering it as a tracked render
+* dependency. Unlike `usePathname()`, this does not use `useSyncExternalStore`
+* and therefore does not cause the component to re-render on navigation.
+*
+* Server: returns the pathname from context, or `"/"` when no navigation context
+* is available (the client will hydrate with the real value). The `"/"` fallback
+* deliberately matches vinext's `usePathname()` behavior rather than Next.js's
+* null context default. Returns `null` only when the render is a missing-params
+* shell — vinext does not yet implement fallback-route-param detection, so this
+* path is not currently reachable.
+*
+* Client: prefers the render snapshot **only during an active navigation**
+* transition (`navigationSnapshotActiveCount > 0`) so the hook returns the
+* pending URL, not the stale committed one. After commit, falls back to the
+* cached pathname so user `pushState`/`replaceState` calls are immediately
+* reflected.
+*
+* Used by `unstable_catchError` error boundaries to avoid unnecessary re-renders.
+*
+* @internal
+*/
+function useUntrackedPathname() {
+	if (isServer) {
+		const ctx = getNavigationContext();
+		if (ctx) return ctx.pathname;
+		const pagesCtx = getPagesNavigationContext();
+		return pagesCtx ? pagesCtx.pathname : "/";
+	}
+	const renderSnapshot = useClientNavigationRenderSnapshot();
+	if (renderSnapshot && (getClientNavigationState()?.navigationSnapshotActiveCount ?? 0) > 0) return renderSnapshot.pathname;
+	const pagesCtx = getPagesNavigationContext();
+	if (pagesCtx) return pagesCtx.pathname;
+	return getPathnameSnapshot();
+}
+//#endregion
+export { useUntrackedPathname };

package/dist/shims/internal/pages-data-target.d.ts

@@ -43,10 +43,15 @@ type PagesDataTarget = {
  */
 declare function resolvePagesDataNavigationTarget(browserUrl: string, basePath: string): PagesDataTarget | null;
 /**
- * Inject a `<link rel="prefetch">` for the data JSON and kick off the
- * code-split loader so the chunk is warm by the time the user clicks.
+ * Prefetch the data JSON and kick off the code-split loader so the chunk is
+ * warm by the time the user clicks.
  *
  * Used by both `Router.prefetch()` and `<Link>` hover/viewport prefetch. The
+ * JSON request uses `fetch()` rather than `<link rel="prefetch">` so it can
+ * carry Next.js's `x-deployment-id` skew-protection header. The in-flight
+ * request is shared with a racing navigation; after it settles, the browser's
+ * normal HTTP cache remains responsible for reuse.
+ *
  * loader's returned Promise is intentionally discarded — `import()` caches the
  * result, so a subsequent navigation re-invocation hits the cache without
  * paying for a second round trip. Errors are swallowed: prefetch is

package/dist/shims/internal/pages-data-target.js

@@ -1,6 +1,8 @@
 import { stripBasePath } from "../../utils/base-path.js";
 import { getLocalePathPrefix } from "../../utils/domain-locale.js";
 import { buildPagesDataHref, matchPagesPattern } from "./pages-data-url.js";
+import { dedupedPagesDataFetch } from "./pages-data-fetch-dedup.js";
+import { NEXT_DEPLOYMENT_ID_HEADER, getDeploymentId } from "../../utils/deployment-id.js";
 //#region src/shims/internal/pages-data-target.ts
 /**
 * Shared decision helper for the Pages Router `/_next/data/<id>/<page>.json`
@@ -66,10 +68,15 @@ function resolvePagesDataNavigationTarget(browserUrl, basePath) {
 	};
 }
 /**
-* Inject a `<link rel="prefetch">` for the data JSON and kick off the
-* code-split loader so the chunk is warm by the time the user clicks.
+* Prefetch the data JSON and kick off the code-split loader so the chunk is
+* warm by the time the user clicks.
 *
 * Used by both `Router.prefetch()` and `<Link>` hover/viewport prefetch. The
+* JSON request uses `fetch()` rather than `<link rel="prefetch">` so it can
+* carry Next.js's `x-deployment-id` skew-protection header. The in-flight
+* request is shared with a racing navigation; after it settles, the browser's
+* normal HTTP cache remains responsible for reuse.
+*
 * loader's returned Promise is intentionally discarded — `import()` caches the
 * result, so a subsequent navigation re-invocation hits the cache without
 * paying for a second round trip. Errors are swallowed: prefetch is
@@ -77,12 +84,14 @@ function resolvePagesDataNavigationTarget(browserUrl, basePath) {
 */
 function prefetchPagesData(target) {
 	if (typeof document === "undefined") return;
-	const link = document.createElement("link");
-	link.rel = "prefetch";
-	link.as = "fetch";
-	link.crossOrigin = "anonymous";
-	link.href = target.dataHref;
-	document.head.appendChild(link);
+	const headers = {
+		Accept: "application/json",
+		purpose: "prefetch",
+		"x-nextjs-data": "1"
+	};
+	const deploymentId = getDeploymentId();
+	if (deploymentId) headers[NEXT_DEPLOYMENT_ID_HEADER] = deploymentId;
+	dedupedPagesDataFetch(target.dataHref, { headers }).catch(() => {});
 	target.loader().catch(() => {});
 }
 //#endregion

package/dist/shims/internal/pages-router-accessor.d.ts

@@ -0,0 +1,19 @@
+//#region src/shims/internal/pages-router-accessor.d.ts
+/**
+ * Shared Pages Router navigation accessor.
+ *
+ * Both `next/navigation` (usePathname/useParams/useSearchParams) and the
+ * internal `useUntrackedPathname` read from the same global Symbol. Keeping
+ * the lookup in one place avoids the Symbol string and the error-handling
+ * shape from drifting across modules.
+ *
+ * @internal
+ */
+type PagesNavigationContext = {
+  pathname: string | null;
+  searchParams: URLSearchParams;
+  params: Record<string, string | string[]> | null;
+};
+declare function getPagesNavigationContext(): PagesNavigationContext | null;
+//#endregion
+export { PagesNavigationContext, getPagesNavigationContext };

package/dist/shims/internal/pages-router-accessor.js

@@ -0,0 +1,13 @@
+//#region src/shims/internal/pages-router-accessor.ts
+const PAGES_NAVIGATION_ACCESSOR_KEY = Symbol.for("vinext.navigation.pagesNavigationContextAccessor");
+function getPagesNavigationContext() {
+	const accessor = globalThis[PAGES_NAVIGATION_ACCESSOR_KEY];
+	if (!accessor) return null;
+	try {
+		return accessor();
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { getPagesNavigationContext };

package/dist/shims/internal/router-context.d.ts

@@ -1,6 +1,7 @@
 import { NextRouter } from "../router.js";
+import { Context } from "react";
 
 //#region src/shims/internal/router-context.d.ts
-declare const RouterContext: import("react").Context<NextRouter | null>;
+declare const RouterContext: Context<NextRouter | null>;
 //#endregion
 export { RouterContext };

package/dist/shims/internal/router-context.js

@@ -6,6 +6,8 @@ import { createContext } from "react";
 * Used by: some testing utilities and older libraries.
 * Provides the Pages Router context.
 */
-const RouterContext = createContext(null);
+const ROUTER_CONTEXT_KEY = Symbol.for("vinext.routerContext");
+const globalState = globalThis;
+const RouterContext = globalState[ROUTER_CONTEXT_KEY] ?? (globalState[ROUTER_CONTEXT_KEY] = createContext(null));
 //#endregion
 export { RouterContext };

package/dist/shims/link.js

@@ -8,9 +8,10 @@ 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";
@@ -122,7 +123,7 @@ function getLinkPrefetchRouterMode() {
 }
 function resolveMatchedAutoAppRoutePrefetch(route) {
 	return {
-		cacheForNavigation: !(route.isDynamic && route.canPrefetchLoadingShell),
+		cacheForNavigation: !route.canPrefetchLoadingShell,
 		prefetchShellFirst: !route.isDynamic,
 		shouldPrefetch: true
 	};
@@ -189,6 +190,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,7 +493,6 @@ 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);
 		if (onNavigate) try {
 			const navUrl = new URL(absoluteFullHref, window.location.origin);
@@ -507,6 +509,11 @@ const Link = forwardRef(function Link({ href, as, replace = false, prefetch: pre
 			onNavigate(navEvent);
 			if (navEvent.defaultPrevented) return;
 		} catch {}
+		if (getNavigationRuntime()?.functions.navigate && ["pages", "document"].includes(resolveHybridClientRouteOwner(navigateHref, __basePath) ?? "")) {
+			if (replace) window.location.replace(absoluteFullHref);
+			else window.location.assign(absoluteFullHref);
+			return;
+		}
 		if (getNavigationRuntime()?.functions.navigate) {
 			const setter = setPendingRef.current;
 			if (setter) setLinkForCurrentNavigation(setter);
@@ -521,7 +528,7 @@ const Link = forwardRef(function Link({ href, as, replace = false, prefetch: pre
 		} else try {
 			const Router = (await import("next/router.js")).default;
 			await navigatePagesRouterLink(Router, {
-				href: absoluteHref,
+				href: navigateHref,
 				replace,
 				scroll,
 				shallow,

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() {
@@ -1117,6 +1144,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 +1249,7 @@ function useSelectedLayoutSegment(parallelRoutesKey) {
 * @param parallelRoutesKey - Which parallel route to read (default: "children")
 */
 function useSelectedLayoutSegments(parallelRoutesKey) {
+	if (isServer) markPprFallbackShellDynamicBoundary();
 	return useChildSegments(parallelRoutesKey);
 }
 /**
@@ -1602,4 +1632,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 };