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

package/build/actions.mjs

@@ -44,7 +44,7 @@ export function createServerActions({ projectRoot }) {
       const id=createHmac('sha256',templateSalt).update(name).digest('hex');
       registrations.push({name,binding,id});return id;
     }
-    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']:[])]});
     const moduleServer=hasDirective(ast.program,'use server');
     const moduleClient=hasDirective(ast.program,'use client');
     if(moduleServer&&moduleClient) throw new Error(`A module cannot use both 'use client' and 'use server': ${file}`);

package/build/analyze.mjs

@@ -5,12 +5,23 @@ import {gzip,brotliCompress,constants} from 'node:zlib';
 import {promisify} from 'node:util';
 import {mapConcurrent} from './concurrent.mjs';
 import {readBuildDirectory} from '../runtime/build-directory.mjs';
+import {fileURLToPath} from 'node:url';
+
+// These imports are awaited before App hydration. esbuild correctly describes
+// them as dynamic imports, but they are not deferred by user interaction.
+const appClient=fileURLToPath(new URL('../runtime/app-client.mjs',import.meta.url));
+const hydrationImports=new Map([
+  ['react-server-dom-webpack/client.browser','always'],
+  ['./app-partial-client.mjs','cache-components'],
+]);
 
 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]));
+  const working=options.absWorkingDir||state.root;
+  const entries=new Map([...outputs].filter(([,info])=>info.entryPoint).map(([file,info])=>[path.resolve(working,info.entryPoint),file]));
   for(const [absolute,info] of outputs){
     const relative=path.relative(state.stage,absolute).replaceAll(path.sep,'/');
     if(!info.entryPoint||!relative.startsWith('server/'))continue;
@@ -27,15 +38,78 @@ export function recordBuildAnalysis(state,options,result){
     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})),
+    const imports=(info.imports||[]).filter(item=>!item.external).map(item=>({file:path.relative(path.join(state.stage,'assets'),path.resolve(working,item.path)).replaceAll(path.sep,'/'),kind:item.kind}));
+    for(const name of Object.keys(info.inputs||{})){
+      const source=path.resolve(working,name);
+      for(const input of result.metafile.inputs[name]?.imports||[]){
+        if(input.kind!=='dynamic-import'||input.external)continue;
+        const target=entries.get(path.resolve(working,input.path));if(!target)continue;
+        const asset=relativeAsset(state.stage,target);
+        const edge=imports.find(item=>item.file===asset&&item.kind==='dynamic-import');
+        if(!edge)continue;
+        const id='dynamic-'+createHash('sha256').update(relativePath(state.root,source)+'\0'+input.original).digest('hex').slice(0,20);
+        (edge.dynamicIds||=[]).push(id);
+        if(source===appClient&&hydrationImports.has(input.original))edge.initial=hydrationImports.get(input.original);
+        else if(source===path.join(state.stage,'.entries','app-runtime.mjs'))edge.initial='flight-reference';
+      }
+    }
+    for(const edge of imports)if(edge.dynamicIds)edge.dynamicIds=[...new Set(edge.dynamicIds)].sort();
+    state.analysis.set(relative,{file:relative,bytes:info.bytes,imports,...(result.metafile.initialGraphComplete===false?{initialIncomplete:true}:{}),
       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){
+function relativePath(root,file){return path.relative(root,file).replaceAll(path.sep,'/');}
+function relativeAsset(stage,file){return relativePath(path.join(stage,'assets'),file);}
+function initialFiles(entry,files,cacheComponents=false){
   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);}
+  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'||item.initial==='always'||item.initial==='cache-components'&&cacheComponents)pending.push(item.file);}
   return [...seen].sort();
 }
