vinext 0.1.1 → 0.1.3

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 };

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/metadata.d.ts

@@ -271,11 +271,15 @@ declare function resolveModuleMetadata(mod: Record<string, unknown>, params?: Re
 type MetadataHeadProps = {
   metadata: Metadata;
   pathname?: string;
+  trailingSlash?: boolean;
 };
-declare function renderMetadataToHtml(metadata: Metadata, pathname?: string): string;
+declare function renderMetadataToHtml(metadata: Metadata, pathname?: string, options?: {
+  trailingSlash?: boolean;
+}): string;
 declare function MetadataHead({
   metadata,
-  pathname
+  pathname,
+  trailingSlash
 }: MetadataHeadProps): React.JSX.Element;
 //#endregion
 export { DEFAULT_VIEWPORT, Metadata, MetadataHead, MetadataMergeEntry, Viewport, ViewportHead, mergeMetadata, mergeMetadataEntries, mergeViewport, postProcessMetadata, renderMetadataToHtml, resolveModuleMetadata, resolveModuleViewport };

package/dist/shims/metadata.js

@@ -287,18 +287,35 @@ function formatResolvedMetadataUrl(url) {
 	if (url.pathname === "/" && url.search === "" && url.hash === "") return url.origin;
 	return url.href;
 }
-function resolveMetadataUrl(url, metadataBase) {
+const TRAILING_SLASH_FILE_REGEX = /^(?:\/((?!\.well-known(?:\/.*)?)((?:[^/]+\/)*)([^/]+\.\w+)))(\/?|$)/i;
+function resolveMetadataUrl(url, metadataBase, trailingSlash) {
 	const value = stringifyUrl(url);
-	if (isAbsoluteOrProtocolRelativeUrl(value) || !metadataBase) return value;
+	if (!metadataBase) return value;
 	try {
-		return formatResolvedMetadataUrl(new URL(joinMetadataPath(metadataBase.pathname, value), metadataBase));
+		const isAbsolute = isAbsoluteOrProtocolRelativeUrl(value);
+		const composed = isAbsolute ? new URL(value, metadataBase) : new URL(joinMetadataPath(metadataBase.pathname, value), metadataBase);
+		if (isAbsolute && composed.origin !== metadataBase.origin) return value;
+		if (trailingSlash === true && composed.search === "") {
+			if (composed.pathname !== "/" && !composed.pathname.endsWith("/") && !TRAILING_SLASH_FILE_REGEX.test(composed.pathname)) composed.pathname += "/";
+		}
+		const result = formatResolvedMetadataUrl(composed);
+		if (trailingSlash === true && result === metadataBase.origin) return `${metadataBase.origin}/`;
+		return result;
 	} catch {
 		return value;
 	}
 }
-function resolveCanonicalUrl(url, metadataBase, pathname) {
-	if (url instanceof URL) return resolveMetadataUrl(url, metadataBase);
-	return resolveMetadataUrl(resolveRelativeMetadataUrl(url, pathname), metadataBase);
+function resolveCanonicalUrl(url, metadataBase, pathname, trailingSlash) {
+	if (url instanceof URL) return resolveMetadataUrl(url, metadataBase, trailingSlash);
+	return resolveMetadataUrl(resolveRelativeMetadataUrl(url, pathname), metadataBase, trailingSlash);
+}
+function resolveAlternateUrl(url, metadataBase, pathname, trailingSlash) {
+	if (url instanceof URL) {
+		const resolvedUrl = new URL(pathname, url);
+		url.searchParams.forEach((value, key) => resolvedUrl.searchParams.set(key, value));
+		return resolveMetadataUrl(resolvedUrl, metadataBase, trailingSlash);
+	}
+	return resolveCanonicalUrl(url, metadataBase, pathname, trailingSlash);
 }
 function isSocialImageDescriptor(value) {
 	return typeof value === "object" && !(value instanceof URL);
@@ -359,13 +376,14 @@ function renderMetadataElementToHtml(node) {
 		default: return "";
 	}
 }
-function renderMetadataToHtml(metadata, pathname = "/") {
+function renderMetadataToHtml(metadata, pathname = "/", options) {
 	return renderMetadataElementToHtml(MetadataHead({
 		metadata,
-		pathname
+		pathname,
+		trailingSlash: options?.trailingSlash
 	}));
 }
-function MetadataHead({ metadata, pathname = "/" }) {
+function MetadataHead({ metadata, pathname = "/", trailingSlash }) {
 	const elements = [];
 	let key = 0;
 	const base = metadata.metadataBase;
@@ -474,7 +492,7 @@ function MetadataHead({ metadata, pathname = "/" }) {
 		}, key++));
 		if (og.url) elements.push(/* @__PURE__ */ jsx("meta", {
 			property: "og:url",
-			content: resolveUrl(og.url)
+			content: resolveCanonicalUrl(og.url, base, pathname, trailingSlash)
 		}, key++));
 		if (og.siteName) elements.push(/* @__PURE__ */ jsx("meta", {
 			property: "og:site_name",
@@ -691,22 +709,22 @@ function MetadataHead({ metadata, pathname = "/" }) {
 		const alt = metadata.alternates;
 		if (alt.canonical) elements.push(/* @__PURE__ */ jsx("link", {
 			rel: "canonical",
-			href: resolveCanonicalUrl(alt.canonical, base, pathname)
+			href: resolveCanonicalUrl(alt.canonical, base, pathname, trailingSlash)
 		}, key++));
 		if (alt.languages) for (const [lang, href] of Object.entries(alt.languages)) elements.push(/* @__PURE__ */ jsx("link", {
 			rel: "alternate",
 			hrefLang: lang,
-			href: resolveUrl(href)
+			href: resolveAlternateUrl(href, base, pathname, trailingSlash)
 		}, key++));
 		if (alt.media) for (const [media, href] of Object.entries(alt.media)) elements.push(/* @__PURE__ */ jsx("link", {
 			rel: "alternate",
 			media,
-			href: resolveUrl(href)
+			href: resolveAlternateUrl(href, base, pathname, trailingSlash)
 		}, key++));
 		if (alt.types) for (const [type, href] of Object.entries(alt.types)) elements.push(/* @__PURE__ */ jsx("link", {
 			rel: "alternate",
 			type,
-			href: resolveUrl(href)
+			href: resolveAlternateUrl(href, base, pathname, trailingSlash)
 		}, key++));
 	}
 	if (metadata.verification) {

package/dist/shims/navigation.d.ts

@@ -1,4 +1,6 @@
-import { NavigateOptions, PrefetchOptions as PrefetchOptions$1 } from "./internal/app-router-context.js";
+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";
 import { UnrecognizedActionError, unstable_isUnrecognizedActionError } from "./unrecognized-action-error.js";
 import * as React$1 from "react";
@@ -96,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
@@ -204,7 +208,10 @@ 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;
 declare function replaceClientParamsWithoutNotify(params: Record<string, string | string[]>): void;
 /** Get the current client params (for testing referential stability). */
@@ -253,10 +260,11 @@ 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.
  */
-declare function navigateClientSide(href: string, mode: "push" | "replace", scroll: boolean, programmaticTransition?: boolean): Promise<void>;
+declare function navigateClientSide(href: string, mode: "push" | "replace", scroll: boolean, programmaticTransition?: boolean, visibleCommitMode?: NavigationRuntimeVisibleCommitMode): Promise<void>;
 /**
  * Public App Router instance, exposed for the browser entry so it can wire
  * `window.next.router` to the same singleton returned from `useRouter()`.
@@ -264,19 +272,7 @@ declare function navigateClientSide(href: string, mode: "push" | "replace", scro
  * Mirrors `publicAppRouterInstance` from Next.js's
  * `packages/next/src/client/components/app-router-instance.ts` (line 392).
  */
-declare const appRouterInstance: {
-  bfcacheId: string;
-  push(href: string, options?: {
-    scroll?: boolean;
-  }): void;
-  replace(href: string, options?: {
-    scroll?: boolean;
-  }): void;
-  back(): void;
-  forward(): void;
-  refresh(): void;
-  prefetch(href: string, options?: PrefetchOptions): void;
-};
+declare const appRouterInstance: AppRouterInstance;
 /**
  * App Router's useRouter — returns push/replace/back/forward/refresh.
  * Different from Pages Router's useRouter (next/router).
@@ -292,6 +288,7 @@ declare function useRouter(): {
   push(href: string, options?: NavigateOptions): void;
   replace(href: string, options?: NavigateOptions): void;
   prefetch(href: string, options?: PrefetchOptions$1): void;
+  experimental_gesturePush?(href: string, options?: NavigateOptions): void;
 };
 /**
  * Returns the active child segment one level below the layout where it's called.
@@ -574,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, 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 };