@thomas.f/prnext 0.1.17-alpha → 0.1.19-alpha

package/build/migration-scenarios.mjs

@@ -0,0 +1,72 @@
+import { execFile, fork } from 'node:child_process';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const runner = fileURLToPath(new URL('./migration-scenarios-runner.mjs', import.meta.url));
+const scope = 'Application-provided browser scenarios run independently against each server in isolated contexts. Passing both servers does not establish full application equivalence. Application code is explicitly executed and may submit forms or change test data. Browser messages, request data and raw errors are excluded from this report.';
+function origin(value) {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) throw new Error('Scenario servers must be HTTP(S) origins without credentials, paths, or queries.');
+  return url.origin;
+}
+
+/** The explicit scenario option is the only path that loads application test code. */
+export async function runMigrationScenarios({ directory, against, candidate, scenarios, timeout = 10000 }) {
+  const root = await realpath(path.resolve(directory));
+  const reference = origin(against), current = origin(candidate);
+  if (typeof scenarios !== 'string' || !scenarios || !/\.[cm]?js$/.test(scenarios)) throw new Error('Provide an application browser scenario module ending in .mjs, .cjs or .js.');
+  const filename = await realpath(path.resolve(root, scenarios));
+  const relative = path.relative(root, filename);
+  if (!relative || relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)) throw new Error('The browser scenario module must be inside the application directory.');
+  if (!(await stat(filename)).isFile()) throw new Error('The browser scenario module must be a regular file.');
+  if (!Number.isInteger(timeout) || timeout < 100 || timeout > 60000) throw new Error('Scenario timeout must be 100–60000 milliseconds.');
+  // Require an application manifest, without loading it as executable code.
+  JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+  return new Promise(resolve => {
+    const child = fork(runner, [], { cwd: root, execArgv: [], stdio: ['ignore', 'ignore', 'ignore', 'ipc'], windowsHide: true });
+    let settled = false, report, timer, killTimer, browserPid, termination = Promise.resolve();
+    const incomplete = reason => ({ ok: false, state: 'unknown', reason, results: [], scope });
+    const finish = value => {
+      if (settled) return;
+      settled = true; clearTimeout(timer); clearTimeout(killTimer);
+      child.removeAllListeners('message');
+      resolve({ ...value, scope });
+    };
+    // The worker has 20 scenarios maximum, two targets each, plus a bounded
+    // startup/teardown budget. A hung module import cannot hold the CLI open.
+    const terminate = () => {
+      if (child.exitCode !== null || child.signalCode !== null || !child.pid) return;
+      // Kill only this worker's descendants on Windows. A synchronous user test
+      // cannot process SIGTERM or close its browser itself.
+      if (process.platform === 'win32') termination = new Promise(done => execFile('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true }, () => { if (child.exitCode === null) child.kill(); done(); }));
+      else {
+        // BrowserServer owns this process, and Chromium closes its subprocesses
+        // when that browser process exits. No shared browser is ever connected.
+        if (browserPid) { try { process.kill(browserPid, 'SIGKILL'); } catch {} }
+        child.kill('SIGTERM'); killTimer = setTimeout(() => child.kill('SIGKILL'), 1000);
+      }
+    };
+    const budget = Math.min(300000, 20000 + timeout * 40);
+    timer = setTimeout(() => { report = incomplete('worker-timeout'); terminate(); }, budget);
+    child.on('message', message => {
+      if (message?.type === 'browser-started' && Number.isInteger(message.pid) && message.pid > 0 && message.pid !== process.pid && message.pid !== child.pid) { browserPid = message.pid; return; }
+      if (message?.type === 'browser-closed') { browserPid = undefined; return; }
+      if (message?.type !== 'result' || !message.report || report) return;
+      // Never forward arbitrary fields from application code or a compromised
+      // IPC message: the public report has a fixed, deliberately small schema.
+      const input = message.report;
+      if (!Array.isArray(input.results) || input.results.length > 40 || input.results.some(item => !item || !Number.isInteger(item.scenario) || item.scenario < 1 || item.scenario > 20 || !['reference', 'candidate'].includes(item.target) || !['passed', 'failed'].includes(item.status))) { report = incomplete('invalid-result'); terminate(); return; }
+      const results = input.results.map(item => ({ scenario: Number.isInteger(item.scenario) ? item.scenario : 0, target: item.target === 'reference' ? 'reference' : 'candidate', status: item.status === 'passed' ? 'passed' : 'failed', ...(item.reason === 'timeout' ? { reason: 'timeout' } : item.status !== 'passed' ? { reason: 'assertion-or-runtime-failure' } : {}) }));
+      const allowed = new Set(['playwright-unavailable', 'invalid-scenarios', 'scenario-module-failed', 'scenario-module-timeout', 'browser-unavailable', 'worker-failed']);
+      report = { ok: input.ok === true && results.length > 0 && results.every(item => item.status === 'passed'), state: input.state === 'checked' ? 'checked' : 'unknown', ...(allowed.has(input.reason) ? { reason: input.reason } : {}), results };
+      child.send({ type: 'close' }, () => {});
+      // A module can leave its own timers running. Once the owned browser has
+      // closed, exit the worker rather than waiting for application handles.
+      clearTimeout(timer); timer = setTimeout(terminate, 5000);
+    });
+    child.once('error', () => finish(incomplete('worker-failed')));
+    child.once('close', () => { void termination.then(() => finish(report || incomplete('worker-failed'))); });
+    child.send({ type: 'run', root, filename, reference, candidate: current, timeout }, error => { if (error) { report = incomplete('worker-failed'); terminate(); } });
+  });
+}

package/build/native-discovery.mjs

@@ -1,6 +1,9 @@
 import { readdir, readFile, realpath } from 'node:fs/promises';
-import { createRequire } from 'node:module';
+import { builtinModules, createRequire } from 'node:module';
 import path from 'node:path';
+import { analyzeSource } from './source-analysis.mjs';
+
+const builtins = new Set([...builtinModules, ...builtinModules.map(name => 'node:' + name)]);
 
 /** Inspect only packages reached through imports and declared runtime dependencies. */
 export function createNativeDiscovery({ projectRoot, isClientSource }) {
@@ -9,6 +12,27 @@ export function createNativeDiscovery({ projectRoot, isClientSource }) {
   const packageFiles = new Map();
   const dependencyRoots = new Map();
   const clientBoundaries = new Map();
+  const sourceImports = new Map(), entryNative = new Map(), declaredNative = new Map();
+  const resolvers = new Map();
+  let sourceBytes = 0;
+  const isApplication = directory => {
+    const relative = path.relative(directory, projectRoot);
+    return relative === '' || (!relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative));
+  };
+
+  function importsFor(file) {
+    if (!sourceImports.has(file)) sourceImports.set(file, (async () => {
+      if (!/\.(?:[cm]?[jt]s|jsx|tsx)$/.test(file) || /\.d\.[cm]?ts$/.test(file)) return { imports: [], computedRequire: false };
+      const source = await readFile(file, 'utf8');
+      const size = Buffer.byteLength(source);
+      if (size > 8 * 1024 ** 2 || (sourceBytes += size) > 64 * 1024 ** 2) throw new Error('Native npm import analysis exceeds its 8 MiB file / 64 MiB source budget. Separate the native loader into a server-only package.');
+      // The compiler accepts JSX in JavaScript npm entries, including .js.
+      const { imports, computedRequire } = analyzeSource(source, /\.[cm]?js$/.test(file) ? file + '.jsx' : file);
+      // Keep edges, not the AST, so the shared parser can bound its retained cache.
+      return { imports, computedRequire };
+    })());
+    return sourceImports.get(file);
+  }
 
   function readMetadata(directory) {
     if (!metadata.has(directory)) metadata.set(directory, readFile(path.join(directory, 'package.json'), 'utf8').then(JSON.parse).catch(error => {
@@ -53,7 +77,7 @@ export function createNativeDiscovery({ projectRoot, isClientSource }) {
           else if (entry.isFile() || entry.isSymbolicLink()) {
             if (entry.name.endsWith('.node')) result.native = true;
             if (/\.(?:css|scss|sass)$/i.test(entry.name)) result.css = true;
-            if (/\.(?:[cm]?js|jsx|tsx?)$/.test(entry.name) && !entry.name.endsWith('.d.ts')) result.sources.push(file);
+            if (/\.(?:[cm]?[jt]s|jsx|tsx)$/.test(entry.name) && !/\.d\.[cm]?ts$/.test(entry.name)) result.sources.push(file);
           }
         }
       }
@@ -99,6 +123,38 @@ export function createNativeDiscovery({ projectRoot, isClientSource }) {
     return false;
   }
 
+  function declaredNativeFor(owner) {
+    if (!declaredNative.has(owner.directory)) declaredNative.set(owner.directory, nativeReachable(owner));
+    return declaredNative.get(owner.directory);
+  }
+
+  function nativeFromEntry(file, mode) {
+    const key = mode + '\0' + file;
+    if (!entryNative.has(key)) entryNative.set(key, (async () => {
+      const pending = [file], visited = new Set();
+      while (pending.length) {
+        const current = pending.pop();
+        if (visited.has(current)) continue;
+        visited.add(current);
+        if (visited.size > 4096) throw new Error('Native npm import analysis exceeds 4096 reached modules. Separate the native loader into a server-only package.');
+        const owner = await packageFor(current);
+        if (!owner || isApplication(owner.directory)) continue;
+        if ((await filesFor(owner.directory)).native) return true;
+        const source = await importsFor(current);
+        // A runtime loader may compute a declared package name. Preserve its
+        // original npm boundary when that unknown name can reach an addon.
+        if (source.computedRequire && await declaredNativeFor(owner)) return true;
+        for (const dependency of source.imports) {
+          if (builtins.has(dependency.path)) continue;
+          const resolved = await resolvers.get(mode)(dependency.path, current, dependency.kind);
+          if (!resolved.errors?.length && !resolved.external && resolved.namespace === 'file') pending.push(resolved.path);
+        }
+      }
+      return false;
+    })());
+    return entryNative.get(key);
+  }
+
   function hasClientBoundary(directory, sources) {
     if (!clientBoundaries.has(directory)) clientBoundaries.set(directory, (async () => {
       for (const file of sources) {
@@ -116,13 +172,17 @@ export function createNativeDiscovery({ projectRoot, isClientSource }) {
   }
 
   return {
+    setResolver(mode, resolve) { resolvers.set(mode, resolve); },
     canExternalizeDirectory,
     async externalOwner(file, mode) {
       const owner = await packageFor(file);
       if (!owner) return;
-      const application = path.relative(owner.directory, projectRoot);
-      if (application === '' || (!application.startsWith('..' + path.sep) && application !== '..' && !path.isAbsolute(application))) return;
-      if (!await nativeReachable(owner)) return;
+      if (isApplication(owner.directory)) return;
+      if (!await declaredNativeFor(owner)) return;
+      // A package can declare build tools with native dependencies that its
+      // runtime entry never imports (for example an i18n extractor). Follow
+      // that entry's real compiler resolution before externalizing its parent.
+      if (resolvers.has(mode) && !await nativeFromEntry(file, mode)) return;
       // Keep CSS extraction and Server Component client-reference transforms in
       // the compiler. A native dependency imported by this package is examined
       // separately when its own entry is resolved.

package/build/native-packages.mjs

@@ -66,6 +66,8 @@ export function createNativePackages(projectRoot, { isClientSource }) {
       return {
         name: `prnext-native-packages-${mode}`,
         setup(esbuild) {
+          discovery.setResolver(mode, (name, importer, kind) => esbuild.resolve(name, { importer, resolveDir: path.dirname(importer), kind,
+            pluginData: { prnextNativeResolving: true, prnextNpmResolving: true } }));
           esbuild.onResolve({ filter: /\.node$/ }, async args => {
             if (args.pluginData?.prnextNativeResolving) return;
             if (mode === 'browser') return { errors: [{ text: `Native Node addon ${args.path} cannot run in a Client Component (${args.importer}). Keep the native dependency in a Server Component or route handler.` }] };

package/build/native-type-config.mjs

@@ -0,0 +1,37 @@
+import {readFile} from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {parseTsconfig,createPathsMatcher} from 'get-tsconfig';
+import {parse,modify,applyEdits} from 'jsonc-parser';
+
+// TypeScript 7 has no stable legacy compiler API. Parse configuration only with
+// the dedicated JSONC/config resolvers; semantic checking stays in native tsc.
+export async function nativeTypeConfig(filename,helper){
+  let source=await readFile(filename,'utf8');const errors=[];
+  const own=parse(source,errors,{allowTrailingComma:true});
+  if(errors.length||!own||typeof own!=='object'||Array.isArray(own))throw new Error('Cannot configure typed routes: invalid tsconfig.');
+  const config=parseTsconfig(filename),directory=path.dirname(filename);
+  const format={insertSpaces:true,tabSize:2,eol:source.includes('\r\n')?'\r\n':'\n'};
+  const update=(location,value)=>{source=applyEdits(source,modify(source,location,value,{formattingOptions:format}));};
+  const files=own.files??config.files??[];
+  if(!Array.isArray(files)||files.some(file=>typeof file!=='string'))throw new Error('tsconfig.files must be an array.');
+  if(!files.some(file=>path.resolve(directory,file)===helper))update(['files'],[...files,path.relative(directory,helper).replaceAll(path.sep,'/')]);
+  const options=config.compilerOptions||{},paths=options.paths||{};
+  const missing=['next','next/*'].filter(name=>!Object.hasOwn(paths,name));
+  if(!missing.length)return source;
+  const base=options.baseUrl?path.resolve(directory,options.baseUrl):directory;
+  const relative=filename=>{const value=path.relative(base,filename).replaceAll(path.sep,'/');return value.startsWith('.')?value:'./'+value;};
+  const resolved=own.compilerOptions?.paths?{...paths}:{};
+  if(!own.compilerOptions?.paths){
+    const matcher=createPathsMatcher({path:filename,config});
+    for(const pattern of Object.keys(paths)){
+      const probe='__prnext_type_path__',values=matcher?.(pattern.replace('*',probe));
+      if(!values?.length)throw new Error('Cannot resolve inherited TypeScript path: '+pattern);
+      resolved[pattern]=values.map(value=>relative(value).replaceAll(probe,'*'));
+    }
+  }
+  const compat=fileURLToPath(new URL('../compat/',import.meta.url));
+  for(const name of missing)resolved[name]=[relative(path.join(compat,name==='next'?'index.d.ts':'*.d.cts'))];
+  update(['compilerOptions','paths'],resolved);
+  return source;
+}

package/build/npm-packages.mjs

@@ -33,6 +33,7 @@ export function npmPackagesPlugin({ pages = false, projectRoot, transpilePackage
   return { name: 'prnext-npm-packages', setup(build) {
     const resolving = { prnextNpmResolving: true, prnextNativeResolving: true };
     const resolve = (name, importer, kind) => build.resolve(name, { importer, resolveDir: path.dirname(importer), kind, pluginData: resolving });
+    native.setResolver('ssr', resolve);
     function classify(file) {
       if (!decisions.has(file)) decisions.set(file, (async () => {
         const queue = [file], visited = new Set();

package/build/persistent-cache.mjs

@@ -17,7 +17,21 @@ async function frameworkHash(){
     const hash=createHash('sha256');
     for(const f of files)hash.update(f).update(await readFile(path.join(packageRoot,'build',f)));
     hash.update(await readFile(path.join(packageRoot,'package.json')));
-    for(const name of ['@babel/core','@babel/parser','@babel/traverse','@babel/generator','@babel/types','esbuild'])hash.update(name+':'+require(name+'/package.json').version);
+    for(const name of ['@babel/core','@babel/parser','@babel/traverse','@babel/generator','@babel/types','babel-plugin-react-compiler','esbuild'])hash.update(name+':'+require(name+'/package.json').version);
+    // CSS graph outputs also depend on the installed style engine and browser
+    // database, including nested/non-hoisted installations with different pins.
+    for(const name of ['lightningcss','browserslist','caniuse-lite','electron-to-chromium','postcss','postcss-value-parser','postcss-flexbugs-fixes','postcss-preset-env']){
+      let filename;
+      try{filename=require.resolve(name+'/package.json');}
+      catch{
+        let directory=path.dirname(require.resolve(name));
+        while(true){
+          try{const candidate=path.join(directory,'package.json'),value=JSON.parse(await readFile(candidate,'utf8'));if(value.name===name){filename=candidate;break;}}catch{}
+          const parent=path.dirname(directory);if(parent===directory)throw new Error(`Cannot fingerprint ${name}`);directory=parent;
+        }
+      }
+      hash.update(name).update(await readFile(filename));
+    }
     return hash.digest('hex');
   })();
   return frameworkIdentity;
@@ -78,8 +92,9 @@ export async function readCacheRecord(directory,key,limit=16*1024*1024){
     return JSON.parse(record.payload);
   }catch{return null;}finally{await file?.close().catch(()=>{});}
 }
-export async function writeCacheRecord(directory,key,value,limit=16*1024*1024){
+export async function writeCacheRecord(directory,key,value,limit=16*1024*1024,{maxFiles=64}={}){
   if(!directory||!/^[a-f0-9]{64}$/.test(key))return false;
+  if(!Number.isInteger(maxFiles)||maxFiles<1||maxFiles>4096)return false;
   const filename=path.join(directory,key+'.json'),temporary=filename+'.'+randomUUID()+'.tmp';
   try{
     const payload=JSON.stringify(value),body=JSON.stringify({version:1,key,checksum:cacheHash(payload),payload});
@@ -91,7 +106,7 @@ export async function writeCacheRecord(directory,key,value,limit=16*1024*1024){
       const stat=await lstat(path.join(directory,name)).catch(()=>null);if(stat?.isFile()&&!stat.isSymbolicLink())records.push({name,size:stat.size,time:stat.mtimeMs});
     }
     records.sort((a,b)=>b.time-a.time);let total=0;
-    for(let i=0;i<records.length;i++){total+=records[i].size;if(i>=64||total>MAX_DISK)await unlink(path.join(directory,records[i].name)).catch(()=>{});}
+    for(let i=0;i<records.length;i++){total+=records[i].size;if(i>=maxFiles||total>MAX_DISK)await unlink(path.join(directory,records[i].name)).catch(()=>{});}
     return true;
   }catch{return false;}finally{await unlink(temporary).catch(()=>{});}
 }

package/build/precompress.mjs

@@ -20,7 +20,7 @@ async function digest(stream, limit = Infinity) {
 // this bounded index and serialize publication/eviction, including overwrites.
 // Cached bytes are still decoded and hashed before reuse below.
 async function compressionCache(directory) {
-  if (!directory) return;
+  if (!directory || process.env.PRNEXT_BUILD_CACHE === '0') return;
   try {
     await mkdir(directory,{recursive:true});
     const info=await lstat(directory);

package/build/prerender-cache.mjs

@@ -0,0 +1,70 @@
+import { createServer } from 'node:http';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+
+const MAX_VALUE = 2 * 1024 * 1024;
+const MAX_BYTES = 32 * 1024 * 1024;
+const MAX_ENTRIES = 256;
+const LEASE_MS = 25_000;
+const keyPattern = /^[a-f\d]{64}$/;
+
+// A build-only, loopback capability. It shares only values which the existing
+// runtime explicitly elects to cache. It never stores route output or fetches
+// marked no-store. The entire store dies with this prerender session.
+export async function createPrerenderCache() {
+  const token = randomBytes(32).toString('hex');
+  const values = new Map(), leases = new Map();
+  let bytes = 0, active = 0;
+  const generation = 0;
+  function remove(key) { const value = values.get(key); if (value) { bytes -= value.cost; values.delete(key); } }
+  function operation(input) {
+    if (input.op === 'generation') return { generation };
+    if (input.op === 'invalidate') throw new Error('Build cache invalidation requires a running production server');
+    if (!keyPattern.test(input.key)) throw new Error('Invalid build cache key');
+    const now = Date.now();
+    for(const [key,lease] of leases)if(lease.until<=now)leases.delete(key);
+    const lease = leases.get(input.key);
+    if (input.op === 'leaseStatus') return { valid: Boolean(lease && lease.id === input.lease) };
+    if (input.op === 'release') { if (lease?.id === input.lease) leases.delete(input.key); return {}; }
+    if (input.op === 'commit') {
+      if (!lease || lease.id !== input.lease || typeof input.value !== 'string' || input.value.length > Math.ceil(MAX_VALUE / 3) * 4) return { stored: false };
+      const size = Buffer.byteLength(input.value, 'base64');
+      if (size > MAX_VALUE || (input.revalidate !== null && (!Number.isFinite(input.revalidate) || input.revalidate < 0))) return { stored: false };
+      remove(input.key);
+      const cost = Buffer.byteLength(input.value) + 512;
+      while (values.size && (bytes + cost > MAX_BYTES || values.size >= MAX_ENTRIES)) remove(values.keys().next().value);
+      values.set(input.key, { value: input.value, cost, timestamp: now, revalidate: input.revalidate, expire: input.expire }); bytes += cost;
+      leases.delete(input.key);
+      return { stored: true };
+    }
+    if (input.op !== 'read') throw new Error('Unknown build cache operation');
+    const record = values.get(input.key);
+    const ttl = Math.min(input.revalidate ?? Infinity, record?.revalidate ?? Infinity, record?.expire ?? Infinity);
+    if (record && now - record.timestamp < ttl * 1000) {
+      values.delete(input.key); values.set(input.key, record);
+      return { state: 'fresh', value: record.value, key: input.key, generation };
+    }
+    if (record) remove(input.key);
+    if (lease) return { state: 'pending', retryAfterMs: 20, key: input.key, generation };
+    if (leases.size >= MAX_ENTRIES) throw new Error('Build cache lease capacity exceeded');
+    const id = randomBytes(16).toString('hex'); leases.set(input.key, { id, until: now + LEASE_MS });
+    return { state: 'miss', lease: id, key: input.key, generation };
+  }
+  const server = createServer(async (request, response) => {
+    if(active>=8){response.writeHead(503).end();return;}
+    active++;
+    try {
+      const auth = Buffer.from(request.headers.authorization || '');
+      const expected = Buffer.from(`Bearer ${token}`);
+      if (request.method !== 'POST' || request.url !== '/' || auth.length !== expected.length || !timingSafeEqual(auth, expected)) { response.writeHead(403).end(); return; }
+      let size = 0; const chunks = [];
+      for await (const chunk of request) { size += chunk.length; if (size > 3 * 1024 * 1024) throw new Error('Build cache request too large'); chunks.push(chunk); }
+      const result = operation(JSON.parse(Buffer.concat(chunks).toString()));
+      response.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' }).end(JSON.stringify(result));
+    } catch { if (!response.headersSent) response.writeHead(400); response.end(); }
+    finally{active--;}
+  });
+  server.requestTimeout = 5000; server.headersTimeout = 5000;
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+  const env = { PRNEXT_CACHE_URL: `http://127.0.0.1:${server.address().port}/`, PRNEXT_CACHE_TOKEN: token };
+  return { env, async close() { values.clear(); leases.clear(); bytes = 0; await new Promise(resolve => { server.close(resolve); server.closeAllConnections(); }); } };
+}

package/build/prerender-config.mjs

@@ -0,0 +1,29 @@
+import { availableParallelism, freemem } from 'node:os';
+
+const MIB = 1024 * 1024;
+
+export function validatePrerenderConfig(value) {
+  if (value === undefined) return {};
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('prerender must be an object.');
+  for (const key of Object.keys(value)) if (!['workers', 'maxMemoryMb'].includes(key)) throw new TypeError(`prerender.${key} is not supported.`);
+  const result = {};
+  if (value.workers !== undefined) {
+    if (!Number.isInteger(value.workers) || value.workers < 1 || value.workers > 8) throw new TypeError('prerender.workers must be an integer from 1 to 8.');
+    result.workers = value.workers;
+  }
+  if (value.maxMemoryMb !== undefined) {
+    if (!Number.isInteger(value.maxMemoryMb) || value.maxMemoryMb < 256 || value.maxMemoryMb > 16384) throw new TypeError('prerender.maxMemoryMb must be an integer from 256 to 16384.');
+    result.maxMemoryMb = value.maxMemoryMb;
+  }
+  return result;
+}
+
+// This is an admission budget, not an OS memory sandbox. Reserve memory for the
+// coordinator/compiler and derive the process count from currently free RAM.
+export function prerenderResources(value, { cpus = availableParallelism(), free = Math.min(freemem(), process.availableMemory?.() ?? Infinity) } = {}) {
+  const config = validatePrerenderConfig(value);
+  const availableMb = Math.max(0, Math.floor(free / MIB) - 512);
+  const maxMemoryMb = Math.min(config.maxMemoryMb ?? 2048, Math.max(256, Math.floor(availableMb / 2)));
+  const workers = Math.max(1, Math.min(config.workers ?? 4, Math.max(1, cpus - 1), Math.floor(maxMemoryMb / 384)));
+  return { workers, maxMemoryMb, heapMb: Math.max(64, Math.floor(maxMemoryMb / workers / 3)), explicit: config.workers !== undefined };
+}

package/build/prerender-pages.mjs

@@ -4,6 +4,7 @@ import {writeFile} from 'node:fs/promises';
 import {createHash} from 'node:crypto';
 import {localizedStaticPaths} from './i18n.mjs';
 import {mapConcurrent} from './concurrent.mjs';
+import {mapPrerender,prerenderPath} from './prerender-pool.mjs';
 const isDynamic=pattern=>pattern.includes('[');
 
 export async function prerenderPages(stage, manifest, dev) {
@@ -11,12 +12,12 @@ export async function prerenderPages(stage, manifest, dev) {
   // getStaticProps/getStaticPaths for every route on every edit.
   const renderer = dev ? null : await import(pathToFileURL(path.join(stage, 'runtime/render.mjs')).href);
   const paths = new Set();
-  const seedsByRoute = new Map();
   const validatedDocuments = new Set();
   const staticListings = new Map();
+  const jobs=[],seedPaths=new Map(),seeds=new Map();
   // Error page data is available when another static page returns notFound.
   const ordered = [...manifest.routes].sort((left, right) => Number(!!right.errorStatus) - Number(!!left.errorStatus));
-  async function renderRoute(route) {
+  async function renderRoute(route,immediate=false) {
     if (route.kind !== 'page' || route.router === 'app') return;
     const modulePath = path.join(stage, route.module);
     const page = await import(pathToFileURL(modulePath).href);
@@ -59,10 +60,13 @@ export async function prerenderPages(stage, manifest, dev) {
       route.fallback = result.fallback;
       entries = result.paths;
     }
+    seedPaths.set(route.id,entries.map(entry=>entry.path));
+    const routeJobs=[];
     for (const entry of entries) {
       if (paths.has(entry.path)) throw new Error(`Multiple pages prerender the same path: ${entry.path}.`);
       paths.add(entry.path);
-      const rendered = await renderer.prerenderRoute({ ...manifest.config, manifest, distDir: stage, route, modulePath, path: entry.path, params: entry.params, client: route.client, css: route.css, pattern: route.pattern, errorStatus: route.errorStatus, buildId: manifest.buildId, production: !dev });
+      routeJobs.push(async()=>{
+      const rendered = await prerenderPath('pages',{ ...manifest.config, manifest, distDir: stage, route, modulePath, path: entry.path, params: entry.params, client: route.client, css: route.css, pattern: route.pattern, errorStatus: route.errorStatus, buildId: manifest.buildId, production: !dev },renderer.prerenderRoute);
       const file = `static/${createHash('sha256').update(entry.path).digest('hex').slice(0, 20)}.html`;
       await writeFile(path.join(stage, file), rendered.body);
       const seed = { routeId: route.id, path: entry.path, file, status: route.errorStatus || rendered.status || 200, headers: rendered.headers || {} };
@@ -73,18 +77,24 @@ export async function prerenderPages(stage, manifest, dev) {
         await writeFile(path.join(stage, seed.dataFile), rendered.dataJSON);
       }
       manifest.prerendered.push(seed);
-      if (!seedsByRoute.has(route.id)) seedsByRoute.set(route.id, []);
-      seedsByRoute.get(route.id).push(seed);
+      seeds.set(entry.path,seed);
+      });
     }
     if (route.fallback === true) {
-      const rendered = await renderer.renderFallback({ ...manifest.config, modulePath, path: route.pattern, params: {}, client: route.client, css: route.css, pattern: route.pattern, buildId: manifest.buildId, production: !dev });
+      routeJobs.push(async()=>{
+      const rendered = await prerenderPath('fallback',{ ...manifest.config, manifest, distDir: stage, route, modulePath, path: route.pattern, params: {}, client: route.client, css: route.css, pattern: route.pattern, buildId: manifest.buildId, production: !dev },renderer.renderFallback);
       route.fallbackFile = `static/fallback-${route.id}.html`;
       await writeFile(path.join(stage, route.fallbackFile), rendered.body);
+      });
     }
+    if(immediate)for(const run of routeJobs)await run();
+    else jobs.push({route,run:routeJobs});
   }
   // Error seeds must exist before ordinary pages can render notFound/failures.
-  for(const route of ordered.filter(route=>route.errorStatus))await renderRoute(route);
-  await mapConcurrent(ordered.filter(route=>!route.errorStatus),renderRoute);
+  for(const route of ordered.filter(route=>route.errorStatus))await renderRoute(route,true);
+  await mapConcurrent(ordered.filter(route=>!route.errorStatus),route=>renderRoute(route));
+  jobs.sort((a,b)=>manifest.routes.indexOf(a.route)-manifest.routes.indexOf(b.route));
+  await mapPrerender(jobs.flatMap(job=>job.run),run=>run());
   // Rendering errors first must not change the published route/seed ordering.
-  manifest.prerendered = manifest.routes.flatMap(route => seedsByRoute.get(route.id) || []);
+  manifest.prerendered = manifest.routes.flatMap(route => (seedPaths.get(route.id)||[]).flatMap(path=>seeds.has(path)?[seeds.get(path)]:[]));
 }

package/build/prerender-pool.mjs

@@ -0,0 +1,165 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { fork } from 'node:child_process';
+import { prerenderResources } from './prerender-config.mjs';
+import { createPrerenderCache } from './prerender-cache.mjs';
+import { mapConcurrent } from './concurrent.mjs';
+
+const storage = new AsyncLocalStorage();
+const MIB = 1024 * 1024;
+
+export async function withPrerenderSession(root, stage, manifest, config, callback, {signal}={}) {
+  if (storage.getStore()) return callback();
+  const session = new PrerenderPool(root, stage, manifest, config);
+  const abort=()=>void session.abort(signal.reason instanceof Error?signal.reason:new Error('Prerender cancelled'));
+  signal?.addEventListener('abort',abort,{once:true});
+  try { signal?.throwIfAborted();const result=await storage.run(session,callback);signal?.throwIfAborted();return result; }
+  finally { signal?.removeEventListener('abort',abort);await session.close(); }
+}
+
+export async function mapPrerender(items, run) {
+  const values = Array.from(items), session = storage.getStore();
+  if (!session) return mapConcurrent(values, run);
+  await session.prepare(values.length);
+  try { return await mapConcurrent(values, run, session.parallelism); }
+  catch (error) { await session.abort(error); throw error; }
+}
+
+export function prerenderPath(kind, options, local) {
+  const session = storage.getStore();
+  return session?.enabled ? session.run(kind, options) : local(options);
+}
+
+export class PrerenderPool {
+  constructor(root, stage, manifest, config, resources, dependencies = {}) {
+    this.root = root; this.stage = stage; this.manifest = manifest;
+    this.resources = prerenderResources(config, resources);
+    this.children = []; this.enabled = false; this.parallelism = this.resources.workers;
+    this.queue = []; this.revision = 0;
+    this.sequence = 0; this.failure = undefined; this.closing = false;
+    this.fork = dependencies.fork || fork;
+    this.killGraceMs = dependencies.killGraceMs ?? 5000;
+    this.updateTimeoutMs = dependencies.updateTimeoutMs ?? 30000;
+  }
+  async prepare(count) {
+    if (this.failure) throw this.failure;
+    if(this.preparing){await this.preparing;return;}
+    // Starting a second Node/React runtime costs more than a tiny local render.
+    if(this.enabled){await this.updateManifest();return;}
+    if (this.parallelism < 2 || count < (this.resources.explicit ? 2 : 4)) return;
+    this.preparing=(async()=>{
+      this.parallelism = Math.min(this.parallelism, count);
+      this.cache = await createPrerenderCache();
+      try {
+        if(this.failure)throw this.failure;
+        await Promise.all(Array.from({ length: this.parallelism }, () => this.start()));
+        this.enabled = true;
+      } catch (error) { await this.abort(error); throw error; }
+    })();
+    try{await this.preparing;}finally{this.preparing=undefined;}
+  }
+  start() {
+    return new Promise((resolve, reject) => {
+      const child = this.fork(new URL('./prerender-process-worker.mjs', import.meta.url), [], {
+        cwd: this.root, execArgv: [`--max-old-space-size=${this.resources.heapMb}`], serialization: 'advanced',
+        env: { ...process.env, ...this.cache.env }, stdio: ['ignore', 'inherit', 'inherit', 'ipc'], windowsHide: true,
+      });
+      const worker = { child, rss: 0, busy: false, ready: false, updates: new Map() };
+      this.children.push(worker);
+      // A failed spawn emits error+close without exit. close is also the final
+      // stdio/IPC terminal event for a successfully spawned process.
+      worker.exited = new Promise(done => child.once('close', done));
+      const timeout = setTimeout(() => void this.abort(new Error('Prerender worker startup exceeded 30 seconds')), 30_000);
+      child.once('close',()=>clearTimeout(timeout));
+      worker.startReject = reject;
+      child.on('error', error => void this.abort(error));
+      child.on('exit', (code, signal) => {
+        clearTimeout(timeout);
+        if (!this.closing) void this.abort(new Error(`Prerender worker exited (${signal || code}); its path was not retried`));
+      });
+      child.on('message', message => {
+        if (Number.isSafeInteger(message.rss)) worker.rss = message.rss;
+        if (this.children.reduce((sum, value) => sum + value.rss, 0) > this.resources.maxMemoryMb * MIB) {
+          void this.abort(new Error(`Prerender workers exceeded the ${this.resources.maxMemoryMb} MiB RSS budget`)); return;
+        }
+        if (message.type === 'ready') { clearTimeout(timeout); worker.ready = true; worker.startReject = undefined; resolve(); }
+        else if(message.type==='updated'){const update=worker.updates.get(message.revision);worker.updates.delete(message.revision);clearTimeout(update?.timer);update?.resolve();}
+        else if (message.type === 'failure') { void this.abort(Object.assign(new Error(message.error), { code: message.code })); }
+        else if (message.type === 'result') {
+          if (!worker.current || worker.current.id !== message.id) { void this.abort(new Error('Invalid prerender worker response')); return; }
+          clearTimeout(worker.current.timer);
+          const current = worker.current; worker.current = undefined; worker.busy = false; current.resolve(message.rendered);this.dispatch();
+        }
+      });
+      child.send({ type: 'init', stage: this.stage, manifest: this.manifest }, error => { if (error) void this.abort(error); });
+    });
+  }
+  run(kind, options) {
+    if (this.failure) return Promise.reject(this.failure);
+    if(this.closing||this.closed||!this.enabled)return Promise.reject(new Error('Prerender pool is not open'));
+    if(this.queue.length>=32)return Promise.reject(new Error('Prerender scheduler exceeded its bounded waiting queue'));
+    return new Promise((resolve, reject) => {
+      this.queue.push({kind,options,resolve,reject});this.dispatch();
+    });
+  }
+  dispatch(){
+    if(this.failure||this.closing)return;
+    for(const worker of this.children){
+      if(!worker.ready||worker.busy||!this.queue.length)continue;
+      const {kind,options,resolve,reject}=this.queue.shift();
+      worker.busy=true;const id=++this.sequence;
+      const timeoutMs = Math.min(300_000, (options.route?.cacheConfig?.maxDuration || 60) * 1000);
+      const timer = setTimeout(() => void this.abort(new Error(`Prerender path ${options.path} exceeded ${timeoutMs} ms; it was not retried`)), timeoutMs);
+      worker.current = { id, resolve, reject, timer };
+      const { manifest, ...serialized } = options;
+      worker.child.send({ type: 'job', id, kind, options: serialized }, error => { if (error) void this.abort(error); });
+    }
+  }
+  async updateManifest(){
+    const revision=++this.revision;
+    await Promise.all(this.children.map(worker=>new Promise((resolve,reject)=>{
+      const timer=setTimeout(()=>void this.abort(new Error('Prerender manifest acknowledgement timed out')),this.updateTimeoutMs);
+      worker.updates.set(revision,{resolve,reject,timer});
+      worker.child.send({type:'update',revision,manifest:this.manifest},error=>{if(error)void this.abort(error);});
+    })));
+  }
+  async abort(error) {
+    this.failure ||= error;
+    this.closing = true;
+    for(const job of this.queue.splice(0))job.reject(this.failure);
+    for (const worker of this.children) {
+      worker.startReject?.(this.failure); worker.startReject = undefined;
+      for(const update of worker.updates.values()){clearTimeout(update.timer);update.reject(this.failure);}worker.updates.clear();
+      if (worker.current) { clearTimeout(worker.current.timer); worker.current.reject(this.failure); worker.current = undefined; }
+    }
+    await this.stopChildren(true);
+  }
+  stopChildren(force) {
+    if(this.stopping)return this.stopping;
+    this.stopping=(async()=>{
+      for(const {child}of this.children){
+        if(!child.pid||child.exitCode!==null||child.signalCode!==null)continue;
+        if(force)child.kill('SIGTERM');
+        else child.send({type:'close'},()=>{});
+      }
+      // User code may install a SIGTERM handler. Arm escalation before waiting
+      // for any terminal event, including on the error/cancellation path.
+      const killer=setTimeout(()=>{
+        for(const {child}of this.children)if(child.pid&&child.exitCode===null&&child.signalCode===null)child.kill('SIGKILL');
+      },this.killGraceMs);
+      try{await Promise.all(this.children.map(worker=>worker.exited));}
+      finally{clearTimeout(killer);}
+    })();
+    return this.stopping;
+  }
+  async close() {
+    if (this.closed) return this.closed;
+    this.closed = (async () => {
+      await this.preparing?.catch(()=>{});
+      if(this.queue.length||this.children.some(worker=>worker.current))await this.abort(new Error('Prerender session closed with unfinished paths; they were not retried'));
+      this.closing = true;
+      try { await this.stopChildren(Boolean(this.failure)); }
+      finally { await this.cache?.close(); }
+    })();
+    return this.closed;
+  }
+}