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

package/runtime/rsc-worker.mjs

@@ -1,4 +1,8 @@
+import {drainTraces} from './trace.mjs';
+import {withInstrumentation,reportRequestError,wasRequestErrorReported} from './instrumentation.mjs';
 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';
@@ -6,6 +10,7 @@ import { createFromReadableStream } from 'react-server-dom-webpack/client.edge';
 import { parentPort } from 'node:worker_threads';
 import { pathToFileURL } from 'node:url';
 import { createHash } from 'node:crypto';
+import { navigationAuthorization } from '../compat/navigation-authorization.cjs';
 import { runRequestContext, currentRequest } from '../compat/headers.cjs';
 import { Metadata } from './app-metadata.mjs';
 import { appTimeoutError } from './app-errors.mjs';
@@ -25,6 +30,8 @@ import { flightConsumer } from './cache-components-rsc.mjs';
 import { partialModel, isPartialHole, boundedPartialFlight } from './app-partial-model.mjs';
 import { PartialTemplates, canResumePartialDirectly, partialTemplateReuse } from './partial-template.mjs';
 import { createAfterScope } from '../compat/after.cjs';
+import {renderKeyFor} from './app-render-key.mjs';
+import { selectAppStyles } from './app-style-selection.mjs';
 
 installFetchCache();
 if (process.env.PRNEXT_INSPECT_DIR) parentPort.postMessage({type:'rsc-ready'});
