vinext 1.2.0 → 1.3.0

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

@@ -1,6 +1,7 @@
 import { HistoryUpdateMode } from "./app-browser-navigation-controller.js";
 //#region src/server/app-browser-mpa-navigation.d.ts
 export type AppBrowserMpaNavigationWindow = {
+  document?: Pick<Document, "visibilityState">;
   location: Pick<Location, "assign" | "replace">;
   requestAnimationFrame?: (callback: FrameRequestCallback) => unknown;
   setTimeout(callback: () => void, timeout: number): unknown;

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

@@ -14,21 +14,22 @@ var AppBrowserMpaNavigationScheduler = class {
 		this.#pendingNavigation = null;
 	}
 	navigate(targetWindow, href, historyUpdateMode) {
-		const pendingNavigation = this.#pendingNavigation;
-		if (pendingNavigation?.href === href && pendingNavigation.historyUpdateMode === historyUpdateMode) return;
+		if (this.#pendingNavigation?.href === href) return;
 		const token = this.#nextToken + 1;
 		this.#nextToken = token;
 		this.#pendingNavigation = {
 			href,
-			historyUpdateMode,
 			token
 		};
 		const navigate = () => {
-			const currentNavigation = this.#pendingNavigation;
-			if (currentNavigation?.href !== href || currentNavigation.historyUpdateMode !== historyUpdateMode || currentNavigation.token !== token) return;
+			if (this.#pendingNavigation?.token !== token) return;
 			if (historyUpdateMode === "replace") targetWindow.location.replace(href);
 			else targetWindow.location.assign(href);
 		};
+		if (targetWindow.document?.visibilityState === "hidden") {
+			navigate();
+			return;
+		}
 		if (typeof targetWindow.requestAnimationFrame === "function") {
 			targetWindow.requestAnimationFrame(() => {
 				targetWindow.setTimeout(navigate, 0);

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

@@ -1,4 +1,4 @@
-import { RouteManifest } from "../routing/app-route-graph.js";
+import { BrowserRouteManifest } from "../routing/browser-route-manifest.js";
 import { AppRouterScrollIntent } from "../shims/app-router-scroll-state.js";
 import { NavigationRuntimeVisibleCommitMode } from "../client/navigation-runtime.js";
 import { AppElements } from "./app-elements-wire.js";
@@ -17,10 +17,14 @@ export type PendingBrowserRouterState = {
 };
 export type NavigationPayloadOutcome = "committed" | "no-commit" | "hard-navigate";
 type HardNavigationMode = "assign" | "replace";
-type BrowserNavigationCommitEffect = (options: {
-  keepCurrentUrl: boolean;
-  releaseSnapshot: boolean;
-}) => void;
+type BrowserNavigationCommitEffect = {
+  writeHistory(options: {
+    keepCurrentUrl: boolean;
+  }): void;
+  publish(options: {
+    releaseSnapshot: boolean;
+  }): void;
+};
 type BrowserNavigationCommitEffectFactory = (options: {
   activeRoutePaths: readonly string[];
   bfcacheIds: Readonly<Record<string, string>>;
@@ -43,8 +47,10 @@ type SameUrlServerActionLifecycleOptions = {
 type BrowserNavigationControllerDeps = {
   basePath?: string;
   commitClientNavigationState?: typeof commitClientNavigationState;
+  navigateDocument?: (href: string, mode: HardNavigationMode) => void;
   performHardNavigation?: (href: string, mode?: HardNavigationMode) => boolean;
-  getRouteManifest?: () => RouteManifest | null;
+  getRouteManifest?: () => BrowserRouteManifest | null;
+  loadRouteManifest?: () => Promise<boolean> | null;
   syncHistoryStatePreviousNextUrl?: (previousNextUrl: string | null, bfcacheIds?: Readonly<Record<string, string>> | null) => void;
 };
 type BrowserNavigationPayloadOptions = {
@@ -80,6 +86,7 @@ type BrowserNavigationController = {
   waitForBrowserRouterStateReady(): Promise<void>;
   attachBrowserRouterState(setter: Dispatch<AppRouterState | Promise<AppRouterState>>, stateRef: BrowserRouterStateRef): () => void;
   beginPendingBrowserRouterState(): PendingBrowserRouterState;
+  abandonPendingBrowserRouterState(pending: PendingBrowserRouterState | null | undefined): void;
   finalizeNavigation(navId: number, pending: PendingBrowserRouterState | null | undefined): void;
   discardPendingNavigation(visibleState: AppRouterState | null): boolean;
   flushCommittingNavigationUrl(): void;
@@ -112,8 +119,12 @@ type BrowserNavigationController = {
     renderId: number;
     children?: ReactNode;
   }): ReactNode;
+  NavigationHistoryCommit(this: void, { renderId }: {
+    renderId: number;
+  }): null;
 };
 export declare function clearHardNavigationLoopGuard(): void;
+export declare function navigateDocumentDirectly(href: string, mode: HardNavigationMode): void;
 export declare function createBasePathStrippedPathAndSearch(url: URL, basePath: string): string;
 export declare function createAppBrowserNavigationController(deps?: BrowserNavigationControllerDeps): BrowserNavigationController;
 //#endregion

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

@@ -1,4 +1,5 @@
 import { stripBasePath } from "../utils/base-path.js";
+import { withBasePath } from "../shims/url-utils.js";
 import { clearAppNavigationFailureTarget, getAppNavigationFailureTarget } from "../client/app-nav-failure-handler.js";
 import { claimAppRouterScrollIntentForCommit, clearAppRouterScrollIntent, consumeAppRouterScrollIntent } from "../shims/app-router-scroll-state.js";
 import { resolveServerActionOperationLane, shouldScheduleRefreshForDiscardedServerAction } from "./app-browser-action-result.js";
@@ -37,7 +38,11 @@ function clearHardNavigationLoopGuard() {
 		window.sessionStorage.removeItem(HARD_NAVIGATION_LOOP_GUARD_KEY);
 	} catch {}
 }
-function performHardNavigationWithLoopGuard(href, mode = "assign") {
+function navigateDocumentDirectly(href, mode) {
+	if (mode === "replace") window.location.replace(href);
+	else window.location.assign(href);
+}
+function performHardNavigationWithLoopGuard(href, mode = "assign", navigateDocument = navigateDocumentDirectly) {
 	const targetHref = normalizeBrowserHref(href);
 	const currentHref = normalizeBrowserHref(window.location.href);
 	if (readHardNavigationLoopGuard() === targetHref && currentHref === targetHref) {
@@ -49,8 +54,7 @@ function performHardNavigationWithLoopGuard(href, mode = "assign") {
 		console.error(`[vinext] Hard navigation to ${targetHref} requires a reload-loop guard, but sessionStorage is unavailable; leaving the current document in place.`);
 		return false;
 	}
-	if (mode === "replace") window.location.replace(href);
-	else window.location.assign(href);
+	navigateDocument(href, mode);
 	return true;
 }
 function createBasePathStrippedPathAndSearch(url, basePath) {
@@ -69,8 +73,9 @@ function isSnapshotTargetHref(basePath, snapshot, targetHref) {
 function createAppBrowserNavigationController(deps = {}) {
 	const basePath = deps.basePath ?? "";
 	const commitClientNavigationStateImpl = deps.commitClientNavigationState ?? commitClientNavigationState;
-	const performHardNavigation = deps.performHardNavigation ?? performHardNavigationWithLoopGuard;
+	const performHardNavigation = deps.performHardNavigation ?? ((href, mode) => performHardNavigationWithLoopGuard(href, mode, deps.navigateDocument));
 	const getRouteManifest = deps.getRouteManifest ?? (() => null);
+	const loadRouteManifest = deps.loadRouteManifest ?? (() => null);
 	const syncHistoryStatePreviousNextUrl = deps.syncHistoryStatePreviousNextUrl ?? (() => {});
 	let nextNavigationRenderId = 0;
 	let activeNavigationId = 0;
@@ -162,6 +167,11 @@ function createAppBrowserNavigationController(deps = {}) {
 		pending.resolve(getBrowserRouterState());
 		if (activePendingBrowserRouterState === pending) activePendingBrowserRouterState = null;
 	}
+	function abandonPendingBrowserRouterState(pending) {
+		if (!pending || pending.settled) return;
+		pending.settled = true;
+		if (activePendingBrowserRouterState === pending) activePendingBrowserRouterState = null;
+	}
 	function finalizeNavigation(navId, pending) {
 		settlePendingBrowserRouterState(pending);
 		if (isCurrentNavigation(navId)) {
@@ -209,11 +219,11 @@ function createAppBrowserNavigationController(deps = {}) {
 		return true;
 	}
 	/**
-	* Run the URL update of a navigation render React is committing right now.
-	* It normally runs in NavigationCommitSignal's layout effect, after the
-	* route's own layout effects. Next.js writes the URL in an insertion effect
-	* instead, so a raw history write from a destination layout effect lands on
-	* top of the destination entry. Called before such a write to keep that order.
+	* Publish the URL update of a navigation render React is committing right
+	* now. Its history entry is already written, but publishing normally runs in
+	* NavigationCommitSignal's layout effect, after the route's own layout
+	* effects. Called before a raw history write from such an effect, so the
+	* write is published on top of the destination's.
 	*/
 	function flushCommittingNavigationUrl() {
 		if (committingNavigationRenderId !== null) drainPrePaintEffects(committingNavigationRenderId);
@@ -224,9 +234,12 @@ function createAppBrowserNavigationController(deps = {}) {
 	function isRetiredNavigationUrl(navId, targetHref) {
 		return retiredNavigationUrl !== null && retiredNavigationUrl.navigationId === navId && retiredNavigationUrl.href === normalizeBrowserHref(targetHref);
 	}
-	function queuePrePaintNavigationEffect(renderId, effect) {
-		if (!effect) return;
-		pendingNavigationPrePaintEffects.set(renderId, effect);
+	function writeNavigationRenderHistory(renderId) {
+		const effect = pendingNavigationPrePaintEffects.get(renderId);
+		const writeHistory = effect?.writeHistory;
+		if (!effect || !writeHistory) return;
+		effect.writeHistory = null;
+		writeHistory();
 	}
 	/**
 	* Run all queued pre-paint effects for renderIds up to and including the
@@ -243,8 +256,10 @@ function createAppBrowserNavigationController(deps = {}) {
 		for (const [id, effect] of pendingNavigationPrePaintEffects) {
 			if (id > upToRenderId) continue;
 			pendingNavigationPrePaintEffects.delete(id);
-			if (id === upToRenderId) effect();
-			else releaseRenderSnapshot(id);
+			if (id === upToRenderId) {
+				effect.writeHistory?.();
+				effect.publish();
+			} else releaseRenderSnapshot(id);
 		}
 	}
 	/**
@@ -261,7 +276,10 @@ function createAppBrowserNavigationController(deps = {}) {
 			pendingCommit.resolve(didCommit);
 		}
 	}
-	/** Runs when React starts committing a render, before any layout effect. */
+	/**
+	* Runs when React starts committing a render, before it changes the route
+	* tree's DOM, and writes the render's history entry.
+	*/
 	function beginNavigationRenderCommit(renderId) {
 		committingNavigationRenderId = renderId;
 		const committingCommit = pendingNavigationCommits.get(renderId);
@@ -269,6 +287,7 @@ function createAppBrowserNavigationController(deps = {}) {
 		if (committingCommit && committingOperation?.navigationCommitKind === "detached" && committingOperation.navigationId === pendingUserNavigationId) pendingUserNavigationShellHref = normalizeBrowserHref(committingCommit.targetHref);
 		else pendingUserNavigationCommitStarted = true;
 		clearCommittedNavigationFailureTargets(renderId);
+		writeNavigationRenderHistory(renderId);
 	}
 	function commitNavigationRender(renderId) {
 		committingNavigationRenderId = null;
@@ -288,7 +307,11 @@ function createAppBrowserNavigationController(deps = {}) {
 		if (!hasBrowserRouterState()) return;
 		const currentState = getBrowserRouterState();
 		const renderId = allocateRenderId();
-		const [navigationSnapshot] = await Promise.all([pendingNavigationSnapshot, nextElements]);
+		const [navigationSnapshot, , routeManifestLoaded] = await Promise.all([
+			pendingNavigationSnapshot,
+			nextElements,
+			loadRouteManifest()
+		]);
 		const pending = await createPendingNavigationCommit({
 			currentState,
 			nextElements,
@@ -300,6 +323,10 @@ function createAppBrowserNavigationController(deps = {}) {
 		});
 		if (hmrUpdateId !== latestHmrUpdateId || startedDuringUserNavigation) return;
 		if (!hasBrowserRouterState()) return;
+		if (routeManifestLoaded === false) {
+			performHardNavigation(withBasePath(createSnapshotPathAndSearch(navigationSnapshot), basePath));
+			return;
+		}
 		const approval = approveHmrVisibleCommit({
 			currentState: getBrowserRouterState(),
 			pending,
@@ -309,10 +336,19 @@ function createAppBrowserNavigationController(deps = {}) {
 		if (approval.approvedCommit) dispatchSynchronousVisibleCommit(approval.approvedCommit);
 		else if (approval.decision.disposition === "hard-navigate") performHardNavigation(createSnapshotPathAndSearch(navigationSnapshot));
 	}
-	function NavigationCommitSignal({ renderId, children }) {
+	/**
+	* Rendered before the route tree (see createAppRouteTree). Insertion effects
+	* run in the mutation phase, in tree order, after each component's own
+	* subtree mutations, so this one runs before React changes the route tree's
+	* DOM. An effect on NavigationCommitSignal itself would run after them.
+	*/
+	function NavigationHistoryCommit({ renderId }) {
 		useInsertionEffect(() => {
 			beginNavigationRenderCommit(renderId);
 		}, [renderId]);
+		return null;
+	}
+	function NavigationCommitSignal({ renderId, children }) {
 		useLayoutEffect(() => {
 			commitNavigationRender(renderId);
 			return () => {
@@ -433,6 +469,13 @@ function createAppBrowserNavigationController(deps = {}) {
 		return isSamePathSearchHashCommit(options.targetHref);
 	}
 	async function renderNavigationPayload(options) {
+		const routeManifestLoad = loadRouteManifest();
+		if (routeManifestLoad !== null && !await routeManifestLoad) {
+			settlePendingBrowserRouterState(options.pendingRouterState);
+			consumeAppRouterScrollIntent(options.scrollIntent ?? null);
+			if (isCurrentNavigation(options.navId)) performHardNavigation(options.targetHref, options.historyUpdateMode === "push" ? "assign" : "replace");
+			return "no-commit";
+		}
 		if (options.navId === pendingUserNavigationId) pendingUserNavigationLane = options.operationLane;
 		const renderId = allocateRenderId();
 		const failureTarget = getAppNavigationFailureTarget(options.targetHref);
@@ -486,11 +529,14 @@ function createAppBrowserNavigationController(deps = {}) {
 				return "no-commit";
 			}
 			if (approval.decision.disposition === "hard-navigate") {
-				settlePendingBrowserRouterState(options.pendingRouterState);
 				pendingNavigationFailureTargets.delete(renderId);
 				pendingNavigationCommits.delete(renderId);
 				consumeAppRouterScrollIntent(options.scrollIntent ?? null);
-				if (performHardNavigation(options.targetHref)) return "hard-navigate";
+				if (performHardNavigation(options.targetHref, options.historyUpdateMode === "push" ? "assign" : "replace")) {
+					abandonPendingBrowserRouterState(options.pendingRouterState);
+					return "hard-navigate";
+				}
+				settlePendingBrowserRouterState(options.pendingRouterState);
 				if (failureTarget) clearAppNavigationFailureTarget(failureTarget);
 				return "no-commit";
 			}
@@ -507,11 +553,13 @@ function createAppBrowserNavigationController(deps = {}) {
 				previousNextUrl: approvedCommit.previousNextUrl,
 				targetHistoryIndex: options.targetHistoryIndex
 			});
-			queuePrePaintNavigationEffect(renderId, () => {
-				commitEffect({
-					keepCurrentUrl: isRetiredNavigationUrl(options.navId, options.targetHref),
-					releaseSnapshot: snapshotRenderIds.delete(renderId)
-				});
+			pendingNavigationPrePaintEffects.set(renderId, {
+				writeHistory: () => {
+					commitEffect.writeHistory({ keepCurrentUrl: isRetiredNavigationUrl(options.navId, options.targetHref) });
+				},
+				publish: () => {
+					commitEffect.publish({ releaseSnapshot: snapshotRenderIds.delete(renderId) });
+				}
 			});
 			claimAppRouterScrollIntentForCommit(options.scrollIntent, renderId);
 			if (!isRetiredNavigationUrl(options.navId, options.targetHref)) {
@@ -542,6 +590,15 @@ function createAppBrowserNavigationController(deps = {}) {
 		const currentState = actionInitiationState ?? getBrowserRouterState();
 		const startedNavigationId = lifecycleOptions?.startedNavigationId ?? activeNavigationId;
 		const targetHref = lifecycleOptions?.targetHref ?? window.location.href;
+		const routeManifestLoad = loadRouteManifest();
+		if (routeManifestLoad !== null && !await routeManifestLoad) {
+			if (isCurrentNavigation(startedNavigationId)) {
+				performHardNavigation(targetHref);
+				return;
+			}
+			notifyDiscardedServerActionRevalidation(lifecycleOptions);
+			return resolveSameUrlActionReturnValue(returnValue);
+		}
 		const { approvedCommit, decision, pending, trace: _navigationTrace } = await resolveAndClassifyNavigationCommit({
 			activeNavigationId,
 			currentState,
@@ -582,6 +639,9 @@ function createAppBrowserNavigationController(deps = {}) {
 				syncHistoryStatePreviousNextUrl(approvedRevalidationCommit.previousNextUrl, approvedRevalidationCommit.action.bfcacheIds);
 			} else notifyDiscardedServerActionRevalidation(lifecycleOptions);
 		} else if (decision.disposition === "no-commit") notifyDiscardedServerActionRevalidation(lifecycleOptions);
+		return resolveSameUrlActionReturnValue(returnValue);
+	}
+	async function resolveSameUrlActionReturnValue(returnValue) {
 		if (returnValue) {
 			if (!returnValue.ok) throw await returnValue.data;
 			return returnValue.data;
@@ -609,6 +669,7 @@ function createAppBrowserNavigationController(deps = {}) {
 		waitForBrowserRouterStateReady,
 		attachBrowserRouterState,
 		beginPendingBrowserRouterState,
+		abandonPendingBrowserRouterState,
 		finalizeNavigation,
 		discardPendingNavigation,
 		flushCommittingNavigationUrl,
@@ -620,8 +681,9 @@ function createAppBrowserNavigationController(deps = {}) {
 		beginNavigationRenderCommit,
 		commitNavigationRender,
 		clearCommittedNavigationFailureTargets,
-		NavigationCommitSignal
+		NavigationCommitSignal,
+		NavigationHistoryCommit
 	};
 }
 //#endregion
-export { clearHardNavigationLoopGuard, createAppBrowserNavigationController, createBasePathStrippedPathAndSearch, createSnapshotPathAndSearch };
+export { clearHardNavigationLoopGuard, createAppBrowserNavigationController, createBasePathStrippedPathAndSearch, createSnapshotPathAndSearch, navigateDocumentDirectly };

package/dist/server/app-browser-prefetch-response.js

@@ -1,4 +1,4 @@
-import { stripRscCacheBustingSearchParam } from "./app-rsc-cache-busting.js";
+import { formatRscRequestPath, stripRscCacheBustingSearchParam } from "./app-rsc-cache-busting.js";
 import { peekPrefetchResponseForNavigation } from "../shims/navigation.js";
 //#region src/server/app-browser-prefetch-response.ts
 function peekSettledPrefetchResponseForNavigation(options) {
@@ -25,7 +25,7 @@ function isSameOriginBrowserRscUrl(url, origin) {
 function canonicalizeBrowserRscResponseUrl(responseUrl, origin) {
 	try {
 		const parsed = new URL(responseUrl, origin);
-		if (parsed.origin === new URL(origin).origin) return `${parsed.pathname}${parsed.search}`;
+		if (parsed.origin === new URL(origin).origin) return formatRscRequestPath(parsed);
 	} catch {}
 	return responseUrl;
 }

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

@@ -1,4 +1,4 @@
-import { RouteManifest } from "../routing/app-route-graph.js";
+import { BrowserRouteManifest } from "../routing/browser-route-manifest.js";
 import { CacheEntryReuseProof } from "./cache-proof.js";
 import { AppElements, AppElementsInterception, AppElementsSlotBinding, LayoutFlags } from "./app-elements-wire.js";
 import "./app-elements.js";
@@ -130,7 +130,7 @@ export declare function resolvePendingNavigationCommitDispositionDecision(option
   activeNavigationId: number;
   currentState: AppRouterState;
   pending: PendingNavigationCommit;
-  routeManifest?: RouteManifest | null;
+  routeManifest?: BrowserRouteManifest | null;
   startedNavigationId: number;
   targetHref?: string;
 }): PendingNavigationCommitDispositionDecision;

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

@@ -1,7 +1,7 @@
-import { normalizePathnameForRouteMatch } from "../routing/utils.js";
 import { stripBasePath } from "../utils/base-path.js";
 import { VINEXT_INTERCEPTION_CONTEXT_HEADER, VINEXT_MOUNTED_SLOTS_HEADER } from "./app-rsc-vary.js";
 import { NEXT_ACTION_HEADER, RSC_ACTION_HEADER } from "./headers.js";
+import { normalizePathnameForRouteMatch } from "../routing/utils.js";
 import { normalizePath } from "./normalize-path.js";
 import { AppElementsWire } from "./app-elements-wire.js";
 import { getMountedSlotIds, getMountedSlotIdsHeader } from "./app-elements.js";

package/dist/server/app-browser-supplemental-refresh.js

@@ -1,5 +1,5 @@
-import { normalizePathnameForRouteMatch } from "../routing/utils.js";
 import { addBasePathToPathname, removeTrailingSlash, stripBasePath } from "../utils/base-path.js";
+import { normalizePathnameForRouteMatch } from "../routing/utils.js";
 import { normalizePath } from "./normalize-path.js";
 import { APP_INTERCEPTION_CONTEXT_KEY, APP_INTERCEPTION_KEY, APP_SLOT_BINDINGS_KEY, AppElementsWire, normalizeAppElementsSlotBindings } from "./app-elements-wire.js";
 import "./app-elements.js";

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

@@ -1,4 +1,4 @@
-import { RouteManifest } from "../routing/app-route-graph.js";
+import { BrowserRouteManifest } from "../routing/browser-route-manifest.js";
 import { AppElements } from "./app-elements-wire.js";
 import "./app-elements.js";
 import { NavigationTrace } from "./navigation-trace.js";
@@ -52,14 +52,14 @@ export declare function applyApprovedVisibleCommit(state: AppRouterState, commit
 export declare function approveHmrVisibleCommit(options: {
   currentState: AppRouterState;
   pending: PendingNavigationCommit;
-  routeManifest?: RouteManifest | null;
+  routeManifest?: BrowserRouteManifest | null;
   targetHref: string;
 }): CommitApproval;
 export declare function approvePendingNavigationCommit(options: {
   activeNavigationId: number;
   currentState: AppRouterState;
   pending: PendingNavigationCommit;
-  routeManifest?: RouteManifest | null;
+  routeManifest?: BrowserRouteManifest | null;
   startedNavigationId: number;
   targetHref: string;
 }): CommitApproval;
@@ -74,7 +74,7 @@ export declare function resolveAndClassifyNavigationCommit(options: {
   payloadOrigin: AppNavigationPayloadOrigin;
   previousNextUrl?: string | null;
   renderId: number;
-  routeManifest?: RouteManifest | null;
+  routeManifest?: BrowserRouteManifest | null;
   startedNavigationId: number;
   targetHref: string;
   type: "navigate" | "replace" | "traverse";

package/dist/server/app-client-reference-preloader.d.ts

@@ -9,5 +9,28 @@ type ClientReferencePreloaderOptions = {
 type ClientReferencePreloader = {
   preload: (referenceIds?: Iterable<string>) => Promise<void>;
 };
+/**
+ * The client references each App Router route preloads before SSR, generated
+ * by plugins/rsc-client-reference-loaders.ts from the RSC build's module graph.
+ * Each list holds indices into `references`, or for routes into `files`.
+ */
+export type RouteClientReferences = {
+  /** Client reference keys. */
+  references: readonly string[];
+  /** References any render may use, whatever its route. */
+  always: readonly number[];
+  /** The references each route file reaches. */
+  files: readonly (readonly number[])[];
+  /** Each route pattern's files. */
+  routes: Readonly<Record<string, readonly number[]>>;
+  /** The files of a render without a route, such as a route-miss 404. */
+  routeless: readonly number[];
+};
+/**
+ * The client references a render of `routePattern` preloads, or of no route
+ * when it is null. Undefined, meaning every reference, without a plan or a
+ * route to look up, or for a pattern the plan doesn't know.
+ */
+export declare function resolveRouteClientReferences(plan: RouteClientReferences | null, routePattern: string | null | undefined): string[] | undefined;
 export declare function createClientReferencePreloader(options: ClientReferencePreloaderOptions): ClientReferencePreloader;
 //#endregion

package/dist/server/app-client-reference-preloader.js

@@ -1,27 +1,50 @@
+import { shareIsolatePromise } from "./isolate-shared-promise.js";
 //#region src/server/app-client-reference-preloader.ts
 const resolvedPreload = Promise.resolve();
+/**
+* The client references a render of `routePattern` preloads, or of no route
+* when it is null. Undefined, meaning every reference, without a plan or a
+* route to look up, or for a pattern the plan doesn't know.
+*/
+function resolveRouteClientReferences(plan, routePattern) {
+	if (!plan || routePattern === void 0) return void 0;
+	let files;
+	if (routePattern === null) files = plan.routeless;
+	else if (Object.hasOwn(plan.routes, routePattern)) files = plan.routes[routePattern];
+	else return;
+	const indices = new Set(plan.always);
+	for (const file of files) for (const index of plan.files[file]) indices.add(index);
+	return Array.from(indices, (index) => plan.references[index]);
+}
 function createClientReferencePreloader(options) {
 	let allReferencesPreloaded = false;
 	let allReferencesPreloadPromise = null;
 	const preloadedReferences = /* @__PURE__ */ new Set();
 	const referencePreloadPromises = /* @__PURE__ */ new Map();
 	function preloadReference(id, clientRequire) {
-		if (preloadedReferences.has(id)) return resolvedPreload;
 		const existing = referencePreloadPromises.get(id);
 		if (existing) return existing;
-		const preloadPromise = clientRequire(id).catch((error) => {
+		const loading = clientRequire(id);
+		const preloadPromise = shareIsolatePromise(loading.then((value) => {
+			loading.status = "fulfilled";
+			loading.value = value;
+		}, (error) => {
+			loading.status = "rejected";
+			loading.reason = error;
+			throw error;
+		}).catch((error) => {
 			options.onPreloadError?.(id, error);
 		}).then(() => {
 			preloadedReferences.add(id);
 		}).finally(() => {
 			referencePreloadPromises.delete(id);
-		});
+		}));
 		referencePreloadPromises.set(id, preloadPromise);
 		return preloadPromise;
 	}
 	function preloadReferenceSet(referenceIds, refs, clientRequire) {
 		const pending = [];
-		for (const id of referenceIds) if (Object.hasOwn(refs, id)) pending.push(preloadReference(id, clientRequire));
+		for (const id of referenceIds) if (Object.hasOwn(refs, id) && !preloadedReferences.has(id)) pending.push(preloadReference(id, clientRequire));
 		if (pending.length === 0) return resolvedPreload;
 		return Promise.all(pending).then(() => {});
 	}
@@ -32,13 +55,13 @@ function createClientReferencePreloader(options) {
 		if (referenceIds) return preloadReferenceSet(referenceIds, refs, clientRequire);
 		if (allReferencesPreloaded) return resolvedPreload;
 		if (allReferencesPreloadPromise) return allReferencesPreloadPromise;
-		allReferencesPreloadPromise = preloadReferenceSet(Object.keys(refs), refs, clientRequire).then(() => {
+		allReferencesPreloadPromise = shareIsolatePromise(preloadReferenceSet(Object.keys(refs), refs, clientRequire).then(() => {
 			allReferencesPreloaded = true;
 		}).finally(() => {
 			allReferencesPreloadPromise = null;
-		});
+		}));
 		return allReferencesPreloadPromise;
 	} };
 }
 //#endregion
-export { createClientReferencePreloader };
+export { createClientReferencePreloader, resolveRouteClientReferences };

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

@@ -1,4 +1,5 @@
 import { runOutsideRequestScopes } from "../shims/internal/als-registry.js";
+import { shareIsolatePromise } from "./isolate-shared-promise.js";
 import { DEFAULT_GLOBAL_ERROR_MODULE } from "./default-global-error-module.js";
 import { shouldServeStreamingMetadata } from "./streaming-metadata.js";
 import { renderAppPageErrorBoundary, renderAppPageHttpAccessFallback } from "./app-page-boundary-render.js";
@@ -17,7 +18,7 @@ function createAppFallbackRenderer(options) {
 	let globalNotFoundModulePromise = null;
 	function resolveGlobalNotFoundModule() {
 		if (!loadGlobalNotFoundModule) return null;
-		if (globalNotFoundModulePromise === null) globalNotFoundModulePromise = runOutsideRequestScopes(() => Promise.resolve().then(loadGlobalNotFoundModule));
+		if (globalNotFoundModulePromise === null) globalNotFoundModulePromise = shareIsolatePromise(runOutsideRequestScopes(() => Promise.resolve().then(loadGlobalNotFoundModule)));
 		return globalNotFoundModulePromise;
 	}
 	return {

package/dist/server/app-middleware.d.ts

@@ -50,6 +50,12 @@ export type ApplyAppMiddlewareResult = {
   search: string | null;
 } | {
   kind: "response";
+  /**
+   * True when `response` proxies a middleware external rewrite. It carries
+   * middleware's headers, and the caller still stages next.config headers
+   * beneath them.
+   */
+  externalRewrite?: boolean;
   /** Present on real middleware results; optional for older generated callers. */
   matched?: boolean;
   /** True when this pathname can match middleware for some request context. */

package/dist/server/app-middleware.js

@@ -6,7 +6,7 @@ import { internalServerErrorResponse } from "./http-error-responses.js";
 import { cloneRequestWithHeaders, processMiddlewareHeaders } from "./request-pipeline.js";
 import { executeMiddleware } from "./middleware-runtime.js";
 import { applyMiddlewareRequestHeaders, setHeadersContext } from "../shims/headers.js";
-import { mergeMiddlewareResponseHeaders } from "./middleware-response-headers.js";
+import { mergeMiddlewareResponseHeaders, withExternalRewriteResponseHeaders } from "./middleware-response-headers.js";
 import { setNavigationContext } from "../shims/navigation-context-accessors.js";
 //#region src/server/app-middleware.ts
 const FLIGHT_HEADER_SET = new Set(FLIGHT_HEADERS);
@@ -92,19 +92,15 @@ async function proxyExternalMiddlewareRewrite(request, rewriteUrl, context) {
 	const proxyResponse = await proxyExternalRequest(proxyRequest, rewriteUrl);
 	const headers = new Headers(proxyResponse.headers);
 	processMiddlewareHeaders(headers);
-	if (!context.headers) return new Response(proxyResponse.body, {
-		status: proxyResponse.status,
-		statusText: proxyResponse.statusText,
-		headers
-	});
-	const middlewareHeaders = new Headers(context.headers);
+	const stagedHeaders = new Headers();
+	const middlewareHeaders = new Headers(context.headers ?? void 0);
 	processMiddlewareHeaders(middlewareHeaders);
-	mergeMiddlewareResponseHeaders(headers, middlewareHeaders);
-	return new Response(proxyResponse.body, {
+	mergeMiddlewareResponseHeaders(stagedHeaders, middlewareHeaders);
+	return withExternalRewriteResponseHeaders(new Response(proxyResponse.body, {
 		status: proxyResponse.status,
 		statusText: proxyResponse.statusText,
 		headers
-	});
+	}), stagedHeaders, middlewareHeaders.getSetCookie());
 }
 function validationResponseWithMiddlewareHeaders(response, context) {
 	if (!context.headers) return response;
@@ -171,6 +167,7 @@ async function applyAppMiddleware(options) {
 			const externalRequest = options.externalRewriteRequest ?? options.request;
 			return {
 				kind: "response",
+				externalRewrite: true,
 				matched,
 				pathnameEligible,
 				response: await proxyExternalMiddlewareRewrite(externalRequest, forwarded.rewriteUrl, options.context)
@@ -248,6 +245,7 @@ async function applyAppMiddleware(options) {
 				const externalRequest = options.externalRewriteRequest ?? options.request;
 				return {
 					kind: "response",
+					externalRewrite: true,
 					matched,
 					pathnameEligible,
 					response: await proxyExternalMiddlewareRewrite(externalRequest, result.rewriteUrl, options.context)