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

package/build/index.mjs

@@ -1,11 +1,20 @@
+import {compileInstrumentation} from './instrumentation.mjs';
+import {prerenderPages as prerender} from './prerender-pages.mjs';
+import {isolatedPrerender,prerenderProduction} 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,compilationGraphCacheReport } from './compiler.mjs';
+import {retainDeploymentAssets} from './deployment-assets.mjs';
+import {selectHtmlOnlyRoutes} from './html-only-config.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, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
@@ -30,28 +39,52 @@ 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';
+import {createReactCompilerTransform} from './react-compiler.mjs';
+import {writeReactCompilerReport,reactCompilerReport} from './react-compiler-report.mjs';
 export { staticPath } from '../runtime/pages-paths.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const compatibleModules = new Set(['link', 'head', 'router', 'compat/router', 'next-router-context', 'next-app-router-context', 'image', 'cache', 'dynamic', 'error', 'document', 'app', 'script', 'og']);
-const extensions = { '.js': 'jsx', '.jsx': 'jsx', '.mjs': 'jsx', '.cjs': 'jsx', '.ts': 'ts', '.tsx': 'tsx' };
+const compatibleModules = new Set(['link', 'head', 'router', 'compat/router', 'next-router-context', 'next-app-router-context', 'image', 'cache', 'dynamic', 'error', 'document', 'app', 'script', 'og', 'offline', 'redis-cache']);
+const extensions = { '.js': 'jsx', '.jsx': 'jsx', '.mjs': 'jsx', '.cjs': 'jsx', '.ts': 'ts', '.tsx': 'tsx', '.mts': 'ts', '.cts': 'ts' };
 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,{development=true}={}) {
+  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' || development&&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, serverOnlyFiles, fonts, refresh, locations, reactCompiler }) {
   return {
     name: 'prnext-pages-compatibility',
     setup(esbuild) {
+      applicationEntry(esbuild,readCompilerFile,{transformTypedHelpers:browser && !!reactCompiler});
       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 => {
         const name = frameworkImportName(args.path);
         if (!compatibleModules.has(name)) return { errors: [{ text: `PRNext does not implement ${args.path} yet (imported by ${args.importer}). Supported runtime imports: next/link, next/head, next/router, next/image, next/cache, next/dynamic, next/error, next/document, next/app, next/script.` }] };
         if (browser && name === 'document') return { errors: [{ text: `${args.path} is server-only. Import Document, Html, Head, Main and NextScript from pages/_document, not from a browser page or component.` }] };
-        if (browser && ['cache', 'og'].includes(name)) return { errors: [{ text: `${args.path} is server-only and cannot be imported by a browser component.` }] };
+        if (browser && ['cache', 'og', 'redis-cache'].includes(name)) return { errors: [{ text: `${args.path} is server-only and cannot be imported by a browser component.` }] };
         const file = name === 'compat/router' ? 'compat-router' : name;
         return browser ? { path: path.join(packageRoot, 'compat', file + '.cjs') } : { path: `../compat/${file}.cjs`, external: true };
       });
@@ -67,9 +100,15 @@ function compatibilityPlugin({ browser, pageFiles, projectRoot, documentFile, fo
         });
         esbuild.onLoad({ filter: /.*/, namespace: 'prnext-empty' }, () => ({ contents: '', loader: 'js' }));
       }
-      esbuild.onLoad({ filter: /\.(?:[cm]?js|jsx|tsx?)$/, namespace: 'file' }, async args => {
+      esbuild.onLoad({ filter: /\.(?:[cm]?[jt]s|[jt]sx)$/, 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);
+        // Pages shares a server graph with API handlers, Document and data
+        // loaders. Keep that entire graph original: an uppercase JSX utility
+        // may be called normally there, outside a React render. Browser render
+        // graphs receive memoization before instrumentation and JSX lowering.
+        const compiled=browser && reactCompiler && args.path!==documentFile && !serverOnlyFiles.has(args.path) ? await reactCompiler(original,args.path,{loaderOutput:args.prnextSource!==undefined}) : original;
+        const source = await fonts.transform(locations?await locations(compiled,args.path):compiled, 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 +149,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 +184,25 @@ 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,deferredRoutes=[];
+  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);
+    deferredRoutes=discovery.routes.filter(route=>!devRoutes.includes(route.pattern)&&!route.internal&&!route.errorStatus);
+    project.routes=project.routes.filter(route=>devRoutes.includes(route.pattern)||route.internal||route.errorStatus);
+  } else project=await scanProject(projectRoot,scanOptions);
+  if(!dev&&config.htmlOnly.length)selectHtmlOnlyRoutes(project.routes,config.htmlOnly,config);
+  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 +210,35 @@ 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'),
-    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: [],
+    ...(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, partialPrefetching: config.partialPrefetching, navigationCache: config.navigationCache, cacheLife: config.cacheLife, htmlOnly:config.htmlOnly, 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.
+  if(!dev)manifest.config.deploymentId=manifest.cacheId;
   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 reactCompiler = config.reactCompiler ? createReactCompilerTransform(project.root, config.reactCompiler, {dev}) : undefined;
+  const serverOnlyFiles = new Set();
+  if (reactCompiler) for (const file of [...project.routes.filter(route=>route.kind==='api').map(route=>route.file),...(project.document?[project.document]:[])]) {
+    serverOnlyFiles.add(file);serverOnlyFiles.add(await realpath(file));
+  }
   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,dev,config });
   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,{development:dev});
     // 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.workerMemory && !dev)manifest.config.workerMemory=config.workerMemory;
     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 });
