vinext 0.0.50 → 0.0.51

package/dist/server/app-browser-entry.js

@@ -1,25 +1,31 @@
+import { stripBasePath } from "../utils/base-path.js";
 import { ACTION_REDIRECT_HEADER, VINEXT_MOUNTED_SLOTS_HEADER, VINEXT_PARAMS_HEADER } from "./headers.js";
 import { DANGEROUS_URL_BLOCK_MESSAGE, isDangerousScheme } from "../shims/url-safety.js";
 import { APP_RSC_RENDER_MODE_REFRESH_PRESERVE_UI } from "./app-rsc-render-mode.js";
 import { installWindowNext } from "../client/window-next.js";
+import { scrollToHashTargetOnNextFrame } from "../shims/hash-scroll.js";
 import { notifyAppRouterTransitionStart } from "../client/instrumentation-client-state.js";
 import { AppElementsWire } from "./app-elements-wire.js";
 import { getMountedSlotIdsHeader, resolveVisitedResponseInterceptionContext } from "./app-elements.js";
-import { createRscRequestHeaders, createRscRequestUrl, stripRscCacheBustingSearchParam, stripRscSuffix } from "./app-rsc-cache-busting.js";
-import { __basePath, appRouterInstance, commitClientNavigationState, consumePrefetchResponse, createClientNavigationRenderSnapshot, getClientNavigationRenderContext, getCurrentInterceptionContext, getCurrentNextUrl, getPrefetchCache, getPrefetchedUrls, pushHistoryStateWithoutNotify, replaceClientParamsWithoutNotify, replaceHistoryStateWithoutNotify, restoreRscResponse, setClientParams, setMountedSlotsHeader, setNavigationContext, setPendingPathname } from "../shims/navigation.js";
+import { createHistoryStateWithNavigationMetadata, createHistoryStateWithPreviousNextUrl, readHistoryStatePreviousNextUrl, readHistoryStateTraversalIndex, resolveHistoryTraversalIntent } from "./app-history-state.js";
+import { VINEXT_RSC_COMPATIBILITY_ID_HEADER, createRscRequestHeaders, createRscRequestUrl, getVinextRscCompatibilityId, resolveHardNavigationTargetFromRscResponse, resolveRscCompatibilityNavigationDecision } from "./app-rsc-cache-busting.js";
+import { AppRouterContext } from "../shims/internal/app-router-context.js";
+import { __basePath, appRouterInstance, commitClientNavigationState, consumePrefetchResponse, createCachedRscResponseSnapshot, createClientNavigationRenderSnapshot, getClientNavigationRenderContext, getCurrentInterceptionContext, getCurrentNextUrl, invalidatePrefetchCache, pushHistoryStateWithoutNotify, replaceClientParamsWithoutNotify, replaceHistoryStateWithoutNotify, restoreRscResponse, setClientParams, setMountedSlotsHeader, setNavigationContext, setPendingPathname } from "../shims/navigation.js";
 import { DevRecoveryBoundary, RedirectBoundary } from "../shims/error-boundary.js";
 import { ElementsContext, Slot } from "../shims/slot.js";
 import "../client/instrumentation-client.js";
-import { isServerActionResult, shouldClearClientNavigationCachesForServerActionResult } from "./app-browser-action-result.js";
+import { createDiscardedServerActionRefreshScheduler, createServerActionInitiationSnapshot, isServerActionResult, parseServerActionRevalidationHeader, shouldClearClientNavigationCachesForServerActionResult } from "./app-browser-action-result.js";
 import { chunksToReadableStream, createProgressiveRscStream, getVinextBrowserGlobal } from "./app-browser-stream.js";
-import { createHistoryStateWithPreviousNextUrl, readHistoryStatePreviousNextUrl, resolveInterceptionContextFromPreviousNextUrl, resolveServerActionRequestState } from "./app-browser-state.js";
+import { resolveInterceptionContextFromPreviousNextUrl, resolveServerActionRequestState } from "./app-browser-state.js";
 import { clearHardNavigationLoopGuard, createAppBrowserNavigationController } from "./app-browser-navigation-controller.js";
-import { consumeInitialFormState, createVinextHydrateRootOptions } from "./app-browser-hydration.js";
+import { consumeInitialFormState, createVinextHydrateRootOptions, hydrateRootInTransition } from "./app-browser-hydration.js";
+import { createPopstateRestoreHandler } from "./app-browser-popstate.js";
 import { createOnUncaughtError } from "./app-browser-error.js";
 import { dismissOverlay } from "./dev-error-overlay-store.js";
 import { devOnCaughtError, devOnUncaughtError, installDevErrorOverlay } from "./dev-error-overlay.js";
