vinext 0.2.0 → 1.0.0-beta.0

package/dist/build/prerender-paths.js

@@ -0,0 +1,296 @@
+import { findDir } from "../utils/project.js";
+import { normalizePathSeparators } from "../utils/path.js";
+import { apiRouter, pagesRouter } from "../routing/pages-router.js";
+import { VINEXT_PRERENDER_SECRET_HEADER } from "../utils/protocol-headers.js";
+import { classifyAppRoute, classifyPagesRoute, getAppRouteRenderEntryPath, hasNamedExport } from "./report.js";
+import { appRouter } from "../routing/app-router.js";
+import { normalizeStaticPathsEntry } from "../routing/route-pattern.js";
+import { BLOCKED_PAGES, PHASE_PRODUCTION_BUILD } from "../shims/constants.js";
+import { loadNextConfig, resolveNextConfig } from "../config/next-config.js";
+import { readPrerenderSecret } from "./server-manifest.js";
+import { startProdServer } from "../server/prod-server.js";
+import { buildUrlFromParams, resolveParentParams } from "./prerender.js";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/build/prerender-paths.ts
+const PRERENDER_PATH_DISCOVERY_ENV = "__VINEXT_PRERENDER_PATH_DISCOVERY";
+const PRERENDER_PATHS_MANIFEST = "vinext-prerender-paths.json";
+const PATH_DISCOVERY_FETCH_TIMEOUT_MS = 3e4;
+function readBuiltBuildId(serverDir) {
+	try {
+		const buildId = fs.readFileSync(path.join(serverDir, "BUILD_ID"), "utf-8").trim();
+		return buildId.length > 0 ? buildId : null;
+	} catch (error) {
+		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return null;
+		throw error;
+	}
+}
+function addPath(paths, seen, pathname) {
+	if (seen.has(pathname)) return;
+	seen.add(pathname);
+	paths.push(pathname);
+}
+function warnDiscoveryFailure(route, error) {
+	const message = error instanceof Error ? error.message : String(error);
+	console.warn(`[vinext] Warning: failed to discover warmup path(s) for ${route}: ${message}`);
+}
+async function fetchDiscoveryEndpoint(url, headers) {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), PATH_DISCOVERY_FETCH_TIMEOUT_MS);
+	try {
+		const res = await fetch(url, {
+			headers,
+			signal: controller.signal
+		});
+		const text = await res.text();
+		if (!res.ok || text === "null") return null;
+		return text;
+	} catch (error) {
+		if (error instanceof Error && error.name === "AbortError") throw new Error(`path discovery timed out after ${PATH_DISCOVERY_FETCH_TIMEOUT_MS}ms`);
+		throw error;
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+function fileHasNamedExport(filePath, name) {
+	if (!filePath) return false;
+	try {
+		return hasNamedExport(fs.readFileSync(filePath, "utf-8"), name);
+	} catch {
+		return false;
+	}
+}
+function resolveConfiguredRouteDirs(root, routeRootConfig) {
+	if (!routeRootConfig) return {
+		appDir: findDir(root, "app", "src/app"),
+		pagesDir: findDir(root, "pages", "src/pages")
+	};
+	let baseDir;
+	if (routeRootConfig.appDir) {
+		baseDir = path.isAbsolute(routeRootConfig.appDir) ? routeRootConfig.appDir : path.resolve(root, routeRootConfig.appDir);
+		baseDir = normalizePathSeparators(baseDir);
+	} else {
+		const hasRootApp = fs.existsSync(path.posix.join(root, "app"));
+		const hasRootPages = fs.existsSync(path.posix.join(root, "pages"));
+		const hasSrcApp = fs.existsSync(path.posix.join(root, "src", "app"));
+		const hasSrcPages = fs.existsSync(path.posix.join(root, "src", "pages"));
+		baseDir = hasRootApp || hasRootPages ? root : hasSrcApp || hasSrcPages ? path.posix.join(root, "src") : root;
+	}
+	const appDir = path.posix.join(baseDir, "app");
+	const pagesDir = path.posix.join(baseDir, "pages");
+	return {
+		appDir: !routeRootConfig.disableAppRouter && fs.existsSync(appDir) ? appDir : null,
+		pagesDir: fs.existsSync(pagesDir) ? pagesDir : null
+	};
+}
+function appRouteMayHaveGenerateStaticParams(route) {
+	if (fileHasNamedExport(route.pagePath, "generateStaticParams")) return true;
+	return route.layouts.some((layoutPath) => fileHasNamedExport(layoutPath, "generateStaticParams"));
+}
+async function shouldStartPathDiscoveryServer(options) {
+	if (options.appDir) {
+		if ((await appRouter(options.appDir, options.pageExtensions)).some((route) => route.isDynamic && appRouteMayHaveGenerateStaticParams(route))) return true;
+	}
+	if (options.pagesDir) {
+		if ((await pagesRouter(options.pagesDir, options.pageExtensions)).some((route) => route.isDynamic && fileHasNamedExport(route.filePath, "getStaticPaths"))) return true;
+	}
+	return false;
+}
+async function withPrerenderEndpoints(fn) {
+	const previousPrerenderFlag = process.env.VINEXT_PRERENDER;
+	const previousPathDiscoveryFlag = process.env[PRERENDER_PATH_DISCOVERY_ENV];
+	process.env.VINEXT_PRERENDER = "1";
+	process.env[PRERENDER_PATH_DISCOVERY_ENV] = "1";
+	try {
+		return await fn();
+	} finally {
+		if (previousPrerenderFlag === void 0) delete process.env.VINEXT_PRERENDER;
+		else process.env.VINEXT_PRERENDER = previousPrerenderFlag;
+		if (previousPathDiscoveryFlag === void 0) delete process.env[PRERENDER_PATH_DISCOVERY_ENV];
+		else process.env[PRERENDER_PATH_DISCOVERY_ENV] = previousPathDiscoveryFlag;
+	}
+}
+async function collectPagesPaths(options) {
+	const [pageRoutes, apiRoutes] = await Promise.all([pagesRouter(options.pagesDir, options.pageExtensions), apiRouter(options.pagesDir, options.pageExtensions)]);
+	const apiPatterns = new Set(apiRoutes.map((route) => route.pattern));
+	const paths = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const route of pageRoutes) {
+		if (apiPatterns.has(route.pattern)) continue;
+		if (BLOCKED_PAGES.includes(route.pattern)) continue;
+		if (route.pattern === "/404" || route.pattern === "/500" || route.pattern === "/_error") continue;
+		const { type } = classifyPagesRoute(route.filePath);
+		if (type === "api" || type === "ssr") continue;
+		if (!route.isDynamic) {
+			addPath(paths, seen, route.pattern);
+			continue;
+		}
+		if (!fileHasNamedExport(route.filePath, "getStaticPaths")) continue;
+		if (!options.baseUrl) continue;
+		try {
+			const search = new URLSearchParams({ pattern: route.pattern });
+			const text = await fetchDiscoveryEndpoint(`${options.baseUrl}/__vinext/prerender/pages-static-paths?${search}`, options.secretHeaders);
+			if (text === null) continue;
+			const pathsResult = JSON.parse(text);
+			for (const item of pathsResult.paths ?? []) {
+				const normalized = normalizeStaticPathsEntry(item, route.pattern);
+				if ("error" in normalized) throw new Error(normalized.error);
+				addPath(paths, seen, buildUrlFromParams(route.pattern, normalized.params));
+			}
+		} catch (error) {
+			warnDiscoveryFailure(route.pattern, error);
+		}
+	}
+	return paths;
+}
+async function collectAppPaths(options) {
+	const routes = await appRouter(options.appDir, options.pageExtensions);
+	const paths = [];
+	const seen = /* @__PURE__ */ new Set();
+	const staticParamsCache = /* @__PURE__ */ new Map();
+	const staticParamsMap = new Proxy({}, {
+		get(_target, pattern) {
+			return async ({ params }) => {
+				if (!options.baseUrl) return null;
+				const cacheKey = `${pattern}\0${JSON.stringify(params)}`;
+				const cached = staticParamsCache.get(cacheKey);
+				if (cached !== void 0) return cached;
+				const request = (async () => {
+					const search = new URLSearchParams({ pattern });
+					if (Object.keys(params).length > 0) search.set("parentParams", JSON.stringify(params));
+					const text = await fetchDiscoveryEndpoint(`${options.baseUrl}/__vinext/prerender/static-params?${search}`, options.secretHeaders);
+					if (text === null) return null;
+					return JSON.parse(text);
+				})();
+				request.catch(() => staticParamsCache.delete(cacheKey));
+				staticParamsCache.set(cacheKey, request);
+				return request;
+			};
+		},
+		has() {
+			return false;
+		}
+	});
+	for (const route of routes) {
+		const renderEntryPath = getAppRouteRenderEntryPath(route);
+		if (!renderEntryPath) continue;
+		const { type } = classifyAppRoute(renderEntryPath, route.routePath, route.isDynamic);
+		if (type === "api") continue;
+		if (type === "ssr" && !route.isDynamic) continue;
+		if (!route.isDynamic) {
+			addPath(paths, seen, route.pattern);
+			continue;
+		}
+		if (!appRouteMayHaveGenerateStaticParams(route)) continue;
+		try {
+			const generateStaticParams = staticParamsMap[route.pattern];
+			if (typeof generateStaticParams !== "function") continue;
+			const parentParamSets = await resolveParentParams(route, staticParamsMap);
+			let paramSets;
+			if (parentParamSets.length > 0) {
+				paramSets = [];
+				for (const parentParams of parentParamSets) {
+					const childResults = await generateStaticParams({ params: parentParams });
+					if (childResults === null) {
+						paramSets = null;
+						break;
+					}
+					if (Array.isArray(childResults)) for (const childParams of childResults) paramSets.push({
+						...parentParams,
+						...childParams
+					});
+				}
+			} else {
+				const results = await generateStaticParams({ params: {} });
+				paramSets = Array.isArray(results) || results === null ? results : [];
+			}
+			if (!paramSets?.length) continue;
+			for (const params of paramSets) {
+				if (params === null || params === void 0) continue;
+				addPath(paths, seen, buildUrlFromParams(route.pattern, params));
+			}
+		} catch (error) {
+			warnDiscoveryFailure(route.pattern, error);
+		}
+	}
+	return paths;
+}
+async function startPathDiscoveryServer(options) {
+	return startProdServer({
+		port: 0,
+		host: "127.0.0.1",
+		outDir: options.pagesBundlePath ? path.dirname(path.dirname(options.pagesBundlePath)) : path.dirname(options.serverDir),
+		rscEntryPath: options.rscBundlePath,
+		serverEntryPath: options.pagesBundlePath,
+		noCompression: true,
+		purpose: "prerender"
+	});
+}
+async function emitPrerenderPathManifest(options) {
+	const { root } = options;
+	const configuredRouteDirs = resolveConfiguredRouteDirs(root, options.routeRootConfig);
+	const appDir = options.appDir !== void 0 ? options.appDir : configuredRouteDirs.appDir;
+	const pagesDir = options.pagesDir !== void 0 ? options.pagesDir : configuredRouteDirs.pagesDir;
+	if (!appDir && !pagesDir) return null;
+	const defaultRscBundlePath = options.routeRootConfig?.rscOutDir ? path.join(path.resolve(root, options.routeRootConfig.rscOutDir), "index.js") : path.join(root, "dist", "server", "index.js");
+	const rscBundlePath = options.rscBundlePath ?? defaultRscBundlePath;
+	const pagesBundlePath = options.pagesBundlePath ?? path.join(root, "dist", "server", "entry.js");
+	const bundleServerDir = fs.existsSync(rscBundlePath) ? path.dirname(rscBundlePath) : path.dirname(pagesBundlePath);
+	const manifestDir = path.join(root, "dist", "server");
+	const loadedConfig = await resolveNextConfig(await loadNextConfig(root, PHASE_PRODUCTION_BUILD), root);
+	const config = options.nextConfigOverride ? {
+		...loadedConfig,
+		...options.nextConfigOverride
+	} : { ...loadedConfig };
+	const builtBuildId = readBuiltBuildId(manifestDir) ?? readBuiltBuildId(bundleServerDir);
+	if (builtBuildId) config.buildId = builtBuildId;
+	const paths = [];
+	const seen = /* @__PURE__ */ new Set();
+	await withPrerenderEndpoints(async () => {
+		let prodServer = null;
+		if (await shouldStartPathDiscoveryServer({
+			appDir,
+			pagesDir,
+			pageExtensions: config.pageExtensions
+		})) try {
+			prodServer = await startPathDiscoveryServer({
+				serverDir: bundleServerDir,
+				pagesBundlePath: !appDir && pagesDir ? pagesBundlePath : void 0,
+				rscBundlePath: appDir ? rscBundlePath : void 0
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			console.warn(`[vinext] Warning: failed to start prerender path discovery server: ${message}`);
+		}
+		const baseUrl = prodServer ? `http://127.0.0.1:${prodServer.port}` : null;
+		const prerenderSecret = readPrerenderSecret(bundleServerDir) ?? readPrerenderSecret(manifestDir);
+		const secretHeaders = prerenderSecret ? { [VINEXT_PRERENDER_SECRET_HEADER]: prerenderSecret } : {};
+		try {
+			if (appDir) for (const pathname of await collectAppPaths({
+				appDir,
+				baseUrl,
+				pageExtensions: config.pageExtensions,
+				secretHeaders
+			})) addPath(paths, seen, pathname);
+			if (pagesDir) for (const pathname of await collectPagesPaths({
+				baseUrl,
+				pagesDir,
+				pageExtensions: config.pageExtensions,
+				secretHeaders
+			})) addPath(paths, seen, pathname);
+		} finally {
+			if (prodServer) await new Promise((resolve) => prodServer.server.close(() => resolve()));
+		}
+	});
+	const manifest = {
+		buildId: config.buildId,
+		trailingSlash: config.trailingSlash,
+		paths
+	};
+	fs.mkdirSync(manifestDir, { recursive: true });
+	fs.writeFileSync(path.join(manifestDir, PRERENDER_PATHS_MANIFEST), JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+	console.log(`  Discovered ${paths.length} CDN warmup path(s).`);
+	return manifest;
+}
+//#endregion
+export { PRERENDER_PATHS_MANIFEST, PRERENDER_PATH_DISCOVERY_ENV, emitPrerenderPathManifest };

package/dist/build/prerender-server-entry.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/build/prerender-server-entry.js

@@ -0,0 +1,49 @@
+import { NoOpCacheHandler, setCacheHandler } from "../shims/cache-handler.js";
+import { startProdServer } from "../server/prod-server.js";
+//#region src/build/prerender-server-entry.ts
+/**
+* Child-process entry for a parallel prerender render server.
+*
+* Forked by `prerender-server-pool.ts`. React SSR/RSC rendering is CPU-bound
+* JS, so a single-process promise pool serializes every render on one core.
+* This entry lets the prerender phase fan rendering out across N OS processes
+* (one per core, like Next.js's static worker pool): each child starts a normal
+* vinext production server on an ephemeral port and reports it to the parent
+* over IPC. The parent then load-balances per-route fetches across the pool.
+*
+* `VINEXT_PRERENDER` / `VINEXT_PRERENDER_OUTDIR` are passed via the fork env so
+* they are set before any module loads (some server modules read the flag at
+* import time).
+*/
+async function main() {
+	const outDir = process.env.VINEXT_PRERENDER_OUTDIR;
+	if (!outDir) throw new Error("[vinext] prerender server worker: VINEXT_PRERENDER_OUTDIR not set");
+	setCacheHandler(new NoOpCacheHandler());
+	const { port } = await startProdServer({
+		port: 0,
+		host: "127.0.0.1",
+		outDir,
+		noCompression: true,
+		purpose: "prerender",
+		silent: true
+	});
+	if (typeof process.send === "function") process.send({
+		type: "ready",
+		port
+	});
+	else throw new Error("[vinext] prerender server worker: no IPC channel to parent");
+}
+process.on("disconnect", () => process.exit(0));
+main().catch((err) => {
+	const message = err instanceof Error ? err.stack ?? err.message : String(err);
+	if (typeof process.send === "function") {
+		process.send({
+			type: "error",
+			error: message
+		}, () => process.exit(1));
+		return;
+	}
+	process.exit(1);
+});
+//#endregion
+export {};

package/dist/build/prerender-server-pool.d.ts

@@ -0,0 +1,44 @@
+//#region src/build/prerender-server-pool.d.ts
+/**
+ * Whether the forkable worker entry exists as a runnable `.js` sibling. False
+ * when vinext runs from source (e.g. the test suite transpiles `.ts` on the
+ * fly and a forked plain-node child can't load `.ts`); callers fall back to the
+ * single in-process server. True in the published/built package.
+ */
+declare function prerenderPoolAvailable(): boolean;
+type PrerenderServerPool = {
+  /** Ports of the forked render servers, for round-robin per-route fetches. */ports: number[];
+  /**
+   * Throw if any worker exited unexpectedly (i.e. not via `close()`). The
+   * caller MUST call this after the render loop: a crashed worker makes every
+   * route routed to it fail with a connection error, which the per-route
+   * handler records as a (non-fatal) error — without this check the build
+   * would emit partial output and still exit 0. Mirrors the single-process
+   * design, where a server crash takes the whole build down loudly.
+   */
+  assertHealthy: () => void;
+  /**
+   * Record a failed fetch to a render worker. This closes the tiny ordering gap
+   * where the request can fail before Node has delivered the child `exit` event.
+   */
+  recordRenderError: (err: unknown) => void; /** Kill every forked server. Safe to call more than once. */
+  close: () => Promise<void>;
+};
+/**
+ * Choose how many render processes to fork for `routeCount` routes.
+ *
+ * Returns 1 to mean "don't fork — render in-process as before" (small apps,
+ * single/dual-core, low memory, or an explicit `--prerender-concurrency 1`).
+ * `maxOverride` comes from `--prerender-concurrency`, which caps both the
+ * number of in-flight route fetches and the worker count (the default is capped
+ * at `min(cores, 8)`).
+ */
+declare function resolvePrerenderPoolSize(routeCount: number, maxOverride?: number): number;
+/**
+ * Fork `size` production servers against `outDir` and resolve once all are
+ * listening. Each child reports its port over IPC. Rejects (and tears down any
+ * already-started children) if any child fails to come up.
+ */
+declare function startPrerenderServerPool(outDir: string, size: number, entry?: string): Promise<PrerenderServerPool>;
+//#endregion
+export { PrerenderServerPool, prerenderPoolAvailable, resolvePrerenderPoolSize, startPrerenderServerPool };

package/dist/build/prerender-server-pool.js

@@ -0,0 +1,194 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+import { fork } from "node:child_process";
+//#region src/build/prerender-server-pool.ts
+/**
+* Parallel prerender server pool.
+*
+* React SSR/RSC rendering during prerender is CPU-bound JS. vinext renders
+* every route by fetching it from a single in-process production server, so the
+* promise pool in `prerender.ts` only overlaps I/O — the actual rendering
+* serializes on one core. This module forks a pool of OS processes (one vinext
+* production server each, on its own ephemeral port) so the prerender phase can
+* spread rendering across cores, mirroring Next.js's static worker pool. The
+* caller load-balances per-route fetches across `ports`.
+*
+* child_process (not worker_threads) is deliberate: worker threads share the
+* process and contend badly for CPU on this workload (measured ~2× slower
+* per route and non-scaling), which is also why Next.js uses processes.
+*/
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WORKER_ENTRY = path.join(__dirname, "prerender-server-entry.js");
+/**
+* Whether the forkable worker entry exists as a runnable `.js` sibling. False
+* when vinext runs from source (e.g. the test suite transpiles `.ts` on the
+* fly and a forked plain-node child can't load `.ts`); callers fall back to the
+* single in-process server. True in the published/built package.
+*/
+function prerenderPoolAvailable() {
+	return fs.existsSync(WORKER_ENTRY);
+}
+/** Hard cap on render processes. Beyond this the main thread (which collects
+* HTML and writes files) becomes the bottleneck, so more workers don't help. */
+const MAX_POOL_SIZE = 8;
+/** Don't fork a dedicated process unless a worker gets at least this many
+* routes — below this the fork + bundle-import startup cost outweighs the
+* parallel-render saving (measured: a 2-worker pool only reliably beats the
+* single server from ~50 routes/worker up). */
+const MIN_ROUTES_PER_WORKER = 48;
+/** Rough memory budget reserved for the main build process plus its in-process
+* prerender server. */
+const APPROX_MAIN_PROCESS_BYTES = 768 * 1024 * 1024;
+/** Rough memory budget per worker (a worker loads the whole server bundle).
+* Used with total system memory as a coarse upper bound on constrained machines
+* so K render processes don't OOM. Deliberately under-forks rather than risking
+* OOM; measured mid-size apps are usually lower (~260-380 MB/worker). */
+const APPROX_BYTES_PER_WORKER = 768 * 1024 * 1024;
+/** Per-worker readiness timeout. */
+const WORKER_READY_TIMEOUT_MS = 6e4;
+/** Best-effort close timeout so build cleanup is not blocked forever by a wedged child. */
+const WORKER_CLOSE_TIMEOUT_MS = 5e3;
+const PRERENDER_WORKER_TRANSPORT_ERROR_CODES = new Set([
+	"ECONNREFUSED",
+	"ECONNRESET",
+	"EPIPE",
+	"UND_ERR_SOCKET"
+]);
+/**
+* Choose how many render processes to fork for `routeCount` routes.
+*
+* Returns 1 to mean "don't fork — render in-process as before" (small apps,
+* single/dual-core, low memory, or an explicit `--prerender-concurrency 1`).
+* `maxOverride` comes from `--prerender-concurrency`, which caps both the
+* number of in-flight route fetches and the worker count (the default is capped
+* at `min(cores, 8)`).
+*/
+function resolvePrerenderPoolSize(routeCount, maxOverride) {
+	const cores = Math.max(1, os.availableParallelism());
+	const byCores = Math.max(1, Math.min(cores - 1, MAX_POOL_SIZE));
+	const memoryForWorkers = Math.max(0, os.totalmem() - APPROX_MAIN_PROCESS_BYTES);
+	const byMemory = Math.max(1, Math.floor(memoryForWorkers / APPROX_BYTES_PER_WORKER));
+	const cap = maxOverride && maxOverride > 0 ? Math.min(maxOverride, byCores) : byCores;
+	const byRoutes = Math.floor(routeCount / MIN_ROUTES_PER_WORKER);
+	return Math.max(1, Math.min(cap, byMemory, byRoutes));
+}
+function getErrorCauseCode(err) {
+	if (!(err instanceof Error)) return void 0;
+	const cause = err.cause;
+	return typeof cause?.code === "string" ? cause.code : void 0;
+}
+function isWorkerTransportError(err) {
+	const code = getErrorCauseCode(err);
+	if (code && PRERENDER_WORKER_TRANSPORT_ERROR_CODES.has(code)) return true;
+	return err instanceof TypeError && err.message === "fetch failed";
+}
+/**
+* Fork `size` production servers against `outDir` and resolve once all are
+* listening. Each child reports its port over IPC. Rejects (and tears down any
+* already-started children) if any child fails to come up.
+*/
+async function startPrerenderServerPool(outDir, size, entry = WORKER_ENTRY) {
+	const children = [];
+	let shuttingDown = false;
+	let crash = null;
+	let renderTransportError = null;
+	const close = async () => {
+		shuttingDown = true;
+		await Promise.all(children.map(closeChild));
+	};
+	try {
+		const readies = Array.from({ length: size }, () => {
+			const child = fork(entry, [], {
+				cwd: process.cwd(),
+				env: {
+					...process.env,
+					VINEXT_PRERENDER: "1",
+					VINEXT_PRERENDER_OUTDIR: outDir
+				},
+				stdio: [
+					"ignore",
+					"inherit",
+					"inherit",
+					"ipc"
+				]
+			});
+			children.push(child);
+			return new Promise((resolve, reject) => {
+				const timer = setTimeout(() => {
+					reject(/* @__PURE__ */ new Error("[vinext] prerender render server did not start within 60s"));
+				}, WORKER_READY_TIMEOUT_MS);
+				const cleanupStartupListeners = () => {
+					clearTimeout(timer);
+					child.off("message", onMessage);
+					child.off("error", onError);
+					child.off("exit", onStartupExit);
+				};
+				const onMessage = (msg) => {
+					cleanupStartupListeners();
+					if (msg?.type === "ready" && typeof msg.port === "number") {
+						child.once("exit", (code, signal) => {
+							if (!shuttingDown && !crash) crash = {
+								port: msg.port,
+								code,
+								signal
+							};
+						});
+						resolve(msg.port);
+					} else reject(/* @__PURE__ */ new Error(`[vinext] prerender render server failed: ${msg?.error ?? "unknown"}`));
+				};
+				const onError = (err) => {
+					cleanupStartupListeners();
+					reject(err);
+				};
+				const onStartupExit = (code, signal) => {
+					if (code !== null || signal !== null) {
+						cleanupStartupListeners();
+						reject(/* @__PURE__ */ new Error(`[vinext] prerender render server exited during startup (code ${code}, signal ${signal})`));
+					}
+				};
+				child.once("message", onMessage);
+				child.once("error", onError);
+				child.once("exit", onStartupExit);
+			});
+		});
+		const ports = await Promise.all(readies);
+		const recordRenderError = (err) => {
+			if (!renderTransportError && isWorkerTransportError(err)) renderTransportError = err instanceof Error ? err : new Error(String(err));
+		};
+		const assertHealthy = () => {
+			if (crash) throw new Error(`[vinext] A prerender render worker (port ${crash.port}) exited unexpectedly (code ${crash.code}, signal ${crash.signal}) during the build. Prerender output is incomplete; failing the build. This is often an out-of-memory kill — try a lower --prerender-concurrency.`);
+			if (renderTransportError) {
+				const causeCode = getErrorCauseCode(renderTransportError);
+				throw new Error(`[vinext] A prerender render worker request failed` + (causeCode ? ` (${causeCode})` : "") + " before the worker exit was observed. Prerender output is incomplete; failing the build. This is often an out-of-memory kill — try a lower --prerender-concurrency.");
+			}
+		};
+		return {
+			ports,
+			assertHealthy,
+			recordRenderError,
+			close
+		};
+	} catch (err) {
+		await close();
+		throw err;
+	}
+}
+async function closeChild(child) {
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	const exited = new Promise((resolve) => {
+		const timer = setTimeout(resolve, WORKER_CLOSE_TIMEOUT_MS);
+		timer.unref?.();
+		const finish = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		child.once("exit", finish);
+		if (child.exitCode !== null || child.signalCode !== null) finish();
+	});
+	if (!child.killed) child.kill("SIGKILL");
+	await exited;
+}
+//#endregion
+export { prerenderPoolAvailable, resolvePrerenderPoolSize, startPrerenderServerPool };

package/dist/build/prerender.d.ts

@@ -135,6 +135,17 @@ type PrerenderAppOptionsInternal = PrerenderAppOptions & {
  * all '<' and '>' in the embedded JSON, preventing false </script> matches.
  */
 declare function extractRscPayloadFromPrerenderedHtml(html: string): Uint8Array | null;
+/**
+ * Build a URL path from a route pattern and params.
+ * "/posts/:id" + { id: "42" } → "/posts/42"
+ * "/docs/:slug+" + { slug: ["a", "b"] } → "/docs/a/b"
+ *
+ * Throws a descriptive error rather than a cryptic `Cannot read properties of
+ * undefined` if `params` itself is missing or required keys are absent — the
+ * caller (prerenderPages / prerenderApp) catches this and surfaces it as a
+ * per-route error result.
+ */
+declare function buildUrlFromParams(pattern: string, params: Record<string, string | string[]> | undefined | null): string;
 /** Map of route patterns to generateStaticParams functions (or null/undefined). */
 type StaticParamsMap = Record<string, ((opts: {
   params: Record<string, string | string[]>;
@@ -207,4 +218,4 @@ declare function writePrerenderIndex(routes: PrerenderRouteResult[], outDir: str
   trailingSlash?: boolean;
 }): void;
 //#endregion
-export { PrerenderResult, PrerenderRouteResult, StaticParamsMap, extractRscPayloadFromPrerenderedHtml, prerenderApp, prerenderPages, readPrerenderSecret, resolveParentParams, writePrerenderIndex };
+export { PrerenderResult, PrerenderRouteResult, StaticParamsMap, buildUrlFromParams, extractRscPayloadFromPrerenderedHtml, prerenderApp, prerenderPages, readPrerenderSecret, resolveParentParams, writePrerenderIndex };