vinext 0.1.1 → 0.1.3

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

@@ -1,6 +1,13 @@
 //#region src/server/app-browser-error.d.ts
-declare function createOnUncaughtError(getRecoveryHref: () => string | null): (error: unknown, errorInfo: {
+type VinextHydrateRootErrorInfo = {
   componentStack?: string;
-}) => void;
+  errorBoundary?: unknown;
+};
+type HydrateRootErrorHandler = (error: unknown, errorInfo: VinextHydrateRootErrorInfo) => void;
+declare function createOnUncaughtError(): HydrateRootErrorHandler;
+declare function createProdOnCaughtError(onImplicitRootError: HydrateRootErrorHandler): HydrateRootErrorHandler;
+declare function createDevOnCaughtError(onCaughtError: HydrateRootErrorHandler, onImplicitRootError: HydrateRootErrorHandler): HydrateRootErrorHandler;
+declare function prodOnCaughtError(error: unknown, errorInfo: VinextHydrateRootErrorInfo): void;
+declare function prodOnRecoverableError(error: unknown): void;
 //#endregion
-export { createOnUncaughtError };
+export { createDevOnCaughtError, createOnUncaughtError, createProdOnCaughtError, prodOnCaughtError, prodOnRecoverableError };

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

@@ -1,11 +1,52 @@
+import { isUnknownRecord } from "../utils/record.js";
+import { isNavigationSignalError } from "../utils/navigation-signal.js";
 //#region src/server/app-browser-error.ts
