vinext 0.1.0 → 0.1.2

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

@@ -2,5 +2,8 @@
 declare function createOnUncaughtError(getRecoveryHref: () => string | null): (error: unknown, errorInfo: {
   componentStack?: string;
 }) => void;
+declare function prodOnCaughtError(error: unknown, errorInfo: {
+  componentStack?: string;
+}): void;
 //#endregion
-export { createOnUncaughtError };
+export { createOnUncaughtError, prodOnCaughtError };

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

@@ -1,3 +1,4 @@
+import { isNavigationSignalError } from "../utils/navigation-signal.js";
 //#region src/server/app-browser-error.ts
 function createOnUncaughtError(getRecoveryHref) {
 	return (error, errorInfo) => {
@@ -7,5 +8,10 @@ function createOnUncaughtError(getRecoveryHref) {
 		if (recoveryHref !== null) window.location.assign(recoveryHref);
 	};
 }
+function prodOnCaughtError(error, errorInfo) {
+	if (isNavigationSignalError(error)) return;
+	console.error(error);
+	if (errorInfo?.componentStack) console.error("The above error occurred in a React component:\n" + errorInfo.componentStack);
+}
 //#endregion
-export { createOnUncaughtError };
+export { createOnUncaughtError, prodOnCaughtError };

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

@@ -0,0 +1,104 @@
+import { BfcacheIdMap, HistoryTraversalIntent } from "./app-history-state.js";
+import { AppRouterState } from "./app-browser-state.js";
+import { HistoryUpdateMode } from "./app-browser-navigation-controller.js";
+
+//#region src/server/app-browser-history-controller.d.ts
+/**
+ * Visible router-state metadata at the instant a hash-only navigation commits.
+ * `null` means the browser router tree has not committed yet, so the controller
+ * falls back to reading the same facts off the live history entry.
+ */
+type VisibleNavigationMetadata = {
+  bfcacheIds: BfcacheIdMap | null;
+  previousNextUrl: string | null;
+};
+type AppBrowserHistoryControllerDeps = {
+  initialHistoryState: unknown;
+  maxHistoryStateSnapshots: number; /** Reads `window.history.state`. Injected so the controller stays unit-testable. */
+  readHistoryState: () => unknown; /** Reads `window.location.href`. Injected so the controller stays unit-testable. */
+  readCurrentHref: () => string; /** Wraps `pushHistoryStateWithoutNotify(state, "", href)`. */
+  pushHistoryState: (state: unknown, href: string) => void; /** Wraps `replaceHistoryStateWithoutNotify(state, "", href)`. */
+  replaceHistoryState: (state: unknown, href: string) => void;
+  readVisibleNavigationMetadata: () => VisibleNavigationMetadata | null;
+};
+/**
+ * Candidate visible state resolved from a restorable history snapshot, handed to
+ * the entry's approved-visible-restore callback. The controller resolves the
+ * candidate and owns the traversal-index commit; the entry owns the actual
+ * `AppBrowserNavigationController.restoreHistorySnapshotVisibleState()` call and
+ * the `ApprovedVisibleCommit` boundary.
+ */
+type RestorableSnapshotCandidate = {
+  state: AppRouterState;
+  beforeCommit: () => void;
+};
+type RestoreHistorySnapshotOptions = {
+  historyState: unknown;
+  stageClientParams: (params: Record<string, string | string[]>) => void;
+  approveVisibleRestore: (candidate: RestorableSnapshotCandidate) => boolean;
+};
+type CommitNavigationHistoryOptions = {
+  bfcacheIds: BfcacheIdMap;
+  href: string;
+  historyUpdateMode: HistoryUpdateMode | undefined;
+  previousNextUrl: string | null;
+  targetHistoryIndex?: number | null;
+  stageClientParams: () => void;
+};
+/**
+ * Owns App Router browser-history metadata and traversal bookkeeping behind a
+ * typed seam: traversal index allocation/commit, push/replace/traverse/hash-only
+ * history-state writes, BFCache epoch/snapshot invalidation through
+ * `RestorableClientStateController`, and restorable-snapshot candidate
+ * resolution.
+ *
+ * Ownership boundary: this is not a second router or visible-state authority. It
+ * resolves history facts and delegates visible restoration through an injected
+ * approved-commit callback. It never sets router state directly, never imports
+ * `applyApprovedVisibleCommit()`, and never bypasses the `ApprovedVisibleCommit`
+ * boundary owned by `AppBrowserNavigationController`.
+ */
+declare class AppBrowserHistoryController {
+  #private;
+  constructor(deps: AppBrowserHistoryControllerDeps);
+  get currentHistoryTraversalIndex(): number | null;
+  allocateNavigationHistoryTraversalIndex(historyUpdateMode: HistoryUpdateMode | undefined): number | null;
+  commitHistoryTraversalIndex(index: number | null): void;
+  commitTraversalIndexFromHistoryState(historyState: unknown): void;
+  resolveTraversalIntent(historyState: unknown): HistoryTraversalIntent;
+  readCurrentBfcacheVersionHistoryIds(historyState: unknown): BfcacheIdMap | null;
+  isCacheInvalidationGuarded(): boolean;
+  isCurrentBfcacheVersion(historyState: unknown): boolean;
+  beginCacheInvalidationGuard(): () => void;
+  invalidateRestorableClientState(): void;
+  rememberHistoryStateSnapshot(state: AppRouterState): void;
+  commitHashOnlyNavigation(href: string, historyUpdateMode: HistoryUpdateMode, scroll: boolean): void;
+  /**
+   * Writes the history entry for an approved push/replace/traverse commit and
+   * advances the traversal index. `stageClientParams` runs at the exact point it
+   * ran inline in the browser-entry commit effect so client-param staging stays
+   * ordered relative to the history write. Mirrors Next.js committing tree state
+   * into the history entry during the navigation commit.
+   */
+  commitNavigationHistory(options: CommitNavigationHistoryOptions): void;
+  syncCurrentHistoryStatePreviousNextUrl(previousNextUrl: string | null, bfcacheIds?: BfcacheIdMap | null): void;
+  /** Initial history write performed before hydration starts. */
+  writeBootstrapHistoryMetadata(): void;
+  /** History write performed on the first committed (hydrated) render. */
+  writeHydratedHistoryMetadata(options: {
+    bfcacheIds: BfcacheIdMap;
+    previousNextUrl: string | null;
+  }): void;
+  /**
+   * Resolves a restorable snapshot candidate for the given history entry and
+   * commits the traversal index after, and only after, the injected
+   * approved-visible-restore callback succeeds. The traversal-index commit and
+   * client-param staging run inside `beforeCommit`, which the
+   * `AppBrowserNavigationController` invokes only once the `ApprovedVisibleCommit`
+   * is approved. Returns false when no snapshot is restorable or the restore is
+   * not approved.
+   */
+  restoreHistorySnapshot(options: RestoreHistorySnapshotOptions): boolean;
+}
+//#endregion
+export { AppBrowserHistoryController, RestorableSnapshotCandidate };

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

@@ -0,0 +1,210 @@
+import { RestorableClientStateController, createHistoryStateWithNavigationMetadata, readHistoryStateBfcacheIds, readHistoryStatePreviousNextUrl, readHistoryStateTraversalIndex, resolveHistoryTraversalIntent } from "./app-history-state.js";
+//#region src/server/app-browser-history-controller.ts
+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;
+}
+/**
+* Owns App Router browser-history metadata and traversal bookkeeping behind a
+* typed seam: traversal index allocation/commit, push/replace/traverse/hash-only
+* history-state writes, BFCache epoch/snapshot invalidation through
+* `RestorableClientStateController`, and restorable-snapshot candidate
+* resolution.
+*
+* Ownership boundary: this is not a second router or visible-state authority. It
+* resolves history facts and delegates visible restoration through an injected
+* approved-commit callback. It never sets router state directly, never imports
+* `applyApprovedVisibleCommit()`, and never bypasses the `ApprovedVisibleCommit`
+* boundary owned by `AppBrowserNavigationController`.
+*/
+var AppBrowserHistoryController = class {
+	#restorableClientState;
+	#readHistoryState;
+	#readCurrentHref;
+	#pushHistoryState;
+	#replaceHistoryState;
+	#readVisibleNavigationMetadata;
+	#currentHistoryTraversalIndex;
+	#nextHistoryTraversalIndex;
+	constructor(deps) {
+		this.#readHistoryState = deps.readHistoryState;
+		this.#readCurrentHref = deps.readCurrentHref;
+		this.#pushHistoryState = deps.pushHistoryState;
+		this.#replaceHistoryState = deps.replaceHistoryState;
+		this.#readVisibleNavigationMetadata = deps.readVisibleNavigationMetadata;
+		this.#restorableClientState = new RestorableClientStateController({
+			initialHistoryState: deps.initialHistoryState,
+			maxHistoryStateSnapshots: deps.maxHistoryStateSnapshots
+		});
+		this.#currentHistoryTraversalIndex = readHistoryStateTraversalIndex(deps.initialHistoryState) ?? 0;
+		this.#nextHistoryTraversalIndex = this.#currentHistoryTraversalIndex;
+	}
+	get currentHistoryTraversalIndex() {
+		return this.#currentHistoryTraversalIndex;
+	}
+	allocateNavigationHistoryTraversalIndex(historyUpdateMode) {
+		switch (historyUpdateMode) {
+			case "push": return this.#nextHistoryTraversalIndex + 1;
+			case "replace": return this.#currentHistoryTraversalIndex;
+			case void 0: return null;
+			default: throw new Error("[vinext] Unknown history update mode: " + String(historyUpdateMode));
+		}
+	}
+	commitHistoryTraversalIndex(index) {
+		this.#currentHistoryTraversalIndex = index;
+		if (index !== null) this.#nextHistoryTraversalIndex = Math.max(this.#nextHistoryTraversalIndex, index);
+	}
+	commitTraversalIndexFromHistoryState(historyState) {
+		this.commitHistoryTraversalIndex(readHistoryStateTraversalIndex(historyState));
+	}
+	resolveTraversalIntent(historyState) {
+		return resolveHistoryTraversalIntent({
+			currentHistoryIndex: this.#currentHistoryTraversalIndex,
+			historyState
+		});
+	}
+	readCurrentBfcacheVersionHistoryIds(historyState) {
+		return this.#restorableClientState.readCurrentBfcacheVersionHistoryIds(historyState);
+	}
+	isCacheInvalidationGuarded() {
+		return this.#restorableClientState.isCacheInvalidationGuarded();
+	}
+	isCurrentBfcacheVersion(historyState) {
+		return this.#restorableClientState.isCurrentBfcacheVersion(historyState);
+	}
+	beginCacheInvalidationGuard() {
+		return this.#restorableClientState.beginCacheInvalidationGuard();
+	}
+	invalidateRestorableClientState() {
+		this.#restorableClientState.invalidateClientState();
+	}
+	rememberHistoryStateSnapshot(state) {
+		this.#restorableClientState.rememberHistoryStateSnapshot({
+			historyIndex: this.#currentHistoryTraversalIndex,
+			state
+		});
+	}
+	commitHashOnlyNavigation(href, historyUpdateMode, scroll) {
+		const navigationHistoryIndex = this.allocateNavigationHistoryTraversalIndex(historyUpdateMode);
+		const historyState = this.#readHistoryState();
+		const visible = this.#readVisibleNavigationMetadata();
+		const previousNextUrl = visible ? visible.previousNextUrl : readHistoryStatePreviousNextUrl(historyState);
+		const bfcacheIds = visible ? visible.bfcacheIds : this.#restorableClientState.readCurrentBfcacheVersionHistoryIds(historyState);
+		const nextHistoryState = createHistoryStateWithNavigationMetadata(this.#createHashOnlyNavigationBaseHistoryState(historyUpdateMode, scroll), {
+			bfcacheIds,
+			bfcacheVersion: bfcacheIds === null ? void 0 : this.#restorableClientState.currentBfcacheVersion,
+			previousNextUrl,
+			traversalIndex: navigationHistoryIndex
+		});
+		if (historyUpdateMode === "replace") this.#replaceHistoryState(nextHistoryState, href);
+		else this.#pushHistoryState(nextHistoryState, href);
+		this.commitHistoryTraversalIndex(navigationHistoryIndex);
+	}
+	#createHashOnlyNavigationBaseHistoryState(historyUpdateMode, scroll) {
+		if (historyUpdateMode !== "replace") return null;
+		const historyState = this.#readHistoryState();
+		return scroll ? stripVinextScrollState(historyState) : historyState;
+	}
+	/**
+	* Writes the history entry for an approved push/replace/traverse commit and
+	* advances the traversal index. `stageClientParams` runs at the exact point it
+	* ran inline in the browser-entry commit effect so client-param staging stays
+	* ordered relative to the history write. Mirrors Next.js committing tree state
+	* into the history entry during the navigation commit.
+	*/
+	commitNavigationHistory(options) {
+		const currentHref = this.#readCurrentHref();
+		const origin = new URL(currentHref).origin;
+		const targetHref = new URL(options.href, origin).href;
+		const preserveExistingState = options.historyUpdateMode === "replace";
+		const navigationHistoryIndex = options.targetHistoryIndex !== void 0 ? options.targetHistoryIndex : this.allocateNavigationHistoryTraversalIndex(options.historyUpdateMode);
+		const historyState = createHistoryStateWithNavigationMetadata(preserveExistingState ? this.#readHistoryState() : null, {
+			bfcacheIds: options.bfcacheIds,
+			bfcacheVersion: this.#restorableClientState.currentBfcacheVersion,
+			previousNextUrl: options.previousNextUrl,
+			traversalIndex: navigationHistoryIndex
+		});
+		let wroteHistoryState = false;
+		if (options.historyUpdateMode === "replace" && currentHref !== targetHref) {
+			options.stageClientParams();
+			this.#replaceHistoryState(historyState, options.href);
+			wroteHistoryState = true;
+			this.commitHistoryTraversalIndex(navigationHistoryIndex);
+		} else if (options.historyUpdateMode === "push" && currentHref !== targetHref) {
+			options.stageClientParams();
+			this.#pushHistoryState(historyState, options.href);
+			wroteHistoryState = true;
+			this.commitHistoryTraversalIndex(navigationHistoryIndex);
+		}
+		if (!wroteHistoryState) {
+			this.syncCurrentHistoryStatePreviousNextUrl(options.previousNextUrl, options.bfcacheIds);
+			options.stageClientParams();
+			if (options.targetHistoryIndex !== void 0) this.commitHistoryTraversalIndex(options.targetHistoryIndex);
+		}
+	}
+	syncCurrentHistoryStatePreviousNextUrl(previousNextUrl, bfcacheIds) {
+		if (this.#isHistoryStateNavigationMetadataInSync(this.#readHistoryState(), previousNextUrl, bfcacheIds)) return;
+		const nextHistoryState = createHistoryStateWithNavigationMetadata(this.#readHistoryState(), {
+			bfcacheIds,
+			bfcacheVersion: bfcacheIds === void 0 ? void 0 : this.#restorableClientState.currentBfcacheVersion,
+			previousNextUrl
+		});
+		this.#replaceHistoryState(nextHistoryState, this.#readCurrentHref());
+		if (this.#isHistoryStateNavigationMetadataInSync(this.#readHistoryState(), previousNextUrl, bfcacheIds)) return;
+		this.#replaceHistoryState(nextHistoryState, this.#readCurrentHref());
+	}
+	#isHistoryStateNavigationMetadataInSync(state, previousNextUrl, bfcacheIds) {
+		return readHistoryStatePreviousNextUrl(state) === previousNextUrl && (bfcacheIds === void 0 || areBfcacheIdMapsEqual(readHistoryStateBfcacheIds(state), bfcacheIds) && this.#restorableClientState.isCurrentBfcacheVersion(state));
+	}
+	/** Initial history write performed before hydration starts. */
+	writeBootstrapHistoryMetadata() {
+		this.#replaceHistoryState(createHistoryStateWithNavigationMetadata(this.#readHistoryState(), {
+			previousNextUrl: null,
+			traversalIndex: this.#currentHistoryTraversalIndex
+		}), this.#readCurrentHref());
+	}
+	/** History write performed on the first committed (hydrated) render. */
+	writeHydratedHistoryMetadata(options) {
+		this.#replaceHistoryState(createHistoryStateWithNavigationMetadata(this.#readHistoryState(), {
+			bfcacheIds: options.bfcacheIds,
+			bfcacheVersion: this.#restorableClientState.currentBfcacheVersion,
+			previousNextUrl: options.previousNextUrl,
+			traversalIndex: this.#currentHistoryTraversalIndex
+		}), this.#readCurrentHref());
+	}
+	/**
+	* Resolves a restorable snapshot candidate for the given history entry and
+	* commits the traversal index after, and only after, the injected
+	* approved-visible-restore callback succeeds. The traversal-index commit and
+	* client-param staging run inside `beforeCommit`, which the
+	* `AppBrowserNavigationController` invokes only once the `ApprovedVisibleCommit`
+	* is approved. Returns false when no snapshot is restorable or the restore is
+	* not approved.
+	*/
+	restoreHistorySnapshot(options) {
+		const decision = this.#restorableClientState.resolveHistoryStateSnapshotRestore(options.historyState);
+		if (decision.kind === "skip") return false;
+		return options.approveVisibleRestore({
+			state: decision.state,
+			beforeCommit: () => {
+				this.commitHistoryTraversalIndex(decision.targetHistoryIndex);
+				options.stageClientParams(decision.state.navigationSnapshot.params);
+			}
+		});
+	}
+};
+function areBfcacheIdMapsEqual(a, b) {
+	if (a === b) return true;
+	if (a === null || b === null) return false;
+	const aEntries = Object.entries(a);
+	const bEntries = Object.entries(b);
+	if (aEntries.length !== bEntries.length) return false;
+	return aEntries.every(([key, value]) => b[key] === value);
+}
+//#endregion
+export { AppBrowserHistoryController };

