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

package/build/css-modules.mjs

@@ -1,10 +1,15 @@
 import { build as bundle } from 'esbuild';
-import { mkdir, writeFile, realpath } from 'node:fs/promises';
+import { mkdir, writeFile, realpath, readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { runInNewContext } from 'node:vm';
 import { createRequire } from 'node:module';
-import { createStyleProcessor, stylesheetPattern, moduleStylesheetPattern } from './styles.mjs';
+import { createStyleProcessor, resolveStandardBrowserTargets, stylesheetPattern, moduleStylesheetPattern } from './styles.mjs';
+import {rename} from '../runtime/fs.mjs';
+import {randomUUID} from 'node:crypto';
+import {rm} from 'node:fs/promises';
+import {cachedCompilation} from './compilation-cache.mjs';
+import {compactCssModule,globalCssNames} from './compact-css.mjs';
 
 const assetLoaders = Object.fromEntries(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg', '.ico', '.woff', '.woff2', '.ttf', '.eot'].map(ext => [ext, 'file']));
 
@@ -20,18 +25,41 @@ 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 }) {
-  const cache = new Map();
-  const processor = createStyleProcessor({ projectRoot, sassOptions });
+export function createCssModules({ projectRoot, stage, assetBase = '/_prnext/assets', sassOptions, cssEngine, dev = false, config = {} }) {
+  const cache = new Map(), compactNames = new Map();
+  let targets;
+  const browserTargets=()=>targets ??= Promise.resolve().then(()=>resolveStandardBrowserTargets(projectRoot));
+  const processor = createStyleProcessor({ projectRoot, sassOptions, cssEngine, browserTargets });
   const hash = file => createHash('sha256').update(path.relative(projectRoot, file).replaceAll(path.sep, '/')).digest('hex').slice(0, 12);
+  let eligibility;
+  async function cacheEligible() {
+    if (dev || cssEngine==='postcss' || config.webpack || Object.keys(config.turbopack?.rules || {}).length || process.env.BROWSERSLIST_CONFIG || process.env.BROWSERSLIST_STATS || /\b(?:extends|stats)\b/i.test(process.env.BROWSERSLIST || '')) return false;
+    // A user PostCSS plugin can read arbitrary files, glob directories or use
+    // network/time without declaring dependencies. Its output is never cached.
+    const names = await readdir(projectRoot);
+    if (names.some(name => /^(?:postcss\.config|\.postcssrc)(?:\.|$)/.test(name))) return false;
+    try { if (JSON.parse(await readFile(path.join(projectRoot, 'package.json'), 'utf8')).postcss !== undefined) return false; }
+    catch (error) { if (error.code !== 'ENOENT') return false; }
+    return true;
+  }
+  const validMapping = value => {try{const parsed=JSON.parse(value);return parsed&&typeof parsed==='object'&&!Array.isArray(parsed)&&Object.values(parsed).every(value=>typeof value==='string');}catch{return false;}};
+  const validResult = value => value && typeof value.mapping === 'string' && value.mapping.length <= 16*1024*1024 && validMapping(value.mapping) && typeof value.css === 'string' && value.css.length <= 16*1024*1024
+    && Array.isArray(value.compactNames) && value.compactNames.length <= 65536 && value.compactNames.every(item=>Array.isArray(item)&&item.length===2&&typeof item[0]==='string'&&item[0].length<=4096&&typeof item[1]==='string'&&/^p[\w-]{10}$/.test(item[1]))
+    && Array.isArray(value.watchFiles) && value.watchFiles.length <= 4096 && value.watchFiles.every(file => typeof file==='string' && path.isAbsolute(file) && !file.includes('\0') && !/\.s[ac]ss$/i.test(file))
+    && Array.isArray(value.assets) && value.assets.length <= 4096 && value.assets.every(asset => asset && typeof asset.name === 'string'
+      && asset.name && asset.name === path.basename(asset.name) && !/[\\/\0<>:"|?*#]/.test(asset.name) && asset.name !== '.' && asset.name !== '..'
+      && typeof asset.data === 'string' && asset.data.length<=24*1024*1024 && asset.data.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(asset.data))
+    && new Set(value.assets.map(asset=>asset.name)).size===value.assets.length && value.assets.reduce((sum,asset)=>sum+asset.data.length,0)<=48*1024*1024;
 
   async function compile(file) {
+    const dependencies=new Set([file]), globals = new Set();
     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 +80,14 @@ 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);
+            if (!dev) globalCssNames(transformed.css, {local:true}, globals);
+            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);
+            if (!dev) globalCssNames(transformed.css, {local:false}, globals);
+            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,26 +96,49 @@ 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.
     const module = { exports: {} };
     runInNewContext(javascript.text, { module }, { timeout: 1000, filename: 'prnext-css-exports.cjs' });
-    const mapping = JSON.stringify({ ...module.exports.default, ...(await processor.process(file)).exports });
-    await mkdir(path.join(stage, 'assets'), { recursive: true });
+    const compact = dev ? {mapping:module.exports.default,css:stylesheet.text,names:[]} : compactCssModule(stylesheet.text,module.exports.default,{globals});
+    const mapping = JSON.stringify({ ...compact.mapping, ...(await processor.process(file)).exports });
+    const assets = [];
     for (const output of result.outputFiles) {
       if (output === javascript || output === stylesheet) continue;
-      await writeFile(path.join(stage, 'assets', path.basename(output.path)), output.contents);
+      assets.push({name:path.basename(output.path),data:Buffer.from(output.contents).toString('base64')});
     }
-    return { mapping, css: stylesheet.text };
+    return { mapping, css: compact.css,compactNames:compact.names,watchFiles:[...dependencies],assets };
   }
 
   function get(file) {
-    if (!cache.has(file)) cache.set(file, compile(file));
+    if (!cache.has(file)) cache.set(file, (async () => {
+      eligibility ??= cacheEligible();
+      const enabled = await eligibility && /\.css$/i.test(file);
+      const result = await cachedCompilation({root:projectRoot,kind:'css-modules',inputs:[file],excluded:[path.resolve(projectRoot,config.distDir || '.prnext'),...(config.output==='export'?[path.join(projectRoot,'out')]:[])],styleTargets:true,settings:{file,assetBase,cssEngine:cssEngine || 'auto',...(enabled?{browserTargets:await browserTargets()}:{})},
+        enabled,reason:dev?'development':'custom-style-pipeline',validate:validResult,
+        bytes:value=>Buffer.byteLength(value.mapping)+Buffer.byteLength(value.css)+Buffer.byteLength(JSON.stringify(value.compactNames))+value.assets.reduce((sum,asset)=>sum+Buffer.byteLength(asset.data,'base64'),0),
+        produce:async()=>{const value=await compile(file);return {value,dependencies:value.watchFiles};}});
+      await mkdir(path.join(stage,'assets'),{recursive:true});
+      for(const [original,short] of result.compactNames || []) {
+        if(compactNames.has(short)&&compactNames.get(short)!==original)throw new Error('CSS Module compact-name collision across modules.');
+        compactNames.set(short,original);
+      }
+      for (const asset of result.assets) {
+        const target=path.join(stage,'assets',asset.name),temporary=target+'.'+randomUUID()+'.tmp';
+        try{await writeFile(temporary,Buffer.from(asset.data,'base64'));await rename(temporary,target);}finally{await rm(temporary,{force:true});}
+      }
+      // Keep the original public result and release replay-only binary payloads.
+      // The per-build mapping cache must not retain a base64 copy of every asset.
+      return {mapping:result.mapping,css:result.css,watchFiles:result.watchFiles};
+    })());
     return cache.get(file);
   }
 
   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/deployment-assets.mjs

@@ -0,0 +1,89 @@
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const INDEX = 'deployment-assets.json';
+const MAX_FILES = 1024, MAX_BYTES = 64 * 1024 * 1024, MAX_FILE_BYTES = 8 * 1024 * 1024;
+const MAX_AGE = 60 * 60 * 1000, MAX_GENERATIONS = 2;
+// Only build-owned, immutable code/styles. Never JSON, maps, HTML, public/ or server/.
+const safeName = value => typeof value === 'string' && value.length < 240 && /^[a-zA-Z0-9_.-]+-[a-zA-Z0-9]{8,64}\.(?:js|mjs|css|woff2?|ttf|otf|eot|png|jpe?g|avif|webp|gif|svg|ico|wasm)$/.test(value);
+const assetKey = name => process.platform === 'win32' ? name.toLowerCase() : name;
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+async function regular(file, limit) {
+  const info = await lstat(file);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > limit) return;
+  return info;
+}
+async function indexAt(directory) {
+  try {
+    if (!await regular(path.join(directory, INDEX), 1024 * 1024)) return;
+    const value = JSON.parse(await readFile(path.join(directory, INDEX), 'utf8'));
+    if (value.version !== 1 || !Array.isArray(value.generations) || value.generations.length > 6) return;
+    for (const generation of value.generations) {
+      if (typeof generation.id !== 'string' || generation.id.length > 128 || !Number.isSafeInteger(generation.createdAt) || !Array.isArray(generation.files) || generation.files.length > MAX_FILES) return;
+      const seen = new Set();
+      for (const file of generation.files) {
+        if (!safeName(file.name) || seen.has(assetKey(file.name)) || !Number.isSafeInteger(file.bytes) || file.bytes < 0 || file.bytes > MAX_FILE_BYTES || !/^[a-f0-9]{64}$/.test(file.hash)) return;
+        seen.add(assetKey(file.name));
+      }
+    }
+    return value;
+  } catch (error) { if (!['ENOENT', 'ENOTDIR'].includes(error.code)) { /* Corrupt previous metadata is an optional retention miss. */ } }
+}
+
+/** Copy only public immutable assets into a stage, before its atomic publication. */
+export async function retainDeploymentAssets({ stage, destination, manifest, policy, now = Date.now() }) {
+  if (manifest.dev) return { generations: 0, files: 0, bytes: 0 };
+  const maxAge = (policy && policy.maxAge !== undefined ? policy.maxAge * 1000 : MAX_AGE);
+  const maxGenerations = policy && policy.maxGenerations !== undefined ? policy.maxGenerations : MAX_GENERATIONS;
+  const maxBytes = policy && policy.maxBytes !== undefined ? policy.maxBytes : MAX_BYTES;
+  const assets = path.join(stage, 'assets');
+  const assetInfo = await lstat(assets);
+  if (!assetInfo.isDirectory() || assetInfo.isSymbolicLink()) throw new Error('Deployment assets must be a regular directory');
+  const current = { id: manifest.cacheId, createdAt: now, eligible: true, files: [] };
+  let indexedBytes = 0;
+  for (const name of (await readdir(assets)).sort()) {
+    if (!safeName(name)) {
+      // Maps/manifests do not participate in executable chunk graphs. Unknown
+      // content-addressed media and auxiliary directories make retention unsafe.
+      if (/\.(?:map|json|html|txt|gz|br)$/.test(name)) continue;
+      current.eligible = false; current.files = []; break;
+    }
+    const file = path.join(assets, name), info = await regular(file, MAX_FILE_BYTES);
+    if (!info || (indexedBytes += info.size) > 256 * 1024 * 1024) { current.eligible = false; current.files = []; break; }
+    const bytes = await readFile(file);
+    current.files.push({ name, bytes: bytes.length, hash: hash(bytes) });
+    if (current.files.length > MAX_FILES) { current.eligible = false; current.files = []; break; }
+  }
+  const previousRoot = await lstat(path.join(destination, 'assets')).catch(() => null);
+  const previous = !current.eligible || policy === false || !previousRoot?.isDirectory() || previousRoot.isSymbolicLink() ? undefined : await indexAt(destination), generations = [current], known = new Map(current.files.map(file => [assetKey(file.name), file]));
+  const retained = Object.create(null); let bytes = 0, count = 0;
+  for (const generation of previous?.generations || []) {
+    if (generation.eligible !== true || generations.length > maxGenerations || generation.id === current.id || generation.createdAt > now || now - generation.createdAt >= maxAge) continue;
+    if (generation.files.some(file => { const value = known.get(assetKey(file.name)); return value && (value.hash !== file.hash || value.bytes !== file.bytes); })) continue;
+    const candidates = generation.files.filter(file => !known.has(assetKey(file.name)));
+    const size = candidates.reduce((sum, file) => sum + file.bytes, 0);
+    if (bytes + size > maxBytes || count + candidates.length > MAX_FILES) continue;
+    const verified = [];
+    for (const file of candidates) {
+      const source = path.join(destination, 'assets', file.name);
+      try {
+        if (!await regular(source, MAX_FILE_BYTES)) continue;
+        const contents = await readFile(source);
+        if (contents.length !== file.bytes || hash(contents) !== file.hash) continue;
+        verified.push({file, contents});
+      } catch { /* An unreadable previous asset is an optional retention miss. */ }
+    }
+    // An incomplete previous generation cannot promise a working chunk graph.
+    if (verified.length !== candidates.length) continue;
+    for (const {file, contents} of verified) {
+      await writeFile(path.join(assets, file.name), contents, {flag:'wx'});
+      known.set(assetKey(file.name), file); retained[file.name] = generation.createdAt + maxAge;
+      bytes += file.bytes; count++;
+    }
+    generations.push(generation);
+  }
+  manifest.config.retainedAssets = retained;
+  await writeFile(path.join(stage, INDEX), JSON.stringify({ version: 1, generations }) + '\n');
+  return { generations: generations.length - 1, files: count, bytes };
+}