-function createOnUncaughtError(getRecoveryHref) {
+function isImplicitRootErrorBoundary(errorInfo) {
+	if (!isUnknownRecord(errorInfo.errorBoundary)) return false;
+	const props = errorInfo.errorBoundary.props;
+	return isUnknownRecord(props) && props.isImplicitRootErrorBoundary === true;
+}
+function logCaughtError(error, errorInfo) {
+	console.error(error);
+	if (errorInfo?.componentStack) console.error("The above error occurred in a React component:\n" + errorInfo.componentStack);
+}
+function reportGlobalError(error) {
+	if (typeof globalThis.reportError === "function") {
+		globalThis.reportError(error);
+		return;
+	}
+	console.error(error);
+}
+function createOnUncaughtError() {
+	return (error) => {
+		reportGlobalError(error);
+	};
+}
+function createProdOnCaughtError(onImplicitRootError) {
 	return (error, errorInfo) => {
-		console.error(error);
-		if (errorInfo?.componentStack) console.error("The above error occurred in a React component:\n" + errorInfo.componentStack);
-		const recoveryHref = getRecoveryHref();
-		if (recoveryHref !== null) window.location.assign(recoveryHref);
+		if (isNavigationSignalError(error)) return;
+		if (isImplicitRootErrorBoundary(errorInfo)) {
+			onImplicitRootError(error, errorInfo);
+			return;
+		}
+		logCaughtError(error, errorInfo);
 	};
 }
+function createDevOnCaughtError(onCaughtError, onImplicitRootError) {
+	return (error, errorInfo) => {
+		if (isImplicitRootErrorBoundary(errorInfo)) {
+			onImplicitRootError(error, errorInfo);
+			return;
+		}
+		onCaughtError(error, errorInfo);
+	};
+}
+function prodOnCaughtError(error, errorInfo) {
+	if (isNavigationSignalError(error)) return;
+	logCaughtError(error, errorInfo);
+}
+function prodOnRecoverableError(error) {
+	reportGlobalError(error instanceof Error && error.cause !== void 0 ? error.cause : error);
+}
 //#endregion
-export { createOnUncaughtError };
+export { createDevOnCaughtError, createOnUncaughtError, createProdOnCaughtError, prodOnCaughtError, prodOnRecoverableError };

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-hydration.d.ts

@@ -8,6 +8,7 @@ type HydrateRootChildren = Parameters<HydrateRoot>[1];
 type HydrateRootReturn = ReturnType<HydrateRoot>;
 type HydrateRootCaughtErrorHandler = NonNullable<HydrateRootOptions["onCaughtError"]>;
 type HydrateRootUncaughtErrorHandler = NonNullable<HydrateRootOptions["onUncaughtError"]>;
+type HydrateRootRecoverableErrorHandler = NonNullable<HydrateRootOptions["onRecoverableError"]>;
 type StartTransition = (action: () => void) => void;
 declare const RSC_FORM_STATE_GLOBAL = "__VINEXT_RSC_FORM_STATE__";
 type FormStateGlobal = {
@@ -17,6 +18,7 @@ declare function consumeInitialFormState(global: FormStateGlobal): ReactFormStat
 declare function createVinextHydrateRootOptions(options: {
   formState: ReactFormState | null;
   onCaughtError?: HydrateRootCaughtErrorHandler;
+  onRecoverableError?: HydrateRootRecoverableErrorHandler;
   onUncaughtError: HydrateRootUncaughtErrorHandler;
 }): HydrateRootOptions;
 declare function hydrateRootInTransition(options: {

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

@@ -8,6 +8,7 @@ function consumeInitialFormState(global) {
 function createVinextHydrateRootOptions(options) {
 	const hydrateOptions = {
 		formState: options.formState,
+		...options.onRecoverableError ? { onRecoverableError: options.onRecoverableError } : {},
 		onUncaughtError: options.onUncaughtError
 	};
 	if (options.onCaughtError) return {

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 { ServerActionRevalidationKind } from "./app-browser-action-result.js";
+import { NavigationRuntimeVisibleCommitMode } from "../client/navigation-runtime.js";
 import { AppElements } from "./app-elements-wire.js";
 import { OperationLane } from "./navigation-planner.js";
-import { ClientNavigationRenderSnapshot, commitClientNavigationState } from "../shims/navigation.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";
 
@@ -16,6 +17,7 @@ type PendingBrowserRouterState = {
 };
 type NavigationPayloadOutcome = "committed" | "no-commit" | "hard-navigate";
 type HardNavigationMode = "assign" | "replace";
+type BrowserNavigationCommitEffect = () => void;
 type BrowserNavigationCommitEffectFactory = (options: {
   bfcacheIds: Readonly<Record<string, string>>;
   href: string;
@@ -24,7 +26,7 @@ type BrowserNavigationCommitEffectFactory = (options: {
   params: Record<string, string | string[]>;
   previousNextUrl: string | null;
   targetHistoryIndex?: number | null;
-}) => () => void;
+}) => BrowserNavigationCommitEffect;
 type BrowserRouterStateRef = {
   current: AppRouterState;
 };
@@ -75,6 +77,7 @@ type BrowserNavigationController = {
     targetHistoryIndex?: number | null;
     targetHref: string;
     navId: number;
+    visibleCommitMode?: NavigationRuntimeVisibleCommitMode;
   }): Promise<NavigationPayloadOutcome>;
   commitSameUrlNavigatePayload(nextElements: Promise<AppElements>, navigationSnapshot: ClientNavigationRenderSnapshot, returnValue?: {
     ok: boolean;
@@ -90,6 +93,7 @@ type BrowserNavigationController = {
    * navigation would otherwise be lost.
    */
   drainPrePaintEffects(renderId: number): void;
+  clearCommittedNavigationFailureTargets(renderId: number): void;
   NavigationCommitSignal(this: void, {
     renderId,
     children
@@ -99,7 +103,6 @@ type BrowserNavigationController = {
   }): ReactNode;
 };
 declare function clearHardNavigationLoopGuard(): void;
-declare function createSnapshotPathAndSearch(snapshot: ClientNavigationRenderSnapshot): string;
 declare function createBasePathStrippedPathAndSearch(url: URL, basePath: string): string;
 declare function createAppBrowserNavigationController(deps?: BrowserNavigationControllerDeps): BrowserNavigationController;
 //#endregion

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

@@ -1,10 +1,12 @@
 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 } 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 { 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) {
@@ -50,10 +52,6 @@ function performHardNavigationWithLoopGuard(href, mode = "assign") {
 	else window.location.assign(href);
 	return true;
 }
-function createSnapshotPathAndSearch(snapshot) {
-	const query = snapshot.searchParams.toString();
-	return query === "" ? snapshot.pathname : `${snapshot.pathname}?${query}`;
-}
 function createBasePathStrippedPathAndSearch(url, basePath) {
 	const pathname = stripBasePath(url.pathname, basePath);
 	const query = new URLSearchParams(url.search).toString();
@@ -76,6 +74,7 @@ function createAppBrowserNavigationController(deps = {}) {
 	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;
@@ -194,6 +193,13 @@ function createAppBrowserNavigationController(deps = {}) {
 			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({
@@ -209,6 +215,9 @@ function createAppBrowserNavigationController(deps = {}) {
 		dispatchSynchronousVisibleCommit(approveHmrVisibleCommit(pending));
 	}
 	function NavigationCommitSignal({ renderId, children }) {
+		useInsertionEffect(() => {
+			clearCommittedNavigationFailureTargets(renderId);
+		}, [renderId]);
 		useLayoutEffect(() => {
 			drainPrePaintEffects(renderId);
 			const frame = requestAnimationFrame(() => {
@@ -221,12 +230,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));
 		});
@@ -295,6 +310,8 @@ function createAppBrowserNavigationController(deps = {}) {
 	}
 	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;
@@ -324,6 +341,8 @@ function createAppBrowserNavigationController(deps = {}) {
 			});
 			if (approval.decision.disposition === "no-commit") {
 				settlePendingBrowserRouterState(options.pendingRouterState);
+				pendingNavigationFailureTargets.delete(renderId);
+				if (failureTarget) clearAppNavigationFailureTarget(failureTarget);
 				pendingNavigationCommits.delete(renderId);
 				resolveCommitted?.();
 				consumeAppRouterScrollIntent(options.scrollIntent ?? null);
@@ -331,9 +350,12 @@ function createAppBrowserNavigationController(deps = {}) {
 			}
 			if (approval.decision.disposition === "hard-navigate") {
 				settlePendingBrowserRouterState(options.pendingRouterState);
+				pendingNavigationFailureTargets.delete(renderId);
 				pendingNavigationCommits.delete(renderId);
 				consumeAppRouterScrollIntent(options.scrollIntent ?? null);
-				return performHardNavigation(options.targetHref) ? "hard-navigate" : "no-commit";
+				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");
@@ -349,8 +371,9 @@ function createAppBrowserNavigationController(deps = {}) {
 			claimAppRouterScrollIntentForCommit(options.scrollIntent, renderId);
 			activateNavigationSnapshot();
 			snapshotActivated = true;
-			dispatchApprovedVisibleCommit(approvedCommit, options.pendingRouterState);
+			dispatchApprovedVisibleCommit(approvedCommit, options.pendingRouterState, options.visibleCommitMode ?? "transition");
 		} catch (error) {
+			pendingNavigationFailureTargets.delete(renderId);
 			pendingNavigationPrePaintEffects.delete(renderId);
 			pendingNavigationCommits.delete(renderId);
 			if (snapshotActivated) commitClientNavigationStateImpl(options.navId);
@@ -434,6 +457,7 @@ function createAppBrowserNavigationController(deps = {}) {
 		commitSameUrlNavigatePayload,
 		hmrReplaceTree,
 		drainPrePaintEffects,
+		clearCommittedNavigationFailureTargets,
 		NavigationCommitSignal
 	};
 }

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

@@ -1,7 +1,7 @@
 //#region src/server/app-browser-rsc-redirect.d.ts
-declare const MAX_RSC_REDIRECT_DEPTH = 10;
 type RscRedirectHistoryUpdateMode = "push" | "replace" | undefined;
 type RscRedirectLifecycleDecision = {
+  href: string;
   kind: "no-redirect";
 } | {
   href: string;
@@ -24,5 +24,14 @@ declare function resolveRscRedirectLifecycleHop(options: {
   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 { MAX_RSC_REDIRECT_DEPTH, resolveRscRedirectLifecycleHop };
+export { resolveRscRedirectLifecycleHop, resolveStreamedRscRedirectLifecycleHop };