vinext 0.1.1 → 0.1.2

package/dist/server/middleware.js

@@ -85,6 +85,7 @@ async function runMiddleware(runner, middlewarePath, request, i18nConfig, basePa
 	return runGeneratedMiddleware({
 		basePath,
 		filePath: middlewarePath,
+		hadBasePath: true,
 		i18nConfig,
 		includeErrorDetails: process.env.NODE_ENV !== "production",
 		isDataRequest,

package/dist/server/navigation-planner.d.ts

@@ -114,6 +114,63 @@ type FlightResultV0 = {
   href: string;
   targetSnapshot: RouteSnapshotV0;
 };
+type RscFetchResultSource = "cached" | "live";
+type RscFetchResultFactsV0 = {
+  source: RscFetchResultSource;
+  currentHref: string;
+  origin: string;
+  effectiveHistoryUpdateMode: "push" | "replace";
+  redirectDepth: number;
+  requestPreviousNextUrl: string | null;
+  clientCompatibilityId: string | null;
+  responseOk: boolean;
+  isRscContentType: boolean;
+  hasBody: boolean;
+  compatibilityIdHeader: string | null;
+  responseUrl: string | null;
+  streamedRedirectTarget: string | null;
+};
+type RscRedirectFollowV0 = {
+  href: string;
+  historyUpdateMode: "push" | "replace";
+  previousNextUrl: string | null;
+  redirectDepth: number;
+};
+type RscFetchResultHardNavReason = "invalidRscPayload" | "rscCompatibilityMismatch" | "externalRedirectTarget" | "redirectDepthExhausted" | "streamedRedirectLoop";
+type RscFetchResultDecisionV0 = {
+  kind: "proceedToCommit";
+  discardBody: false;
+  trace: NavigationTrace;
+} | {
+  kind: "followRedirect";
+  discardBody: boolean;
+  redirect: RscRedirectFollowV0;
+  trace: NavigationTrace;
+} | {
+  kind: "hardNavigate";
+  discardBody: boolean;
+  url: string;
+  reason: RscFetchResultHardNavReason;
+  trace: NavigationTrace;
+};
+type EarlyNavigationIntentFactsV0 = {
+  basePath: string;
+  currentHref: string;
+  mode: "push" | "replace";
+  scroll: boolean;
+  targetHref: string;
+};
+type EarlyNavigationIntentDecisionV0 = {
+  kind: "sameDocumentScroll";
+  hash: string;
+  mode: "push" | "replace";
+  scroll: boolean;
+  trace: NavigationTrace;
+} | {
+  kind: "flightNavigation";
+  bypassNavigationCache: boolean;
+  trace: NavigationTrace;
+};
 type NavigationPlannerInput = {
   routeManifest: RouteManifest | null;
   state: NavigationPlannerStateV0;
@@ -122,6 +179,8 @@ type NavigationPlannerInput = {
 type AcceptedCacheEntryReuseDecision = Extract<CacheEntryReuseDecision, {
   canReuse: true;
 }>;
+declare function classifyRscFetchResult(facts: RscFetchResultFactsV0): RscFetchResultDecisionV0;
+declare function classifyEarlyNavigationIntent(facts: EarlyNavigationIntentFactsV0): EarlyNavigationIntentDecisionV0;
 declare function classifyRootBoundaryTransition(currentRootBoundaryId: string | null, nextRootBoundaryId: string | null): RootBoundaryTransition;
 declare function resolveSameLayoutAncestorPersistence(currentSnapshot: RouteSnapshotV0, targetSnapshot: RouteSnapshotV0): readonly string[];
 declare function resolveMountedParallelSlotPersistence(currentSnapshot: RouteSnapshotV0, targetSnapshot: RouteSnapshotV0): readonly string[];
@@ -143,6 +202,8 @@ declare function resolveDefaultOrUnmatchedSlotPersistenceForLayouts(options: {
 }): readonly string[];
 declare function planNavigation(input: NavigationPlannerInput): NavigationDecisionV0;
 declare const navigationPlanner: {
+  classifyEarlyNavigationIntent: typeof classifyEarlyNavigationIntent;
+  classifyRscFetchResult: typeof classifyRscFetchResult;
   classifyRootBoundaryTransition: typeof classifyRootBoundaryTransition;
   plan: typeof planNavigation;
   resolveCurrentRootBoundaryElementPersistence: typeof resolveCurrentRootBoundaryElementPersistence;
@@ -150,4 +211,4 @@ declare const navigationPlanner: {
   resolveSameLayoutAncestorPersistence: typeof resolveSameLayoutAncestorPersistence;
 };
 //#endregion
-export { FlightResultV0, InterceptionSnapshotV0, MountedParallelSlotSnapshotV0, NavigationDecisionV0, NavigationEvent, NavigationPlannerInput, NavigationPlannerStateV0, OperationLane, OperationToken, ParallelSlotBindingSnapshotV0, RefreshScope, RootBoundaryTransition, RouteSnapshotV0, TraverseDirection, navigationPlanner, resolveDefaultOrUnmatchedSlotPersistenceForLayouts };
+export { EarlyNavigationIntentDecisionV0, EarlyNavigationIntentFactsV0, FlightResultV0, InterceptionSnapshotV0, MountedParallelSlotSnapshotV0, NavigationDecisionV0, NavigationEvent, NavigationPlannerInput, NavigationPlannerStateV0, OperationLane, OperationToken, ParallelSlotBindingSnapshotV0, RefreshScope, RootBoundaryTransition, RouteSnapshotV0, RscFetchResultDecisionV0, RscFetchResultFactsV0, TraverseDirection, navigationPlanner, resolveDefaultOrUnmatchedSlotPersistenceForLayouts };

package/dist/server/navigation-planner.js

@@ -1,7 +1,10 @@
 import { splitPathnameForRouteMatch } from "../routing/utils.js";
+import { stripBasePath } from "../utils/base-path.js";
 import { matchRoutePattern, matchRoutePatternPrefix, matchRoutePatternWithOptionalDynamicSegments } from "../routing/route-pattern.js";
 import { compareAppElementsSlotIds } from "./app-elements-wire.js";
 import "./app-elements.js";
+import { resolveHardNavigationTargetFromRscResponse, resolveRscCompatibilityNavigationDecision } from "./app-rsc-cache-busting.js";
+import { resolveRscRedirectLifecycleHop, resolveStreamedRscRedirectLifecycleHop } from "./app-browser-rsc-redirect.js";
 import { NavigationTraceReasonCodes, createNavigationLifecycleTraceFields, createNavigationTrace } from "./navigation-trace.js";
 //#region src/server/navigation-planner.ts
 const ROUTE_INTERCEPTION_CONTEXT_SEPARATOR = "\0";
@@ -27,6 +30,189 @@ function getRequestedWorkTargetHref(work) {
 		default: throw new Error("[vinext] Unknown requested navigation work: " + String(work));
 	}
 }
+function createRscFetchResultTraceFields(facts, fields = {}) {
+	return {
+		fetchResultSource: facts.source,
+		...fields
+	};
+}
+function createRscFetchResultHardNavigationDecision(options) {
+	return {
+		discardBody: options.discardBody,
+		kind: "hardNavigate",
+		reason: options.reason,
+		trace: createNavigationTrace(options.reasonCode, createRscFetchResultTraceFields(options.facts, {
+			...options.redirectSignal !== void 0 ? { redirectSignal: options.redirectSignal } : {},
+			redirectDepth: options.facts.redirectDepth,
+			targetHref: options.url
+		})),
+		url: options.url
+	};
+}
+function createRscFetchResultFollowRedirectDecision(options) {
+	return {
+		discardBody: options.discardBody,
+		kind: "followRedirect",
+		redirect: options.redirect,
+		trace: createNavigationTrace(NavigationTraceReasonCodes.redirectFollow, createRscFetchResultTraceFields(options.facts, {
+			redirectDepth: options.redirect.redirectDepth,
+			redirectSignal: options.redirectSignal,
+			targetHref: options.redirect.href
+		}))
+	};
+}
+function mapRscRedirectTerminalReason(reason) {
+	switch (reason) {
+		case "externalRedirect": return {
+			hardNavigationReason: "externalRedirectTarget",
+			traceReasonCode: NavigationTraceReasonCodes.redirectTerminalExternal
+		};
+		case "maxRedirectsExceeded": return {
+			hardNavigationReason: "redirectDepthExhausted",
+			traceReasonCode: NavigationTraceReasonCodes.redirectTerminalDepth
+		};
+		default: throw new Error("[vinext] Unknown RSC redirect terminal reason: " + String(reason));
+	}
+}
+function classifyRscFetchResult(facts) {
+	if (!facts.responseOk || !facts.isRscContentType || !facts.hasBody) {
+		const url = resolveHardNavigationTargetFromRscResponse(facts.responseUrl, facts.currentHref, facts.origin);
+		return createRscFetchResultHardNavigationDecision({
+			discardBody: false,
+			facts,
+			reason: "invalidRscPayload",
+			reasonCode: NavigationTraceReasonCodes.invalidRscPayload,
+			url
+		});
+	}
+	const compatibilityDecision = resolveRscCompatibilityNavigationDecision({
+		clientCompatibilityId: facts.clientCompatibilityId,
+		currentHref: facts.currentHref,
+		origin: facts.origin,
+		responseCompatibilityId: facts.compatibilityIdHeader,
+		responseUrl: facts.responseUrl
+	});
+	if (compatibilityDecision.kind === "hard-navigate") return createRscFetchResultHardNavigationDecision({
+		discardBody: false,
+		facts,
+		reason: "rscCompatibilityMismatch",
+		reasonCode: NavigationTraceReasonCodes.rscCompatibilityMismatch,
+		url: compatibilityDecision.hardNavigationTarget
+	});
+	if (facts.responseUrl !== null) {
+		const redirectDecision = resolveRscRedirectLifecycleHop({
+			currentHref: facts.currentHref,
+			historyUpdateMode: facts.effectiveHistoryUpdateMode,
+			origin: facts.origin,
+			redirectDepth: facts.redirectDepth,
+			requestPreviousNextUrl: facts.requestPreviousNextUrl,
+			responseUrl: facts.responseUrl
+		});
+		if (redirectDecision.kind === "terminal-hard-navigation") {
+			const terminalReason = mapRscRedirectTerminalReason(redirectDecision.reason);
+			return createRscFetchResultHardNavigationDecision({
+				discardBody: false,
+				facts,
+				reason: terminalReason.hardNavigationReason,
+				reasonCode: terminalReason.traceReasonCode,
+				redirectSignal: "response-url",
+				url: redirectDecision.href
+			});
+		}
+		if (redirectDecision.kind === "follow") return createRscFetchResultFollowRedirectDecision({
+			discardBody: false,
+			facts,
+			redirect: {
+				href: redirectDecision.href,
+				historyUpdateMode: facts.effectiveHistoryUpdateMode,
+				previousNextUrl: redirectDecision.previousNextUrl,
+				redirectDepth: redirectDecision.redirectDepth
+			},
+			redirectSignal: "response-url"
+		});
+	}
+	if (facts.streamedRedirectTarget !== null) {
+		const redirectDecision = resolveStreamedRscRedirectLifecycleHop({
+			currentHref: facts.currentHref,
+			historyUpdateMode: facts.effectiveHistoryUpdateMode,
+			origin: facts.origin,
+			redirectDepth: facts.redirectDepth,
+			requestPreviousNextUrl: facts.requestPreviousNextUrl,
+			streamedRedirectTarget: facts.streamedRedirectTarget
+		});
+		if (redirectDecision.kind === "terminal-hard-navigation") {
+			const terminalReason = mapRscRedirectTerminalReason(redirectDecision.reason);
+			return createRscFetchResultHardNavigationDecision({
+				discardBody: true,
+				facts,
+				reason: terminalReason.hardNavigationReason,
+				reasonCode: terminalReason.traceReasonCode,
+				redirectSignal: "streamed-header",
+				url: redirectDecision.href
+			});
+		}
+		if (redirectDecision.kind === "follow") return createRscFetchResultFollowRedirectDecision({
+			discardBody: true,
+			facts,
+			redirect: {
+				href: redirectDecision.href,
+				historyUpdateMode: facts.effectiveHistoryUpdateMode,
+				previousNextUrl: redirectDecision.previousNextUrl,
+				redirectDepth: redirectDecision.redirectDepth
+			},
+			redirectSignal: "streamed-header"
+		});
+		return createRscFetchResultHardNavigationDecision({
+			discardBody: true,
+			facts,
+			reason: "streamedRedirectLoop",
+			reasonCode: NavigationTraceReasonCodes.streamedRedirectLoop,
+			redirectSignal: "streamed-header",
+			url: redirectDecision.href
+		});
+	}
+	return {
+		discardBody: false,
+		kind: "proceedToCommit",
+		trace: createNavigationTrace(NavigationTraceReasonCodes.proceedToCommit, createRscFetchResultTraceFields(facts))
+	};
+}
+function createEarlyNavigationIntentTrace(reasonCode, facts) {
+	return createNavigationTrace(reasonCode, { targetHref: facts.targetHref });
+}
+function classifyEarlyNavigationIntent(facts) {
+	let current;
+	let next;
+	try {
+		current = new URL(facts.currentHref);
+		next = new URL(facts.targetHref, facts.currentHref);
+	} catch {
+		return {
+			bypassNavigationCache: false,
+			kind: "flightNavigation",
+			trace: createEarlyNavigationIntentTrace(NavigationTraceReasonCodes.crossDocumentFlight, facts)
+		};
+	}
+	const samePathname = current.origin === next.origin && stripBasePath(current.pathname, facts.basePath) === stripBasePath(next.pathname, facts.basePath);
+	const sameSearch = current.searchParams.toString() === next.searchParams.toString();
+	if (samePathname && sameSearch && next.hash !== "") return {
+		hash: next.hash,
+		kind: "sameDocumentScroll",
+		mode: facts.mode,
+		scroll: facts.scroll,
+		trace: createEarlyNavigationIntentTrace(NavigationTraceReasonCodes.sameDocumentScroll, facts)
+	};
+	if (samePathname && !sameSearch) return {
+		bypassNavigationCache: true,
+		kind: "flightNavigation",
+		trace: createEarlyNavigationIntentTrace(NavigationTraceReasonCodes.samePageSearch, facts)
+	};
+	return {
+		bypassNavigationCache: false,
+		kind: "flightNavigation",
+		trace: createEarlyNavigationIntentTrace(NavigationTraceReasonCodes.crossDocumentFlight, facts)
+	};
+}
 function createSnapshotRouteTopology(snapshot) {
 	return {
 		layoutIds: snapshot.layoutIds,
@@ -495,6 +681,8 @@ function planNavigation(input) {
 	}
 }
 const navigationPlanner = {
+	classifyEarlyNavigationIntent,
+	classifyRscFetchResult,
 	classifyRootBoundaryTransition,
 	plan: planNavigation,
 	resolveCurrentRootBoundaryElementPersistence,

package/dist/server/navigation-trace.d.ts

@@ -4,6 +4,8 @@ type NavigationTraceSchemaVersion = 0;
 declare const NavigationTraceReasonCodes: {
   cacheProofRejected: "NC_CACHE_REJECT";
   commitCurrent: "NC_COMMIT";
+  crossDocumentFlight: "NC_CROSS_DOC_FLIGHT";
+  invalidRscPayload: "NC_RSC_INVALID";
   interceptedCommitCurrent: "NC_INTERCEPT_COMMIT";
   interceptedRejectedIncompatibleRoot: "NC_INTERCEPT_REJECT_ROOT";
   interceptedRejectedMissingProof: "NC_INTERCEPT_REJECT_MISSING_PROOF";
@@ -12,10 +14,18 @@ declare const NavigationTraceReasonCodes: {
   interceptedRejectedUndeclaredTopology: "NC_INTERCEPT_REJECT_GRAPH";
   interceptedRejectedUnknownSource: "NC_INTERCEPT_REJECT_SOURCE";
   prefetchOnly: "NC_PREFETCH_ONLY";
+  proceedToCommit: "NC_RSC_PROCEED";
+  redirectFollow: "NC_RSC_REDIRECT_FOLLOW";
+  redirectTerminalDepth: "NC_RSC_REDIRECT_DEPTH";
+  redirectTerminalExternal: "NC_RSC_REDIRECT_EXTERNAL";
   requestWork: "NC_REQUEST";
   rootBoundaryChanged: "NC_ROOT";
   rootBoundaryUnknown: "NC_ROOT_UNKNOWN";
+  rscCompatibilityMismatch: "NC_RSC_COMPAT_MISMATCH";
+  sameDocumentScroll: "NC_SAME_DOC_SCROLL";
+  samePageSearch: "NC_SAME_PAGE_SEARCH";
   staleOperation: "NC_STALE";
+  streamedRedirectLoop: "NC_RSC_STREAMED_REDIRECT_LOOP";
 };
 declare const NavigationTraceTransactionCodes: {
   hardNavigate: "NT_HARD_NAVIGATE";
@@ -25,7 +35,7 @@ declare const NavigationTraceTransactionCodes: {
 type NavigationTraceReasonCode = (typeof NavigationTraceReasonCodes)[keyof typeof NavigationTraceReasonCodes];
 type NavigationTraceTransactionCode = (typeof NavigationTraceTransactionCodes)[keyof typeof NavigationTraceTransactionCodes];
 type NavigationTraceCode = NavigationTraceReasonCode | NavigationTraceTransactionCode;
-type NavigationTraceFieldName = "activeNavigationId" | "cacheProofCode" | "cacheProofMode" | "cacheProofReuseClass" | "cacheProofScope" | "currentRootLayoutTreePath" | "currentVisibleCommitVersion" | "nextRootLayoutTreePath" | "eventKind" | "operationLane" | "pendingOperationId" | "startedVisibleCommitVersion" | "startedNavigationId" | "targetHref" | "traverseDirection";
+type NavigationTraceFieldName = "activeNavigationId" | "cacheProofCode" | "cacheProofMode" | "cacheProofReuseClass" | "cacheProofScope" | "currentRootLayoutTreePath" | "currentVisibleCommitVersion" | "nextRootLayoutTreePath" | "eventKind" | "fetchResultSource" | "operationLane" | "pendingOperationId" | "redirectDepth" | "redirectSignal" | "startedVisibleCommitVersion" | "startedNavigationId" | "targetHref" | "traverseDirection";
 type NavigationTraceFieldValue = string | number | boolean | null;
 type NavigationTraceFields = Readonly<Partial<Record<NavigationTraceFieldName, NavigationTraceFieldValue>>>;
 type NavigationTraceEntry = Readonly<{

package/dist/server/navigation-trace.js

@@ -3,6 +3,8 @@ const NAVIGATION_TRACE_SCHEMA_VERSION = 0;
 const NavigationTraceReasonCodes = {
 	cacheProofRejected: "NC_CACHE_REJECT",
 	commitCurrent: "NC_COMMIT",
+	crossDocumentFlight: "NC_CROSS_DOC_FLIGHT",
+	invalidRscPayload: "NC_RSC_INVALID",
 	interceptedCommitCurrent: "NC_INTERCEPT_COMMIT",
 	interceptedRejectedIncompatibleRoot: "NC_INTERCEPT_REJECT_ROOT",
 	interceptedRejectedMissingProof: "NC_INTERCEPT_REJECT_MISSING_PROOF",
@@ -11,10 +13,18 @@ const NavigationTraceReasonCodes = {
 	interceptedRejectedUndeclaredTopology: "NC_INTERCEPT_REJECT_GRAPH",
 	interceptedRejectedUnknownSource: "NC_INTERCEPT_REJECT_SOURCE",
 	prefetchOnly: "NC_PREFETCH_ONLY",
+	proceedToCommit: "NC_RSC_PROCEED",
+	redirectFollow: "NC_RSC_REDIRECT_FOLLOW",
+	redirectTerminalDepth: "NC_RSC_REDIRECT_DEPTH",
+	redirectTerminalExternal: "NC_RSC_REDIRECT_EXTERNAL",
 	requestWork: "NC_REQUEST",
 	rootBoundaryChanged: "NC_ROOT",
 	rootBoundaryUnknown: "NC_ROOT_UNKNOWN",
-	staleOperation: "NC_STALE"
+	rscCompatibilityMismatch: "NC_RSC_COMPAT_MISMATCH",
+	sameDocumentScroll: "NC_SAME_DOC_SCROLL",
+	samePageSearch: "NC_SAME_PAGE_SEARCH",
+	staleOperation: "NC_STALE",
+	streamedRedirectLoop: "NC_RSC_STREAMED_REDIRECT_LOOP"
 };
 const NavigationTraceTransactionCodes = {
 	hardNavigate: "NT_HARD_NAVIGATE",

package/dist/server/normalize-path.d.ts

@@ -1,12 +1,4 @@
 //#region src/server/normalize-path.d.ts
-/**
- * Re-encode path delimiter characters that were decoded by decodeURIComponent.
- * After decoding a URL segment, characters like / # ? \ need to be re-encoded
- * so they don't change the path structure.
- *
- * Ported from Next.js: packages/next/src/shared/lib/router/utils/escape-path-delimiters.ts
- * https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/escape-path-delimiters.ts
- */
 declare function escapePathDelimiters(segment: string, escapeEncoded?: boolean): string;
 /**
  * Decode a URL pathname segment-by-segment, preserving encoded path delimiters.

package/dist/server/normalize-path.js

@@ -7,8 +7,10 @@
 * Ported from Next.js: packages/next/src/shared/lib/router/utils/escape-path-delimiters.ts
 * https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/escape-path-delimiters.ts
 */
+const PATH_DELIMITERS_RE = /([/#?])/gi;
+const PATH_DELIMITERS_ENCODED_RE = /([/#?]|%(2f|23|3f|5c))/gi;
 function escapePathDelimiters(segment, escapeEncoded) {
-	return segment.replace(new RegExp(`([/#?]${escapeEncoded ? "|%(2f|23|3f|5c)" : ""})`, "gi"), (char) => encodeURIComponent(char));
+	return segment.replace(escapeEncoded ? PATH_DELIMITERS_ENCODED_RE : PATH_DELIMITERS_RE, (char) => encodeURIComponent(char));
 }
 /**
 * Decode a URL pathname segment-by-segment, preserving encoded path delimiters.

package/dist/server/otel-tracer-extension.d.ts

@@ -0,0 +1,45 @@
+//#region src/server/otel-tracer-extension.d.ts
+/**
+ * OpenTelemetry tracer provider extension for Cache Components.
+ *
+ * When `cacheComponents: true` is enabled in next.config, component renders
+ * go through multiple phases (warmup → resume). During these phases, the
+ * `workUnitAsyncStorage` carries a prerender or cache store. Without this
+ * extension, calls to `tracer.startSpan()` / `tracer.startActiveSpan()` from
+ * inside user RSC code would inherit that prerender context, causing:
+ *
+ *  1. Spans to reuse the same trace ID across requests (the frozen prerender
+ *     context bleeds into the runtime resume render).
+ *  2. Spans not being created at all during fallback resume (the work unit
+ *     context gates span creation in some OTel SDK implementations).
+ *
+ * The fix mirrors Next.js's `instrumentation-node-extensions.ts`:
+ *  - Wrap `tracer.startSpan` to exit `workUnitAsyncStorage` before creating
+ *    the span, ensuring a clean context for span ID generation.
+ *  - Wrap `tracer.startActiveSpan` similarly and re-enter the work unit store
+ *    for the callback, so that the callback runs with the correct request
+ *    context restored.
+ *
+ * This extension is intentionally a no-op when:
+ *  - `@opentelemetry/api` is not installed (graceful degradation).
+ *  - No OTel tracer provider has been registered (provider is the noop provider).
+ *  - `workUnitAsyncStorage` has no active store (non-render contexts).
+ *
+ * References:
+ *  - packages/next/src/server/lib/router-utils/instrumentation-node-extensions.ts
+ *  - https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/router-utils/instrumentation-node-extensions.ts
+ */
+/**
+ * Extend the registered OTel tracer provider so that `startSpan` and
+ * `startActiveSpan` exit the `workUnitAsyncStorage` context before creating
+ * spans. This prevents the prerender/cache work unit store from leaking into
+ * span ID generation during Cache Component fallback resumes.
+ *
+ * Safe to call multiple times — subsequent calls are no-ops once the provider
+ * has been wrapped.
+ *
+ * Must only be called in Node.js environments (not Edge runtime).
+ */
+declare function extendTracerProviderForCacheComponents(): void;
+//#endregion
+export { extendTracerProviderForCacheComponents };

package/dist/server/otel-tracer-extension.js

@@ -0,0 +1,89 @@
+import { workUnitAsyncStorage } from "../shims/internal/work-unit-async-storage.js";
+//#region src/server/otel-tracer-extension.ts
+/**
+* OpenTelemetry tracer provider extension for Cache Components.
+*
+* When `cacheComponents: true` is enabled in next.config, component renders
+* go through multiple phases (warmup → resume). During these phases, the
+* `workUnitAsyncStorage` carries a prerender or cache store. Without this
+* extension, calls to `tracer.startSpan()` / `tracer.startActiveSpan()` from
+* inside user RSC code would inherit that prerender context, causing:
+*
+*  1. Spans to reuse the same trace ID across requests (the frozen prerender
+*     context bleeds into the runtime resume render).
+*  2. Spans not being created at all during fallback resume (the work unit
+*     context gates span creation in some OTel SDK implementations).
+*
+* The fix mirrors Next.js's `instrumentation-node-extensions.ts`:
+*  - Wrap `tracer.startSpan` to exit `workUnitAsyncStorage` before creating
+*    the span, ensuring a clean context for span ID generation.
+*  - Wrap `tracer.startActiveSpan` similarly and re-enter the work unit store
+*    for the callback, so that the callback runs with the correct request
+*    context restored.
+*
+* This extension is intentionally a no-op when:
+*  - `@opentelemetry/api` is not installed (graceful degradation).
+*  - No OTel tracer provider has been registered (provider is the noop provider).
+*  - `workUnitAsyncStorage` has no active store (non-render contexts).
+*
+* References:
+*  - packages/next/src/server/lib/router-utils/instrumentation-node-extensions.ts
+*  - https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/router-utils/instrumentation-node-extensions.ts
+*/
+const extendedProviders = /* @__PURE__ */ new WeakSet();
+const USE_CACHE_FUNCTION_SYMBOL = Symbol.for("vinext.useCacheFunction");
+function isUseCacheFn(fn) {
+	return typeof fn === "function" && fn[USE_CACHE_FUNCTION_SYMBOL] === true;
+}
+/**
+* Extend the registered OTel tracer provider so that `startSpan` and
+* `startActiveSpan` exit the `workUnitAsyncStorage` context before creating
+* spans. This prevents the prerender/cache work unit store from leaking into
+* span ID generation during Cache Component fallback resumes.
+*
+* Safe to call multiple times — subsequent calls are no-ops once the provider
+* has been wrapped.
+*
+* Must only be called in Node.js environments (not Edge runtime).
+*/
+function extendTracerProviderForCacheComponents() {
+	let api;
+	try {
+		const req = globalThis.require;
+		if (typeof req === "function") api = req("@opentelemetry/api");
+	} catch {
+		return;
+	}
+	if (!api) return;
+	const provider = api.trace.getTracerProvider();
+	if (!provider || typeof provider.getTracer !== "function") return;
+	if (extendedProviders.has(provider)) return;
+	extendedProviders.add(provider);
+	const originalGetTracer = provider.getTracer.bind(provider);
+	const wrappedTracers = /* @__PURE__ */ new WeakSet();
+	provider.getTracer = (...args) => {
+		const tracer = originalGetTracer(...args);
+		if (!tracer || wrappedTracers.has(tracer)) return tracer;
+		const originalStartSpan = tracer.startSpan;
+		if (typeof originalStartSpan === "function") tracer.startSpan = (...startSpanArgs) => workUnitAsyncStorage.exit(() => originalStartSpan.apply(tracer, startSpanArgs));
+		const originalStartActiveSpan = tracer.startActiveSpan;
+		if (typeof originalStartActiveSpan === "function") tracer.startActiveSpan = (...startActiveSpanArgs) => {
+			const workUnitStore = workUnitAsyncStorage.getStore();
+			if (!workUnitStore) return originalStartActiveSpan.apply(tracer, startActiveSpanArgs);
+			let fnIdx = 0;
+			if (startActiveSpanArgs.length === 2 && typeof startActiveSpanArgs[1] === "function") fnIdx = 1;
+			else if (startActiveSpanArgs.length === 3 && typeof startActiveSpanArgs[2] === "function") fnIdx = 2;
+			else if (startActiveSpanArgs.length > 3 && typeof startActiveSpanArgs[3] === "function") fnIdx = 3;
+			if (fnIdx > 0) {
+				const originalFn = startActiveSpanArgs[fnIdx];
+				if (isUseCacheFn(originalFn)) console.error("A Cache Function (`use cache`) was passed to startActiveSpan which means it will receive a Span argument with a possibly random ID on every invocation leading to cache misses. Provide a wrapping function around the Cache Function that does not forward the Span argument to avoid this issue.");
+				startActiveSpanArgs[fnIdx] = (...cbArgs) => workUnitAsyncStorage.run(workUnitStore, originalFn, ...cbArgs);
+			}
+			return workUnitAsyncStorage.exit(() => originalStartActiveSpan.apply(tracer, startActiveSpanArgs));
+		};
+		wrappedTracers.add(tracer);
+		return tracer;
+	};
+}
+//#endregion
+export { extendTracerProviderForCacheComponents };

package/dist/server/pages-api-route.d.ts

@@ -12,8 +12,7 @@ type PagesApiRouteConfig = {
    * `bodyParser: false` is critical for webhook handlers (Stripe, GitHub,
    * Slack, etc.) that need to read the raw bytes to verify an HMAC
    * signature. With it set, `req.body` is left undefined and the raw stream
-   * is exposed on `req.body` as a Web `ReadableStream<Uint8Array>` so user
-   * code can consume it.
+   * remains available through the Node-readable request object.
    *
    * @see https://nextjs.org/docs/pages/building-your-application/routing/api-routes#custom-config
    */
@@ -22,9 +21,21 @@ type PagesApiRouteConfig = {
       sizeLimit?: string | number;
     };
     responseLimit?: boolean | string | number;
+    /**
+     * `externalResolver: true` declares that the response is sent by an
+     * external resolver (e.g. express/connect proxy middleware) that may
+     * complete after the handler's promise settles. Next.js uses it to
+     * suppress the "API resolved without sending a response" dev warning;
+     * vinext additionally uses it to suppress the auto-`end()` safety net,
+     * which would otherwise resolve an empty response before the external
+     * resolver writes.
+     *
+     * @see https://nextjs.org/docs/pages/building-your-application/routing/api-routes#custom-config
+     */
+    externalResolver?: boolean;
   };
 };
-type PagesNodeApiRouteHandler = (req: PagesReqResRequest, res: PagesReqResResponse) => void | Promise<void>;
+type PagesNodeApiRouteHandler = (req: PagesReqResRequest, res: PagesReqResResponse) => unknown;
 type PagesEdgeApiRouteHandler = (request: Request) => Response | Promise<Response>;
 type PagesApiRouteModule = {
   /**

package/dist/server/pages-api-route.js

@@ -43,8 +43,13 @@ async function _handlePagesApiRoute(options) {
 			request: options.request,
 			url: options.url
 		});
+		let resWasPiped = false;
+		res.once("pipe", () => {
+			resWasPiped = true;
+		});
+		const externalResolver = route.module.config?.api?.externalResolver || false;
 		await route.module.default(req, res);
-		res.end();
+		if (!externalResolver && !resWasPiped && !res.headersSent) res.end();
 		return await responsePromise;
 	} catch (error) {
 		if (error instanceof PagesBodyParseError) return new Response(error.message, {

package/dist/server/pages-asset-tags.d.ts

@@ -23,11 +23,14 @@ declare function resolveSsrManifest(manifest: Record<string, string[]> | null |
  */
 declare function getManifestFilesForModule(manifest: Record<string, string[]> | null | undefined, moduleId: string | null | undefined): string[] | null;
 /**
- * Find the first `.js` file in the manifest for `moduleId` and return its
- * URL-path form (with a leading `/`). Used to resolve the hydration URL for
- * the matched page or the `_app` module.
+ * Find the first `.js` file in the manifest for `moduleId` and return the URL it
+ * is actually SERVED from. Used to resolve the client-navigation / hydration URL
+ * for the matched page or the `_app` module (it is `import()`ed on the client),
+ * so it must point at the served location: `assetPrefix` replaces `basePath` for
+ * asset URLs. SSR-manifest values are base-anchored; re-anchor under any
+ * configured `assetPrefix` (default `""` keeps the legacy `"/" + file`).
  */
-declare function resolveClientModuleUrl(manifest: Record<string, string[]> | null | undefined, moduleId: string | null | undefined): string | undefined;
+declare function resolveClientModuleUrl(manifest: Record<string, string[]> | null | undefined, moduleId: string | null | undefined, basePath?: string, assetPrefix?: string): string | undefined;
 type CollectAssetTagsOptions = {
   /**
    * SSR manifest mapping module file paths to their associated asset list.
@@ -46,6 +49,14 @@ type CollectAssetTagsOptions = {
    * default.
    */
   disableOptimizedLoading: boolean;
+  /**
+   * Configured `basePath` / `assetPrefix`. SSR-manifest values are base-anchored
+   * (needed for the lazy-chunk membership test), but the EMITTED href must point
+   * where the asset is actually served — `assetPrefix` replaces `basePath` for
+   * asset URLs. Default `""` (both unset) keeps the legacy `"/" + value` href.
+   */
+  basePath?: string;
+  assetPrefix?: string;
 };
 /**
  * Build the HTML `<link>` and `<script>` tag string for the SSR response.