+
+async function initialSample(stage,seed,route,manifest){
+  // These documents were validated before publication and intentionally have
+  // no Flight sidecar. Its absence is exact zero JS, not missing coverage.
+  if(route.htmlOnly)return {entries:[],ids:[]};
+  if(route.router==='app'){
+    if(!seed.dataFile)return null;
+    const data=await readBoundedText(path.join(stage,seed.dataFile));
+    if(data===null)return null;
+    const entries=[],rows=new Map(),imports=[];
+    // Read only official import rows; do not execute, decode or rewrite Flight.
+    for(const line of data.split('\n')){
+      // Flight also carries length-framed raw/binary rows. Their bytes may
+      // contain newlines that resemble import rows; do not parse such a stream
+      // as newline-delimited JSON or claim complete hydration coverage for it.
+      if(/^[\da-f]+:[TAOobUSsLlGgMmV]/.test(line))return null;
+      const row=/^([\da-f]+):(I?)(.*)$/.exec(line);if(!row)continue;
+      let value;try{value=JSON.parse(row[3]);}catch{if(row[2])return null;continue;}
+      if(row[2])imports.push(value);else if(typeof value==='string')rows.set(row[1],value);
+    }
+    for(const value of imports){
+      const reference=value?.[0];
+      const id=typeof reference==='string'&&/^\$[\da-f]+$/.test(reference)?rows.get(reference.slice(1)):reference;
+      const module=manifest.app?.clientModules?.[id]?.browserModule;
+      if(!module)return null;
+      entries.push(assetName(module));
+    }
+    return {entries,ids:[]};
+  }
+  const html=await readBoundedText(path.join(stage,seed.file));
+  if(html===null)return null;
+  const match=/window\.__PRNEXT_DATA__=JSON\.parse\(("(?:\\.|[^"\\])*")\);/.exec(html);
+  if(!match)return null;
+  try{const value=JSON.parse(JSON.parse(match[1]));return Array.isArray(value.dynamicIds)?{entries:[],ids:value.dynamicIds}:null;}catch{return null;}
+}
+async function readBoundedText(file){
+  const handle=await open(file,'r');try{
+    const info=await handle.stat(),size=info.size;if(!info.isFile()||size>16*1024*1024)return null;
+    const data=Buffer.alloc(size+1);let length=0;
+    while(length<data.length){const result=await handle.read(data,length,data.length-length,null);if(!result.bytesRead)break;length+=result.bytesRead;}
+    if(length>size)return null;
+    return data.subarray(0,length).toString('utf8');
+  }finally{await handle.close();}
+}
+function assetName(url){return decodeURIComponent(new URL(url,'http://local').pathname).split('/').pop();}
 const gzipAsync=promisify(gzip),brotliAsync=promisify(brotliCompress);
 export async function writeBuildAnalysis({root,stage,destination,manifest,records,routeInputs,precompressed=false}){
   const files=new Map(records||[]);
@@ -51,19 +125,53 @@ export async function writeBuildAnalysis({root,stage,destination,manifest,record
     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]:[];
+  const dynamicEntries=new Map();
+  for(const info of files.values())for(const edge of info.imports)for(const id of edge.dynamicIds||[]){
+    if(!dynamicEntries.has(id))dynamicEntries.set(id,new Set());dynamicEntries.get(id).add(edge.file);
+  }
+  const seedsByRoute=new Map();
+  for(const seed of manifest.prerendered||[])if(!seed.status||seed.status<300){
+    if(!seedsByRoute.has(seed.routeId))seedsByRoute.set(seed.routeId,[]);seedsByRoute.get(seed.routeId).push(seed);
+  }
+  const routes=await mapConcurrent(manifest.routes.filter(route=>!route.internal&&route.kind==='page'),async route=>{
+    const client=route.client?assetName(route.client):null;
+    const baseEntries=client?[client]:[];
+    const initialAssets=entries=>[...new Set(entries.flatMap(entry=>initialFiles(entry,files,manifest.config?.cacheComponents)))].sort();
+    const costs=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 potential=[];
     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());
+      if(entry)potential.push(assetName(entry));
+    }
+    const seeds=seedsByRoute.get(route.id)||[];
+    const samples=[];let failedSample=false;
+    for(const seed of seeds){
+      const sample=await initialSample(stage,seed,route,manifest);
+      if(!sample){failedSample=true;continue;}
+      const entries=[...baseEntries,...sample.entries];
+      for(const id of sample.ids)entries.push(...dynamicEntries.get(id)||[]);
+      const assets=initialAssets(entries);
+      samples.push({path:seed.path,files:assets,...costs(assets)});
     }
-    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)};
+    // A route graph cannot reveal which conditional components request data
+    // selects. Never turn its lower bound into a successful initial-JS budget.
+    const runtime=route.ssp||route.gip||route.appGip||route.ppr||route.pprGeneric||
+      route.pattern.includes('[')&&route.fallback!==false||seeds.some(seed=>typeof seed.revalidate==='number');
+    const baseFiles=[...new Set([...initialAssets(baseEntries),...samples.flatMap(sample=>sample.files)])].sort();
+    const hasDynamic=(samples.length?samples:[{files:baseFiles}]).some(sample=>{
+      const known=new Set(sample.files);
+      return sample.files.some(file=>files.get(file).imports.some(edge=>edge.kind==='dynamic-import'&&!edge.initial&&!known.has(edge.file)));
+    });
+    const unknown=!!runtime||failedSample||(!samples.length&&potential.length>0)||hasDynamic||baseFiles.some(file=>files.get(file).initialIncomplete);
+    const values=samples.length?samples:[costs(baseFiles)];
+    // Route files are a union for inspection. Each budget metric is the actual
+    // largest sampled path, never the sum of mutually exclusive path chunks.
+    return {route:route.pattern,files:baseFiles,initial:{status:unknown?'request-dependent':samples.length?'prerendered':'static-graph',samplePaths:samples.map(sample=>sample.path),samples},
+      ...Object.fromEntries(['jsBytes','gzipBytes','brotliBytes'].map(key=>[key,Math.max(...values.map(value=>value[key]))]))};
   });
