vinext 0.1.2 → 0.1.3

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

@@ -0,0 +1,9 @@
+//#region src/shims/error.react-server.d.ts
+type ErrorInfo = {
+  error: unknown;
+  reset: () => void;
+  unstable_retry: () => void;
+};
+declare function unstable_catchError(): never;
+//#endregion
+export { ErrorInfo, unstable_catchError };

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

@@ -0,0 +1,6 @@
+//#region src/shims/error.react-server.ts
+function unstable_catchError() {
+	throw new Error("`unstable_catchError` can only be used in Client Components.");
+}
+//#endregion
+export { unstable_catchError };

package/dist/shims/fetch-cache.d.ts

@@ -40,6 +40,7 @@ type FetchCacheState = {
   currentRequestTags: string[];
   currentFetchSoftTags: string[];
   currentFetchCacheMode: FetchCacheMode | null;
+  currentForceDynamicFetchDefault: boolean;
   dynamicFetchUrls: Set<string>;
   isFetchDedupeActive: boolean;
   currentFetchDedupeEntries: Map<string, FetchDedupeEntry[]>;
@@ -84,6 +85,7 @@ declare function setCurrentFetchSoftTags(tags: string[]): void;
  */
 declare function getCurrentFetchSoftTags(): string[];
 declare function setCurrentFetchCacheMode(mode: FetchCacheMode | null): void;
+declare function setCurrentForceDynamicFetchDefault(enabled: boolean): void;
 /**
  * Install the patched fetch and reset per-request tag state.
  * Returns a cleanup function that clears tags.
@@ -131,4 +133,4 @@ declare function ensureFetchPatch(): void;
  */
 declare function getOriginalFetch(): typeof globalThis.fetch;
 //#endregion
-export { FetchCacheMode, FetchCacheState, _resetPendingRefetches, addCollectedRequestTags, consumeDynamicFetchObservations, ensureFetchPatch, getCollectedFetchTags, getCurrentFetchSoftTags, getOriginalFetch, peekCacheableFetchObservations, peekDynamicFetchObservations, runWithFetchCache, runWithFetchDedupe, setCurrentFetchCacheMode, setCurrentFetchSoftTags, withFetchCache };
+export { FetchCacheMode, FetchCacheState, _resetPendingRefetches, addCollectedRequestTags, consumeDynamicFetchObservations, ensureFetchPatch, getCollectedFetchTags, getCurrentFetchSoftTags, getOriginalFetch, peekCacheableFetchObservations, peekDynamicFetchObservations, runWithFetchCache, runWithFetchDedupe, setCurrentFetchCacheMode, setCurrentFetchSoftTags, setCurrentForceDynamicFetchDefault, withFetchCache };

package/dist/shims/fetch-cache.js

@@ -1,6 +1,7 @@
 import { getOrCreateAls } from "./internal/als-registry.js";
 import { getRequestContext, isInsideUnifiedScope, runWithUnifiedStateMutation } from "./unified-request-context.js";
 import { getRequestExecutionContext } from "./request-context.js";
+import { markDynamicUsage } from "./headers.js";
 import { encodeCacheTags } from "../utils/encode-cache-tag.js";
 import { getDataCacheHandler } from "./cache.js";
 //#region src/shims/fetch-cache.ts
@@ -32,6 +33,7 @@ import { getDataCacheHandler } from "./cache.js";
 const HEADER_BLOCKLIST = ["traceparent", "tracestate"];
 const CACHE_KEY_PREFIX = "v3";
 const MAX_CACHE_KEY_BODY_BYTES = 1024 * 1024;
+const ONE_YEAR_SECONDS = 31536e3;
 var BodyTooLargeForCacheKeyError = class extends Error {
 	constructor() {
 		super("Fetch body too large for cache key generation");
@@ -292,6 +294,7 @@ const _fallbackState = _g[_FALLBACK_KEY] ??= {
 	currentRequestTags: [],
 	currentFetchSoftTags: [],
 	currentFetchCacheMode: null,
+	currentForceDynamicFetchDefault: false,
 	dynamicFetchUrls: /* @__PURE__ */ new Set(),
 	isFetchDedupeActive: false,
 	currentFetchDedupeEntries: /* @__PURE__ */ new Map()
@@ -309,6 +312,7 @@ function _resetFallbackState(isFetchDedupeActive) {
 	_fallbackState.currentRequestTags = [];
 	_fallbackState.currentFetchSoftTags = [];
 	_fallbackState.currentFetchCacheMode = null;
+	_fallbackState.currentForceDynamicFetchDefault = false;
 	_fallbackState.dynamicFetchUrls = /* @__PURE__ */ new Set();
 	_fallbackState.isFetchDedupeActive = isFetchDedupeActive;
 	_fallbackState.currentFetchDedupeEntries = /* @__PURE__ */ new Map();
@@ -319,6 +323,10 @@ function getFetchObservationUrl(input) {
 function recordDynamicFetchObservation(input) {
 	_getState().dynamicFetchUrls.add(getFetchObservationUrl(input));
 }
+function markUncachedFetchForPageOutput(input) {
+	recordDynamicFetchObservation(input);
+	markDynamicUsage();
+}
 function recordCacheableFetchObservation(input) {
 	_getState().cacheableFetchUrls.add(getFetchObservationUrl(input));
 }
@@ -382,16 +390,23 @@ function getCurrentFetchSoftTags() {
 function setCurrentFetchCacheMode(mode) {
 	_getState().currentFetchCacheMode = mode;
 }
+function setCurrentForceDynamicFetchDefault(enabled) {
+	_getState().currentForceDynamicFetchDefault = enabled;
+}
 function isNoStoreFetch(cacheDirective, nextOpts) {
-	return cacheDirective === "no-store" || cacheDirective === "no-cache" || nextOpts?.revalidate === false || nextOpts?.revalidate === 0;
+	return cacheDirective === "no-store" || cacheDirective === "no-cache" || nextOpts?.revalidate === 0;
 }
 function isCacheableFetch(cacheDirective, nextOpts) {
-	return cacheDirective === "force-cache" || typeof nextOpts?.revalidate === "number" && nextOpts.revalidate > 0;
+	return cacheDirective === "force-cache" || nextOpts?.revalidate === false || typeof nextOpts?.revalidate === "number" && nextOpts.revalidate > 0;
 }
 function hasExplicitRevalidateValue(nextOpts) {
 	return nextOpts?.revalidate !== void 0;
 }
-function resolveSegmentCacheDirective(cacheDirective, nextOpts, mode) {
+function isFalsyRevalidate(nextOpts) {
+	return !nextOpts?.revalidate;
+}
+function resolveSegmentCacheDirective(cacheDirective, nextOpts, mode, forceDynamicFetchDefault) {
+	if (forceDynamicFetchDefault && (!mode || mode === "auto") && (cacheDirective === void 0 || cacheDirective === "default") && isFalsyRevalidate(nextOpts)) return "no-store";
 	if (!mode || mode === "auto") return cacheDirective;
 	switch (mode) {
 		case "force-cache": return "force-cache";
@@ -457,6 +472,20 @@ function cloneDedupeResponse(response) {
 	const [body1, body2] = response.body.tee();
 	return [buildDedupeClone(body1, response), buildDedupeClone(body2, response)];
 }
+function buildCachedFetchResponse(data, input) {
+	const response = new Response(data.body, {
+		status: data.status ?? 200,
+		headers: data.headers
+	});
+	Object.defineProperty(response, "url", {
+		value: data.url ?? getFetchObservationUrl(input),
+		configurable: true,
+		enumerable: true,
+		writable: false
+	});
+	if (_responseBodyRegistry && response.body) _responseBodyRegistry.register(response, new WeakRef(response.body));
+	return response;
+}
 function dedupeFetch(input, init) {
 	const state = _getState();
 	if (!state.isFetchDedupeActive) return originalFetch(input, init);
@@ -507,25 +536,26 @@ function dedupeFetch(input, init) {
 function createPatchedFetch() {
 	return async function patchedFetch(input, init) {
 		const nextOpts = init?.next;
-		const cacheDirective = resolveSegmentCacheDirective(getFetchCacheDirective(input, init), nextOpts, _getState().currentFetchCacheMode);
+		const cacheDirective = resolveSegmentCacheDirective(getFetchCacheDirective(input, init), nextOpts, _getState().currentFetchCacheMode, _getState().currentForceDynamicFetchDefault);
 		if (!nextOpts && !cacheDirective) {
 			recordDynamicFetchObservation(input);
 			return dedupeFetch(input, init);
 		}
-		if (cacheDirective === "no-store" || cacheDirective === "no-cache" || nextOpts?.revalidate === false || nextOpts?.revalidate === 0) {
+		if (cacheDirective === "no-store" || cacheDirective === "no-cache" || nextOpts?.revalidate === 0) {
 			const cleanInit = stripNextFromInit(init, cacheDirective);
-			recordDynamicFetchObservation(input);
+			markUncachedFetchForPageOutput(input);
 			return dedupeFetch(input, cleanInit);
 		}
-		if (!(cacheDirective === "force-cache" || typeof nextOpts?.revalidate === "number" && nextOpts.revalidate > 0) && hasAuthHeaders(input, init)) {
+		if (!(cacheDirective === "force-cache" || nextOpts?.revalidate === false || typeof nextOpts?.revalidate === "number" && nextOpts.revalidate > 0) && hasAuthHeaders(input, init)) {
 			const cleanInit = stripNextFromInit(init, cacheDirective);
 			recordDynamicFetchObservation(input);
 			return dedupeFetch(input, cleanInit);
 		}
 		let revalidateSeconds;
-		if (cacheDirective === "force-cache") revalidateSeconds = nextOpts?.revalidate && typeof nextOpts.revalidate === "number" ? nextOpts.revalidate : 31536e3;
+		if (cacheDirective === "force-cache") revalidateSeconds = nextOpts?.revalidate && typeof nextOpts.revalidate === "number" ? nextOpts.revalidate : ONE_YEAR_SECONDS;
+		else if (nextOpts?.revalidate === false) revalidateSeconds = ONE_YEAR_SECONDS;
 		else if (typeof nextOpts?.revalidate === "number" && nextOpts.revalidate > 0) revalidateSeconds = nextOpts.revalidate;
-		else if (nextOpts?.tags && nextOpts.tags.length > 0) revalidateSeconds = 31536e3;
+		else if (nextOpts?.tags && nextOpts.tags.length > 0) revalidateSeconds = ONE_YEAR_SECONDS;
 		else {
 			const cleanInit = stripNextFromInit(init, cacheDirective);
 			recordDynamicFetchObservation(input);
@@ -560,10 +590,7 @@ function createPatchedFetch() {
 			});
 			if (cached?.value && cached.value.kind === "FETCH" && cached.cacheState !== "stale") {
 				const cachedData = cached.value.data;
-				return new Response(cachedData.body, {
-					status: cachedData.status ?? 200,
-					headers: cachedData.headers
-				});
+				return buildCachedFetchResponse(cachedData, input);
 			}
 			if (cached?.value && cached.value.kind === "FETCH" && cached.cacheState === "stale") {
 				const staleData = cached.value.data;
@@ -581,7 +608,7 @@ function createPatchedFetch() {
 							data: {
 								headers: freshHeaders,
 								body: freshBody,
-								url: typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url,
+								url: freshResp.url,
 								status: freshResp.status
 							},
 							tags,
@@ -605,10 +632,7 @@ function createPatchedFetch() {
 					}, DEDUP_TIMEOUT_MS);
 					getRequestExecutionContext()?.waitUntil(refetchPromise);
 				}
-				return new Response(staleData.body, {
-					status: staleData.status ?? 200,
-					headers: staleData.headers
-				});
+				return buildCachedFetchResponse(staleData, input);
 			}
 		} catch (cacheErr) {
 			console.error("[vinext] fetch cache read error:", cacheErr);
@@ -627,7 +651,7 @@ function createPatchedFetch() {
 				data: {
 					headers,
 					body,
-					url: typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url,
+					url: response.url,
 					status: cloned.status
 				},
 				tags,
@@ -700,6 +724,7 @@ async function runWithFetchCache(fn) {
 		currentRequestTags: [],
 		currentFetchSoftTags: [],
 		currentFetchCacheMode: null,
+		currentForceDynamicFetchDefault: false,
 		dynamicFetchUrls: /* @__PURE__ */ new Set(),
 		isFetchDedupeActive: true,
 		currentFetchDedupeEntries: /* @__PURE__ */ new Map()
@@ -738,4 +763,4 @@ function getOriginalFetch() {
 	return originalFetch;
 }
 //#endregion
-export { _resetPendingRefetches, addCollectedRequestTags, consumeDynamicFetchObservations, ensureFetchPatch, getCollectedFetchTags, getCurrentFetchSoftTags, getOriginalFetch, peekCacheableFetchObservations, peekDynamicFetchObservations, runWithFetchCache, runWithFetchDedupe, setCurrentFetchCacheMode, setCurrentFetchSoftTags, withFetchCache };
+export { _resetPendingRefetches, addCollectedRequestTags, consumeDynamicFetchObservations, ensureFetchPatch, getCollectedFetchTags, getCurrentFetchSoftTags, getOriginalFetch, peekCacheableFetchObservations, peekDynamicFetchObservations, runWithFetchCache, runWithFetchDedupe, setCurrentFetchCacheMode, setCurrentFetchSoftTags, setCurrentForceDynamicFetchDefault, withFetchCache };

package/dist/shims/hash-scroll.js

@@ -17,7 +17,12 @@ function scrollToHashTarget(hash) {
 		idElement.scrollIntoView({ behavior: "auto" });
 		return;
 	}
-	document.getElementsByName(fragment)[0]?.scrollIntoView({ behavior: "auto" });
+	const namedElement = document.getElementsByName(fragment)[0];
+	if (namedElement) {
+		namedElement.scrollIntoView({ behavior: "auto" });
+		return;
+	}
+	window.scrollTo(0, 0);
 }
 function scrollToHashTargetOnNextFrame(hash) {
 	requestAnimationFrame(() => {

package/dist/shims/headers.js

@@ -3,7 +3,8 @@ import { getRequestContext, isInsideUnifiedScope, runWithUnifiedStateMutation }
 import { MIDDLEWARE_SET_COOKIE_HEADER } from "../server/headers.js";
 import { buildRequestHeadersFromMiddlewareResponse } from "../server/middleware-request-headers.js";
 import { serializeSetCookie, validateCookieAttributeValue, validateCookieName } from "./internal/cookie-serialize.js";
-import { parseCookieHeader } from "./internal/parse-cookie-header.js";
+import { parseEdgeRequestCookieHeader } from "../utils/parse-cookie.js";
+import { createPprFallbackShellSuspensePromise } from "./ppr-fallback-shell.js";
 //#region src/shims/headers.ts
 /**
 * next/headers shim
@@ -81,7 +82,7 @@ function setCookieNameValue(setCookie) {
 function rebuildCookiesFromHeader(ctx, cookieHeader) {
 	ctx.cookies.clear();
 	if (cookieHeader === null) return;
-	const nextCookies = parseCookieHeader(cookieHeader);
+	const nextCookies = parseEdgeRequestCookieHeader(cookieHeader);
 	for (const [name, value] of nextCookies) ctx.cookies.set(name, value);
 }
 function mergeMiddlewareSetCookies(ctx, rawHeader) {
@@ -414,6 +415,26 @@ function _decorateRejectedRequestApiPromise(error) {
 		throw normalizedError;
 	} }));
 }
+function _decorateSuspendingRequestApiPromise(promise) {
+	return new Proxy(promise, {
+		get(promiseTarget, prop) {
+			if (prop === "then" || prop === "catch" || prop === "finally") {
+				const value = Reflect.get(promiseTarget, prop, promiseTarget);
+				return typeof value === "function" ? value.bind(promiseTarget) : value;
+			}
+			throw promise;
+		},
+		getOwnPropertyDescriptor() {
+			throw promise;
+		},
+		has() {
+			throw promise;
+		},
+		ownKeys() {
+			throw promise;
+		}
+	});
+}
 function _sealHeaders(headers) {
 	return new Proxy(headers, { get(target, prop) {
 		if (typeof prop === "string" && _HEADERS_MUTATING_METHODS.has(prop)) throw new ReadonlyHeadersError();
@@ -485,7 +506,7 @@ function headersContextFromRequest(request, options) {
 	let _cookies = null;
 	function getCookies() {
 		if (_cookies) return _cookies;
-		_cookies = parseCookieHeader(headersProxy.get("cookie") || "");
+		_cookies = parseEdgeRequestCookieHeader(headersProxy.get("cookie") || "");
 		return _cookies;
 	}
 	return {
@@ -512,6 +533,8 @@ function headers() {
 	if (!state.headersContext) return _decorateRejectedRequestApiPromise(/* @__PURE__ */ new Error("headers() can only be called from a Server Component, Route Handler, or Server Action. Make sure you're not calling it from a Client Component."));
 	if (state.headersContext.accessError) return _decorateRejectedRequestApiPromise(state.headersContext.accessError);
 	markDynamicUsage();
+	const fallbackShellPromise = createPprFallbackShellSuspensePromise("`headers()`");
+	if (fallbackShellPromise) return _decorateSuspendingRequestApiPromise(fallbackShellPromise);
 	return _getOrCreateDecoratedRequestApiPromise(_decoratedHeadersPromises, _getReadonlyHeaders(state.headersContext));
 }
 /**
@@ -529,6 +552,8 @@ function cookies() {
 	if (!state.headersContext) return _decorateRejectedRequestApiPromise(/* @__PURE__ */ new Error("cookies() can only be called from a Server Component, Route Handler, or Server Action."));
 	if (state.headersContext.accessError) return _decorateRejectedRequestApiPromise(state.headersContext.accessError);
 	markDynamicUsage();
+	const fallbackShellPromise = createPprFallbackShellSuspensePromise("`cookies()`");
+	if (fallbackShellPromise) return _decorateSuspendingRequestApiPromise(fallbackShellPromise);
 	return _getOrCreateDecoratedRequestApiPromise(_decoratedCookiesPromises, _areCookiesMutableInCurrentPhase() ? _getMutableCookies(state.headersContext) : _getReadonlyCookies(state.headersContext));
 }
 /** Accumulated Set-Cookie headers from cookies().set() / .delete() calls */
@@ -572,7 +597,7 @@ function ensureContextDraftModeSecret(ctx) {
 function isDraftModeRequest(request, draftModeSecret) {
 	const cookieHeader = request.headers.get("cookie");
 	if (!cookieHeader) return false;
-	return parseCookieHeader(cookieHeader).get(DRAFT_MODE_COOKIE) === validateDraftModeSecret(draftModeSecret);
+	return parseEdgeRequestCookieHeader(cookieHeader).get(DRAFT_MODE_COOKIE) === validateDraftModeSecret(draftModeSecret);
 }
 function draftModeCookieAttributes() {
 	if (typeof process !== "undefined" && process.env?.NODE_ENV === "development") return "Path=/; HttpOnly; SameSite=Lax";

package/dist/shims/internal/als-registry.js

@@ -38,6 +38,33 @@ import { AsyncLocalStorage } from "node:async_hooks";
 */
 const _g = globalThis;
 /**
+* No-op AsyncLocalStorage used when the runtime does not provide a usable
+* `AsyncLocalStorage` constructor.
+*
+* In browser/client bundles `node:async_hooks` can resolve to a stub without a
+* usable constructor (e.g. Vite's `__vite-browser-external`). Constructing such
+* a value with `new` throws `TypeError: AsyncLocalStorage is not a constructor`
+* at module-eval time, crashing every client-reachable shim that calls
+* `getOrCreateAls` on import (request-context, headers, cache, …).
+*
+* Mirrors Next.js' `FakeAsyncLocalStorage` (and this repo's
+* `async-hooks-stub.ts` client virtual module): `getStore()` returns
+* `undefined` so shims fall back to their non-ALS code path, and the mutating
+* methods are best-effort no-ops that still invoke the callback.
+* See: https://github.com/vercel/next.js/blob/canary/packages/next/src/server/app-render/async-local-storage.ts
+*/
+var NoopAsyncLocalStorage = class {
+	getStore() {}
+	run(_store, fn, ...args) {
+		return fn(...args);
+	}
+	exit(fn, ...args) {
+		return fn(...args);
+	}
+	enterWith(_store) {}
+	disable() {}
+};
+/**
 * Get (or lazily create) the AsyncLocalStorage registered on `globalThis`
 * under `Symbol.for(key)`. Multiple callers — including callers in different
 * module instances — that pass the same `key` receive the same ALS instance.
@@ -47,7 +74,7 @@ const _g = globalThis;
 */
 function getOrCreateAls(key) {
 	const sym = Symbol.for(key);
-	return _g[sym] ??= new AsyncLocalStorage();
+	return _g[sym] ??= typeof AsyncLocalStorage === "function" ? new AsyncLocalStorage() : new NoopAsyncLocalStorage();
 }
 //#endregion
 export { getOrCreateAls };

package/dist/shims/internal/app-route-detection.js

@@ -1,7 +1,7 @@
 import { removeTrailingSlash, stripBasePath } from "../../utils/base-path.js";
-import { createRouteTrieCache, matchRouteWithTrie } from "../../routing/route-matching.js";
+import { getLocalePathPrefix } from "../../utils/domain-locale.js";
+import { resolveHybridClientRouteOwner } from "./hybrid-client-route-owner.js";
 //#region src/shims/internal/app-route-detection.ts
-const appRouteTrieCache = createRouteTrieCache();
 const _COMPONENTS_KEY = Symbol.for("vinext.pagesRouter.components");
 /**
 * Get-or-create the Pages Router `components` map. Returns the same object
@@ -32,20 +32,11 @@ function resolveSameOriginPathname(href, basePath) {
 		return null;
 	}
 	if (url.origin !== window.location.origin) return null;
-	return stripBasePath(url.pathname, basePath);
-}
-/**
-* Returns true when the prefetch href matches any route in the App Router
-* prefetch manifest (static or dynamic). Returns false when the manifest is
-* absent (Pages-Router-only build), the URL is external, or no route matches.
-*/
-function matchesAppRoute(href, basePath) {
-	if (typeof window === "undefined") return false;
-	const routes = window.__VINEXT_LINK_PREFETCH_ROUTES__;
-	if (!routes || routes.length === 0) return false;
-	const pathname = resolveSameOriginPathname(href, basePath);
-	if (pathname === null) return false;
-	return matchRouteWithTrie(pathname, routes, appRouteTrieCache) !== null;
+	const pathname = stripBasePath(url.pathname, basePath);
+	const locale = getLocalePathPrefix(pathname, window.__VINEXT_LOCALES__);
+	if (!locale) return pathname;
+	const localePrefixLength = locale.length + 1;
+	return pathname.length === localePrefixLength ? "/" : pathname.slice(localePrefixLength);
 }
 /**
 * Record `components[pathname] = { __appRouter: true }` on the shared
@@ -61,7 +52,7 @@ function matchesAppRoute(href, basePath) {
 */
 function markAppRouteDetectedOnPrefetch(href, basePath) {
 	if (typeof window === "undefined") return;
-	if (!matchesAppRoute(href, basePath)) return;
+	if (resolveHybridClientRouteOwner(href, basePath) !== "app") return;
 	const rawPathname = resolveSameOriginPathname(href, basePath);
 	if (rawPathname === null) return;
 	const pathname = removeTrailingSlash(rawPathname);

package/dist/shims/internal/hybrid-client-route-owner.d.ts

@@ -0,0 +1,31 @@
+import { NextRewrite } from "../../config/next-config.js";
+import { VinextLinkPrefetchRoute, VinextPagesLinkPrefetchRoute } from "../../client/vinext-next-data.js";
+
+//#region src/shims/internal/hybrid-client-route-owner.d.ts
+type HybridClientOwner = "app" | "document" | "pages";
+declare global {
+  interface Window {
+    __VINEXT_LINK_PREFETCH_ROUTES__?: VinextLinkPrefetchRoute[];
+    __VINEXT_PAGES_LINK_PREFETCH_ROUTES__?: VinextPagesLinkPrefetchRoute[];
+    __VINEXT_CLIENT_REWRITES__?: {
+      afterFiles: NextRewrite[];
+      beforeFiles: NextRewrite[];
+      fallback: NextRewrite[];
+    };
+  }
+}
+/**
+ * Decide which router should own a soft-navigated URL. Returns:
+ *   - "app"    → the App Router runtime handles the navigation (RSC fetch).
+ *   - "pages"  → Pages owns the URL; the caller must hard-navigate instead.
+ *   - null     → no router matched (preserves the existing 404 path).
+ *
+ * `basePath` must match what the page uses (typically `process.env.__NEXT_ROUTER_BASEPATH`).
+ *
+ * The lookup uses the App and Pages manifests on `window` so the same
+ * matcher trie produces the same result the server will see when the
+ * request lands.
+ */
+declare function resolveHybridClientRouteOwner(href: string, basePath: string): HybridClientOwner | null;
+//#endregion
+export { HybridClientOwner, resolveHybridClientRouteOwner };

package/dist/shims/internal/hybrid-client-route-owner.js

@@ -0,0 +1,143 @@
+import { compareHybridRoutePatterns } from "../../routing/utils.js";
+import { stripBasePath } from "../../utils/base-path.js";
+import { createRouteTrieCache, matchRouteWithTrie } from "../../routing/route-matching.js";
+import { isExternalUrl, matchRewrite, parseCookies } from "../../config/config-matchers.js";
+import { getLocalePathPrefix } from "../../utils/domain-locale.js";
+import { mergeRewriteQuery } from "../../utils/query.js";
+//#region src/shims/internal/hybrid-client-route-owner.ts
+/**
+* Client-side resolver that decides whether a URL should be soft-navigated
+* (App Router / RSC) or hard-navigated (Pages Router / document). Delegates
+* the owner decision to `compareHybridRoutePatterns` in `routing/utils.ts`
+* so the server and the client reach the same answer for the same
+* (pages pattern, app pattern) pair.
+*
+* Lives in `shims/internal/` because both `link.tsx` and the App Router
+* browser entry import it without pulling in the server route graph.
+*
+* The App + Pages route manifests are emitted once per page load by the
+* Vite plugin onto the matching `__VINEXT_*_PREFETCH_ROUTES__` window
+* globals (see `entries/app-browser-entry.ts` and
+* `entries/pages-client-entry.ts`). Hybrid builds expose both globals; a
+* single-router build only sets its own.
+*/
+function resolveClientRewrite(href, basePath, rewrites, continueAfterMatch = false) {
+	const initialUrl = new URL(href, window.location.href);
+	const basePathState = {
+		basePath,
+		hadBasePath: basePath ? initialUrl.pathname === basePath || initialUrl.pathname.startsWith(`${basePath}/`) : true
+	};
+	let currentHref = href;
+	let matched = false;
+	for (const rewrite of rewrites) {
+		const pathname = resolveSameOriginPathname(currentHref, basePath);
+		if (pathname === null) return null;
+		const url = new URL(currentHref, window.location.href);
+		const headers = new Headers({ "user-agent": globalThis.navigator?.userAgent ?? "" });
+		const context = {
+			cookies: parseCookies(globalThis.document?.cookie ?? ""),
+			headers,
+			host: url.hostname,
+			query: url.searchParams
+		};
+		const rewritten = matchRewrite(pathname, [rewrite], context, basePathState);
+		if (rewritten === null) continue;
+		if (isExternalUrl(rewritten)) return { kind: "document" };
+		currentHref = mergeRewriteQuery(currentHref, rewritten);
+		matched = true;
+		if (!continueAfterMatch) break;
+	}
+	return matched ? {
+		href: currentHref,
+		kind: "rewrite"
+	} : null;
+}
+const appRouteTrieCache = createRouteTrieCache();
+const pagesRouteTrieCache = createRouteTrieCache();
+/**
+* Build a `/`-joined pattern from a manifest's `patternParts`. Mirrors the
+* server-side route-graph shape (`{ pattern: string }`) so the
+* `compareHybridRoutePatterns` segment-rank comparator can score both Pages
+* and App patterns. The
+* `patternParts` array never includes an empty string for the static `/`
+* route (the App catch-all handles the bare path), so the simple join is
+* safe for everything the route trie actually matches.
+*/
+function patternFromParts(parts) {
+	return "/" + parts.join("/");
+}
+function resolveSameOriginPathname(href, basePath) {
+	if (typeof window === "undefined") return null;
+	let url;
+	try {
+		url = new URL(href, window.location.href);
+	} catch {
+		return null;
+	}
+	if (url.origin !== window.location.origin) return null;
+	const pathname = stripBasePath(url.pathname, basePath);
+	const locale = getLocalePathPrefix(pathname, window.__VINEXT_LOCALES__);
+	if (!locale) return pathname;
+	const localePrefixLength = locale.length + 1;
+	return pathname.length === localePrefixLength ? "/" : pathname.slice(localePrefixLength);
+}
+function matchAppRoute(href, basePath, routes) {
+	const pathname = resolveSameOriginPathname(href, basePath);
+	if (pathname === null) return null;
+	return matchRouteWithTrie(pathname, routes, appRouteTrieCache)?.route ?? null;
+}
+function matchPagesRoute(href, basePath, routes) {
+	const pathname = resolveSameOriginPathname(href, basePath);
+	if (pathname === null) return null;
+	return matchRouteWithTrie(pathname, routes, pagesRouteTrieCache)?.route ?? null;
+}
+/**
+* Decide which router should own a soft-navigated URL. Returns:
+*   - "app"    → the App Router runtime handles the navigation (RSC fetch).
+*   - "pages"  → Pages owns the URL; the caller must hard-navigate instead.
+*   - null     → no router matched (preserves the existing 404 path).
+*
+* `basePath` must match what the page uses (typically `process.env.__NEXT_ROUTER_BASEPATH`).
+*
+* The lookup uses the App and Pages manifests on `window` so the same
+* matcher trie produces the same result the server will see when the
+* request lands.
+*/
+function resolveHybridClientRouteOwner(href, basePath) {
+	if (typeof window === "undefined") return null;
+	const appRoutes = window.__VINEXT_LINK_PREFETCH_ROUTES__;
+	const pagesRoutes = window.__VINEXT_PAGES_LINK_PREFETCH_ROUTES__;
+	const rewrites = window.__VINEXT_CLIENT_REWRITES__;
+	if (rewrites) {
+		const beforeFilesRewrite = resolveClientRewrite(href, basePath, rewrites.beforeFiles, true);
+		if (beforeFilesRewrite?.kind === "document") return "document";
+		if (beforeFilesRewrite?.kind === "rewrite") href = beforeFilesRewrite.href;
+	}
+	let appMatch = appRoutes ? matchAppRoute(href, basePath, appRoutes) : null;
+	let pagesMatch = pagesRoutes ? matchPagesRoute(href, basePath, pagesRoutes) : null;
+	if (rewrites && (appMatch === null || appMatch.isDynamic) && (pagesMatch === null || pagesMatch.isDynamic)) for (const rewrite of rewrites.afterFiles) {
+		const afterFilesRewrite = resolveClientRewrite(href, basePath, [rewrite]);
+		if (afterFilesRewrite?.kind === "document") return "document";
+		if (afterFilesRewrite?.kind !== "rewrite") continue;
+		href = afterFilesRewrite.href;
+		appMatch = appRoutes ? matchAppRoute(href, basePath, appRoutes) : null;
+		pagesMatch = pagesRoutes ? matchPagesRoute(href, basePath, pagesRoutes) : null;
+		if (appMatch || pagesMatch) break;
+	}
+	if (rewrites && appMatch === null && pagesMatch === null) for (const rewrite of rewrites.fallback) {
+		const fallbackRewrite = resolveClientRewrite(href, basePath, [rewrite]);
+		if (fallbackRewrite?.kind === "document") return "document";
+		if (fallbackRewrite?.kind !== "rewrite") continue;
+		href = fallbackRewrite.href;
+		appMatch = appRoutes ? matchAppRoute(href, basePath, appRoutes) : null;
+		pagesMatch = pagesRoutes ? matchPagesRoute(href, basePath, pagesRoutes) : null;
+		if (appMatch || pagesMatch) break;
+	}
+	if (appMatch === null && pagesMatch === null) return null;
+	if (pagesMatch === null) return appMatch.documentOnly ? "document" : "app";
+	if (appMatch === null) return pagesMatch.documentOnly ? "document" : "pages";
+	const owner = compareHybridRoutePatterns(patternFromParts(pagesMatch.patternParts), pagesMatch.isDynamic, patternFromParts(appMatch.patternParts), appMatch.isDynamic);
+	return (owner === "app" ? appMatch : pagesMatch).documentOnly ? "document" : owner;
+}
+//#endregion
+export { resolveHybridClientRouteOwner };

package/dist/shims/internal/navigation-untracked.d.ts

@@ -0,0 +1,35 @@
+//#region src/shims/internal/navigation-untracked.d.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
+ */
+/**
+ * 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
+ */
+declare function useUntrackedPathname(): string | null;
+//#endregion
+export { useUntrackedPathname };