vinext 0.0.55 → 0.1.1

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,11 +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 };
-//# sourceMappingURL=pages-page-response.d.ts.map
+export { PagesGsspResponse, PagesI18nRenderContext, PagesNextDataExtras, buildPagesNextDataScript, renderPagesPageResponse };

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

@@ -1,13 +1,14 @@
 import { getRequestExecutionContext } from "../shims/request-context.js";
 import { reportRequestError } from "./instrumentation.js";
 import { setCacheStateHeaders } from "./cache-headers.js";
+import { encodeCacheTag } from "../utils/encode-cache-tag.js";
 import { withScriptNonce } from "../shims/script-nonce-context.js";
 import { createInlineScriptTag, createNonceAttribute, escapeHtmlAttr } from "./html.js";
 import { getClientTraceMetadataHTML } from "./client-trace-metadata.js";
 import { readStreamAsText } from "../utils/text-stream.js";
 import { loadUserDocumentInitialProps, runDocumentRenderPage } from "./pages-document-initial-props.js";
 import { callDocumentGetInitialProps } from "./document-initial-head.js";
-import { buildRevalidateCacheControl } from "./cache-control.js";
+import { applyCdnResponseHeaders, buildRevalidateCacheControl } from "./cache-control.js";
 import React from "react";
 //#region src/server/pages-page-response.ts
 function buildPagesFontHeadHtml(fontLinks, fontPreloads, fontStyles, scriptNonce) {
@@ -26,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);
 }
