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

package/build/dev.mjs

@@ -9,6 +9,44 @@ import {inlineSourceMap} from './source-maps.mjs';
 
 const packageRoot = fileURLToPath(new URL('../', import.meta.url));
 export const devClientFile = path.join(packageRoot, 'runtime/dev-client.mjs');
+const refreshIdentities = new Map();
+function namedDefaultComponents({types:t}){
+  return {visitor:{Program:{enter(program){
+    if(program.node.directives.some(item=>item.value.value==='use server'))return;
+    for(const statement of program.get('body')){
+      if(!statement.isExportDefaultDeclaration())continue;
+      const value=statement.get('declaration');if(!value.isArrowFunctionExpression())continue;
+      let jsx=false;value.traverse({JSXElement(p){jsx=true;p.stop();},JSXFragment(p){jsx=true;p.stop();}});if(!jsx)continue;
+      let name='PRNextDefaultComponent',suffix=0;
+      while(program.scope.hasBinding(name)||program.scope.hasGlobal(name))name='PRNextDefaultComponent'+(++suffix);
+      const id=t.identifier(name);
+      statement.replaceWithMultiple([t.variableDeclaration('const',[t.variableDeclarator(id,value.node)]),t.exportDefaultDeclaration(t.cloneNode(id))]);
+      program.scope.crawl();
+    }
+  }}}};
+}
+function sourceElements(id){return ({types:t})=>({visitor:{JSXOpeningElement(node){
+  const name=node.node.name;
+  if(name.type!=='JSXIdentifier'||!/^[a-z]/.test(name.name)||node.node.attributes.some(attribute=>attribute.type==='JSXAttribute'&&attribute.name.name==='data-prnext-source'))return;
+  const start=node.node.loc?.start;if(!start)return;
+  node.node.attributes.push(t.jsxAttribute(t.jsxIdentifier('data-prnext-source'),t.stringLiteral(`${id}:${start.line}:${start.column+1}`)));
+}}});}
+
+/** The same original JSX locations must be present in SSR and browser output. */
+export function createSourceLocationTransform(projectRoot){
+  projectRoot=path.resolve(projectRoot);const canonicalRoot=realpath(projectRoot).catch(()=>projectRoot);
+  return async(source,filename)=>{
+    filename=path.resolve(filename);
+    if(!source.includes('<')||filename.includes(`${path.sep}node_modules${path.sep}`)||filename.includes(`${path.sep}.prnext-build-`))return source;
+    const root=filename.startsWith(projectRoot+path.sep)?projectRoot:await canonicalRoot;
+    if(!filename.startsWith(root+path.sep))return source;
+    const id=path.relative(root,filename).split(path.sep).join('/');
+    return cachedAsyncTransform('dev-source-elements',source,[root,filename,'v1'],async()=>{
+      const result=await transformAsync(source,{filename,babelrc:false,configFile:false,sourceMaps:true,sourceFileName:filename,sourceType:'unambiguous',parserOpts:{plugins:['jsx',...(/\.tsx?$/.test(filename)?['typescript']:[])]},plugins:[sourceElements(id)]});
+      return inlineSourceMap(result.code,result.map);
+    });
+  };
+}
 
 /** Keep React renderers and framework contexts identical across rebuilt ESM chunks. */
 export function devSingletonsPlugin() {
@@ -46,8 +84,9 @@ function componentExports(program) {
 }
 
 /** The official React transform records hook signatures and refresh families. */
-export function createRefreshTransform(projectRoot) {
+export function createRefreshTransform(projectRoot, { generation,forceGeneration=false,forceFiles } = {}) {
   projectRoot = path.resolve(projectRoot);
+  const affected=forceFiles&&new Set(forceFiles.map(file=>path.resolve(projectRoot,file)));
   const canonicalRoot = realpath(projectRoot).catch(() => projectRoot);
   return async (source, filename) => {
     filename = path.resolve(filename);
@@ -57,13 +96,13 @@ export function createRefreshTransform(projectRoot) {
     const root = filename.startsWith(projectRoot + path.sep) ? projectRoot : await canonicalRoot;
     if (!filename.startsWith(root + path.sep)) return source;
     const hash = createHash('sha256').update(source).digest('hex');
-    return cachedAsyncTransform('fast-refresh',source,[projectRoot,filename],async () => {
+    const transformed = await cachedAsyncTransform('fast-refresh',source,[projectRoot,filename,'source-elements-v2'],async () => {
+      const id = path.relative(root, filename).replaceAll(path.sep, '/');
       const result = await transformAsync(source, { filename, babelrc: false, configFile: false,
         ast: true, sourceMaps: true, sourceFileName:filename, sourceType: 'unambiguous',
         parserOpts: { plugins: ['jsx', ...(/\.tsx?$/.test(filename) ? ['typescript'] : [])] },
-        plugins: [[refresh, { skipEnvCheck: true, refreshReg: '__prnextRefreshReg', refreshSig: '__prnextRefreshSig' }]],
+        plugins: [namedDefaultComponents,[refresh, { skipEnvCheck: true, refreshReg: '__prnextRefreshReg', refreshSig: '__prnextRefreshSig' }],sourceElements(id)],
       });
-      const id = path.relative(root, filename).replaceAll(path.sep, '/');
       // An ESM import changes webpack's interpretation of module.exports.
       // Keep script/CommonJS inputs in their original module format.
       const runtime = result.ast.program.sourceType === 'script'
@@ -73,5 +112,17 @@ export function createRefreshTransform(projectRoot) {
       const prefix = `${strict}${runtime}function __prnextRefreshReg(type,id){__prnextRegister(type,${JSON.stringify(id + ':')}+id)};\n`;
       return inlineSourceMap(prefix + result.code + `\n__prnextRegisterModule(${JSON.stringify(id)},${JSON.stringify(hash)},${componentExports(result.ast.program)});\n`,{...result.map,mappings:';'+result.map.mappings});
     });
+    // ESM URLs are cached forever by the browser. A -> B -> exact A otherwise
+    // imports an already evaluated content-hashed chunk and never registers A
+    // with React Refresh again. Mark project modules per generation, after the
+    // persistent transform cache. Keep the marker stable for unchanged modules:
+    // esbuild can retain their parsed graph rather than reparsing every route.
+    if(!generation)return transformed;
+    const identity=refreshIdentities.get(filename);
+    if((affected?affected.has(filename):forceGeneration)||!identity||identity.hash!==hash){
+      if(refreshIdentities.size>=50_000&&!identity)refreshIdentities.delete(refreshIdentities.keys().next().value);
+      refreshIdentities.set(filename,{hash,generation});
+    }
+    return transformed + `\nglobalThis.__PRNEXT_DEV__.evaluatedGeneration=${JSON.stringify(refreshIdentities.get(filename).generation)};\n`;
   };
 }

package/build/edge.mjs

@@ -1,9 +1,9 @@
 import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
-import {frameworkImportName, frameworkSubpathPattern} from './framework-imports.mjs';
+import {applicationEntry, frameworkImportName, frameworkSubpathPattern} from './framework-imports.mjs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { builtinModules, createRequire } from 'node:module';
-import { build } from './compiler.mjs';
+import { build, readCompilerFile } from './compiler.mjs';
 import { parse } from '@babel/parser';
 import traversePackage from '@babel/traverse';
 import { cachedTransform } from './transform-cache.mjs';
@@ -85,6 +85,7 @@ export async function compileEdge({ file, outfile, projectRoot, dev = false, def
     mainFields: ['browser', 'module', 'main'], logLevel: 'silent', metafile: true,
     define: { 'process.env.NODE_ENV': JSON.stringify(dev ? 'development' : 'production'), ...defineEnvironment, 'process.env.NEXT_RUNTIME': '"edge"' },
     plugins: [...plugins, { name: 'prnext-edge', setup(builder) {
+      applicationEntry(builder,readCompilerFile);
       builder.onResolve({ filter: /.*/ }, args => {
         if (builtin.has(args.path) || args.path.startsWith('node:')) return { errors: [{ text: `Node.js module ${args.path} cannot run in the Edge Runtime (${args.importer}).` }] };
         if (reactMode && ['react', 'react/jsx-runtime', 'react/jsx-dev-runtime', 'react-dom', 'react-server-dom-webpack/server', 'react-server-dom-webpack/server.node'].includes(args.path)) return { path: args.path, namespace: 'prnext-edge-react' };

package/build/framework-imports.mjs

@@ -1,3 +1,8 @@
+import {fileURLToPath} from 'node:url';
+import {dirname} from 'node:path';
+import {readFile} from 'node:fs/promises';
+import {analyzeSource} from './source-analysis.mjs';
+import {cachedTransform} from './transform-cache.mjs';
 const adapters = new Map([
   ['dist/shared/lib/router-context.shared-runtime','next-router-context'],
   ['dist/shared/lib/router-context','next-router-context'],
@@ -15,3 +20,38 @@ export function frameworkImportName(specifier) {
   const name=specifier.replace(frameworkSubpathPattern, '').replace(/\.js$/,'');
   return adapters.get(name) || name;
 }
+
+// Application graphs must not traverse the programmatic build API's native tools.
+// Outside a compiled application, the package root retains its full Node API.
+export function applicationEntry(builder,readSource=(file,override)=>override??readFile(file,'utf8')){
+  // esbuild understands .mts/.cts, but our framework transforms do not. Never
+  // silently bundle a server implementation or misclassify a client boundary.
+  builder.onLoad({filter:/\.[cm]ts$/i,namespace:'file'},async args=>{
+    // Loader bridges dispatch framework callbacks independently of their filters.
+    if(!/\.[cm]ts$/i.test(args.path))return;
+    const source=await readSource(args.path,args.prnextSource);
+    const original=args.prnextSource===undefined?source:await readSource(args.path);
+    // A loader may remove a directive as well as introduce one. Both versions
+    // must be safe before its output can become an ordinary browser module.
+    for(const candidate of new Set([original,source])){
+     const unsupported=cachedTransform('unsupported-framework-directives',candidate,[args.path,'v3'],()=>{
+      const analysis=analyzeSource(candidate,args.path);
+      if(analysis.frameworkBoundary)return 'yes';
+      const pending=[analysis.program];
+      while(pending.length){
+        const node=pending.pop();
+        if(node.type==='ExpressionStatement'&&node.directive==='use server')return 'yes';
+        for(const value of Object.values(node)){
+          if(Array.isArray(value)){for(const item of value)if(item?.type)pending.push(item);}
+          else if(value&&typeof value==='object'&&value.type)pending.push(value);
+        }
+      }
+      return 'no';
+     });
+     if(unsupported==='yes')throw new Error(`React server/client directives are not supported in ${args.path}. Rename this file to .ts or .tsx.`);
+    }
+    return {contents:source,loader:args.prnextSource===undefined?'ts':'tsx',resolveDir:dirname(args.path)};
+  });
+  builder.onResolve({filter:/^(?:prnext|@thomas\.f\/prnext)(?:\/route(?:\.js)?)?$/},()=>
+    ({path:fileURLToPath(new URL('../runtime/typed-route.mjs',import.meta.url))}));
+}

package/build/incremental.mjs

@@ -3,13 +3,17 @@ import { readFile, writeFile, mkdir, realpath } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import {clearDirectoryCache} from './directory-cache.mjs';
+import {closeWebpackCompiler,webpackCompilerStats} from './webpack-graph.mjs';
 const contexts = new Map();
 const LIMIT = 8;
 let created = 0, reused = 0;
-export const incrementalCompilerStats = () => ({contexts:contexts.size, created, reused});
-export async function closeIncrementalCompiler() {
+export const incrementalCompilerStats = () => ({contexts:contexts.size, created, reused,webpack:webpackCompilerStats()});
+export async function closeIncrementalCompiler(root) {
   clearDirectoryCache();
-  const active=[...contexts.values()];contexts.clear();await Promise.all(active.map(slot=>slot.context.dispose()));
+  const active=[];for(const [key,slot] of contexts)if(root===undefined||slot.root===root){contexts.delete(key);active.push(slot);}
+  const results=await Promise.allSettled([...active.map(slot=>slot.context.dispose()),closeWebpackCompiler(root)]);
+  const errors=results.filter(result=>result.status==='rejected').map(result=>result.reason);
+  if(errors.length)throw new AggregateError(errors,'Unable to dispose incremental compiler sessions');
 }
 /** Retain esbuild's parsed module graphs while rebinding per-build framework plugins. */
 export async function incrementalBuild(options, {root,stage,group='project',run=callback=>callback()}) {
@@ -40,7 +44,7 @@ export async function incrementalBuild(options, {root,stage,group='project',run=
   if(slot){contexts.delete(key);reused++;}
   else {
     while([...contexts.values()].filter(slot=>slot.group===group).length>=(group==='auxiliary'?2:LIMIT)){const [oldest,previous]=[...contexts].find(([,slot])=>slot.group===group);contexts.delete(oldest);await previous.context.dispose();}
-    created++;slot={group};
+    created++;slot={group,root};
     slot.current={hooks,run,toVirtual,fromVirtual,virtualResult,stage};
     slot.context=await context({...normalized,plugins:[{name:'prnext-incremental-delegates',setup(builder){
       slot.builder=builder;

package/build/index.mjs

@@ -1,11 +1,17 @@
+import {prerenderPages as prerender} from './prerender-pages.mjs';
+import {isolatedPrerender} from './production-builder.mjs';
 import { rename } from '../runtime/fs.mjs';
 import { writeRuntimeContract } from './runtime-contract.mjs';
 import { writeBuildOutput } from './output-contract.mjs';
 import { bundleRuntime } from './bundle-runtime.mjs';
-import {frameworkImportName, frameworkRuntimeImportPattern} from './framework-imports.mjs';
+import {withPersistentTransforms} from './transform-cache.mjs';
+import {applicationEntry, frameworkImportName, frameworkRuntimeImportPattern} from './framework-imports.mjs';
 import { expandLocales, localizedStaticPaths } from './i18n.mjs';
-import { build as bundle, withCompilation, configureCompiler, compilerSource } from './compiler.mjs';
-import { mkdir, readFile, writeFile, rm, cp, stat, readdir } from 'node:fs/promises';
+import { build as bundle, withCompilation, configureCompiler, compilerSource,buildAnalysisRecords,buildAnalysisRoutes,devDependencies,devStylePlans,devStyleDependencies,devModules,readCompilerFile } from './compiler.mjs';
+import {writeBuildAnalysis} from './analyze.mjs';
+import {routeFiles} from './dev-discovery.mjs';
+import {writeTypedRoutes} from './typed-routes.mjs';
+import { mkdir, readFile, writeFile, rm, cp, copyFile, stat, readdir } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
@@ -30,7 +36,7 @@ import { prepareMetadataRoutes } from './metadata-routes.mjs';
 import { prepareImageResponse } from './og.mjs';
 import { prepareCacheHandler, prepareCacheHandlers } from './cache-handlers.mjs';
 import { npmPackagesPlugin } from './npm-packages.mjs';
-import { createRefreshTransform, devSingletonsPlugin, devClientFile } from './dev.mjs';
+import { createRefreshTransform, createSourceLocationTransform, devSingletonsPlugin, devClientFile } from './dev.mjs';
 import { snapshotEnvConfig } from '../runtime/env.mjs';
 import { validateStaticPaths } from '../runtime/pages-paths.mjs';
 import { projectTsconfig, checkTypeScript } from './typescript.mjs';
@@ -41,10 +47,32 @@ const compatibleModules = new Set(['link', 'head', 'router', 'compat/router', 'n
 const extensions = { '.js': 'jsx', '.jsx': 'jsx', '.mjs': 'jsx', '.cjs': 'jsx', '.ts': 'ts', '.tsx': 'tsx' };
 const assetLoaders = Object.fromEntries(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg', '.ico', '.woff', '.woff2', '.ttf', '.eot'].map(ext => [ext, 'file']));
 
-function compatibilityPlugin({ browser, pageFiles, projectRoot, documentFile, fonts, refresh }) {
+// These framework files have already been enumerated: copyFile avoids cp's
+// recursive traversal/stat work for every file. Bound I/O on large installations.
+async function copyRuntimeFiles(stage) {
+  const files = (await Promise.all(['runtime', 'compat'].map(async directory => {
+    await mkdir(path.join(stage, directory), { recursive: true });
+    return (await readdir(path.join(packageRoot, directory)))
+      .filter(name => directory === 'runtime' ? name === 'profiles.json' || name.endsWith('.mjs') && !name.endsWith('.test.mjs') : name.endsWith('.cjs'))
+      .map(name => path.join(directory, name));
+  }))).flat();
+  let next = 0;
+  const copying = await Promise.allSettled(Array.from({ length: Math.min(8, files.length) }, async () => {
+    while (next < files.length) {
+      const file = files[next++];
+      await copyFile(path.join(packageRoot, file), path.join(stage, file));
+    }
+  }));
+  // Let outstanding writes finish before the caller removes a failed stage.
+  const failed = copying.find(result => result.status === 'rejected');
+  if (failed) throw failed.reason;
+}
+
+function compatibilityPlugin({ browser, pageFiles, projectRoot, documentFile, fonts, refresh, locations }) {
   return {
     name: 'prnext-pages-compatibility',
     setup(esbuild) {
+      applicationEntry(esbuild,readCompilerFile);
       esbuild.onResolve({ filter: /\.(?:css|scss|sass)$/i }, args => args.importer === documentFile
         ? { errors: [{ text: 'CSS cannot be imported within pages/_document. Move global styles to pages/_app, or return collected styles from Document.getInitialProps.' }] } : undefined);
       esbuild.onResolve({ filter: frameworkRuntimeImportPattern }, args => {
@@ -69,7 +97,8 @@ function compatibilityPlugin({ browser, pageFiles, projectRoot, documentFile, fo
       }
       esbuild.onLoad({ filter: /\.(?:[cm]?js|jsx|tsx?)$/, namespace: 'file' }, async args => {
         if (browser && args.path === documentFile) return { errors: [{ text: 'pages/_document is server-only and cannot be imported by a browser page or component.' }] };
-        const source = await fonts.transform(args.prnextSource ?? await readFile(args.path, 'utf8'), args.path);
+        const original=await readCompilerFile(args.path,args.prnextSource);
+        const source = await fonts.transform(locations?await locations(original,args.path):original, args.path);
         assertSupportedSource(source, args.path);
         const dynamicSource = transformDynamicImports(source, args.path, { projectRoot, mode: browser ? 'browser' : 'server' });
         let contents = browser && pageFiles.has(args.path) ? stripServerCode(dynamicSource, args.path) : dynamicSource;
@@ -110,91 +139,34 @@ async function addBuiltinPagesErrors(project, stage) {
   }
 }
 
-async function prerender(stage, manifest, dev) {
-  const { prerenderRoute, renderFallback } = await import(pathToFileURL(path.join(stage, 'runtime/render.mjs')).href);
-  const paths = new Set();
-  const seedsByRoute = new Map();
-  const validatedDocuments = new Set();
-  const staticListings = new Map();
-  // Error page data is available when another static page returns notFound.
-  const ordered = [...manifest.routes].sort((left, right) => Number(!!right.errorStatus) - Number(!!left.errorStatus));
-  for (const route of ordered) {
-    if (route.kind !== 'page' || route.router === 'app') continue;
-    const modulePath = path.join(stage, route.module);
-    const page = await import(pathToFileURL(modulePath).href);
-    if (page.__prnextDocument && !validatedDocuments.has(page.__prnextDocument)) {
-      for (const name of ['getStaticProps', 'getStaticPaths', 'getServerSideProps']) {
-        if (Object.hasOwn(page.__prnextDocument, name) || typeof page.Document?.[name] === 'function') throw new Error(`pages/_document does not support ${name}. Use Document.getInitialProps for server document rendering.`);
-      }
-      validatedDocuments.add(page.__prnextDocument);
-    }
-    if (route.errorStatus && (page.getServerSideProps || page.default?.getInitialProps)) throw new Error(`pages${route.pattern} must be static and cannot use getServerSideProps or getInitialProps. Use getStaticProps instead.`);
-    route.gip = typeof page.default?.getInitialProps === 'function';
-    route.appGip = !!page.App && page.App.getInitialProps !== page.App.origGetInitialProps;
-    if (route.internal && route.errorStatus && route.appGip) {
-      // A custom App hook makes the built-in Error request-dependent. Select
-      // its actual _error module so the default status props and visible URL
-      // reach App.getInitialProps instead of a synthetic static wrapper.
-      const kind = route.errorStatus === 404 ? 'notFound' : 'serverError';
-      if (manifest.pagesErrors?.[kind] === route.id) delete manifest.pagesErrors[kind];
-    }
-    if (route.gip && (page.getStaticProps || page.getServerSideProps)) throw new Error(`Page ${route.pattern} cannot combine getInitialProps with getStaticProps or getServerSideProps.`);
-    if (route.internal && !route.errorStatus) {
-      if (page.getStaticProps || page.getServerSideProps || page.getStaticPaths) throw new Error('pages/_error does not support getStaticProps, getServerSideProps or getStaticPaths. Use ErrorComponent.getInitialProps instead.');
-      continue;
-    }
-    if (page.getServerSideProps && page.getStaticProps) throw new Error(`Page ${route.pattern} exports both getServerSideProps and getStaticProps. Choose one.`);
-    if (page.getStaticPaths && !page.getStaticProps) throw new Error(`Page ${route.pattern} exports getStaticPaths without getStaticProps.`);
-    if (page.getServerSideProps) { route.ssp = true; continue; }
-    if (page.getStaticProps) route.ssg = true;
-    else if (route.gip || route.appGip) continue;
-    let entries = [{ path: route.pattern, params: {} }];
-    if (isDynamic(route.pattern)) {
-      if (!page.getStaticProps) continue;
-      if (!page.getStaticPaths) throw new Error(`Dynamic page ${route.pattern} with getStaticProps must export getStaticPaths.`);
-      if (!staticListings.has(modulePath)) staticListings.set(modulePath, Promise.resolve().then(() => page.getStaticPaths(manifest.config.i18n ? {locales: manifest.config.i18n.locales, defaultLocale: manifest.config.i18n.defaultLocale} : {})));
-      const result = localizedStaticPaths(route, await staticListings.get(modulePath), manifest.config.i18n);
-      route.fallback = result.fallback;
-      entries = result.paths;
-    } else if (page.getStaticPaths) throw new Error(`getStaticPaths is only valid on dynamic pages (${route.pattern}).`);
-    for (const entry of entries) {
-      if (paths.has(entry.path)) throw new Error(`Multiple pages prerender the same path: ${entry.path}.`);
-      paths.add(entry.path);
-      const rendered = await prerenderRoute({ ...manifest.config, manifest, distDir: stage, route, modulePath, path: entry.path, params: entry.params, client: route.client, css: route.css, pattern: route.pattern, errorStatus: route.errorStatus, buildId: manifest.buildId, production: !dev });
-      const file = `static/${createHash('sha256').update(entry.path).digest('hex').slice(0, 20)}.html`;
-      await writeFile(path.join(stage, file), rendered.body);
-      const seed = { routeId: route.id, path: entry.path, file, status: route.errorStatus || rendered.status || 200, headers: rendered.headers || {} };
-      if (route.ssg) {
-        seed.dataFile = file.replace(/\.html$/, '.json');
-        seed.revalidate = rendered.revalidate ?? false;
-        seed.generatedAt = rendered.generatedAt;
-        await writeFile(path.join(stage, seed.dataFile), rendered.dataJSON);
-      }
-      manifest.prerendered.push(seed);
-      if (!seedsByRoute.has(route.id)) seedsByRoute.set(route.id, []);
-      seedsByRoute.get(route.id).push(seed);
-    }
-    if (route.fallback === true) {
-      const rendered = await renderFallback({ ...manifest.config, modulePath, path: route.pattern, params: {}, client: route.client, css: route.css, pattern: route.pattern, buildId: manifest.buildId, production: !dev });
-      route.fallbackFile = `static/fallback-${route.id}.html`;
-      await writeFile(path.join(stage, route.fallbackFile), rendered.body);
-    }
-  }
-  // Rendering errors first must not change the published route/seed ordering.
-  manifest.prerendered = manifest.routes.flatMap(route => seedsByRoute.get(route.id) || []);
-}
 
 let buildQueue = Promise.resolve();
+let developmentModulesLoaded = false;
+/** Disposing shared compiler contexts must not interrupt another queued build. */
+export function disposeBuildSession(root){
+  const task=buildQueue.then(async()=>{const {closeIncrementalCompiler}=await import('./incremental.mjs');await closeIncrementalCompiler(root);});
+  buildQueue=task.catch(()=>{});return task;
+}
 /** Isolate process.env between programmatic builds, including simultaneous calls. */
 export function build(projectRoot, options = {}) {
   const task = buildQueue.then(async () => {
+    if (options.adapter === undefined || options.adapter === 'auto') {
+      const { detectBuildAdapter } = await import('./static-input.mjs');
+      const selected = await detectBuildAdapter(projectRoot, { prepared: options.adapter === 'auto' });
+      if (selected.adapter === 'static') return (await import('./static-adapter.mjs')).buildStatic(projectRoot, { ...selected, ...options });
+      if (options.adapter === 'auto') options = { ...options, adapter: 'react' };
+    }
     if (options.adapter === 'static') return (await import('./static-adapter.mjs')).buildStatic(projectRoot, options);
     if (options.adapter !== undefined && options.adapter !== 'react') throw new Error(`Unknown PRNext adapter: ${options.adapter}`);
     if (options.from !== undefined || options.spa !== undefined) throw new Error('from and spa are only supported by the static adapter.');
     const restore = snapshotEnvConfig();
     const envMode = options.envMode || (process.env.NODE_ENV === 'test' ? 'test' : options.dev ? 'development' : 'production');
     process.env.NODE_ENV = options.dev ? 'development' : 'production';
-    try { return await withBuildLock(projectRoot, root => withCompilation(() => buildProject(root, { ...options, envMode }))); }
+    try { return await withBuildLock(projectRoot, async root => {
+      const started=performance.now();
+      const result=await withPersistentTransforms(root,{dev:!!options.dev},()=>withCompilation(() => buildProject(root, { ...options, envMode })));
+      return {...result,durationMs:Math.round(performance.now()-started)};
+    }); }
     finally { restore(); }
   });
   buildQueue = task.catch(() => {});
@@ -202,15 +174,23 @@ export function build(projectRoot, options = {}) {
 }
 
 /** Compile Pages Router and App Router projects. A failed build preserves .prnext. */
-async function buildProject(projectRoot, { dev = false, envMode, incremental = false, devInputs } = {}) {
+async function buildProject(projectRoot, { dev = false, envMode, incremental = false, devInputs, devRoutes, devSequence, devSession, devTools,devForceRefresh=false,devAffectedModules } = {}) {
   const started = performance.now();
-  const config = await loadProjectConfig(projectRoot, { dev, envMode });
+  const config = await loadProjectConfig(projectRoot, { dev, envMode, devInputs });
   const tsconfig = config.typescript ? await projectTsconfig(projectRoot, config) : undefined;
   const environment = defineEnvironment(config);
   const publicPaths = { trailingSlash: config.trailingSlash, skipTrailingSlashRedirect: config.skipTrailingSlashRedirect, basePath: config.basePath, assetPrefix: config.assetPrefix, assetBase: publicAssetBase(config) };
   const customRoutes = await compileCustomRoutes(config);
   const buildId = await generateBuildId(config, { dev });
-  const project = await scanProject(projectRoot, { basePath: config.basePath, pageExtensions: config.pageExtensions, i18n: config.i18n });
+  const scanOptions={basePath:config.basePath,pageExtensions:config.pageExtensions,i18n:config.i18n};
+  let project;
+  if(dev && Array.isArray(devRoutes)) {
+    const discovery=await scanProject(projectRoot,{...scanOptions,devAppFiles:new Set()});
+    project=await scanProject(projectRoot,{...scanOptions,devAppFiles:routeFiles(discovery,devRoutes)});
+    await writeTypedRoutes(projectRoot,discovery,config);
+    project.routes=project.routes.filter(route=>devRoutes.includes(route.pattern)||route.internal||route.errorStatus);
+  } else project=await scanProject(projectRoot,scanOptions);
+  if(!dev || !Array.isArray(devRoutes))await writeTypedRoutes(projectRoot,project,config);
   const stage = path.join(project.root, `.prnext-build-${randomUUID()}`);
   const destination = await prepareBuildDirectory(project.root, config.distDir);
   const backup = path.join(project.root, `.prnext-backup-${randomUUID()}`);
@@ -218,33 +198,28 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
   await mkdir(path.join(stage, 'static'), { recursive: true });
   await addBuiltinPagesErrors(project, stage);
   const manifest = { version: 1, dev, buildId, cacheId: randomUUID(), previewModeId: randomUUID().replaceAll('-', ''), previewModeEncryptionKey: randomBytes(32).toString('hex'),
+    ...(dev && Array.isArray(devRoutes) ? {devOnDemand:true} : {}), ...(dev && devSession ? {devSequence,devSession} : {}), ...(dev ? {devForceRefresh,devAffectedModules,devIndicators:config.devIndicators,...(devTools?{devTools}:{})} : {}),
     config: { i18n: config.i18n, skipMiddlewareUrlNormalize: config.skipMiddlewareUrlNormalize, compress: config.compress, poweredByHeader: config.poweredByHeader, reactStrictMode: config.reactStrictMode, cacheComponents: config.cacheComponents, cacheLife: config.cacheLife, images: config.images, ...publicPaths }, customRoutes, routes: [], prerendered: [],
     ...(project.pagesErrors ? { pagesErrors: project.pagesErrors } : {}) };
   // Its build-unique name is known before bundling and avoids a hash cycle
   // between page entry URLs and the manifest that lists those entries.
   const pagesManifestUrl = `${publicPaths.assetBase}/pages-manifest-${manifest.cacheId}.json`;
   if (dev) manifest.devClient = `${publicPaths.assetBase}/dev-manifest-${manifest.cacheId}.json`;
-  const development = dev ? { buildId, clientManifest: manifest.devClient } : undefined;
-  const refresh = dev ? createRefreshTransform(project.root) : undefined;
+  const development = dev ? { buildId, clientManifest: manifest.devClient, onDemand:manifest.devOnDemand===true, sequence:devSequence, session:devSession, indicator:config.devIndicators,...(devTools?{tools:devTools}:{}) } : undefined;
+  const refresh = dev ? createRefreshTransform(project.root, {generation:manifest.cacheId,forceGeneration:devForceRefresh,forceFiles:devAffectedModules}) : undefined;
+  const locations = dev ? createSourceLocationTransform(project.root) : undefined;
   const fonts = createFonts({ projectRoot: project.root, stage, assetBase: publicPaths.assetBase });
-  const cssModules = createCssModules({ projectRoot: project.root, stage, assetBase: publicPaths.assetBase, sassOptions: config.sassOptions });
+  const cssModules = createCssModules({ projectRoot: project.root, stage, assetBase: publicPaths.assetBase, sassOptions: config.sassOptions, cssEngine:config.cssEngine });
   configureCompiler({config,root:project.root,stage,buildId,dev,incremental,devInputs,tsconfig,assetBase:publicPaths.assetBase});
   try {
-    await mkdir(path.join(stage, 'runtime'), { recursive: true });
-    await mkdir(path.join(stage, 'compat'), { recursive: true });
-    for (const name of await readdir(path.join(packageRoot, 'runtime'))) {
-      if (name.endsWith('.mjs') && !name.endsWith('.test.mjs')) await cp(path.join(packageRoot, 'runtime', name), path.join(stage, 'runtime', name));
-    }
-    await cp(path.join(packageRoot, 'runtime/profiles.json'), path.join(stage, 'runtime/profiles.json'));
+    await copyRuntimeFiles(stage);
     // Runtime copies must work even when dotenv is nested beneath the PRNext
     // package instead of hoisted beside the application's dependencies.
     await bundle({ entryPoints: [path.join(packageRoot, 'runtime/env.mjs')], outfile: path.join(stage, 'runtime/env.mjs'), bundle: true, platform: 'node', format: 'esm', target: 'node22', logLevel: 'silent', banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" } });
-    for (const name of await readdir(path.join(packageRoot, 'compat'))) {
-      if (name.endsWith('.cjs')) await cp(path.join(packageRoot, 'compat', name), path.join(stage, 'compat', name));
-    }
     await prepareImageResponse(stage);
     manifest.config.serverActions = config.experimental.serverActions;
     if (config.workerRetirement) manifest.config.workerRetirement = config.workerRetirement;
+    if(config.workerPreload&&!dev)manifest.config.workerPreload=config.workerPreload;
     const cacheHandlers = await prepareCacheHandlers({ config, projectRoot: project.root, stage, environment });
     if (Object.keys(cacheHandlers).length) manifest.config.cacheHandlers = cacheHandlers;
     const cacheHandler = await prepareCacheHandler({ config, projectRoot: project.root, stage, environment });
@@ -270,7 +245,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     }
     const common = { absWorkingDir: project.root, bundle: true, logLevel: 'silent', jsx: 'automatic', loader: assetLoaders, assetNames: '[name]-[hash]', publicPath: publicPaths.assetBase, metafile: true, define: { 'process.env.NODE_ENV': JSON.stringify(dev ? 'development' : 'production'), ...environment } };
     if (Object.keys(serverEntries).length) {
-      const server = await bundle({ ...common, entryPoints: serverEntries, outdir: path.join(stage, 'server'), outExtension: { '.js': '.mjs' }, platform: 'node', format: 'esm', splitting: true, chunkNames: 'chunk-[hash]', banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" }, target: 'node22', sourcemap: dev, plugins: [moduleResolutionPlugin(config.turbopack, project.root), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: false, pageFiles, projectRoot: project.root, documentFile: project.document, fonts }), npmPackagesPlugin({ pages: true, projectRoot: project.root, transpilePackages: config.transpilePackages, serverExternalPackages: config.serverExternalPackages }), cssModules.plugin(false)] });
+      const server = await bundle({ ...common, entryPoints: serverEntries, outdir: path.join(stage, 'server'), outExtension: { '.js': '.mjs' }, platform: 'node', format: 'esm', splitting: true, chunkNames: 'chunk-[hash]', banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" }, target: 'node22', sourcemap: dev, plugins: [moduleResolutionPlugin(config.turbopack, project.root), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: false, pageFiles, projectRoot: project.root, documentFile: project.document, fonts, locations }), npmPackagesPlugin({ pages: true, projectRoot: project.root, transpilePackages: config.transpilePackages, serverExternalPackages: config.serverExternalPackages }), cssModules.plugin(false)] });
       fonts.record(server.metafile);
       const serverChunks = new Set(Object.keys(server.metafile.outputs).filter(file => file.endsWith('.mjs')).map(file => path.basename(file)));
       for (const [output, metadata] of Object.entries(server.metafile.outputs)) {
@@ -285,7 +260,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
       }
     }
     if (Object.keys(clientEntries).length) {
-      const browser = await bundle({ ...common, entryPoints: clientEntries, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', chunkNames: 'chunk-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], splitting: true, minify: !dev, sourcemap: dev || config.productionBrowserSourceMaps, define: { 'process.env': '{}', ...common.define }, plugins: [moduleResolutionPlugin(config.turbopack, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: true, pageFiles, projectRoot: project.root, documentFile: project.document, fonts, refresh }), cssModules.plugin(true)] });
+      const browser = await bundle({ ...common, entryPoints: clientEntries, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', chunkNames: 'chunk-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], splitting: true, minify: !dev, sourcemap: dev || config.productionBrowserSourceMaps, define: { 'process.env': '{}', ...common.define }, plugins: [moduleResolutionPlugin(config.turbopack, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: true, pageFiles, projectRoot: project.root, documentFile: project.document, fonts, refresh, locations }), cssModules.plugin(true)] });
       fonts.record(browser.metafile);
       const byEntry = new Map(Object.entries(clientEntries).map(([id, file]) => [path.resolve(file), id]));
       for (const [output, metadata] of Object.entries(browser.metafile.outputs)) {
@@ -303,14 +278,21 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     if (manifest.middleware) manifest.middleware.bodySizeLimit = config.experimental.proxyClientMaxBodySize;
     await prepareMetadataRoutes(project, stage);
     await compileApp({ project, stage, manifest, moduleResolution: config.turbopack, cssModules, fonts, images, dev, defineEnvironment: environment, productionBrowserSourceMaps: config.productionBrowserSourceMaps, serverExternalPackages: config.serverExternalPackages });
+    if(manifest.config.workerPreload)for(const pattern of config.workerPreload.routes){
+      const selected=manifest.routes.find(route=>!route.internal&&route.pattern===pattern);
+      if(!selected||selected.cacheConfig?.runtime==='edge'||selected.handlerConfig?.runtime==='edge')throw new Error(`workerPreload route ${pattern} must be an existing Node route.`);
+    }
     await checkTypeScript(project.root, config, { dev, tsconfig });
     fonts.attach(manifest);
     expandLocales(manifest);
     // All runtime preparation must finish before its shared modules are built;
     // no staged renderer has been imported before this production-only point.
-    if (!dev) await bundleRuntime(stage);
-    await prerender(stage, manifest, dev);
-    await prerenderApp(stage, manifest, dev);
+    if (!dev) await bundleRuntime(stage,{projectRoot:project.root});
+    // Node caches CJS React by filename, not NODE_ENV. Once development metadata
+    // imports load it, subsequent production renders need a clean process too.
+    if(dev) developmentModulesLoaded = true;
+    if(!dev && (incremental || developmentModulesLoaded)) Object.assign(manifest,await isolatedPrerender(project.root,stage,manifest));
+    else {await prerender(stage, manifest, dev);await prerenderApp(stage, manifest, dev);}
     const pages = manifest.routes.filter(route => route.kind === 'page' && route.router !== 'app' && !route.internal);
     const publicPage = route => ({ ...(route.locale ? {locale:route.locale,originalPattern:route.originalPattern} : {}), id: route.id, pattern: route.pattern, client: route.client, css: route.css, ...(route.fonts ? { fonts: route.fonts } : {}), ssg: !!route.ssg, ssp: !!route.ssp, gip: !!route.gip, appGip: !!route.appGip });
     if (pages.length || manifest.pagesErrors) {
@@ -332,6 +314,16 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     }
     await rm(path.join(stage, '.entries'), { recursive: true });
     if (dev) {
+      manifest.devStyles={bundles:devStylePlans(),dependencies:devStyleDependencies(),modules:await cssModules.mappings()};
+      for(const [,files]of manifest.devStyles.dependencies)for(const module of manifest.devStyles.modules)if(files.includes(module.file))for(const file of module.watchFiles)if(!files.includes(file))files.push(file);
+      manifest.devDependencies=devDependencies(project,manifest);
+      manifest.devModules=devModules(project.root);
+      manifest.devDependencyStatus={complete:!manifest.devDependencies.incomplete&&!manifest.devModules.incomplete,reason:manifest.devDependencies.incomplete||manifest.devModules.incomplete};
+      for(const route of manifest.devDependencies)for(const module of manifest.devStyles.modules){
+        if(route.files.includes(path.relative(project.root,module.file).replaceAll(path.sep,'/')))for(const file of module.watchFiles){
+          const relative=path.relative(project.root,file).replaceAll(path.sep,'/');if(!relative.startsWith('../')&&!route.files.includes(relative))route.files.push(relative);
+        }
+      }
       const appRoute = manifest.routes.find(route => route.router === 'app' && route.kind === 'page' && route.client);
       await writeFile(path.join(stage, 'assets', path.basename(manifest.devClient)), JSON.stringify({ buildId,
         pages: manifest.routes.filter(route => route.router !== 'app' && route.client).map(publicPage),
@@ -341,7 +333,10 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     await writeRuntimeContract(stage);
     await writeFile(path.join(stage, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
     await writeBuildOutput(stage, manifest);
-    if (config.compress) await precompressBuild(stage, manifest, {cacheDirectory:path.join(project.root,'.prnext-cache/precompress-v1')});
+    // Offline compression is a deployment optimization. Recompressing source
+    // maps and every entry after a save stalls Fast Refresh for no local benefit.
+    if (!dev && config.compress) await precompressBuild(stage, manifest, {cacheDirectory:path.join(project.root,'.prnext-cache/precompress-v1')});
+    if(!dev)await writeBuildAnalysis({root:project.root,stage,destination,manifest,records:buildAnalysisRecords(),routeInputs:buildAnalysisRoutes(),precompressed:config.compress});
     if (config.output === 'standalone' && !dev) await (await import('./standalone-runner.mjs')).prepareStandalone({ projectRoot: project.root, stage, manifest, config });
     const exporting = config.output === 'export' && !dev ? await import('./static-export.mjs') : null;
     const exportSource = exporting && await exporting.prepareStaticExport({ project, stage, manifest, config });

package/build/inspect.mjs

@@ -69,6 +69,7 @@ export async function inspectProject(directory) {
     sample: { events: recent.length, from: recent[0]?.time, to: recent.at(-1)?.time },
     notes: ['Enable measurements with prn start --inspect (or prn dev --inspect), visit routes, then run prn inspect again.',
       'HTTP and fetch durations end when response headers are ready. Samples are bounded and can span server sessions; they are not full-response benchmarks.',
+      'Request-stage samples additionally separate admission, worker first byte, response headers and complete body consumption, with completion/cancellation/deadline outcomes. Stages overlap; do not add their durations. Body completion means the HTTP layer consumed the application body, not remote delivery.',
       'Fetch destinations omit queries and credentials. Runtime cache tags/paths are hashed; matching identifiers link reads to invalidations. No diagnostic HTTP endpoint is exposed.'] };
 }
 export function printInspection(report) {
@@ -76,6 +77,8 @@ export function printInspection(report) {
   console.log(`Recorded sample: ${report.summary.requests} HTTP requests; p50 ${report.summary.p50Ms ?? 'n/a'} ms; p95 ${report.summary.p95Ms ?? 'n/a'} ms (response headers); ${report.summary.errors} server errors.`);
   if(report.summary.wakeP95Ms !== null) console.log(`Worker startup p95: ${report.summary.wakeP95Ms} ms.`);
   if(report.summary.workerRssBytes !== null) console.log(`Latest recorded worker RSS: ${(report.summary.workerRssBytes/1048576).toFixed(1)} MiB. Native server memory is not included.`);
+  for(const stage of report.requestStages||[]) console.log(`STAGE ${stage.stage}: ${stage.samples} sample(s), p95 ${stage.p95Ms ?? 'n/a'} ms; ${stage.completed} completed, ${stage.failed} failed, ${stage.cancelled} cancelled, ${stage.timedOut} timed out.`);
+  for(const budget of report.budgets||[])console.log(`BUDGET ${budget.budget}: ${budget.used ?? 'n/a'}/${budget.limit ?? 'n/a'} ${budget.unit}, ${budget.waiting ?? 'n/a'} waiting; ${budget.rejected ?? 'n/a'} rejected, ${budget.timedOut ?? 'n/a'} timed out, ${budget.cancelledWaits ?? 'n/a'} cancelled waits.`);
   for(const finding of report.findings)console.log(`${finding.level.toUpperCase()}: ${finding.message} ${finding.action}`);
   for (const route of report.routes) console.log(`${route.mode.padEnd(13)} ${route.pattern}\n  ${route.reasons.join('; ') || `${route.prerenderedPaths} prerendered path(s); revalidate: ${route.revalidate.join(', ') || 'on demand'}`}`);
   for (const item of report.measurements) console.log(`${item.type.toUpperCase()} ${item.route}${item.destination ? ' -> ' + item.destination : ''}: ${item.count} sample(s)${item.state ? ', ' + item.state : ''}${item.reason ? ' (' + item.reason + ')' : ''}${item.p95Ms !== undefined ? ', p95 ' + item.p95Ms.toFixed(2) + ' ms' : ''}, ${item.errors} error(s)`);

package/build/inspection-summary.mjs

@@ -1,22 +1,46 @@
 const quantile = (values, q) => values.length ? Math.round([...values].sort((a,b)=>a-b)[Math.ceil(values.length*q)-1]*100)/100 : null;
 const durations = events => events.map(e=>e.durationMs).filter(v=>Number.isFinite(v)&&v>=0);
+const stages=['admission','renderStart','bodyAdmission','bodyRead','workerQueue','workerFirstByte','workerHeaders','httpHeaders','responseBody','requestTotal'];
+const outcomes=['completed','failed','cancelled','timedOut'];
+const budgetNames=['renderLive','apiLive','renderStart','inputBytes','responseBytes'];
+const validTime=value=>Number.isSafeInteger(value)&&value>=0&&value<=18446744073709;
+function summarizeStages(events) {
+  return stages.flatMap(stage=>{
+    const sample=events.filter(event=>event.stage===stage), times=durations(sample);
+    return sample.length?[{stage,samples:sample.length,p50Ms:quantile(times,.5),p95Ms:quantile(times,.95),...Object.fromEntries(outcomes.map(outcome=>[outcome,sample.filter(event=>event.outcome===outcome).length]))}]:[];
+  });
+}
+function currentBudgets(snapshot) {
+  if(!Array.isArray(snapshot?.workers?.budgets))return null;
+  return budgetNames.flatMap(budget=>{
+    const value=snapshot.workers.budgets.find(value=>value?.budget===budget);
+    if(!value)return [];
+    const row={budget,unit:budget.endsWith('Bytes')?'bytes':'requests'};
+    for(const key of ['limit','used','peakUsed','waiting','peakWaiting','acquired','rejected','timedOut','cancelledWaits'])row[key]=Number.isSafeInteger(value[key])&&value[key]>=0?value[key]:null;
+    return [row];
+  });
+}
 export function summarizeDiagnostics(events, snapshots = []) {
   const http=events.filter(e=>e.type==='http'), times=durations(http);
   const wake=durations(events.filter(e=>e.type==='wake'&&e.phase==='node-ready'));
   const processes=new Map();
   for(const event of events)if(event.type==='process'&&Number.isSafeInteger(event.pid)&&Number.isFinite(event.rssBytes)&&event.rssBytes>=0)processes.set(event.pid,event);
-  const last=snapshots.sort((a,b)=>b.unixMs-a.unixMs)[0];
+  const last=[...snapshots].sort((a,b)=>b.unixMs-a.unixMs)[0];
   const current=last&&Date.now()-last.unixMs<30000&&Date.now()>=last.unixMs;
   const rss=[...processes.values()].filter(e=>Date.now()-e.time<30000&&Date.now()>=e.time);
+  const stageSample=events.filter(e=>e.type==='requestStage'&&stages.includes(e.stage)&&outcomes.includes(e.outcome)&&Number.isFinite(e.durationMs)&&e.durationMs>=0&&e.durationMs<=86400000&&validTime(e.time)).map(({stage,outcome,durationMs,time})=>({stage,outcome,durationMs,time}));
+  const requestStages=summarizeStages(stageSample), totals=requestStages.find(s=>s.stage==='requestTotal');
   const summary={requests:http.length,errors:http.filter(e=>e.status>=500).length,p50Ms:quantile(times,.5),p95Ms:quantile(times,.95),wakeP95Ms:quantile(wake,.95),workerRssBytes:rss.length?rss.reduce((n,e)=>n+e.rssBytes,0):null,
-    queuedJobs:current?last.workers.queuedJobs??null:null,activeJobs:current?last.workers.activeJobs??null:null, runtimeSampleAt:last?.unixMs??null};
+    queuedJobs:current?last.workers?.queuedJobs??null:null,activeJobs:current?last.workers?.activeJobs??null:null, runtimeSampleAt:last?.unixMs??null,
+    completedResponseP95Ms:quantile(durations(stageSample.filter(e=>e.stage==='requestTotal'&&e.outcome==='completed')),.95),cancelledResponses:totals?.cancelled??null,timedOutResponses:totals?.timedOut??null};
   const findings=[];
   if(!http.length)findings.push({level:'info',code:'NO_SAMPLE',message:'No HTTP sample recorded.',action:'Start with --inspect, visit the site and run inspect again.'});
   if(summary.queuedJobs>0)findings.push({level:'warning',code:'WORKER_QUEUE',message:`${summary.queuedJobs} jobs are waiting for a worker.`,action:'Check slow routes and available CPU/RAM before increasing concurrency.'});
   if(summary.p95Ms>=1000)findings.push({level:'warning',code:'SLOW_HEADERS',message:'The slowest 5% of recorded responses take at least one second to prepare headers.',action:'Inspect route and fetch timings below; this includes queueing and startup.'});
   if(summary.errors)findings.push({level:'warning',code:'SERVER_ERRORS',message:`${summary.errors} recorded requests returned a server error.`,action:'Check application logs for the same sample period.'});
   if(summary.wakeP95Ms>=1000)findings.push({level:'info',code:'SLOW_WAKE',message:'Recorded worker startup p95 exceeds one second.',action:'Review startup imports or use keep-warm if the extra memory is acceptable.'});
-  return {summary,findings,metricSample:http.filter(e=>Number.isFinite(e.durationMs)&&e.durationMs>=0&&e.durationMs<=86400000&&Number.isSafeInteger(e.time)&&e.time>=0&&e.time<=18446744073709).map(e=>({route:typeof e.route==='string'?e.route.slice(0,256):'<unmatched>',method:/^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS|CONNECT|TRACE)$/.test(e.method)?e.method:'_OTHER',durationMs:e.durationMs,time:e.time}))};
+  if(summary.timedOutResponses>0)findings.push({level:'warning',code:'RESPONSE_DEADLINES',message:`${summary.timedOutResponses} recorded HTTP responses reached their request deadline.`,action:'Compare admission, worker and body timings before increasing the configured timeout.'});
+  return {summary,findings,requestStages,budgets:current?currentBudgets(last):null,stageSample,metricSample:http.filter(e=>Number.isFinite(e.durationMs)&&e.durationMs>=0&&e.durationMs<=86400000&&validTime(e.time)).map(e=>({route:typeof e.route==='string'?e.route.slice(0,256):'<unmatched>',method:/^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS|CONNECT|TRACE)$/.test(e.method)?e.method:'_OTHER',durationMs:e.durationMs,time:e.time}))};
 }
 
 /** OTLP/JSON Metrics export of a bounded local sample, never a complete traffic counter. */
@@ -33,5 +57,14 @@ export function inspectionMetrics(report) {
     return {attributes:[{key:'http.route',value:{stringValue:group.route}},{key:'http.request.method',value:{stringValue:group.method}}],
       startTimeUnixNano:String(BigInt(Math.trunc(group.start))*1000000n),timeUnixNano:String(BigInt(Math.trunc(group.end))*1000000n),count:String(group.values.length),sum:group.values.reduce((a,b)=>a+b,0),min:Math.min(...group.values),max:Math.max(...group.values),explicitBounds:bounds,bucketCounts:buckets.map(String)};
   });
-  return {resourceMetrics:[{resource:{attributes:[{key:'service.name',value:{stringValue:'prnext'}},{key:'prnext.inspect.sampled',value:{boolValue:true}}]},scopeMetrics:[{scope:{name:'prnext.inspect',version:'1'},metrics:[{name:'prnext.http.response.headers.duration',description:'Bounded diagnostic sample of time until response headers; excludes response body streaming.',unit:'s',histogram:{aggregationTemporality:1,dataPoints}}]}]}]};
+  const stageGroups=new Map();
+  for(const event of report.stageSample||[]) {
+    if(!stages.includes(event.stage)||!outcomes.includes(event.outcome)||!Number.isFinite(event.durationMs)||event.durationMs<0||event.durationMs>86400000||!validTime(event.time))continue;
+    const key=JSON.stringify([event.stage,event.outcome]);
+    if(!stageGroups.has(key))stageGroups.set(key,{stage:event.stage,outcome:event.outcome,count:0,sum:0,min:Infinity,max:0,start:event.time,end:event.time,buckets:Array(bounds.length+1).fill(0)});
+    const group=stageGroups.get(key),value=event.durationMs/1000,index=bounds.findIndex(bound=>value<=bound);
+    group.count++;group.sum+=value;group.min=Math.min(group.min,value);group.max=Math.max(group.max,value);group.start=Math.min(group.start,event.time);group.end=Math.max(group.end,event.time);group.buckets[index<0?bounds.length:index]++;
+  }
+  const stagePoints=[...stageGroups.values()].map(g=>({attributes:[{key:'prnext.request.stage',value:{stringValue:g.stage}},{key:'prnext.request.outcome',value:{stringValue:g.outcome}}],startTimeUnixNano:String(BigInt(g.start)*1000000n),timeUnixNano:String(BigInt(g.end)*1000000n),count:String(g.count),sum:g.sum,min:g.min,max:g.max,explicitBounds:bounds,bucketCounts:g.buckets.map(String)}));
+  return {resourceMetrics:[{resource:{attributes:[{key:'service.name',value:{stringValue:'prnext'}},{key:'prnext.inspect.sampled',value:{boolValue:true}}]},scopeMetrics:[{scope:{name:'prnext.inspect',version:'1'},metrics:[{name:'prnext.http.response.headers.duration',description:'Bounded diagnostic sample of time until response headers; excludes response body streaming.',unit:'s',histogram:{aggregationTemporality:1,dataPoints}},{name:'prnext.request.stage.duration',description:'Bounded diagnostic sample of request stages and terminal outcomes; stages overlap and must not be added together.',unit:'s',histogram:{aggregationTemporality:1,dataPoints:stagePoints}}]}]}]};
 }