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

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;
+  }
+}

package/build/prerender-process-worker.mjs

@@ -0,0 +1,58 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+let stage, manifest, busy = false;
+let closeRuntime;
+const send = value => new Promise((resolve, reject) => process.send(value, error => error ? reject(error) : resolve()));
+const memory = () => ({ rss: process.memoryUsage().rss, pid: process.pid });
+const pulse = setInterval(() => { if (process.connected) process.send({ type: 'memory', ...memory() }); }, 100);
+pulse.unref();
+
+process.on('message', async message => {
+  try {
+    if (message.type === 'init') {
+      if (stage) throw new Error('Prerender worker was initialized twice');
+      ({ stage, manifest } = message);
+      await send({ type: 'ready', ...memory() });
+      return;
+    }
+    if (message.type === 'update') {
+      manifest = message.manifest;
+      await send({ type: 'updated', revision: message.revision });
+      return;
+    }
+    if (message.type === 'close') {
+      if (busy) throw new Error('Cannot close an active prerender worker');
+      if (closeRuntime) await closeRuntime();
+      clearInterval(pulse);
+      process.disconnect();
+      return;
+    }
+    if (message.type !== 'job' || !stage || busy) throw new Error('Invalid prerender worker operation');
+    busy = true;
+    const options = { ...message.options, manifest };
+    let rendered;
+    if (message.kind === 'pages' || message.kind === 'fallback') {
+      const runtime = await import(pathToFileURL(path.join(stage, 'runtime/render.mjs')).href);
+      rendered = await runtime[message.kind === 'pages' ? 'prerenderRoute' : 'renderFallback'](options);
+    } else if (message.kind === 'app' || message.kind === 'handler') {
+      const runtime = await import(pathToFileURL(path.join(stage, `runtime/${message.kind === 'app' ? 'app-static' : 'route-static'}.mjs`)).href);
+      if (message.kind === 'app') closeRuntime ||= (await import(pathToFileURL(path.join(stage, 'runtime/app-render.mjs')).href)).closeAppRuntime;
+      rendered = await runtime[message.kind === 'app' ? 'prerenderAppRoute' : 'prerenderAppRouteHandler'](options);
+    } else throw new Error('Unknown prerender job kind');
+    busy = false;
+    // Runtime prerender entrypoints already flush their request/cache work.
+    // Do not transfer retained finalizers, contexts or incidental worker data.
+    const result = {};
+    for (const field of ['body','dataJSON','status','headers','revalidate','generatedAt','tags','paths','partial','metadata','dynamic','reason','flight']) {
+      if (rendered[field] !== undefined) result[field] = rendered[field];
+    }
+    await send({ type: 'result', id: message.id, rendered: result, ...memory() });
+  } catch (error) {
+    busy = false;
+    await send({ type: 'failure', id: message.id, error: error.stack || error.message, code: error.code, ...memory() }).catch(() => {});
+  }
+});
+
+// A dead coordinator must not leave application work or an RSC thread behind.
+process.once('disconnect', () => process.exit(0));

package/build/prerender-worker.mjs

