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

package/build/check.mjs

@@ -7,34 +7,79 @@ import { scanProject } from './scan.mjs';
 import { compileCustomRoutes } from './custom-routes.mjs';
 import { validateReactVersions } from './app.mjs';
 import { snapshotEnvConfig } from '../runtime/env.mjs';
+import { environmentDiagnostics } from '../native/diagnostics.mjs';
+import { packageManifest } from '../native/resolve.mjs';
+import { projectTsconfig } from './typescript.mjs';
 
 /** Preflight an existing project without rewriting sources, dependencies or build output. */
-export async function checkProject(directory, { dev = false, validateDependencies = true } = {}) {
+export async function checkProject(directory, { dev = false, validateDependencies = true, validateEnvironment = validateDependencies } = {}, services = {}) {
   const root = path.resolve(directory);
-  const report = { root, ok: false, routes: [], versions: {}, errors: [], notes: [
+  const report = { root, ok: false, routes: [], versions: {}, errors: [], diagnostics: [], notes: [
     'Preflight validates configuration, route conventions and installed React versions. A successful production build and browser tests are still required.',
     'Webpack plugin hooks are validated during compilation; preflight only validates plugin shape and translated configuration.',
     'Rust handles HTTP, routing, static files, images and persistent caches. React and npm JavaScript execute on Node/V8.',
   ] };
+  const diagnostic = (id, error, action) => {
+    const item = { id, severity: 'error', message: error.message, action };
+    report.diagnostics.push(item);
+    report.errors.push(item.message);
+  };
   const restore = snapshotEnvConfig();
   try {
-    const config = await loadProjectConfig(root, {dev});
-    if (config.onDemandEntries) report.notes.push('onDemandEntries is accepted for Next plugin compatibility. PRNext compiles all development routes and does not use Next\'s in-memory page eviction queue; these retention settings do not change its memory limits.');
-    await compileCustomRoutes(config);
-    const project = await scanProject(root, {basePath:config.basePath,pageExtensions:config.pageExtensions,i18n:config.i18n});
-    await validateCompilerConfig(config,root,{dev,edge:project.middleware?.runtime==='edge'||project.routes.some(route=>route.cacheConfig?.runtime==='edge'||route.handlerConfig?.runtime==='edge')});
+    let config, project;
+    try { config = await loadProjectConfig(root, {dev}); }
+    catch (error) { diagnostic('config', error, 'Correct the project configuration and run check again.'); }
+    if (config) {
+    if (config.onDemandEntries) report.notes.push('Development compiles requested routes and retains open browser routes. onDemandEntries controls inactive route retention; middleware, rewrites and parallel/intercepting routing use the complete graph.');
+    try { await compileCustomRoutes(config); }
+    catch (error) { diagnostic('custom-routes', error, 'Correct redirects, headers or rewrites in the configuration.'); }
+    try { project = await scanProject(root, {basePath:config.basePath,pageExtensions:config.pageExtensions,i18n:config.i18n}); }
+    catch (error) { diagnostic('routes', error, 'Correct the conflicting route files or route conventions.'); }
+    try { await validateCompilerConfig(config,root,{dev,edge:project?.middleware?.runtime==='edge'||project?.routes.some(route=>route.cacheConfig?.runtime==='edge'||route.handlerConfig?.runtime==='edge')}); }
+    catch (error) { diagnostic('compiler', error, 'Correct the compiler options or install the required compiler plugins.'); }
+    try {
+      const tsconfig = await projectTsconfig(root, config);
+      if (tsconfig) {
+        let ts;
+        try { ts = createRequire(path.join(root, 'package.json'))('typescript'); }
+        catch {
+          const required = config.typedRoutes || config.typescript && !config.typescript.ignoreBuildErrors;
+          const item = { id: 'typescript', severity: required ? 'error' : 'warning', message: 'TypeScript configuration exists, but TypeScript is not installed in the application.', action: 'Install typescript as an application dev dependency.' };
+          report.diagnostics.push(item); if (required) report.errors.push(item.message);
+        }
+        if (ts) {
+          const parsed = ts.getParsedCommandLineOfConfigFile(tsconfig, { noEmit: true }, { ...ts.sys, onUnRecoverableConfigFileDiagnostic: value => { throw new Error(ts.flattenDiagnosticMessageText(value.messageText, '\n')); } });
+          if (!parsed || parsed.errors.length) throw new Error(parsed ? ts.formatDiagnostics(parsed.errors, { getCanonicalFileName: name => name, getCurrentDirectory: () => root, getNewLine: () => '\n' }) : 'TypeScript configuration could not be parsed.');
+          report.versions.typescript = ts.version;
+          report.diagnostics.push({ id: 'typescript', severity: 'info', message: `TypeScript ${ts.version} configuration is valid. Semantic errors require prnext typecheck.` });
+        }
+      } else if (config.typedRoutes || config.typescript && !config.typescript.ignoreBuildErrors) throw new Error('TypeScript is enabled, but tsconfig.json does not exist.');
+    } catch (error) { diagnostic('typescript', error, 'Correct typescript.tsconfigPath or the selected TypeScript configuration.'); }
+    }
+    if (project) {
     report.routes = project.routes.filter(route=>!route.internal).map(({pattern,kind,router})=>({pattern,kind,router:router||'pages'}));
+    }
     const resolve = createRequire(path.join(root,'package.json'));
     for (const name of ['next','react','react-dom','react-server-dom-webpack']) {
       try { report.versions[name] = JSON.parse(await readFile(resolve.resolve(`${name}/package.json`),'utf8')).version; }
       catch { report.versions[name] = null; }
     }
     if (validateDependencies) {
-      if (project.routes.some(route=>route.router==='app')) await validateReactVersions(resolve);
-      else if (!report.versions.react || !report.versions['react-dom']) throw new Error('Install react and react-dom in the project before building Pages routes.');
+      try {
+        if (project?.routes.some(route=>route.router==='app')) await validateReactVersions(resolve);
+        else {
+          const names = ['react', 'react-dom'];
+          if (names.some(name => report.versions[name] !== packageManifest.peerDependencies[name])) throw new Error(`Pages routes require the declared React peer versions. Resolved ${names.map(name => `${name}@${report.versions[name] || 'missing'}`).join(', ')}. Install ${names.map(name => `${name}@${packageManifest.peerDependencies[name]}`).join(' ')} in the application.`);
+        }
+      } catch (error) { diagnostic('react', error, 'Install the matching React protocol packages shown in this error.'); }
     } else report.notes.push('Installed React versions have not been validated yet; migration checks them after dependency installation.');
-    report.ok = true;
-  } catch (error) { report.errors.push(error.message); }
+    if (validateEnvironment) {
+      const diagnostics = await (services.environmentDiagnostics || environmentDiagnostics)();
+      report.diagnostics.push(...diagnostics);
+      report.errors.push(...diagnostics.filter(item => item.severity === 'error').map(item => item.message));
+    }
+    report.ok = report.errors.length === 0;
+  } catch (error) { diagnostic('preflight', error, 'Resolve the reported file or installation error and retry.'); }
   finally { restore(); }
   return report;
 }

package/build/compiler.mjs

@@ -13,11 +13,28 @@ import { webpackGraph } from './webpack-graph.mjs';
 import { turbopackRules, sourceReader } from './turbopack-conditions.mjs';
 import {withSourceMaps,configureSourceMaps,inlineSourceMap} from './source-maps.mjs';
 import { optimizeImportsPlugins } from './optimize-imports.mjs';
+import {recordBuildAnalysis} from './analyze.mjs';
+import {recordDevDependencies,developmentDependencies,developmentStylePlans,developmentStyleDependencies,developmentModules} from './dev-dependencies.mjs';
 
 let validateOptions;
 const compilation = new AsyncLocalStorage();
 export const withCompilation = callback => withSourceMaps(()=>compilation.run({ targets: new Map(), loaded: new Map() }, callback));
 export function configureCompiler(options) { Object.assign(compilation.getStore() || {}, options);configureSourceMaps(options.dev || options.config?.productionBrowserSourceMaps); }
+export const buildAnalysisRecords=()=>compilation.getStore()?.analysis;
+export const buildAnalysisRoutes=()=>compilation.getStore()?.analysisRoutes;
+export const devDependencies=(project,manifest)=>developmentDependencies(compilation.getStore(),project,manifest);
+export const devStylePlans=()=>developmentStylePlans(compilation.getStore());
+export const devStyleDependencies=()=>developmentStyleDependencies(compilation.getStore());
+export const devModules=root=>developmentModules(compilation.getStore(),root);
+export async function readCompilerFile(file,override){
+  if(override!==undefined)return override;
+  const state=compilation.getStore();if(!state)return readFile(file,'utf8');
+  state.sourceFiles||=new Map();
+  if(state.sourceFiles.has(file))return state.sourceFiles.get(file);
+  const pending=readFile(file,'utf8').then(source=>{state.devInputs?.record(file,source);state.sourceBytes=(state.sourceBytes||0)+source.length*2;if(state.sourceBytes>8*1024*1024)state.sourceFiles.delete(file);return source;});
+  if(state.sourceFiles.size<512)state.sourceFiles.set(file,pending);
+  return pending;
+}
 export async function compilerSource(file, fallback) {
   return compilation.getStore()?.loaded.get(file)?.source ?? fallback ?? await readFile(file, 'utf8');
 }
@@ -120,6 +137,13 @@ export async function validateCompilerConfig(config, root, {dev=false,edge=false
   for (const target of ['node','browser',...(edge?['edge']:[])]) await targetConfig(state,target);
 }
 export async function build(options) {
+  const state=compilation.getStore();
+  const result=await compileGraph(options);
+  recordBuildAnalysis(state,options,result);
+  recordDevDependencies(state,options,result);
+  return result;
+}
+async function compileGraph(options) {
   const state = compilation.getStore();
   if ((options.plugins || []).some(plugin => framework.test(plugin.name))) options = { ...options, plugins: optimizeImportsPlugins(options.plugins, state?.config?.experimental?.optimizePackageImports) };
   // esbuild's shared service dispatches callbacks from its own async context.
@@ -137,7 +161,7 @@ export async function build(options) {
   // Runtime vendor bundles are framework-owned, not project webpack targets.
   const projectGraph = (options.plugins || []).some(plugin => framework.test(plugin.name));
   if (projectGraph && state?.tsconfig) options = { ...options, tsconfig: state.tsconfig };
-  const compile = input => state?.incremental && state.dev && (projectGraph || !input.plugins?.length) ? incrementalBuild(input,{root:state.root,stage:state.stage,group:projectGraph?'project':'auxiliary',run:callback=>compilation.run(state,callback)}) : esbuild(input);
+  const compile = input => state?.incremental && (projectGraph || !input.plugins?.length) ? incrementalBuild(input,{root:state.root,stage:state.stage,group:projectGraph?'project':'auxiliary',run:callback=>compilation.run(state,callback)}) : esbuild(input);
   if (!(state?.config?.webpack || Object.keys(state?.config?.turbopack?.rules || {}).length) || !projectGraph) return compile(options);
   const target = options.define?.['process.env.NEXT_RUNTIME'] === '"edge"' ? 'edge' : options.platform === 'browser' ? 'browser' : 'node';
   const config = await targetConfig(state,target);

package/build/concurrent.mjs

@@ -0,0 +1,12 @@
+import {availableParallelism} from 'node:os';
+
+// A shared finite worker set, with deterministic results and full settlement
+// before a caller discards its stage. No new work starts after a failure.
+export async function mapConcurrent(items,run,limit=Math.min(4,availableParallelism())) {
+  if(!Number.isInteger(limit)||limit<1||limit>32)throw new RangeError('Invalid build concurrency');
+  const values=Array.from(items),results=new Array(values.length);let next=0,failure,failed=false;
+  await Promise.all(Array.from({length:Math.min(limit,values.length)},async()=>{
+    while(!failed&&next<values.length){const index=next++;try{results[index]=await run(values[index],index);}catch(error){if(!failed){failed=true;failure=error;}}}
+  }));
+  if(failed)throw failure;return results;
+}

package/build/config.mjs

@@ -17,6 +17,7 @@ import { validateI18n } from './i18n.mjs';
 import { frameworkPackages } from './framework-imports.mjs';
 import { validateTypeScript } from './typescript.mjs';
 import { validateWorkerRetirement } from './worker-retirement.mjs';
+import {validateWorkerPreload} from './worker-preload.mjs';
 import { validateOptimizePackageImports } from './optimize-imports.mjs';
 import { validateProxyBodySize } from './proxy-body-config.mjs';
 
@@ -26,6 +27,8 @@ const supported = new Set(['env', 'redirects', 'headers', 'rewrites', 'generateB
 const defaults = { distDir: '.prnext', env: {}, compress: true, poweredByHeader: true, productionBrowserSourceMaps: false, basePath: '', assetPrefix: '', trailingSlash: false, skipTrailingSlashRedirect: false, skipMiddlewareUrlNormalize: false, experimental: { nextScriptWorkers: false } };
 supported.add('cacheHandler');
 supported.add('workerRetirement');
+supported.add('workerPreload');
+supported.add('cssEngine');
 supported.add('cacheMaxMemorySize');
 supported.add('turbopack');
 supported.add('i18n');
@@ -47,7 +50,7 @@ export function publicAssetBase(config) {
   return (config.assetPrefix || config.basePath || '').replace(/\/+$/, '') + '/_prnext/assets';
 }
 
-function configPlugin() {
+function configPlugin(devInputs) {
   return {
     name: 'prnext-project-config',
     setup(build) {
@@ -56,20 +59,21 @@ function configPlugin() {
         if (filename.includes(`${path.sep}node_modules${path.sep}`)) return;
         // Preserve filesystem paths after bundling config's relative helpers.
         const prefix = `const __prnext_config_url=${JSON.stringify(pathToFileURL(filename).href)};const __prnext_config_file=${JSON.stringify(filename)};const __prnext_config_dir=${JSON.stringify(path.dirname(filename))};\n`;
-        const source = (await readFile(filename, 'utf8')).replace(/^#![^\n]*(?:\n|$)/, '');
+        const raw = await readFile(filename, 'utf8');devInputs?.record(filename,raw);
+        const source = raw.replace(/^#![^\n]*(?:\n|$)/, '');
         return { contents: prefix + source, loader: filename.endsWith('.ts') ? 'ts' : 'js', resolveDir: path.dirname(filename) };
       });
     },
   };
 }
 
-async function importConfig(filename) {
+async function importConfig(filename,devInputs) {
   const temporary = path.join(path.dirname(filename), `.prnext-config-${randomUUID()}.mjs`);
   try {
     const result = await bundle({ entryPoints: [filename], absWorkingDir: path.dirname(filename), bundle: true, write: false, platform: 'node', target: 'node22', format: 'esm', packages: 'external', logLevel: 'silent',
       define: { 'import.meta.url': '__prnext_config_url', __filename: '__prnext_config_file', __dirname: '__prnext_config_dir' },
       banner: { js: `import {createRequire as __prnext_create_require} from 'node:module';const require=__prnext_create_require(${JSON.stringify(pathToFileURL(filename).href)});` },
-      plugins: [configPlugin()],
+      plugins: [configPlugin(devInputs)],
     });
     await writeFile(temporary, result.outputFiles[0].contents, { flag: 'wx' });
     const imported = await import(pathToFileURL(temporary).href);
@@ -85,14 +89,18 @@ export function validateProjectConfig(input, filename = 'project config') {
   // Optional properties explicitly set to undefined still use their defaults,
   // as in common process.env-based Next configuration wrappers.
   const config = { ...defaults, ...Object.fromEntries(Object.entries(input).filter(([,value]) => value !== undefined)) };
-  for (const key of ['reactCompiler', 'typedRoutes']) {
-    if (config[key] === undefined || config[key] === false) continue;
-    if (key === 'reactCompiler') throw new Error('reactCompiler currently supports only false. PRNext does not run the React Compiler transform; keep Next.js for builds that require it.');
-    throw new Error('typedRoutes currently supports only false. PRNext does not generate or validate typed route declarations; keep Next.js for builds that require them.');
-  }
+  if(config.typedRoutes!==undefined&&typeof config.typedRoutes!=='boolean')throw new TypeError('typedRoutes must be a boolean');
+  if(config.reactCompiler!==undefined&&config.reactCompiler!==false)throw new Error('reactCompiler currently supports only false. PRNext does not run the React Compiler transform; keep Next.js for builds that require it.');
   config.typescript = validateTypeScript(config.typescript);
   config.workerRetirement = validateWorkerRetirement(config.workerRetirement);
-  if (config.devIndicators !== undefined && config.devIndicators !== false) throw new TypeError('devIndicators currently supports only false. PRNext provides development errors and Fast Refresh, but no Next.js development indicator menu.');
+  config.workerPreload=validateWorkerPreload(config.workerPreload);
+  config.cssEngine ??= 'auto';
+  if (!['auto','postcss','lightningcss'].includes(config.cssEngine)) throw new TypeError('cssEngine must be auto, postcss or lightningcss.');
+  if (config.devIndicators !== false) {
+    const indicator = config.devIndicators ?? {};
+    if (config.devIndicators === null || typeof indicator !== 'object' || Array.isArray(indicator) || Object.keys(indicator).some(key => key !== 'position') || (indicator.position !== undefined && !['bottom-right', 'bottom-left', 'top-right', 'top-left'].includes(indicator.position))) throw new TypeError('devIndicators must be false or an object with position: bottom-right, bottom-left, top-right or top-left.');
+    config.devIndicators = { position: indicator.position ?? 'bottom-left' };
+  }
   if (config.onDemandEntries !== undefined) {
     const entries = config.onDemandEntries;
     if (!entries || typeof entries !== 'object' || Array.isArray(entries)) throw new TypeError('onDemandEntries must be an object');
@@ -182,9 +190,9 @@ export function validateProjectConfig(input, filename = 'project config') {
 }
 
 /** Config and its relative imports are evaluated fresh on every build. */
-export async function loadProjectConfig(projectRoot, { dev = false, envMode, phase = dev ? constants.PHASE_DEVELOPMENT_SERVER : constants.PHASE_PRODUCTION_BUILD } = {}) {
+export async function loadProjectConfig(projectRoot, { dev = false, envMode, devInputs, phase = dev ? constants.PHASE_DEVELOPMENT_SERVER : constants.PHASE_PRODUCTION_BUILD } = {}) {
   const root = path.resolve(projectRoot);
-  loadEnvConfig(root, { dev, mode: envMode });
+  loadEnvConfig(root, { dev, mode: envMode, inputs:devInputs });
   const files = await readdir(root);
   const names = files.filter(name => configName.test(name));
   const unsupportedFiles = files.filter(name => /^(?:next|prnext)\.config\.(?:mts|cts|jsx|tsx|json)$/.test(name));
@@ -192,7 +200,7 @@ export async function loadProjectConfig(projectRoot, { dev = false, envMode, pha
   if (names.length > 1) throw new Error(`Multiple configuration files found: ${names.sort().join(', ')}. Keep one next.config.* or prnext.config.* file.`);
   if (!names.length) return validateProjectConfig({});
   const filename = path.join(root, names[0]);
-  let input = await importConfig(filename);
+  let input = await importConfig(filename,devInputs);
   if (typeof input === 'function') input = await input(phase, { defaultConfig: { ...defaults, env: {}, experimental: { ...defaults.experimental } } });
   return validateProjectConfig(input, names[0]);
 }

package/build/css-modules.mjs

@@ -5,6 +5,9 @@ import { createHash } from 'node:crypto';
 import { runInNewContext } from 'node:vm';
 import { createRequire } from 'node:module';
 import { createStyleProcessor, stylesheetPattern, moduleStylesheetPattern } from './styles.mjs';
+import {rename} from '../runtime/fs.mjs';
+import {randomUUID} from 'node:crypto';
+import {rm} from 'node:fs/promises';
 
 const assetLoaders = Object.fromEntries(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg', '.ico', '.woff', '.woff2', '.ttf', '.eot'].map(ext => [ext, 'file']));
 
@@ -20,18 +23,20 @@ async function resolveCss(esbuild, args) {
 }
 
 /** One cached CSS compilation supplies identical class maps to the server and the browser. */
-export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/assets', sassOptions }) {
+export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/assets', sassOptions, cssEngine }) {
   const cache = new Map();
-  const processor = createStyleProcessor({ projectRoot, sassOptions });
+  const processor = createStyleProcessor({ projectRoot, sassOptions, cssEngine });
   const hash = file => createHash('sha256').update(path.relative(projectRoot, file).replaceAll(path.sep, '/')).digest('hex').slice(0, 12);
 
   async function compile(file) {
+    const dependencies=new Set([file]);
     const result = await bundle({
       absWorkingDir: projectRoot,
       stdin: { contents: `import styles from ${JSON.stringify(file)}; export default styles;`, resolveDir: projectRoot, loader: 'js' },
       outfile: path.join(stage, '.cssmodules', hash(file) + '.js'),
       bundle: true,
       write: false,
+      metafile:true,
       format: 'cjs',
       platform: 'browser',
       logLevel: 'silent',
@@ -52,10 +57,12 @@ export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/ass
           });
           esbuild.onLoad({ filter: /.*/, namespace: 'prnext-local-css' }, async args => {
             const transformed = await processor.process(args.pluginData.source);
+            for(const file of transformed.watchFiles)dependencies.add(file);
             return { contents: transformed.css, loader: 'local-css', resolveDir: path.dirname(args.pluginData.source), watchFiles: transformed.watchFiles };
           });
           esbuild.onLoad({ filter: stylesheetPattern, namespace: 'file' }, async args => {
             const transformed = await processor.process(args.path);
+            for(const file of transformed.watchFiles)dependencies.add(file);
             return { contents: transformed.css, loader: 'css', resolveDir: path.dirname(args.path), watchFiles: transformed.watchFiles };
           });
           esbuild.onResolve({ filter: /^\// }, args => args.kind === 'url-token' ? { path: args.path, external: true } : undefined);
@@ -64,6 +71,7 @@ export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/ass
     });
     const javascript = result.outputFiles.find(output => output.path.endsWith('.js'));
     const stylesheet = result.outputFiles.find(output => output.path.endsWith('.css'));
+    for(const name of Object.keys(result.metafile.inputs))if(name!=='<stdin>'&&(!name.includes(':')||path.isAbsolute(name)))dependencies.add(path.resolve(projectRoot,name));
     if (!javascript || !stylesheet) throw new Error(`Unable to compile CSS Module ${file}.`);
     // This is esbuild's generated export map, whose only inputs are CSS files.
     // The isolated context deliberately has no require, process, network, or filesystem.
@@ -73,9 +81,10 @@ export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/ass
     await mkdir(path.join(stage, 'assets'), { recursive: true });
     for (const output of result.outputFiles) {
       if (output === javascript || output === stylesheet) continue;
-      await writeFile(path.join(stage, 'assets', path.basename(output.path)), output.contents);
+      const target=path.join(stage,'assets',path.basename(output.path)),temporary=target+'.'+randomUUID()+'.tmp';
+      try{await writeFile(temporary,output.contents);await rename(temporary,target);}finally{await rm(temporary,{force:true});}
     }
-    return { mapping, css: stylesheet.text };
+    return { mapping, css: stylesheet.text,watchFiles:[...dependencies] };
   }
 
   function get(file) {
@@ -84,6 +93,8 @@ export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/ass
   }
 
   return {
+    compile:get,
+    async mappings(){return Promise.all([...cache].map(async([file,result])=>({file,mapping:(await result).mapping,watchFiles:(await result).watchFiles})));},
     plugin(browser, { emitStyles = () => true } = {}) {
       return {
         name: 'prnext-shared-css-modules',

package/build/dev-compiler-health.mjs

@@ -0,0 +1,11 @@
+export function createCompilerHealth({maxRssMb=768,maxHeapMb=384,maxBuilds=256}={}) {
+  let builds=0;const samples=[];
+  return ({rss,heapUsed})=>{
+    builds++;const rssMb=rss/1024/1024,heapMb=heapUsed/1024/1024;
+    samples.push(rssMb);if(samples.length>12)samples.shift();
+    const floor=Math.min(...samples),growth=rssMb-floor;
+    const reason=rssMb>=maxRssMb?'rss-limit':heapMb>=maxHeapMb?'heap-limit':
+      samples.length>=8&&growth>128&&rssMb>floor*1.35?'sustained-growth':builds>=maxBuilds?'session-limit':null;
+    return {builds,rssMb:Math.round(rssMb),heapMb:Math.round(heapMb),recycle:reason!==null,reason};
+  };
+}

package/build/dev-css-update.mjs

@@ -0,0 +1,83 @@
+import {build as bundle} from 'esbuild';
+import {readFile,writeFile,rm,stat,readdir} from 'node:fs/promises';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {rename} from '../runtime/fs.mjs';
+import {createCssModules} from './css-modules.mjs';
+import {recordDevDependencies,developmentStyleDependencies} from './dev-dependencies.mjs';
+import {writeBuildOutput} from './output-contract.mjs';
+
+/** Publish only styles when all JS-visible class maps remain identical. */
+export async function tryDevCssUpdate({root,source,destination,manifest,changed,sequence,cssEngine,snapshot,onFallback=()=>{}}){
+  const fallback=code=>{onFallback(code);return undefined;};
+  if(!changed.length||changed.some(file=>!file.endsWith('.css'))||!manifest.devStyles?.bundles.length||manifest.app?.globalError?.css?.length)return;
+  if(!manifest.config.assetBase.startsWith('/'))return fallback('external-asset-base');
+  if(JSON.parse(await readFile(path.join(root,'package.json'),'utf8')).postcss!==undefined)return fallback('css-processor');
+  // Custom PostCSS/webpack generators can change JS or emit other files.
+  for(const name of ['postcss.config.js','postcss.config.cjs','postcss.config.mjs','postcss.config.json','.postcssrc','.postcssrc.json'])if(await stat(path.join(root,name)).catch(()=>null)){
+    if(name!=='postcss.config.json')return fallback('css-processor');
+    const value=JSON.parse(await readFile(path.join(root,name),'utf8'));
+    if(Object.keys(value).some(key=>key!=='plugins')||!value.plugins||Object.keys(value.plugins).length)return fallback('css-processor');
+  }
+  const plans=manifest.devStyles.bundles,dependencies=new Map(manifest.devStyles.dependencies||[]);
+  // Older manifests lack enough provenance to select bundles safely.
+  if(plans.some(([name])=>!dependencies.get(name)?.length))return fallback('missing-style-dependencies');
+  const changedPaths=new Set(changed.map(file=>path.resolve(root,file)));
+  const selected=plans.filter(([name])=>dependencies.get(name).some(file=>changedPaths.has(file)));
+  const known=new Set([...dependencies.values()].flat());
+  const allRoots=plans.flatMap(([,files])=>files);
+  if(selected.flatMap(([,files])=>files).some(file=>!file.endsWith('.css')||!file.startsWith('prnext-compiled-css:')&&!path.isAbsolute(file)))return fallback('stylesheet-language');
+  for(const file of allRoots)known.add(file.replace(/^prnext-compiled-css:/,''));
+  for(const dependency of manifest.devDependencies||[])for(const file of dependency.files)if(file.endsWith('.css'))known.add(path.join(root,file));
+  if(changed.some(file=>!known.has(path.join(root,file))))return fallback('unknown-style-dependency');
+  if(!selected.length)return fallback('unknown-style-dependency');
+  const stage=destination,modules=createCssModules({projectRoot:root,stage,assetBase:manifest.config.assetBase,cssEngine});
+  try{
+    await snapshot(source,stage);
+    for(const previous of manifest.devStyles.modules.filter(module=>(module.watchFiles||[module.file]).some(file=>changedPaths.has(file)))){
+      if(!previous.file.endsWith('.css')){await rm(stage,{recursive:true,force:true});return fallback('stylesheet-language');}
+      if((await modules.compile(previous.file)).mapping!==previous.mapping){await rm(stage,{recursive:true,force:true});return fallback('css-module-exports');}
+    }
+    const state={dev:true,root,stage};
+    for(const [name,files]of selected){
+      const options={absWorkingDir:root,stdin:{contents:files.map(file=>`@import ${JSON.stringify(file.replace(/^prnext-compiled-css:/,'prnext-css:'))};`).join('\n'),resolveDir:root,loader:'css'},outfile:path.join(stage,'assets',name),bundle:true,write:false,metafile:true,logLevel:'silent',publicPath:manifest.config.assetBase,assetNames:'[name]-[hash]',loader:Object.fromEntries(['.png','.jpg','.jpeg','.svg','.gif','.webp','.avif','.woff','.woff2','.ttf'].map(ext=>[ext,'file'])),plugins:[modules.plugin(true)]};
+      const result=await bundle(options);recordDevDependencies(state,options,result);
+      for(const output of result.outputFiles){const temporary=output.path+'.'+randomUUID()+'.tmp';try{await writeFile(temporary,output.contents);await rename(temporary,output.path);}finally{await rm(temporary,{force:true});}}
+    }
+    const compiled=await modules.mappings();
+    if(compiled.some(value=>!manifest.devStyles.modules.some(previous=>previous.file===value.file&&previous.mapping===value.mapping))){await rm(stage,{recursive:true,force:true});return fallback('css-module-exports');}
+    const updated=manifest.devStyles.modules.map(previous=>compiled.find(value=>value.file===previous.file)||previous);
+    for(const [name,files]of developmentStyleDependencies(state)){
+      for(const module of updated)if(files.includes(module.file))for(const file of module.watchFiles)if(!files.includes(file))files.push(file);
+      dependencies.set(name,files);
+    }
+    const buildId=randomUUID(),baseClient=manifest.devStyles.baseClient||manifest.devClient,next={...manifest,buildId,devSequence:sequence,devClient:manifest.config.assetBase+'/dev-manifest-'+buildId+'.json',outputDirectory:stage,devStyles:{baseClient,bundles:plans,dependencies:[...dependencies],modules:updated}};
+    // Keep route invalidation conservative as CSS imports are added or removed.
+    // Unchanged routes retain their original dependency arrays.
+    next.devDependencies=(manifest.devDependencies||[]).map(route=>{
+      const relevant=selected.filter(([name])=>manifest.devStyles.dependencies.find(([key])=>key===name)[1].some(file=>route.files.includes(path.relative(root,file).replaceAll(path.sep,'/'))));
+      if(!relevant.length)return route;
+      const currentStyleFiles=new Set([...dependencies.values()].flat());
+      const removed=new Set(manifest.devStyles.dependencies.flatMap(([,files])=>files).filter(file=>!currentStyleFiles.has(file)).map(file=>path.relative(root,file).replaceAll(path.sep,'/')));
+      const files=new Set(route.files.filter(file=>!removed.has(file)));
+      for(const[name]of relevant)for(const file of dependencies.get(name)){
+        const relative=path.relative(root,file).replaceAll(path.sep,'/');
+        if(relative&&!relative.startsWith('../')&&!relative.includes(':'))files.add(relative);
+      }
+      return {...route,files:[...files]};
+    });
+    const old=JSON.parse(await readFile(path.join(source,'assets',path.basename(manifest.devClient)),'utf8'));
+    old.buildId=buildId;
+    const changedNames=new Set(selected.map(([name])=>name));
+    const revise=urls=>urls.map(url=>changedNames.has(path.posix.basename(url.split('?')[0]))?url.split('?')[0]+'?v='+buildId:url);
+    for(const page of old.pages)page.css=revise(page.css);if(old.app)old.app.css=revise(old.app.css);
+    await writeFile(path.join(stage,'assets',path.basename(next.devClient)),JSON.stringify(old));
+    const protectedNames=new Set([path.basename(baseClient),path.basename(next.devClient)]),history=[];
+    for(const name of await readdir(path.join(stage,'assets')))if(/^dev-manifest-.*\.json$/.test(name)&&!protectedNames.has(name)){const info=await stat(path.join(stage,'assets',name));history.push({name,size:info.size,time:info.mtimeMs});}
+    history.sort((a,b)=>b.time-a.time);let bytes=0;
+    for(let i=0;i<history.length;i++){bytes+=history[i].size;if(i>=32||bytes>4*1024*1024)await rm(path.join(stage,'assets',history[i].name));}
+    const temporary=path.join(stage,'manifest.'+buildId+'.tmp');await writeFile(temporary,JSON.stringify(next));await rename(temporary,path.join(stage,'manifest.json'));
+    await rm(path.join(stage,'build-output.json'));await writeBuildOutput(stage,next);
+    return next;
+  }catch(error){await rm(stage,{recursive:true,force:true});throw error;}
+}

package/build/dev-dependencies.mjs

@@ -0,0 +1,44 @@
+import path from 'node:path';
+export function recordDevDependencies(state,options,result){
+  if(!state?.dev||!result.metafile)return;
+  state.devDependencies||=new Map();state.devStyleBundles||=new Map();state.devStyleDependencies||=new Map();
+  const absolute=name=>path.resolve(options.absWorkingDir||state.root,name.replace(/^[\w-]+:(?=(?:[A-Za-z]:[\\/]|\/))/ ,''));
+  for(const [name,input]of Object.entries(result.metafile.inputs)){
+    const file=absolute(name),imports=state.devDependencies.get(file)||new Set();
+    for(const item of input.imports||[])if(!item.external)imports.add(absolute(item.path));
+    state.devDependencies.set(file,imports);
+  }
+  for(const [name,output]of Object.entries(result.metafile.outputs))if(name.endsWith('.css')){
+    const inputs=Object.keys(output.inputs||{}).filter(file=>file!=='<stdin>'),imported=new Set();
+    for(const input of inputs)for(const item of result.metafile.inputs[input]?.imports||[])if(item.kind==='import-rule')imported.add(item.path);
+    const roots=inputs.filter(input=>!imported.has(input));
+    state.devStyleBundles.set(path.basename(name),roots.map(file=>file.startsWith('prnext-compiled-css:')?file:path.isAbsolute(file)?file:path.resolve(state.root,file)));
+    state.devStyleDependencies.set(path.basename(name),inputs.map(absolute));
+  }
+}
+export function developmentDependencies(state,project,manifest){
+  const graph=state?.devDependencies||new Map(),routes=[];
+  let bytes=0;
+  for(const route of manifest.routes.filter(route=>!route.internal)){
+    const source=project.routes.find(item=>item.id===route.id);if(!source)continue;
+    const pending=[],seen=new Set(),visit=value=>{if(typeof value==='string'&&path.isAbsolute(value))pending.push(value);else if(Array.isArray(value))value.forEach(visit);else if(value&&typeof value==='object')Object.values(value).forEach(visit);};
+    visit(source);if(project.app)pending.push(project.app);if(project.document)pending.push(project.document);
+    while(pending.length){const file=pending.pop();if(seen.has(file))continue;seen.add(file);for(const dependency of graph.get(file)||[])pending.push(dependency);}
+    const record={route:route.pattern,files:[...seen].filter(file=>file.startsWith(project.root+path.sep)&&!path.relative(project.root,file).startsWith('.prnext-')).map(file=>path.relative(project.root,file).replaceAll(path.sep,'/')).filter(file=>!file.includes(':')&&!file.includes('?'))};
+    bytes+=Buffer.byteLength(JSON.stringify(record));if(bytes>16*1024*1024||routes.length>=50000)return Object.assign([],{incomplete:'Route dependency graph exceeds the 16 MiB / 50,000 record budget'});
+    routes.push(record);
+  }
+  return routes;
+}
+export const developmentStylePlans=state=>[...(state?.devStyleBundles||[])];
+export const developmentStyleDependencies=state=>[...(state?.devStyleDependencies||[])];
+export function developmentModules(state,root){
+  const records=[];let bytes=0;
+  const relative=file=>{const name=path.relative(root,file).replaceAll(path.sep,'/');return !name||name.startsWith('../')||name.includes(':')||name.includes('?')||name.startsWith('.prnext-')||name.startsWith('node_modules/')?undefined:name;};
+  for(const[file,dependencies]of state?.devDependencies||[]){
+    const name=relative(file);if(!name)continue;
+    const record={route:name,module:true,files:[name,...[...dependencies].map(relative).filter(Boolean)]};
+    bytes+=Buffer.byteLength(JSON.stringify(record));if(bytes>16*1024*1024||records.length>=50000)return Object.assign([],{incomplete:'Module dependency graph exceeds the 16 MiB / 50,000 record budget'});records.push(record);
+  }
+  return records;
+}

package/build/dev-discovery.mjs

@@ -0,0 +1,28 @@
+import {loadProjectConfig} from './config.mjs';
+import {scanProject} from './scan.mjs';
+import {snapshotEnvConfig} from '../runtime/env.mjs';
+
+export function routeFiles(project, patterns) {
+  const files=new Set();
+  const visit=value=>{
+    if(typeof value==='string' && /\.(?:[cm]?js|jsx|tsx?)$/.test(value))files.add(value);
+    else if(Array.isArray(value))for(const item of value)visit(item);
+    else if(value&&typeof value==='object')for(const item of Object.values(value))visit(item);
+  };
+  for(const route of project.routes)if(patterns.includes(route.pattern)||route.internal||route.errorStatus)visit(route);
+  visit(project.appNotFound);return files;
+}
+export async function discoverDevelopment(root) {
+  const restore=snapshotEnvConfig();
+  const envMode=process.env.NODE_ENV==='test'?'test':'development';
+  process.env.NODE_ENV='development';
+  try {
+    const config=await loadProjectConfig(root,{dev:true,envMode});
+    const project=await scanProject(root,{basePath:config.basePath,pageExtensions:config.pageExtensions,i18n:config.i18n,devAppFiles:new Set()});
+    // Dynamic middleware/rewrite destinations and intercepted/parallel trees
+    // need the complete graph until the gateway can resolve their routing RPC.
+    const eager=!!project.middleware || !!config.rewrites || project.routes.some(route=>route.parallel||route.interception);
+    return {project,eager,cssFast:!config.webpack&&!Object.keys(config.turbopack?.rules||{}).length,config:{basePath:config.basePath,assetPrefix:config.assetPrefix,i18n:config.i18n,distDir:config.distDir,
+      onDemandEntries:config.onDemandEntries,typescript:config.typescript,typedRoutes:config.typedRoutes,cssEngine:config.cssEngine}};
+  } finally {restore();}
+}

package/build/dev-worker.mjs

@@ -1,17 +1,26 @@
 import {build} from './index.mjs';
-import {closeIncrementalCompiler} from './incremental.mjs';
+import {closeIncrementalCompiler,incrementalCompilerStats} from './incremental.mjs';
 import {realpath} from 'node:fs/promises';
 import {createDevInputSnapshot} from '../runtime/dev-file-changes.mjs';
-let builds=0,busy=false;
+import {discoverDevelopment} from './dev-discovery.mjs';
+import {transformCacheStats} from './transform-cache.mjs';
+import {scheduleCompileCacheFlush} from '../runtime/compile-cache.mjs';
+import {createCompilerHealth} from './dev-compiler-health.mjs';
+const compilerHealth=createCompilerHealth();
+let busy=false;
 process.on('message',async message=>{
-  if(message?.type!=='build'||busy)return;
+  if(!['build','discover'].includes(message?.type)||busy)return;
   busy=true;
   try{
+    if(message.type==='discover'){process.send({type:'result',ok:true,discovery:await discoverDevelopment(message.root)});return;}
     const started=performance.now();
     const inputs=createDevInputSnapshot([message.root,await realpath(message.root)]);
-    await build(message.root,{dev:true,incremental:true,devInputs:inputs});
+    const manifest=await build(message.root,{dev:true,incremental:!message.options?.devSafe,...message.options,devInputs:inputs});
     console.log(`PRNext built ${message.root} in ${((performance.now()-started)/1000).toFixed(2)}s`);
-    process.send({type:'result',ok:true,inputs:inputs.entries(),recycle:++builds>=24 || process.memoryUsage().rss>512*1024*1024});
+    scheduleCompileCacheFlush();
+    const health=compilerHealth(process.memoryUsage());
+    if(message.options?.devSafe)Object.assign(health,{recycle:true,reason:'safe-mode'});
+    process.send({type:'result',ok:true,manifest,inputs:inputs.entries(),compiler:{...incrementalCompilerStats(),health},transforms:transformCacheStats(),recycle:health.recycle});
   }catch(error){process.send({type:'result',ok:false,error:error.stack||error.message,recycle:true});}
   finally{busy=false;}
 });