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

package/build/analyze.mjs

@@ -0,0 +1,184 @@
+import {readFile,writeFile,stat,open} from 'node:fs/promises';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {gzip,brotliCompress,constants} from 'node:zlib';
+import {promisify} from 'node:util';
+import {mapConcurrent} from './concurrent.mjs';
+import {readBuildDirectory} from '../runtime/build-directory.mjs';
+
+export function recordBuildAnalysis(state,options,result){
+  if(!state?.stage||!result.metafile)return;
+  state.analysis ||= new Map();
+  state.analysisRoutes ||= new Map();
+  const outputs=new Map(Object.entries(result.metafile.outputs).map(([file,info])=>[path.resolve(options.absWorkingDir||state.root,file),info]));
+  for(const [absolute,info] of outputs){
+    const relative=path.relative(state.stage,absolute).replaceAll(path.sep,'/');
+    if(!info.entryPoint||!relative.startsWith('server/'))continue;
+    const visited=new Set(),inputs=new Set(),pending=[absolute];
+    while(pending.length){
+      const next=pending.pop();if(visited.has(next))continue;visited.add(next);
+      const output=outputs.get(next);if(!output)continue;
+      for(const name of Object.keys(output.inputs||{}))inputs.add(path.relative(state.root,path.resolve(options.absWorkingDir||state.root,name)).replaceAll(path.sep,'/'));
+      for(const item of output.imports||[])if(!item.external)pending.push(path.resolve(options.absWorkingDir||state.root,item.path));
+    }
+    state.analysisRoutes.set(relative,inputs);
+  }
+  for(const [file,info] of Object.entries(result.metafile.outputs)){
+    const absolute=path.resolve(options.absWorkingDir||state.root,file);
+    const relative=path.relative(path.join(state.stage,'assets'),absolute).replaceAll(path.sep,'/');
+    if(relative.startsWith('../')||path.isAbsolute(relative)||!relative.endsWith('.js'))continue;
+    state.analysis.set(relative,{file:relative,bytes:info.bytes,imports:(info.imports||[]).filter(item=>!item.external).map(item=>({file:path.relative(path.join(state.stage,'assets'),path.resolve(options.absWorkingDir||state.root,item.path)).replaceAll(path.sep,'/'),kind:item.kind})),
+      modules:Object.entries(info.inputs||{}).map(([name,record])=>({file:path.relative(state.root,path.resolve(options.absWorkingDir||state.root,name)).replaceAll(path.sep,'/').replace(/\.prnext-build-[^/]+\//g,'<generated>/'),bytes:record.bytesInOutput})).sort((a,b)=>b.bytes-a.bytes).slice(0,100)});
+  }
+}
+function initialFiles(entry,files){
+  const seen=new Set(),pending=[entry];
+  while(pending.length){const name=pending.pop();if(seen.has(name)||!files.has(name))continue;seen.add(name);for(const item of files.get(name).imports)if(item.kind!=='dynamic-import')pending.push(item.file);}
+  return [...seen].sort();
+}
+const gzipAsync=promisify(gzip),brotliAsync=promisify(brotliCompress);
+export async function writeBuildAnalysis({root,stage,destination,manifest,records,routeInputs,precompressed=false}){
+  const files=new Map(records||[]);
+  await mapConcurrent(files.values(),async info=>{
+    const file=path.join(stage,'assets',info.file),data=await readFile(file);
+    info.bytes=data.length;
+    // Sidecars in this unpublished stage have just passed decode/hash validation.
+    // Never trust arbitrary sidecars when analysis is called independently.
+    const size=async(extension,compress)=>{
+      if(precompressed)try{return(await stat(file+extension)).size;}catch(error){if(error.code!=='ENOENT')throw error;}
+      return(await compress()).length;
+    };
+    info.gzipBytes=await size('.gz',()=>gzipAsync(data));
+    info.brotliBytes=await size('.br',()=>brotliAsync(data,{params:{[constants.BROTLI_PARAM_QUALITY]:5}}));
+  });
+  const routes=manifest.routes.filter(route=>!route.internal&&route.kind==='page').map(route=>{
+    const client=route.client?decodeURIComponent(new URL(route.client,'http://local').pathname).split('/').pop():null;
+    const entries=client?[client]:[];
+    if(route.router==='app')for(const file of routeInputs?.get(route.module)||[]){
+      const id='client-'+createHash('sha256').update(file).digest('hex').slice(0,16);
+      const entry=manifest.app?.clientModules?.[id]?.browserModule;
+      if(entry)entries.push(new URL(entry,'http://local').pathname.split('/').pop());
+    }
+    const assets=[...new Set(entries.flatMap(entry=>initialFiles(entry,files)))].sort();
+    return {route:route.pattern,files:assets,jsBytes:assets.reduce((total,file)=>total+files.get(file).bytes,0),gzipBytes:assets.reduce((total,file)=>total+files.get(file).gzipBytes,0),brotliBytes:assets.reduce((total,file)=>total+files.get(file).brotliBytes,0)};
+  });
+  const report={version:1,buildId:manifest.buildId,routes,files:[...files.values()],totalJsBytes:[...files.values()].reduce((n,item)=>n+item.bytes,0)};
+  try{const previous=await readReport(path.join(destination,'build-analysis.json'));report.previous={buildId:previous.buildId,totalJsBytes:previous.totalJsBytes,routes:previous.routes.map(({route,jsBytes,gzipBytes,brotliBytes})=>({route,jsBytes,gzipBytes,brotliBytes}))};}catch(error){if(error.code!=='ENOENT')console.warn('Previous bundle analysis could not be read; comparison unavailable.');}
+  await writeFile(path.join(stage,'build-analysis.json'),JSON.stringify(report));
+  return report;
+}
+const metrics={raw:'jsBytes',gzip:'gzipBytes',brotli:'brotliBytes'};
+const size=value=>Number.isSafeInteger(value)&&value>=0;
+const text=value=>typeof value==='string'&&value.length>0&&value.length<=4096&&!/[\0\r\n]/.test(value);
+const object=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
+async function boundedJson(file,label){
+  const handle=await open(file,'r'),limit=16*1024*1024;
+  try{
+    const info=await handle.stat();
+    if(!info.isFile()||info.size>limit)throw new Error(`${label} must be a regular JSON file of at most 16 MiB.`);
+    // Fixed allocation also bounds reads when a concurrent writer grows it.
+    const data=Buffer.alloc(limit+1);let length=0;
+    while(length<data.length){const {bytesRead}=await handle.read(data,length,data.length-length,null);if(!bytesRead)break;length+=bytesRead;}
+    if(length>limit)throw new Error(`${label} exceeds 16 MiB.`);
+    try{return JSON.parse(data.subarray(0,length).toString('utf8'));}catch{throw new Error(`${label} contains invalid JSON.`);}
+  }finally{await handle.close();}
+}
+function validateRoutes(routes,{complete=true}={}){
+  if(!Array.isArray(routes)||routes.length>10000)throw new Error('Invalid analysis routes (maximum 10,000).');
+  const seen=new Set();
+  for(const route of routes){
+    if(!object(route)||!text(route.route)||!route.route.startsWith('/')||seen.has(route.route)||!size(route.jsBytes))throw new Error('Invalid or duplicate route in bundle analysis.');
+    seen.add(route.route);
+    for(const key of ['gzipBytes','brotliBytes'])if((complete||route[key]!==undefined)&&!size(route[key]))throw new Error(`Invalid ${key} in bundle analysis.`);
+  }
+}
+async function readReport(file){
+  const value=await boundedJson(file,'Bundle analysis');
+  if(!object(value)||value.version!==1||!text(value.buildId)||!size(value.totalJsBytes)||!Array.isArray(value.files)||value.files.length>100000)throw new Error('Invalid bundle analysis; rebuild with this PRNext version.');
+  validateRoutes(value.routes);
+  for(const route of value.routes)if(!Array.isArray(route.files)||route.files.length>100000||route.files.some(file=>!text(file)))throw new Error('Invalid route asset list in bundle analysis.');
+  for(const file of value.files){
+    if(!object(file)||!text(file.file)||!size(file.bytes)||!size(file.gzipBytes)||!size(file.brotliBytes)||!Array.isArray(file.modules)||file.modules.length>100||file.modules.some(module=>!object(module)||!text(module.file)||!size(module.bytes))||!Array.isArray(file.imports)||file.imports.length>100000||file.imports.some(item=>!object(item)||!text(item.file)||!text(item.kind)))throw new Error('Invalid file, module or import in bundle analysis.');
+  }
+  if(value.previous!==undefined){
+    if(!object(value.previous)||!text(value.previous.buildId)||value.previous.totalJsBytes!==undefined&&!size(value.previous.totalJsBytes))throw new Error('Invalid previous bundle analysis.');
+    validateRoutes(value.previous.routes,{complete:false});
+  }
+  // Retain only the versioned schema, rather than echoing arbitrary nested
+  // properties from a supplied baseline into a machine-readable report.
+  const cleanRoute=({route,files,jsBytes,gzipBytes,brotliBytes})=>({route,files,jsBytes,gzipBytes,brotliBytes});
+  return {version:1,buildId:value.buildId,totalJsBytes:value.totalJsBytes,routes:value.routes.map(cleanRoute),
+    files:value.files.map(({file,bytes,gzipBytes,brotliBytes,imports,modules})=>({file,bytes,gzipBytes,brotliBytes,imports:imports.map(({file,kind})=>({file,kind})),modules:modules.map(({file,bytes})=>({file,bytes}))})),
+    ...(value.previous?{previous:{buildId:value.previous.buildId,totalJsBytes:value.previous.totalJsBytes,routes:value.previous.routes.map(({route,jsBytes,gzipBytes,brotliBytes})=>({route,jsBytes,gzipBytes,brotliBytes}))}}:{})};
+}
+function nonnegative(value,name,{integer=false}={}){
+  if(typeof value!=='number'||!Number.isFinite(value)||value<0||value>Number.MAX_SAFE_INTEGER||(integer&&!Number.isSafeInteger(value)))throw new Error(`${name} requires a finite nonnegative ${integer?'integer':'number'}.`);
+  return value;
+}
+export function parseAnalysisArgs(args){
+  const options={};
+  const numeric={'--max-js':'maxJs','--max-increase-bytes':'maxIncreaseBytes','--max-increase-percent':'maxIncreasePercent'};
+  const values={'--baseline':'baseline','--metric':'metric','--budgets':'budgets'};
+  for(let index=0;index<args.length;index++){
+    const flag=args[index],key=Object.hasOwn(numeric,flag)?numeric[flag]:Object.hasOwn(values,flag)?values[flag]:undefined;
+    if(flag==='--json'&&!options.json){options.json=true;continue;}
+    if(!key||options[key]!==undefined)throw new Error(`Unknown or duplicate analyze option: ${flag}`);
+    const value=args[++index];if(!value||value.startsWith('--'))throw new Error(`${flag} requires a value.`);
+    if(Object.hasOwn(numeric,flag)){
+      if(!/^\d+(?:\.\d+)?$/.test(value))throw new Error(`${flag} requires a nonnegative number.`);
+      options[key]=nonnegative(Number(value),flag,{integer:key==='maxIncreaseBytes'});
+    }else options[key]=value;
+  }
+  if(options.metric!==undefined&&!Object.hasOwn(metrics,options.metric))throw new Error('--metric must be raw, gzip or brotli.');
+  return options;
+}
+async function routeBudgets(filename){
+  if(!filename)return {};
+  const value=await boundedJson(filename,'Route budgets');
+  if(!object(value)||Object.keys(value).length>10000)throw new Error('Route budgets must be an object with at most 10,000 route keys.');
+  for(const [route,budget]of Object.entries(value)){
+    if(!text(route)||!route.startsWith('/')||!object(budget)||!Object.keys(budget).length)throw new Error('Each route budget must be a nonempty object keyed by an exact route pattern.');
+    for(const [key,limit]of Object.entries(budget)){
+      if(!['maxJs','maxIncreaseBytes','maxIncreasePercent'].includes(key))throw new Error(`Unknown route budget field: ${key}`);
+      nonnegative(limit,`Budget ${route}.${key}`,{integer:key==='maxIncreaseBytes'});
+    }
+  }
+  return value;
+}
+export async function analyzeBuild(root,{maxJs,baseline,metric='raw',maxIncreaseBytes,maxIncreasePercent,budgets}={}){
+  if(!Object.hasOwn(metrics,metric))throw new Error('Analysis metric must be raw, gzip or brotli.');
+  for(const [key,value]of Object.entries({maxJs,maxIncreaseBytes,maxIncreasePercent}))if(value!==undefined)nonnegative(value,key,{integer:key==='maxIncreaseBytes'});
+  const report=await readReport(path.join(root,await readBuildDirectory(root),'build-analysis.json'));
+  const limits=await routeBudgets(budgets?path.resolve(root,budgets):null);
+  const routeNames=new Set(report.routes.map(route=>route.route));
+  for(const route of Object.keys(limits))if(!routeNames.has(route))throw new Error(`Route budget does not match a current route: ${route}`);
+  const reference=baseline?await readReport(path.resolve(root,baseline)):report.previous;
+  const needsBaseline=maxIncreaseBytes!==undefined||maxIncreasePercent!==undefined||Object.values(limits).some(value=>value.maxIncreaseBytes!==undefined||value.maxIncreasePercent!==undefined);
+  if(needsBaseline&&!reference)throw new Error('Regression budgets require --baseline or a previous build analysis.');
+  const field=metrics[metric],previous=new Map((reference?.routes||[]).map(route=>[route.route,route[field]]));
+  report.metric=metric;
+  report.baseline=reference?{buildId:reference.buildId,source:baseline?'file':'previous-build'}:null;
+  report.routes=report.routes.map(route=>{
+    const budget={maxJs,maxIncreaseBytes,maxIncreasePercent,...(limits[route.route]||{})};
+    const before=previous.get(route.route),current=route[field],hasBaseline=size(before),delta=hasBaseline?current-before:null;
+    const regressionBudget=budget.maxIncreaseBytes!==undefined||budget.maxIncreasePercent!==undefined;
+    const exceeded=[];
+    if(budget.maxJs!==undefined&&current>budget.maxJs*1000)exceeded.push('maxJs');
+    if(regressionBudget&&!hasBaseline)exceeded.push('baseline-missing');
+    if(hasBaseline&&budget.maxIncreaseBytes!==undefined&&delta>budget.maxIncreaseBytes)exceeded.push('maxIncreaseBytes');
+    if(hasBaseline&&budget.maxIncreasePercent!==undefined&&(before===0?delta>0:delta/before*100>budget.maxIncreasePercent))exceeded.push('maxIncreasePercent');
+    return {...route,selectedBytes:current,baselineBytes:hasBaseline?before:null,deltaBytes:delta,deltaPercent:hasBaseline&&before>0?delta/before*100:hasBaseline&&current===0?0:null,
+      comparison:hasBaseline?'compared':reference?'new-or-unavailable':'no-baseline',budget:{...budget,exceeded}};
+  }).sort((a,b)=>b.selectedBytes-a.selectedBytes||a.route.localeCompare(b.route));
+  report.budget={metric,maxJsBytes:maxJs===undefined?null:maxJs*1000,maxIncreaseBytes:maxIncreaseBytes??null,maxIncreasePercent:maxIncreasePercent??null,exceeded:report.routes.filter(route=>route.budget.exceeded.length).map(route=>route.route)};
+  report.ok=report.budget.exceeded.length===0;
+  return report;
+}
+export function printAnalysis(report){
+  const kb=n=>(n/1000).toFixed(1)+' kB';
+  console.log(`PRNext bundle analysis (${report.buildId})\nInitial browser JavaScript per route; shared files counted once per route. Dynamic imports are excluded. Budget metric: ${report.metric||'raw'}.`);
+  for(const route of report.routes)console.log(`${route.route}: ${kb(route.jsBytes)} JS / ${kb(route.gzipBytes)} gzip / ${kb(route.brotliBytes)} br${route.deltaBytes===null?'':` (${route.deltaBytes>=0?'+':''}${kb(route.deltaBytes)} ${report.metric||'raw'} vs baseline${route.deltaPercent===null?'':`, ${route.deltaPercent.toFixed(1)}%`})`}${route.budget?.exceeded.length?` [${route.budget.exceeded.join(', ')}]`:''}`);
+  console.log('\nLargest browser modules (per output chunk):');
+  for(const item of report.files.flatMap(chunk=>chunk.modules.map(module=>({...module,chunk:chunk.file}))).sort((a,b)=>b.bytes-a.bytes).slice(0,10))console.log(`  ${kb(item.bytes)} ${item.file} [${item.chunk}]`);
+  if(report.budget.exceeded.length)console.error(`JavaScript budget exceeded: ${report.budget.exceeded.join(', ')}`);
+}

package/build/app-config.mjs

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { parse } from '@babel/parser';
+import {analyzeSource} from './source-analysis.mjs';
 import {validSamples} from '../compat/instant-samples.cjs';
 import { createHash } from 'node:crypto';
 
@@ -23,19 +23,19 @@ const supported = new Map([
 
 function literal(node) {
   while (['TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'TypeCastExpression'].includes(node?.type)) node = node.expression;
-  if (node?.type === 'NullLiteral') return null;
+  if (node?.type === 'Literal' && node.value === null) return null;
   if (node?.type === 'ArrayExpression') { const values = node.elements.map(literal); return values.includes(undefined) ? undefined : values; }
   if (node?.type === 'ObjectExpression') {
     const output = {};
     for (const item of node.properties) {
-      if (item.type !== 'ObjectProperty' || item.computed || item.shorthand) return undefined;
+      if (item.type !== 'Property' || item.kind !== 'init' || item.method || item.computed || item.shorthand) return undefined;
       const key = item.key.name ?? item.key.value, value = literal(item.value);
       if (typeof key !== 'string' || value === undefined || key === '__proto__') return undefined;
       Object.defineProperty(output, key, { value, enumerable: true });
     }
     return output;
   }
-  return ['StringLiteral', 'BooleanLiteral', 'NumericLiteral'].includes(node?.type) ? node.value : undefined;
+  return node?.type === 'Literal' && ['string','boolean','number'].includes(typeof node.value) ? node.value : undefined;
 }
 
 export async function validateAppConfig(file) {
@@ -48,8 +48,7 @@ export async function validateAppConfig(file) {
   }
   parsedMisses++;
   if (hit) { parsedConfigs.delete(file); parsedBytes -= hit.size; }
-  const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: file,
-    plugins: ['jsx', ...(/\.tsx?$/.test(file) ? ['typescript'] : [])] });
+  const analysis=analyzeSource(source,file), ast={program:analysis.program};
   const locals = new Map();
   const exports = [];
   for (const statement of ast.program.body) {
@@ -71,11 +70,11 @@ export async function validateAppConfig(file) {
     const value = locals.get(item.local);
     const allowed = supported.get(item.name);
     if (item.name === 'instant') {
-      if (ast.program.directives.some(directive => directive.value.value === 'use client')) throw new Error(`instant cannot be exported by a Client Component (${file}).`);
+      if (analysis.directives.includes('use client')) throw new Error(`instant cannot be exported by a Client Component (${file}).`);
       if (value && typeof value === 'object' && Object.entries(value).every(([name, value]) => name === 'unstable_samples' ? validSamples(value) : name === 'level' ? ['warning', 'experimental-error'].includes(value) : ['unstable_disableValidation', 'unstable_disableDevValidation', 'unstable_disableBuildValidation'].includes(name) && value === true)) { config.instant = value; continue; }
     }
     if (item.name === 'generateStaticParams') {
-      if (ast.program.directives.some(directive => directive.value.value === 'use client')) throw new Error(`generateStaticParams cannot be exported by a Client Component (${file}).`);
+      if (analysis.directives.includes('use client')) throw new Error(`generateStaticParams cannot be exported by a Client Component (${file}).`);
       config.generateStaticParams = true;
       continue;
     }

package/build/app-static.mjs

@@ -3,6 +3,7 @@ import { writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { staticPath } from '../runtime/pages-paths.mjs';
+import {mapConcurrent} from './concurrent.mjs';
 
 const MAX_STATIC_PATHS = 10_000;
 const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
@@ -48,7 +49,8 @@ export async function prerenderApp(stage, manifest, dev) {
       ? await import(pathToFileURL(path.join(stage, 'runtime/app-static.mjs')).href) : null;
     const handlers = routes.some(route => route.kind === 'api')
       ? await import(pathToFileURL(path.join(stage, 'runtime/route-static.mjs')).href) : null;
-    for (const route of routes) {
+    const initialSeeds=[...manifest.prerendered];
+    await mapConcurrent(routes,async route=>{
       const handler = route.kind === 'api';
       const options = { modulePath: path.join(stage, route.module), distDir: stage, manifest, route, production: true };
       // This fixed internal entry shares the root layout, but its parameter
@@ -64,7 +66,7 @@ export async function prerenderApp(stage, manifest, dev) {
       // while separating dynamic rendering from the persistent Data Cache.
       if (config.runtime === 'edge') {
         if (dynamic && config.dynamicParams === false) route.allowedPaths = entries.map(entry => entry.path);
-        continue;
+        return;
       }
       const partial = !handler && manifest.config?.cacheComponents === true && (!config.dynamic || config.dynamic === 'auto');
       if (partial && dynamic && !inspected.generated) entries.length = 0;
@@ -99,16 +101,17 @@ export async function prerenderApp(stage, manifest, dev) {
       if (partial) route.pprFallback = config.dynamicParams !== false;
       if (dynamic && config.dynamicParams === false) route.allowedPaths = entries.map(entry => entry.path);
       if (handler) {
-        if (!inspected.staticEligible) continue;
-        if (dynamic && !inspected.generated && !['force-static', 'error'].includes(config.dynamic)) continue;
+        if (!inspected.staticEligible) return;
+        if (dynamic && !inspected.generated && !['force-static', 'error'].includes(config.dynamic)) return;
       } else {
-        if (config.dynamic === 'force-dynamic' || (config.dynamic !== 'force-static' && (config.revalidate === 0 || config.forceNoStore))) continue;
-        if (dynamic && !inspected.generated && !partial && !['force-static', 'error'].includes(config.dynamic)) continue;
+        if (config.dynamic === 'force-dynamic' || (config.dynamic !== 'force-static' && (config.revalidate === 0 || config.forceNoStore))) return;
+        if (dynamic && !inspected.generated && !partial && !['force-static', 'error'].includes(config.dynamic)) return;
       }
       route.ssg = true;
       route.fallback = config.dynamicParams === false ? false : 'blocking';
       for (const entry of entries) {
         if (occupied.has(entry.path)) throw new Error(`Multiple pages prerender the same path: ${entry.path}.`);
+        occupied.add(entry.path);
         const rendered = await (handler ? handlers.prerenderAppRouteHandler : pages.prerenderAppRoute)({ ...options, path: entry.path, params: entry.params });
         if (rendered.partial) {
           const file = `static/partial-${createHash('sha256').update(entry.path).digest('hex').slice(0, 20)}.json`;
@@ -155,6 +158,8 @@ export async function prerenderApp(stage, manifest, dev) {
           route.ssg = true; route.fallback = 'ppr';
         } else { delete route.ssg; delete route.fallback; }
       }
-    }
+    });
+    const appSeeds=manifest.prerendered.slice(initialSeeds.length);
+    manifest.prerendered=[...initialSeeds,...routes.flatMap(route=>appSeeds.filter(seed=>seed.routeId===route.id))];
   } finally { await closeAppRuntime(); }
 }

package/build/app.mjs

@@ -1,6 +1,6 @@
-import {frameworkImportName, frameworkRuntimeImportPattern, frameworkSubpathPattern} from './framework-imports.mjs';
+import {applicationEntry, frameworkImportName, frameworkRuntimeImportPattern, frameworkSubpathPattern} from './framework-imports.mjs';
 import { moduleResolutionPlugin } from './module-resolution.mjs';
-import { build as bundle, compilerSource } from './compiler.mjs';
+import { build as bundle, compilerSource,readCompilerFile } from './compiler.mjs';
 import { readFile, writeFile, mkdir, cp, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
@@ -14,7 +14,7 @@ import { createServerActions } from './actions.mjs';
 import { expandActionExports } from './action-exports.mjs';
 import { compileEdge } from './edge.mjs';
 import { createNativePackages } from './native-packages.mjs';
-import { createRefreshTransform, devSingletonsPlugin, devClientFile } from './dev.mjs';
+import { createRefreshTransform, createSourceLocationTransform, devSingletonsPlugin, devClientFile } from './dev.mjs';
 import { npmPackagesPlugin } from './npm-packages.mjs';
 import { transformCacheComponents } from './cache-components.mjs';
 
@@ -174,7 +174,8 @@ function routeEntry(route, globalError, dev) {
 
 /** Compile independent React Server and client graphs. The RSC graph contains only references to client boundaries. */
 export async function compileApp({ project, stage, manifest, cssModules, fonts, images, dev, defineEnvironment = {}, productionBrowserSourceMaps = false, serverExternalPackages = [], moduleResolution = {} }) {
-  const refresh = dev ? createRefreshTransform(project.root) : undefined;
+  const refresh = dev ? createRefreshTransform(project.root, {generation:manifest.cacheId,forceGeneration:manifest.devForceRefresh,forceFiles:manifest.devAffectedModules}) : undefined;
+  const locations = dev ? createSourceLocationTransform(project.root) : undefined;
   const { basePath = '', assetPrefix = '', assetBase = '/_prnext/assets', trailingSlash = false, skipTrailingSlashRedirect = false } = manifest.config || {};
   const publicPath = assetBase + '/';
   const routes = project.routes.filter(route => route.router === 'app');
@@ -234,6 +235,7 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
     return {
       name: `prnext-app-${mode}`,
       setup(esbuild) {
+        applicationEntry(esbuild,readCompilerFile);
         esbuild.onResolve({ filter: /^prnext-internal:use-cache$/ }, () => browser
           ? { errors: [{ text: "'use cache' cannot enter a Client Component graph" }] }
           : { path: '../compat/use-cache.cjs', external: true });
@@ -296,7 +298,8 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
         }
         esbuild.onLoad({ filter: /\.(?:[cm]?js|jsx|tsx?)$/, namespace: 'file' }, async args => {
           if (browser && args.path === project.document) return { errors: [{ text: 'pages/_document is server-only and cannot be imported by a Client Component.' }] };
-          const source = await fonts.transform(await expandActionExports(args.prnextSource ?? await readFile(args.path, 'utf8'), args.path, async (specifier, importer) => {
+          const original=await readCompilerFile(args.path,args.prnextSource);
+          const source = await fonts.transform(await expandActionExports(locations?await locations(original,args.path):original, args.path, async (specifier, importer) => {
             const resolved = await esbuild.resolve(specifier, { resolveDir: path.dirname(importer), kind: 'import-statement', pluginData: { prnextExportScan: true } });
             return resolved.errors.length || resolved.external || resolved.namespace !== 'file' ? undefined : resolved.path;
           }), args.path);
@@ -315,7 +318,7 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
             return { contents: `import {registerClientReference} from 'react-server-dom-webpack/server';\n${references.join('\n')}`, loader: 'js', resolveDir: path.dirname(args.path) };
           }
           let contents = transformDynamicImports(actionSource, args.path, { projectRoot: project.root, mode: rsc ? 'rsc' : browser ? 'browser' : 'server' });
-          if (browser && refresh) contents = await refresh(contents, args.path);
+          if (browser && refresh && !actions.isServerModule(cachedSource,args.path)) contents = await refresh(contents, args.path);
           return { contents, loader: extensions[path.extname(args.path)] || 'jsx', resolveDir: path.dirname(args.path) };
         });
       },
@@ -331,6 +334,7 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
     const rsc = mode === 'rsc';
     const framework = new Set(['link', 'image', 'head', 'router', 'compat-router', 'next-router-context', 'next-app-router-context', 'navigation', 'script', 'app-context', 'app-layout-context', 'app-navigation-boundary', 'app-client-page', 'app-error-boundary', 'app-dynamic']);
     return { name: 'prnext-edge-app', setup(esbuild) {
+      applicationEntry(esbuild,readCompilerFile);
       esbuild.onResolve({filter:/^prnext-internal:action-(?:crypto|ssr)$/}, args => ({path:args.path.slice('prnext-internal:'.length),namespace:'prnext-edge-action'}));
       esbuild.onLoad({filter:/.*/,namespace:'prnext-edge-action'}, args => ({loader:'js',contents:(args.path==='action-crypto'?['encryptBoundArgs','decryptBoundArgs','bindEncryptedReference']:['createServerReference']).map(name=>`export const ${name}=globalThis.__PRNEXT_EDGE_ACTIONS[${JSON.stringify(args.path)}][${JSON.stringify(name)}];`).join('\n')}));
       esbuild.onResolve({ filter: frameworkSubpathPattern }, args => {
@@ -375,7 +379,7 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
   async function edgeAppBuild(file, outfile, mode, defaultExport = false) {
     const result = await compileEdge({ file, outfile, projectRoot: project.root, dev, defineEnvironment, reactMode: mode, defaultExport,
       plugins: [moduleResolutionPlugin(moduleResolution, project.root), edgeGraphPlugin(mode), images.plugin(), fonts.plugin(), cssModules.plugin(false)],
-      transformSource: async (source, file, builder) => actionTransform(await fonts.transform(await expandActionExports(source, file, async (specifier, importer) => {
+      transformSource: async (source, file, builder) => actionTransform(await fonts.transform(await expandActionExports(locations?await locations(source,file):source, file, async (specifier, importer) => {
         const resolved = await builder.resolve(specifier, {resolveDir:path.dirname(importer),kind:'import-statement',pluginData:{prnextExportScan:true}});
         return resolved.errors.length || resolved.external || resolved.namespace !== 'file' ? undefined : resolved.path;
       }), file), file, mode, 'edge') });
@@ -481,11 +485,16 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
   }
   manifest.app = { clientModules: {}, actions: {}, actionKey: actions.actionKey };
   const actionRevision = () => [...actions.actions.values()].map(action=>action.id+':'+[...(action.runtimes || [])].sort().join(',')).join(';');
+  const boundaryRevision = () => [...boundaries.values()].map(boundary=>boundary.id+':'+!!boundary.edge).join(';');
+  const browserRevision = () => `${boundaryRevision()}:${cssFiles.size}:${globalErrorCssFiles.size}:${nativePackages.version}`;
   // Route Handlers have a Node React environment and must not share RSC chunks
   // that import registerServerReference or client-reference registration.
   await serverBuild(handlerEntries, 'server', 'route');
   for (;;) {
-    const revision = `${actionRevision()}:${boundaries.size}:${cssFiles.size}:${globalErrorCssFiles.size}`;
+    // Each graph consumes discoveries from the preceding one. Discovering a
+    // client boundary in RSC is normal: SSR and browser below already include
+    // it. Only discoveries made too late for a graph require another pass.
+    const emittedActions = actionRevision();
     for (const action of actions.actions.values()) {
       const entry = path.join(stage, '.entries', 'action-' + action.id + '.mjs');
       await writeFile(entry, `export {${JSON.stringify(action.binding)} as invoke} from ${JSON.stringify(action.file)};`);
@@ -493,6 +502,8 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
       if (!action.runtimes?.size || action.runtimes.has('nodejs')) entries['action-' + action.id] = entry;
     }
     await serverBuild(entries, 'server', 'rsc');
+    const serverNativeVersion = nativePackages.version;
+    const emittedBoundaries = boundaryRevision();
     const ssrEntries = {};
     const globalSsrEntries = {};
     for (const boundary of boundaries.values()) {
@@ -512,6 +523,7 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
     await collectBrowserStyles(browserEntries);
     globalErrorOnlyCss.clear();
     for (const file of globalErrorCssFiles) if (!cssFiles.has(file)) globalErrorOnlyCss.add(file);
+    const emittedBrowserInputs = browserRevision();
     if (routes.some(route => route.kind === 'page')) {
     let globalErrorCss = [];
     if (globalErrorCssFiles.size) {
@@ -525,7 +537,7 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
     if (globalErrorId) manifest.app.globalError = { id: globalErrorId, name: 'default', css: globalErrorCss };
     const runtimeEntry = path.join(stage, '.entries', 'app-runtime.mjs');
     const importers = Object.entries(browserEntries).map(([id, file]) => `${JSON.stringify(id)}:()=>import(${JSON.stringify(file)})`);
-    await writeFile(runtimeEntry, `${dev ? `import ${JSON.stringify(devClientFile)};\n` : ''}${[...cssFiles].map(file => `import ${JSON.stringify(file)};`).join('\n')}\nimport {bootstrapApp} from ${JSON.stringify(path.join(packageRoot, 'runtime/app-client.mjs'))};\nbootstrapApp({clientModules:{${importers.join(',')}},...${JSON.stringify({ basePath, assetPrefix, assetBase, trailingSlash, skipTrailingSlashRedirect, strictMode: manifest.config.reactStrictMode !== false, cacheComponents: manifest.config.cacheComponents === true, ...(globalErrorId ? { globalErrorId, globalErrorCss } : {}), ...(dev ? { dev: { buildId: manifest.buildId, clientManifest: manifest.devClient } } : {}) })}});\n`);
+    await writeFile(runtimeEntry, `${dev ? `import ${JSON.stringify(devClientFile)};\n` : ''}${[...cssFiles].map(file => `import ${JSON.stringify(file)};`).join('\n')}\nimport {bootstrapApp} from ${JSON.stringify(path.join(packageRoot, 'runtime/app-client.mjs'))};\nbootstrapApp({clientModules:{${importers.join(',')}},...${JSON.stringify({ basePath, assetPrefix, assetBase, trailingSlash, skipTrailingSlashRedirect, strictMode: manifest.config.reactStrictMode !== false, cacheComponents: manifest.config.cacheComponents === true, ...(globalErrorId ? { globalErrorId, globalErrorCss } : {}), ...(dev ? { dev: { buildId: manifest.buildId, clientManifest: manifest.devClient, onDemand:manifest.devOnDemand===true, sequence:manifest.devSequence, session:manifest.devSession, indicator:manifest.devIndicators, ...(manifest.devTools ? {tools:manifest.devTools} : {}) } } : {}) })}});\n`);
     const clientEntries = { 'app-runtime': runtimeEntry, ...browserEntries };
     const browser = await bundle({ ...common, entryPoints: clientEntries, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', chunkNames: 'app-chunk-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], splitting: true, minify: !dev, sourcemap: dev || productionBrowserSourceMaps,
       define: { 'process.env': '{}', ...common.define }, plugins: [moduleResolutionPlugin(moduleResolution, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), graphPlugin('browser'), nativePackages.plugin('browser'), cssModules.plugin(true, { emitStyles: file => !globalErrorOnlyCss.has(file) })] });
@@ -548,7 +560,8 @@ export async function compileApp({ project, stage, manifest, cssModules, fonts,
       module: `server/action-${action.runtimes?.has('nodejs')?'':'edge-'}${action.id}.mjs`, export: 'invoke',
       ...(action.runtimes?.has('edge') ? {edgeModule:`server/action-edge-${action.id}.mjs`} : {}),
     }]));
-    if (revision === `${actionRevision()}:${boundaries.size}:${cssFiles.size}:${globalErrorCssFiles.size}`) break;
+    if (emittedActions === actionRevision() && emittedBoundaries === boundaryRevision() &&
+        serverNativeVersion === nativePackages.version && emittedBrowserInputs === browserRevision()) break;
   }
 
 }

package/build/build-lock.mjs

@@ -11,7 +11,7 @@ function alive(pid) {
 }
 async function owner(directory) {
   const info = await lstat(directory);
-  if (!info.isDirectory() || info.isSymbolicLink()) throw busy('The build lock is not a real directory. Check .prnext-build.lock before retrying.');
+  if (!info.isDirectory() || info.isSymbolicLink()) throw busy(`The project lock is not a real directory. Check ${path.basename(directory)} before retrying.`);
   const file = await open(path.join(directory, 'owner.json'), 'r');
   try {
     if ((await file.stat()).size > 4096) throw new Error('oversized owner');
@@ -22,8 +22,8 @@ async function owner(directory) {
 }
 
 /** One publisher per canonical project, covering React and direct static imports. */
-export async function withBuildLock(directory, action) {
-  const root = await realpath(directory), lock = path.join(root, LOCK);
+export async function withBuildLock(directory, action, {development = false} = {}) {
+  const root = await realpath(directory), lock = path.join(root, development ? '.prnext-dev.lock' : LOCK);
   const identity = { pid: process.pid, host: hostname(), token: randomUUID(), createdAt: new Date().toISOString() };
   const prepared = path.join(root, `.prnext-lock-${identity.token}`);
   await mkdir(prepared, { mode: 0o700 });
@@ -37,16 +37,16 @@ export async function withBuildLock(directory, action) {
         try { previous = await owner(lock); }
         catch (cause) {
           if (cause.code === 'ENOENT' && attempt < 8) continue;
-          throw busy('Cannot verify the build lock. Check .prnext-build.lock before retrying.');
+          throw busy(`Cannot verify the project lock. Check ${path.basename(lock)} before retrying.`);
         }
-        if (previous.host !== identity.host || alive(previous.pid)) throw busy(`A build is already running for this project (PID ${previous.pid}). Wait for it to finish.`);
+        if (previous.host !== identity.host || alive(previous.pid)) throw busy(development ? `A development server is already running for this project (PID ${previous.pid}). Stop it before starting another.` : `A build is already running for this project (PID ${previous.pid}). Wait for it to finish.`);
         // Exactly one contender can recover this generation. Never delete a lock
         // merely because it is old: long builds and suspended processes are valid.
         let claim;
         try { claim = await open(path.join(lock, 'recovery'), 'wx', 0o600); }
         catch (cause) {
           if (cause.code === 'ENOENT' && attempt < 8) continue;
-          throw busy('Build lock recovery is in progress. Retry shortly; if recovery was interrupted, check .prnext-build.lock manually.');
+          throw busy(`Project lock recovery is in progress. Retry shortly; if recovery was interrupted, check ${path.basename(lock)} manually.`);
         }
         const retired = path.join(root, `.prnext-lock-retired-${identity.token}`);
         try {

package/build/bundle-runtime.mjs

@@ -1,6 +1,9 @@
 import { build } from 'esbuild';
-import { lstat, realpath, readdir, writeFile, unlink } from 'node:fs/promises';
+import { lstat, realpath, readdir, writeFile, unlink,readFile } from 'node:fs/promises';
 import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {version as esbuildVersion} from 'esbuild';
+import {privateCacheDirectory,readCacheRecord,writeCacheRecord} from './persistent-cache.mjs';
 
 // Paths used by the native worker, generated application modules, prerender,
 // standalone tracing, compatibility modules and the runtime lifecycle contract.
@@ -12,7 +15,7 @@ export const runtimeEntryNames = Object.freeze([
 ].sort());
 
 /** Run once, after compiling application/Edge graphs and before any prerender. */
-export async function bundleRuntime(stage) {
+export async function bundleRuntime(stage,{projectRoot}={}) {
   const resolvedStage = path.resolve(stage);
   if (!path.basename(resolvedStage).startsWith('.prnext-build-')) {
     throw new Error('Runtime bundling requires an unpublished PRNext build stage.');
@@ -34,11 +37,21 @@ export async function bundleRuntime(stage) {
   for (const name of runtimeEntryNames) {
     if (!originals.some(entry => entry.name === `${name}.mjs`)) throw new Error(`Missing runtime entry ${name}.mjs`);
   }
+  let directory,key,cached;
+  if(projectRoot){
+    directory=await privateCacheDirectory(projectRoot,'runtime-bundle-v1');
+    if(directory){
+      const hash=createHash('sha256').update(esbuildVersion).update(JSON.stringify(runtimeEntryNames)).update(await readFile(new URL('./bundle-runtime.mjs',import.meta.url)));
+      for(const entry of [...originals].sort((a,b)=>a.name.localeCompare(b.name)))hash.update(JSON.stringify([entry.name,createHash('sha256').update(await readFile(path.join(runtime,entry.name))).digest('hex')]));
+      key=hash.digest('hex');cached=await readCacheRecord(directory,key);
+    }
+  }
   // write:false makes compilation atomic with respect to the source runtime:
   // no files change if parsing or resolution fails. The virtual output is a
   // sibling so all relative paths have the same depth as the final runtime.
   const virtualOutput = path.join(resolvedStage, '.runtime-bundle');
-  const result = await build({
+  const validCache=cached&&Array.isArray(cached.files)&&cached.files.length<=128&&cached.files.every(item=>Array.isArray(item)&&item.length===2&&/^[\w-]+\.mjs$/.test(item[0])&&typeof item[1]==='string')&&new Set(cached.files.map(([name])=>name)).size===cached.files.length&&runtimeEntryNames.every(name=>cached.files.some(([file])=>file===name+'.mjs'));
+  const result = validCache?null:await build({
     absWorkingDir: runtime,
     entryPoints: runtimeEntryNames.map(name => path.join(runtime, `${name}.mjs`)),
     outdir: virtualOutput,
@@ -62,13 +75,15 @@ export async function bundleRuntime(stage) {
     logLevel: 'silent',
   });
   const emitted = new Map();
-  for (const file of result.outputFiles) {
+  if(validCache)for(const [name,contents]of cached.files)emitted.set(name,Buffer.from(contents));
+  for (const file of result?.outputFiles||[]) {
     if (path.dirname(file.path) !== virtualOutput || !file.path.endsWith('.mjs')) {
       throw new Error('Runtime bundler emitted a file outside its flat output directory.');
     }
     emitted.set(path.basename(file.path), file.contents);
   }
   if (runtimeEntryNames.some(name => !emitted.has(`${name}.mjs`))) throw new Error('Runtime bundle omitted a required entry.');
+  if(directory&&!validCache)await writeCacheRecord(directory,key,{files:[...emitted].map(([name,bytes])=>[name,Buffer.from(bytes).toString()])});
   // This is an unpublished, disposable stage. On any write failure buildProject
   // discards the stage and preserves the previous published build unchanged.
   for (const [name, contents] of emitted) await writeFile(path.join(runtime, name), contents);
@@ -77,6 +92,6 @@ export async function bundleRuntime(stage) {
   }
   // JSON, CJS, license files and the OG assets directory are never traversed or
   // removed. The caller writes the normal runtime contract after prerender.
-  return { entryCount: runtimeEntryNames.length, moduleCount: emitted.size,
+  return { entryCount: runtimeEntryNames.length, moduleCount: emitted.size,cached:!!validCache,
     bytes: [...emitted.values()].reduce((sum, contents) => sum + contents.length, 0) };
 }