vinext 0.1.0 → 0.1.2

package/dist/server/pages-readiness.d.ts

@@ -0,0 +1,36 @@
+import { VinextNextData } from "../client/vinext-next-data.js";
+import { PagesPageModule } from "./pages-page-data.js";
+
+//#region src/server/pages-readiness.d.ts
+/**
+ * Shared Pages Router readiness modeling.
+ *
+ * The initial `router.isReady` value for the `next/navigation` compat hooks is
+ * derived from the page/_app data-fetching exports plus the configured-rewrites
+ * flag, serialized into `__NEXT_DATA__`. The dev SSR handler and the production
+ * Pages page handler must compute this identically so server HTML and client
+ * hydration agree — see `getPagesNavigationIsReadyFromSerializedState` in
+ * `shims/router.ts`.
+ */
+/**
+ * The serialized readiness flags (gssp/gsp/gip/appGip/autoExport +
+ * `__vinext.hasRewrites`) that gate the initial Pages Router `router.isReady`.
+ * The field names/types are projected from the canonical `VinextNextData` so
+ * this stays in lockstep with the `__NEXT_DATA__` shape it feeds into.
+ */
+type PagesReadinessNextData = Pick<VinextNextData, "gssp" | "gsp" | "gip" | "appGip" | "autoExport"> & {
+  __vinext: Pick<NonNullable<VinextNextData["__vinext"]>, "hasRewrites">;
+};
+/**
+ * Build the readiness flags for a Pages Router render. Shared by the dev and
+ * production Pages render paths.
+ */
+declare function buildPagesReadinessNextData(options: {
+  pageModule: PagesPageModule;
+  appComponent: {
+    getInitialProps?: unknown;
+  } | null | undefined;
+  hasRewrites: boolean;
+}): PagesReadinessNextData;
+//#endregion
+export { buildPagesReadinessNextData };

package/dist/server/pages-readiness.js

@@ -0,0 +1,21 @@
+//#region src/server/pages-readiness.ts
+/**
+* Build the readiness flags for a Pages Router render. Shared by the dev and
+* production Pages render paths.
+*/
+function buildPagesReadinessNextData(options) {
+	const hasPageGssp = typeof options.pageModule.getServerSideProps === "function";
+	const hasPageGsp = typeof options.pageModule.getStaticProps === "function";
+	const hasPageGip = typeof options.pageModule.default?.getInitialProps === "function";
+	const hasAppGip = typeof options.appComponent?.getInitialProps === "function";
+	return {
+		gssp: hasPageGssp,
+		gsp: hasPageGsp,
+		gip: hasPageGip,
+		appGip: hasAppGip,
+		autoExport: !hasPageGssp && !hasPageGsp && !hasPageGip && !hasAppGip,
+		__vinext: { hasRewrites: options.hasRewrites }
+	};
+}
+//#endregion
+export { buildPagesReadinessNextData };

package/dist/server/pages-request-pipeline.d.ts

