vinext 0.1.1 → 0.1.2

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-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";
 
@@ -75,6 +76,7 @@ type BrowserNavigationController = {
     targetHistoryIndex?: number | null;
     targetHref: string;
     navId: number;
+    visibleCommitMode?: NavigationRuntimeVisibleCommitMode;
   }): Promise<NavigationPayloadOutcome>;
   commitSameUrlNavigatePayload(nextElements: Promise<AppElements>, navigationSnapshot: ClientNavigationRenderSnapshot, returnValue?: {
     ok: boolean;
@@ -99,7 +101,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,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) {
@@ -50,10 +51,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();
@@ -221,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));
 		});
@@ -349,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);

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 };

package/dist/server/app-browser-rsc-redirect.js

@@ -6,17 +6,23 @@ function toVisibleAppHref(href, origin) {
 	stripRscCacheBustingSearchParam(url);
 	return `${stripRscSuffix(url.pathname)}${url.search}${url.hash}`;
 }
-function resolveRscRedirectLifecycleHop(options) {
-	const responseUrl = new URL(options.responseUrl, options.origin);
-	if (responseUrl.origin !== options.origin) return {
-		href: responseUrl.href,
+function toStreamedRedirectVisibleAppHref(href, origin) {
+	const url = new URL(href, origin);
+	return `${url.pathname}${url.search}${url.hash}`;
+}
+function resolveRedirectLifecycleHopFromTarget(options) {
+	if (options.targetUrl.origin !== options.origin) return {
+		href: options.targetUrl.href,
 		kind: "terminal-hard-navigation",
 		reason: "externalRedirect",
 		redirectDepth: options.redirectDepth
 	};
-	const redirectedHref = resolveHardNavigationTargetFromRscResponse(responseUrl.href, options.currentHref, options.origin);
-	if (redirectedHref === toVisibleAppHref(options.currentHref, options.origin)) return { kind: "no-redirect" };
-	const maxRedirectDepth = options.maxRedirectDepth ?? 10;
+	const redirectedHref = options.redirectedHref;
+	if (redirectedHref === toVisibleAppHref(options.currentHref, options.origin)) return {
+		href: redirectedHref,
+		kind: "no-redirect"
+	};
+	const maxRedirectDepth = options.maxRedirectDepth ?? MAX_RSC_REDIRECT_DEPTH;
 	if (options.redirectDepth >= maxRedirectDepth) return {
 		href: redirectedHref,
 		kind: "terminal-hard-navigation",
@@ -31,5 +37,21 @@ function resolveRscRedirectLifecycleHop(options) {
 		redirectDepth: options.redirectDepth + 1
 	};
 }
+function resolveRscRedirectLifecycleHop(options) {
+	const responseUrl = new URL(options.responseUrl, options.origin);
+	return resolveRedirectLifecycleHopFromTarget({
+		...options,
+		redirectedHref: resolveHardNavigationTargetFromRscResponse(responseUrl.href, options.currentHref, options.origin),
+		targetUrl: responseUrl
+	});
+}
+function resolveStreamedRscRedirectLifecycleHop(options) {
+	const streamedRedirectUrl = new URL(options.streamedRedirectTarget, options.origin);
+	return resolveRedirectLifecycleHopFromTarget({
+		...options,
+		redirectedHref: toStreamedRedirectVisibleAppHref(options.streamedRedirectTarget, options.origin),
+		targetUrl: streamedRedirectUrl
+	});
+}
 //#endregion
-export { MAX_RSC_REDIRECT_DEPTH, resolveRscRedirectLifecycleHop };
+export { resolveRscRedirectLifecycleHop, resolveStreamedRscRedirectLifecycleHop };

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

@@ -7,9 +7,10 @@ import { getMountedSlotIds, getMountedSlotIdsHeader } from "./app-elements.js";
 import "./app-bfcache-id.js";
 import { createHistoryStateWithNavigationMetadata, createHistoryStateWithPreviousNextUrl, isBfcacheSegmentId, isHistoryStateBfcacheVersionCurrent, readHistoryStateBfcacheIds, readHistoryStateBfcacheVersion, readHistoryStatePreviousNextUrl, readHistoryStateTraversalIndex, resolveHistoryTraversalIntent } from "./app-history-state.js";
 import { createRscRequestHeaders } from "./app-rsc-cache-busting.js";
-import { createCacheEntryReuseProof } from "./cache-proof.js";
 import { NavigationTraceReasonCodes, createNavigationLifecycleTraceFields, createNavigationTrace } from "./navigation-trace.js";
 import { navigationPlanner, resolveDefaultOrUnmatchedSlotPersistenceForLayouts } from "./navigation-planner.js";
+import { createSnapshotPathAndSearch } from "../shims/navigation.js";
+import { createCacheEntryReuseProof } from "./cache-proof.js";
 //#region src/server/app-browser-state.ts
 const FRESH_APP_NAVIGATION_PAYLOAD_ORIGIN = { origin: "fresh" };
 const VISITED_CACHE_APP_NAVIGATION_PAYLOAD_ORIGIN = { origin: "visited-cache" };
@@ -222,10 +223,6 @@ function createPendingNavigationTraceFields(options) {
 		...options.targetHref !== void 0 ? { targetHref: options.targetHref } : {}
 	};
 }
-function createNavigationSnapshotUrl(snapshot) {
-	const query = snapshot.searchParams.toString();
-	return query === "" ? snapshot.pathname : `${snapshot.pathname}?${query}`;
-}
 function createMountedParallelSlotSnapshots(elements) {
 	const snapshots = [];
 	for (const slotId of getMountedSlotIds(elements)) {
@@ -239,7 +236,7 @@ function createMountedParallelSlotSnapshots(elements) {
 	return snapshots;
 }
 function createVisibleRouteSnapshot(state) {
-	const displayUrl = createNavigationSnapshotUrl(state.navigationSnapshot);
+	const displayUrl = createSnapshotPathAndSearch(state.navigationSnapshot);
 	const matchedUrl = normalizeNavigationSnapshotMatchedUrl(state.navigationSnapshot.pathname);
 	return {
 		displayUrl,
@@ -257,7 +254,7 @@ function createVisibleRouteSnapshot(state) {
 	};
 }
 function createPendingRouteSnapshot(pending) {
-	const displayUrl = createNavigationSnapshotUrl(pending.action.navigationSnapshot);
+	const displayUrl = createSnapshotPathAndSearch(pending.action.navigationSnapshot);
 	const matchedUrl = normalizeNavigationSnapshotMatchedUrl(pending.action.navigationSnapshot.pathname);
 	return {
 		displayUrl,

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

@@ -1,7 +1,7 @@
 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 { mergeElements } from "../shims/slot.js";
 import { createPendingNavigationCommit, preserveBfcacheIdsForMergedElements, resolvePendingNavigationCommitDispositionDecision } from "./app-browser-state.js";
 //#region src/server/app-browser-visible-commit.ts
 const approvedVisibleCommitBrand = Symbol("ApprovedVisibleCommit");

package/dist/server/app-fallback-renderer.d.ts

@@ -52,7 +52,8 @@ type AppFallbackRendererOptions<TModule extends AppPageModule = AppPageModule> =
   loadGlobalNotFoundModule?: (() => Promise<TModule | null | undefined>) | null;
   makeThenableParams: (params: AppPageParams) => unknown;
   metadataRoutes: MetadataFileRoute[]; /** Configured next.config `basePath`, threaded into file-based metadata href emission. */
-  basePath?: string;
+  basePath?: string; /** Configured next.config `trailingSlash`, threaded into canonical URL rendering. */
+  trailingSlash?: boolean;
   resolveChildSegments: (routeSegments: readonly string[], treePosition: number, params: AppPageParams) => string[];
   rootBoundaries: AppFallbackRendererRootBoundaries<TModule>;
   rscRenderer: (element: ReactNode | AppElements, options: {

package/dist/server/app-fallback-renderer.js

@@ -7,7 +7,7 @@ const EMPTY_MW_CTX = {
 	status: null
 };
 function createAppFallbackRenderer(options) {
-	const { basePath = "", clearRequestContext, createRscOnErrorHandler: buildRscOnErrorHandler, fontProviders, getNavigationContext, globalErrorModule, loadGlobalNotFoundModule, makeThenableParams, metadataRoutes, resolveChildSegments, rootBoundaries, rscRenderer, sanitizer, ssrLoader } = options;
+	const { basePath = "", clearRequestContext, createRscOnErrorHandler: buildRscOnErrorHandler, fontProviders, getNavigationContext, globalErrorModule, loadGlobalNotFoundModule, makeThenableParams, metadataRoutes, resolveChildSegments, rootBoundaries, rscRenderer, sanitizer, ssrLoader, trailingSlash } = options;
 	const { rootForbiddenModule, rootLayouts, rootNotFoundModule, rootUnauthorizedModule } = rootBoundaries;
 	const effectiveGlobalErrorModule = globalErrorModule ?? DEFAULT_GLOBAL_ERROR_MODULE;
 	const effectiveRootNotFoundModule = rootNotFoundModule ?? DEFAULT_NOT_FOUND_MODULE;
@@ -58,6 +58,7 @@ function createAppFallbackRenderer(options) {
 			}
 			return renderAppPageHttpAccessFallback({
 				basePath,
+				trailingSlash,
 				boundaryComponent: opts?.boundaryComponent ?? null,
 				boundaryModule: opts?.boundaryModule ?? null,
 				buildFontLinkHeader: fontProviders.buildFontLinkHeader,
@@ -96,6 +97,7 @@ function createAppFallbackRenderer(options) {
 		renderErrorBoundary(route, error, isRscRequest, request, matchedParams, scriptNonce, middlewareContext, callContext) {
 			return renderAppPageErrorBoundary({
 				basePath,
+				trailingSlash,
 				buildFontLinkHeader: fontProviders.buildFontLinkHeader,
 				clearRequestContext,
 				createRscOnErrorHandler(pathname, routePath) {

package/dist/server/app-middleware.js

@@ -115,6 +115,7 @@ async function applyAppMiddleware(options) {
 	if (!forwarded.applied) {
 		const result = await executeMiddleware({
 			basePath: options.basePath,
+			hadBasePath: true,
 			i18nConfig: options.i18nConfig,
 			isDataRequest: options.isDataRequest,
 			isProxy: options.isProxy,

package/dist/server/app-optimistic-routing.js

@@ -1,5 +1,6 @@
 import { buildParams, decodeMatchedParams, splitPathnameForRouteMatch } from "../routing/utils.js";
 import { stripBasePath } from "../utils/base-path.js";
+import { matchRoutePattern } from "../routing/route-pattern.js";
 import { isUnknownRecord } from "../utils/record.js";
 import { AppElementsWire } from "./app-elements-wire.js";
 import "./app-elements.js";
@@ -135,6 +136,20 @@ function matchOptimisticRouteManifestRoute(options) {
 	decodeMatchedParams(match.params);
 	return match;
 }
+function mergeParams(target, source) {
+	for (const [key, value] of Object.entries(source)) target[key] = value;
+}
+function resolveOptimisticNavigationParams(options) {
+	const navigationParams = { ...options.match.params };
+	for (const binding of options.routeManifest.segmentGraph.slotBindings.values()) {
+		if (binding.routeId !== options.match.route.id || binding.state !== "active") continue;
+		const patternParts = binding.slotPatternParts;
+		if (!patternParts) continue;
+		const matched = matchRoutePattern(options.urlParts, patternParts);
+		if (matched) mergeParams(navigationParams, matched);
+	}
+	return navigationParams;
+}
 function elementHasSuspenseFallback(value, depth = 0) {
 	if (depth > 100) return false;
 	if (Array.isArray(value)) return value.some((entry) => elementHasSuspenseFallback(entry, depth + 1));
@@ -183,6 +198,8 @@ function createOptimisticRouteElements(template) {
 }
 function resolveOptimisticNavigationPayload(options) {
 	if (options.interceptionContext !== null) return null;
+	const urlParts = hrefToRouteParts(options.href, options.basePath);
+	if (urlParts === null) return null;
 	const match = matchOptimisticRouteManifestRoute({
 		basePath: options.basePath,
 		href: options.href,
@@ -198,7 +215,11 @@ function resolveOptimisticNavigationPayload(options) {
 	if (template.mountedSlotsHeader !== options.mountedSlotsHeader) return null;
 	return {
 		elements: createOptimisticRouteElements(template),
-		params: match.params,
+		params: resolveOptimisticNavigationParams({
+			match,
+			routeManifest: options.routeManifest,
+			urlParts
+		}),
 		template
 	};
 }

package/dist/server/app-page-boundary-render.d.ts

@@ -41,7 +41,8 @@ type AppPageBoundaryRenderCommonOptions<TModule extends AppPageModule = AppPageM
   makeThenableParams: (params: AppPageParams) => unknown;
   middlewareContext: AppPageMiddlewareContext;
   metadataRoutes: MetadataFileRoute[]; /** Configured next.config `basePath`, threaded into file-based metadata href emission. */
-  basePath?: string;
+  basePath?: string; /** Configured next.config `trailingSlash`, threaded into canonical URL rendering. */
+  trailingSlash?: boolean;
   renderToReadableStream: (element: ReactNode | AppElements, options: {
     onError: AppPageBoundaryOnError;
   }) => ReadableStream<Uint8Array>;

package/dist/server/app-page-boundary-render.js

@@ -168,7 +168,8 @@ async function renderAppPageHttpAccessFallback(options) {
 	if (metadata) headElements.push(createElement(MetadataHead, {
 		key: "metadata",
 		metadata,
-		pathname
+		pathname,
+		trailingSlash: options.trailingSlash
 	}));
 	headElements.push(createElement(ViewportHead, {
 		key: "viewport",
@@ -231,7 +232,8 @@ async function renderAppPageErrorBoundary(options) {
 		if (metadata) headElements.push(createElement(MetadataHead, {
 			key: "metadata",
 			metadata,
-			pathname
+			pathname,
+			trailingSlash: options.trailingSlash
 		}));
 		headElements.push(createElement(ViewportHead, {
 			key: "viewport",