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

package/runtime/persistent/daemon.mjs

@@ -1,11 +1,12 @@
 import { spawn } from 'node:child_process';
-import { Agent, createServer, request } from 'node:http';
+import { request } from 'node:http';
 import { cp, mkdir, readFile, rm, realpath } from 'node:fs/promises';
 import { randomUUID, createHash } from 'node:crypto';
 import path from 'node:path';
 import { readBuildDirectory } from '../build-directory.mjs';
 import { atomicJSON, delay, environment, validName, validHealthPath } from './common.mjs';
 import { RotatingLog } from './logger.mjs';
+import {nativeGateway,stopNativeProxy} from './native-proxy.mjs';
 
 const home = process.argv[2];
 const registry = path.join(home, 'apps.json');
@@ -16,6 +17,7 @@ const send = message => { if (process.connected) process.send(message); };
 
 function validate(config) {
   validName(config.name); validHealthPath(config.healthPath);
+  if(config.rollbackWindow!==undefined&&(!Number.isInteger(config.rollbackWindow)||config.rollbackWindow<0||config.rollbackWindow>120000))throw new Error('rollbackWindow must be between 0 and 120000 milliseconds');
   if (!path.isAbsolute(config.root) || !path.isAbsolute(config.binary) || !path.isAbsolute(config.node)) throw new Error('Application, Node and native executable paths must be absolute');
   if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535) throw new Error('--port must be between 1 and 65535');
   if (typeof config.hostname !== 'string' || !config.hostname || /[\s\x00-\x1f]/.test(config.hostname)) throw new Error('Choose a valid --hostname');
