vinext 1.0.1 → 1.1.0

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

@@ -1,6 +1,6 @@
 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 { claimAppRouterScrollIntentForCommit, clearAppRouterScrollIntent, consumeAppRouterScrollIntent } from "../shims/app-router-scroll-state.js";
 import { resolveServerActionOperationLane, shouldScheduleRefreshForDiscardedServerAction } from "./app-browser-action-result.js";
 import { resolveActiveRoutePaths } from "./app-history-state.js";
 import { activateNavigationSnapshot, clearPendingPathname, commitClientNavigationState, createSnapshotPathAndSearch } from "../shims/navigation.js";
@@ -76,10 +76,15 @@ function createAppBrowserNavigationController(deps = {}) {
 	let activeNavigationId = 0;
 	let pendingUserNavigationId = null;
 	let pendingUserNavigationLane = null;
+	let committingNavigationRenderId = null;
+	let pendingUserNavigationCommitStarted = false;
 	let latestHmrUpdateId = 0;
 	const pendingNavigationCommits = /* @__PURE__ */ new Map();
 	const pendingNavigationFailureTargets = /* @__PURE__ */ new Map();
 	const pendingNavigationPrePaintEffects = /* @__PURE__ */ new Map();
+	const snapshotRenderIds = /* @__PURE__ */ new Set();
+	let pendingUserNavigationShellHref = null;
+	let retiredNavigationUrl = null;
 	let setBrowserRouterState = null;
 	let browserRouterStateRef = null;
 	let activePendingBrowserRouterState = null;
@@ -113,6 +118,9 @@ function createAppBrowserNavigationController(deps = {}) {
 		activeNavigationId += 1;
 		pendingUserNavigationId = activeNavigationId;
 		pendingUserNavigationLane = null;
+		pendingUserNavigationCommitStarted = false;
+		pendingUserNavigationShellHref = null;
+		retiredNavigationUrl = null;
 		return activeNavigationId;
 	}
 	function getActiveNavigationId() {
@@ -159,9 +167,63 @@ function createAppBrowserNavigationController(deps = {}) {
 		if (isCurrentNavigation(navId)) {
 			pendingUserNavigationId = null;
 			pendingUserNavigationLane = null;
+			pendingUserNavigationShellHref = null;
+			retiredNavigationUrl = null;
 			clearPendingPathname(navId);
 		}
 	}
+	/**
+	* Discard the user navigation that has not committed yet, keeping
+	* `visibleState` (the committed tree) on screen. Next.js does the same when
+	* a raw history.pushState/replaceState dispatches ACTION_RESTORE: the
+	* pending action is marked discarded and the restore commits the current
+	* tree in a transition, which replaces the navigation's suspended one.
+	* Returns whether a navigation was discarded.
+	*/
+	function discardPendingNavigation(visibleState) {
+		if (pendingUserNavigationId === null || pendingUserNavigationCommitStarted) return false;
+		if (pendingUserNavigationShellHref !== null) {
+			retiredNavigationUrl = {
+				navigationId: pendingUserNavigationId,
+				href: pendingUserNavigationShellHref
+			};
+			for (const renderId of pendingNavigationPrePaintEffects.keys()) releaseRenderSnapshot(renderId);
+			return false;
+		}
+		activeNavigationId += 1;
+		pendingUserNavigationId = null;
+		pendingUserNavigationLane = null;
+		clearAppRouterScrollIntent();
+		for (const renderId of pendingNavigationPrePaintEffects.keys()) {
+			pendingNavigationPrePaintEffects.delete(renderId);
+			releaseRenderSnapshot(renderId);
+		}
+		clearCommittedNavigationFailureTargets(nextNavigationRenderId);
+		settleNavigationCommits(nextNavigationRenderId, false);
+		if (visibleState && setBrowserRouterState) {
+			const setter = setBrowserRouterState;
+			startTransition(() => {
+				setter(visibleState);
+			});
+		}
+		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.
+	*/
+	function flushCommittingNavigationUrl() {
+		if (committingNavigationRenderId !== null) drainPrePaintEffects(committingNavigationRenderId);
+	}
+	function releaseRenderSnapshot(renderId) {
+		if (snapshotRenderIds.delete(renderId)) commitClientNavigationStateImpl(void 0, { releaseSnapshot: true });
+	}
+	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);
@@ -182,7 +244,7 @@ function createAppBrowserNavigationController(deps = {}) {
 			if (id > upToRenderId) continue;
 			pendingNavigationPrePaintEffects.delete(id);
 			if (id === upToRenderId) effect();
-			else commitClientNavigationStateImpl(void 0, { releaseSnapshot: true });
+			else releaseRenderSnapshot(id);
 		}
 	}
 	/**
@@ -199,7 +261,17 @@ function createAppBrowserNavigationController(deps = {}) {
 			pendingCommit.resolve(didCommit);
 		}
 	}
+	/** Runs when React starts committing a render, before any layout effect. */
+	function beginNavigationRenderCommit(renderId) {
+		committingNavigationRenderId = renderId;
+		const committingCommit = pendingNavigationCommits.get(renderId);
+		const committingOperation = committingCommit?.committedState?.activeOperation;
+		if (committingCommit && committingOperation?.navigationCommitKind === "detached" && committingOperation.navigationId === pendingUserNavigationId) pendingUserNavigationShellHref = normalizeBrowserHref(committingCommit.targetHref);
+		else pendingUserNavigationCommitStarted = true;
+		clearCommittedNavigationFailureTargets(renderId);
+	}
 	function commitNavigationRender(renderId) {
+		committingNavigationRenderId = null;
 		drainPrePaintEffects(renderId);
 		settleNavigationCommits(renderId, true);
 	}
@@ -239,7 +311,7 @@ function createAppBrowserNavigationController(deps = {}) {
 	}
 	function NavigationCommitSignal({ renderId, children }) {
 		useInsertionEffect(() => {
-			clearCommittedNavigationFailureTargets(renderId);
+			beginNavigationRenderCommit(renderId);
 		}, [renderId]);
 		useLayoutEffect(() => {
 			commitNavigationRender(renderId);
@@ -371,10 +443,10 @@ function createAppBrowserNavigationController(deps = {}) {
 			pendingNavigationCommits.set(renderId, {
 				committedState: null,
 				onCommittedState: options.onCommittedState,
-				resolve
+				resolve,
+				targetHref: options.targetHref
 			});
 		});
-		let snapshotActivated = false;
 		try {
 			const pendingOptions = {
 				currentState: options.navigationInitiationState,
@@ -425,7 +497,7 @@ function createAppBrowserNavigationController(deps = {}) {
 			const approvedCommit = approval.approvedCommit;
 			if (approvedCommit === null) throw new Error("[vinext] Commit decision did not approve a visible commit");
 			const approvedVisibleState = applyApprovedVisibleCommit(getBrowserRouterState(), approvedCommit);
-			queuePrePaintNavigationEffect(renderId, options.createNavigationCommitEffect({
+			const commitEffect = options.createNavigationCommitEffect({
 				activeRoutePaths: resolveActiveRoutePaths(approvedVisibleState.slotBindings),
 				bfcacheIds: approvedVisibleState.bfcacheIds,
 				href: options.targetHref,
@@ -434,10 +506,18 @@ function createAppBrowserNavigationController(deps = {}) {
 				params: options.params,
 				previousNextUrl: approvedCommit.previousNextUrl,
 				targetHistoryIndex: options.targetHistoryIndex
-			}));
+			});
+			queuePrePaintNavigationEffect(renderId, () => {
+				commitEffect({
+					keepCurrentUrl: isRetiredNavigationUrl(options.navId, options.targetHref),
+					releaseSnapshot: snapshotRenderIds.delete(renderId)
+				});
+			});
 			claimAppRouterScrollIntentForCommit(options.scrollIntent, renderId);
-			activateNavigationSnapshot();
-			snapshotActivated = true;
+			if (!isRetiredNavigationUrl(options.navId, options.targetHref)) {
+				activateNavigationSnapshot();
+				snapshotRenderIds.add(renderId);
+			}
 			dispatchApprovedVisibleCommit(renderId, approvedCommit, options.pendingRouterState, shouldForceSynchronousCommit(options) ? "synchronous" : options.visibleCommitMode ?? "transition");
 			if (options.navigationResponseCompletion) options.navigationResponseCompletion.then(() => {
 				if (!isCurrentNavigation(options.navId) || !hasBrowserRouterState()) return;
@@ -451,7 +531,7 @@ function createAppBrowserNavigationController(deps = {}) {
 			pendingNavigationFailureTargets.delete(renderId);
 			pendingNavigationPrePaintEffects.delete(renderId);
 			pendingNavigationCommits.delete(renderId);
-			if (snapshotActivated) commitClientNavigationStateImpl(options.navId);
+			if (snapshotRenderIds.delete(renderId)) commitClientNavigationStateImpl(options.navId);
 			settlePendingBrowserRouterState(options.pendingRouterState);
 			resolveCommitted?.(false);
 			throw error;
@@ -530,11 +610,14 @@ function createAppBrowserNavigationController(deps = {}) {
 		attachBrowserRouterState,
 		beginPendingBrowserRouterState,
 		finalizeNavigation,
+		discardPendingNavigation,
+		flushCommittingNavigationUrl,
 		restoreHistorySnapshotVisibleState,
 		renderNavigationPayload,
 		commitSameUrlNavigatePayload,
 		hmrReplaceTree,
 		drainPrePaintEffects,
+		beginNavigationRenderCommit,
 		commitNavigationRender,
 		clearCommittedNavigationFailureTargets,
 		NavigationCommitSignal

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

@@ -96,6 +96,8 @@ type AppFallbackRenderer<TModule extends AppPageModule = AppPageModule> = {
     boundaryComponent?: AppPageComponent | null;
     boundaryModule?: TModule | null;
     intercept?: AppPageInterceptOptions<TModule> | null;
+    /** The document may be stored, so it must not carry the request's query. */
+    isCacheCandidate?: boolean;
     layouts?: readonly (TModule | null | undefined)[] | null;
     matchedParams?: AppPageParams;
   }, scriptNonce: string | undefined, middlewareContext: AppPageMiddlewareContext, callContext?: AppFallbackRendererCallContext) => Promise<Response | null>;

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

@@ -86,6 +86,7 @@ function createAppFallbackRenderer(options) {
 				getNavigationContext,
 				globalErrorModule: effectiveGlobalErrorModule,
 				intercept: opts?.intercept ?? null,
+				isCacheCandidate: opts?.isCacheCandidate,
 				isEdgeRuntime: callContext?.isEdgeRuntime,
 				isRscRequest,
 				layoutModules: useGlobalNotFound ? [] : opts?.layouts ?? null,

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

@@ -29,6 +29,8 @@ export declare class HistoryStateSnapshotCache<TState> {
     historyIndex: number | null;
     state: TState;
   }): void;
+  /** Point every entry that remembered `previous` at `next` instead. */
+  replaceState(previous: TState, next: TState): void;
   resolveRestore(options: {
     currentBfcacheVersion: number;
     guarded: boolean;
@@ -51,6 +53,7 @@ export declare class RestorableClientStateController<TState> {
     historyIndex: number | null;
     state: TState;
   }): void;
+  replaceHistoryStateSnapshots(previous: TState, next: TState): void;
   resolveHistoryStateSnapshotRestore(historyState: unknown): HistoryStateSnapshotRestoreDecision<TState>;
 }
 export declare function createHistoryStateWithPreviousNextUrl(state: unknown, previousNextUrl: string | null): HistoryStateRecord | null;

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

@@ -31,6 +31,10 @@ var HistoryStateSnapshotCache = class {
 		const oldestIndex = this.#snapshots.keys().next().value;
 		if (typeof oldestIndex === "number") this.#snapshots.delete(oldestIndex);
 	}
+	/** Point every entry that remembered `previous` at `next` instead. */
+	replaceState(previous, next) {
+		for (const snapshot of this.#snapshots.values()) if (snapshot.state === previous) snapshot.state = next;
+	}
 	resolveRestore(options) {
 		const targetHistoryIndex = readHistoryStateTraversalIndex(options.historyState);
 		if (targetHistoryIndex === null) return {
@@ -111,6 +115,9 @@ var RestorableClientStateController = class {
 			state: options.state
 		});
 	}
+	replaceHistoryStateSnapshots(previous, next) {
+		this.#snapshots.replaceState(previous, next);
+	}
 	resolveHistoryStateSnapshotRestore(historyState) {
 		return this.#snapshots.resolveRestore({
 			currentBfcacheVersion: this.#currentBfcacheVersion,

package/dist/server/app-middleware.js

@@ -49,7 +49,8 @@ function requestWithMiddlewareRequestHeaders(request, middlewareHeaders) {
 	const init = {
 		method: request.method,
 		headers: nextHeaders,
-		body: request.body
+		body: request.body,
+		signal: request.signal
 	};
 	if (request.body) Object.defineProperty(init, "duplex", {
 		value: "half",

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

@@ -1,9 +1,9 @@
 import { isUnknownRecord } from "../utils/record.js";
 import { buildParams, decodeMatchedParams, splitPathnameForRouteMatch } from "../routing/utils.js";
 import { stripBasePath } from "../utils/base-path.js";
+import { extractRawRoutePatternParams, matchRoutePattern } from "../routing/route-pattern.js";
 import { AppElementsWire } from "./app-elements-wire.js";
 import "./app-elements.js";
-import { extractRawRoutePatternParams, matchRoutePattern } from "../routing/route-pattern.js";
 import { createNestedBfcacheSlotSegmentId, deriveBfcacheSegmentIdentity, isNestedBfcacheSlotSegmentId } from "./bfcache-identity.js";
 import { stripRscCacheBustingSearchParam, stripRscSuffix } from "./app-rsc-cache-busting.js";
 import { canonicalizeAppPageParams, resolveAppPagePatternStateKey, resolveAppPageSemanticSegmentStateKey } from "./app-page-segment-state.js";

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

@@ -49,6 +49,11 @@ type AppPageBoundaryRenderCommonOptions<TModule extends AppPageModule = AppPageM
   getFontStyles: () => string[];
   getNavigationContext: () => NavigationContext | null;
   globalErrorModule?: TModule | null;
+  /**
+   * The document may be stored under a query-free key, so its SSR
+   * `useSearchParams()` waits as a cache candidate's does.
+   */
+  isCacheCandidate?: boolean;
   isEdgeRuntime?: boolean;
   isRscRequest: boolean;
   loadSsrHandler: () => Promise<AppPageSsrHandler>;

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

@@ -6,19 +6,20 @@ import "./app-elements.js";
 import DefaultGlobalError from "../shims/default-global-error.js";
 import { ErrorBoundary, GlobalErrorBoundary, SerializedErrorBoundary } from "../shims/error-boundary.js";
 import { LayoutSegmentProvider } from "../shims/layout-segment-context.js";
+import { withUseCacheLayoutMarker } from "../shims/internal/app-page-props-cache-key.js";
 import { MetadataHead, ViewportHead } from "../shims/metadata.js";
 import { resolveAppPageBranchParams, resolveAppPageSegmentParams } from "./app-page-params.js";
 import { stripRscSuffix } from "./app-rsc-cache-busting.js";
 import { buildRscRedirectFlightStream } from "./app-rsc-redirect-flight.js";
 import { bufferAppPageBinaryStream, buildAppPageSpecialErrorResponse, resolveAppPageSpecialError } from "./app-page-execution.js";
-import { resolveActiveParallelRouteHeadInputs, resolveAppPageHead } from "./app-page-head.js";
 import { createAppPageLayoutEntries, createAppPageSourcePage } from "./app-page-route-wiring.js";
+import { createAppPageFontData, createAppPageRscErrorTracker, createAppPageSsrErrorHandler, renderAppPageHtmlResponse } from "./app-page-stream.js";
 import { buildClientHookErrorMessage } from "../shims/client-hook-error.js";
+import { resolveActiveParallelRouteHeadInputs, resolveAppPageHead } from "./app-page-head.js";
 import { resolveHttpAccessFallbackMetadata, resolveHttpAccessFallbackViewport } from "./app-page-http-access-fallback-metadata.js";
 import "./app-rsc-route-matching.js";
 import { renderAppPageBoundaryResponse, resolveAppPageErrorBoundary, resolveAppPageHttpAccessBoundaryModule, wrapAppPageBoundaryElement } from "./app-page-boundary.js";
 import { resolveSlotParamOverrides } from "./app-page-element-builder.js";
-import { createAppPageFontData, createAppPageRscErrorTracker, createAppPageSsrErrorHandler, renderAppPageHtmlResponse } from "./app-page-stream.js";
 import { Fragment, createElement } from "react";
 //#region src/server/app-page-boundary-render.ts
 const DEFAULT_GLOBAL_ERROR_COMPONENT = DefaultGlobalError;
@@ -56,10 +57,10 @@ function wrapRenderedBoundaryElement(options) {
 			});
 		},
 		renderLayout(LayoutComponent, children, asyncParams) {
-			return createElement(LayoutComponent, {
+			return createElement(LayoutComponent, withUseCacheLayoutMarker(LayoutComponent, {
 				children,
 				params: asyncParams
-			});
+			}));
 		},
 		renderLayoutSegmentProvider(segmentMap, children) {
 			return createElement(LayoutSegmentProvider, { segmentMap }, children);
@@ -153,6 +154,7 @@ async function renderAppPageBoundaryElementResponse(options) {
 					clearRequestContext: options.clearRequestContext,
 					fontData,
 					fontLinkHeader: options.buildFontLinkHeader(fontData.preloads),
+					isCacheCandidate: options.isCacheCandidate,
 					isEdgeRuntime: options.isEdgeRuntime,
 					middlewareHeaders: options.middlewareContext.headers,
 					navigationContext: options.getNavigationContext() ?? {

package/dist/server/app-page-cache-finalizer.d.ts

@@ -2,6 +2,7 @@ import { RenderObservation } from "./cache-proof.js";
 import { AppRscRenderMode } from "./app-rsc-render-mode.js";
 import { AppPageRenderObservationState } from "./app-page-render-observation.js";
 import { AppPageCacheSetter } from "./isr-cache.js";
+import { AppPageRscRenderStatus } from "./app-page-rsc-render-status.js";
 //#region src/server/app-page-cache-finalizer.d.ts
 type AppPageDebugLogger = (event: string, detail: string) => void;
 type AppPageRscCacheKeyBuilder = (pathname: string, mountedSlotsHeader?: string | null, renderMode?: AppRscRenderMode, interceptionContext?: string | null, interceptionId?: string | null) => string;
@@ -26,6 +27,8 @@ type FinalizeAppPageCacheabilityEvaluationOptions = {
    * cacheable even when a cacheLife resolves during the render.
    */
   isStaticEligible: boolean;
+  /** An RSC render's status, from its document's shell. */
+  resolveRscRenderStatus?: () => Promise<AppPageRscRenderStatus>;
   revalidateSeconds: number | null;
 };
 type FinalizeAppPageHtmlCacheResponseOptions = {
@@ -53,6 +56,12 @@ type FinalizeAppPageHtmlCacheResponseOptions = {
   isStaticEligible: boolean;
   revalidateSeconds: number | null;
   linkHeader: string | null;
+  /**
+   * The status and headers stored with both entries, for a render that ended
+   * in a special error: 404/403/401, or 307/308 with its `location`.
+   */
+  status?: number;
+  headers?: Record<string, string>;
   waitUntil?: (promise: Promise<void>) => void;
 };
 type ScheduleAppPageRscCacheWriteOptions = {
@@ -73,6 +82,8 @@ type ScheduleAppPageRscCacheWriteOptions = {
   mountedSlotsHeader?: string | null;
   omitPendingDynamicCacheState?: boolean;
   renderMode?: AppRscRenderMode;
+  /** The render's status, from its document's shell. Without it the render is a 200. */
+  resolveRscRenderStatus?: () => Promise<AppPageRscRenderStatus>;
   preserveClientResponseHeaders?: boolean;
   expireSeconds?: number;
   isStaticEligible: boolean;

package/dist/server/app-page-cache-finalizer.js

@@ -10,6 +10,7 @@ import { deferUntilStreamConsumed } from "./defer-until-stream-consumed.js";
 import { markFrameworkLinkHeaders } from "./app-response-header-provenance.js";
 import { hasQueryInvariantRenderProof } from "./cache-proof.js";
 import { createEmptyAppPageRenderObservationState } from "./app-page-render-observation.js";
+import { resolveAppPageRscResponseStatus } from "./app-page-rsc-render-status.js";
 //#region src/server/app-page-cache-finalizer.ts
 function applyPendingDynamicCdnHeaders(headers, tags, options = {}) {
 	const cacheable = headers.get("Cache-Control") ?? "";
@@ -50,6 +51,22 @@ function resolveAppPageCacheControl(options) {
 function appPageCacheControlHeader(cacheControl) {
 	return cacheControl.revalidate === Infinity ? STATIC_CACHE_CONTROL : buildRevalidateCacheControl(cacheControl.revalidate, cacheControl.expire);
 }
+/**
+* The completed response replaces a streamed 200 with the status Next.js sends
+* for the render's special error, and stores that.
+*/
+function applyRscRenderStatus(outcome, renderStatus) {
+	if (renderStatus.kind === "page") return outcome;
+	if (renderStatus.kind === "unstorable") return {
+		cacheable: false,
+		reason: "render ended in a special error Next.js doesn't store"
+	};
+	return {
+		...outcome,
+		status: resolveAppPageRscResponseStatus(renderStatus.status),
+		...renderStatus.headers ? { headers: renderStatus.headers } : {}
+	};
+}
 function finalizeEvaluatedAppPageResponse(response, options) {
 	if (!isRouteCacheabilityEvaluation()) return null;
 	const complete = deferRouteCacheability();
@@ -90,6 +107,14 @@ function finalizeEvaluatedAppPageResponse(response, options) {
 				reason: "render did not produce a cache policy"
 			};
 		}
+		if (outcome.cacheable && options.resolveRscRenderStatus) {
+			const cacheableOutcome = outcome;
+			options.resolveRscRenderStatus().then((renderStatus) => complete(applyRscRenderStatus(cacheableOutcome, renderStatus)), () => complete({
+				cacheable: false,
+				reason: "render status could not be resolved"
+			}));
+			return;
+		}
 		complete(outcome);
 	};
 	if (!response.body) {
@@ -131,15 +156,15 @@ function finalizeAppPageHtmlCacheResponse(response, options) {
 		markFrameworkLinkHeaders(clientResponse.headers, options.linkHeader);
 		return clientResponse;
 	}
-	if (!response.body) return response;
-	const [streamForClient, streamForCache] = response.body.tee();
+	const [streamForClient, streamForCache] = response.body ? response.body.tee() : [null, null];
 	const htmlKey = options.isrHtmlKey(options.cleanPathname);
 	const rscKey = options.isrRscKey(options.cleanPathname, null, void 0, options.interceptionContext, options.interceptionId);
 	const clientHeaders = new Headers(response.headers);
 	if (options.preserveClientResponseHeaders !== true) applyPendingDynamicCdnHeaders(clientHeaders, options.getPageTags(), { omitCacheState: options.omitPendingDynamicCacheState === true });
 	const cachePromise = (async () => {
 		try {
-			let cachedHtml = await readStreamAsText(streamForCache);
+			let cachedHtml = streamForCache ? await readStreamAsText(streamForCache) : "";
+			const rscData = options.capturedRscDataPromise ? await options.capturedRscDataPromise : void 0;
 			if (options.capturedDynamicUsageBeforeContextCleanup?.() === true || options.consumeDynamicUsage()) {
 				options.isrDebug?.("HTML cache write skipped (dynamic usage during render)", htmlKey);
 				return;
@@ -168,18 +193,22 @@ function finalizeAppPageHtmlCacheResponse(response, options) {
 				state: observationState
 			});
 			const linkHeader = options.linkHeader;
+			const status = options.status ?? 200;
 			if (!hasQueryInvariantRenderProof(htmlRenderObservation) || !hasQueryInvariantRenderProof(rscRenderObservation)) {
 				options.isrDebug?.("HTML cache write skipped (searchParams not proven unread)", htmlKey);
 				return;
 			}
-			const writes = [options.isrSet(htmlKey, buildAppPageCacheValue(cachedHtml, void 0, 200, htmlRenderObservation, linkHeader ? { link: linkHeader } : void 0), {
+			const writes = [options.isrSet(htmlKey, buildAppPageCacheValue(cachedHtml, void 0, status, htmlRenderObservation, linkHeader ? {
+				...options.headers,
+				link: linkHeader
+			} : options.headers), {
 				cacheControl,
 				tags: pageTags
 			})];
-			if (options.capturedRscDataPromise) writes.push(options.capturedRscDataPromise.then((rscData) => options.isrSet(rscKey, buildAppPageCacheValue("", rscData, 200, rscRenderObservation), {
+			if (rscData) writes.push(options.isrSet(rscKey, buildAppPageCacheValue("", rscData, status, rscRenderObservation, options.headers), {
 				cacheControl,
 				tags: pageTags
-			})));
+			}));
 			await Promise.all(writes);
 			options.isrDebug?.("HTML cache written", htmlKey);
 		} catch (cacheError) {
@@ -243,7 +272,12 @@ function scheduleAppPageRscCacheWrite(options) {
 				options.isrDebug?.("RSC cache write skipped (searchParams not proven unread)", rscKey);
 				return;
 			}
-			await options.isrSet(rscKey, buildAppPageCacheValue("", rscData, 200, rscRenderObservation), {
+			const renderStatus = await options.resolveRscRenderStatus?.() ?? { kind: "page" };
+			if (renderStatus.kind === "unstorable") {
+				options.isrDebug?.("RSC cache write skipped (unstorable special error)", rscKey);
+				return;
+			}
+			await options.isrSet(rscKey, renderStatus.kind === "special-error" ? buildAppPageCacheValue("", rscData, renderStatus.status, rscRenderObservation, renderStatus.headers) : buildAppPageCacheValue("", rscData, 200, rscRenderObservation), {
 				cacheControl,
 				tags: pageTags
 			});

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

@@ -24,11 +24,18 @@ export type RenderAppPageCacheArtifactsOptions = {
   getNavigationContext: () => NavigationContext | null;
   loadSsrHandler: () => Promise<AppPageSsrHandler>;
   mountedSlotsHeader?: string | null;
+  /** Start mirroring Flight into Next.js's `self.__next_f` once this returns true. */
+  mirrorNextFlight?: () => boolean;
   navigationParams: Record<string, unknown>;
   isCapturedRscError?: (error: unknown) => boolean;
   onError: (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
   onSsrError?: (error: unknown) => unknown;
   reactMaxHeadersLength?: number;
+  /**
+   * Render the document of a special error that rejected the shell, or return
+   * null to fail the render with it.
+   */
+  renderShellSpecialError?: (error: unknown) => Promise<AppPageCacheSpecialErrorDocument | null>;
   renderToReadableStream: (element: AppPageRenderableElement, options: {
     onError: (error: unknown, requestInfo: unknown, errorContext: unknown) => unknown;
   }) => ReadableStream<Uint8Array>;
@@ -37,13 +44,24 @@ export type RenderAppPageCacheArtifactsOptions = {
   waitForAllReady?: boolean;
   isForceStatic?: boolean;
 };
+type AppPageCacheSpecialErrorDocument = {
+  /** Response headers stored with the entries, such as a redirect's `location`. */
+  headers?: Record<string, string>;
+  html: string;
+  /** The renderer's own `Link` header, without middleware's. */
+  linkHeader?: string;
+  status: number;
+};
 export type RenderAppPageCacheArtifactsResult = {
   cacheControl?: CacheControlMetadata;
+  headers?: Record<string, string>;
   html: string;
   htmlRenderObservation: ReturnType<typeof createAppPageRenderObservation>;
   linkHeader?: string;
   rscData?: ArrayBuffer;
   rscRenderObservation?: ReturnType<typeof createAppPageRenderObservation>;
+  /** The status of a render whose shell ended in a special error. */
+  status?: number;
   tags: string[];
   /** The render used a dynamic API, so its output must not be stored. */
   usedDynamicApi: boolean;

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

@@ -26,34 +26,49 @@ async function renderAppPageCacheArtifactsImpl(options, renderSpan) {
 	const rscCapture = teeAppPageRscStreamForCapture(rscStream, options.captureRscData);
 	const capturedRscDataRef = { value: null };
 	const fontPreloads = options.getFontPreloads();
-	const htmlResult = await (await options.loadSsrHandler()).handleSsr(rscCapture.ssrStream, options.getNavigationContext(), {
-		links: options.getFontLinks(),
-		styles: options.getFontStyles(),
-		preloads: fontPreloads
-	}, {
-		basePath: options.basePath,
-		clientTraceMetadata: options.clientTraceMetadata,
-		reactMaxHeadersLength: options.reactMaxHeadersLength,
-		rootParams: options.rootParams,
-		waitForAllReady: options.waitForAllReady,
-		isStaticGeneration: true,
-		isForceStatic: options.isForceStatic,
-		onSsrError: options.onSsrError && options.isCapturedRscError ? createAppPageSsrErrorHandler((error) => {
-			recordAppPageRenderError(renderSpan, error);
-			return options.onSsrError?.(error);
-		}, options.isCapturedRscError) : options.onSsrError ? (error) => {
-			recordAppPageRenderError(renderSpan, error);
-			return options.onSsrError?.(error);
-		} : void 0,
-		...rscCapture.sideStream ? {
-			sideStream: rscCapture.sideStream,
-			capturedRscDataRef
-		} : {}
-	});
-	const htmlStream = isAppSsrRenderResult(htmlResult) ? htmlResult.htmlStream : htmlResult;
-	const reactLinkHeader = isAppSsrRenderResult(htmlResult) ? htmlResult.linkHeader : void 0;
-	const linkHeader = buildAppPageLinkHeader(reactLinkHeader, buildAppPageFontLinkHeader(fontPreloads), options.reactMaxHeadersLength);
-	const html = await readStreamAsText(htmlStream);
+	const ssrHandler = await options.loadSsrHandler();
+	let htmlResult = null;
+	let specialErrorDocument = null;
+	try {
+		htmlResult = await ssrHandler.handleSsr(rscCapture.ssrStream, options.getNavigationContext(), {
+			links: options.getFontLinks(),
+			styles: options.getFontStyles(),
+			preloads: fontPreloads
+		}, {
+			basePath: options.basePath,
+			clientTraceMetadata: options.clientTraceMetadata,
+			reactMaxHeadersLength: options.reactMaxHeadersLength,
+			rootParams: options.rootParams,
+			waitForAllReady: options.waitForAllReady,
+			mirrorNextFlight: options.mirrorNextFlight,
+			isStaticGeneration: true,
+			isForceStatic: options.isForceStatic,
+			onSsrError: options.onSsrError && options.isCapturedRscError ? createAppPageSsrErrorHandler((error) => {
+				recordAppPageRenderError(renderSpan, error);
+				return options.onSsrError?.(error);
+			}, options.isCapturedRscError) : options.onSsrError ? (error) => {
+				recordAppPageRenderError(renderSpan, error);
+				return options.onSsrError?.(error);
+			} : void 0,
+			...rscCapture.sideStream ? {
+				sideStream: rscCapture.sideStream,
+				capturedRscDataRef
+			} : {}
+		});
+	} catch (error) {
+		if (!options.renderShellSpecialError) throw error;
+		await capturedRscDataRef.value?.catch(() => {});
+		specialErrorDocument = await options.renderShellSpecialError(error);
+		if (!specialErrorDocument) throw error;
+	}
+	let html = specialErrorDocument?.html ?? "";
+	let linkHeader = specialErrorDocument?.linkHeader;
+	if (htmlResult) {
+		const htmlStream = isAppSsrRenderResult(htmlResult) ? htmlResult.htmlStream : htmlResult;
+		const reactLinkHeader = isAppSsrRenderResult(htmlResult) ? htmlResult.linkHeader : void 0;
+		linkHeader = buildAppPageLinkHeader(reactLinkHeader, buildAppPageFontLinkHeader(fontPreloads), options.reactMaxHeadersLength);
+		html = await readStreamAsText(htmlStream);
+	}
 	let rscData;
 	if (options.captureRscData) {
 		const capturedPromise = capturedRscDataRef.value;
@@ -65,24 +80,29 @@ async function renderAppPageCacheArtifactsImpl(options, renderSpan) {
 	const observationState = consumeAppPageRenderObservationState();
 	consumeInvalidDynamicUsageError();
 	const usedDynamicApi = consumeDynamicUsage() || isRenderDynamicLatched();
+	const htmlRenderObservation = createAppPageRenderObservation({
+		boundaryOutcome: { kind: "success" },
+		cacheability: "public",
+		cacheTags: tags,
+		cleanPathname: options.cleanPathname,
+		completeness: "complete",
+		output: createAppPageHtmlOutputScope({
+			element: options.element,
+			renderEpoch: null,
+			rootBoundaryId: null,
+			routePattern: options.route.pattern
+		}),
+		params: options.navigationParams,
+		state: observationState
+	});
 	const result = {
 		html,
-		htmlRenderObservation: createAppPageRenderObservation({
-			boundaryOutcome: { kind: "success" },
-			cacheability: "public",
-			cacheTags: tags,
-			cleanPathname: options.cleanPathname,
-			completeness: "complete",
-			output: createAppPageHtmlOutputScope({
-				element: options.element,
-				renderEpoch: null,
-				rootBoundaryId: null,
-				routePattern: options.route.pattern
-			}),
-			params: options.navigationParams,
-			state: observationState
-		}),
+		htmlRenderObservation,
 		...linkHeader ? { linkHeader } : {},
+		...specialErrorDocument ? {
+			headers: specialErrorDocument.headers,
+			status: specialErrorDocument.status
+		} : {},
 		tags,
 		usedDynamicApi,
 		cacheControl: typeof cacheLife?.revalidate === "number" ? {