-  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.');}
+  const report={version:2,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'));if(previous.version===2)report.previous={version:2,buildId:previous.buildId,totalJsBytes:previous.totalJsBytes,routes:previous.routes.map(({route,initial,jsBytes,gzipBytes,brotliBytes})=>({route,initial,jsBytes,gzipBytes,brotliBytes}))};else report.comparisonUnavailable='Initial asset accounting changed; rebuild the baseline with this PRNext version.';}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;
 }
@@ -90,26 +198,67 @@ function validateRoutes(routes,{complete=true}={}){
     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.`);
+    if(route.initial!==undefined){
+      const initial=route.initial;
+      if(!object(initial)||!['prerendered','static-graph','request-dependent'].includes(initial.status)||!Array.isArray(initial.samplePaths)||initial.samplePaths.length>10000||initial.samplePaths.some(value=>!text(value))||!Array.isArray(initial.samples)||initial.samples.length>10000)throw new Error('Invalid initial asset coverage in bundle analysis.');
+      for(const sample of initial.samples)if(!object(sample)||!text(sample.path)||!Array.isArray(sample.files)||sample.files.length>100000||sample.files.some(file=>!text(file))||['jsBytes','gzipBytes','brotliBytes'].some(key=>!size(sample[key])))throw new Error('Invalid initial asset sample in bundle analysis.');
+    }
+  }
+}
+function validateInitialTotals(value){
+  const files=new Map();
+  for(const file of value.files){if(files.has(file.file))throw new Error('Duplicate asset in bundle analysis.');files.set(file.file,file);}
+  const fields={jsBytes:'bytes',gzipBytes:'gzipBytes',brotliBytes:'brotliBytes'};
+  const sum=(names,key)=>names.reduce((total,name)=>{
+    const file=files.get(name);if(!file)throw new Error('Unknown asset in initial bundle analysis.');
+    const result=total+file[fields[key]];if(!size(result))throw new Error('Initial asset totals exceed the supported range.');return result;
+  },0);
+  const unique=names=>new Set(names).size===names.length;
+  for(const route of value.routes){
+    if(!unique(route.files))throw new Error('Duplicate route asset in bundle analysis.');
+    const routeFiles=new Set(route.files);
+    const {initial}=route,samples=initial.samples;
+    if(!unique(initial.samplePaths)||initial.samplePaths.length!==samples.length||samples.some((sample,index)=>sample.path!==initial.samplePaths[index]))throw new Error('Initial sample paths do not match their measurements.');
+    if(initial.status==='prerendered'&&!samples.length||initial.status==='static-graph'&&samples.length)throw new Error('Invalid initial sample coverage status.');
+    for(const name of route.files)if(!files.has(name))throw new Error('Unknown route asset in bundle analysis.');
+    for(const sample of samples){
+      if(!unique(sample.files)||sample.files.some(file=>!routeFiles.has(file)))throw new Error('Invalid or duplicate sampled asset in bundle analysis.');
+      for(const key of Object.keys(fields))if(sum(sample.files,key)!==sample[key])throw new Error('Initial sample totals do not match their assets.');
+    }
+    const union=new Set(samples.flatMap(sample=>sample.files));
+    if(samples.length&&(union.size!==route.files.length||route.files.some(file=>!union.has(file))))throw new Error('Route asset union does not match its initial samples.');
+    for(const key of Object.keys(fields)){
+      const expected=samples.length?Math.max(...samples.map(sample=>sample[key])):sum(route.files,key);
+      if(expected!==route[key])throw new Error('Initial route totals do not match their samples.');
+    }
+    if(initial.status!=='request-dependent'&&route.files.some(file=>files.get(file).initialIncomplete))throw new Error('Incomplete metadata cannot have exact initial asset coverage.');
   }
 }
 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.');
+  if(!object(value)||![1,2].includes(value.version)||!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(!object(file)||!text(file.file)||!size(file.bytes)||!size(file.gzipBytes)||!size(file.brotliBytes)||file.initialIncomplete!==undefined&&typeof file.initialIncomplete!=='boolean'||!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)||item.initial!==undefined&&!['always','cache-components','flight-reference'].includes(item.initial)||item.dynamicIds!==undefined&&(!Array.isArray(item.dynamicIds)||item.dynamicIds.length>100000||item.dynamicIds.some(id=>!/^dynamic-[a-f\d]{20}$/.test(id)))))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.');
+    if(!object(value.previous)||!text(value.previous.buildId)||value.previous.totalJsBytes!==undefined&&!size(value.previous.totalJsBytes)||value.version===2&&value.previous.version!==2)throw new Error('Invalid previous bundle analysis.');
     validateRoutes(value.previous.routes,{complete:false});
   }
+  if(value.version===2){
+    if(value.routes.some(route=>!route.initial)||value.previous?.routes.some(route=>!route.initial))throw new Error('Missing initial asset coverage in bundle analysis.');
+    validateInitialTotals(value);
+  }
   // 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}))}}:{})};
+  const cleanInitial=initial=>initial?{status:initial.status,samplePaths:[...initial.samplePaths],samples:initial.samples.map(({path,files,jsBytes,gzipBytes,brotliBytes})=>({path,files:[...files],jsBytes,gzipBytes,brotliBytes}))}:undefined;
+  const cleanRoute=({route,files,initial,jsBytes,gzipBytes,brotliBytes})=>({route,files,...(initial?{initial:cleanInitial(initial)}:{}),jsBytes,gzipBytes,brotliBytes});
+  if(value.version===2&&value.routes.some(route=>!route.initial)||value.previous&&value.version===2&&value.previous.routes.some(route=>!route.initial))throw new Error('Missing initial asset coverage in bundle analysis.');
+  return {version:value.version,buildId:value.buildId,totalJsBytes:value.totalJsBytes,routes:value.routes.map(cleanRoute),
+    files:value.files.map(({file,bytes,gzipBytes,brotliBytes,imports,modules,initialIncomplete})=>({file,bytes,gzipBytes,brotliBytes,...(initialIncomplete?{initialIncomplete:true}:{}),imports:imports.map(({file,kind,initial,dynamicIds})=>({file,kind,...(initial?{initial}:{}),...(dynamicIds?{dynamicIds:[...dynamicIds]}:{})})),modules:modules.map(({file,bytes})=>({file,bytes}))})),
+    ...(text(value.comparisonUnavailable)?{comparisonUnavailable:value.comparisonUnavailable}:{}),
+    ...(value.previous?{previous:{version:value.previous.version||1,buildId:value.previous.buildId,totalJsBytes:value.previous.totalJsBytes,routes:value.previous.routes.map(cleanRoute)}}:{})};
 }
 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'}.`);