package/build/deployment-config.mjs

@@ -0,0 +1,18 @@
+const defaults=Object.freeze({maxAge:3600,maxGenerations:2,maxBytes:64*1024*1024});
+const limits={maxAge:[1,86400],maxGenerations:[1,5],maxBytes:[1024,256*1024*1024]};
+
+/** Retain only bounded, immutable public assets; false revokes all carry-over. */
+export function validateDeploymentRetention(value){
+  if(value===false)return false;
+  if(value===undefined)return {...defaults};
+  if(!value||typeof value!=='object'||Array.isArray(value)||![Object.prototype,null].includes(Object.getPrototypeOf(value)))throw new TypeError('deploymentRetention must be false or an object.');
+  const output={...defaults};
+  for(const key of Reflect.ownKeys(value)){
+    if(!Object.hasOwn(limits,key))throw new TypeError(`deploymentRetention.${String(key)} is not supported.`);
+    if(value[key]===undefined)continue;
+    const [minimum,maximum]=limits[key];
+    if(!Number.isSafeInteger(value[key])||value[key]<minimum||value[key]>maximum)throw new TypeError(`deploymentRetention.${key} must be an integer from ${minimum} to ${maximum}.`);
+    output[key]=value[key];
+  }
+  return output;
+}

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,85 @@
+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,dev:true});
+  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);
+    const reviseScopes=scopes=>scopes?.map(scope=>({...scope,css:revise(scope.css)}));
+    for(const page of old.pages)page.css=revise(page.css);if(old.app){old.app.css=revise(old.app.css);for(const route of old.app.routes||[]){route.css=revise(route.css);if(route.cssScopes)route.cssScopes=reviseScopes(route.cssScopes);}}
+    next.routes=next.routes.map(route=>({...route,css:revise(route.css||[]),...(route.cssScopes?{cssScopes:reviseScopes(route.cssScopes)}:{})}));
+    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')&&path.resolve(options.absWorkingDir||state.root,name).startsWith(path.join(state.stage,'assets')+path.sep)){
+    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()});
+    // Destinations unknown before routing are represented by deferred entries.
+    // Their worker asks the compiler only after middleware has run once.
+    const eager=false;
+    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;}
 });

