@qzsy/vinext 0.1.7

package/dist/server/app-browser-navigation-controller.d.ts

@@ -0,0 +1,109 @@
+import { RouteManifest } from "../routing/app-route-graph.js";
+import { AppRouterScrollIntent } from "../shims/app-router-scroll-state.js";
+import { NavigationRuntimeVisibleCommitMode } from "../client/navigation-runtime.js";
+import { AppElements } from "./app-elements-wire.js";
+import { OperationLane } from "./operation-token.js";
+import { ServerActionRevalidationKind } from "./app-browser-action-result.js";
+import { ClientNavigationRenderSnapshot, commitClientNavigationState, createSnapshotPathAndSearch } from "../shims/navigation.js";
+import { AppNavigationPayloadOrigin, AppRouterState } from "./app-browser-state.js";
+import { Dispatch, ReactNode } from "react";
+
+//#region src/server/app-browser-navigation-controller.d.ts
+type HistoryUpdateMode = "push" | "replace";
+type PendingBrowserRouterState = {
+  promise: Promise<AppRouterState>;
+  resolve: (state: AppRouterState) => void;
+  settled: boolean;
+};
+type NavigationPayloadOutcome = "committed" | "no-commit" | "hard-navigate";
+type HardNavigationMode = "assign" | "replace";
+type BrowserNavigationCommitEffect = () => void;
+type BrowserNavigationCommitEffectFactory = (options: {
+  bfcacheIds: Readonly<Record<string, string>>;
+  href: string;
+  historyUpdateMode: HistoryUpdateMode | undefined;
+  navId: number;
+  params: Record<string, string | string[]>;
+  previousNextUrl: string | null;
+  targetHistoryIndex?: number | null;
+}) => BrowserNavigationCommitEffect;
+type BrowserRouterStateRef = {
+  current: AppRouterState;
+};
+type SameUrlServerActionLifecycleOptions = {
+  onDiscardedRevalidation?: () => void;
+  revalidation?: ServerActionRevalidationKind;
+  startedNavigationId?: number;
+  targetHref?: string;
+};
+type BrowserNavigationControllerDeps = {
+  basePath?: string;
+  commitClientNavigationState?: typeof commitClientNavigationState;
+  performHardNavigation?: (href: string, mode?: HardNavigationMode) => boolean;
+  getRouteManifest?: () => RouteManifest | null;
+  syncHistoryStatePreviousNextUrl?: (previousNextUrl: string | null, bfcacheIds?: Readonly<Record<string, string>> | null) => void;
+};
+type BrowserNavigationController = {
+  beginNavigation(): number;
+  getActiveNavigationId(): number;
+  hasBrowserRouterState(): boolean;
+  getBrowserRouterState(): AppRouterState;
+  isCurrentNavigation(navId: number): boolean;
+  performHardNavigation(href: string, mode?: HardNavigationMode): boolean;
+  waitForBrowserRouterStateReady(): Promise<void>;
+  attachBrowserRouterState(setter: Dispatch<AppRouterState | Promise<AppRouterState>>, stateRef: BrowserRouterStateRef): () => void;
+  beginPendingBrowserRouterState(): PendingBrowserRouterState;
+  finalizeNavigation(navId: number, pending: PendingBrowserRouterState | null | undefined): void;
+  restoreHistorySnapshotVisibleState(options: {
+    beforeCommit?: () => void;
+    navId: number;
+    state: AppRouterState;
+    targetHref: string;
+  }): boolean;
+  renderNavigationPayload(options: {
+    actionType: "navigate" | "replace" | "traverse";
+    createNavigationCommitEffect: BrowserNavigationCommitEffectFactory;
+    historyUpdateMode: HistoryUpdateMode | undefined;
+    navigationSnapshot: ClientNavigationRenderSnapshot;
+    nextElements: Promise<AppElements>;
+    operationLane: OperationLane;
+    payloadOrigin: AppNavigationPayloadOrigin;
+    params: Record<string, string | string[]>;
+    pendingRouterState: PendingBrowserRouterState | null;
+    previousNextUrl: string | null;
+    scrollIntent?: AppRouterScrollIntent | null;
+    restoredBfcacheIds?: Readonly<Record<string, string>> | null;
+    reuseCurrentBfcacheIds?: boolean;
+    targetHistoryIndex?: number | null;
+    targetHref: string;
+    navId: number;
+    visibleCommitMode?: NavigationRuntimeVisibleCommitMode;
+  }): Promise<NavigationPayloadOutcome>;
+  commitSameUrlNavigatePayload(nextElements: Promise<AppElements>, navigationSnapshot: ClientNavigationRenderSnapshot, returnValue?: {
+    ok: boolean;
+    data: unknown;
+  }, actionInitiationState?: AppRouterState, lifecycleOptions?: SameUrlServerActionLifecycleOptions): Promise<unknown>;
+  hmrReplaceTree(nextElements: Promise<AppElements>, navigationSnapshot: ClientNavigationRenderSnapshot): Promise<void>;
+  /**
+   * Force-drain the queued pre-paint effect for the given renderId without
+   * waiting for NavigationCommitSignal to commit. Used by the dev recovery
+   * boundary in app-browser-entry.ts: when a render error replaces
+   * NavigationCommitSignal with the boundary's null fallback, its
+   * useLayoutEffect never fires, so the URL update for the in-flight
+   * navigation would otherwise be lost.
+   */
+  drainPrePaintEffects(renderId: number): void;
+  clearCommittedNavigationFailureTargets(renderId: number): void;
+  NavigationCommitSignal(this: void, {
+    renderId,
+    children
+  }: {
+    renderId: number;
+    children?: ReactNode;
+  }): ReactNode;
+};
+declare function clearHardNavigationLoopGuard(): void;
+declare function createBasePathStrippedPathAndSearch(url: URL, basePath: string): string;
+declare function createAppBrowserNavigationController(deps?: BrowserNavigationControllerDeps): BrowserNavigationController;
+//#endregion
+export { HistoryUpdateMode, NavigationPayloadOutcome, PendingBrowserRouterState, clearHardNavigationLoopGuard, createAppBrowserNavigationController, createBasePathStrippedPathAndSearch, createSnapshotPathAndSearch };