@@ -153,22 +302,25 @@ export async function analyzeBuild(root,{maxJs,baseline,metric='raw',maxIncrease
   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;
+  if(reference&&report.version!==(reference.version||1))throw new Error('Initial asset accounting changed; rebuild the baseline with this PRNext version before comparing.');
   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]]));
+  const field=metrics[metric],previous=new Map((reference?.routes||[]).filter(route=>route.initial?.status!=='request-dependent').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 uncertain=route.initial?.status==='request-dependent';
+    const before=previous.get(route.route),current=route[field],hasBaseline=!uncertain&&size(before),delta=hasBaseline?current-before:null;
     const regressionBudget=budget.maxIncreaseBytes!==undefined||budget.maxIncreasePercent!==undefined;
     const exceeded=[];
+    if(uncertain&&Object.values(budget).some(value=>value!==undefined))exceeded.push('initial-unknown');
     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}};
+      comparison:uncertain?'initial-unknown':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;
@@ -176,9 +328,13 @@ export async function analyzeBuild(root,{maxJs,baseline,metric='raw',maxIncrease
 }
 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(`PRNext bundle analysis (${report.buildId})\n${report.version===2?'Hydration JavaScript per route, including required runtime imports and prerendered dynamic modules. Each metric is the largest sampled path; route file lists are unions. Shared files counted once; deferred imports excluded. Request-dependent route maxima are lower bounds.':'Legacy static-import-only accounting; rebuild to include hydration dependencies.'} Budget metric: ${report.metric||'raw'}.`);
+  for(const route of report.routes)console.log(`${route.route}: ${route.initial?.status==='request-dependent'?'>= ':''}${kb(route.jsBytes)} JS / ${kb(route.gzipBytes)} gzip / ${kb(route.brotliBytes)} br${route.initial?` [${route.initial.status}]`:''}${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(', ')}]`:''}`);
+  if(report.comparisonUnavailable)console.log(report.comparisonUnavailable);
   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(', ')}`);