package/build/dev.mjs

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

package/build/dynamic.mjs

@@ -67,7 +67,7 @@ export function transformDynamicImports(source, filename, { projectRoot, mode =
 
 function transformDynamicImportsUncached(source, filename, {projectRoot,mode}) {
   const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: filename,
-    plugins: ['jsx', ...(/\.tsx?$/.test(filename) ? ['typescript'] : [])] });
+    plugins: ['jsx', ...(/\.[cm]?tsx?$/.test(filename) ? ['typescript'] : [])] });
   const relative = path.relative(projectRoot || process.cwd(), filename).replaceAll(path.sep, '/');
   let changed = false;
   traverse(ast, {

package/build/edge.mjs

@@ -1,9 +1,9 @@
 import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
-import {frameworkImportName, frameworkSubpathPattern} from './framework-imports.mjs';
+import {applicationEntry, frameworkImportName, frameworkSubpathPattern} from './framework-imports.mjs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { builtinModules, createRequire } from 'node:module';
-import { build } from './compiler.mjs';
+import { build, readCompilerFile } from './compiler.mjs';
 import { parse } from '@babel/parser';
 import traversePackage from '@babel/traverse';
 import { cachedTransform } from './transform-cache.mjs';
@@ -60,7 +60,7 @@ function validateUncached(source,file,reactMode) {
 }
 
 /** Bundle the entire application graph as Web ESM before entering the V8 realm. */
-export async function compileEdge({ file, outfile, projectRoot, dev = false, defineEnvironment = {}, defaultExport = false, reactMode, plugins = [], transformSource }) {
+export async function compileEdge({ file, outfile, projectRoot, dev = false, defineEnvironment = {}, defaultExport = false, reactMode, plugins = [], transformSource, transformTypedHelpers = false }) {
   const runtime = path.resolve(path.dirname(outfile), '../runtime');
   await mkdir(runtime, { recursive: true });
   try { await access(path.join(runtime, 'edge-vm.cjs')); }
@@ -85,6 +85,7 @@ export async function compileEdge({ file, outfile, projectRoot, dev = false, def
     mainFields: ['browser', 'module', 'main'], logLevel: 'silent', metafile: true,
     define: { 'process.env.NODE_ENV': JSON.stringify(dev ? 'development' : 'production'), ...defineEnvironment, 'process.env.NEXT_RUNTIME': '"edge"' },
     plugins: [...plugins, { name: 'prnext-edge', setup(builder) {
+      applicationEntry(builder,readCompilerFile,{transformTypedHelpers});
       builder.onResolve({ filter: /.*/ }, args => {
         if (builtin.has(args.path) || args.path.startsWith('node:')) return { errors: [{ text: `Node.js module ${args.path} cannot run in the Edge Runtime (${args.importer}).` }] };
         if (reactMode && ['react', 'react/jsx-runtime', 'react/jsx-dev-runtime', 'react-dom', 'react-server-dom-webpack/server', 'react-server-dom-webpack/server.node'].includes(args.path)) return { path: args.path, namespace: 'prnext-edge-react' };
@@ -111,7 +112,7 @@ export async function compileEdge({ file, outfile, projectRoot, dev = false, def
         : names[args.path].map(name => `export const ${name}=globalThis.__PRNEXT_EDGE_HOST.${args.path}.${name};`).join('\n') }));
       builder.onLoad({ filter: /\.[cm]?[jt]sx?$/, namespace: 'file' }, async args => {
         let source = args.prnextSource ?? await readFile(args.path, 'utf8');
-        if (transformSource) source = await transformSource(source, args.path, builder);
+        if (transformSource) source = await transformSource(source, args.path, builder, {loaderOutput:args.prnextSource!==undefined});
         if (!trusted.has(args.path)) source = validate(source, args.path, reactMode);
         return { contents: source, loader: /\.[cm]?tsx?$/.test(args.path) ? 'tsx' : 'jsx', resolveDir: path.dirname(args.path) };
       });

package/build/fonts.mjs

@@ -51,7 +51,7 @@ export function createFonts({ projectRoot, stage, assetBase }) {
   }
   async function transformSource(source, file) {
     if (/(?:^|[/\\])pages[/\\]_document\.[cm]?[jt]sx?$/.test(file)) throw new Error('next/font cannot be used in pages/_document. Define fonts in pages/_app or a page component.');
-    const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: file, plugins: ['jsx', ...(/\.tsx?$/.test(file) ? ['typescript'] : [])] });
+    const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: file, plugins: ['jsx', ...(/\.[cm]?tsx?$/.test(file) ? ['typescript'] : [])] });
     let program;
     traverse(ast, { Program(value) { program = value; value.stop(); } });
     const imports = [], calls = [];