-import { getServerActionNotFoundClientMessage, isServerActionNotFoundResponse } from "./server-action-not-found.js";
-import { createElement, use, useLayoutEffect, useRef, useState } from "react";
+import { throwOnServerActionNotFound } from "./server-action-not-found.js";
+import { resolveRscRedirectLifecycleHop } from "./app-browser-rsc-redirect.js";
+import { createElement, startTransition, use, useLayoutEffect, useRef, useState } from "react";
 import { createFromFetch, createFromReadableStream, createTemporaryReferenceSet, encodeReply, setServerCallback } from "@vitejs/plugin-rsc/browser";
 import { hydrateRoot } from "react-dom/client";
 //#region src/server/app-browser-entry.ts
@@ -37,7 +43,20 @@ function toOperationLane(kind) {
 const MAX_VISITED_RESPONSE_CACHE_SIZE = 50;
 const VISITED_RESPONSE_CACHE_TTL = 5 * 6e4;
 const MAX_TRAVERSAL_CACHE_TTL = 30 * 6e4;
-const browserNavigationController = createAppBrowserNavigationController();
+const CLIENT_RSC_COMPATIBILITY_ID = getVinextRscCompatibilityId();
+function getBrowserRouteManifest() {
+	return window.__VINEXT_ROUTE_MANIFEST__ ?? null;
+}
+const browserNavigationController = createAppBrowserNavigationController({
+	getRouteManifest: getBrowserRouteManifest,
+	syncHistoryStatePreviousNextUrl: syncCurrentHistoryStatePreviousNextUrl
+});
+const discardedServerActionRefreshScheduler = createDiscardedServerActionRefreshScheduler({ runRefresh() {
+	clearClientNavigationCaches();
+	const rscNavigate = window.__VINEXT_RSC_NAVIGATE__;
+	if (typeof rscNavigate !== "function") return;
+	rscNavigate(window.location.href, 0, "refresh", void 0, void 0, true);
+} });
 const NavigationCommitSignal = browserNavigationController.NavigationCommitSignal;
 function parseEncodedJsonHeader(value) {
 	if (!value) return null;
@@ -54,6 +73,47 @@ let latestClientParams = {};
 const visitedResponseCache = /* @__PURE__ */ new Map();
 let browserRouterStateHasEverCommitted = false;
 let pendingNavigationRecoveryHref = null;
+let currentHistoryTraversalIndex = readHistoryStateTraversalIndex(window.history.state) ?? 0;
+let nextHistoryTraversalIndex = currentHistoryTraversalIndex;
+function allocateNavigationHistoryTraversalIndex(historyUpdateMode) {
+	switch (historyUpdateMode) {
+		case "push": return nextHistoryTraversalIndex + 1;
+		case "replace": return currentHistoryTraversalIndex;
+		case void 0: return null;
+		default: throw new Error("[vinext] Unknown history update mode: " + String(historyUpdateMode));
+	}
+}
+function commitHistoryTraversalIndex(index) {
+	currentHistoryTraversalIndex = index;
+	if (index !== null) nextHistoryTraversalIndex = Math.max(nextHistoryTraversalIndex, index);
+}
+function commitHashOnlyNavigation(href, historyUpdateMode, scroll) {
+	const navigationHistoryIndex = allocateNavigationHistoryTraversalIndex(historyUpdateMode);
+	const previousNextUrl = hasBrowserRouterState() ? getBrowserRouterState().previousNextUrl : readHistoryStatePreviousNextUrl(window.history.state);
+	const historyState = createHistoryStateWithNavigationMetadata(createHashOnlyNavigationBaseHistoryState(historyUpdateMode, scroll), {
+		previousNextUrl,
+		traversalIndex: navigationHistoryIndex
+	});
+	if (historyUpdateMode === "replace") replaceHistoryStateWithoutNotify(historyState, "", href);
+	else pushHistoryStateWithoutNotify(historyState, "", href);
+	commitHistoryTraversalIndex(navigationHistoryIndex);
+}
+function createHashOnlyNavigationBaseHistoryState(historyUpdateMode, scroll) {
+	if (historyUpdateMode !== "replace") return null;
+	return scroll ? stripVinextScrollState(window.history.state) : window.history.state;
+}
+function stripVinextScrollState(state) {
+	if (!state || typeof state !== "object") return state;
+	const nextState = {};
+	for (const [key, value] of Object.entries(state)) {
+		if (key === "__vinext_scrollX" || key === "__vinext_scrollY") continue;
+		nextState[key] = value;
+	}
+	return Object.keys(nextState).length > 0 ? nextState : null;
+}
+function commitTraversalIndexFromHistoryState(historyState) {
+	commitHistoryTraversalIndex(readHistoryStateTraversalIndex(historyState));
+}
 function getBrowserRouterState() {
 	return browserNavigationController.getBrowserRouterState();
 }
@@ -78,30 +138,63 @@ function clearVisitedResponseCache() {
 	visitedResponseCache.clear();
 }
 function clearPrefetchState() {
-	getPrefetchCache().clear();
-	getPrefetchedUrls().clear();
+	invalidatePrefetchCache();
 }
 function clearClientNavigationCaches() {
 	clearVisitedResponseCache();
 	clearPrefetchState();
 }
+function syncCurrentHistoryStatePreviousNextUrl(previousNextUrl) {
+	if (readHistoryStatePreviousNextUrl(window.history.state) === previousNextUrl) return;
+	const nextHistoryState = createHistoryStateWithPreviousNextUrl(window.history.state, previousNextUrl);
+	replaceHistoryStateWithoutNotify(nextHistoryState, "", window.location.href);
+	if (readHistoryStatePreviousNextUrl(window.history.state) === previousNextUrl) return;
+	window.history.replaceState(nextHistoryState, "", window.location.href);
+}
+function createActionInitiationSnapshot() {
+	const routerState = getBrowserRouterState();
+	return createServerActionInitiationSnapshot({
+		href: window.location.href,
+		navigationId: browserNavigationController.getActiveNavigationId(),
+		routerState
+	});
+}
 function createNavigationCommitEffect(options) {
-	const { href, historyUpdateMode, navId, params, previousNextUrl } = options;
+	const { href, historyUpdateMode, navId, params, previousNextUrl, targetHistoryIndex } = options;
 	return () => {
 		if (!browserNavigationController.isCurrentNavigation(navId)) {
 			commitClientNavigationState(void 0, { releaseSnapshot: true });
 			return;
 		}
 		const targetHref = new URL(href, window.location.origin).href;
-		stageClientParams(params);
-		const historyState = createHistoryStateWithPreviousNextUrl(historyUpdateMode === "replace" ? window.history.state : null, previousNextUrl);
-		if (historyUpdateMode === "replace" && window.location.href !== targetHref) replaceHistoryStateWithoutNotify(historyState, "", href);
-		else if (historyUpdateMode === "push" && window.location.href !== targetHref) pushHistoryStateWithoutNotify(historyState, "", href);
+		const preserveExistingState = historyUpdateMode === "replace";
+		const navigationHistoryIndex = targetHistoryIndex !== void 0 ? targetHistoryIndex : allocateNavigationHistoryTraversalIndex(historyUpdateMode);
+		const historyState = createHistoryStateWithNavigationMetadata(preserveExistingState ? window.history.state : null, {
+			previousNextUrl,
+			traversalIndex: navigationHistoryIndex
+		});
+		let wroteHistoryState = false;
+		if (historyUpdateMode === "replace" && window.location.href !== targetHref) {
+			stageClientParams(params);
+			replaceHistoryStateWithoutNotify(historyState, "", href);
+			wroteHistoryState = true;
+			commitHistoryTraversalIndex(navigationHistoryIndex);
+		} else if (historyUpdateMode === "push" && window.location.href !== targetHref) {
+			stageClientParams(params);
+			pushHistoryStateWithoutNotify(historyState, "", href);
+			wroteHistoryState = true;
+			commitHistoryTraversalIndex(navigationHistoryIndex);
+		}
+		if (!wroteHistoryState) {
+			syncCurrentHistoryStatePreviousNextUrl(previousNextUrl);
+			stageClientParams(params);
+			if (targetHistoryIndex !== void 0) commitHistoryTraversalIndex(targetHistoryIndex);
+		}
 		pendingNavigationRecoveryHref = null;
 		commitClientNavigationState(navId);
 	};
 }
-async function renderNavigationPayload(payload, navigationSnapshot, targetHref, navId, historyUpdateMode, params, previousNextUrl, pendingRouterState, actionType = "navigate", operationLane = "navigation") {
+async function renderNavigationPayload(payload, navigationSnapshot, targetHref, navId, historyUpdateMode, params, previousNextUrl, pendingRouterState, actionType = "navigate", operationLane = "navigation", traversalIntent = null) {
 	try {
 		return await browserNavigationController.renderNavigationPayload({
 			actionType,
@@ -116,6 +209,7 @@ async function renderNavigationPayload(payload, navigationSnapshot, targetHref,
 			params,
 			pendingRouterState,
 			previousNextUrl,
+			targetHistoryIndex: traversalIntent === null ? void 0 : traversalIntent.targetHistoryIndex,
 			targetHref,
 			navId
 		});
@@ -124,9 +218,16 @@ async function renderNavigationPayload(payload, navigationSnapshot, targetHref,
 		throw error;
 	}
 }
-async function commitSameUrlNavigatePayload(nextElements, returnValue, actionInitiationState) {
-	const navigationSnapshot = createClientNavigationRenderSnapshot(window.location.href, latestClientParams);
-	return browserNavigationController.commitSameUrlNavigatePayload(nextElements, navigationSnapshot, returnValue, actionInitiationState);
+async function commitSameUrlNavigatePayload(nextElements, actionInitiation, returnValue, revalidation = "none") {
+	const navigationSnapshot = createClientNavigationRenderSnapshot(actionInitiation.href, actionInitiation.routerState.navigationSnapshot.params);
+	return browserNavigationController.commitSameUrlNavigatePayload(nextElements, navigationSnapshot, returnValue, actionInitiation.routerState, {
+		onDiscardedRevalidation() {
+			discardedServerActionRefreshScheduler.schedule();
+		},
+		revalidation,
+		startedNavigationId: actionInitiation.navigationId,
+		targetHref: actionInitiation.href
+	});
 }
 function evictVisitedResponseCacheIfNeeded() {
 	while (visitedResponseCache.size >= MAX_VISITED_RESPONSE_CACHE_SIZE) {
@@ -173,18 +274,25 @@ function storeVisitedResponseSnapshot(rscUrl, interceptionContext, snapshot, par
 		response: snapshot
 	});
 }
-function getRequestState(navigationKind, previousNextUrlOverride) {
+function getRequestState(navigationKind, previousNextUrlOverride, traverseHistoryState) {
 	if (previousNextUrlOverride !== void 0) return {
 		interceptionContext: resolveInterceptionContextFromPreviousNextUrl(previousNextUrlOverride, __basePath),
 		previousNextUrl: previousNextUrlOverride
 	};
 	switch (navigationKind) {
-		case "navigate": return {
-			interceptionContext: getCurrentInterceptionContext(),
-			previousNextUrl: getCurrentNextUrl()
-		};
+		case "navigate": {
+			const currentPreviousNextUrl = getBrowserRouterState().previousNextUrl;
+			if (currentPreviousNextUrl !== null) return {
+				interceptionContext: resolveInterceptionContextFromPreviousNextUrl(currentPreviousNextUrl, __basePath),
+				previousNextUrl: currentPreviousNextUrl
+			};
+			return {
+				interceptionContext: getCurrentInterceptionContext(),
+				previousNextUrl: getCurrentNextUrl()
+			};
+		}
 		case "traverse": {
-			const previousNextUrl = readHistoryStatePreviousNextUrl(window.history.state);
+			const previousNextUrl = readHistoryStatePreviousNextUrl(traverseHistoryState ?? window.history.state);
 			return {
 				interceptionContext: resolveInterceptionContextFromPreviousNextUrl(previousNextUrl, __basePath),
 				previousNextUrl
@@ -212,6 +320,7 @@ function BrowserRoot({ initialElements, initialNavigationSnapshot }) {
 	const [treeStateValue, setTreeStateValue] = useState({
 		activeOperation: null,
 		elements: resolvedElements,
+		interception: initialMetadata.interception,
 		interceptionContext: initialMetadata.interceptionContext,
 		layoutIds: initialMetadata.layoutIds,
 		layoutFlags: initialMetadata.layoutFlags,
@@ -220,6 +329,7 @@ function BrowserRoot({ initialElements, initialNavigationSnapshot }) {
 		renderId: 0,
 		rootLayoutTreePath: initialMetadata.rootLayoutTreePath,
 		routeId: initialMetadata.routeId,
+		slotBindings: initialMetadata.slotBindings,
 		visibleCommitVersion: 0
 	});
 	const treeState = isRouterStatePromise(treeStateValue) ? use(treeStateValue) : treeStateValue;
@@ -228,6 +338,7 @@ function BrowserRoot({ initialElements, initialNavigationSnapshot }) {
 	useLayoutEffect(() => {
 		const detach = browserNavigationController.attachBrowserRouterState(setTreeStateValue, stateRef);
 		browserRouterStateHasEverCommitted = true;
+		window.__VINEXT_HYDRATED_AT = performance.now();
 		return () => {
 			detach();
 			setMountedSlotsHeader(null);
@@ -235,12 +346,17 @@ function BrowserRoot({ initialElements, initialNavigationSnapshot }) {
 	}, [setTreeStateValue]);
 	useLayoutEffect(() => {
 		setMountedSlotsHeader(getMountedSlotIdsHeader(stateRef.current.elements));
+		window.__VINEXT_PING_VISIBLE_LINKS__?.();
 	}, [treeState.elements]);
 	useLayoutEffect(() => {
 		if (treeState.renderId !== 0) return;
-		replaceHistoryStateWithoutNotify(createHistoryStateWithPreviousNextUrl(window.history.state, treeState.previousNextUrl), "", window.location.href);
+		replaceHistoryStateWithoutNotify(createHistoryStateWithNavigationMetadata(window.history.state, {
+			previousNextUrl: treeState.previousNextUrl,
+			traversalIndex: currentHistoryTraversalIndex
+		}), "", window.location.href);
 	}, [treeState.previousNextUrl, treeState.renderId]);
-	const innerTree = createElement(RedirectBoundary, null, createElement(NavigationCommitSignal, { renderId: treeState.renderId }, createElement(ElementsContext.Provider, { value: treeState.elements }, createElement(Slot, { id: treeState.routeId }))));
+	const routeTree = createElement(RedirectBoundary, null, createElement(NavigationCommitSignal, { renderId: treeState.renderId }, createElement(ElementsContext.Provider, { value: treeState.elements }, createElement(Slot, { id: treeState.routeId }))));
+	const innerTree = AppRouterContext ? createElement(AppRouterContext.Provider, { value: appRouterInstance }, routeTree) : routeTree;
 	const committedTree = import.meta.env.DEV ? createElement(DevRecoveryBoundary, {
 		resetKey: treeState.renderId,
 		onCatch: handleDevRecoveryBoundaryCatch
@@ -256,31 +372,9 @@ function restoreHydrationNavigationContext(pathname, searchParams, params) {
 		params
 	});
 }
-function decodeHashFragment(fragment) {
-	try {
-		return decodeURIComponent(fragment);
-	} catch {
-		return fragment;
-	}
-}
-function scrollToHashTarget(hash) {
-	const fragment = decodeHashFragment(hash.startsWith("#") ? hash.slice(1) : hash);
-	requestAnimationFrame(() => {
-		if (fragment === "" || fragment === "top") {
-			window.scrollTo(0, 0);
-			return;
-		}
-		const idElement = document.getElementById(fragment);
-		if (idElement) {
-			idElement.scrollIntoView({ behavior: "auto" });
-			return;
-		}
-		document.getElementsByName(fragment)[0]?.scrollIntoView({ behavior: "auto" });
-	});
-}
 function restorePopstateScrollPosition(state) {
 	if (!(state && typeof state === "object" && "__vinext_scrollY" in state)) {
-		if (window.location.hash) scrollToHashTarget(window.location.hash);
+		if (window.location.hash) scrollToHashTargetOnNextFrame(window.location.hash);
 		return;
 	}
 	const y = Number(state.__vinext_scrollY);
@@ -289,6 +383,15 @@ function restorePopstateScrollPosition(state) {
 		window.scrollTo(x, y);
 	});
 }
+function isSameAppRoutePopstateTarget(href) {
+	if (!hasBrowserRouterState()) return false;
+	const target = new URL(href, window.location.origin);
+	const routerState = getBrowserRouterState();
+	const targetPathname = stripBasePath(target.pathname, __basePath);
+	const targetSearch = new URLSearchParams(target.search).toString();
+	const currentSearch = routerState.navigationSnapshot.searchParams.toString();
+	return targetPathname === routerState.navigationSnapshot.pathname && targetSearch === currentSearch;
+}
 let isPageUnloading = false;
 const RSC_RELOAD_KEY = "__vinext_rsc_initial_reload__";
 function readReloadFlag() {
@@ -364,20 +467,21 @@ async function readInitialRscStream() {
 function registerServerActionCallback() {
 	setServerCallback(async (id, args) => {
 		const temporaryReferences = createTemporaryReferenceSet();
+		const actionInitiation = createActionInitiationSnapshot();
+		syncCurrentHistoryStatePreviousNextUrl(actionInitiation.routerState.previousNextUrl);
 		const body = await encodeReply(args, { temporaryReferences });
-		const currentState = getBrowserRouterState();
 		const { headers } = resolveServerActionRequestState({
 			actionId: id,
 			basePath: __basePath,
-			elements: currentState.elements,
-			previousNextUrl: currentState.previousNextUrl
+			elements: actionInitiation.routerState.elements,
+			previousNextUrl: actionInitiation.routerState.previousNextUrl
 		});
-		const fetchResponse = await fetch(await createRscRequestUrl(window.location.pathname + window.location.search, headers), {
+		const fetchResponse = await fetch(await createRscRequestUrl(actionInitiation.path, headers), {
 			method: "POST",
 			headers,
 			body
 		});
-		if (isServerActionNotFoundResponse(fetchResponse)) throw new Error(getServerActionNotFoundClientMessage(id));
+		throwOnServerActionNotFound(fetchResponse, id);
 		const actionRedirect = fetchResponse.headers.get(ACTION_REDIRECT_HEADER);
 		if (actionRedirect) {
 			if (isDangerousScheme(actionRedirect)) {
@@ -395,17 +499,28 @@ function registerServerActionCallback() {
 			else window.location.replace(actionRedirect);
 			return;
 		}
+		if (resolveRscCompatibilityNavigationDecision({
+			clientCompatibilityId: CLIENT_RSC_COMPATIBILITY_ID,
+			currentHref: actionInitiation.href,
+			origin: window.location.origin,
+			responseCompatibilityId: fetchResponse.headers.get("X-Vinext-RSC-Compatibility-Id"),
+			responseUrl: fetchResponse.url
+		}).kind === "hard-navigate") {
+			window.location.reload();
+			return;
+		}
+		const revalidation = parseServerActionRevalidationHeader(fetchResponse.headers);
 		const result = await createFromFetch(Promise.resolve(fetchResponse), { temporaryReferences });
-		if (shouldClearClientNavigationCachesForServerActionResult(result)) clearClientNavigationCaches();
+		if (shouldClearClientNavigationCachesForServerActionResult(result, revalidation)) clearClientNavigationCaches();
 		if (isServerActionResult(result)) {
-			if (result.root !== void 0) return commitSameUrlNavigatePayload(Promise.resolve(AppElementsWire.decode(result.root)), result.returnValue, currentState);
+			if (result.root !== void 0) return commitSameUrlNavigatePayload(Promise.resolve(AppElementsWire.decode(result.root)), actionInitiation, result.returnValue, revalidation);
 			if (result.returnValue) {
 				if (!result.returnValue.ok) throw result.returnValue.data;
 				return result.returnValue.data;
 			}
 			return;
 		}
-		return commitSameUrlNavigatePayload(Promise.resolve(AppElementsWire.decode(result)), void 0, currentState);
+		return commitSameUrlNavigatePayload(Promise.resolve(AppElementsWire.decode(result)), actionInitiation, void 0, revalidation);
 	});
 }
 async function main() {
@@ -418,7 +533,10 @@ function bootstrapHydration(rscStream) {
 	if (import.meta.env.DEV) installDevErrorOverlay();
 	const root = decodeAppElementsPromise(createFromReadableStream(rscStream));
 	const initialNavigationSnapshot = createClientNavigationRenderSnapshot(window.location.href, latestClientParams);
-	replaceHistoryStateWithoutNotify(createHistoryStateWithPreviousNextUrl(window.history.state, null), "", window.location.href);
+	replaceHistoryStateWithoutNotify(createHistoryStateWithNavigationMetadata(window.history.state, {
+		previousNextUrl: null,
+		traversalIndex: currentHistoryTraversalIndex
+	}), "", window.location.href);
 	const onUncaughtError = import.meta.env.DEV ? devOnUncaughtError : createOnUncaughtError(() => pendingNavigationRecoveryHref);
 	const formState = consumeInitialFormState(getVinextBrowserGlobal());
 	const hydrateRootOptions = import.meta.env.DEV ? createVinextHydrateRootOptions({
@@ -429,21 +547,32 @@ function bootstrapHydration(rscStream) {
 		formState,
 		onUncaughtError
 	});
-	window.__VINEXT_RSC_ROOT__ = hydrateRoot(document, createElement(BrowserRoot, {
-		initialElements: root,
-		initialNavigationSnapshot
-	}), hydrateRootOptions);
-	window.__VINEXT_HYDRATED_AT = performance.now();
+	window.__VINEXT_RSC_ROOT__ = hydrateRootInTransition({
+		children: createElement(BrowserRoot, {
+			initialElements: root,
+			initialNavigationSnapshot
+		}),
+		container: document,
+		hydrateRoot,
+		options: hydrateRootOptions,
+		startTransition
+	});
 	window.__VINEXT_CLEAR_NAV_CACHES__ = clearClientNavigationCaches;
-	window.__VINEXT_RSC_NAVIGATE__ = async function navigateRsc(href, redirectDepth = 0, navigationKind = "navigate", historyUpdateMode, previousNextUrlOverride, programmaticTransition = false) {
+	window.__VINEXT_RSC_COMMIT_HASH_NAVIGATION__ = commitHashOnlyNavigation;
+	window.__VINEXT_RSC_NAVIGATE__ = async function navigateRsc(href, redirectDepth = 0, navigationKind = "navigate", historyUpdateMode, previousNextUrlOverride, programmaticTransition = false, traversalIntent) {
 		let pendingRouterState = null;
 		const navId = browserNavigationController.beginNavigation();
+		discardedServerActionRefreshScheduler.markNavigationStart();
 		let currentHref = href;
 		let currentHistoryMode = historyUpdateMode;
 		let currentPrevNextUrl = previousNextUrlOverride;
 		let redirectCount = redirectDepth;
+		const activeTraversalIntent = navigationKind === "traverse" ? traversalIntent ?? resolveHistoryTraversalIntent({
+			currentHistoryIndex: currentHistoryTraversalIndex,
+			historyState: window.history.state
+		}) : null;
 		try {
-			const shouldUsePendingRouterState = programmaticTransition && navigationKind !== "refresh";
+			const shouldUsePendingRouterState = programmaticTransition;
 			if (shouldUsePendingRouterState && hasBrowserRouterState()) pendingRouterState = beginPendingBrowserRouterState();
 			else {
 				await waitForBrowserRouterStateReady();
@@ -451,15 +580,11 @@ function bootstrapHydration(rscStream) {
 				if (shouldUsePendingRouterState) pendingRouterState = beginPendingBrowserRouterState();
 			}
 			while (true) {
-				if (redirectCount > 10) {
-					console.error("[vinext] Too many RSC redirects — aborting navigation to prevent infinite loop.");
-					window.location.href = currentHref;
-					return;
-				}
 				const url = new URL(currentHref, window.location.origin);
-				const requestState = getRequestState(navigationKind, currentPrevNextUrl);
+				const requestState = getRequestState(navigationKind, currentPrevNextUrl, activeTraversalIntent?.historyState);
 				const requestInterceptionContext = requestState.interceptionContext;
 				const requestPreviousNextUrl = requestState.previousNextUrl;
+				if (navigationKind === "refresh") syncCurrentHistoryStatePreviousNextUrl(requestPreviousNextUrl);
 				setPendingPathname(url.pathname, navId);
 				const elementsAtNavStart = getBrowserRouterState().elements;
 				const mountedSlotsHeader = getMountedSlotIdsHeader(elementsAtNavStart);
@@ -471,12 +596,23 @@ function bootstrapHydration(rscStream) {
 				const rscUrl = await createRscRequestUrl(url.pathname + url.search, requestHeaders);
 				const cachedRoute = getVisitedResponse(rscUrl, requestInterceptionContext, mountedSlotsHeader, navigationKind);
 				if (cachedRoute) {
+					const compatibilityDecision = resolveRscCompatibilityNavigationDecision({
+						clientCompatibilityId: CLIENT_RSC_COMPATIBILITY_ID,
+						currentHref,
+						origin: window.location.origin,
+						responseCompatibilityId: cachedRoute.response.compatibilityIdHeader,
+						responseUrl: cachedRoute.response.url
+					});
+					if (compatibilityDecision.kind === "hard-navigate") {
+						window.location.href = compatibilityDecision.hardNavigationTarget;
+						return;
+					}
 					if (!browserNavigationController.isCurrentNavigation(navId)) return;
 					const cachedParams = cachedRoute.params;
 					const cachedNavigationSnapshot = createClientNavigationRenderSnapshot(currentHref, cachedParams);
 					const cachedPayload = decodeAppElementsPromise(createFromFetch(Promise.resolve(restoreRscResponse(cachedRoute.response))));
 					if (!browserNavigationController.isCurrentNavigation(navId)) return;
-					await renderNavigationPayload(cachedPayload, cachedNavigationSnapshot, currentHref, navId, currentHistoryMode, cachedParams, requestPreviousNextUrl, pendingRouterState, toActionType(navigationKind), toOperationLane(navigationKind));
+					await renderNavigationPayload(cachedPayload, cachedNavigationSnapshot, currentHref, navId, currentHistoryMode, cachedParams, requestPreviousNextUrl, pendingRouterState, toActionType(navigationKind), toOperationLane(navigationKind), activeTraversalIntent);
 					return;
 				}
 				let navResponse;
@@ -496,29 +632,38 @@ function bootstrapHydration(rscStream) {
 				const isRscResponse = (navResponse.headers.get("content-type") ?? "").startsWith("text/x-component");
 				if (!navResponse.ok || !isRscResponse || !navResponse.body) {
 					const responseUrl = navResponseUrl ?? navResponse.url;
-					let hardNavTarget = currentHref;
-					if (responseUrl) {
-						const parsed = new URL(responseUrl, window.location.origin);
-						stripRscCacheBustingSearchParam(parsed);
-						const origUrl = new URL(currentHref, window.location.origin);
-						let pathname = stripRscSuffix(parsed.pathname);
-						if (origUrl.pathname.length > 1 && origUrl.pathname.endsWith("/") && !pathname.endsWith("/")) pathname += "/";
-						hardNavTarget = pathname + parsed.search;
-						if (origUrl.hash) hardNavTarget += origUrl.hash;
-					}
-					window.location.href = hardNavTarget;
+					window.location.href = resolveHardNavigationTargetFromRscResponse(responseUrl, currentHref, window.location.origin);
 					return;
 				}
-				const finalUrl = new URL(navResponseUrl ?? navResponse.url, window.location.origin);
-				stripRscCacheBustingSearchParam(finalUrl);
-				const requestedUrl = new URL(rscUrl, window.location.origin);
-				if (finalUrl.pathname !== requestedUrl.pathname) {
-					const destinationPath = stripRscSuffix(finalUrl.pathname) + finalUrl.search;
-					replaceHistoryStateWithoutNotify(createHistoryStateWithPreviousNextUrl(null, requestPreviousNextUrl), "", destinationPath);
-					currentHref = destinationPath;
-					currentHistoryMode = void 0;
-					currentPrevNextUrl = requestPreviousNextUrl;
-					redirectCount += 1;
+				const compatibilityDecision = resolveRscCompatibilityNavigationDecision({
+					clientCompatibilityId: CLIENT_RSC_COMPATIBILITY_ID,
+					currentHref,
+					origin: window.location.origin,
+					responseCompatibilityId: navResponse.headers.get(VINEXT_RSC_COMPATIBILITY_ID_HEADER),
+					responseUrl: navResponseUrl ?? navResponse.url
+				});
+				if (compatibilityDecision.kind === "hard-navigate") {
+					window.location.href = compatibilityDecision.hardNavigationTarget;
+					return;
+				}
+				const redirectDecision = resolveRscRedirectLifecycleHop({
+					currentHref,
+					historyUpdateMode: currentHistoryMode ?? "replace",
+					origin: window.location.origin,
+					redirectDepth: redirectCount,
+					requestPreviousNextUrl,
+					responseUrl: navResponseUrl ?? navResponse.url
+				});
+				if (redirectDecision.kind === "terminal-hard-navigation") {
+					if (redirectDecision.reason === "maxRedirectsExceeded") console.error("[vinext] Too many RSC redirects — aborting navigation to prevent infinite loop.");
+					window.location.href = redirectDecision.href;
+					return;
+				}
+				if (redirectDecision.kind === "follow") {
+					currentHref = redirectDecision.href;
+					currentHistoryMode = redirectDecision.historyUpdateMode;
+					currentPrevNextUrl = redirectDecision.previousNextUrl;
+					redirectCount = redirectDecision.redirectDepth;
 					continue;
 				}
 				const navParams = parseEncodedJsonHeader(navResponse.headers.get("X-Vinext-Params")) ?? {};
@@ -534,18 +679,12 @@ function bootstrapHydration(rscStream) {
 				if (!browserNavigationController.isCurrentNavigation(navId)) return;
 				const rscPayload = decodeAppElementsPromise(createFromFetch(Promise.resolve(reactResponse)));
 				if (!browserNavigationController.isCurrentNavigation(navId)) return;
-				if (await renderNavigationPayload(rscPayload, navigationSnapshot, currentHref, navId, currentHistoryMode, navParams, requestPreviousNextUrl, pendingRouterState, toActionType(navigationKind), toOperationLane(navigationKind)) !== "committed") return;
+				if (await renderNavigationPayload(rscPayload, navigationSnapshot, currentHref, navId, currentHistoryMode, navParams, requestPreviousNextUrl, pendingRouterState, toActionType(navigationKind), toOperationLane(navigationKind), activeTraversalIntent) !== "committed") return;
 				if (!browserNavigationController.isCurrentNavigation(navId)) return;
 				const resolvedElements = await rscPayload;
 				const metadata = AppElementsWire.readMetadata(resolvedElements);
 				const cacheBuffer = await cacheBufferPromise;
-				storeVisitedResponseSnapshot(rscUrl, resolveVisitedResponseInterceptionContext(requestInterceptionContext, metadata.interceptionContext), {
-					buffer: cacheBuffer,
-					contentType: navResponse.headers.get("content-type") ?? "text/x-component",
-					mountedSlotsHeader: navResponse.headers.get(VINEXT_MOUNTED_SLOTS_HEADER),
-					paramsHeader: navResponse.headers.get(VINEXT_PARAMS_HEADER),
-					url: navResponse.url
-				}, navParams);
+				storeVisitedResponseSnapshot(rscUrl, resolveVisitedResponseInterceptionContext(requestInterceptionContext, metadata.interceptionContext), createCachedRscResponseSnapshot(navResponse, cacheBuffer, navResponseUrl), navParams);
 				return;
 			}
 		} catch (error) {
@@ -554,17 +693,32 @@ function bootstrapHydration(rscStream) {
 			window.location.href = currentHref;
 		} finally {
 			browserNavigationController.finalizeNavigation(navId, pendingRouterState);
+			discardedServerActionRefreshScheduler.markNavigationSettled();
 		}
 	};
 	if ("scrollRestoration" in history) history.scrollRestoration = "manual";
+	const handlePopstate = createPopstateRestoreHandler({
+		getActiveNavigationId: browserNavigationController.getActiveNavigationId.bind(browserNavigationController),
+		getPendingNavigation: () => window.__VINEXT_RSC_PENDING__,
+		getNavigate: () => window.__VINEXT_RSC_NAVIGATE__,
+		isCurrentNavigation: browserNavigationController.isCurrentNavigation.bind(browserNavigationController),
+		notifyAppRouterTransitionStart: (href) => {
+			notifyAppRouterTransitionStart(href, "traverse");
+		},
+		restorePopstateScrollPosition,
+		setPendingNavigation: (pendingNavigation) => {
+			window.__VINEXT_RSC_PENDING__ = pendingNavigation;
+		}
+	});
 	window.addEventListener("popstate", (event) => {
-		notifyAppRouterTransitionStart(window.location.href, "traverse");
-		const pendingNavigation = window.__VINEXT_RSC_NAVIGATE__?.(window.location.href, 0, "traverse") ?? Promise.resolve();
-		window.__VINEXT_RSC_PENDING__ = pendingNavigation;
-		pendingNavigation.finally(() => {
+		const href = window.location.href;
+		if (isSameAppRoutePopstateTarget(href)) {
+			notifyAppRouterTransitionStart(href, "traverse");
+			commitTraversalIndexFromHistoryState(event.state);
 			restorePopstateScrollPosition(event.state);
-			if (window.__VINEXT_RSC_PENDING__ === pendingNavigation) window.__VINEXT_RSC_PENDING__ = null;
-		});
+			return;
+		}
+		handlePopstate(event);
 	});
 	if (import.meta.hot) {
 		const handleRscUpdate = async () => {