@@ -27,7 +29,8 @@ async function persist() {
   await atomicJSON(registry, { version: 1, apps: [...apps.values()].map(app => ({ config: app.config, enabled: app.enabled, snapshots: [...app.snapshots] })) });
 }
 function newApp(config, enabled = false) {
-  return { config, enabled, snapshots: new Set(), active: null, generations: new Set(), gateway: null, sockets: new Set(), state: 'stopped', error: null, starts: 0, failures: [], retry: null,
+  config={rollbackWindow:15000,...config};
+  return { config, enabled, snapshots: new Set(), active: null, generations: new Set(), gateway: null, state: 'stopped', error: null, starts: 0, failures: [], retry: null, probation:null,
     log: new RotatingLog(path.join(home, 'logs', `app-${config.name}.log`)) };
 }
 function summary(app) {
@@ -36,44 +39,13 @@ function summary(app) {
     activeRequests: [...app.generations].reduce((sum, generation) => sum + generation.active, 0),
     draining: [...app.generations].filter(generation => generation !== app.active).length,
     buildId: app.active?.buildId || null, startedAt: app.active?.startedAt || null, error: app.error,
+    proxyPid:app.gateway?.pid||null,
+    rollback:app.probation?{previousBuildId:app.probation.previous.buildId,until:app.probation.deadline}:null,
     log: path.join(home, 'logs', `app-${app.config.name}.log`) };
 }
-function hopHeaders(headers) {
-  const result = { ...headers };
-  const nominated = String(headers.connection || '').split(',').map(value => value.trim().toLowerCase());
-  for (const key of ['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade', ...nominated]) delete result[key];
-  return result;
-}
 async function listen(app) {
   if (app.gateway) return;
-  const server = createServer({ requestTimeout: 300000, headersTimeout: 30000 }, (incoming, outgoing) => {
-    const generation = app.active;
-    if (!incoming.url.startsWith('/')) { outgoing.writeHead(400).end('Use a local request path.'); return; }
-    if (!generation || generation.dead) { outgoing.writeHead(503, { 'retry-after': '1' }).end('Application is restarting.'); incoming.resume(); return; }
-    if (generation.active >= 512) { outgoing.writeHead(503, { 'retry-after': '1' }).end('Application is busy.'); incoming.resume(); return; }
-    generation.active++;
-    const headers = hopHeaders(incoming.headers);
-    // Preserve original Host and trusted reverse-proxy headers. Never invent
-    // retry/replay behavior for POSTs or requests that have already streamed.
-    const upstream = request({ host: '127.0.0.1', port: generation.port, method: incoming.method, path: incoming.url, headers, agent: generation.agent }, response => {
-      outgoing.writeHead(response.statusCode, hopHeaders(response.headers));
-      response.on('error', () => outgoing.destroy()); response.pipe(outgoing);
-    });
-    generation.requests.add(upstream);
-    let released = false;
-    const release = () => { if (released) return; released = true; generation.active--; generation.requests.delete(upstream); upstream.destroy(); };
-    outgoing.once('finish', release); outgoing.once('close', release);
-    incoming.once('aborted', () => outgoing.destroy());
-    incoming.once('error', () => outgoing.destroy());
-    upstream.once('error', () => { if (!outgoing.headersSent) outgoing.writeHead(502).end('Application connection closed.'); else outgoing.destroy(); });
-    incoming.pipe(upstream);
-  });
-  server.on('upgrade', (_request, socket) => socket.end('HTTP/1.1 501 Not Implemented\r\nConnection: close\r\nContent-Length: 0\r\n\r\n'));
-  server.on('connection', socket => { app.sockets.add(socket); socket.once('close', () => app.sockets.delete(socket)); });
-  server.maxConnections = 1024;
-  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(app.config.port, app.config.hostname, resolve); });
-  server.on('error', error => { app.error = error.message; app.log.message(error.message); });
-  app.gateway = server;
+  app.gateway=await nativeGateway(app.config,{home,notify:send,onFatal:error=>{console.error(error.message);if(!closing)process.exit(1);}});
 }
 async function removeSnapshot(app, relative) {
   // Only delete a directory generated by this manager inside this exact root.
@@ -120,11 +92,9 @@ async function stopGeneration(app, generation, drain = true) {
   generation.expected = true;
   generation.stopping = (async () => {
     const deadline = Date.now() + (drain ? app.config.drainTimeout : 0);
-    while (generation.active && Date.now() < deadline && !generation.dead) await delay(25);
-    for (const req of generation.requests) req.destroy();
-    generation.agent.destroy();
+    await app.gateway?.retire(generation,drain?Math.max(0,deadline-Date.now()):0).catch(error=>app.log.message(`Proxy retirement: ${error.message}`));
     generation.child.stdin?.end();
-    await Promise.race([generation.closed, delay(3000)]);
+    await Promise.race([generation.closed, delay(drain?Math.max(1000,deadline-Date.now()):3000)]);
     if (!generation.dead) generation.child.kill('SIGKILL');
     if (process.platform !== 'win32' && generation.child.pid) { try { process.kill(-generation.child.pid, 'SIGKILL'); } catch {} }
     await generation.closed;
@@ -156,7 +126,7 @@ async function launch(app) {
     env: { ...environment(), NODE_ENV: 'production', ...(config.inspect ? { PRNEXT_INSPECT_DIR: path.join(config.root, '.prnext-cache/inspect') } : {}) },
   });
   child.stdin.on('error', () => {});
-  const generation = { child, ...build, active: 0, requests: new Set(), agent: new Agent({ keepAlive: true, maxSockets: 512, maxFreeSockets: 16, timeout: 30000 }), dead: false, expected: false, port: null, startedAt: Date.now() };
+  const generation = { child, ...build, active: 0, dead: false, expected: false, port: null, startedAt: Date.now() };
   app.generations.add(generation);
   if (child.pid) send({ type: 'child', pid: child.pid, running: true });
   let output = '', failure;
@@ -173,12 +143,12 @@ async function launch(app) {
   generation.closed = new Promise(resolve => child.once('close', (code, signal) => {
     generation.dead = true;
     if (child.pid) send({ type: 'child', pid: child.pid, running: false });
-    if (app.active === generation) app.active = null;
+    if (app.active === generation) {app.active = null;void app.gateway?.pause(generation).catch(error=>app.log.message(error.message));}
     if (!generation.expected) {
       app.log.message(`Process ${child.pid || 'unknown'} exited (${signal || code}).`);
       if (generation.ready) {
         // Serialize recovery and cleanup with explicit lifecycle commands.
-        sequence = sequence.then(async () => { await stopGeneration(app, generation, false); await persist(); retry(app, new Error(`Application exited (${signal || code})`)); }).catch(error => app.log.message(error.stack));
+        sequence = sequence.then(async () => { if(app.probation?.next===generation&&await rollback(app,new Error(`Replacement exited (${signal||code})`)))return;await stopGeneration(app, generation, false); await persist(); if(!app.active)retry(app, new Error(`Application exited (${signal || code})`)); }).catch(error => app.log.message(error.stack));
       }
     }
     resolve();
@@ -197,7 +167,42 @@ async function launch(app) {
   } catch (error) { await stopGeneration(app, generation, false); throw error; }
   finally { child.stdout.off('data', started); }
 }
+async function finishProbation(app){
+  const probation=app.probation;if(!probation)return;
+  clearTimeout(probation.timer);app.probation=null;
+  await stopGeneration(app,probation.previous).catch(error=>app.log.message(`Previous build cleanup: ${error.message}`));
+  await persist();
+}
+async function rollback(app,error){
+  const probation=app.probation;if(!probation)return false;
+  clearTimeout(probation.timer);app.probation=null;
+  if(!app.enabled||closing||probation.previous.dead||probation.previous.expected){
+    await stopGeneration(app,probation.previous,false);return false;
+  }
+  // A live previous process still has to pass its health check. Never roll
+  // traffic back to an instance whose dependencies have also become unhealthy.
+  try{await health(probation.previous,app.config,Math.min(2000,app.config.healthTimeout));await app.gateway.activate(probation.previous);}
+  catch(restore){app.log.message(`Rollback unavailable: ${restore.message}`);await stopGeneration(app,probation.previous,false);return false;}
+  app.active=probation.previous;app.state='online';app.error=`Rolled back: ${error.message}`;
+  app.log.message(`Rolled back to build ${app.active.buildId}: ${error.message}`);
+  await stopGeneration(app,probation.next);await persist();return true;
+}
+function beginProbation(app,next,previous){
+  const probation=app.probation={next,previous,deadline:Date.now()+app.config.rollbackWindow,failures:0};
+  const schedule=()=>{probation.timer=setTimeout(()=>{
+    sequence=sequence.then(async()=>{
+      if(app.probation!==probation||!app.enabled||closing)return;
+      if(next.dead){await rollback(app,new Error('Replacement exited during monitoring'));return;}
+      if(Date.now()>=probation.deadline){await finishProbation(app);return;}
+      try{await health(next,app.config,Math.min(2000,app.config.healthTimeout));probation.failures=0;}
+      catch(error){if(++probation.failures>=3){if(!await rollback(app,error)){await stopGeneration(app,next,false);retry(app,error);}return;}}
+      if(app.probation===probation)schedule();
+    }).catch(error=>app.log.message(`Replacement monitoring: ${error.stack||error}`));
+  },Math.min(1000,Math.max(1,probation.deadline-Date.now())));};
+  schedule();
+}
 async function activate(app) {
+  await finishProbation(app);
   await listen(app);
   const previous = app.active;
   const wasEnabled = app.enabled;
@@ -208,9 +213,13 @@ async function activate(app) {
     app.enabled = true;
     await persist();
     if (next.dead) throw new Error('Application exited before traffic could switch');
+    await app.gateway.activate(next);
+    if (next.dead) throw new Error('Application exited while traffic switched');
     app.active = next; app.state = 'online'; app.error = null;
     app.log.message(`Ready: pid ${next.child.pid}, build ${next.buildId || 'unknown'}, ${app.config.hostname}:${app.config.port}`);
   } catch (error) {
+    if (previous && !previous.dead) await app.gateway.activate(previous).catch(restore=>app.log.message(restore.message));
+    else await app.gateway?.pause().catch(restore=>app.log.message(restore.message));
     if (next) await stopGeneration(app, next, false).catch(cleanup => app.log.message(cleanup.message));
     app.enabled = wasEnabled;
     app.state = previous && !previous.dead ? 'online' : 'errored'; app.error = error.message;
@@ -218,21 +227,17 @@ async function activate(app) {
     app.log.message(`Start failed; ${previous && !previous.dead ? 'previous generation remains active' : 'no healthy generation'}: ${error.message}`);
     throw error;
   }
-  if (previous) {
-    await stopGeneration(app, previous).catch(error => app.log.message(`Previous build cleanup: ${error.message}`));
-    await persist();
-  }
+  if(previous && app.config.rollbackWindow>0)beginProbation(app,next,previous);
+  else if(previous){await stopGeneration(app,previous);await persist();}
 }
 async function stopApp(app) {
+  if(app.probation)clearTimeout(app.probation.timer);app.probation=null;
   app.enabled = false; clearTimeout(app.retry); app.retry = null;
   await persist();
   app.state = 'stopping'; app.active = null;
-  const gateway = app.gateway; app.gateway = null;
-  const closed = gateway ? new Promise(resolve => gateway.close(resolve)) : Promise.resolve();
-  gateway?.closeIdleConnections();
+  await app.gateway?.pause();
   await Promise.all([...app.generations].map(generation => stopGeneration(app, generation)));
-  for (const socket of app.sockets) socket.destroy();
-  await closed; app.state = 'stopped'; app.error = null; await persist();
+  await app.gateway?.close();app.gateway=null;app.state = 'stopped'; app.error = null; await persist();
   app.log.message('Stopped.');
 }
 function select(message) {
@@ -242,8 +247,12 @@ function select(message) {
   return selected;
 }
 async function command(message) {
-  if (message.command === 'status') return { daemonPid: process.pid, apps: [...apps.values()].map(summary) };
+  if (message.command === 'status') {
+    for(const app of apps.values())if(app.gateway){const counts=await app.gateway.counts();for(const g of app.generations)g.active=counts[g.relative]||0;}
+    return { daemonPid: process.pid, apps: [...apps.values()].map(summary) };
+  }
   if (message.command === 'start') {
+    message.config={rollbackWindow:15000,...message.config};
     validate(message.config);
     message.config.root = await realpath(message.config.root);
     let app = apps.get(message.config.name);
@@ -274,12 +283,13 @@ async function shutdown() {
   await sequence;
   // A supervisor shutdown preserves each enabled flag for the next launch.
   await Promise.all([...apps.values()].map(async app => {
-    clearTimeout(app.retry); app.active = null; app.gateway?.close();
+    if(app.probation)clearTimeout(app.probation.timer);app.probation=null;
+    clearTimeout(app.retry); app.active = null;await app.gateway?.pause();
     await Promise.all([...app.generations].map(generation => stopGeneration(app, generation)));
-    for (const socket of app.sockets) socket.destroy();
+    await app.gateway?.close();app.gateway=null;
     app.log.end();
   }));
-  await persist(); process.exit(0);
+  await stopNativeProxy();await persist(); process.exit(0);
 }
 process.on('disconnect', () => void shutdown());
 process.on('SIGTERM', () => void shutdown());

package/runtime/persistent/native-proxy.mjs

@@ -0,0 +1,63 @@
+// Lifecycle RPC only: no public HTTP bytes, headers or response bodies enter JS.
+import {spawn} from 'node:child_process';
+import {environment,delay} from './common.mjs';
+let manager;
+class NativeProxy {
+  constructor(binary,{home,notify,onFatal}){
+    this.pending=new Map();this.next=0;this.stopping=false;
+    this.child=spawn(binary,['persistent-proxy'],{cwd:home,windowsHide:true,detached:process.platform!=='win32',stdio:['pipe','pipe','inherit'],env:{...environment(),TOKIO_WORKER_THREADS:'1'}});
+    this.pid=this.child.pid;if(this.pid)notify({type:'child',pid:this.pid,running:true});
+    this.closed=new Promise(resolve=>this.child.once('close',()=>{if(this.pid)notify({type:'child',pid:this.pid,running:false});resolve();}));
+    this.ready=new Promise((resolve,reject)=>{
+      const timer=setTimeout(()=>{reject(new Error('Native persistent proxy did not initialize'));this.child.kill();},10000);timer.unref();
+      let buffer='';
+      this.child.stdout.setEncoding('utf8');
+      this.child.stdout.on('data',chunk=>{
+        buffer+=chunk;
+        if(buffer.length>1024*1024){this.child.kill();return;}
+        for(let end;(end=buffer.indexOf('\n'))>=0;){
+          const line=buffer.slice(0,end);buffer=buffer.slice(end+1);let message;
+          try{message=JSON.parse(line);}catch{this.child.kill();return;}
+          if(message.type==='ready'&&message.protocol===1){clearTimeout(timer);resolve();continue;}
+          const request=this.pending.get(message.id);if(!request)continue;
+          this.pending.delete(message.id);clearTimeout(request.timer);message.ok?request.resolve(message.value):request.reject(new Error(message.error||'Native proxy request failed'));
+        }
+      });
+      const failed=error=>{
+        clearTimeout(timer);reject(error);
+        for(const request of this.pending.values()){clearTimeout(request.timer);request.reject(error);}this.pending.clear();
+        if(!this.stopping)onFatal(error);
+      };
+      this.child.once('error',failed);this.child.once('exit',(code,signal)=>failed(new Error(`Native persistent proxy exited (${signal||code})`)));
+    });
+    this.child.stdin.on('error',()=>{});
+  }
+  async request(command,values={},timeout=10000){
+    await this.ready;
+    if(this.stopping||this.child.exitCode!==null||this.pending.size>=32)throw new Error('Native persistent proxy unavailable');
+    const id=++this.next;
+    return new Promise((resolve,reject)=>{
+      const timer=setTimeout(()=>{
+        this.pending.delete(id);reject(new Error('Native proxy control request timed out'));
+        // A timed-out switch/listen might still mutate native state later.
+        // End that uncertain control plane; the watchdog restores saved apps.
+        this.child.kill('SIGKILL');
+      },timeout);timer.unref();
+      this.pending.set(id,{resolve,reject,timer});
+      this.child.stdin.write(JSON.stringify({id,command,...values})+'\n',error=>{if(error){const request=this.pending.get(id);if(request){clearTimeout(request.timer);this.pending.delete(id);request.reject(error);}}});
+    });
+  }
+  async stop(){this.stopping=true;this.child.stdin.end();await Promise.race([this.closed,delay(3000)]);if(this.child.exitCode===null)this.child.kill('SIGKILL');await this.closed;}
+}
+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}),
+    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,
+    close:()=>manager.request('close',{app}),
+  };
+}
+export async function stopNativeProxy(){if(manager){const active=manager;manager=undefined;await active.stop();}}

package/runtime/preload.mjs

@@ -0,0 +1,12 @@
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+// This is an import budget, not a total RSS limit. An individual module and its
+// transitive imports can exceed it; imported JavaScript cannot be unloaded.
+export async function preloadModules(files,{maxRssMb,timeoutMs},load=file=>import(pathToFileURL(file).href)){
+  const deadline=performance.now()+timeoutMs,loaded=[];
+  for(const file of files){
+    if(performance.now()>=deadline||process.memoryUsage().rss>=maxRssMb*1024*1024)break;
+    await load(path.resolve(file));loaded.push(file);
+  }
+  return loaded.length;
+}

package/runtime/rsc-worker.mjs

@@ -1,4 +1,6 @@
 import React from 'react';
+import {scheduleCompileCacheFlush} from './compile-cache.mjs';
+import {preloadModules} from './preload.mjs';
 import { flightBundler } from './worker-metadata.mjs';
 import { removeBasePath, normalizeTrailingSlash } from '../compat/paths.cjs';
 import { renderToReadableStream } from 'react-server-dom-webpack/server.node';
@@ -40,6 +42,7 @@ async function routeEntry(request) {
     return entry;
   }
   const entry = await import(pathToFileURL(key).href);
+  scheduleCompileCacheFlush();
   if (request.production) {
     if (routeEntries.size >= 64) routeEntries.delete(routeEntries.keys().next().value);
     routeEntries.set(key, entry);
@@ -387,6 +390,10 @@ const responseCompletions = new Map();
 const manifests = new Map();
 const artifacts = new Map();
 parentPort.on('message', async ({ id, request, type, value, token }) => {
+  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;
+  }
   if (type === 'after-response') { responseCompletions.get(id)?.(); return; }
   // Only the host arms these probes, while completed responses still have
   // tracked cache work. There is no timer or heartbeat in an idle RSC isolate.

package/runtime/typed-route.mjs

@@ -0,0 +1,19 @@
+/** Materialize a discovered route pattern without interpolating path separators. */
+export function route(pattern,params={}) {
+  if(typeof pattern!=='string'||!pattern.startsWith('/')||pattern.startsWith('//')||pattern.length>4096||!params||typeof params!=='object'||Array.isArray(params))throw TypeError('Invalid route pattern or parameters');
+  const used=new Set(),parts=[];
+  const segment=value=>{
+    if(typeof value!=='string'||!value||value==='.'||value==='..'||/[/\\\0]/.test(value))throw TypeError('Route parameters must be nonempty path segments');
+    return encodeURIComponent(value);
+  };
+  for(const part of pattern.split('/').slice(1)){
+    const match=/^(?:\[\[\.\.\.([A-Za-z_$][\w$]*)\]\]|\[\.\.\.([A-Za-z_$][\w$]*)\]|\[([A-Za-z_$][\w$]*)\])$/.exec(part);
+    if(!match){if(/[\[\]?#\\\0]/.test(part)||part==='.'||part==='..'||!part&&pattern!=='/')throw TypeError('Invalid route segment');parts.push(part);continue;}
+    const name=match[1]||match[2]||match[3];used.add(name);const value=params[name];
+    if(match[1]&&value===undefined)continue;
+    if(match[1]||match[2]){if(!Array.isArray(value)||match[2]&&!value.length)throw TypeError(`Route parameter ${name} must be an array of segments`);parts.push(...value.map(segment));}
+    else parts.push(segment(value));
+  }
+  for(const name of Object.keys(params))if(!used.has(name))throw TypeError(`Unknown route parameter ${name}`);
+  const result='/'+parts.join('/');if(result.length>8192)throw TypeError('Route exceeds 8 KiB');return result;
+}

package/runtime/watch-project.mjs

@@ -9,9 +9,10 @@ const missing = error => error.code === 'ENOENT' || error.code === 'ENOTDIR';
 // including ignored build trees. Atomic build swaps can delete a descendant
 // during that scan. Watch only source directories, and handle removal races
 // in our own traversal. No file contents or node_modules watches are retained.
-export async function watchProject(root, { onChange, onError, ignore = () => false, watch = watchDirectory, maxDirectories = 8192, nativeRecursive = process.platform === 'darwin' || process.platform === 'win32' }) {
-  // macOS and Windows have native recursive backends. Separate directory
-  // subscriptions can lose coalesced events during rapid renames.
+export async function watchProject(root, { onChange, onError, ignore = () => false, watch = watchDirectory, maxDirectories = 8192, nativeRecursive = process.platform === 'darwin' }) {
+  // Windows' recursive notification buffer can overflow while V8/webpack flush
+  // caches. Source-only subscriptions avoid losing edits in that disk traffic.
+  // macOS uses its native recursive backend for coalesced directory renames.
   if (nativeRecursive) {
     const watcher = watch(root, { recursive: true }, (event, filename) => {
       const relative = filename && String(filename).replaceAll(path.sep, '/');
@@ -65,7 +66,8 @@ export async function watchProject(root, { onChange, onError, ignore = () => fal
   async function scan(relative, recursive = false) {
     if (closed) return;
     if (!allowedDirectory(relative)) { remove(relative); return; }
-    if (!directories.has(relative)) {
+    const fresh = !directories.has(relative);
+    if (fresh) {
       if (directories.size >= maxDirectories) throw new Error(`Development watcher exceeds ${maxDirectories} source directories. Narrow the application directory.`);
       let watcher;
       try {
@@ -78,7 +80,11 @@ export async function watchProject(root, { onChange, onError, ignore = () => fal
             return;
           }
           const changed = filename ? path.posix.join(relative, String(filename).replaceAll(path.sep, '/')) : relative;
-          if (allowedFile(changed)) onChange(changed);
+          let metadataOnly = false;
+          if (process.platform === 'win32' && event === 'change') {
+            try { metadataOnly = statSync(path.join(root, changed)).isDirectory(); } catch {}
+          }
+          if (allowedFile(changed) && !metadataOnly) onChange(changed);
           // The .contentlayer container itself is ignored as a source, but
           // its generated directory may be created after the watcher starts.
           // Platforms can coalesce a directory rename into a change event.
@@ -103,6 +109,7 @@ export async function watchProject(root, { onChange, onError, ignore = () => fal
     const children = new Set();
     for (const entry of entries) {
       const child = path.posix.join(relative, entry.name);
+      if (fresh && ready && entry.isFile() && allowedFile(child)) onChange(child);
       if (!entry.isDirectory() || !allowedDirectory(child)) continue;
       children.add(child);
       if (recursive || !directories.has(child)) await scan(child, recursive);

package/runtime/worker.mjs

@@ -1,6 +1,8 @@
 // prnext-transport:socket-v2
 // prnext-concurrency:512
 import { requestFrames } from './request-transport.mjs';
+import {scheduleCompileCacheFlush} from './compile-cache.mjs';
+import {preloadModules} from './preload.mjs';
 import { requestWork } from './request-work.mjs';
 import { freezeClientModules } from './worker-metadata.mjs';
 import { AsyncResource } from 'node:async_hooks';
@@ -36,12 +38,20 @@ loadEnvConfig(projectRoot, { dev: !!manifest.dev });
 // browser graph and the RSC worker's mode, including dev launched from CI.
 process.env.NODE_ENV = manifest.dev ? 'development' : 'production';
 const production = !manifest.dev;
+let dispatchRequest=handleRequest;
+if(!production){
+  const {createDevWorkerConsole}=await import('./dev-worker-logs.mjs'),logs=createDevWorkerConsole();globalThis.console=logs.console;
+  dispatchRequest=(input,...args)=>logs.run({requestId:input.id,route:routes.get(input.routeId)?.pattern},()=>handleRequest(input,...args));
+  const {publishDevCacheCapability}=await import('./dev-cache-control.mjs');
+  await publishDevCacheCapability({root:projectRoot,distDir,manifest}).catch(()=>{console.warn('[prnext] Local cache controls are unavailable for this development generation.');});
+}
 if (production) freezeClientModules(manifest.app?.clientModules);
 // Load each renderer beside the application only when that request needs it.
 // Middleware and API workers do not pay for React or the Pages/App renderers.
 const runtimeModule = async name => {
   const started = diagnostics.enabled ? performance.now() : 0;
   const module = await import(pathToFileURL(path.join(distDir, `runtime/${name}.mjs`)).href);
+  scheduleCompileCacheFlush();
   if (diagnostics.enabled) diagnostics.record('wake', { phase: 'module', module: name, durationMs: performance.now() - started });
   return module;
 };
@@ -62,6 +72,25 @@ async function handleRequest(input, output, signalController, responseComplete)
   let responseStarted = false;
   const finalizers = new Set();
   try {
+    if(input.routeId==='__prnext_preload'&&input.renderMode==='preload'){
+      const options=manifest.config?.workerPreload;
+      if(!production||!options){await output(input.id,{status:204,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;
+      for(const route of selected){
+        if(performance.now()>=deadline||process.memoryUsage().rss>=options.maxRssMb*1024*1024)break;
+        const remaining={...options,timeoutMs:Math.max(1,deadline-performance.now())};
+        if(route.router==='app'&&route.kind==='page'){
+          appRuntime??=await runtimeModule('app-render');
+          await appRuntime.preloadAppRoutes([path.resolve(distDir,route.module)],remaining);
+        }else{
+          if(route.kind==='page')pagesRuntime??=await runtimeModule('render');else apiRuntime??=await runtimeModule('api');
+          await preloadModules([path.resolve(distDir,route.module)],remaining);
+        }
+        if(process.memoryUsage().rss>=options.maxRssMb*1024*1024)break;
+      }
+      scheduleCompileCacheFlush();await output(input.id,{status:204,body:''},input);return;
+    }
     if (input.renderMode === 'incremental-cache' && input.routeId === '__prnext_incremental_cache') {
       incrementalRuntime ??= await runtimeModule('incremental-cache');
       const result = await incrementalRuntime.runIncrementalCache({ ...input, manifest, distDir, production, signal: signalController.signal });
@@ -223,7 +252,7 @@ if (token && laneLimit > 1) {
             workTimer.unref();
           };
           active.signal.addEventListener('abort', retireIfAbandoned, { once: true });
-          try { await handleRequest(input, output, active, () => { controller = undefined; }); }
+          try { await dispatchRequest(input, output, active, () => { controller = undefined; }); }
           finally {
             finished = true;
             if (!pendingWork) { invocations.delete(active); clearTimeout(workTimer); }
@@ -262,6 +291,10 @@ if (token && laneLimit > 1) {
     else throw error;
   });
   server.listen(0, '127.0.0.1', () => {
+    if(!production&&typeof globalThis.__PRNEXT_DEV_WORKER_READY__==='function'){
+      globalThis.__PRNEXT_DEV_WORKER_READY__({port:server.address().port,binary:true,gracefulShutdown:true});
+      delete globalThis.__PRNEXT_DEV_WORKER_READY__;
+    }
     writeProtocol(JSON.stringify({ port: server.address().port, binary: true, heartbeat: true, activity: reportActivity, gracefulShutdown: true }) + '\n');
     heartbeat = setInterval(() => {
       // Coalesce the idle transition with the existing heartbeat. Normal
@@ -269,6 +302,7 @@ if (token && laneLimit > 1) {
       // cannot add two messages for every response.
       reportedBusy = reportActivity && invocations.size > 0;
       writeProtocol(reportedBusy ? 'busy\n' : 'alive\n');
+      if(!production)globalThis.__PRNEXT_DEV_WORKER_PULSE__?.(reportedBusy?'busy\n':'alive\n');
     }, 1000).unref();
   });
 } else {
@@ -276,7 +310,7 @@ if (token && laneLimit > 1) {
   for await (let line of readline.createInterface({ input: process.stdin, crlfDelay: Infinity })) {
     if (!line.trim()) continue;
     const input = JSON.parse(line); line = '';
-    try { await handleRequest(input, output, new AbortController()); }
+    try { await dispatchRequest(input, output, new AbortController()); }
     catch (error) { console.error('[prnext] Worker transport failed:', error?.stack || error); process.exit(1); }
   }
   // The maintenance/ISR transport is serial and awaits its own finalizers.