@@ -261,7 +255,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
       serverEntries[route.id] = serverEntry;
       if (route.kind === 'page') {
         const clientEntry = path.join(stage, '.entries', route.id + '.client.jsx');
-        await writeFile(clientEntry, browserEntry(route, project.app, pagesManifestUrl, { ...publicPaths, strictMode: config.reactStrictMode === true }, development));
+        await writeFile(clientEntry, browserEntry(route, project.app, pagesManifestUrl, { ...publicPaths, deploymentId:dev?undefined:manifest.cacheId, strictMode: config.reactStrictMode === true }, development));
         clientEntries[route.id] = clientEntry;
       }
       manifest.routes.push({ id: route.id, pattern: route.pattern, kind: route.kind, module: `server/${route.id}.mjs`, css: [],
@@ -270,7 +264,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, serverOnlyFiles, fonts, locations, reactCompiler }), 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 +279,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, serverOnlyFiles, fonts, refresh, locations, reactCompiler }), 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)) {
@@ -302,20 +296,35 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     await compileMiddleware({ project, stage, manifest, dev, moduleResolution: config.turbopack, defineEnvironment: environment });
     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 });
+    await compileApp({ project, stage, manifest, reactCompiler: config.reactCompiler, 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 compileInstrumentation({root:project.root,stage,manifest,config,dev,environment});
+    if(deferredRoutes.length){
+      for(const route of deferredRoutes){
+        const module=`server/dev-deferred-${route.id}.mjs`;await writeFile(path.join(stage,module),'export {};\n');
+        manifest.routes.push({id:route.id,pattern:route.pattern,kind:route.kind,router:route.router,module,devDeferred:true,css:[],cacheConfig:{maxDuration:120}});
+      }
+    }
     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);
-    const pages = manifest.routes.filter(route => route.kind === 'page' && route.router !== 'app' && !route.internal);
+    if (!dev) await bundleRuntime(stage,{projectRoot:project.root,sourceDirectory:path.join(packageRoot,'runtime')});
+    // 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) Object.assign(manifest,await (incremental || developmentModulesLoaded ? isolatedPrerender : prerenderProduction)(project.root,stage,manifest,{prerender:config.prerender}));
+    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 && !route.devDeferred);
     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) {
       const publicPages = {
         buildId: manifest.buildId,
+        ...(manifest.config.deploymentId?{deploymentId:manifest.config.deploymentId}:{}),
         ...publicPaths,
         // Header rules cannot select a different page. Other server routing
         // stays authoritative, including middleware with conditional behavior.
@@ -332,16 +341,35 @@ 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),
-        ...(appRoute ? { app: { client: appRoute.client, css: appRoute.css } } : {}),
+        ...(appRoute ? { app: { client: appRoute.client, css: appRoute.css, routes: manifest.routes.filter(route=>route.router==='app'&&route.kind==='page'&&route.client).map(({id,pattern,css,cssScopes})=>({id,pattern,css,cssScopes:cssScopes||[]})) } } : {}),
       }));
     }
