vinext 0.1.0 → 0.1.1

package/dist/server/pages-page-data.js

@@ -117,6 +117,7 @@ async function renderPagesIsrHtml(options) {
 		params: options.params,
 		routePattern: options.routePattern,
 		safeJsonStringify: options.safeJsonStringify,
+		nextData: options.nextData,
 		vinext: options.vinext
 	});
 	return rewritePagesCachedHtml(options.cachedHtml, freshBody, nextDataScript);
@@ -174,11 +175,11 @@ async function resolvePagesPageData(options) {
 		const cacheKey = options.isrCacheKey("pages", pathname);
 		const cached = await options.isrGet(cacheKey);
 		const cachedValue = cached?.value.value;
-		if (cachedValue?.kind === "PAGES" && cached && !cached.isStale && !options.scriptNonce && !options.isDataReq) return {
+		if (!options.isOnDemandRevalidate && cachedValue?.kind === "PAGES" && cached && !cached.isStale && !options.scriptNonce && !options.isDataReq) return {
 			kind: "response",
 			response: buildPagesCacheResponse(cachedValue.html, "HIT", options.fontLinkHeader, void 0, options.expireSeconds, cached.value.cacheControl, cachedValue.status)
 		};
-		if (cachedValue?.kind === "PAGES" && cached && cached.isStale && !options.scriptNonce && !options.isDataReq) {
+		if (!options.isOnDemandRevalidate && cachedValue?.kind === "PAGES" && cached && cached.isStale && !options.scriptNonce && !options.isDataReq) {
 			options.triggerBackgroundRegeneration(cacheKey, async function() {
 				return options.runInFreshUnifiedContext(async () => {
 					const freshResult = await options.pageModule.getStaticProps?.({
@@ -200,6 +201,7 @@ async function resolvePagesPageData(options) {
 							renderIsrPassToStringAsync: options.renderIsrPassToStringAsync,
 							routePattern: options.routePattern,
 							safeJsonStringify: options.safeJsonStringify,
+							nextData: options.nextData,
 							vinext: options.vinext
 						});
 						await options.isrSet(cacheKey, buildPagesCacheValue(freshHtml, freshResult.props, options.statusCode), freshResult.revalidate, void 0, options.expireSeconds);

package/dist/server/pages-page-handler.d.ts

@@ -47,8 +47,15 @@ type CreatePagesPageHandlerOptions = {
   vinextConfig: VinextConfigSubset; /** Build ID embedded at build time (or null in dev). */
   buildId: string | null; /** Whether the app has user-defined middleware. */
   hasMiddleware: boolean; /** Absolute file path of `pages/_app` (or null). Used for manifest lookup. */
-  appAssetPath: string | null; /** `setSSRContext` from `next/router`. */
-  setSSRContext: ((ctx: Record<string, unknown> | null) => void) | null; /** `setI18nContext` from `vinext/i18n-context`. */
+  appAssetPath: string | null; /** Whether next.config rewrites are configured (gates Pages router readiness). */
+  hasRewrites: boolean; /** `setSSRContext` from `next/router`. */
+  setSSRContext: ((ctx: Record<string, unknown> | null) => void) | null;
+  /**
+   * `getPagesNavigationIsReadyFromSerializedState` from `next/router`. Decides
+   * the initial `router.isReady` value for the Pages Router navigation
+   * compat hooks (mirrors Next.js's Pages adapter readiness gate).
+   */
+  getPagesNavigationIsReadyFromSerializedState: ((routePattern: string | undefined, searchString: string, nextData?: Record<string, unknown>) => boolean) | null; /** `setI18nContext` from `vinext/i18n-context`. */
   setI18nContext: ((ctx: Record<string, unknown>) => void) | null; /** `wrapWithRouterContext` from `next/router`. */
   wrapWithRouterContext: ((element: ReactNode) => ReactNode) | null; /** `resetSSRHead` from `next/head`. */
   resetSSRHead: (() => void) | undefined; /** `getSSRHeadHTML` from `next/head`. */

package/dist/server/pages-page-handler.js

@@ -2,12 +2,13 @@ import { createRequestContext, runWithRequestContext } from "../shims/unified-re
 import { patternToNextFormat } from "../routing/route-validation.js";
 import { getRequestExecutionContext } from "../shims/request-context.js";
 import { reportRequestError } from "./instrumentation.js";
-import { isrCacheKey, isrGet, isrSet, triggerBackgroundRegeneration } from "./isr-cache.js";
+import { PRERENDER_REVALIDATE_HEADER, isOnDemandRevalidateRequest, isrCacheKey, isrGet, isrSet, triggerBackgroundRegeneration } from "./isr-cache.js";
 import { ensureFetchPatch } from "../shims/fetch-cache.js";
 import { mergeRouteParamsIntoQuery, parseQueryString } from "../utils/query.js";
 import { getScriptNonceFromHeaderSources } from "./csp.js";
 import { resolvePagesI18nRequest } from "./pages-i18n.js";
 import { buildDefaultPagesNotFoundResponse } from "./pages-default-404.js";
+import { buildPagesReadinessNextData } from "./pages-readiness.js";
 import { resolvePagesPageMethodResponse } from "./pages-page-method.js";
 import { buildNextDataJsonResponse, buildNextDataNotFoundResponse, normalizePagesDataRequest } from "./pages-data-route.js";
 import { createPagesReqRes } from "./pages-node-compat.js";
@@ -30,7 +31,7 @@ function buildI18nRenderContext(i18nConfig, locale, currentDefaultLocale, domain
 * accepts the same options shape the generated entry always passed inline.
 */
 function createPagesPageHandler(opts) {
-	const { pageRoutes, errorPageRoute, matchRoute, i18nConfig, vinextConfig, buildId, hasMiddleware, appAssetPath, setSSRContext, setI18nContext, wrapWithRouterContext, resetSSRHead, getSSRHeadHTML, setDocumentInitialHead, flushPreloads, getFontLinks, getFontStyles, getFontPreloads, renderToReadableStream, renderIsrPassToStringAsync, safeJsonStringify, sanitizeDestination, createPageElement, enhancePageElement, AppComponent, DocumentComponent } = opts;
+	const { pageRoutes, errorPageRoute, matchRoute, i18nConfig, vinextConfig, buildId, hasMiddleware, appAssetPath, hasRewrites, setSSRContext, getPagesNavigationIsReadyFromSerializedState, setI18nContext, wrapWithRouterContext, resetSSRHead, getSSRHeadHTML, setDocumentInitialHead, flushPreloads, getFontLinks, getFontStyles, getFontPreloads, renderToReadableStream, renderIsrPassToStringAsync, safeJsonStringify, sanitizeDestination, createPageElement, enhancePageElement, AppComponent, DocumentComponent } = opts;
 	function renderToStringAsync(element) {
 		return renderToReadableStream(element).then((stream) => new Response(stream).text());
 	}
@@ -102,15 +103,24 @@ function createPagesPageHandler(opts) {
 				const routePattern = patternToNextFormat(route.pattern);
 				const renderStatusCode = renderStatusCodeOverride ?? (routePattern === "/404" ? 404 : void 0);
 				const query = mergeRouteParamsIntoQuery(parseQueryString(routeUrl), params);
-				function applySSRContext() {
+				const pageModule = route.module;
+				const pagesNextData = buildPagesReadinessNextData({
+					pageModule,
+					appComponent: AppComponent,
+					hasRewrites
+				});
+				const navigationIsReady = typeof getPagesNavigationIsReadyFromSerializedState === "function" ? getPagesNavigationIsReadyFromSerializedState(routePattern, new URL(renderAsPath ?? routeUrl, "http://_").search, pagesNextData) : true;
+				function applySSRContext(extra) {
 					if (typeof setSSRContext === "function") setSSRContext({
 						pathname: routePattern,
 						query,
 						asPath: renderAsPath ?? routeUrl,
+						navigationIsReady,
 						locale,
 						locales: i18nConfig ? i18nConfig.locales : void 0,
 						defaultLocale: currentDefaultLocale,
-						domainLocales
+						domainLocales,
+						...extra
 					});
 					if (i18nConfig && typeof setI18nContext === "function") setI18nContext({
 						locale,
@@ -120,8 +130,7 @@ function createPagesPageHandler(opts) {
 						hostname: new URL(request.url).hostname
 					});
 				}
-				applySSRContext();
-				const pageModule = route.module;
+				applySSRContext({ nextData: pagesNextData });
 				const PageComponent = pageModule.default;
 				if (!PageComponent) return new Response("Page has no default export", { status: 500 });
 				if (!isDataReq && routePattern !== "/_error" && routePattern !== "/404" && routePattern !== "/500" && renderStatusCodeOverride === void 0) {
@@ -133,6 +142,15 @@ function createPagesPageHandler(opts) {
 				}
 				const pageModuleUrl = resolveClientModuleUrl(manifest, route.filePath);
 				const appModuleUrl = resolveClientModuleUrl(manifest, appAssetPath);
+				const serializedPagesNextData = {
+					...pagesNextData,
+					__vinext: {
+						...pagesNextData.__vinext,
+						pageModuleUrl,
+						appModuleUrl,
+						hasMiddleware
+					}
+				};
 				const scriptNonce = getScriptNonceFromHeaderSources(request.headers, middlewareHeaders);
 				let fontLinkHeader = "";
 				let allFontPreloads = [];
@@ -164,6 +182,7 @@ function createPagesPageHandler(opts) {
 					isrSet,
 					expireSeconds: vinextConfig.expireTime,
 					isBuildTimePrerendering: typeof process !== "undefined" && process.env && process.env.VINEXT_PRERENDER === "1",
+					isOnDemandRevalidate: isOnDemandRevalidateRequest(request.headers.get(PRERENDER_REVALIDATE_HEADER)),
 					pageModule,
 					params,
 					query,
@@ -183,11 +202,8 @@ function createPagesPageHandler(opts) {
 					scriptNonce,
 					statusCode: renderStatusCode,
 					triggerBackgroundRegeneration,
-					vinext: {
-						pageModuleUrl,
-						appModuleUrl,
-						hasMiddleware
-					}
+					vinext: serializedPagesNextData.__vinext,
+					nextData: serializedPagesNextData
 				});
 				if (pageDataResult.kind === "notFound") {
 					const notFoundRoute = findNotFoundRoute();
@@ -212,6 +228,7 @@ function createPagesPageHandler(opts) {
 					pathname: routePattern,
 					query,
 					asPath: renderAsPath ?? routeUrl,
+					navigationIsReady: false,
 					locale,
 					locales: i18nConfig ? i18nConfig.locales : void 0,
 					defaultLocale: currentDefaultLocale,
@@ -288,11 +305,7 @@ function createPagesPageHandler(opts) {
 					safeJsonStringify,
 					scriptNonce,
 					statusCode: renderStatusCode,
-					vinext: {
-						pageModuleUrl,
-						appModuleUrl,
-						hasMiddleware
-					}
+					nextData: serializedPagesNextData
 				});
 			} catch (e) {
 				console.error("[vinext] SSR error:", e);

package/dist/server/pages-page-response.d.ts

@@ -8,6 +8,14 @@ type PagesFontPreload = {
   href: string;
   type: string;
 };
+/**
+ * The `__NEXT_DATA__` fields beyond the always-present core that the Pages
+ * renderer serializes: the `__vinext` block plus the readiness flags
+ * (gssp/gsp/gip/appGip/autoExport/isExperimentalCompile) the client uses to
+ * recompute the initial `router.isReady`. Shared by every render path
+ * (initial, ISR regeneration) so they emit identical readiness state.
+ */
+type PagesNextDataExtras = Pick<VinextNextData, "__vinext" | "appGip" | "autoExport" | "gip" | "gsp" | "gssp" | "isExperimentalCompile">;
 type PagesI18nRenderContext = {
   locale?: string;
   locales?: string[];
@@ -73,10 +81,11 @@ type RenderPagesPageResponseOptions = {
   scriptNonce?: string;
   statusCode?: number;
   vinext?: VinextNextData["__vinext"];
+  nextData?: PagesNextDataExtras;
 };
-declare function buildPagesNextDataScript(options: Pick<RenderPagesPageResponseOptions, "buildId" | "i18n" | "isFallback" | "pageProps" | "params" | "routePattern" | "safeJsonStringify" | "scriptNonce"> & {
+declare function buildPagesNextDataScript(options: Pick<RenderPagesPageResponseOptions, "buildId" | "i18n" | "isFallback" | "pageProps" | "params" | "routePattern" | "safeJsonStringify" | "scriptNonce" | "nextData"> & {
   vinext?: VinextNextData["__vinext"];
 }): string;
 declare function renderPagesPageResponse(options: RenderPagesPageResponseOptions): Promise<Response>;
 //#endregion
-export { PagesGsspResponse, PagesI18nRenderContext, buildPagesNextDataScript, renderPagesPageResponse };
+export { PagesGsspResponse, PagesI18nRenderContext, PagesNextDataExtras, buildPagesNextDataScript, renderPagesPageResponse };

package/dist/server/pages-page-response.js

@@ -27,13 +27,19 @@ function buildPagesNextDataScript(options) {
 		buildId: options.buildId,
 		isFallback: options.isFallback === true
 	};
+	if (options.nextData) {
+		for (const [key, value] of Object.entries(options.nextData)) if (value !== void 0) nextDataPayload[key] = value;
+	}
 	if (options.i18n.locales) {
 		nextDataPayload.locale = options.i18n.locale;
 		nextDataPayload.locales = options.i18n.locales;
 		nextDataPayload.defaultLocale = options.i18n.defaultLocale;
 		nextDataPayload.domainLocales = options.i18n.domainLocales;
 	}
-	if (options.vinext) nextDataPayload.__vinext = options.vinext;
+	if (options.vinext) nextDataPayload.__vinext = {
+		...options.nextData?.__vinext,
+		...options.vinext
+	};
 	const localeGlobals = options.i18n.locales ? `;window.__VINEXT_LOCALE__=${options.safeJsonStringify(options.i18n.locale)};window.__VINEXT_LOCALES__=${options.safeJsonStringify(options.i18n.locales)};window.__VINEXT_DEFAULT_LOCALE__=${options.safeJsonStringify(options.i18n.defaultLocale)}` : "";
 	return createInlineScriptTag(`window.__NEXT_DATA__ = ${options.safeJsonStringify(nextDataPayload)}${localeGlobals}`, options.scriptNonce);
 }
@@ -129,6 +135,7 @@ async function renderPagesPageResponse(options) {
 		routePattern: options.routePattern,
 		safeJsonStringify: options.safeJsonStringify,
 		scriptNonce: options.scriptNonce,
+		nextData: options.nextData,
 		vinext: options.vinext
 	});
 	const bodyMarker = "<!--VINEXT_STREAM_BODY-->";

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 { PagesReadinessNextData, 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,99 @@
+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;
+};
+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 };

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

@@ -0,0 +1,209 @@
+import { 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
+/**
+* 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 };

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

@@ -29,8 +29,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;
 /**