@@ -0,0 +1,113 @@
+import { NextHeader, NextI18nConfig, NextRedirect, NextRewrite } from "../config/next-config.js";
+import { HeaderRecord } from "./request-pipeline.js";
+
+//#region src/server/pages-request-pipeline.d.ts
+type PagesRenderOptions = {
+  isDataReq?: boolean;
+  renderErrorPageOnMiss?: boolean;
+};
+type MiddlewareResult = {
+  continue: boolean;
+  redirectUrl?: string;
+  redirectStatus?: number;
+  rewriteUrl?: string;
+  rewriteStatus?: number;
+  status?: number;
+  responseHeaders?: Iterable<[string, string]>;
+  response?: Response;
+  waitUntilPromises?: Promise<unknown>[];
+};
+type PagesPipelineDeps = {
+  basePath: string;
+  trailingSlash: boolean;
+  i18nConfig: NextI18nConfig | null;
+  configRedirects: NextRedirect[];
+  configRewrites: {
+    beforeFiles: NextRewrite[];
+    afterFiles: NextRewrite[];
+    fallback: NextRewrite[];
+  };
+  configHeaders: NextHeader[];
+  hadBasePath: boolean;
+  isDataReq: boolean;
+  isDataRequest: boolean;
+  ctx?: unknown;
+  rawSearch?: string;
+  matchPageRoute?: ((pathname: string, request: Request) => {
+    route: {
+      isDynamic: boolean;
+    };
+  } | null) | null;
+  runMiddleware?: ((request: Request, ctx: unknown, opts: {
+    isDataRequest: boolean;
+  }) => Promise<MiddlewareResult>) | null;
+  renderPage?: ((request: Request, resolvedUrl: string, options?: PagesRenderOptions, stagedHeaders?: Headers) => Promise<Response>) | null;
+  handleApi?: ((request: Request, apiUrl: string, ctx: unknown) => Promise<Response>) | null;
+  /**
+   * Optional override for proxying external rewrite destinations.
+   * When supplied, the pipeline calls this instead of proxyExternalRequest(currentRequest, url).
+   * Receives the pipeline's current request (with post-middleware headers applied) and the
+   * external target URL. Dev adapters supply this to forward the original Node req body
+   * (which is not included in the pipeline's body-less Web Request).
+   */
+  proxyExternal?: ((currentRequest: Request, externalUrl: string) => Promise<Response>) | null;
+  /**
+   * Optional public-directory static file server (Node prod only).
+   * Called post-middleware (so middleware can intercept/redirect public files) with the
+   * original basePath-stripped pathname and the staged middleware response headers.
+   * The callback writes the file to its own output (Node `res`) and resolves `true` when
+   * it served the request; the pipeline then returns `{ type: "handled" }`. Resolves `false`
+   * to fall through to rewrites/render. Worker/dev adapters omit this — their public files
+   * are served by the asset binding / Vite respectively.
+   */
+  serveStaticFile?: ((requestPathname: string, stagedHeaders: HeaderRecord) => Promise<boolean>) | null;
+};
+/**
+ * Wrap an adapter's `runMiddleware` callback so middleware receives the original
+ * (pre-basePath-stripping) URL. Adapters strip the basePath before handing the
+ * request to `runPagesRequest`, but Next.js passes the un-stripped URL to the
+ * middleware adapter so `request.nextUrl.basePath` reflects whether the URL
+ * actually had the basePath prefix. Requests outside the basePath
+ * (`hadBasePath === false`) are passed through untouched so middleware sees
+ * `nextUrl.basePath === ""` and can redirect them into the basePath
+ * (see the middleware-base-path e2e test / #1830).
+ *
+ * Shared by the Node prod server (prod-server.ts) and the generated Pages
+ * Router worker entry (deploy.ts) to keep the two adapters in sync.
+ */
+declare function wrapMiddlewareWithBasePath(runMiddleware: NonNullable<PagesPipelineDeps["runMiddleware"]>, basePath: string, hadBasePath: boolean): NonNullable<PagesPipelineDeps["runMiddleware"]>;
+type PagesPipelineResult = {
+  type: "response";
+  response: Response;
+  defaultContentType?: string;
+} | {
+  type: "handled";
+} | {
+  type: "render";
+  resolvedUrl: string;
+  renderOptions: PagesRenderOptions | undefined;
+  stagedHeaders: HeaderRecord; /** Post-middleware request headers — dev adapters apply these to req.headers before SSR. */
+  requestHeaders: Headers;
+  middlewareStatus: number | undefined;
+  isDataReq: boolean;
+} | {
+  type: "api";
+  apiUrl: string;
+  stagedHeaders: HeaderRecord; /** Post-middleware request headers — dev adapters apply these to req.headers before API handler. */
+  requestHeaders: Headers;
+  middlewareStatus: number | undefined;
+} | {
+  type: "next";
+};
+/**
+ * Run the Pages Router request pipeline.
+ *
+ * ASSUMPTION: request already has internal headers filtered and basePath stripped.
+ * The adapter is responsible for that pre-processing before calling runPagesRequest.
+ * The adapter also handles: open-redirect guard, _next/static 404, image optimization,
+ * _next/data normalization, Node decode/normalize/400, public-file serving.
+ * runPagesRequest receives a "clean" request with basePath-stripped URL.
+ */
+declare function runPagesRequest(request: Request, deps: PagesPipelineDeps): Promise<PagesPipelineResult>;
+//#endregion
+export { MiddlewareResult, PagesPipelineDeps, PagesPipelineResult, PagesRenderOptions, runPagesRequest, wrapMiddlewareWithBasePath };