package/dist/server/app-browser-navigation-controller.js

@@ -0,0 +1,465 @@
+import { stripBasePath } from "../utils/base-path.js";
+import { clearAppNavigationFailureTarget, getAppNavigationFailureTarget } from "../client/app-nav-failure-handler.js";
+import { claimAppRouterScrollIntentForCommit, consumeAppRouterScrollIntent } from "../shims/app-router-scroll-state.js";
+import { activateNavigationSnapshot, clearPendingPathname, commitClientNavigationState, createSnapshotPathAndSearch } from "../shims/navigation.js";
+import { shouldScheduleRefreshForDiscardedServerAction } from "./app-browser-action-result.js";
+import { FRESH_APP_NAVIGATION_PAYLOAD_ORIGIN, createPendingNavigationCommit } from "./app-browser-state.js";
+import { applyApprovedVisibleCommit, approveHmrVisibleCommit, approvePendingNavigationCommit, resolveAndClassifyNavigationCommit } from "./app-browser-visible-commit.js";
+import { startTransition, useInsertionEffect, useLayoutEffect } from "react";
+import { flushSync } from "react-dom";
+//#region src/server/app-browser-navigation-controller.ts
+const HARD_NAVIGATION_LOOP_GUARD_KEY = "__vinext_hard_navigation_target__";
+function normalizeBrowserHref(href) {
+	try {
+		return new URL(href, window.location.href).href;
+	} catch {
+		return href;
+	}
+}
+function readHardNavigationLoopGuard() {
+	try {
+		return window.sessionStorage.getItem(HARD_NAVIGATION_LOOP_GUARD_KEY);
+	} catch {
+		return null;
+	}
+}
+function writeHardNavigationLoopGuard(targetHref) {
+	try {
+		window.sessionStorage.setItem(HARD_NAVIGATION_LOOP_GUARD_KEY, targetHref);
+		return window.sessionStorage.getItem(HARD_NAVIGATION_LOOP_GUARD_KEY) === targetHref;
+	} catch {
+		return false;
+	}
+}
+function clearHardNavigationLoopGuard() {
+	try {
+		window.sessionStorage.removeItem(HARD_NAVIGATION_LOOP_GUARD_KEY);
+	} catch {}
+}
+function performHardNavigationWithLoopGuard(href, mode = "assign") {
+	const targetHref = normalizeBrowserHref(href);
+	const currentHref = normalizeBrowserHref(window.location.href);
+	if (readHardNavigationLoopGuard() === targetHref && currentHref === targetHref) {
+		clearHardNavigationLoopGuard();
+		console.error(`[vinext] Prevented repeated hard navigation to ${targetHref}; leaving the current document in place to avoid a reload loop.`);
+		return false;
+	}
+	if (!writeHardNavigationLoopGuard(targetHref) && currentHref === targetHref) {
+		console.error(`[vinext] Hard navigation to ${targetHref} requires a reload-loop guard, but sessionStorage is unavailable; leaving the current document in place.`);
+		return false;
+	}
+	if (mode === "replace") window.location.replace(href);
+	else window.location.assign(href);
+	return true;
+}
+function createBasePathStrippedPathAndSearch(url, basePath) {
+	const pathname = stripBasePath(url.pathname, basePath);
+	const query = new URLSearchParams(url.search).toString();
+	return query === "" ? pathname : `${pathname}?${query}`;
+}
+function isSnapshotTargetHref(basePath, snapshot, targetHref) {
+	try {
+		const baseHref = typeof window === "undefined" ? "http://localhost" : window.location.href;
+		return createBasePathStrippedPathAndSearch(new URL(targetHref, baseHref), basePath) === createSnapshotPathAndSearch(snapshot);
+	} catch {
+		return false;
+	}
+}
+function createAppBrowserNavigationController(deps = {}) {
+	const basePath = deps.basePath ?? "";
+	const commitClientNavigationStateImpl = deps.commitClientNavigationState ?? commitClientNavigationState;
+	const performHardNavigation = deps.performHardNavigation ?? performHardNavigationWithLoopGuard;
+	const getRouteManifest = deps.getRouteManifest ?? (() => null);
+	const syncHistoryStatePreviousNextUrl = deps.syncHistoryStatePreviousNextUrl ?? (() => {});
+	let nextNavigationRenderId = 0;
+	let activeNavigationId = 0;
+	const pendingNavigationCommits = /* @__PURE__ */ new Map();
+	const pendingNavigationFailureTargets = /* @__PURE__ */ new Map();
+	const pendingNavigationPrePaintEffects = /* @__PURE__ */ new Map();
+	let setBrowserRouterState = null;
+	let browserRouterStateRef = null;
+	let activePendingBrowserRouterState = null;
+	let resolveBrowserRouterStateReady = null;
+	let browserRouterStateReadyPromise = null;
+	let browserRouterStateHasCommitted = false;
+	function getBrowserRouterStateSetter() {
+		if (!setBrowserRouterState) throw new Error("[vinext] Browser router state setter is not initialized");
+		return setBrowserRouterState;
+	}
+	function getBrowserRouterState() {
+		if (!browserRouterStateRef) throw new Error("[vinext] Browser router state is not initialized");
+		return browserRouterStateRef.current;
+	}
+	function waitForBrowserRouterStateReady() {
+		if (browserRouterStateRef || browserRouterStateHasCommitted) return Promise.resolve();
+		if (!browserRouterStateReadyPromise) browserRouterStateReadyPromise = new Promise((resolve) => {
+			resolveBrowserRouterStateReady = resolve;
+		});
+		return browserRouterStateReadyPromise;
+	}
+	function markBrowserRouterStateReady() {
+		browserRouterStateHasCommitted = true;
+		const resolveReady = resolveBrowserRouterStateReady;
+		resolveBrowserRouterStateReady = null;
+		browserRouterStateReadyPromise = null;
+		resolveReady?.();
+	}
+	function beginNavigation() {
+		activeNavigationId += 1;
+		return activeNavigationId;
+	}
+	function getActiveNavigationId() {
+		return activeNavigationId;
+	}
+	function allocateRenderId() {
+		nextNavigationRenderId += 1;
+		return nextNavigationRenderId;
+	}
+	function hasBrowserRouterState() {
+		return browserRouterStateRef !== null;
+	}
+	function isCurrentNavigation(navId) {
+		return navId === activeNavigationId;
+	}
+	function beginPendingBrowserRouterState() {
+		const setter = getBrowserRouterStateSetter();
+		if (activePendingBrowserRouterState && !activePendingBrowserRouterState.settled) {
+			activePendingBrowserRouterState.settled = true;
+			activePendingBrowserRouterState.resolve(getBrowserRouterState());
+		}
+		let resolvePending;
+		const promise = new Promise((resolve) => {
+			resolvePending = resolve;
+		});
+		if (!resolvePending) throw new Error("[vinext] Failed to initialize browser router promise");
+		const pending = {
+			promise,
+			resolve: resolvePending,
+			settled: false
+		};
+		activePendingBrowserRouterState = pending;
+		setter(promise);
+		return pending;
+	}
+	function settlePendingBrowserRouterState(pending) {
+		if (!pending || pending.settled) return;
+		pending.settled = true;
+		pending.resolve(getBrowserRouterState());
+		if (activePendingBrowserRouterState === pending) activePendingBrowserRouterState = null;
+	}
+	function finalizeNavigation(navId, pending) {
+		settlePendingBrowserRouterState(pending);
+		if (isCurrentNavigation(navId)) clearPendingPathname(navId);
+	}
+	function resolvePendingBrowserRouterState(pending, commit) {
+		if (!pending || pending.settled) return;
+		pending.settled = true;
+		pending.resolve(applyApprovedVisibleCommit(getBrowserRouterState(), commit));
+		if (activePendingBrowserRouterState === pending) activePendingBrowserRouterState = null;
+	}
+	function queuePrePaintNavigationEffect(renderId, effect) {
+		if (!effect) return;
+		pendingNavigationPrePaintEffects.set(renderId, effect);
+	}
+	/**
+	* Run all queued pre-paint effects for renderIds up to and including the
+	* given renderId. When React supersedes a startTransition update (rapid
+	* clicks on same-route links), the superseded NavigationCommitSignal never
+	* mounts, so its pre-paint effect never fires. By draining all effects
+	* <= the committed renderId here, the winning transition cleans up after
+	* any superseded ones, keeping the counter balanced.
+	*
+	* Invariant: each superseded navigation gets a commitClientNavigationState()
+	* to balance the activateNavigationSnapshot() from its renderNavigationPayload call.
+	*/
+	function drainPrePaintEffects(upToRenderId) {
+		for (const [id, effect] of pendingNavigationPrePaintEffects) {
+			if (id > upToRenderId) continue;
+			pendingNavigationPrePaintEffects.delete(id);
+			if (id === upToRenderId) effect();
+			else commitClientNavigationStateImpl(void 0, { releaseSnapshot: true });
+		}
+	}
+	/**
+	* Resolve all pending navigation commits with renderId <= the committed renderId.
+	* Note: Map iteration handles concurrent deletion safely — entries are visited in
+	* insertion order and deletion doesn't affect the iterator's view of remaining entries.
+	* This pattern is also used in drainPrePaintEffects with the same semantics.
+	*/
+	function resolveCommittedNavigations(renderId) {
+		for (const [pendingId, resolve] of pendingNavigationCommits) {
+			if (pendingId > renderId) continue;
+			pendingNavigationCommits.delete(pendingId);
+			resolve();
+		}
+	}
+	function clearCommittedNavigationFailureTargets(renderId) {
+		for (const [pendingId, targetHref] of pendingNavigationFailureTargets) {
+			if (pendingId > renderId) continue;
+			pendingNavigationFailureTargets.delete(pendingId);
+			clearAppNavigationFailureTarget(targetHref);
+		}
+	}
+	async function hmrReplaceTree(nextElements, navigationSnapshot) {
+		if (!hasBrowserRouterState()) return;
+		const pending = await createPendingNavigationCommit({
+			currentState: getBrowserRouterState(),
+			nextElements,
+			navigationSnapshot,
+			operationLane: "hmr",
+			payloadOrigin: FRESH_APP_NAVIGATION_PAYLOAD_ORIGIN,
+			renderId: allocateRenderId(),
+			type: "replace"
+		});
+		if (!hasBrowserRouterState()) return;
+		dispatchSynchronousVisibleCommit(approveHmrVisibleCommit(pending));
+	}
+	function NavigationCommitSignal({ renderId, children }) {
+		useInsertionEffect(() => {
+			clearCommittedNavigationFailureTargets(renderId);
+		}, [renderId]);
+		useLayoutEffect(() => {
+			drainPrePaintEffects(renderId);
+			const frame = requestAnimationFrame(() => {
+				resolveCommittedNavigations(renderId);
+			});
+			return () => {
+				cancelAnimationFrame(frame);
+				resolveCommittedNavigations(renderId);
+			};
+		}, [renderId]);
+		return children;
+	}
+	function dispatchApprovedVisibleCommit(commit, pendingRouterState, visibleCommitMode) {
+		const setter = getBrowserRouterStateSetter();
+		if (pendingRouterState) {
+			resolvePendingBrowserRouterState(pendingRouterState, commit);
+			return;
+		}
+		if (visibleCommitMode === "synchronous") {
+			flushSync(() => {
+				setter(applyApprovedVisibleCommit(getBrowserRouterState(), commit));
+			});
+			return;
+		}
+		startTransition(() => {
+			setter(applyApprovedVisibleCommit(getBrowserRouterState(), commit));
+		});
+	}
+	function dispatchSynchronousVisibleCommit(commit) {
+		getBrowserRouterStateSetter()(applyApprovedVisibleCommit(getBrowserRouterState(), commit));
+	}
+	function createRestoredHistorySnapshotCommit(options) {
+		const operation = {
+			id: options.renderId,
+			lane: "traverse",
+			startedVisibleCommitVersion: options.currentState.visibleCommitVersion,
+			state: "pending"
+		};
+		return {
+			action: {
+				bfcacheIds: options.restoredState.bfcacheIds,
+				elements: options.restoredState.elements,
+				interception: options.restoredState.interception,
+				interceptionContext: options.restoredState.interceptionContext,
+				layoutFlags: options.restoredState.layoutFlags,
+				layoutIds: options.restoredState.layoutIds,
+				navigationSnapshot: options.restoredState.navigationSnapshot,
+				operation,
+				previousNextUrl: options.restoredState.previousNextUrl,
+				renderId: options.renderId,
+				rootLayoutTreePath: options.restoredState.rootLayoutTreePath,
+				reuseCurrentBfcacheIds: false,
+				routeId: options.restoredState.routeId,
+				skippedLayoutIds: [],
+				slotBindings: options.restoredState.slotBindings,
+				type: "traverse"
+			},
+			interception: options.restoredState.interception,
+			interceptionContext: options.restoredState.interceptionContext,
+			previousNextUrl: options.restoredState.previousNextUrl,
+			rootLayoutTreePath: options.restoredState.rootLayoutTreePath,
+			routeId: options.restoredState.routeId,
+			skippedLayoutIds: []
+		};
+	}
+	function restoreHistorySnapshotVisibleState(options) {
+		if (!isSnapshotTargetHref(basePath, options.state.navigationSnapshot, options.targetHref)) return false;
+		const currentState = getBrowserRouterState();
+		const pending = createRestoredHistorySnapshotCommit({
+			currentState,
+			renderId: allocateRenderId(),
+			restoredState: options.state
+		});
+		const approval = approvePendingNavigationCommit({
+			activeNavigationId,
+			currentState,
+			pending,
+			routeManifest: getRouteManifest(),
+			startedNavigationId: options.navId,
+			targetHref: options.targetHref
+		});
+		if (approval.approvedCommit === null) return false;
+		options.beforeCommit?.();
+		dispatchSynchronousVisibleCommit(approval.approvedCommit);
+		return true;
+	}
+	function notifyDiscardedServerActionRevalidation(lifecycleOptions) {
+		if (!shouldScheduleRefreshForDiscardedServerAction(lifecycleOptions?.revalidation ?? "none")) return;
+		lifecycleOptions?.onDiscardedRevalidation?.();
+	}
+	async function renderNavigationPayload(options) {
+		const renderId = allocateRenderId();
+		const failureTarget = getAppNavigationFailureTarget(options.targetHref);
+		if (failureTarget) pendingNavigationFailureTargets.set(renderId, failureTarget);
+		let resolveCommitted;
+		const committed = new Promise((resolve) => {
+			resolveCommitted = resolve;
+			pendingNavigationCommits.set(renderId, resolve);
+		});
+		let snapshotActivated = false;
+		try {
+			const pending = await createPendingNavigationCommit({
+				currentState: getBrowserRouterState(),
+				nextElements: options.nextElements,
+				navigationSnapshot: options.navigationSnapshot,
+				operationLane: options.operationLane,
+				payloadOrigin: options.payloadOrigin,
+				previousNextUrl: options.previousNextUrl,
+				renderId,
+				restoredBfcacheIds: options.restoredBfcacheIds,
+				reuseCurrentBfcacheIds: options.reuseCurrentBfcacheIds,
+				type: options.actionType
+			});
+			const approval = approvePendingNavigationCommit({
+				activeNavigationId,
+				currentState: getBrowserRouterState(),
+				pending,
+				routeManifest: getRouteManifest(),
+				startedNavigationId: options.navId,
+				targetHref: options.targetHref
+			});
+			if (approval.decision.disposition === "no-commit") {
+				settlePendingBrowserRouterState(options.pendingRouterState);
+				pendingNavigationFailureTargets.delete(renderId);
+				if (failureTarget) clearAppNavigationFailureTarget(failureTarget);
+				pendingNavigationCommits.delete(renderId);
+				resolveCommitted?.();
+				consumeAppRouterScrollIntent(options.scrollIntent ?? null);
+				return "no-commit";
+			}
+			if (approval.decision.disposition === "hard-navigate") {
+				settlePendingBrowserRouterState(options.pendingRouterState);
+				pendingNavigationFailureTargets.delete(renderId);
+				pendingNavigationCommits.delete(renderId);
+				consumeAppRouterScrollIntent(options.scrollIntent ?? null);
+				if (performHardNavigation(options.targetHref)) return "hard-navigate";
+				if (failureTarget) clearAppNavigationFailureTarget(failureTarget);
+				return "no-commit";
+			}
+			const approvedCommit = approval.approvedCommit;
+			if (approvedCommit === null) throw new Error("[vinext] Commit decision did not approve a visible commit");
+			queuePrePaintNavigationEffect(renderId, options.createNavigationCommitEffect({
+				bfcacheIds: approvedCommit.action.bfcacheIds,
+				href: options.targetHref,
+				historyUpdateMode: options.historyUpdateMode,
+				navId: options.navId,
+				params: options.params,
+				previousNextUrl: approvedCommit.previousNextUrl,
+				targetHistoryIndex: options.targetHistoryIndex
+			}));
+			claimAppRouterScrollIntentForCommit(options.scrollIntent, renderId);
+			activateNavigationSnapshot();
+			snapshotActivated = true;
+			dispatchApprovedVisibleCommit(approvedCommit, options.pendingRouterState, options.visibleCommitMode ?? "transition");
+		} catch (error) {
+			pendingNavigationFailureTargets.delete(renderId);
+			pendingNavigationPrePaintEffects.delete(renderId);
+			pendingNavigationCommits.delete(renderId);
+			if (snapshotActivated) commitClientNavigationStateImpl(options.navId);
+			settlePendingBrowserRouterState(options.pendingRouterState);
+			resolveCommitted?.();
+			throw error;
+		}
+		return committed.then(() => "committed");
+	}
+	async function commitSameUrlNavigatePayload(nextElements, navigationSnapshot, returnValue, actionInitiationState, lifecycleOptions) {
+		const currentState = actionInitiationState ?? getBrowserRouterState();
+		const startedNavigationId = lifecycleOptions?.startedNavigationId ?? activeNavigationId;
+		const targetHref = lifecycleOptions?.targetHref ?? window.location.href;
+		const { approvedCommit, decision, pending, trace: _navigationTrace } = await resolveAndClassifyNavigationCommit({
+			activeNavigationId,
+			currentState,
+			getActiveNavigationId: () => activeNavigationId,
+			getCurrentStateForApproval: getBrowserRouterState,
+			navigationSnapshot,
+			nextElements,
+			renderId: allocateRenderId(),
+			operationLane: "server-action",
+			payloadOrigin: FRESH_APP_NAVIGATION_PAYLOAD_ORIGIN,
+			startedNavigationId,
+			routeManifest: getRouteManifest(),
+			targetHref,
+			type: "navigate"
+		});
+		if (decision.disposition === "hard-navigate") {
+			performHardNavigation(targetHref);
+			return;
+		}
+		if (approvedCommit) {
+			const latestApproval = approvePendingNavigationCommit({
+				activeNavigationId,
+				currentState: getBrowserRouterState(),
+				pending,
+				routeManifest: getRouteManifest(),
+				startedNavigationId,
+				targetHref
+			});
+			if (latestApproval.decision.disposition === "hard-navigate") {
+				performHardNavigation(targetHref);
+				return;
+			}
+			if (latestApproval.approvedCommit) {
+				dispatchSynchronousVisibleCommit(latestApproval.approvedCommit);
+				syncHistoryStatePreviousNextUrl(latestApproval.approvedCommit.previousNextUrl, latestApproval.approvedCommit.action.bfcacheIds);
+			} else notifyDiscardedServerActionRevalidation(lifecycleOptions);
+		} else if (decision.disposition === "no-commit") notifyDiscardedServerActionRevalidation(lifecycleOptions);
+		if (returnValue) {
+			if (!returnValue.ok) throw returnValue.data;
+			return returnValue.data;
+		}
+	}
+	function attachBrowserRouterState(setter, stateRef) {
+		setBrowserRouterState = setter;
+		browserRouterStateRef = stateRef;
+		markBrowserRouterStateReady();
+		return () => {
+			if (setBrowserRouterState === setter) setBrowserRouterState = null;
+			if (browserRouterStateRef === stateRef) {
+				browserRouterStateRef = null;
+				browserRouterStateHasCommitted = false;
+			}
+		};
+	}
+	return {
+		beginNavigation,
+		getActiveNavigationId,
+		hasBrowserRouterState,
+		getBrowserRouterState,
+		isCurrentNavigation,
+		performHardNavigation,
+		waitForBrowserRouterStateReady,
+		attachBrowserRouterState,
+		beginPendingBrowserRouterState,
+		finalizeNavigation,
+		restoreHistorySnapshotVisibleState,
+		renderNavigationPayload,
+		commitSameUrlNavigatePayload,
+		hmrReplaceTree,
+		drainPrePaintEffects,
+		clearCommittedNavigationFailureTargets,
+		NavigationCommitSignal
+	};
+}
+//#endregion
+export { clearHardNavigationLoopGuard, createAppBrowserNavigationController, createBasePathStrippedPathAndSearch, createSnapshotPathAndSearch };