-    await writeRuntimeContract(stage);
+    // A report belongs to this successful staging generation, never to the
+    // runtime manifest or public assets. Publishing the stage is atomic below.
+    if(!dev)await retainDeploymentAssets({stage,destination,manifest,policy:config.deploymentRetention});
+    const compilationCache=compilationGraphCacheReport();
+    if(!dev)await writeFile(path.join(stage,'compilation-cache-report.json'),JSON.stringify(compilationCache,null,2)+'\n');
+    const compilerReport=await writeReactCompilerReport(stage,reactCompilerReport());
+    await writeRuntimeContract(stage,{deployment:!dev,htmlOnly:!dev&&manifest.routes.some(route=>route.htmlOnly),workerMemory:Boolean(manifest.config.workerMemory),incrementalCache:Boolean(manifest.config.cacheHandler)});
     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 });
@@ -365,7 +393,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     } finally { await rm(pointerTemporary, {force:true}); }
     await exported?.commit();
     if (hadDestination) await rm(backup, { recursive: true, force: true });
-    return { ...manifest, outputDirectory: destination, durationMs: Math.round(performance.now() - started) };
+    return { ...manifest, outputDirectory: destination, durationMs: Math.round(performance.now() - started),reactCompilerReport:compilerReport,compilationCache };
   } catch (error) {
     await rm(stage, { recursive: true, force: true });
     if (error.errors) error.message = error.errors.map(item => `${item.location ? `${item.location.file}:${item.location.line}: ` : ''}${item.text}`).join('\n');

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

package/build/instrumentation.mjs

@@ -0,0 +1,30 @@
+import {access,writeFile,mkdir} from 'node:fs/promises';
+import path from 'node:path';
+import {build} from './compiler.mjs';
+import {compileEdge} from './edge.mjs';
+import {moduleResolutionPlugin} from './module-resolution.mjs';
+
+export async function compileInstrumentation({root,stage,manifest,config,dev,environment}) {
+  const found=[];
+  for(const directory of ['', 'src'])for(const extension of ['ts','js','mjs','cjs']){
+    const file=path.join(root,directory,'instrumentation.'+extension);
+    try{await access(file);found.push(file);}catch(error){if(error.code!=='ENOENT')throw error;}
+  }
+  if(!found.length)return;
+  if(found.length>1)throw Error('Only one instrumentation file is allowed, in the project root or src directory.');
+  const file=found[0],entry=path.join(stage,'.entries/instrumentation.mjs');manifest.instrumentation={};
+  await mkdir(path.dirname(entry),{recursive:true});
+  await writeFile(entry,`import * as hooks from ${JSON.stringify(file)};export const register=hooks.register??hooks.default?.register;export const onRequestError=hooks.onRequestError??hooks.default?.onRequestError;`);
+  for(const runtime of ['node','rsc']){
+    const module=`server/instrumentation-${runtime}.mjs`;
+    await build({absWorkingDir:root,entryPoints:[entry],outfile:path.join(stage,module),bundle:true,packages:'external',platform:'node',format:'esm',target:'node22',banner:{js:"import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);"},conditions:runtime==='rsc'?['react-server']:[],sourcemap:dev,logLevel:'silent',
+      define:{...environment,'process.env.NODE_ENV':JSON.stringify(dev?'development':'production'),'process.env.NEXT_RUNTIME':'"nodejs"'},
+      plugins:[moduleResolutionPlugin(config.turbopack,root)]});
+    manifest.instrumentation[runtime]=module;
+  }
+  if(manifest.middleware?.runtime==='edge'||manifest.routes.some(route=>route.cacheConfig?.runtime==='edge'||route.handlerConfig?.runtime==='edge')){
+    const module='server/instrumentation-edge.mjs';
+    await compileEdge({file:entry,outfile:path.join(stage,module),projectRoot:root,dev,defineEnvironment:environment});
+    manifest.instrumentation.edge=module;
+  }
+}