package/dist/server/pages-request-pipeline.js

@@ -0,0 +1,230 @@
+import { addBasePathToPathname, hasBasePath } from "../utils/base-path.js";
+import { applyMiddlewareRequestHeaders, isExternalUrl, matchRedirect, matchRewrite, preserveRedirectDestinationQuery, proxyExternalRequest, requestContextFromRequest, sanitizeDestination } from "../config/config-matchers.js";
+import { applyConfigHeadersToHeaderRecord, normalizeTrailingSlash } from "./request-pipeline.js";
+import { mergeRewriteQuery } from "../utils/query.js";
+import { normalizeDefaultLocalePathname, stripI18nLocaleForApiRoute } from "./pages-i18n.js";
+import { mergeHeaders } from "./worker-utils.js";
+//#region src/server/pages-request-pipeline.ts
+/**
+* Wrap an adapter's `runMiddleware` callback so middleware receives the original
+* (pre-basePath-stripping) URL. Adapters strip the basePath before handing the
+* request to `runPagesRequest`, but Next.js passes the un-stripped URL to the
+* middleware adapter so `request.nextUrl.basePath` reflects whether the URL
+* actually had the basePath prefix. Requests outside the basePath
+* (`hadBasePath === false`) are passed through untouched so middleware sees
+* `nextUrl.basePath === ""` and can redirect them into the basePath
+* (see the middleware-base-path e2e test / #1830).
+*
+* Shared by the Node prod server (prod-server.ts) and the generated Pages
+* Router worker entry (deploy.ts) to keep the two adapters in sync.
+*/
+function wrapMiddlewareWithBasePath(runMiddleware, basePath, hadBasePath) {
+	if (!hadBasePath || !basePath) return runMiddleware;
+	return (request, ctx, opts) => {
+		const mwUrl = new URL(request.url);
+		mwUrl.pathname = addBasePathToPathname(mwUrl.pathname, basePath);
+		return runMiddleware(new Request(mwUrl, request), ctx, opts);
+	};
+}
+/**
+* Run the Pages Router request pipeline.
+*
+* ASSUMPTION: request already has internal headers filtered and basePath stripped.
+* The adapter is responsible for that pre-processing before calling runPagesRequest.
+* The adapter also handles: open-redirect guard, _next/static 404, image optimization,
+* _next/data normalization, Node decode/normalize/400, public-file serving.
+* runPagesRequest receives a "clean" request with basePath-stripped URL.
+*/
+async function runPagesRequest(request, deps) {
+	const { basePath, trailingSlash, i18nConfig, configRedirects, configRewrites, configHeaders, hadBasePath, isDataReq, isDataRequest } = deps;
+	const proxyExternal = (currentReq, externalUrl) => deps.proxyExternal ? deps.proxyExternal(currentReq, externalUrl) : proxyExternalRequest(currentReq, externalUrl);
+	const url = new URL(request.url);
+	let pathname = url.pathname;
+	const search = url.search;
+	const basePathState = {
+		basePath,
+		hadBasePath
+	};
+	{
+		const trailingSlashRedirect = normalizeTrailingSlash(pathname, basePath, trailingSlash, search);
+		if (trailingSlashRedirect) return {
+			type: "response",
+			response: trailingSlashRedirect
+		};
+	}
+	const reqCtx = requestContextFromRequest(request);
+	const requestHostname = i18nConfig ? url.hostname : "";
+	const matchPathname = i18nConfig ? normalizeDefaultLocalePathname(pathname, i18nConfig, { hostname: requestHostname }) : pathname;
+	if (configRedirects.length) {
+		const redirect = matchRedirect(matchPathname, configRedirects, reqCtx, basePathState);
+		if (redirect) {
+			const location = preserveRedirectDestinationQuery(sanitizeDestination(basePath && hadBasePath && !isExternalUrl(redirect.destination) && !hasBasePath(redirect.destination, basePath) ? basePath + redirect.destination : redirect.destination), deps.rawSearch ?? search);
+			return {
+				type: "response",
+				response: new Response(null, {
+					status: redirect.permanent ? 308 : 307,
+					headers: { Location: location }
+				})
+			};
+		}
+	}
+	let resolvedUrl = pathname + search;
+	const middlewareHeaders = {};
+	let middlewareStatus;
+	if (typeof deps.runMiddleware === "function") {
+		const result = await deps.runMiddleware(request, deps.ctx ?? null, { isDataRequest });
+		if (result.waitUntilPromises && result.waitUntilPromises.length > 0) {
+			const ctx = deps.ctx;
+			if (ctx && typeof ctx.waitUntil === "function") for (const p of result.waitUntilPromises) ctx.waitUntil(p);
+			else Promise.allSettled(result.waitUntilPromises);
+		}
+		if (!result.continue) {
+			if (result.redirectUrl) {
+				const redirectHeaders = { Location: result.redirectUrl };
+				if (result.responseHeaders) for (const [key, value] of result.responseHeaders) {
+					const existing = redirectHeaders[key];
+					if (existing === void 0) redirectHeaders[key] = value;
+					else if (Array.isArray(existing)) existing.push(value);
+					else redirectHeaders[key] = [existing, value];
+				}
+				const headers = new Headers();
+				for (const [k, v] of Object.entries(redirectHeaders)) if (Array.isArray(v)) for (const item of v) headers.append(k, item);
+				else headers.set(k, v);
+				return {
+					type: "response",
+					response: new Response(null, {
+						status: result.redirectStatus ?? 307,
+						headers
+					})
+				};
+			}
+			if (result.response) return {
+				type: "response",
+				response: result.response
+			};
+		}
+		if (result.responseHeaders) for (const [key, value] of result.responseHeaders) if (key === "set-cookie") {
+			const existing = middlewareHeaders[key];
+			if (Array.isArray(existing)) existing.push(value);
+			else if (existing) middlewareHeaders[key] = [existing, value];
+			else middlewareHeaders[key] = [value];
+		} else middlewareHeaders[key] = value;
+		if (result.rewriteUrl) resolvedUrl = result.rewriteUrl;
+		middlewareStatus = result.status ?? result.rewriteStatus;
+	}
+	const { postMwReqCtx, request: postMwReq } = applyMiddlewareRequestHeaders(middlewareHeaders, request, { preserveCredentialHeaders: isExternalUrl(resolvedUrl) });
+	request = postMwReq;
+	let resolvedPathname = resolvedUrl.split("?")[0];
+	const matchResolvedPathname = (p) => i18nConfig ? normalizeDefaultLocalePathname(p, i18nConfig, { hostname: requestHostname }) : p;
+	if (configHeaders.length) applyConfigHeadersToHeaderRecord(middlewareHeaders, {
+		configHeaders,
+		pathname: matchPathname,
+		requestContext: reqCtx,
+		basePathState
+	});
+	if (isExternalUrl(resolvedUrl)) return {
+		type: "response",
+		response: mergeHeaders(await proxyExternal(request, resolvedUrl), middlewareHeaders, void 0)
+	};
+	if (deps.serveStaticFile) {
+		if (await deps.serveStaticFile(pathname, middlewareHeaders)) return { type: "handled" };
+	}
+	let configRewriteFired = false;
+	if (configRewrites.beforeFiles?.length) {
+		const rewritten = matchRewrite(matchResolvedPathname(resolvedPathname), configRewrites.beforeFiles, postMwReqCtx, basePathState);
+		if (rewritten) {
+			if (isExternalUrl(rewritten)) return {
+				type: "response",
+				response: await proxyExternal(request, rewritten)
+			};
+			resolvedUrl = mergeRewriteQuery(resolvedUrl, rewritten);
+			resolvedPathname = resolvedUrl.split("?")[0];
+			configRewriteFired = true;
+		}
+	}
+	if (basePath && !hadBasePath && !configRewriteFired) return {
+		type: "response",
+		response: new Response("This page could not be found", {
+			status: 404,
+			headers: { "Content-Type": "text/html; charset=utf-8" }
+		})
+	};
+	const apiLookupUrl = stripI18nLocaleForApiRoute(resolvedUrl, i18nConfig);
+	const apiLookupPathname = apiLookupUrl.split("?")[0];
+	if (apiLookupPathname.startsWith("/api/") || apiLookupPathname === "/api") if (typeof deps.handleApi === "function") return {
+		type: "response",
+		defaultContentType: "application/octet-stream",
+		response: mergeHeaders(await deps.handleApi(request, apiLookupUrl, deps.ctx ?? null), middlewareHeaders, middlewareStatus)
+	};
+	else return {
+		type: "api",
+		apiUrl: apiLookupUrl,
+		stagedHeaders: middlewareHeaders,
+		requestHeaders: request.headers,
+		middlewareStatus
+	};
+	const pageMatch = deps.matchPageRoute ? deps.matchPageRoute(resolvedPathname, request) : null;
+	let resolvedPathnameChanged = false;
+	if ((!pageMatch || pageMatch.route.isDynamic) && configRewrites.afterFiles?.length) {
+		const rewritten = matchRewrite(matchResolvedPathname(resolvedPathname), configRewrites.afterFiles, postMwReqCtx, basePathState);
+		if (rewritten) {
+			if (isExternalUrl(rewritten)) return {
+				type: "response",
+				response: await proxyExternal(request, rewritten)
+			};
+			resolvedUrl = mergeRewriteQuery(resolvedUrl, rewritten);
+			resolvedPathname = resolvedUrl.split("?")[0];
+			resolvedPathnameChanged = true;
+		}
+	}
+	if (typeof deps.renderPage === "function") {
+		const renderPageMatch = resolvedPathnameChanged ? deps.matchPageRoute ? deps.matchPageRoute(resolvedPathname, request) : null : pageMatch;
+		const shouldDeferErrorPageOnMiss = !isDataReq && !isDataRequest && !!deps.matchPageRoute && !renderPageMatch;
+		const initialRenderOptions = shouldDeferErrorPageOnMiss ? { renderErrorPageOnMiss: false } : isDataReq ? { isDataReq: true } : void 0;
+		const stagedHeaders = new Headers();
+		for (const [k, v] of Object.entries(middlewareHeaders)) if (Array.isArray(v)) for (const item of v) stagedHeaders.append(k, item);
+		else stagedHeaders.set(k, v);
+		let response = await deps.renderPage(request, resolvedUrl, initialRenderOptions, stagedHeaders);
+		let matchedFallbackRewrite = false;
+		if (response.status === 404 && shouldDeferErrorPageOnMiss && configRewrites.fallback?.length) {
+			const fallbackRewrite = matchRewrite(matchResolvedPathname(resolvedPathname), configRewrites.fallback, postMwReqCtx, basePathState);
+			if (fallbackRewrite) {
+				if (isExternalUrl(fallbackRewrite)) return {
+					type: "response",
+					response: await proxyExternal(request, fallbackRewrite)
+				};
+				response = await deps.renderPage(request, mergeRewriteQuery(resolvedUrl, fallbackRewrite), void 0, stagedHeaders);
+				matchedFallbackRewrite = true;
+			}
+		}
+		if (response.status === 404 && shouldDeferErrorPageOnMiss && !matchedFallbackRewrite) response = await deps.renderPage(request, resolvedUrl, void 0, stagedHeaders);
+		const merged = mergeHeaders(response, middlewareHeaders, middlewareStatus);
+		if (merged !== response) merged.__vinextStreamedHtmlResponse = response.__vinextStreamedHtmlResponse;
+		return {
+			type: "response",
+			response: merged,
+			defaultContentType: "text/html"
+		};
+	}
+	if (!(resolvedPathnameChanged ? deps.matchPageRoute ? deps.matchPageRoute(resolvedPathname, request) : null : pageMatch) && configRewrites.fallback?.length) {
+		const fallbackRewrite = matchRewrite(matchResolvedPathname(resolvedPathname), configRewrites.fallback, postMwReqCtx, basePathState);
+		if (fallbackRewrite) {
+			if (isExternalUrl(fallbackRewrite)) return {
+				type: "response",
+				response: await proxyExternal(request, fallbackRewrite)
+			};
+			resolvedUrl = mergeRewriteQuery(resolvedUrl, fallbackRewrite);
+		}
+	}
+	return {
+		type: "render",
+		resolvedUrl,
+		renderOptions: isDataReq ? { isDataReq: true } : void 0,
+		stagedHeaders: middlewareHeaders,
+		requestHeaders: request.headers,
+		middlewareStatus,
+		isDataReq
+	};
+}
+//#endregion
+export { runPagesRequest, wrapMiddlewareWithBasePath };

