@thomas.f/prnext 0.1.20-alpha → 0.1.21-alpha

package/runtime/loopback-rpc.mjs

@@ -0,0 +1,92 @@
+import net from 'node:net';
+import {createHmac,randomBytes,timingSafeEqual} from 'node:crypto';
+
+const protocol='prnext-loopback-v2',noncePattern=/^[a-f0-9]{64}$/;
+const nonce=()=>randomBytes(32).toString('hex');
+const authenticationError=()=>Object.assign(Error('Loopback peer authentication failed'),{code:'ERR_PRNEXT_PEER_AUTH'});
+const proof=(token,context,role,client,server,...body)=>createHmac('sha256',token).update(JSON.stringify([protocol,context,role,client,server,...body])).digest('hex');
+function matches(supplied,expected){return typeof supplied==='string'&&noncePattern.test(supplied)&&timingSafeEqual(Buffer.from(supplied,'hex'),Buffer.from(expected,'hex'));}
+function encode(value,limit){const body=JSON.stringify(value);if(typeof body!=='string'||Buffer.byteLength(body)>limit)throw Error('Loopback control body is too large');return body;}
+function send(socket,value){socket.write(JSON.stringify({protocol,...value})+'\n');}
+
+function frames(socket,limit,receive,fail){
+  let buffer=Buffer.alloc(0);
+  socket.on('data',chunk=>{
+    try{
+      buffer=Buffer.concat([buffer,chunk]);
+      for(;;){
+        const end=buffer.indexOf(10),maximum=limit();
+        if(end<0){if(buffer.length>maximum)throw Error('Loopback control frame is too large');return;}
+        if(end>maximum)throw Error('Loopback control frame is too large');
+        const message=JSON.parse(buffer.subarray(0,end).toString('utf8'));buffer=buffer.subarray(end+1);
+        if(!message||message.protocol!==protocol)throw authenticationError();
+        receive(message);if(socket.destroyed)return;
+      }
+    }catch(error){fail(error);}
+  });
+}
+
+// One fresh transcript authorizes exactly one payload. Role and context labels
+// prevent reflection and cross-service reuse; both nonces prevent replay across
+// connections and watchdog restarts. The first client frame contains only a
+// nonce; the command follows a verified server proof. The key is never sent.
+export function requestLoopback({port,token},request,{context,timeout=120000,signal,maxRequestBytes=65536,maxResponseBytes=1024*1024}={}) {
+  if(signal?.aborted)return Promise.reject(signal.reason||Error('Loopback request aborted'));
+  let body;try{body=encode(request,maxRequestBytes);}catch(error){return Promise.reject(error);}
+  return new Promise((resolve,reject)=>{
+    const socket=net.connect({host:'127.0.0.1',port});
+    const client=nonce();let server,state='challenge',finished=false;
+    const finish=(error,value)=>{if(finished)return;finished=true;clearTimeout(handshake);clearTimeout(total);signal?.removeEventListener('abort',abort);socket.destroy();error?reject(error):resolve(value);};
+    const abort=()=>finish(signal.reason||Error('Loopback request aborted'));
+    const total=setTimeout(()=>finish(Error('Loopback request timed out')),timeout);
+    const handshake=setTimeout(()=>finish(authenticationError()),Math.min(5000,timeout));
+    signal?.addEventListener('abort',abort,{once:true});
+    socket.once('connect',()=>send(socket,{type:'hello',client}));
+    socket.on('error',error=>finish(error));
+    socket.on('end',()=>finish(state==='challenge'?authenticationError():Error('Loopback peer disconnected')));
+    socket.on('close',()=>{if(!finished)finish(state==='challenge'?authenticationError():Error('Loopback peer disconnected'));});
+    frames(socket,()=>state==='challenge'?1024:2*maxResponseBytes+1024,message=>{
+      if(state==='challenge'){
+        if(message.type!=='challenge'||typeof message.server!=='string'||!noncePattern.test(message.server)||!matches(message.proof,proof(token,context,'server',client,message.server)))throw authenticationError();
+        server=message.server;state='response';clearTimeout(handshake);
+        send(socket,{type:'request',body,proof:proof(token,context,'request',client,server,body)});
+        return;
+      }
+      if(state!=='response'||message.type!=='response'||typeof message.body!=='string'||Buffer.byteLength(message.body)>maxResponseBytes||!matches(message.proof,proof(token,context,'response',client,server,body,message.body)))throw authenticationError();
+      const result=JSON.parse(message.body);state='done';
+      if(!result||typeof result.ok!=='boolean')throw Error('Invalid loopback response');
+      finish(result.ok?null:Error(typeof result.error==='string'?result.error:'Loopback request failed'),result.value);
+    },error=>finish(error));
+  });
+}
+
+export function serveLoopback(socket,{token,context,handle,timeout=125000,handshakeTimeout=5000,maxRequestBytes=65536,maxResponseBytes=1024*1024}) {
+  const controller=new AbortController();let client,server,requestBody,state='hello';
+  const deadlineMs=Date.now()+timeout;
+  const close=()=>{state='closed';controller.abort();socket.destroy();};
+  const total=setTimeout(close,timeout),handshake=setTimeout(close,Math.min(handshakeTimeout,timeout));
+  socket.on('error',()=>{});
+  socket.once('close',()=>{state='closed';clearTimeout(total);clearTimeout(handshake);controller.abort();});
+  socket.on('end',close);
+  frames(socket,()=>state==='hello'?1024:2*maxRequestBytes+1024,message=>{
+    if(state==='hello'){
+      if(message.type!=='hello'||typeof message.client!=='string'||!noncePattern.test(message.client))throw authenticationError();
+      client=message.client;server=nonce();state='request';
+      send(socket,{type:'challenge',server,proof:proof(token,context,'server',client,server)});return;
+    }
+    if(state!=='request'||message.type!=='request'||typeof message.body!=='string'||Buffer.byteLength(message.body)>maxRequestBytes||!matches(message.proof,proof(token,context,'request',client,server,message.body)))throw authenticationError();
+    requestBody=message.body;const request=JSON.parse(requestBody);
+    if(!request||typeof request!=='object'||Array.isArray(request))throw Error('Invalid loopback request');
+    clearTimeout(handshake);state='busy';
+    const reply=result=>{
+      if(state!=='busy')return;
+      let body;
+      try{body=encode(result,maxResponseBytes);}catch{body=encode({ok:false,error:'Loopback response is too large'},maxResponseBytes);}
+      state='done';socket.end(JSON.stringify({protocol,type:'response',body,proof:proof(token,context,'response',client,server,requestBody,body)})+'\n');
+    };
+    Promise.resolve().then(()=>{
+      if(controller.signal.aborted)throw Error('Loopback client disconnected');
+      return handle(request,{signal:controller.signal,deadlineMs});
+    }).then(value=>reply({ok:true,value}),error=>reply({ok:false,error:String(error.message).slice(0,2048)})).catch(close);
+  },close);
+}