+  const unverified=report.routes.filter(route=>route.budget?.exceeded.some(reason=>reason==='initial-unknown'||reason==='baseline-missing')).map(route=>route.route);
+  const exceeded=report.routes.filter(route=>route.budget?.exceeded.some(reason=>!['initial-unknown','baseline-missing'].includes(reason))).map(route=>route.route);
+  if(exceeded.length)console.error(`JavaScript budget exceeded: ${exceeded.join(', ')}`);
+  if(unverified.length)console.error(`JavaScript budget not verified (initial coverage or baseline unavailable): ${unverified.join(', ')}`);
 }

package/build/app-config.mjs

@@ -14,6 +14,7 @@ const supported = new Map([
   ['revalidate', [false]],
   ['dynamicParams', [true, false]],
   ['instant', [true, false]],
+  ['ensureStatic', ['auto', 'shell', 'prefetch', 'navigation', false]],
   ['fetchCache', ['auto', 'default-cache', 'only-cache', 'force-cache', 'force-no-store', 'default-no-store', 'only-no-store']],
   ['preferredRegion', ['auto']],
   ['maxDuration', []],
@@ -69,6 +70,7 @@ export async function validateAppConfig(file) {
     if (!supported.has(item.name)) continue;
     const value = locals.get(item.local);
     const allowed = supported.get(item.name);
+    if (item.name === 'ensureStatic' && analysis.directives.includes('use client')) throw new Error(`ensureStatic cannot be exported by a Client Component (${file}).`);
     if (item.name === 'instant') {
       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; }
@@ -104,7 +106,16 @@ export function mergeAppConfig(configs) {
     throw new Error('Incompatible App Router fetchCache guarantees across route segments.');
   }
   let forceDynamic = false;
+  const levels = ['auto', 'shell', 'prefetch', 'navigation'];
+  let staticLevel = 0;
+  const staticDisabled = configs.some(config => config.ensureStatic === false);
   for (const config of configs) {
+    if (config.ensureStatic !== undefined && config.ensureStatic !== 'auto') {
+      const level = levels.indexOf(config.ensureStatic);
+      if (level > 0 && staticDisabled) throw new Error('ensureStatic: false cannot be combined with a static requirement across route segments.');
+      if (level > 0 && level < staticLevel) throw new Error('A child ensureStatic cannot weaken its parent requirement.');
+      staticLevel = Math.max(staticLevel, level);
+    }
     if (config.maxDuration !== undefined) merged.maxDuration = config.maxDuration;
     if (config.runtime === 'edge') merged.runtime = 'edge';
     else if (config.runtime === 'nodejs') delete merged.runtime;
@@ -118,6 +129,8 @@ export function mergeAppConfig(configs) {
     if (config.fetchCache !== undefined) merged.fetchCache = config.fetchCache;
     if (config.fetchCache === 'force-no-store') merged.forceNoStore = true;
   }
+  if (staticDisabled) merged.ensureStatic = false;
+  else if (staticLevel) merged.ensureStatic = levels[staticLevel];
   if (forceDynamic) merged.dynamic = 'force-dynamic';
   if (policies.has('force-cache')) merged.fetchCache = 'force-cache';
   else if (!merged.forceNoStore && !forceDynamic) {

package/build/app-static.mjs

@@ -4,6 +4,8 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { staticPath } from '../runtime/pages-paths.mjs';
 import {mapConcurrent} from './concurrent.mjs';
+import {mapPrerender,prerenderPath} from './prerender-pool.mjs';
+import {validateHtmlOnlyPrerender} from './html-only-config.mjs';
 
 const MAX_STATIC_PATHS = 10_000;
 const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
@@ -50,7 +52,8 @@ export async function prerenderApp(stage, manifest, dev) {
     const handlers = routes.some(route => route.kind === 'api')
       ? await import(pathToFileURL(path.join(stage, 'runtime/route-static.mjs')).href) : null;
     const initialSeeds=[...manifest.prerendered];
-    await mapConcurrent(routes,async route=>{
+    const jobs=[],seeds=new Map(),partialRoutes=new Set();
+    await mapConcurrent(routes,async(route,routeIndex)=>{
       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
@@ -61,7 +64,14 @@ export async function prerenderApp(stage, manifest, dev) {
       if (handler) route.handlerMethods = inspected.methods;
       const dynamic = route.pattern.includes('[');
       const entries = appStaticEntries(route.pattern, dynamic ? inspected.params : [{}]);
+      if(route.htmlOnly && dynamic && (!inspected.generated || !entries.length || inspected.params.some(params=>appStaticEntries(route.pattern,[params]).length!==1))) {
+        throw new Error(`htmlOnly route ${route.pattern} requires nonempty complete generateStaticParams results.`);
+      }
       const config = route.cacheConfig;
+      if (config.ensureStatic === 'navigation') {
+        if (config.runtime === 'edge' || config.dynamic === 'force-dynamic' || config.revalidate === 0 || config.forceNoStore) throw new Error(`Route ${route.pattern}: ensureStatic='navigation' conflicts with request-time rendering configuration.`);
+        if (dynamic && (!inspected.generated || !entries.length || inspected.params.some(params => appStaticEntries(route.pattern, [params]).length !== 1))) throw new Error(`Route ${route.pattern}: ensureStatic='navigation' requires generateStaticParams() with complete, nonempty parameter sets.`);
+      }
       // Keep generated-path restrictions and method metadata for Edge routes,
       // while separating dynamic rendering from the persistent Data Cache.
       if (config.runtime === 'edge') {
@@ -69,6 +79,7 @@ export async function prerenderApp(stage, manifest, dev) {
         return;
       }
       const partial = !handler && manifest.config?.cacheComponents === true && (!config.dynamic || config.dynamic === 'auto');
+      if(partial)partialRoutes.add(route);
       if (partial && dynamic && !inspected.generated) entries.length = 0;
       if (partial && dynamic && inspected.generated && inspected.params.length === 0) {
         throw new Error(`generateStaticParams for ${route.pattern} must return at least one parameter object when cacheComponents is enabled.`);
@@ -109,10 +120,12 @@ export async function prerenderApp(stage, manifest, dev) {
       }
       route.ssg = true;
       route.fallback = config.dynamicParams === false ? false : 'blocking';
-      for (const entry of entries) {
+      for (const [entryIndex,entry] of entries.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 });
+        jobs.push({route,routeIndex,entryIndex,path:entry.path,run:async()=>{
+        const rendered = await prerenderPath(handler?'handler':'app',{ ...options, path: entry.path, params: entry.params },handler?handlers.prerenderAppRouteHandler:pages.prerenderAppRoute);
+        if(route.htmlOnly)validateHtmlOnlyPrerender(route,rendered);
         if (rendered.partial) {
           const file = `static/partial-${createHash('sha256').update(entry.path).digest('hex').slice(0, 20)}.json`;
           await writeFile(path.join(stage, file), JSON.stringify({ ...rendered.partial, ...rendered.metadata }));
@@ -120,7 +133,7 @@ export async function prerenderApp(stage, manifest, dev) {
           if (!dynamic) { delete route.ssg; delete route.fallback; }
           else (route.dynamicPaths ||= []).push(entry.path);
           occupied.add(entry.path);
-          continue;
+          return;
         }
         if (rendered.dynamic) {
           route.dynamicReasons = [...new Set([...(route.dynamicReasons || []), rendered.reason || 'request-time data'])];
@@ -132,34 +145,43 @@ export async function prerenderApp(stage, manifest, dev) {
             // successful seeds survive, while ungenerated paths stay dynamic.
             if (handler && config.dynamicParams !== false) route.fallback = 'dynamic';
           }
-          continue;
+          return;
         }
         const body = Buffer.isBuffer(rendered.body) ? rendered.body : Buffer.from(rendered.body);
-        const flight = handler ? null : Buffer.isBuffer(rendered.flight) ? rendered.flight : Buffer.from(rendered.flight);
+        const flight = handler || route.htmlOnly ? null : Buffer.isBuffer(rendered.flight) ? rendered.flight : Buffer.from(rendered.flight);
         if (body.byteLength > MAX_RESPONSE_BYTES || (flight && flight.byteLength > MAX_RESPONSE_BYTES)) throw new Error(`Static App route ${entry.path} exceeds the 16 MiB response limit.`);
         const stem = `static/${handler ? 'route' : 'app'}-${createHash('sha256').update(entry.path).digest('hex').slice(0, 20)}`;
         const file = `${stem}.${handler ? 'body' : 'html'}`;
         // Flight is opaque text, not JSON; the native cache supplies text/x-component.
-        const dataFile = handler ? undefined : `${stem}.txt`;
+        const dataFile = handler || route.htmlOnly ? undefined : `${stem}.txt`;
         await writeFile(path.join(stage, file), body);
         if (dataFile) await writeFile(path.join(stage, dataFile), flight);
         occupied.add(entry.path);
-        manifest.prerendered.push({ routeId: route.id, path: entry.path, file, ...(dataFile ? { dataFile } : {}), status: rendered.status ?? 200,
+        seeds.set(entry.path,{ routeId: route.id, path: entry.path, file, ...(dataFile ? { dataFile } : {}), status: rendered.status ?? 200,
           headers: rendered.headers || {}, revalidate: rendered.revalidate ?? config.revalidate,
           generatedAt: rendered.generatedAt, tags: rendered.tags || [], paths: rendered.paths || [],
         });
+        }});
       }
+    });
+    jobs.sort((a,b)=>a.routeIndex-b.routeIndex||a.entryIndex-b.entryIndex);
+    await mapPrerender(jobs,job=>job.run());
+    manifest.prerendered=[...initialSeeds,...jobs.flatMap(job=>seeds.has(job.path)?[seeds.get(job.path)]:[])];
+    for(const route of routes){
+      const routeJobs=jobs.filter(job=>job.route===route);
+      if(route.dynamicPaths)route.dynamicPaths=routeJobs.filter(job=>route.dynamicPaths.includes(job.path)).map(job=>job.path);
+      if(route.ppr)route.ppr=Object.fromEntries(routeJobs.filter(job=>Object.hasOwn(route.ppr,job.path)).map(job=>[job.path,route.ppr[job.path]]));
+      if(route.dynamicReasons)route.dynamicReasons=[...new Set(route.dynamicReasons)].sort();
       // Unseen Cache Components paths are generated by the PPR runtime, which
       // handles either complete HTML/Flight or a resumable shell atomically.
-      if (partial && dynamic) {
+      if (partialRoutes.has(route) && route.pattern.includes('[')) {
         if (manifest.prerendered.some(page => page.routeId === route.id)) {
           // Concrete complete seeds use the native invalidation-aware cache.
           // Other paths still reach the PPR runtime, including dynamic holes.
           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))];
+      if(route.htmlOnly)route.fallback=false;
+    }
   } finally { await closeAppRuntime(); }
 }

package/build/app-styles.mjs

@@ -0,0 +1,79 @@
+import path from 'node:path';
+
+const stylesheet = /\.(?:css|scss|sass)$/i;
+const conventions = ['layout', 'template', 'loading', 'error', 'notFound', 'not-found', 'default', 'page'];
+// Native esbuild identifies virtual inputs with absolute paths. The webpack
+// bridge uses the same namespaces with project-relative paths instead. Only
+// strip framework namespaces here; a Windows drive letter is part of the path.
+const styleNamespace = /^prnext-(?:css-mapping|compiled-css|app-empty|edge-empty):/;
+
+/** Join RSC references with their real client dependency graphs, without
+ * flattening CSS @import/composes dependencies into extra stylesheets. */
+export function createAppStyleGraph(root) {
+  const graph = new Map();
+  const file = name => path.resolve(root, name.replace(styleNamespace, ''));
+  return {
+    alias(source, target) {
+      if (file(source) !== file(target)) graph.set(file(source), new Set([file(target)]));
+    },
+    record(metafile) {
+      for (const [name, input] of Object.entries(metafile?.inputs || {})) {
+        const key = file(name), dependencies = graph.get(key) || new Set();
+        for (const dependency of input.imports || []) if (!dependency.external) dependencies.add(file(dependency.path));
+        graph.set(key, dependencies);
+      }
+    },
+    collect(roots) {
+      const seen = new Set(), styles = new Set();
+      const pending = [...roots].reverse();
+      while (pending.length) {
+        const key = file(pending.pop());
+        if (seen.has(key)) continue;
+        seen.add(key);
+        if (stylesheet.test(key)) { styles.add(key); continue; }
+        const dependencies = [...graph.get(key) || []];
+        for (let index = dependencies.length - 1; index >= 0; index--) pending.push(dependencies[index]);
+      }
+      return [...styles];
+    },
+  };
+}
+
+/** Layout scopes precede their descendants. Shared scopes produce the same
+ * content-addressed sheet on every route, while a page never owns a sibling's
+ * styles. A pruned parallel tree also includes its loading/error/default and
+ * intercepted branches so a retained slot cannot lose its stylesheet. */
+export function appStyleEntries(route) {
+  const scopes = [];
+  function add(files, path) {
+    const roots = conventions.filter(name => name !== 'page' && name !== 'default').map(name => files?.[name]).filter(file => typeof file === 'string');
+    if (roots.length) scopes.push({ path, kind:'layout', roots });
+    for (const kind of ['default', 'page']) if (typeof files?.[kind] === 'string') scopes.push({ path, kind, roots:[files[kind]] });
+  }
+  if (route.routing) {
+    function visit(node) {
+      add(node.files, node.path || '');
+      for (const child of node.children || []) visit(child);
+      for (const name of Object.keys(node.slots || {}).sort()) visit(node.slots[name]);
+    }
+    visit(route.routing);
+  } else {
+    for (const segment of route.segments || []) add(segment, segment.path || '');
+    if (route.file) add({ page: route.file }, '');
+  }
+  return scopes;
+}
+
+export const appStyleScopes = route => appStyleEntries(route).map(scope => scope.roots);
+
+export function planAppStyleEntries(route, graph) {
+  const included = new Set(), groups = [];
+  for (const scope of appStyleEntries(route)) {
+    const styles = graph.collect(scope.roots).filter(file => !included.has(file));
+    for (const file of styles) included.add(file);
+    if (styles.length) groups.push({ ...scope, styles });
+  }
+  return groups;
+}
+
+export const planAppStyles = (route, graph) => planAppStyleEntries(route, graph).map(scope => scope.styles);