package/dist/server/pages-revalidate.d.ts

@@ -0,0 +1,15 @@
+import { IncomingMessage } from "node:http";
+
+//#region src/server/pages-revalidate.d.ts
+type RevalidateOptions = {
+  /**
+   * Only revalidate the path if it was already generated (cached). Mirrors
+   * Next.js's `unstable_onlyGenerated`: sets the
+   * `x-prerender-revalidate-if-generated` header and makes a 404 response count
+   * as a successful no-op rather than an error.
+   */
+  unstable_onlyGenerated?: boolean;
+};
+declare function performOnDemandRevalidate(source: IncomingMessage | Headers, urlPath: string, opts?: RevalidateOptions): Promise<void>;
+//#endregion
+export { RevalidateOptions, performOnDemandRevalidate };

package/dist/server/pages-revalidate.js

@@ -0,0 +1,19 @@
+import "./headers.js";
+import { PRERENDER_REVALIDATE_HEADER, PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER, getRevalidateSecret } from "./isr-cache.js";
+import { resolveRequestHost, resolveRequestProtocol } from "./proxy-trust.js";
+//#region src/server/pages-revalidate.ts
+async function performOnDemandRevalidate(source, urlPath, opts = {}) {
+	if (typeof urlPath !== "string" || !urlPath.startsWith("/")) throw new Error(`Invalid urlPath provided to revalidate(), must be a path e.g. /blog/post-1, received ${urlPath}`);
+	const proto = resolveRequestProtocol(source);
+	const host = resolveRequestHost(source, "localhost");
+	const target = new URL(urlPath, `${proto}://${host}`);
+	const headers = { [PRERENDER_REVALIDATE_HEADER]: getRevalidateSecret() };
+	if (opts.unstable_onlyGenerated) headers[PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER] = "1";
+	const res = await fetch(target, {
+		method: "HEAD",
+		headers
+	});
+	if (!(res.headers.get("x-nextjs-cache")?.toUpperCase() === "REVALIDATED" || res.status === 200 || res.status === 404 && opts.unstable_onlyGenerated === true)) throw new Error(`Failed to revalidate ${urlPath}: ${res.status}`);
+}
+//#endregion
+export { performOnDemandRevalidate };