package/dist/server/app-browser-popstate.d.ts

@@ -0,0 +1,26 @@
+import { NavigationRuntimeNavigate } from "../client/navigation-runtime.js";
+
+//#region src/server/app-browser-popstate.d.ts
+type RestoreScrollPosition = (state: unknown, options?: {
+  shouldContinue?: () => boolean;
+}) => void;
+type BrowserPopstateRestoreDeps = {
+  getActiveNavigationId: () => number;
+  getPendingNavigation: () => Promise<void> | null | undefined;
+  getNavigate: () => NavigationRuntimeNavigate | undefined;
+  isCurrentNavigation: (navId: number) => boolean;
+  notifyAppRouterTransitionStart: (href: string) => void;
+  restorePopstateScrollPosition: RestoreScrollPosition;
+  setPendingNavigation: (pendingNavigation: Promise<void> | null) => void;
+  shouldSkipScrollRestore: (navId: number) => boolean;
+};
+type SynchronousPopstateScrollRestoreDeps = {
+  getActiveNavigationId: () => number;
+  isCurrentNavigation: (navId: number) => boolean;
+  markScrollRestoreConsumed: (navId: number) => void;
+  restorePopstateScrollPosition: RestoreScrollPosition;
+};
+declare function restoreSynchronousPopstateScrollPosition(deps: SynchronousPopstateScrollRestoreDeps, state: unknown): void;
+declare function createPopstateRestoreHandler(deps: BrowserPopstateRestoreDeps): (event: PopStateEvent) => void;
+//#endregion
+export { createPopstateRestoreHandler, restoreSynchronousPopstateScrollPosition };

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

