vinext 0.1.8 → 0.2.0

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

@@ -1,8 +1,8 @@
 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 { resolveServerActionOperationLane, shouldScheduleRefreshForDiscardedServerAction } from "./app-browser-action-result.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";
@@ -73,6 +73,9 @@ function createAppBrowserNavigationController(deps = {}) {
 	const syncHistoryStatePreviousNextUrl = deps.syncHistoryStatePreviousNextUrl ?? (() => {});
 	let nextNavigationRenderId = 0;
 	let activeNavigationId = 0;
+	let pendingUserNavigationId = null;
+	let pendingUserNavigationLane = null;
+	let latestHmrUpdateId = 0;
 	const pendingNavigationCommits = /* @__PURE__ */ new Map();
 	const pendingNavigationFailureTargets = /* @__PURE__ */ new Map();
 	const pendingNavigationPrePaintEffects = /* @__PURE__ */ new Map();
@@ -105,7 +108,10 @@ function createAppBrowserNavigationController(deps = {}) {
 		resolveReady?.();
 	}
 	function beginNavigation() {
+		latestHmrUpdateId += 1;
 		activeNavigationId += 1;
+		pendingUserNavigationId = activeNavigationId;
+		pendingUserNavigationLane = null;
 		return activeNavigationId;
 	}
 	function getActiveNavigationId() {
@@ -149,13 +155,11 @@ function createAppBrowserNavigationController(deps = {}) {
 	}
 	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;
+		if (isCurrentNavigation(navId)) {
+			pendingUserNavigationId = null;
+			pendingUserNavigationLane = null;
+			clearPendingPathname(navId);
+		}
 	}
 	function queuePrePaintNavigationEffect(renderId, effect) {
 		if (!effect) return;
@@ -181,16 +185,17 @@ function createAppBrowserNavigationController(deps = {}) {
 		}
 	}
 	/**
-	* 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.
+	* Settle all pending navigation renders through the supplied renderId. Only
+	* the exact render whose layout effect ran is a successful commit; older
+	* superseded renders and cleanup-only settlements resolve as no-commit.
 	*/
-	function resolveCommittedNavigations(renderId) {
-		for (const [pendingId, resolve] of pendingNavigationCommits) {
+	function settleNavigationCommits(renderId, committed) {
+		for (const [pendingId, pendingCommit] of pendingNavigationCommits) {
 			if (pendingId > renderId) continue;
 			pendingNavigationCommits.delete(pendingId);
-			resolve();
+			const didCommit = committed && pendingId === renderId;
+			if (didCommit && pendingCommit.committedState !== null) pendingCommit.onCommittedState?.(pendingCommit.committedState);
+			pendingCommit.resolve(didCommit);
 		}
 	}
 	function clearCommittedNavigationFailureTargets(renderId) {
@@ -201,6 +206,8 @@ function createAppBrowserNavigationController(deps = {}) {
 		}
 	}
 	async function hmrReplaceTree(nextElements, navigationSnapshot) {
+		const hmrUpdateId = ++latestHmrUpdateId;
+		const startedDuringUserNavigation = pendingUserNavigationLane === "navigation";
 		if (!hasBrowserRouterState()) return;
 		const pending = await createPendingNavigationCommit({
 			currentState: getBrowserRouterState(),
@@ -211,8 +218,16 @@ function createAppBrowserNavigationController(deps = {}) {
 			renderId: allocateRenderId(),
 			type: "replace"
 		});
+		if (hmrUpdateId !== latestHmrUpdateId || startedDuringUserNavigation) return;
 		if (!hasBrowserRouterState()) return;
-		dispatchSynchronousVisibleCommit(approveHmrVisibleCommit(pending));
+		const approval = approveHmrVisibleCommit({
+			currentState: getBrowserRouterState(),
+			pending,
+			routeManifest: deps.getRouteManifest?.() ?? null,
+			targetHref: createSnapshotPathAndSearch(navigationSnapshot)
+		});
+		if (approval.approvedCommit) dispatchSynchronousVisibleCommit(approval.approvedCommit);
+		else if (approval.decision.disposition === "hard-navigate") performHardNavigation(createSnapshotPathAndSearch(navigationSnapshot));
 	}
 	function NavigationCommitSignal({ renderId, children }) {
 		useInsertionEffect(() => {
@@ -220,30 +235,36 @@ function createAppBrowserNavigationController(deps = {}) {
 		}, [renderId]);
 		useLayoutEffect(() => {
 			drainPrePaintEffects(renderId);
-			const frame = requestAnimationFrame(() => {
-				resolveCommittedNavigations(renderId);
-			});
+			settleNavigationCommits(renderId, true);
 			return () => {
-				cancelAnimationFrame(frame);
-				resolveCommittedNavigations(renderId);
+				settleNavigationCommits(renderId, false);
 			};
 		}, [renderId]);
 		return children;
 	}
-	function dispatchApprovedVisibleCommit(commit, pendingRouterState, visibleCommitMode) {
+	function dispatchApprovedVisibleCommit(renderId, commit, pendingRouterState, visibleCommitMode) {
 		const setter = getBrowserRouterStateSetter();
+		const pendingCommit = pendingNavigationCommits.get(renderId);
+		const captureCandidateState = (state) => {
+			if (pendingCommit) pendingCommit.committedState = state;
+			return state;
+		};
 		if (pendingRouterState) {
-			resolvePendingBrowserRouterState(pendingRouterState, commit);
+			if (pendingRouterState.settled) return;
+			const committedState = captureCandidateState(applyApprovedVisibleCommit(getBrowserRouterState(), commit));
+			pendingRouterState.settled = true;
+			pendingRouterState.resolve(committedState);
+			if (activePendingBrowserRouterState === pendingRouterState) activePendingBrowserRouterState = null;
 			return;
 		}
 		if (visibleCommitMode === "synchronous") {
 			flushSync(() => {
-				setter(applyApprovedVisibleCommit(getBrowserRouterState(), commit));
+				setter(captureCandidateState(applyApprovedVisibleCommit(getBrowserRouterState(), commit)));
 			});
 			return;
 		}
 		startTransition(() => {
-			setter(applyApprovedVisibleCommit(getBrowserRouterState(), commit));
+			setter(captureCandidateState(applyApprovedVisibleCommit(getBrowserRouterState(), commit)));
 		});
 	}
 	function dispatchSynchronousVisibleCommit(commit) {
@@ -280,6 +301,7 @@ function createAppBrowserNavigationController(deps = {}) {
 			previousNextUrl: options.restoredState.previousNextUrl,
 			rootLayoutTreePath: options.restoredState.rootLayoutTreePath,
 			routeId: options.restoredState.routeId,
+			restoredHistorySnapshot: true,
 			skippedLayoutIds: []
 		};
 	}
@@ -309,18 +331,25 @@ function createAppBrowserNavigationController(deps = {}) {
 		lifecycleOptions?.onDiscardedRevalidation?.();
 	}
 	async function renderNavigationPayload(options) {
+		if (options.navId === pendingUserNavigationId) pendingUserNavigationLane = options.operationLane;
 		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);
+			pendingNavigationCommits.set(renderId, {
+				committedState: null,
+				onCommittedState: options.onCommittedState,
+				resolve
+			});
 		});
 		let snapshotActivated = false;
 		try {
 			const pending = await createPendingNavigationCommit({
 				currentState: getBrowserRouterState(),
+				navigationCommitKind: options.navigationCommitKind,
+				navigationId: options.navId,
 				nextElements: options.nextElements,
 				navigationSnapshot: options.navigationSnapshot,
 				operationLane: options.operationLane,
@@ -344,7 +373,7 @@ function createAppBrowserNavigationController(deps = {}) {
 				pendingNavigationFailureTargets.delete(renderId);
 				if (failureTarget) clearAppNavigationFailureTarget(failureTarget);
 				pendingNavigationCommits.delete(renderId);
-				resolveCommitted?.();
+				resolveCommitted?.(false);
 				consumeAppRouterScrollIntent(options.scrollIntent ?? null);
 				return "no-commit";
 			}
@@ -371,17 +400,17 @@ function createAppBrowserNavigationController(deps = {}) {
 			claimAppRouterScrollIntentForCommit(options.scrollIntent, renderId);
 			activateNavigationSnapshot();
 			snapshotActivated = true;
-			dispatchApprovedVisibleCommit(approvedCommit, options.pendingRouterState, options.visibleCommitMode ?? "transition");
+			dispatchApprovedVisibleCommit(renderId, 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?.();
+			resolveCommitted?.(false);
 			throw error;
 		}
-		return committed.then(() => "committed");
+		return committed.then((didCommit) => didCommit ? "committed" : "no-commit");
 	}
 	async function commitSameUrlNavigatePayload(nextElements, navigationSnapshot, returnValue, actionInitiationState, lifecycleOptions) {
 		const currentState = actionInitiationState ?? getBrowserRouterState();
@@ -395,7 +424,7 @@ function createAppBrowserNavigationController(deps = {}) {
 			navigationSnapshot,
 			nextElements,
 			renderId: allocateRenderId(),
-			operationLane: "server-action",
+			operationLane: resolveServerActionOperationLane(lifecycleOptions?.revalidation ?? "none"),
 			payloadOrigin: FRESH_APP_NAVIGATION_PAYLOAD_ORIGIN,
 			startedNavigationId,
 			routeManifest: getRouteManifest(),

package/dist/server/app-browser-server-action-client.d.ts

@@ -23,7 +23,7 @@ type ClientServerActionDeps = {
   commitSameUrlNavigatePayload(elements: Promise<AppElements>, actionInitiation: ClientServerActionInitiation, returnValue: ServerActionResult["returnValue"] | undefined, revalidation: ServerActionRevalidationKind): Promise<unknown>;
   navigationPlanner: typeof navigationPlanner;
   performHardNavigation(url: string, historyMode?: "assign" | "replace"): void;
-  renderRedirectPayload(elements: AppElements, target: ActionRedirectTarget, actionInitiation: ClientServerActionInitiation): void;
+  renderRedirectPayload(elements: AppElements, target: ActionRedirectTarget, actionInitiation: ClientServerActionInitiation, revalidation: ServerActionRevalidationKind): void;
   syncCurrentHistoryState(previousNextUrl: string | null, bfcacheIds: Readonly<Record<string, string>>): void;
   syncServerActionHttpFallbackHead(status: number | null): void;
 };

package/dist/server/app-browser-server-action-client.js

@@ -3,7 +3,7 @@ import { DANGEROUS_URL_BLOCK_MESSAGE, isDangerousScheme } from "../shims/url-saf
 import { AppElementsWire } from "./app-elements-wire.js";
 import "./app-elements.js";
 import { VINEXT_RSC_COMPATIBILITY_ID_HEADER, createServerActionRequestUrl } from "./app-rsc-cache-busting.js";
-import { createServerActionResultFacts, isServerActionResult, normalizeServerActionThrownValue, parseServerActionRevalidationHeader, readInvalidServerActionResponseError, shouldClearClientNavigationCachesForServerActionResult } from "./app-browser-action-result.js";
+import { createServerActionResultFacts, isServerActionResult, normalizeServerActionThrownValue, parseServerActionRevalidationHeader, readInvalidServerActionResponseError, shouldClearClientNavigationCachesForServerActionResult, shouldSyncServerActionHttpFallbackHead } from "./app-browser-action-result.js";
 import { resolveServerActionRequestState } from "./app-browser-state.js";
 import { applyServerActionResultDecision } from "./app-browser-server-action-navigation.js";
 import { throwOnServerActionNotFound } from "./server-action-not-found.js";
@@ -100,14 +100,13 @@ async function invokeClientServerAction(id, args, actionInitiation, deps) {
 	if (revalidation === "none" && shouldClearClientNavigationCachesForServerActionResult(result, revalidation)) deps.clearClientNavigationCaches();
 	if (actionRedirectTarget) {
 		if (isServerActionResult(result) && result.root !== void 0) {
-			deps.renderRedirectPayload(AppElementsWire.decode(result.root), actionRedirectTarget, actionInitiation);
+			deps.renderRedirectPayload(AppElementsWire.decode(result.root), actionRedirectTarget, actionInitiation, revalidation);
 			throw new ServerActionRedirectError(actionRedirectTarget);
 		}
 		deps.performHardNavigation(actionRedirectTarget.href);
 		return;
 	}
-	const hasSameUrlRerenderPayload = isServerActionResult(result) && result.root !== void 0;
-	deps.syncServerActionHttpFallbackHead(hasSameUrlRerenderPayload ? null : fetchResponse.status);
+	deps.syncServerActionHttpFallbackHead(shouldSyncServerActionHttpFallbackHead(result) ? fetchResponse.status : null);
 	if (isServerActionResult(result)) {
 		if (result.root !== void 0) {
 			const returnValue = result.returnValue && !result.returnValue.ok ? {

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

@@ -11,6 +11,8 @@ import { ClientNavigationRenderSnapshot } from "../shims/navigation.js";
 type OperationRecordBase = {
   id: number;
   lane: OperationLane;
+  navigationCommitKind?: "authoritative" | "detached";
+  navigationId?: number;
   startedVisibleCommitVersion: number;
 };
 type PendingOperationRecord = OperationRecordBase & {
@@ -64,18 +66,23 @@ type PendingNavigationCommit = {
   previousNextUrl: string | null;
   rootLayoutTreePath: string | null;
   routeId: string;
+  restoredHistorySnapshot?: boolean;
   skippedLayoutIds: readonly string[];
 };
 type AppNavigationPayloadOrigin = Readonly<{
+  origin: "committed-cache";
+} | {
   origin: "fresh";
 } | {
   origin: "visited-cache";
 }>;
+declare const COMMITTED_CACHE_APP_NAVIGATION_PAYLOAD_ORIGIN: AppNavigationPayloadOrigin;
 declare const FRESH_APP_NAVIGATION_PAYLOAD_ORIGIN: AppNavigationPayloadOrigin;
 declare const VISITED_CACHE_APP_NAVIGATION_PAYLOAD_ORIGIN: AppNavigationPayloadOrigin;
 type PendingNavigationCommitDisposition = "dispatch" | "hard-navigate" | "skip";
 type CacheRestorableAppPayloadMetadata = Readonly<{
   cacheEntryReuseProof?: CacheEntryReuseProof;
+  dynamicStaleTimeSeconds?: number;
   skippedLayoutIds: readonly string[];
 }>;
 type DispatchPendingNavigationCommitDispositionDecision = {
@@ -91,6 +98,7 @@ type NonDispatchPendingNavigationCommitDispositionDecision = {
   trace: NavigationTrace;
 };
 type PendingNavigationCommitDispositionDecision = DispatchPendingNavigationCommitDispositionDecision | NonDispatchPendingNavigationCommitDispositionDecision;
+declare function isCompleteAppPayloadMetadata(metadata: CacheRestorableAppPayloadMetadata): boolean;
 declare function isCacheRestorableAppPayloadMetadata(metadata: CacheRestorableAppPayloadMetadata): metadata is CacheRestorableAppPayloadMetadata & {
   cacheEntryReuseProof: CacheEntryReuseProof;
 };
@@ -126,6 +134,8 @@ declare function resolvePendingNavigationCommitDispositionDecision(options: {
 }): PendingNavigationCommitDispositionDecision;
 declare function createPendingNavigationCommit(options: {
   currentState: AppRouterState;
+  navigationCommitKind?: "authoritative" | "detached";
+  navigationId?: number;
   nextElements: Promise<AppElements>;
   navigationSnapshot: ClientNavigationRenderSnapshot;
   operationLane: OperationLane;
@@ -137,4 +147,4 @@ declare function createPendingNavigationCommit(options: {
   type: "navigate" | "replace" | "traverse";
 }): Promise<PendingNavigationCommit>;
 //#endregion
-export { AppNavigationPayloadOrigin, AppRouterAction, AppRouterState, type BfcacheIdMap, CommittedOperationRecord, FRESH_APP_NAVIGATION_PAYLOAD_ORIGIN, type HistoryTraversalIntent, type OperationLane, PendingNavigationCommit, PendingOperationRecord, VISITED_CACHE_APP_NAVIGATION_PAYLOAD_ORIGIN, createBfcacheSegmentStateKeyMap, createHistoryStateWithNavigationMetadata, createHistoryStateWithPreviousNextUrl, createInitialBfcacheIdMap, createNextBfcacheIdMap, createPendingNavigationCommit, isCacheRestorableAppPayloadMetadata, isHistoryStateBfcacheVersionCurrent, preserveBfcacheIdsForMergedElements, readHistoryStateBfcacheIds, readHistoryStateBfcacheVersion, readHistoryStatePreviousNextUrl, readHistoryStateTraversalIndex, resolveHistoryTraversalIntent, resolveInterceptionContextFromPreviousNextUrl, resolvePendingNavigationCommitDispositionDecision, resolveServerActionRequestState };
+export { AppNavigationPayloadOrigin, AppRouterAction, AppRouterState, type BfcacheIdMap, COMMITTED_CACHE_APP_NAVIGATION_PAYLOAD_ORIGIN, CommittedOperationRecord, FRESH_APP_NAVIGATION_PAYLOAD_ORIGIN, type HistoryTraversalIntent, type OperationLane, PendingNavigationCommit, PendingOperationRecord, VISITED_CACHE_APP_NAVIGATION_PAYLOAD_ORIGIN, createBfcacheSegmentStateKeyMap, createHistoryStateWithNavigationMetadata, createHistoryStateWithPreviousNextUrl, createInitialBfcacheIdMap, createNextBfcacheIdMap, createPendingNavigationCommit, isCacheRestorableAppPayloadMetadata, isCompleteAppPayloadMetadata, isHistoryStateBfcacheVersionCurrent, preserveBfcacheIdsForMergedElements, readHistoryStateBfcacheIds, readHistoryStateBfcacheVersion, readHistoryStatePreviousNextUrl, readHistoryStateTraversalIndex, resolveHistoryTraversalIntent, resolveInterceptionContextFromPreviousNextUrl, resolvePendingNavigationCommitDispositionDecision, resolveServerActionRequestState };

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

@@ -6,28 +6,35 @@ import { AppElementsWire } from "./app-elements-wire.js";
 import { getMountedSlotIds, getMountedSlotIdsHeader } from "./app-elements.js";
 import { createRscRequestHeaders } from "./app-rsc-cache-busting.js";
 import { createCacheEntryReuseProof } from "./cache-proof.js";
+import { createBfcacheSegmentStateKeyMap, createInitialBfcacheIdMap, createNextBfcacheIdMap, preserveBfcacheIdsForMergedElements } from "./app-bfcache-identity.js";
 import { createHistoryStateWithNavigationMetadata, createHistoryStateWithPreviousNextUrl, isHistoryStateBfcacheVersionCurrent, readHistoryStateBfcacheIds, readHistoryStateBfcacheVersion, readHistoryStatePreviousNextUrl, readHistoryStateTraversalIndex, resolveHistoryTraversalIntent } from "./app-history-state.js";
 import { NavigationTraceReasonCodes, createNavigationLifecycleTraceFields, createNavigationTrace } from "./navigation-trace.js";
 import { verifyOperationTokenForCommit } from "./operation-token.js";
 import { navigationPlanner, resolveDefaultOrUnmatchedSlotPersistenceForLayouts } from "./navigation-planner.js";
 import { createSnapshotPathAndSearch } from "../shims/navigation.js";
-import { createBfcacheSegmentStateKeyMap, createInitialBfcacheIdMap, createNextBfcacheIdMap, preserveBfcacheIdsForMergedElements } from "./app-bfcache-identity.js";
 //#region src/server/app-browser-state.ts
+const COMMITTED_CACHE_APP_NAVIGATION_PAYLOAD_ORIGIN = { origin: "committed-cache" };
 const FRESH_APP_NAVIGATION_PAYLOAD_ORIGIN = { origin: "fresh" };
 const VISITED_CACHE_APP_NAVIGATION_PAYLOAD_ORIGIN = { origin: "visited-cache" };
 function createOperationRecord(options) {
 	return {
 		id: options.id,
 		lane: options.lane,
+		...options.navigationCommitKind !== void 0 ? { navigationCommitKind: options.navigationCommitKind } : {},
+		...options.navigationId !== void 0 ? { navigationId: options.navigationId } : {},
 		startedVisibleCommitVersion: options.startedVisibleCommitVersion,
 		state: "pending"
 	};
 }
+function isCompleteAppPayloadMetadata(metadata) {
+	return metadata.skippedLayoutIds.length === 0;
+}
 function isCacheRestorableAppPayloadMetadata(metadata) {
-	return metadata.cacheEntryReuseProof !== void 0 && metadata.skippedLayoutIds.length === 0;
+	return metadata.cacheEntryReuseProof !== void 0 && isCompleteAppPayloadMetadata(metadata);
 }
 function requiresCacheEntryReuseProof(origin) {
 	switch (origin.origin) {
+		case "committed-cache":
 		case "fresh": return false;
 		case "visited-cache": return true;
 		default: throw new Error("[vinext] Unknown App Router payload origin: " + String(origin));
@@ -70,14 +77,21 @@ function resolveServerActionRequestState(options) {
 function resolvePendingNavigationCommitDispositionDecision(options) {
 	const traceFields = createPendingNavigationTraceFields(options);
 	const targetSnapshot = createPendingRouteSnapshot(options.pending);
-	const verdict = verifyOperationTokenForCommit(createPendingNavigationOperationToken({
+	const token = createPendingNavigationOperationToken({
 		pending: options.pending,
 		routeManifest: options.routeManifest ?? null,
 		startedNavigationId: options.startedNavigationId,
 		targetSnapshot
-	}), {
+	});
+	if (options.pending.action.operation.navigationCommitKind === "detached" && options.currentState.activeOperation?.navigationId === options.startedNavigationId && options.currentState.activeOperation.navigationCommitKind === "authoritative") return {
+		disposition: "skip",
+		preserveElementIds: [],
+		trace: createNavigationTrace(NavigationTraceReasonCodes.staleOperation, traceFields)
+	};
+	const visibleCommitVersion = options.currentState.activeOperation?.navigationId === options.startedNavigationId && options.currentState.activeOperation.navigationCommitKind === "detached" && options.pending.action.operation.navigationCommitKind === "authoritative" ? options.pending.action.operation.startedVisibleCommitVersion : options.currentState.visibleCommitVersion;
+	const verdict = verifyOperationTokenForCommit(token, {
 		activeNavigationId: options.activeNavigationId,
-		visibleCommitVersion: options.currentState.visibleCommitVersion
+		visibleCommitVersion
 	});
 	if (!verdict.authorized) return {
 		disposition: "skip",
@@ -126,7 +140,7 @@ function createMountedParallelSlotSnapshots(elements) {
 }
 function createVisibleRouteSnapshot(state) {
 	const displayUrl = createSnapshotPathAndSearch(state.navigationSnapshot);
-	const matchedUrl = normalizeNavigationSnapshotMatchedUrl(state.navigationSnapshot.pathname);
+	const matchedUrl = state.interception?.targetMatchedUrl ?? normalizeNavigationSnapshotMatchedUrl(state.navigationSnapshot.pathname);
 	return {
 		displayUrl,
 		interception: state.interception,
@@ -144,7 +158,7 @@ function createVisibleRouteSnapshot(state) {
 }
 function createPendingRouteSnapshot(pending) {
 	const displayUrl = createSnapshotPathAndSearch(pending.action.navigationSnapshot);
-	const matchedUrl = normalizeNavigationSnapshotMatchedUrl(pending.action.navigationSnapshot.pathname);
+	const matchedUrl = pending.action.interception?.targetMatchedUrl ?? normalizeNavigationSnapshotMatchedUrl(pending.action.navigationSnapshot.pathname);
 	return {
 		displayUrl,
 		interception: pending.action.interception,
@@ -188,6 +202,7 @@ function planPendingRootBoundaryFlightResponse(options) {
 			kind: "flightResponseArrived",
 			result: {
 				...cacheEntryReuseProof ? { cacheEntryReuseProof } : {},
+				...options.pending.restoredHistorySnapshot ? { restoredHistorySnapshot: true } : {},
 				href: options.targetHref ?? options.targetSnapshot.displayUrl,
 				targetSnapshot: options.targetSnapshot
 			},
@@ -292,6 +307,8 @@ async function createPendingNavigationCommit(options) {
 			operation: createOperationRecord({
 				id: options.renderId,
 				lane: options.operationLane,
+				navigationCommitKind: options.navigationCommitKind,
+				navigationId: options.navigationId,
 				startedVisibleCommitVersion: options.currentState.visibleCommitVersion
 			}),
 			previousNextUrl,
@@ -312,4 +329,4 @@ async function createPendingNavigationCommit(options) {
 	};
 }
 //#endregion
-export { FRESH_APP_NAVIGATION_PAYLOAD_ORIGIN, VISITED_CACHE_APP_NAVIGATION_PAYLOAD_ORIGIN, createBfcacheSegmentStateKeyMap, createHistoryStateWithNavigationMetadata, createHistoryStateWithPreviousNextUrl, createInitialBfcacheIdMap, createNextBfcacheIdMap, createPendingNavigationCommit, isCacheRestorableAppPayloadMetadata, isHistoryStateBfcacheVersionCurrent, preserveBfcacheIdsForMergedElements, readHistoryStateBfcacheIds, readHistoryStateBfcacheVersion, readHistoryStatePreviousNextUrl, readHistoryStateTraversalIndex, resolveHistoryTraversalIntent, resolveInterceptionContextFromPreviousNextUrl, resolvePendingNavigationCommitDispositionDecision, resolveServerActionRequestState };
+export { COMMITTED_CACHE_APP_NAVIGATION_PAYLOAD_ORIGIN, FRESH_APP_NAVIGATION_PAYLOAD_ORIGIN, VISITED_CACHE_APP_NAVIGATION_PAYLOAD_ORIGIN, createBfcacheSegmentStateKeyMap, createHistoryStateWithNavigationMetadata, createHistoryStateWithPreviousNextUrl, createInitialBfcacheIdMap, createNextBfcacheIdMap, createPendingNavigationCommit, isCacheRestorableAppPayloadMetadata, isCompleteAppPayloadMetadata, isHistoryStateBfcacheVersionCurrent, preserveBfcacheIdsForMergedElements, readHistoryStateBfcacheIds, readHistoryStateBfcacheVersion, readHistoryStatePreviousNextUrl, readHistoryStateTraversalIndex, resolveHistoryTraversalIntent, resolveInterceptionContextFromPreviousNextUrl, resolvePendingNavigationCommitDispositionDecision, resolveServerActionRequestState };

package/dist/server/app-browser-visible-commit.d.ts

@@ -49,7 +49,12 @@ type ClassifiedPendingNavigationCommit = {
   trace: NavigationTrace;
 };
 declare function applyApprovedVisibleCommit(state: AppRouterState, commit: ApprovedVisibleCommit): AppRouterState;
-declare function approveHmrVisibleCommit(pending: PendingNavigationCommit): ApprovedVisibleCommit;
+declare function approveHmrVisibleCommit(options: {
+  currentState: AppRouterState;
+  pending: PendingNavigationCommit;
+  routeManifest?: RouteManifest | null;
+  targetHref: string;
+}): CommitApproval;
 declare function approvePendingNavigationCommit(options: {
   activeNavigationId: number;
   currentState: AppRouterState;

package/dist/server/app-browser-visible-commit.js

@@ -1,8 +1,8 @@
 import { normalizeAppElementsSlotBindings } from "./app-elements-wire.js";
 import "./app-elements.js";
 import { mergeElements } from "../shims/slot.js";
-import { NavigationTraceReasonCodes, NavigationTraceTransactionCodes, createNavigationTrace, prependNavigationTraceEntry } from "./navigation-trace.js";
 import { preserveBfcacheIdsForMergedElements } from "./app-bfcache-identity.js";
+import { NavigationTraceReasonCodes, NavigationTraceTransactionCodes, createNavigationTrace, prependNavigationTraceEntry } from "./navigation-trace.js";
 import { createPendingNavigationCommit, resolvePendingNavigationCommitDispositionDecision } from "./app-browser-state.js";
 //#region src/server/app-browser-visible-commit.ts
 const approvedVisibleCommitBrand = Symbol("ApprovedVisibleCommit");
@@ -17,6 +17,8 @@ function commitOperationRecord(operation, visibleCommitVersion) {
 	return {
 		id: operation.id,
 		lane: operation.lane,
+		...operation.navigationCommitKind !== void 0 ? { navigationCommitKind: operation.navigationCommitKind } : {},
+		...operation.navigationId !== void 0 ? { navigationId: operation.navigationId } : {},
 		startedVisibleCommitVersion: operation.startedVisibleCommitVersion,
 		state: "committed",
 		visibleCommitVersion
@@ -56,9 +58,23 @@ function reduceApprovedVisibleCommitState(state, commit) {
 	const { action } = commit;
 	switch (action.type) {
 		case "traverse":
-		case "navigate": {
-			const preserveElementIds = action.reuseCurrentBfcacheIds ? commit.decision.preserveElementIds : [];
-			const preservePreviousSlotIds = action.reuseCurrentBfcacheIds ? commit.decision.preservePreviousSlotIds : [];
+		case "navigate":
+		case "replace": {
+			const bfcacheCompatiblePreserveElementIds = action.reuseCurrentBfcacheIds && action.operation.lane !== "refresh" ? commit.decision.preserveElementIds.filter((id) => {
+				const previousBfcacheId = state.bfcacheIds[id];
+				return previousBfcacheId !== void 0 && action.bfcacheIds[id] === previousBfcacheId;
+			}) : [];
+			const preservedSlotOwnerElementIdSet = new Set(bfcacheCompatiblePreserveElementIds);
+			const preservePreviousSlotIds = action.reuseCurrentBfcacheIds ? commit.decision.preservePreviousSlotIds.filter((slotId) => {
+				const targetBinding = action.slotBindings.find((binding) => binding.slotId === slotId);
+				return targetBinding?.ownerLayoutId !== null && targetBinding?.ownerLayoutId !== void 0 && preservedSlotOwnerElementIdSet.has(targetBinding.ownerLayoutId);
+			}) : [];
+			const hmrPreservedSlotOwnerLayoutIds = action.operation.lane === "hmr" ? bfcacheCompatiblePreserveElementIds.filter((id) => preservePreviousSlotIds.some((slotId) => {
+				return action.slotBindings.find((binding) => binding.slotId === slotId)?.ownerLayoutId === id;
+			})) : [];
+			const hmrPreserveElementIds = action.operation.lane === "hmr" && state.routeId === action.routeId && Object.hasOwn(state.elements, state.routeId) ? [state.routeId, ...hmrPreservedSlotOwnerLayoutIds] : hmrPreservedSlotOwnerLayoutIds;
+			const hmrUniquePreserveElementIds = hmrPreserveElementIds.length > 1 ? [...new Set(hmrPreserveElementIds)] : hmrPreserveElementIds;
+			const preserveElementIds = action.operation.lane === "hmr" ? hmrUniquePreserveElementIds : bfcacheCompatiblePreserveElementIds;
 			const mergedElements = mergeElements(state.elements, action.elements, {
 				clearAbsentSlots: action.type === "traverse" || !action.reuseCurrentBfcacheIds,
 				preserveAbsentSlots: action.reuseCurrentBfcacheIds && commit.decision.preserveAbsentSlots,
@@ -84,20 +100,6 @@ function reduceApprovedVisibleCommitState(state, commit) {
 				slotBindings: mergeSlotBindings(state.slotBindings, action.slotBindings, action.layoutIds, preservePreviousSlotIds)
 			}, action.operation);
 		}
-		case "replace": return commitVisibleRouterState(state, {
-			bfcacheIds: action.bfcacheIds,
-			elements: action.elements,
-			interception: action.interception,
-			interceptionContext: action.interceptionContext,
-			layoutFlags: action.layoutFlags,
-			layoutIds: action.layoutIds,
-			navigationSnapshot: action.navigationSnapshot,
-			previousNextUrl: action.previousNextUrl,
-			renderId: action.renderId,
-			rootLayoutTreePath: action.rootLayoutTreePath,
-			routeId: action.routeId,
-			slotBindings: action.slotBindings
-		}, action.operation);
 		default: {
 			const _exhaustive = action.type;
 			throw new Error("[vinext] Unknown router action: " + String(_exhaustive));
@@ -176,14 +178,28 @@ function addCommitTransactionTrace(decision, pending) {
 		default: throw new Error("[vinext] Unknown commit decision: " + String(decision));
 	}
 }
-function approveHmrVisibleCommit(pending) {
+function approveHmrVisibleCommit(options) {
+	const { currentState, pending } = options;
 	if (pending.action.operation.lane !== "hmr") throw new Error("[vinext] HMR visible commit approval requires an HMR pending operation");
-	const decision = addCommitTransactionTrace(createVisibleCommitDecision(), pending);
-	if (decision.disposition !== "commit") throw new Error("[vinext] HMR visible commit approval did not produce a commit decision");
-	return createApprovedVisibleCommit({
-		decision,
-		pending
-	});
+	const tracedDecision = addCommitTransactionTrace(resolvePendingNavigationCommitDecision({
+		activeNavigationId: pending.action.operation.id,
+		currentState,
+		pending,
+		routeManifest: options.routeManifest,
+		startedNavigationId: pending.action.operation.id,
+		targetHref: options.targetHref
+	}), pending);
+	if (tracedDecision.disposition === "commit") return {
+		approvedCommit: createApprovedVisibleCommit({
+			decision: tracedDecision,
+			pending
+		}),
+		decision: tracedDecision
+	};
+	return {
+		approvedCommit: null,
+		decision: tracedDecision
+	};
 }
 function approvePendingNavigationCommit(options) {
 	const decision = addCommitTransactionTrace(resolvePendingNavigationCommitDecision({
@@ -213,6 +229,8 @@ function approvePendingNavigationCommit(options) {
 async function resolveAndClassifyNavigationCommit(options) {
 	const pending = await createPendingNavigationCommit({
 		currentState: options.currentState,
+		navigationCommitKind: void 0,
+		navigationId: options.startedNavigationId,
 		nextElements: options.nextElements,
 		navigationSnapshot: options.navigationSnapshot,
 		operationLane: options.operationLane,

package/dist/server/app-elements-wire.d.ts

@@ -6,6 +6,7 @@ import { ReactNode } from "react";
 //#region src/server/app-elements-wire.d.ts
 declare const APP_ARTIFACT_COMPATIBILITY_KEY = "__artifactCompatibility";
 declare const APP_CACHE_ENTRY_REUSE_PROOF_KEY = "__cacheEntryReuseProof";
+declare const APP_DYNAMIC_STALE_TIME_KEY = "__dynamicStaleTime";
 declare const APP_INTERCEPTION_KEY = "__interception";
 declare const APP_INTERCEPTION_CONTEXT_KEY = "__interceptionContext";
 declare const APP_LAYOUT_IDS_KEY = "__layoutIds";
@@ -70,6 +71,7 @@ type LayoutFlags = Readonly<Record<string, "s" | "d">>;
 type AppElementsMetadata = {
   artifactCompatibility: ArtifactCompatibilityEnvelope;
   cacheEntryReuseProof?: CacheEntryReuseProof;
+  dynamicStaleTimeSeconds?: number;
   interception: AppElementsInterception | null;
   interceptionContext: string | null;
   layoutIds: readonly string[];
@@ -100,6 +102,7 @@ type AppElementsWireElementKey = {
   treePath: string;
 };
 type AppElementsWireMetadataInput = {
+  dynamicStaleTimeSeconds?: number;
   interception?: AppElementsInterception | null;
   interceptionContext: string | null;
   layoutIds?: readonly string[];
@@ -109,6 +112,7 @@ type AppElementsWireMetadataInput = {
   sourcePage?: string | null;
 };
 type AppElementsWireMetadataEntries = Readonly<{
+  [APP_DYNAMIC_STALE_TIME_KEY]?: number;
   [APP_ROUTE_KEY]: string;
   [APP_INTERCEPTION_KEY]?: AppElementsInterception;
   [APP_INTERCEPTION_CONTEXT_KEY]: string | null;
@@ -123,10 +127,11 @@ type AppElementsWireMetadataEntries = Readonly<{
  * known keys (e.g. __layoutFlags). Distinct from AppElements / AppWireElements
  * which only carry render-time values.
  */
-type AppOutgoingElements = Readonly<Record<string, ReactNode | LayoutFlags | ArtifactCompatibilityEnvelope | CacheEntryReuseProof | AppElementsInterception | RenderObservation | readonly string[] | readonly AppElementsSlotBinding[]>>;
+type AppOutgoingElements = Readonly<Record<string, ReactNode | LayoutFlags | ArtifactCompatibilityEnvelope | CacheEntryReuseProof | AppElementsInterception | RenderObservation | number | readonly string[] | readonly AppElementsSlotBinding[]>>;
 type AppElementsWireKeys = {
   readonly artifactCompatibility: typeof APP_ARTIFACT_COMPATIBILITY_KEY;
   readonly cacheEntryReuseProof: typeof APP_CACHE_ENTRY_REUSE_PROOF_KEY;
+  readonly dynamicStaleTime: typeof APP_DYNAMIC_STALE_TIME_KEY;
   readonly interception: typeof APP_INTERCEPTION_KEY;
   readonly interceptionContext: typeof APP_INTERCEPTION_CONTEXT_KEY;
   readonly layoutIds: typeof APP_LAYOUT_IDS_KEY;
@@ -149,6 +154,7 @@ type AppElementsWireCodec = {
     element: ReactNode | AppElements;
     artifactCompatibility?: ArtifactCompatibilityEnvelope;
     cacheEntryReuseProof?: CacheEntryReuseProof;
+    dynamicStaleTimeSeconds?: number;
     layoutFlags: LayoutFlags;
     renderObservation?: RenderObservation;
     skipDisposition?: ClientReuseManifestSkipDisposition;
@@ -182,6 +188,7 @@ declare function buildOutgoingAppPayload(input: {
   element: ReactNode | AppElements;
   artifactCompatibility?: ArtifactCompatibilityEnvelope;
   cacheEntryReuseProof?: CacheEntryReuseProof;
+  dynamicStaleTimeSeconds?: number;
   layoutFlags: LayoutFlags;
   renderObservation?: RenderObservation;
   skipDisposition?: ClientReuseManifestSkipDisposition;
@@ -189,4 +196,4 @@ declare function buildOutgoingAppPayload(input: {
 declare function readAppElementsMetadata(elements: Readonly<Record<string, unknown>>): AppElementsMetadata;
 declare const AppElementsWire: AppElementsWireCodec;
 //#endregion
-export { APP_ARTIFACT_COMPATIBILITY_KEY, APP_CACHE_ENTRY_REUSE_PROOF_KEY, APP_INTERCEPTION_CONTEXT_KEY, APP_INTERCEPTION_KEY, APP_LAYOUT_FLAGS_KEY, APP_LAYOUT_IDS_KEY, APP_RENDER_OBSERVATION_KEY, APP_ROOT_LAYOUT_KEY, APP_ROUTE_KEY, APP_SKIPPED_LAYOUT_IDS_KEY, APP_SLOT_BINDINGS_KEY, APP_SOURCE_PAGE_KEY, APP_STATIC_SIBLINGS_KEY, APP_UNMATCHED_SLOT_WIRE_VALUE, AppElementValue, AppElements, AppElementsInterception, AppElementsSlotBinding, AppElementsWire, AppOutgoingElements, AppWireElements, LayoutFlags, UNMATCHED_SLOT, buildOutgoingAppPayload, compareAppElementsSlotIds, isAppElementsRecord, normalizeAppElements, normalizeAppElementsSlotBindings, readAppElementsMetadata, withLayoutFlags };
+export { APP_ARTIFACT_COMPATIBILITY_KEY, APP_CACHE_ENTRY_REUSE_PROOF_KEY, APP_DYNAMIC_STALE_TIME_KEY, APP_INTERCEPTION_CONTEXT_KEY, APP_INTERCEPTION_KEY, APP_LAYOUT_FLAGS_KEY, APP_LAYOUT_IDS_KEY, APP_RENDER_OBSERVATION_KEY, APP_ROOT_LAYOUT_KEY, APP_ROUTE_KEY, APP_SKIPPED_LAYOUT_IDS_KEY, APP_SLOT_BINDINGS_KEY, APP_SOURCE_PAGE_KEY, APP_STATIC_SIBLINGS_KEY, APP_UNMATCHED_SLOT_WIRE_VALUE, AppElementValue, AppElements, AppElementsInterception, AppElementsSlotBinding, AppElementsWire, AppOutgoingElements, AppWireElements, LayoutFlags, UNMATCHED_SLOT, buildOutgoingAppPayload, compareAppElementsSlotIds, isAppElementsRecord, normalizeAppElements, normalizeAppElementsSlotBindings, readAppElementsMetadata, withLayoutFlags };