package/dist/server/app-browser-interception-context.d.ts

@@ -19,5 +19,6 @@ type ResolveManifestNavigationInterceptionContextOptions = {
  * is owned by the deterministic route graph builder.
  */
 declare function resolveManifestNavigationInterceptionContext(options: ResolveManifestNavigationInterceptionContextOptions): string | null;
+declare function resolveMiddlewareRewriteNavigationInterceptionContext(options: ResolveManifestNavigationInterceptionContextOptions): string | null;
 //#endregion
-export { resolveManifestNavigationInterceptionContext };
+export { resolveManifestNavigationInterceptionContext, resolveMiddlewareRewriteNavigationInterceptionContext };

package/dist/server/app-browser-interception-context.js

@@ -1,6 +1,6 @@
 import { splitPathnameForRouteMatch } from "../routing/utils.js";
 import { stripBasePath } from "../utils/base-path.js";
-import { matchRoutePattern, matchRoutePatternPrefix } from "../routing/route-pattern.js";
+import { matchRoutePattern, matchRoutePatternPrefix, matchRoutePatternWithOptionalDynamicSegments } from "../routing/route-pattern.js";
 //#region src/server/app-browser-interception-context.ts
 /**
 * Resolve the first-hop interception context from declared route topology.
@@ -26,5 +26,18 @@ function resolveManifestNavigationInterceptionContext(options) {
 	}
 	return null;
 }
+function resolveMiddlewareRewriteNavigationInterceptionContext(options) {
+	if (options.routeManifest === null) return null;
+	const currentPathname = stripBasePath(options.currentPathname, options.basePath);
+	const targetPathname = stripBasePath(options.targetPathname, options.basePath);
+	const sourceParts = splitPathnameForRouteMatch(currentPathname);
+	const targetParts = splitPathnameForRouteMatch(targetPathname);
+	for (const interception of options.routeManifest.segmentGraph.interceptions.values()) {
+		if (!matchRoutePatternPrefix(sourceParts, interception.sourcePatternParts)) continue;
+		if (!matchRoutePatternWithOptionalDynamicSegments(targetParts, interception.targetPatternParts)) continue;
+		return currentPathname;
+	}
+	return null;
+}
 //#endregion
-export { resolveManifestNavigationInterceptionContext };
+export { resolveManifestNavigationInterceptionContext, resolveMiddlewareRewriteNavigationInterceptionContext };

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

@@ -1,9 +1,10 @@
 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 { ServerActionRevalidationKind } from "./app-browser-action-result.js";
 import { AppElements } from "./app-elements-wire.js";
 import { OperationLane } from "./navigation-planner.js";
-import { ClientNavigationRenderSnapshot, commitClientNavigationState } from "../shims/navigation.js";
+import { ClientNavigationRenderSnapshot, commitClientNavigationState, createSnapshotPathAndSearch } from "../shims/navigation.js";
 import { AppNavigationPayloadOrigin, AppRouterState } from "./app-browser-state.js";
 import { Dispatch, ReactNode } from "react";
 
@@ -35,6 +36,7 @@ type SameUrlServerActionLifecycleOptions = {
   targetHref?: string;
 };
 type BrowserNavigationControllerDeps = {
+  basePath?: string;
   commitClientNavigationState?: typeof commitClientNavigationState;
   performHardNavigation?: (href: string, mode?: HardNavigationMode) => boolean;
   getRouteManifest?: () => RouteManifest | null;
@@ -51,6 +53,12 @@ type BrowserNavigationController = {
   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;
@@ -64,9 +72,11 @@ type BrowserNavigationController = {
     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;
@@ -91,6 +101,7 @@ type BrowserNavigationController = {
   }): 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 };
+export { HistoryUpdateMode, NavigationPayloadOutcome, PendingBrowserRouterState, clearHardNavigationLoopGuard, createAppBrowserNavigationController, createBasePathStrippedPathAndSearch, createSnapshotPathAndSearch };

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

@@ -1,9 +1,11 @@
+import { stripBasePath } from "../utils/base-path.js";
 import { claimAppRouterScrollIntentForCommit, consumeAppRouterScrollIntent } from "../shims/app-router-scroll-state.js";
-import { activateNavigationSnapshot, clearPendingPathname, commitClientNavigationState } from "../shims/navigation.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, 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) {
@@ -49,7 +51,21 @@ function performHardNavigationWithLoopGuard(href, mode = "assign") {
 	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);
@@ -202,12 +218,18 @@ function createAppBrowserNavigationController(deps = {}) {
 		}, [renderId]);
 		return children;
 	}
-	function dispatchApprovedVisibleCommit(commit, pendingRouterState) {
+	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));
 		});
@@ -215,6 +237,61 @@ function createAppBrowserNavigationController(deps = {}) {
 	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?.();
@@ -237,6 +314,7 @@ function createAppBrowserNavigationController(deps = {}) {
 				previousNextUrl: options.previousNextUrl,
 				renderId,
 				restoredBfcacheIds: options.restoredBfcacheIds,
+				reuseCurrentBfcacheIds: options.reuseCurrentBfcacheIds,
 				type: options.actionType
 			});
 			const approval = approvePendingNavigationCommit({
@@ -274,7 +352,7 @@ function createAppBrowserNavigationController(deps = {}) {
 			claimAppRouterScrollIntentForCommit(options.scrollIntent, renderId);
 			activateNavigationSnapshot();
 			snapshotActivated = true;
-			dispatchApprovedVisibleCommit(approvedCommit, options.pendingRouterState);
+			dispatchApprovedVisibleCommit(approvedCommit, options.pendingRouterState, options.visibleCommitMode ?? "transition");
 		} catch (error) {
 			pendingNavigationPrePaintEffects.delete(renderId);
 			pendingNavigationCommits.delete(renderId);
@@ -354,6 +432,7 @@ function createAppBrowserNavigationController(deps = {}) {
 		attachBrowserRouterState,
 		beginPendingBrowserRouterState,
 		finalizeNavigation,
+		restoreHistorySnapshotVisibleState,
 		renderNavigationPayload,
 		commitSameUrlNavigatePayload,
 		hmrReplaceTree,
@@ -362,4 +441,4 @@ function createAppBrowserNavigationController(deps = {}) {
 	};
 }
 //#endregion
-export { clearHardNavigationLoopGuard, createAppBrowserNavigationController };
+export { clearHardNavigationLoopGuard, createAppBrowserNavigationController, createBasePathStrippedPathAndSearch, createSnapshotPathAndSearch };

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

@@ -1,17 +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 NavigateRsc = (href: string, redirectDepth?: number, navigationKind?: "navigate" | "traverse" | "refresh") => Promise<void>;
 type BrowserPopstateRestoreDeps = {
   getActiveNavigationId: () => number;
   getPendingNavigation: () => Promise<void> | null | undefined;
-  getNavigate: () => NavigateRsc | 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 };
+export { createPopstateRestoreHandler, restoreSynchronousPopstateScrollPosition };

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

@@ -1,7 +1,14 @@
+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);
@@ -9,21 +16,29 @@ function scheduleAfterFrame(callback) {
 	}
 	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") ?? Promise.resolve();
+		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 (deps.isCurrentNavigation(popstateNavId)) deps.restorePopstateScrollPosition(event.state, { shouldContinue: () => deps.isCurrentNavigation(popstateNavId) });
+			if (shouldRestoreScrollForNavigation()) deps.restorePopstateScrollPosition(event.state, { shouldContinue: shouldRestoreScrollForNavigation });
 		});
 		pendingNavigation.finally(() => {
-			if (deps.isCurrentNavigation(popstateNavId) && !shouldRestoreSavedScroll) deps.restorePopstateScrollPosition(event.state);
+			if (shouldRestoreScrollForNavigation() && !shouldRestoreSavedScroll) deps.restorePopstateScrollPosition(event.state);
 			if (deps.getPendingNavigation() === pendingNavigation) deps.setPendingNavigation(null);
 		});
 	};
 }
 //#endregion
-export { createPopstateRestoreHandler };
+export { createPopstateRestoreHandler, restoreSynchronousPopstateScrollPosition };