@@ -0,0 +1,44 @@
+import { readHistoryStateTraversalIndex } from "./app-history-state.js";
+import "./app-browser-state.js";
+//#region src/server/app-browser-popstate.ts
+function hasSavedScrollPosition(state) {
+	return Boolean(state && typeof state === "object" && "__vinext_scrollY" in state);
+}
+function restoreSynchronousPopstateScrollPosition(deps, state) {
+	const navId = deps.getActiveNavigationId();
+	deps.markScrollRestoreConsumed(navId);
+	deps.restorePopstateScrollPosition(state, { shouldContinue: () => deps.isCurrentNavigation(navId) });
+}
+function scheduleAfterFrame(callback) {
+	if (typeof window !== "undefined" && typeof window.requestAnimationFrame === "function") {
+		window.requestAnimationFrame(callback);
+		return;
+	}
+	queueMicrotask(callback);
+}
+function createPopstateTraversalIntent(historyState) {
+	return {
+		direction: "unknown",
+		historyState,
+		targetHistoryIndex: readHistoryStateTraversalIndex(historyState)
+	};
+}
+function createPopstateRestoreHandler(deps) {
+	return (event) => {
+		deps.notifyAppRouterTransitionStart(window.location.href);
+		const pendingNavigation = deps.getNavigate()?.(window.location.href, 0, "traverse", void 0, void 0, false, createPopstateTraversalIntent(event.state)) ?? Promise.resolve();
+		const popstateNavId = deps.getActiveNavigationId();
+		deps.setPendingNavigation(pendingNavigation);
+		const shouldRestoreSavedScroll = hasSavedScrollPosition(event.state);
+		const shouldRestoreScrollForNavigation = () => deps.isCurrentNavigation(popstateNavId) && !deps.shouldSkipScrollRestore(popstateNavId);
+		if (shouldRestoreSavedScroll) scheduleAfterFrame(() => {
+			if (shouldRestoreScrollForNavigation()) deps.restorePopstateScrollPosition(event.state, { shouldContinue: shouldRestoreScrollForNavigation });
+		});
+		pendingNavigation.finally(() => {
+			if (shouldRestoreScrollForNavigation() && !shouldRestoreSavedScroll) deps.restorePopstateScrollPosition(event.state);
+			if (deps.getPendingNavigation() === pendingNavigation) deps.setPendingNavigation(null);
+		});
+	};
+}
+//#endregion
+export { createPopstateRestoreHandler, restoreSynchronousPopstateScrollPosition };