package/dist/server/prod-server.d.ts

@@ -3,6 +3,44 @@ import { resolveRequestHost, trustProxy, trustedHosts } from "./proxy-trust.js";
 import { IncomingMessage, ServerResponse } from "node:http";
 
 //#region src/server/prod-server.d.ts
+/**
+ * Import a built server entry module (App Router RSC entry or Pages Router
+ * server entry) by absolute file path.
+ *
+ * The first import of a given path uses the plain file:// URL with NO query
+ * string. This is load-bearing: code-split builds emit lazy chunks that
+ * import the entry back by bare specifier (default Vite builds on both
+ * supported majors — Rollup on Vite 7 and Rolldown on Vite 8 — hoist modules
+ * shared between the entry's static graph and lazy route chunks into the
+ * entry chunk, which the chunks then import as e.g. "../../index.js").
+ * Node keys its ESM cache on the full URL including the query string, so if
+ * the server imported the entry as `index.js?t=<mtime>`, a chunk's bare
+ * back-import would evaluate the entire server bundle a second time and
+ * module-level singletons (db pools, service registries) would silently
+ * diverge between the two copies. See
+ * https://github.com/cloudflare/vinext/issues/1923.
+ *
+ * A `?t=<mtime>` query string is appended only when the same path is
+ * imported again after a rebuild (different mtime) — e.g. test suites that
+ * rebuild a fixture to the same output path within one process — where the
+ * bare URL's cache entry would return the stale previous build. Note this
+ * rebuild branch trades the single-instance guarantee back: chunks that
+ * import the entry by bare path still resolve to the FIRST build's cache
+ * entry, so freshness and single-instance only hold together on the first
+ * import of a path. Production processes import each entry path exactly
+ * once and always get both.
+ *
+ * The entry is imported via its canonical real path: the bundler
+ * canonicalizes module ids with fs.realpathSync.native, so chunks evaluate
+ * under realpath-based URLs and their relative imports resolve to realpath
+ * URLs too. Importing the entry through a symlinked path (macOS /var/...
+ * tmpdirs, symlinked deploy directories) would otherwise create a second
+ * instance keyed on the symlinked URL.
+ *
+ * Exported for direct unit testing of the URL choice.
+ */
+declare function resolveServerEntryImportUrl(entryPath: string): string;
+declare function importServerEntryModule(entryPath: string): Promise<any>;
 type ProdServerOptions = {
   /** Port to listen on */port?: number; /** Host to bind to */
   host?: string; /** Path to the build output directory */
@@ -29,8 +67,12 @@ declare function mergeResponseHeaders(middlewareHeaders: Record<string, string |
 /**
  * Merge middleware/config headers and an optional status override into a new
  * Web Response while preserving the original body stream when allowed.
- * Keep this in sync with server/worker-utils.ts and the generated copy in
- * deploy.ts.
+ *
+ * This is the canonical {@link mergeHeaders} (server/worker-utils.ts) with the
+ * arguments in (headers, response) order. The request path now calls
+ * `runPagesRequest`, which uses `mergeHeaders` directly; this wrapper is retained
+ * only for its existing tests and any external callers, so there is a single
+ * implementation to keep in sync. (deploy.ts still emits its own generated copy.)
  */
 declare function mergeWebResponse(middlewareHeaders: Record<string, string | string[]>, response: Response, statusOverride?: number): Response;
 /**
@@ -101,4 +143,4 @@ declare function resolveAppRouterPrerenderSeeder(entryModule: unknown): AppRoute
  */
 declare function resolveAppRouterAssetPath(pathname: string, assetPathPrefix: string, assetPrefix: string): string | null;
 //#endregion
-export { COMPRESSIBLE_TYPES, COMPRESS_THRESHOLD, ProdServerOptions, mergeResponseHeaders, mergeWebResponse, negotiateEncoding, nodeToWebRequest, resolveAppRouterAssetPath, resolveAppRouterPrerenderSeeder, resolveRequestHost as resolveHost, sendCompressed, sendWebResponse, startProdServer, trustProxy, trustedHosts, tryServeStatic };
+export { COMPRESSIBLE_TYPES, COMPRESS_THRESHOLD, ProdServerOptions, importServerEntryModule, mergeResponseHeaders, mergeWebResponse, negotiateEncoding, nodeToWebRequest, resolveAppRouterAssetPath, resolveAppRouterPrerenderSeeder, resolveRequestHost as resolveHost, resolveServerEntryImportUrl, sendCompressed, sendWebResponse, startProdServer, trustProxy, trustedHosts, tryServeStatic };