@@ -1,9 +1,9 @@
-import {prerenderPages} from './prerender-pages.mjs';
-import {prerenderApp} from './app-static.mjs';
-process.once('message',async({stage,manifest})=>{
+import {prerenderProduction} from './production-builder.mjs';
+const controller=new AbortController();
+process.on('message',message=>{if(message.type==='abort')controller.abort(new Error('Production prerender cancelled by supervisor'));});
+process.once('message',async({root,stage,manifest,options})=>{
   try{
-    await prerenderPages(stage,manifest,false);
-    await prerenderApp(stage,manifest,false);
+    await prerenderProduction(root,stage,manifest,{...options,signal:controller.signal});
     process.send({ok:true,manifest},()=>process.exit(0));
   }catch(error){process.send({ok:false,error:error.stack||error.message},()=>process.exit(1));}
 });

package/build/production-builder.mjs

@@ -4,6 +4,9 @@ import path from 'node:path';
 import {watchProject} from '../runtime/watch-project.mjs';
 import {createDevChangeFilter} from '../runtime/dev-file-changes.mjs';
 import {incrementalCompilerStats} from './incremental.mjs';
+import {withPrerenderSession} from './prerender-pool.mjs';
+import {prerenderPages} from './prerender-pages.mjs';
+import {prerenderApp} from './app-static.mjs';
 
 /** Explicit reusable build session for integrations; always dispose it. */
 export async function createBuilder(projectRoot,options={}){
@@ -21,15 +24,61 @@ export async function createBuilder(projectRoot,options={}){
 
 // Application imports, SSG and RSC isolates belong to one build only. Keeping
 // esbuild's graph must not retain application globals or execute stale modules.
-export function isolatedPrerender(root,stage,manifest){
-  return new Promise((resolve,reject)=>{
-    const child=fork(new URL('./prerender-worker.mjs',import.meta.url),[],{cwd:root,execArgv:[],stdio:['ignore','inherit','inherit','ipc'],windowsHide:true});
-    let result;
-    const timeout=setTimeout(()=>{child.kill();reject(new Error('Production prerender exceeded ten minutes'));},600000);
-    child.once('error',error=>{clearTimeout(timeout);reject(error);});
-    child.on('message',value=>{result=value;});
-    child.once('exit',(code,signal)=>{clearTimeout(timeout);result?.ok&&code===0?resolve(result.manifest):reject(new Error(result?.error||`Prerender exited ${signal||code}`));});
-    child.send({stage,manifest});
+export async function prerenderProduction(root,stage,manifest,{prerender,signal}={}){
+  await withPrerenderSession(root,stage,manifest,prerender,async()=>{
+    await prerenderPages(stage,manifest,false);
+    await prerenderApp(stage,manifest,false);
+  },{signal});
+  return manifest;
+}
+
+export function isolatedPrerender(root, stage, manifest, options = {}, dependencies = {}) {
+  const spawn = dependencies.fork || fork;
+  const { timeoutMs = 600000, abortGraceMs = 30000, killGraceMs = 5000 } = dependencies;
+  return new Promise((resolve, reject) => {
+    const child = spawn(new URL('./prerender-worker.mjs', import.meta.url), [], {
+      cwd: root, execArgv: [], stdio: ['ignore', 'inherit', 'inherit', 'ipc'], windowsHide: true,
+    });
+    let result, failure, terminateTimer, killTimer, closed = false, terminating = false;
+    const running = () => !closed && child.pid && child.exitCode === null && child.signalCode === null;
+    const terminate = () => {
+      if (!running() || terminating) return;
+      terminating = true;
+      child.kill('SIGTERM');
+      // SIGTERM is an application-observable signal on POSIX. Never wait on
+      // its handler before arming the unconditional final termination.
+      killTimer ||= setTimeout(() => { if (running()) child.kill('SIGKILL'); }, killGraceMs);
+    };
+    const fail = error => {
+      failure ||= error;
+      clearTimeout(timeout);
+      clearTimeout(terminateTimer);
+      terminate();
+    };
+    const send = message => {
+      if (!child.connected) { fail(new Error('Prerender coordinator IPC disconnected')); return; }
+      try { child.send(message, error => { if (error && !closed) fail(error); }); }
+      catch (error) { fail(error); }
+    };
+    const timeout = setTimeout(() => {
+      failure ||= new Error('Production prerender exceeded ten minutes');
+      // Cooperative cancellation drains the coordinator's owned path workers.
+      // A blocked application generator may never process this IPC message.
+      send({ type: 'abort' });
+      if (!closed) terminateTimer = setTimeout(terminate, abortGraceMs);
+    }, timeoutMs);
+    child.on('error', fail);
+    child.once('disconnect', () => { if (!closed && !result) fail(new Error('Prerender coordinator IPC disconnected before completion')); });
+    child.on('message', value => { if (typeof value?.ok === 'boolean') result = value; });
+    // Failed spawns emit error+close without exit. Publish/reject only after
+    // the final terminal event, so stage cleanup cannot race this process.
+    child.once('close', (code, signal) => {
+      closed = true;
+      clearTimeout(timeout); clearTimeout(terminateTimer); clearTimeout(killTimer);
+      if (!failure && result?.ok && code === 0) resolve(result.manifest);
+      else reject(failure || new Error(result?.error || `Prerender exited ${signal || code}`));
+    });
+    send({ root, stage, manifest, options });
   });
 }