@@ -128,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-->";
@@ -195,7 +203,12 @@ async function renderPagesPageResponse(options) {
 	const userSetCacheControl = responseHeaders.has("Cache-Control");
 	if (options.scriptNonce) responseHeaders.set("Cache-Control", "no-store, must-revalidate");
 	else if (options.isrRevalidateSeconds) {
-		responseHeaders.set("Cache-Control", buildRevalidateCacheControl(options.isrRevalidateSeconds, options.expireSeconds));
+		const isrPathname = options.routeUrl.split("?")[0];
+		const stem = isrPathname.endsWith("/") ? isrPathname.slice(0, -1) : isrPathname;
+		applyCdnResponseHeaders(responseHeaders, {
+			cacheControl: buildRevalidateCacheControl(options.isrRevalidateSeconds, options.expireSeconds),
+			tags: [encodeCacheTag(`_N_T_${stem || "/"}`)]
+		});
 		setCacheStateHeaders(responseHeaders, "MISS");
 	} else if (options.gsspRes && !userSetCacheControl) responseHeaders.set("Cache-Control", "private, no-cache, no-store, max-age=0, must-revalidate");
 	if (options.fontLinkHeader) responseHeaders.set("Link", options.fontLinkHeader);
@@ -206,5 +219,3 @@ async function renderPagesPageResponse(options) {
 }
 //#endregion
 export { buildPagesNextDataScript, renderPagesPageResponse };
-
-//# sourceMappingURL=pages-page-response.js.map

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/pages-serializable-props.d.ts

@@ -21,5 +21,4 @@ declare class SerializableError extends Error {
 }
 declare function isSerializableProps(page: string, method: string, input: unknown): true;
 //#endregion
-export { SerializableError, isSerializableProps };
-//# sourceMappingURL=pages-serializable-props.d.ts.map
+export { SerializableError, isSerializableProps };

package/dist/server/pages-serializable-props.js

@@ -65,5 +65,3 @@ function isSerializableProps(page, method, input) {
 }
 //#endregion
 export { SerializableError, isSerializableProps };
-
-//# sourceMappingURL=pages-serializable-props.js.map

package/dist/server/pregenerated-concrete-paths.d.ts

@@ -0,0 +1,32 @@
+//#region src/server/pregenerated-concrete-paths.d.ts
+declare global {
+  var __VINEXT_PREGENERATED_CONCRETE_PATHS: unknown;
+}
+declare function normalizePregeneratedPathname(pathname: string): string;
+declare function clearPregeneratedConcretePaths(): void;
+/**
+ * Records a concrete URL path for a route pattern. The pathname is normalized
+ * here so this is the single source of truth: every caller — the Worker global
+ * table and the Node `seed-cache.ts` path — stores the canonical form that
+ * matches the runtime `cleanPathname` lookup without having to pre-normalize.
+ */
+declare function addPregeneratedConcretePath(routePattern: string, pathname: string): void;
+/**
+ * Returns the live backing `Set` for a route pattern (not a copy) to keep
+ * lookups allocation-free on the serving hot path. The `ReadonlySet` type
+ * forbids mutation at compile time. Callers must treat the result as
+ * point-in-time and must NOT retain it across a re-seed: each
+ * `initPregeneratedPathsFromGlobals` call runs `clearPregeneratedConcretePaths`,
+ * which empties the map, leaving any previously-returned reference stale. Read
+ * it, use it, drop it — never cache the reference.
+ */
+declare function getRenderedConcreteUrlPathsForRoute(routePattern: string): ReadonlySet<string> | undefined;
+/**
+ * Populate the registry from `globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS`.
+ * No-op when the global is not set (Node path — seed-cache handles it later).
+ * `addPregeneratedConcretePath` normalizes each pathname so it matches the
+ * runtime `cleanPathname`.
+ */
+declare function initPregeneratedPathsFromGlobals(): void;
+//#endregion
+export { addPregeneratedConcretePath, clearPregeneratedConcretePaths, getRenderedConcreteUrlPathsForRoute, initPregeneratedPathsFromGlobals, normalizePregeneratedPathname };

package/dist/server/pregenerated-concrete-paths.js

@@ -0,0 +1,78 @@
+import { normalizePathnameForRouteMatch } from "../routing/utils.js";
+import { normalizePath } from "./normalize-path.js";
+//#region src/server/pregenerated-concrete-paths.ts
+function normalizePregeneratedPathname(pathname) {
+	return normalizePath(normalizePathnameForRouteMatch(pathname));
+}
+/**
+* Stores concrete URL paths pre-rendered at build time per route pattern.
+* Used by the PPR fallback-shell guard to avoid serving fallback shells for
+* known routes whose exact cache entry is temporarily absent.
+*
+* Populated by `seed-cache.ts` (Node) or from `globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS`
+* injected by `deploy.ts` after prerender (Workers).
+*/
+const concreteUrlPathsByRoute = /* @__PURE__ */ new Map();
+function clearPregeneratedConcretePaths() {
+	concreteUrlPathsByRoute.clear();
+}
+/**
+* Records a concrete URL path for a route pattern. The pathname is normalized
+* here so this is the single source of truth: every caller — the Worker global
+* table and the Node `seed-cache.ts` path — stores the canonical form that
+* matches the runtime `cleanPathname` lookup without having to pre-normalize.
+*/
+function addPregeneratedConcretePath(routePattern, pathname) {
+	const normalized = normalizePregeneratedPathname(pathname);
+	let paths = concreteUrlPathsByRoute.get(routePattern);
+	if (!paths) {
+		paths = /* @__PURE__ */ new Set();
+		concreteUrlPathsByRoute.set(routePattern, paths);
+	}
+	paths.add(normalized);
+}
+/**
+* Returns the live backing `Set` for a route pattern (not a copy) to keep
+* lookups allocation-free on the serving hot path. The `ReadonlySet` type
+* forbids mutation at compile time. Callers must treat the result as
+* point-in-time and must NOT retain it across a re-seed: each
+* `initPregeneratedPathsFromGlobals` call runs `clearPregeneratedConcretePaths`,
+* which empties the map, leaving any previously-returned reference stale. Read
+* it, use it, drop it — never cache the reference.
+*/
+function getRenderedConcreteUrlPathsForRoute(routePattern) {
+	return concreteUrlPathsByRoute.get(routePattern);
+}
+/**
+* Populate the registry from `globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS`.
+* No-op when the global is not set (Node path — seed-cache handles it later).
+* `addPregeneratedConcretePath` normalizes each pathname so it matches the
+* runtime `cleanPathname`.
+*/
+function initPregeneratedPathsFromGlobals() {
+	const raw = globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS;
+	const data = parsePregeneratedConcretePaths(raw);
+	if (!data) return;
+	clearPregeneratedConcretePaths();
+	for (const [routePattern, pathnames] of data) for (const pathname of pathnames) addPregeneratedConcretePath(routePattern, pathname);
+}
+function parsePregeneratedConcretePaths(value) {
+	if (!Array.isArray(value)) return void 0;
+	const result = [];
+	for (const entry of value) {
+		if (!Array.isArray(entry)) return void 0;
+		if (entry.length !== 2) return void 0;
+		const [pattern, paths] = entry;
+		if (typeof pattern !== "string") return void 0;
+		if (!Array.isArray(paths)) return void 0;
+		const strings = [];
+		for (const p of paths) {
+			if (typeof p !== "string") return void 0;
+			strings.push(p);
+		}
+		result.push([pattern, strings]);
+	}
+	return result;
+}
+//#endregion
+export { addPregeneratedConcretePath, clearPregeneratedConcretePaths, getRenderedConcreteUrlPathsForRoute, initPregeneratedPathsFromGlobals, normalizePregeneratedPathname };

package/dist/server/prerender-route-params.d.ts

@@ -1,14 +1,24 @@
 //#region src/server/prerender-route-params.d.ts
 type PrerenderRouteParams = Record<string, string | string[]>;
 type PrerenderRouteParamsPayload = {
+  fallbackParamNames?: readonly string[];
   params: PrerenderRouteParams;
   routePattern: string;
 };
+/** @public exported for #1716 serving consumers; not yet referenced in-repo */
+type PrerenderRouteParamsRouteMatch = {
+  kind: "exact";
+  params: PrerenderRouteParams;
+} | {
+  fallbackParamNames: readonly string[];
+  kind: "fallback-shell";
+  params: PrerenderRouteParams;
+};
 declare function serializePrerenderRouteParamsHeader(payload: PrerenderRouteParamsPayload | null): string | null;
 declare function readTrustedPrerenderRouteParamsFromHeaders(headers: Headers, expectedSecret?: string): PrerenderRouteParamsPayload | null;
 declare function readTrustedPrerenderRouteParams(request: Request): PrerenderRouteParamsPayload | null;
 declare function prerenderRouteParamsPayloadMatchesRoute(payload: PrerenderRouteParamsPayload | null, routePattern: string, params: PrerenderRouteParams): payload is PrerenderRouteParamsPayload;
-declare function encodePrerenderRouteParams(pattern: string, params: PrerenderRouteParams): PrerenderRouteParamsPayload | null;
+declare function matchPrerenderRouteParamsPayload(payload: PrerenderRouteParamsPayload | null, routePattern: string, params: PrerenderRouteParams): PrerenderRouteParamsRouteMatch | null;
+declare function encodePrerenderRouteParams(pattern: string, params: PrerenderRouteParams, fallbackParamNames?: readonly string[]): PrerenderRouteParamsPayload | null;
 //#endregion
-export { PrerenderRouteParams, PrerenderRouteParamsPayload, encodePrerenderRouteParams, prerenderRouteParamsPayloadMatchesRoute, readTrustedPrerenderRouteParams, readTrustedPrerenderRouteParamsFromHeaders, serializePrerenderRouteParamsHeader };
-//# sourceMappingURL=prerender-route-params.d.ts.map
+export { PrerenderRouteParams, PrerenderRouteParamsPayload, PrerenderRouteParamsRouteMatch, encodePrerenderRouteParams, matchPrerenderRouteParamsPayload, prerenderRouteParamsPayloadMatchesRoute, readTrustedPrerenderRouteParams, readTrustedPrerenderRouteParamsFromHeaders, serializePrerenderRouteParamsHeader };