package/runtime/native-ppr.mjs

@@ -7,6 +7,61 @@ export const NATIVE_PPR_ARTIFACT_BYTES = 2 * 1024 * 1024;
 export const NATIVE_PPR_PREFIX_BYTES = 128 * 1024;
 export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
 
+// Only immutable build JSON is retained, after the caller verified the current
+// file bytes. No live model, decoder, request context or continuation is cached.
+export class NativePprArtifactCache {
+  constructor({maxEntries=8,maxBytes=4*1024*1024,maxEntryBytes=1024*1024,maxNodes=8192}={}) {
+    for(const value of [maxEntries,maxBytes,maxEntryBytes,maxNodes])if(!Number.isSafeInteger(value)||value<0)throw new TypeError('Invalid native PPR parsing cache budget');
+    this.maxEntries=maxEntries;this.maxBytes=maxBytes;this.maxEntryBytes=maxEntryBytes;this.maxNodes=maxNodes;
+    this.entries=new Map();this.bytes=0;this.hits=0;this.parses=0;
+  }
+  parse(filename,bytes,route,descriptor) {
+    const key=JSON.stringify([filename,descriptor.artifactHash,route.client||null]);
+    let entry=this.entries.get(key);
+    if(entry){this.hits++;this.entries.delete(key);this.entries.set(key,entry);}
+    else{
+      this.parses++;
+      const artifact=JSON.parse(bytes);
+      const prefix=Buffer.from(partialShell(artifact,route).replace(/<\/body><\/html>$/i,''));
+      entry={artifact,prefixHash:sha256(prefix),identity:sha256(artifact.flight)};
+      if(artifact.version!==1||!artifact.postponed||artifact.complete||artifact.generic||entry.prefixHash!==descriptor.prefixHash||entry.identity!==descriptor.identity)throw new Error('Invalid native PPR snapshot');
+      // Reserve substantial expansion for JSON slots/strings before walking.
+      // This is a conservative admission estimate, not an exact V8 heap size.
+      let size=bytes.length*16+key.length*2+256;
+      if(this.maxEntries&&size<=Math.min(this.maxBytes,this.maxEntryBytes)){
+        const pending=[artifact],objects=[];let nodes=1,eligible=this.maxNodes>0;
+        while(eligible&&pending.length){
+          const value=pending.pop();objects.push(value);size+=128;
+          // JSON arrays are dense: reject wide arrays before enumerating keys
+          // or allocating any list of their primitive/object children.
+          if(Array.isArray(value)&&value.length>this.maxNodes-nodes){eligible=false;break;}
+          for(const name in value){
+            if(!Object.hasOwn(value,name))continue;
+            if(++nodes>this.maxNodes){eligible=false;break;}
+            const child=value[name];size+=16+name.length*2+(typeof child==='string'?child.length*2:0);
+            if(size>Math.min(this.maxBytes,this.maxEntryBytes)){eligible=false;break;}
+            if(child&&typeof child==='object'){
+              if(Array.isArray(child)&&child.length>this.maxNodes-nodes){eligible=false;break;}
+              pending.push(child);
+            }
+          }
+        }
+        if(eligible&&!pending.length&&size<=Math.min(this.maxBytes,this.maxEntryBytes)){
+          for(const value of objects)Object.freeze(value);
+          while(this.entries.size&&(this.entries.size>=this.maxEntries||this.bytes+size>this.maxBytes)){
+            const [oldKey,old]=this.entries.entries().next().value;this.entries.delete(oldKey);this.bytes-=old.size;
+          }
+          entry.size=size;this.entries.set(key,entry);this.bytes+=size;
+        }
+      }
+    }
+    // Descriptor bindings remain authoritative even when the public JSON hit.
+    if(entry.prefixHash!==descriptor.prefixHash||entry.identity!==descriptor.identity)throw new Error('Invalid native PPR snapshot');
+    return entry.artifact;
+  }
+}
+const parsedArtifacts=new NativePprArtifactCache();
+
 export function partialShell(artifact, route) {
   const bootstrap = '<script>self.__PRNEXT_FLIGHT_STREAM__=self.__PRNEXT_FLIGHT_STREAM__||[];</script>' +
     (route.client ? `<script type="module" async src="${escapeHtml(route.client)}"></script>` : '');
@@ -18,7 +73,7 @@ export function partialShell(artifact, route) {
 // This is a private transport field, never an HTTP header. Rust has already
 // checked cache generation and committed these exact build bytes. Pinning the
 // same artifact gives the request one snapshot even if invalidation races Node.
-export async function nativePprArtifact({renderMode, manifest, route, url, distDir}) {
+export async function nativePprArtifact({renderMode, manifest, route, url, distDir},cache=parsedArtifacts) {
   if (!renderMode?.startsWith('native-ppr:')) return null;
   if (!manifest.config?.nativePprShell || manifest.dev || !/^[a-f\d]{64}$/.test(renderMode.slice(11))) throw new Error('Invalid native PPR continuation');
   const pathname = new URL(url).pathname;
@@ -28,8 +83,6 @@ export async function nativePprArtifact({renderMode, manifest, route, url, distD
   if (!descriptor.artifact.startsWith('static/') || !filename.startsWith(path.resolve(distDir) + path.sep) || (await stat(filename)).size > NATIVE_PPR_ARTIFACT_BYTES) throw new Error('Invalid native PPR artifact path or size');
   const bytes = await readFile(filename);
   if (bytes.length > NATIVE_PPR_ARTIFACT_BYTES || sha256(bytes) !== descriptor.artifactHash) throw new Error('Native PPR artifact changed after publication');
-  const artifact = JSON.parse(bytes);
-  const prefix = Buffer.from(partialShell(artifact, route).replace(/<\/body><\/html>$/i, ''));
-  if (artifact.version !== 1 || !artifact.postponed || artifact.complete || artifact.generic || sha256(prefix) !== descriptor.prefixHash || sha256(artifact.flight) !== descriptor.identity) throw new Error('Invalid native PPR snapshot');
+  const artifact = cache.parse(filename,bytes,route,descriptor);
   return {artifact, descriptor};
 }

package/runtime/persistent/client.mjs

@@ -64,7 +64,7 @@ async function ensure(connection) {
     child.on('error', () => {}); child.unref();
   }
   for (let i = 0; i < 200; i++) {
-    try { const result = await rpc(connection, { command: 'ping' }, 1500); if (result.version !== 1) throw new Error('Supervisor protocol mismatch. Run prn pdown before upgrading.'); if (result.ready) return; }
+    try { const result = await rpc(connection, { command: 'ping' }, 1500); if (result.version !== 2) throw new Error('Supervisor protocol mismatch. Stop the supervisor with its current PRNext version before upgrading.'); if (result.ready) return; }
     catch (error) { if (!['ECONNREFUSED', 'ECONNRESET'].includes(error.code)) throw error; }
     await delay(100);
   }

package/runtime/persistent/common.mjs

@@ -1,9 +1,9 @@
 import { mkdir, readFile, writeFile, realpath, rm } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
-import net from 'node:net';
 import path from 'node:path';
 import { rename } from '../fs.mjs';
+import { requestLoopback } from '../loopback-rpc.mjs';
 
 export const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
 export const homeDirectory = () => path.resolve(process.env.PRNEXT_PM_HOME || path.join(homedir(), '.prnext', 'processes'));
@@ -47,21 +47,10 @@ export function validHealthPath(value) {
   return value;
 }
 export async function rpc(connection, request, timeout = 120000) {
-  return new Promise((resolve, reject) => {
-    const socket = net.connect({ host: '127.0.0.1', port: connection.port });
-    socket.setEncoding('utf8');
-    let buffer = '', finished = false;
-    const finish = (error, value) => { if (finished) return; finished = true; socket.destroy(); error ? reject(error) : resolve(value); };
-    socket.setTimeout(timeout, () => finish(new Error('Supervisor request timed out. Check prn plogs --supervisor.')));
-    socket.on('error', error => finish(error));
-    socket.once('connect', () => socket.write(JSON.stringify({ ...request, token: connection.token }) + '\n'));
-    socket.on('data', chunk => {
-      buffer += chunk.toString();
-      if (buffer.length > 1024 * 1024) return finish(new Error('Supervisor response is too large'));
-      if (!buffer.includes('\n')) return;
-      try { const result = JSON.parse(buffer.slice(0, buffer.indexOf('\n'))); finish(result.ok ? null : new Error(result.error || 'Supervisor request failed'), result.value); }
-      catch (error) { finish(error); }
-    });
-    socket.on('end', () => { if (!finished) finish(new Error('Supervisor disconnected')); });
-  });
+  try { return await requestLoopback(connection, request, { context: 'persistent-supervisor', timeout }); }
+  catch (error) {
+    if (error.code === 'ERR_PRNEXT_PEER_AUTH') error.message = 'Cannot authenticate the supervisor control listener. If an older PRNext supervisor is running, stop it with that version\'s prn pdown before upgrading; saved apps are preserved.';
+    else if (error.message === 'Loopback request timed out') error.message = 'Supervisor request timed out. Check prn plogs --supervisor.';
+    throw error;
+  }
 }

package/runtime/persistent/daemon.mjs

@@ -76,7 +76,7 @@ async function snapshot(app) {
     if (path.relative(root, container).startsWith('..') || path.isAbsolute(path.relative(root, container))) throw new Error('Managed builds must remain inside the project');
     await cp(source, destination, { recursive: true, verbatimSymlinks: true, filter: file => file !== path.join(source, 'standalone') });
     if (await readFile(path.join(source, 'manifest.json'), 'utf8') !== before || await readFile(path.join(destination, 'manifest.json'), 'utf8') !== before) throw new Error('Build changed while copying. Finish prn build, then retry prn prestart.');
-    return { relative, buildId: manifest.buildId || null };
+    return { relative, buildId: manifest.buildId || null, server: manifest.config?.server || {} };
   } catch (error) { await removeSnapshot(app, relative); throw error; }
 }
 async function stopGeneration(app, generation, drain = true) {

package/runtime/persistent/native-proxy.mjs

@@ -53,7 +53,7 @@ export async function nativeGateway(config,options){
   manager??=new NativeProxy(config.binary,options);await manager.ready;
   const app=config.name;await manager.request('listen',{app,hostname:config.hostname,port:config.port});
   return {pid:manager.pid,
-    activate:g=>manager.request('activate',{app,generation:g.relative,port:g.port}),
+    activate:g=>manager.request('activate',{app,generation:g.relative,port:g.port,server:g.server}),
     pause:g=>manager.request('pause',{app,...(g?{generation:g.relative}:{})}),
     retire:(g,timeout)=>manager.request('retire',{app,generation:g.relative,timeout},timeout+5000),
     counts:async()=> (await manager.request('status',{app})).generations,

package/runtime/persistent/watchdog.mjs

@@ -1,10 +1,10 @@
 import { fork } from 'node:child_process';
 import { createServer } from 'node:net';
-import { timingSafeEqual } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { initializeHome, environment, delay } from './common.mjs';
 import { RotatingLog } from './logger.mjs';
+import { serveLoopback } from '../loopback-rpc.mjs';
 
 const connection = await initializeHome(process.argv[2]);
 const log = new RotatingLog(path.join(connection.home, 'logs', 'supervisor.log'));
@@ -12,35 +12,20 @@ const pending = new Map(), children = new Set(), sockets = new Set();
 const shutdownReplies = [];
 let daemon, ready = false, closing = false, counter = 0, heartbeat = Date.now(), failures = 0, restartTimer;
 const server = createServer(socket => {
-  socket.setEncoding('utf8');
   sockets.add(socket); socket.once('close', () => sockets.delete(socket));
-  socket.setTimeout(125000, () => socket.destroy());
-  let buffer = '', received = false;
-  socket.on('error', () => {});
-  socket.on('data', chunk => {
-    if (received) return;
-    buffer += chunk.toString();
-    if (buffer.length > 65536) { socket.destroy(); return; }
-    if (!buffer.includes('\n')) return;
-    received = true;
-    let message;
-    const reply = result => socket.end(JSON.stringify(result) + '\n');
-    try {
-      message = JSON.parse(buffer.slice(0, buffer.indexOf('\n')));
-      const supplied = Buffer.from(typeof message.token === 'string' ? message.token : '');
-      const expected = Buffer.from(connection.token);
-      if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) throw new Error('Invalid supervisor credentials');
-      delete message.token;
-      if (message.command === 'ping') { reply({ ok: true, value: { version: 1, pid: process.pid, daemonPid: daemon?.pid || null, ready } }); return; }
-      if (message.command === 'shutdown') { shutdownReplies.push(reply); void shutdown(); return; }
+  serveLoopback(socket, { token: connection.token, context: 'persistent-supervisor', handle: async message => {
+      if (message.command === 'ping') return { version: 2, pid: process.pid, daemonPid: daemon?.pid || null, ready };
+      if (message.command === 'shutdown') return new Promise(resolve => { shutdownReplies.push(resolve); void shutdown(); });
       if (!ready || !daemon?.connected) throw new Error('Supervisor is recovering. Retry shortly.');
       if (pending.size >= 32) throw new Error('Supervisor is busy. Retry shortly.');
       const id = ++counter;
-      pending.set(id, reply);
-      socket.once('close', () => pending.delete(id));
-      daemon.send({ type: 'request', id, request: message }, error => { if (error) { pending.delete(id); reply({ ok: false, error: error.message }); } });
-    } catch (error) { reply({ ok: false, error: error.message }); }
-  });
+      return new Promise((resolve, reject) => {
+        const reply = result => result.ok ? resolve(result.value) : reject(Error(result.error || 'Supervisor request failed'));
+        pending.set(id, reply);
+        socket.once('close', () => { pending.delete(id); reject(Error('Supervisor client disconnected')); });
+        daemon.send({ type: 'request', id, request: message }, error => { if (error) { pending.delete(id); reject(error); } });
+      });
+  } });
 });
 server.maxConnections = 64;
 try { await new Promise((resolve, reject) => { server.once('error', reject); server.listen(connection.port, '127.0.0.1', resolve); }); }
@@ -100,7 +85,7 @@ async function shutdown() {
   log.message('Supervisor stopped.');
   await new Promise(resolve => log.end(resolve));
   server.close();
-  for (const reply of shutdownReplies) reply({ ok: true, value: 'Supervisor stopped; enabled apps will return on the next launch.' });
+  for (const reply of shutdownReplies) reply('Supervisor stopped; enabled apps will return on the next launch.');
   await delay(50);
   for (const socket of sockets) socket.destroy();
   process.exit(0);

package/runtime/prewarm.mjs

@@ -0,0 +1,35 @@
+// Framework preparation only: never import a route, render an app component or call
+// application code. Imports cannot be unloaded or interrupted inside V8; the
+// native parent bounds bootstrap and owns cancellation of the entire child.
+export async function prewarmFramework({ routes, options, load, signal }, {
+  now = () => performance.now(), rss = () => process.memoryUsage().rss,
+} = {}) {
+  if (!Number.isFinite(options?.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 30000
+    || !Number.isFinite(options?.maxRssMb) || options.maxRssMb <= 0 || options.maxRssMb > 2048) {
+    throw new TypeError('Invalid framework prewarm budget');
+  }
+  const started = now(), deadline = started + options.timeoutMs, loaded = [];
+  const available = () => signal?.aborted ? 'cancelled'
+    : now() >= deadline ? 'timeout'
+    : rss() >= options.maxRssMb * 1024 * 1024 ? 'rss' : undefined;
+  const result = reason => ({ ready: !reason, reason, loaded, durationMs: Math.max(0, now() - started) });
+  const nodeRoutes = routes.filter(route => (route.cacheConfig?.runtime ?? route.handlerConfig?.runtime) !== 'edge');
+  const modules = [];
+  if (nodeRoutes.some(route => route.router === 'app' && route.kind === 'page')) modules.push('app-render');
+  if (nodeRoutes.some(route => route.router !== 'app' && route.kind === 'page')) modules.push('render');
+  if (nodeRoutes.some(route => route.kind === 'api')) modules.push('api');
+  for (const name of modules) {
+    let reason = available();
+    if (reason) return result(reason);
+    const module = await load(name);
+    reason = available();
+    if (reason) return result(reason);
+    if (name === 'app-render') {
+      await module.prewarmAppRenderer({ ...options, timeoutMs: Math.max(1, deadline - now()), signal });
+      reason = available();
+      if (reason) return result(reason);
+    }
+    loaded.push(name);
+  }
+  return result(available());
+}

package/runtime/rsc-worker.mjs

@@ -32,6 +32,7 @@ import { PartialTemplates, canResumePartialDirectly, partialTemplateReuse } from
 import { createAfterScope } from '../compat/after.cjs';
 import {renderKeyFor} from './app-render-key.mjs';
 import { selectAppStyles } from './app-style-selection.mjs';
+import {createFlightMeasurement} from './flight-diagnostics.mjs';
 
 installFetchCache();
 if (process.env.PRNEXT_INSPECT_DIR) parentPort.postMessage({type:'rsc-ready'});
@@ -173,7 +174,24 @@ function errorBoundary(entry, error, production, before = Infinity) {
   return index < 0 ? null : { kind: 'error', index, error: publicError(error, production) };
 }
 
-async function renderFlight(request, fallback = null, channel = null) {
+function renderFlight(request, fallback = null, channel = null) {
+  const measurement=createFlightMeasurement(request,'rsc');
+  if(!measurement)return renderFlightModel(request,fallback,channel);
+  return observeFlightModel(request,fallback,channel,measurement);
+}
+async function observeFlightModel(request,fallback,channel,measurement){
+  let status;
+  try{
+    const result=await renderFlightModel(request,fallback,channel,measurement,measurement?value=>{status=value;}:undefined);
+    measurement?.finish('completed',result?.status??status);
+    return result;
+  }catch(error){
+    const reason=channel?.signal?.reason;
+    measurement?.finish(error?.statusCode===504||reason?.statusCode===504?'timedOut':channel?.signal?.aborted?'cancelled':'failed',status??error?.statusCode);
+    throw error;
+  }
+}
+async function renderFlightModel(request, fallback, channel,measurement,onStatus) {
   return runRequestContext({ ...request, phase: 'render' }, async () => {
     const cacheContext = currentRequest();
     try {
@@ -220,7 +238,9 @@ async function renderFlight(request, fallback = null, channel = null) {
           const stored = request.production
             ? await partialTemplates.get(request.partialFlight, consumer.serverConsumerManifest, decode, renderSignal)
             : await decode();
-          const live = !model.routing && canResumePartialDirectly(stored) ? model : await createFromReadableStream(boundedPartialFlight(renderToReadableStream(model, bundlerConfig, {
+          const direct=!model.routing&&canResumePartialDirectly(stored);
+          measurement?.partial(direct?'direct':'normalized');
+          const live = direct ? model : await createFromReadableStream(boundedPartialFlight(renderToReadableStream(model, bundlerConfig, {
             signal: renderSignal,
             onError(error) { return publicError(error, request.production).digest; },
           })), consumer);
@@ -295,9 +315,14 @@ async function renderFlight(request, fallback = null, channel = null) {
                 let offset = 0;
                 for (const item of batch) { value.set(item, offset); offset += item.byteLength; }
               }
-              if (!channel.started) channel.start({ status: request.partialFlight ? 200 : fallback?.kind === 'not-found' || (entry.routing && renderError?.digest === 'NEXT_HTTP_ERROR_FALLBACK;404') ? 404 : renderError || fallback?.kind === 'error' ? 500 : request.responseStatus || 200,
-                rscError: Boolean(ordinaryRenderError(renderError)), boundaryIndex: fallback?.index, headers: request.responseHeaders });
+              if (!channel.started) {
+                const status=request.partialFlight?200:fallback?.kind==='not-found'||(entry.routing&&renderError?.digest==='NEXT_HTTP_ERROR_FALLBACK;404')?404:renderError||fallback?.kind==='error'?500:request.responseStatus||200;
+                onStatus?.(status);
+                channel.start({status,rscError:Boolean(ordinaryRenderError(renderError)),boundaryIndex:fallback?.index,headers:request.responseHeaders});
+              }
+              const emittedBytes=measurement?value.byteLength:0;
               await channel.write(value, abort.signal, Boolean(next.result?.done));
+              measurement?.chunk(emittedBytes);
               continue;
             }
             // The byte stream hands ownership of each Uint8Array to its reader.
@@ -315,7 +340,7 @@ async function renderFlight(request, fallback = null, channel = null) {
           if (channel?.started && renderError.statusCode !== 504) { channel.end(); return; }
           if (renderError.digest === 'NEXT_HTTP_ERROR_FALLBACK;404' && !entry.routing) {
             const boundary = (entry.segments || []).findLastIndex((segment, index) => index < (fallback?.index ?? Infinity) && segment.notFound);
-            if (boundary >= 0) return renderFlight({ ...request, cacheState: cacheContext.cacheState, staticState: cacheContext.staticState }, { kind: 'not-found', index: boundary }, channel);
+            if (boundary >= 0) return renderFlightModel({ ...request, cacheState: cacheContext.cacheState, staticState: cacheContext.staticState }, { kind: 'not-found', index: boundary }, channel,measurement,onStatus);
           } else if (ordinaryRenderError(renderError)) {
             if (cacheContext.staticState) throw renderError;
             // Preserve the original errored Flight tree. React's browser
@@ -329,7 +354,7 @@ async function renderFlight(request, fallback = null, channel = null) {
           }
         }
         if (channel) {
-          if (!channel.started) channel.start({ status: request.responseStatus || 200, headers: request.responseHeaders });
+          if (!channel.started) {onStatus?.(request.responseStatus||200);channel.start({ status: request.responseStatus || 200, headers: request.responseHeaders });}
           channel.end();
           return;
         }
@@ -340,6 +365,7 @@ async function renderFlight(request, fallback = null, channel = null) {
         for (const chunk of chunks) {
           body.set(chunk, offset);
           offset += chunk.byteLength;
+          measurement?.chunk(chunk.byteLength);
         }
         return { body: body.buffer, status: staticNavigation?.status || (fallback?.kind === 'not-found' || (entry.routing && renderError?.digest === 'NEXT_HTTP_ERROR_FALLBACK;404') ? 404 : renderError || fallback?.kind === 'error' ? 500 : request.responseStatus || 200),
           rscError: Boolean(ordinaryRenderError(renderError)), boundaryIndex: fallback?.index, headers: { ...request.responseHeaders, ...staticNavigation?.headers },
@@ -409,11 +435,35 @@ const activeRequests = new Set();
 const responseCompletions = new Map();
 const manifests = new Map();
 const artifacts = new Map();
+const preloading = new Map();
 parentPort.on('message', async ({ id, request, type, value, token }) => {
   if(type==='telemetry-flush'){await drainTraces();parentPort.postMessage({type:'telemetry-flushed',token});return;}
+  if(type==='preload-cancel'){preloading.get(id)?.abort(new Error('Framework prewarm was cancelled'));return;}
   if(type==='preload'){
-    try{await preloadModules(value.files,value.options,file=>routeEntry({modulePath:file,production:true}));parentPort.postMessage({type:'preloaded',id});}
-    catch(error){parentPort.postMessage({type:'preloaded',id,error:error.message});}return;
+    const abort=new AbortController();preloading.set(id,abort);let timer,reader,reply,transfer;
+    try{
+      if(value.options.frameworkWarmup){
+        if(value.files.length||!Number.isFinite(value.options.timeoutMs)||value.options.timeoutMs<=0||value.options.timeoutMs>30000||!Number.isFinite(value.options.maxRssMb)||value.options.maxRssMb<=0||value.options.maxRssMb>2048)throw new TypeError('Invalid synthetic renderer prewarm');
+        const deadline=performance.now()+value.options.timeoutMs;
+        const available=()=>{abort.signal.throwIfAborted();if(performance.now()>=deadline||process.memoryUsage().rss>=value.options.maxRssMb*1024*1024)throw new Error('Synthetic renderer prewarm budget exhausted');};
+        timer=setTimeout(()=>abort.abort(new Error('Synthetic renderer prewarm timed out')),value.options.timeoutMs);
+        available();
+        // Host elements and literals only: no routeEntry, application imports,
+        // fetches, caches, contexts or handlers participate in this warm-up.
+        const model={tree:React.createElement('html',null,React.createElement('head'),React.createElement('body',null,React.createElement('main',null,React.createElement('ul',null,Array.from({length:8},(_,index)=>React.createElement('li',{key:index},'PRNext framework '+index)))))),router:{pathname:'/_prnext-prewarm',query:{}}};
+        reader=renderToReadableStream(model,{}, {signal:abort.signal,onError:()=> 'PRNEXT_FRAMEWORK_PREWARM'}).getReader();
+        const chunks=[];let length=0;
+        for(;;){available();const next=await reader.read();if(next.done)break;length+=next.value.byteLength;if(length>65536)throw new Error('Synthetic renderer prewarm Flight exceeds its byte budget');chunks.push(new Uint8Array(next.value));}
+        available();const bytes=new Uint8Array(length);let offset=0;for(const chunk of chunks){bytes.set(chunk,offset);offset+=chunk.length;}
+        await reader.cancel();reader=undefined;
+        reply={type:'preloaded',id,frameworkFlight:bytes.buffer};transfer=[bytes.buffer];
+      }else{
+        abort.signal.throwIfAborted();await preloadModules(value.files,value.options,file=>routeEntry({modulePath:file,production:true}));abort.signal.throwIfAborted();reply={type:'preloaded',id};
+      }
+    }catch(error){reply={type:'preloaded',id,error:error.message};}
+    finally{clearTimeout(timer);await reader?.cancel().catch(()=>{});preloading.delete(id);}
+    parentPort.postMessage(reply,transfer);
+    return;
   }
   if (type === 'after-response') { responseCompletions.get(id)?.(); return; }
   // Only the host arms these probes, while completed responses still have

package/runtime/worker.mjs

@@ -7,6 +7,7 @@ import {deferredCompiler} from './dev-compiler-broker.mjs';
 import { requestFrames } from './request-transport.mjs';
 import {scheduleCompileCacheFlush} from './compile-cache.mjs';
 import {preloadModules} from './preload.mjs';
+import {prewarmFramework} from './prewarm.mjs';
 import { requestWork } from './request-work.mjs';
 import { freezeClientModules } from './worker-metadata.mjs';
 import { AsyncResource } from 'node:async_hooks';
@@ -70,6 +71,29 @@ const routes = new Map(manifest.routes.map(route => [route.id, route]));
 const prerendered = new Set((manifest.prerendered || []).map(item => item.path));
 const deployment={distDir,manifest,routes,prerendered,modules:new Map()};
 const deployments=new Map([[distDir,deployment]]);
+const prewarmRequested = process.env.PRNEXT_WORKER_PREWARM === '1';
+delete process.env.PRNEXT_WORKER_PREWARM;
+async function rendererFor(selected,name){
+  if(selected.modules.has(name))return selected.modules.get(name);
+  const pending=workScope.runInAsyncScope(()=>runtimeModule(name,selected.distDir));
+  selected.modules.set(name,pending);
+  try{const module=await pending;selected.modules.set(name,module);return module;}
+  catch(error){if(selected.modules.get(name)===pending)selected.modules.delete(name);throw error;}
+}
+async function prepareFramework(signal) {
+  const configured = manifest.config?.workerPreload;
+  const options = { maxRssMb: configured?.maxRssMb ?? 256, timeoutMs: Math.min(15000, configured?.timeoutMs ?? 15000) };
+  const result = await prewarmFramework({ routes: manifest.routes, options, signal,
+    load: name => rendererFor(deployment, name) });
+  if (diagnostics.enabled) diagnostics.record('wake', { phase: 'framework-prewarm', ...result });
+  if (!result.ready) console.warn(`[prnext] Framework prewarm incomplete (${result.reason}); normal requests remain available.`);
+  return result.ready;
+}
+let frameworkPrewarmed = false;
+if (production && prewarmRequested) {
+  try { frameworkPrewarmed = await prepareFramework(); }
+  catch { console.warn('[prnext] Framework prewarm failed; normal requests remain available.'); }
+}
 const compileDeferred=!production&&compilerDescriptor?deferredCompiler(compilerDescriptor,{root:projectRoot,home:path.dirname(distDir)}):undefined;
 async function deferredDeployment(route,signal,sources=[]){
   if(!compileDeferred)throw Error('Deferred development compiler is unavailable');
@@ -91,15 +115,8 @@ async function drainRuntime(){
 
 async function handleRequest(input, output, signalController, responseComplete, selected=deployment) {
   const {manifest,distDir,routes,prerendered}=selected;
-  const renderer=async name=>{
-    if(selected.modules.has(name))return selected.modules.get(name);
-    // Imports share one pending job, then retain only the namespace. Starting
-    // outside the visitor's ALS scope prevents the module cache retaining it.
-    const pending=workScope.runInAsyncScope(()=>runtimeModule(name,distDir));
-    selected.modules.set(name,pending);
-    try{const module=await pending;selected.modules.set(name,module);return module;}
-    catch(error){if(selected.modules.get(name)===pending)selected.modules.delete(name);throw error;}
-  };
+  // Bootstrap and requests share pending imports outside the visitor's ALS.
+  const renderer=name=>rendererFor(selected,name);
   let responseStarted = false;
   const finalizers = new Set();
   try {
@@ -108,10 +125,8 @@ async function handleRequest(input, output, signalController, responseComplete,
       const options=manifest.config?.workerPreload||(frameworkOnly?{routes:[],maxRssMb:256,timeoutMs:15000}:undefined);
       if(!production||!options){await output(input.id,{status:204,body:''},input);return;}
       if(frameworkOnly){
-        if(manifest.routes.some(route=>route.router==='app'&&route.kind==='page'))await(await renderer('app-render')).prewarmAppRenderer(options);
-        if(manifest.routes.some(route=>route.kind==='page'&&route.router!=='app'))await renderer('render');
-        if(manifest.routes.some(route=>route.kind==='api'))await renderer('api');
-        scheduleCompileCacheFlush();await output(input.id,{status:204,body:''},input);return;
+        frameworkPrewarmed = await prepareFramework(signalController.signal);
+        scheduleCompileCacheFlush();await output(input.id,{status:frameworkPrewarmed?204:503,body:''},input);return;
       }
       const selected=options.routes.map(pattern=>manifest.routes.find(route=>route.pattern===pattern&&!route.internal)).filter(Boolean);
       const deadline=performance.now()+options.timeoutMs;
@@ -347,7 +362,7 @@ if (token && laneLimit > 1) {
       globalThis.__PRNEXT_DEV_WORKER_READY__({port:server.address().port,binary:true,gracefulShutdown:true,requestBodyStream:1});
       delete globalThis.__PRNEXT_DEV_WORKER_READY__;
     }
-    writeProtocol(JSON.stringify({ port: server.address().port, binary: true, heartbeat: true, activity: reportActivity, gracefulShutdown: true, requestBodyStream: 1 }) + '\n');
+    writeProtocol(JSON.stringify({ port: server.address().port, binary: true, heartbeat: true, activity: reportActivity, gracefulShutdown: true, requestBodyStream: 1, frameworkPrewarmed }) + '\n');
     heartbeat = setInterval(() => {
       // Coalesce the idle transition with the existing heartbeat. Normal
       // request completion adds no stdout messages, and short cache bursts