@@ -40,6 +47,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);
@@ -68,6 +76,9 @@ function queryObject(url) {
 }
 
 function createTree(entry, request, fallback = null) {
+  function RetainedBranch(props) {
+    return React.createElement(entry.ActivitySlot, { ...props, authorizationKey: navigationAuthorization(currentRequest(), request.authorizationSecret || request.actionKey, request.navigationCache?.authCookies) });
+  }
   const params = staticParams(request.params || {});
   const searchParams = staticSearchParams(queryObject(new URL(request.url)), currentRequest(), entry.page?.default?.$$typeof === Symbol.for('react.client.reference'));
   if (entry.routing && !fallback) return createAdvancedTree(entry, request, searchParams);
@@ -97,7 +108,7 @@ function createTree(entry, request, fallback = null) {
   const scopedParams = paramsBySegment(segments, request.params || {});
   for (const segment of segments) {
     scopes.set(segment, `${segment.path || ''}:${JSON.stringify(scopedParams.get(segment))}`);
-    if (request.partialParams?.length) for (const prefix of ['', 'error:', 'navigation:', 'layout:']) keyScope(`${prefix}${segment.path || ''}:`, scopedParams.get(segment), prefix === 'layout:' ? ['segments'] : undefined);
+    if (request.partialParams?.length) for (const prefix of ['', 'error:', 'navigation:', 'layout:', 'activity:']) keyScope(`${prefix}${segment.path || ''}:`, scopedParams.get(segment), prefix === 'layout:' ? ['segments'] : prefix === 'activity:' ? ['identity', 'authorizationKey'] : ['error:', 'navigation:'].includes(prefix) ? ['resetKey'] : undefined);
   }
   let instantConfig = request.instantValidation ? entry.pageConfig?.instant : undefined;
   for (let index = fallback ? Math.min(fallback.index, segments.length - 1) : segments.length - 1; index >= 0; index--) {
@@ -125,6 +136,10 @@ function createTree(entry, request, fallback = null) {
       tree = React.createElement(component(segment.template, 'template'), { key: child ? scopes.get(child) : pageKey }, tree);
     }
     if (segment.layout) {
+      if (entry.ActivitySlot) tree = React.createElement(RetainedBranch, {
+        identity: segments.slice(index + 1).some(child => child.layout) ? scopes.get(segments[index + 1]) : pageKey + new URL(request.originalUrl || request.url).search,
+        key: `activity:${scopes.get(segment)}`,
+      }, tree);
       if (request.cacheComponents && segment === rootLayout) tree = React.createElement(React.Fragment, null, head, tree);
       tree = React.createElement(component(segment.layout, 'layout'), { params: staticParams(scopedParams.get(segment)), key: scopes.get(segment) }, tree);
       if (entry.LayoutProvider) tree = React.createElement(entry.LayoutProvider, { key: `layout:${scopes.get(segment)}`,
@@ -193,8 +208,9 @@ async function renderFlight(request, fallback = null, channel = null) {
       try {
         if (request.routingContexts?.size) request.renderRoutingBranch = routingBranchRenderer(cacheContext, bundlerConfig,
           renderSignal, error => publicError(error, request.production).digest);
-        let model = request.controlModel || { ...(allowedRouting ? createTree(entry, request, fallback) : { tree: null, routingInvalid: true }), router, css: request.css || [], fonts: request.fonts || [], ...(request.instantDiagnostics?.length ? { instantDiagnostics: request.instantDiagnostics } : {}), ...request.actionModel };
+        let model = request.controlModel || { ...(allowedRouting ? createTree(entry, request, fallback) : { tree: null, routingInvalid: true }), router, styleRoute: request.routePattern, css: request.css || [], ...(request.cssScopes?.length ? { cssScopes: request.cssScopes } : {}), fonts: request.fonts || [], ...(request.instantDiagnostics?.length ? { instantDiagnostics: request.instantDiagnostics } : {}), ...request.actionModel };
         if (model.routing?.params) model.router.params = model.routing.params;
+        selectAppStyles(model);
         if (request.partialFlight) {
           const consumer = { serverConsumerManifest: flightConsumer(request), replayConsoleLogs: false };
           const decode = () => {
@@ -211,14 +227,16 @@ async function renderFlight(request, fallback = null, channel = null) {
           const keyMap = request.partialKeys ? new Map(request.partialKeys) : undefined;
           model = partialModel(stored, { live, keyMap, reuse: partialTemplateReuse(stored, keyMap) });
         }
+        model.authorizationKey = navigationAuthorization(cacheContext, request.authorizationSecret || request.actionKey, request.navigationCache?.authCookies);
         const stream = renderToReadableStream(model, bundlerConfig, {
           signal: renderSignal,
           temporaryReferences: request.temporaryReferences,
           onError(error) {
             const failure = error && typeof error === 'object' ? error : new Error(String(error));
-            if (cacheContext.staticState?.partial && isPartialHole(failure)) return 'PRNEXT_PPR_DYNAMIC';
+            if ((cacheContext.staticState?.partial || request.navigationStage) && isPartialHole(failure)) return 'PRNEXT_PPR_DYNAMIC';
             renderError ??= failure;
             const digest = publicError(failure, request.production).digest;
+            if(ordinaryRenderError(failure)&&!abort.signal.aborted&&!channel?.signal.aborted){if(!failure.digest&&Object.isExtensible(failure))failure.digest=digest;const reporting=reportRequestError(failure);if(reporting&&digest.length<=1024&&request.instrumentationId!==undefined)parentPort.postMessage({id:request.instrumentationId,type:'instrumentation-error',value:digest});}
             if (!abort.signal.aborted && !channel?.signal.aborted && ordinaryRenderError(failure)) console.error(`[prnext] ${digest}`, failure?.stack || failure);
             return digest;
           },
@@ -339,7 +357,12 @@ async function renderFlight(request, fallback = null, channel = null) {
   });
 }
 
-async function handleRequest(request, channel = null) {
+async function handleRequest(request,channel=null){
+  process.env.NEXT_RUNTIME='nodejs';
+  if(!request.runtimeInstrumentation&&(request.operation==='static-params'||request.staticGeneration||request.staticState))return handleRequestInner(request,channel);
+  return withInstrumentation({...request,signal:channel?.signal,manifest:{instrumentation:request.instrumentation},route:{router:'app',kind:'page',pattern:request.routePattern,cacheConfig:request.cacheConfig}},()=>handleRequestInner(request,channel),{realm:'rsc'});
+}
+async function handleRequestInner(request, channel = null) {
   if (request.operation === 'static-params') {
     return runRequestContext({ ...request, phase: 'render' }, async () => {
       const context = currentRequest();
@@ -387,6 +410,11 @@ const responseCompletions = new Map();
 const manifests = new Map();
 const artifacts = 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'){
+    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.
@@ -403,17 +431,18 @@ parentPort.on('message', async ({ id, request, type, value, token }) => {
   for (const field of ['clientModules', 'actions']) {
     if (request[field + 'Id'] !== undefined) request[field] = manifests.get(request[field + 'Id']);
   }
+  request.instrumentationId=id;
   const channel = request.stream && (!request.action || request.action.id) ? workerStreamChannel(parentPort, id) : null;
   let responseDone, responseTimer;
-  if (request.action && request.cacheConfig?.runtime !== 'edge') {
+  if (request.cacheConfig?.runtime !== 'edge') {
     const timeoutMs = request.renderTimeoutMs ?? 25000;
-    request.afterScope = createAfterScope({ timeoutMs, onComplete: flushCacheWork,
-      onTimeout: error => parentPort.postMessage({ id, error: { message: error.message, retireWorker: true } }) });
-    if (request.waitForResponse) responseDone = new Promise(resolve => {
+    request.afterScope = createAfterScope({report:error=>{console.error('[prnext] after() failed:',error?.stack||error);return reportRequestError(error);}, timeoutMs, onComplete: flushCacheWork,
+      onTimeout: error => parentPort.postMessage({ id, error: { message: error.message, retireWorker: true } }),
+      onRegistered() { if (request.waitForResponse) responseDone = new Promise(resolve => {
       const finish = () => { clearTimeout(responseTimer); resolve(); };
       responseCompletions.set(id, finish);
       responseTimer = setTimeout(finish, timeoutMs);
-    });
+    }); } });
   }
   activeRequests.add(id);
   if (channel) streamChannels.set(id, channel);
@@ -425,14 +454,14 @@ parentPort.on('message', async ({ id, request, type, value, token }) => {
       delete request.partialFlightId;
     }
     if (channel) {
-      await handleRequest({ ...request, renderKey: id }, channel);
+      await handleRequest({ ...request, renderKey: renderKeyFor(request, id) }, channel);
       return;
     }
-    const result = await handleRequest({ ...request, renderKey: id });
+    const result = await handleRequest({ ...request, renderKey: renderKeyFor(request, id) });
     parentPort.postMessage({ id, ...result }, result.body instanceof ArrayBuffer ? [result.body] : []);
   } catch (error) {
     parentPort.postMessage({ id, error: {
-      message: error?.message || String(error), stack: error?.stack, digest: error?.digest, statusCode: error?.statusCode,
+      instrumentationReported:wasRequestErrorReported(error), message: error?.message || String(error), stack: error?.stack, digest: error?.digest, statusCode: error?.statusCode,
       retireWorker: error?.retireWorker, responseHeaders: error?.responseHeaders,
       code: error?.code, staticMode: error?.staticMode, dynamicReason: error?.dynamicReason,
     } });

package/runtime/trace.mjs

@@ -0,0 +1,78 @@
+import {isControlError} from './navigation.mjs';
+import {AsyncLocalStorage} from 'node:async_hooks';
+import {randomBytes} from 'node:crypto';
+import {createRequire} from 'node:module';
+const scope=new AsyncLocalStorage(),rawFetch=globalThis.fetch;
+let api;
+try{api=createRequire(import.meta.url)('@opentelemetry/api');}catch{}
+const endpoint=process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT||(process.env.OTEL_EXPORTER_OTLP_ENDPOINT?process.env.OTEL_EXPORTER_OTLP_ENDPOINT.replace(/\/$/,'')+'/v1/traces':undefined);
+const protocol=process.env.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL||process.env.OTEL_EXPORTER_OTLP_PROTOCOL;
+const enabled=process.env.OTEL_SDK_DISABLED!=='true'&&endpoint&&(!protocol||protocol==='http/json');
+const queue=[];let timer,flushing;
+const epoch=BigInt(Date.now())*1000000n-process.hrtime.bigint();
+const nanos=()=>String(epoch+process.hrtime.bigint());
+export function parseTraceparent(value){
+  const match=/^00-([a-f0-9]{32})-([a-f0-9]{16})-([a-f0-9]{2})$/.exec(value||'');
+  return match&&!/^0+$/.test(match[1])&&!/^0+$/.test(match[2])?{traceId:match[1],spanId:match[2],traceFlags:parseInt(match[3],16)&1}:undefined;
+}
+export function currentTraceparent(){const value=scope.getStore();return value?`00-${value.traceId}-${value.spanId}-${value.traceFlags?'01':'00'}`:undefined;}
+export function propagatedFetch(input,init){
+  const parent=currentTraceparent();if(!parent)return [input,init];
+  const headers=new Headers(init?.headers??(input instanceof Request?input.headers:undefined));
+  if(!headers.has('traceparent'))headers.set('traceparent',parent);
+  return [input,{...init,headers}];
+}
+function enqueue(span){
+  if(!enabled||!span.flags||queue.length>=1024)return;
+  queue.push(span);if(!timer)timer=setTimeout(()=>{timer=undefined;void flushTraces();},200).unref();
+}
+export async function flushTraces(){
+  if(flushing)return flushing;
+  if(!queue.length)return;
+  const headers={'content-type':'application/json'};
+  for(const part of (process.env.OTEL_EXPORTER_OTLP_TRACES_HEADERS||process.env.OTEL_EXPORTER_OTLP_HEADERS||'').split(',')){
+    const split=part.indexOf('=');if(split>0)try{headers[part.slice(0,split).trim()]=decodeURIComponent(part.slice(split+1).trim());}catch{}
+  }
+  const spans=queue.splice(0,128);
+  flushing=(async()=>{
+    const body=JSON.stringify({resourceSpans:[{resource:{attributes:[{key:'service.name',value:{stringValue:process.env.OTEL_SERVICE_NAME||'prnext'}}]},scopeSpans:[{scope:{name:'prnext.runtime'},spans}]}]});
+    for(let attempt=0;attempt<3;attempt++){
+      let retry=false;
+      try{
+        const response=await rawFetch(endpoint,{method:'POST',redirect:'error',headers,body,signal:AbortSignal.timeout(1000)});
+        retry=[429,502,503,504].includes(response.status);await response.body?.cancel();
+      }catch{retry=true;} // Telemetry failure never changes an application response.
+      if(!retry)break;
+      if(attempt<2)await new Promise(resolve=>setTimeout(resolve,100*2**attempt).unref());
+    }
+  })().finally(()=>{flushing=undefined;if(queue.length&&!timer)timer=setTimeout(()=>{timer=undefined;void flushTraces();},200).unref();});
+  return flushing;
+}
+export async function drainTraces(){
+  const deadline=Date.now()+2500;let timeout;
+  try{
+    await Promise.race([(async()=>{while((flushing||queue.length)&&Date.now()<deadline)await(flushing||flushTraces());})(),new Promise(resolve=>{timeout=setTimeout(resolve,2500);})]);
+  }finally{clearTimeout(timeout);clearTimeout(timer);timer=undefined;}
+}
+export function markTraceError(){const state=scope.getStore();if(state?.span)state.span.status={code:2};state?.sdkSpan?.setStatus({code:2});}
+export async function withTrace(options,name,callback){
+  const parent=scope.getStore()||parseTraceparent(options.traceparent||new Headers(options.headers).get('traceparent'));
+  if(!enabled&&!api&&!parent)return callback();
+  let sdkSpan;
+  if(!enabled&&api){
+    const remote=parent?api.trace.setSpanContext(api.context.active(),{traceId:parent.traceId,spanId:parent.spanId,traceFlags:parent.traceFlags,isRemote:true}):api.context.active();
+    sdkSpan=api.trace.getTracer('prnext.runtime').startSpan(name,{kind:options.kind||1},remote);
+    const context=sdkSpan.spanContext();
+    if(!api.trace.isSpanContextValid(context)){sdkSpan.end();return callback();}
+    const run=()=>scope.run({...context,sdkSpan},callback);
+    try{return await api.context.with(api.trace.setSpan(remote,sdkSpan),run);}catch(error){if(!isControlError(error))sdkSpan.setStatus({code:2});throw error;}finally{sdkSpan.end();}
+  }
+  const span={traceId:parent?.traceId||randomBytes(16).toString('hex'),spanId:randomBytes(8).toString('hex'),parentSpanId:parent?.spanId,
+    flags:parent?.traceFlags??1,name,kind:options.kind||1,startTimeUnixNano:nanos(),attributes:[]};
+  if(options.route?.pattern)span.attributes.push({key:'http.route',value:{stringValue:options.route.pattern}});
+  const state={traceId:span.traceId,spanId:span.spanId,traceFlags:span.flags,span};
+  const run=()=>scope.run(state,async()=>{
+    try{const result=await callback();if(result?.status>=500)span.status={code:2};return result;}catch(error){if(!isControlError(error))span.status={code:2};throw error;}finally{span.endTimeUnixNano=nanos();enqueue(span);}
+  });
+  return api?api.context.with(api.trace.setSpanContext(api.context.active(),{traceId:state.traceId,spanId:state.spanId,traceFlags:state.traceFlags}),run):run();
+}

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, '/');
@@ -22,14 +23,14 @@ export async function watchProject(root, { onChange, onError, ignore = () => fal
         // Rebuilding on those reads restarts the server (and its SSE stream).
         try { if (statSync(path.join(root, relative)).isDirectory()) return; } catch {}
       }
-      onChange(relative);
+      onChange(relative,event);
     });
     watcher.on('error', error => { watcher.close(); onError(error); });
     return { close: () => watcher.close(), async refresh() {} };
   }
   const directories = new Map();
-  const pending = new Set();
-  let closed = false, ready = false, timer, running, refreshAll = false;
+  const pending = new Map();
+  let closed = false, ready = false, timer, running;
   const allowedDirectory = relative => !relative || (!ignore(relative) && (relative === '.contentlayer' || shouldWatchProjectFile(relative)));
   const allowedFile = relative => relative && !ignore(relative) && shouldWatchProjectFile(relative);
   function remove(relative) {
@@ -50,9 +51,9 @@ export async function watchProject(root, { onChange, onError, ignore = () => fal
     close();
     onError(error);
   }
-  function queue(relative) {
+  function queue(relative, recursive = false) {
     if (closed) return;
-    pending.add(relative);
+    pending.set(relative, recursive || pending.get(relative) === true);
     clearTimeout(timer);
     timer = setTimeout(() => { void drain().catch(fail); }, 20);
   }
@@ -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,18 +80,28 @@ 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,event);
           // 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.
-          // Rescan only this directory, rather than relying on the event name.
-          if (allowedDirectory(changed) || allowedFile(changed)) queue(relative);
+          // Coalesced notifications can name an already subscribed ancestor,
+          // without a separate event from the changed descendant. Reconcile
+          // that subtree even when its existing directory watches are intact.
+          // Ordinary file edits still scan only their immediate parent.
+          if (!filename) queue(relative, true);
+          else if (allowedDirectory(changed) || allowedFile(changed)) {
+            queue(relative);
+            if (!metadataOnly && directories.has(changed)) queue(changed, true);
+          }
         });
       } catch (error) { if (relative && missing(error)) { disappeared(relative); return; } throw error; }
       directories.set(relative, watcher);
       // Files may already exist by the time a newly created directory is
       // subscribed. Its discovery must also invalidate the source snapshot.
-      if (ready && allowedFile(relative)) onChange(relative);
+      if (ready && allowedFile(relative)) onChange(relative,'rename');
       watcher.on('error', error => {
         if (closed) return;
         if (relative && missing(error)) disappeared(relative);
@@ -103,6 +115,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,'rename');
       if (!entry.isDirectory() || !allowedDirectory(child)) continue;
       children.add(child);
       if (recursive || !directories.has(child)) await scan(child, recursive);
@@ -116,8 +129,7 @@ export async function watchProject(root, { onChange, onError, ignore = () => fal
     running = (async () => {
       while (!closed && pending.size) {
         const batch = [...pending]; pending.clear();
-        const recursive = refreshAll; refreshAll = false;
-        for (const relative of batch) await scan(relative, recursive);
+        for (const [relative, recursive] of batch) await scan(relative, recursive);
       }
     })().finally(() => { running = undefined; });
     return running;
@@ -129,8 +141,7 @@ export async function watchProject(root, { onChange, onError, ignore = () => fal
     close,
     async refresh() {
       if (closed) return;
-      refreshAll = true;
-      pending.add('');
+      pending.set('', true);
       await drain();
     },
   };

package/runtime/worker.mjs

@@ -1,6 +1,12 @@
+import {drainTraces} from './trace.mjs';
+import {advancedRoutingSources} from './app-routing-state.mjs';
+import {initializeInstrumentation,withInstrumentation} from './instrumentation.mjs';
+import {deferredCompiler} from './dev-compiler-broker.mjs';
 // 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 +42,24 @@ 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;
+const compilerDescriptor=process.env.PRNEXT_DEV_COMPILER;
+delete process.env.PRNEXT_DEV_COMPILER;
+process.env.NEXT_RUNTIME='nodejs';
+await initializeInstrumentation(distDir,manifest);
+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 runtimeModule = async (name,directory=distDir) => {
   const started = diagnostics.enabled ? performance.now() : 0;
-  const module = await import(pathToFileURL(path.join(distDir, `runtime/${name}.mjs`)).href);
+  const module = await import(pathToFileURL(path.join(directory, `runtime/${name}.mjs`)).href);
+  scheduleCompileCacheFlush();
   if (diagnostics.enabled) diagnostics.record('wake', { phase: 'module', module: name, durationMs: performance.now() - started });
   return module;
 };
@@ -50,20 +68,69 @@ try { ({ errorResponse } = await runtimeModule('http')); }
 catch (error) { console.error('PRNext worker could not load the project runtime:', error.message); process.exit(1); }
 const routes = new Map(manifest.routes.map(route => [route.id, route]));
 const prerendered = new Set((manifest.prerendered || []).map(item => item.path));
-let appRuntime;
-let appStaticRuntime;
-let routeStaticRuntime;
-let middlewareRuntime;
-let pagesRuntime;
-let apiRuntime;
-let incrementalRuntime;
+const deployment={distDir,manifest,routes,prerendered,modules:new Map()};
+const deployments=new Map([[distDir,deployment]]);
+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');
+  const next=await compileDeferred(route.pattern,signal,sources);
+  let value=deployments.get(next.distDir);
+  if(!value){value={...next,routes:new Map(next.manifest.routes.map(route=>[route.id,route])),prerendered:new Set(),modules:new Map()};deployments.set(next.distDir,value);while(deployments.size>4)deployments.delete(deployments.keys().next().value);}
+  const resolved=value.routes.get(route.id);
+  if(!resolved||resolved.devDeferred)throw Error('Compiler did not materialize the selected route');
+  return value;
+}
+
+async function drainRuntime(){
+  for(const value of deployments.values())if(value.modules.has('app-render')||value.modules.has('app-static')){
+    const runtime=await(value.modules.get('app-render')||import(pathToFileURL(path.join(value.distDir,'runtime/app-render.mjs')).href));
+    await runtime.drainAppRuntime();
+  }
+  await drainTraces();
+}
 
-async function handleRequest(input, output, signalController, responseComplete) {
+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;}
+  };
   let responseStarted = false;
   const finalizers = new Set();
   try {
+    if(input.routeId==='__prnext_preload'&&['preload','prewarm'].includes(input.renderMode)){
+      const frameworkOnly=input.renderMode==='prewarm';
+      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;
+      }
+      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'){
+          const appRuntime=await renderer('app-render');
+          await appRuntime.preloadAppRoutes([path.resolve(distDir,route.module)],remaining);
+        }else{
+          if(route.kind==='page')await renderer('render');else await renderer('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 incrementalRuntime = await renderer('incremental-cache');
       const result = await incrementalRuntime.runIncrementalCache({ ...input, manifest, distDir, production, signal: signalController.signal });
       input.body = undefined;
       responseStarted = true;
@@ -75,31 +142,38 @@ async function handleRequest(input, output, signalController, responseComplete)
       ? { ...manifest.middleware, id: '__prnext_middleware', kind: 'middleware' }
       : routes.get(input.routeId);
     if (!route) { await output(input.id, { status: 404, body: 'Not Found' }, input); return; }
+    const sourceModules=!production&&route.router==='app'&&route.kind==='page'?advancedRoutingSources({...input,basePath:manifest.config?.basePath||''},manifest.routes):[];
+    const deferredSources=sourceModules.length?manifest.routes.filter(candidate=>candidate.devDeferred&&sourceModules.includes(candidate.module)).map(candidate=>candidate.pattern):[];
+    if(route.devDeferred||deferredSources.length){
+      const next=await deferredDeployment(route,signalController.signal,deferredSources);
+      return await handleRequest(input,output,signalController,responseComplete,next);
+    }
     const requestedPath = new URL(input.url).pathname;
     if (route.router !== 'app' && !['isr', 'error404', 'error500'].includes(input.renderMode) && route.fallback === false && !prerendered.has(requestedPath) && !prerendered.has(requestedPath.replace(/\/$/, '') || '/')) {
       await output(input.id, { status: 404, body: 'Not Found' }, input); return;
     }
     const options = { ...input, modulePath: path.resolve(distDir, route.module), route, production, manifest, distDir, signal: signalController.signal, deferFinalizer: finalize => finalizers.add(finalize) };
+    return await withInstrumentation(options,async()=>{
     let result;
     if (isMiddleware) {
-      middlewareRuntime ??= await import(pathToFileURL(path.join(distDir, 'runtime/middleware.mjs')).href);
+      const middlewareRuntime = await renderer('middleware');
       result = await middlewareRuntime.runMiddleware(options);
     } else if (route.router === 'app' && route.kind === 'page') {
       if (input.renderMode === 'isr') {
-        appStaticRuntime ??= await import(pathToFileURL(path.join(distDir, 'runtime/app-static.mjs')).href);
+        const appStaticRuntime = await renderer('app-static');
         result = await appStaticRuntime.renderAppIsrPage(options);
       } else {
-        appRuntime ??= await runtimeModule('app-render');
+        const appRuntime = await renderer('app-render');
         result = await appRuntime.renderAppPage(options);
       }
     } else if (route.router === 'app' && route.kind === 'api' && input.renderMode === 'isr') {
-      routeStaticRuntime ??= await import(pathToFileURL(path.join(distDir, 'runtime/route-static.mjs')).href);
+      const routeStaticRuntime = await renderer('route-static');
       result = await routeStaticRuntime.renderRouteHandlerIsr(options);
     } else if (route.kind === 'api') {
-      apiRuntime ??= await runtimeModule('api');
+      const apiRuntime = await renderer('api');
       result = await apiRuntime.runApi(options);
     } else {
-      pagesRuntime ??= await runtimeModule('render');
+      const pagesRuntime = await renderer('render');
       result = input.renderMode === 'isr' ? await pagesRuntime.renderIsrPage({ ...options, capturePageFailure: true })
         : await pagesRuntime.renderPageRequest({ ...options, nativeErrors: true });
     }
@@ -111,6 +185,7 @@ async function handleRequest(input, output, signalController, responseComplete)
     if (result.finalizeCache) finalizers.add(result.finalizeCache);
     await output(input.id, result, { ...input, production, signalController });
     responseComplete?.();
+    });
   } catch (error) {
     const cancelled = signalController.signal.aborted || error instanceof ProtocolWriteError;
     signalController.abort(error);
@@ -160,7 +235,8 @@ if (token && laneLimit > 1) {
     reportedBusy = true;
     writeProtocol('busy\n');
   };
-  const exitWhenDrained = () => { if (shuttingDown && !invocations.size) process.exit(0); };
+  let exiting=false;
+  const exitWhenDrained = () => { if (shuttingDown && !invocations.size&&!exiting){exiting=true;void drainRuntime().catch(error=>console.error('[prnext] Runtime drain failed:',error?.message)).finally(()=>process.exit(0));} };
   const server = net.createServer(socket => {
     if (sockets.size >= laneLimit) { socket.destroy(); return; }
     sockets.add(socket); socket.setNoDelay(true);
@@ -223,7 +299,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 +338,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 +349,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,14 +357,11 @@ 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.
   // RSC settlement can still outlive its terminal frame; drain it explicitly
   // before closing the isolate's MessagePorts after parent EOF.
-  if (appRuntime || appStaticRuntime) {
-    const runtime = appRuntime || await runtimeModule('app-render');
-    await runtime.drainAppRuntime();
-  }
+  await drainRuntime();
 }