package/dist/server/app-browser-rsc-redirect.d.ts

@@ -0,0 +1,38 @@
+//#region src/server/app-browser-rsc-redirect.d.ts
+declare function blockDangerousStreamedRscRedirect(response: Response, streamedRedirectTarget: string | null): boolean;
+type RscRedirectHistoryUpdateMode = "push" | "replace" | undefined;
+type RscRedirectLifecycleDecision = {
+  href: string;
+  kind: "no-redirect";
+} | {
+  href: string;
+  historyUpdateMode: RscRedirectHistoryUpdateMode;
+  kind: "follow";
+  previousNextUrl: string | null;
+  redirectDepth: number;
+} | {
+  href: string;
+  kind: "terminal-hard-navigation";
+  reason: "externalRedirect" | "maxRedirectsExceeded";
+  redirectDepth: number;
+};
+declare function resolveRscRedirectLifecycleHop(options: {
+  currentHref: string;
+  historyUpdateMode: RscRedirectHistoryUpdateMode;
+  maxRedirectDepth?: number;
+  origin: string;
+  redirectDepth: number;
+  requestPreviousNextUrl: string | null;
+  responseUrl: string;
+}): RscRedirectLifecycleDecision;
+declare function resolveStreamedRscRedirectLifecycleHop(options: {
+  currentHref: string;
+  historyUpdateMode: Exclude<RscRedirectHistoryUpdateMode, undefined>;
+  maxRedirectDepth?: number;
+  origin: string;
+  redirectDepth: number;
+  requestPreviousNextUrl: string | null;
+  streamedRedirectTarget: string;
+}): RscRedirectLifecycleDecision;
+//#endregion
+export { blockDangerousStreamedRscRedirect, resolveRscRedirectLifecycleHop, resolveStreamedRscRedirectLifecycleHop };