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

package/build/incremental.mjs

@@ -1,14 +1,76 @@
 import { context } from 'esbuild';
 import { readFile, writeFile, mkdir, realpath } from 'node:fs/promises';
+import { realpath as legacyRealpath } from 'node:fs';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import {clearDirectoryCache} from './directory-cache.mjs';
 import {closeWebpackCompiler,webpackCompilerStats} from './webpack-graph.mjs';
 const contexts = new Map();
 const LIMIT = 8;
-let created = 0, reused = 0;
-export const incrementalCompilerStats = () => ({contexts:contexts.size, created, reused,webpack:webpackCompilerStats()});
+const AUXILIARY_LIMIT = 2;
+const RESERVES = Object.freeze({ main: 6, styles: 2 });
+const counters = () => ({ created: 0, reused: 0, evicted: 0 });
+const roles = () => ({ main: counters(), styles: counters(), auxiliary: counters() });
+const totals = counters(), roleTotals = roles();
+
+function record(metrics, role, event) {
+  totals[event]++;
+  roleTotals[role][event]++;
+  metrics[event]++;
+  metrics.roles[role][event]++;
+}
+
+function roleStats(metrics, active) {
+  return Object.fromEntries(Object.entries(metrics).map(([role, values]) => [role, {
+    ...values,
+    contexts: active.filter(slot => slot.role === role).length,
+  }]));
+}
+
+export function incrementalCompilerStats() {
+  const active = [...contexts.values()];
+  // Counters belong to retained projects, rather than an unbounded registry of
+  // every project ever compiled by this process. Global role totals persist.
+  const projects = [...new Set(active.map(slot => slot.metrics))].map(metrics => {
+    const retained = active.filter(slot => slot.metrics === metrics);
+    return {
+      root: metrics.root,
+      created: metrics.created,
+      reused: metrics.reused,
+      evicted: metrics.evicted,
+      contexts: retained.length,
+      roles: roleStats(metrics.roles, retained),
+    };
+  });
+  return {
+    contexts: contexts.size,
+    ...totals,
+    roles: roleStats(roleTotals, active),
+    projects,
+    limits: { project: LIMIT, auxiliary: AUXILIARY_LIMIT, reserves: { ...RESERVES } },
+    webpack: webpackCompilerStats(),
+  };
+}
+
+function evictionCandidate(group, role) {
+  const candidates = [...contexts].filter(([, slot]) => slot.group === group);
+  if (group === 'auxiliary') return candidates[0];
+  const count = candidateRole => candidates.filter(([, slot]) => slot.role === candidateRole).length;
+  // Both roles can borrow unused capacity. Once full, a role at its reserve
+  // replaces its own oldest graph; a role below its reserve reclaims a loan.
+  if (count(role) >= RESERVES[role]) return candidates.find(([, slot]) => slot.role === role);
+  return candidates.find(([, slot]) => count(slot.role) > RESERVES[slot.role]);
+}
 export async function closeIncrementalCompiler(root) {
+  if (root !== undefined) {
+    try { root = await realpath(root); }
+    catch (error) {
+      // Disposal also runs after users remove a project directory. A supplied
+      // canonical path must still match its retained contexts in that case.
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error;
+      root = path.resolve(root);
+    }
+  }
   clearDirectoryCache();
   const active=[];for(const [key,slot] of contexts)if(root===undefined||slot.root===root){contexts.delete(key);active.push(slot);}
   const results=await Promise.allSettled([...active.map(slot=>slot.context.dispose()),closeWebpackCompiler(root)]);
@@ -16,18 +78,42 @@ export async function closeIncrementalCompiler(root) {
   if(errors.length)throw new AggregateError(errors,'Unable to dispose incremental compiler sessions');
 }
 /** Retain esbuild's parsed module graphs while rebinding per-build framework plugins. */
-export async function incrementalBuild(options, {root,stage,group='project',run=callback=>callback()}) {
-  const canonicalRoot = await realpath(root);
-  if (canonicalRoot !== root) {
-    const canonical = value => typeof value === 'string' ? value.replaceAll(root, canonicalRoot) : Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' && !(value instanceof RegExp) && !ArrayBuffer.isView(value) ? Object.fromEntries(Object.entries(value).map(([key,item]) => [key,canonical(item)])) : value;
-    return incrementalBuild(canonical(options),{root:canonicalRoot,stage:stage.replace(root,canonicalRoot),group,run});
+export async function incrementalBuild(options, {root,stage,group='project',role=group==='auxiliary'?'auxiliary':'main',run=callback=>callback()}) {
+  if (!['project', 'auxiliary'].includes(group) || (group === 'project' ? !Object.hasOwn(RESERVES, role) : role !== 'auxiliary')) {
+    throw new TypeError('Invalid incremental compiler group or role');
   }
+  // Canonical identity is for ownership and disposal only. Compilation paths
+  // and application strings retain the caller's lexical spelling.
+  const ownerRoot = await realpath(root);
   const virtual=path.join(root,'.prnext-incremental-stage');
+  const rootPaths=[root,ownerRoot];
+  if(process.platform==='win32'&&root!==ownerRoot){
+    // Windows resolvers can preserve a short ancestor while resolving the
+    // junction target. The JS realpath walk retains that third spelling.
+    rootPaths.push(await new Promise((resolve,reject)=>legacyRealpath(root,(error,value)=>error?reject(error):resolve(value))));
+  }
+  const virtualPaths=[...new Set(rootPaths.map(directory=>path.join(directory,'.prnext-incremental-stage')))];
+  const stageRelative=path.relative(root,stage);
+  const stagePaths=[...new Set([stage,...rootPaths.map(directory=>path.resolve(directory,stageRelative))])];
+  const relativePath=(directory,value)=>{
+    if(typeof value!=='string'||!path.isAbsolute(value))return;
+    const relative=path.relative(directory,value);
+    if(relative===''||!path.isAbsolute(relative)&&relative!=='..'&&!relative.startsWith('..'+path.sep))return relative;
+  };
+  const withinPaths=(directories,value)=>directories.some(directory=>relativePath(directory,value)!==undefined);
+  const remapPath=(value,directories,target)=>{
+    for(const directory of directories){const relative=relativePath(directory,value);if(relative!==undefined)return path.join(target,relative);}
+    return value;
+  };
   const toVirtual=value=>typeof value==='string'?value.replaceAll(stage,virtual):value;
-  const fromVirtual=value=>typeof value==='string'?value.replaceAll(virtual,stage):value;
+  // esbuild can canonicalize only the parent of a nonexistent virtual file.
+  // Recognize both staging identities on path fields, never application text.
+  const fromVirtual=value=>remapPath(value,[...virtualPaths,...stagePaths],stage);
+  const toVirtualPath=value=>remapPath(value,stagePaths,virtual);
+  const isVirtual=value=>withinPaths(virtualPaths,value),isStaged=value=>withinPaths(stagePaths,value);
   const deep=(value,map)=>typeof value==='string'?map(value):Array.isArray(value)?value.map(item=>deep(item,map)):value&&typeof value==='object'&&!(value instanceof RegExp)&&!ArrayBuffer.isView(value)?Object.fromEntries(Object.entries(value).map(([key,item])=>[map(key),deep(item,map)])):value;
   const realResult=result=>result && {...result,...(result.path?{path:fromVirtual(result.path)}:{}),...(result.resolveDir?{resolveDir:fromVirtual(result.resolveDir)}:{})};
-  const virtualResult=result=>result && {...result,...(result.path?{path:toVirtual(result.path)}:{}),...(result.resolveDir?{resolveDir:toVirtual(result.resolveDir)}:{}),...(result.watchFiles?{watchFiles:result.watchFiles.map(toVirtual)}:{}),...(result.watchDirs?{watchDirs:result.watchDirs.map(toVirtual)}:{})};
+  const virtualResult=result=>result && {...result,...(result.path?{path:toVirtualPath(result.path)}:{}),...(result.resolveDir?{resolveDir:toVirtualPath(result.resolveDir)}:{}),...(result.watchFiles?{watchFiles:result.watchFiles.map(toVirtualPath)}:{}),...(result.watchDirs?{watchDirs:result.watchDirs.map(toVirtualPath)}:{})};
   const hooks=[];
   const initialOptions={...options,plugins:undefined,write:false};
   let slot;
@@ -39,18 +125,24 @@ export async function incrementalBuild(options, {root,stage,group='project',run=
   });
   const normalized=deep(initialOptions,toVirtual);
   const signature=JSON.stringify([normalized,hooks.map(({kind,settings})=>[kind,settings?.namespace,settings?.filter?.source,settings?.filter?.flags]),(options.plugins||[]).map(plugin=>plugin.name)]);
-  const key=group+':'+createHash('sha256').update(signature).digest('hex');
+  const key=JSON.stringify([ownerRoot,root,group,role,createHash('sha256').update(signature).digest('hex')]);
   slot=contexts.get(key);
-  if(slot){contexts.delete(key);reused++;}
+  if(slot){contexts.delete(key);record(slot.metrics,role,'reused');}
   else {
-    while([...contexts.values()].filter(slot=>slot.group===group).length>=(group==='auxiliary'?2:LIMIT)){const [oldest,previous]=[...contexts].find(([,slot])=>slot.group===group);contexts.delete(oldest);await previous.context.dispose();}
-    created++;slot={group,root};
-    slot.current={hooks,run,toVirtual,fromVirtual,virtualResult,stage};
+    const metrics = [...contexts.values()].find(slot => slot.root === ownerRoot)?.metrics || { root: ownerRoot, ...counters(), roles: roles() };
+    while ([...contexts.values()].filter(slot => slot.group === group).length >= (group === 'auxiliary' ? AUXILIARY_LIMIT : LIMIT)) {
+      const [oldest, previous] = evictionCandidate(group, role);
+      contexts.delete(oldest);
+      record(previous.metrics, previous.role, 'evicted');
+      await previous.context.dispose();
+    }
+    slot={group,role,root:ownerRoot,metrics};
+    slot.current={hooks,run,toVirtual,fromVirtual,virtualResult,stage,isVirtual,isStaged};
     slot.context=await context({...normalized,plugins:[{name:'prnext-incremental-delegates',setup(builder){
       slot.builder=builder;
       builder.onResolve({filter:/.*/},async args=>{
         const active=slot.current;
-        if(args.pluginData?.prnextVirtualResolution || !(args.path.startsWith(virtual+path.sep)||args.path.startsWith(active.stage+path.sep)||(args.resolveDir===virtual || args.resolveDir.startsWith(virtual+path.sep))))return;
+        if(args.pluginData?.prnextVirtualResolution || !(active.isVirtual(args.path)||active.isStaged(args.path)||active.isVirtual(args.resolveDir)||active.isStaged(args.resolveDir)))return;
         const result=await builder.resolve(active.fromVirtual(args.path),{resolveDir:active.fromVirtual(args.resolveDir),importer:active.fromVirtual(args.importer),kind:args.kind,with:args.with,pluginData:{...args.pluginData,prnextVirtualResolution:true}});
         const pluginData={...(result.pluginData || args.pluginData)}; delete pluginData.prnextVirtualResolution;
         return {...active.virtualResult(result),pluginData};
@@ -63,13 +155,15 @@ export async function incrementalBuild(options, {root,stage,group='project',run=
         if(settings)builder[kind](settings,callback);else builder[kind](callback);
       });
       builder.onLoad({filter:/.*/,namespace:'file'},async args=>{
-        if(!args.path.startsWith(virtual+path.sep))return;
-        const actual=slot.current.fromVirtual(args.path),extension=path.extname(actual);
+        const active=slot.current;
+        if(!active.isVirtual(args.path))return;
+        const actual=active.fromVirtual(args.path),extension=path.extname(actual);
         return {contents:await readFile(actual),loader:options.loader?.[extension] || ({'.json':'json','.ts':'ts','.tsx':'tsx','.jsx':'jsx','.css':'css'}[extension] || 'js'),resolveDir:path.dirname(args.path)};
       });
     }}]});
+    record(metrics,role,'created');
   }
-  slot.current={hooks,run,toVirtual,fromVirtual,virtualResult,stage};
+  slot.current={hooks,run,toVirtual,fromVirtual,virtualResult,stage,isVirtual,isStaged};
   contexts.set(key,slot);
   const result=await slot.context.rebuild();
   const relativeVirtual=path.basename(virtual),relativeStage=path.basename(stage);

package/build/index.mjs

@@ -6,13 +6,17 @@ import { writeRuntimeContract } from './runtime-contract.mjs';
 import { writeBuildOutput } from './output-contract.mjs';
 import { bundleRuntime } from './bundle-runtime.mjs';
 import {withPersistentTransforms} from './transform-cache.mjs';
+import {withCompilationStorage,configureCompilationStorage} from './compilation-storage.mjs';
+import {reclaimBuildStages,trackBuildStage} from './build-retention.mjs';
 import {applicationEntry, frameworkImportName, frameworkRuntimeImportPattern} from './framework-imports.mjs';
 import { expandLocales, localizedStaticPaths } from './i18n.mjs';
 import { build as bundle, withCompilation, configureCompiler, compilerSource,buildAnalysisRecords,buildAnalysisRoutes,devDependencies,devStylePlans,devStyleDependencies,devModules,readCompilerFile,compilationGraphCacheReport } from './compiler.mjs';
 import {retainDeploymentAssets} from './deployment-assets.mjs';
 import {selectHtmlOnlyRoutes} from './html-only-config.mjs';
 import {writeBuildAnalysis} from './analyze.mjs';
+import {prepareNativePprShells} from './native-ppr.mjs';
 import {routeFiles} from './dev-discovery.mjs';
+import {tryBuildLazyGraph,rememberLazyBuildContext,forgetLazyBuildContext} from './dev-lazy-build.mjs';
 import {writeTypedRoutes} from './typed-routes.mjs';
 import { mkdir, readFile, writeFile, rm, cp, copyFile, stat, readdir, realpath } from 'node:fs/promises';
 import path from 'node:path';
@@ -36,7 +40,7 @@ import { compileCustomRoutes } from './custom-routes.mjs';
 import { compileMiddleware } from './middleware.mjs';
 import { prepareScriptWorkers } from './script-workers.mjs';
 import { prepareMetadataRoutes } from './metadata-routes.mjs';
-import { prepareImageResponse } from './og.mjs';
+import { prepareImageResponse, imageResponseRequirement } from './og.mjs';
 import { prepareCacheHandler, prepareCacheHandlers } from './cache-handlers.mjs';
 import { npmPackagesPlugin } from './npm-packages.mjs';
 import { createRefreshTransform, createSourceLocationTransform, devSingletonsPlugin, devClientFile } from './dev.mjs';
@@ -73,7 +77,7 @@ async function copyRuntimeFiles(stage,{development=true}={}) {
   if (failed) throw failed.reason;
 }
 
-function compatibilityPlugin({ browser, pageFiles, projectRoot, documentFile, serverOnlyFiles, fonts, refresh, locations, reactCompiler }) {
+function compatibilityPlugin({ browser, pageFiles, projectRoot, documentFile, serverOnlyFiles, fonts, refresh, locations, reactCompiler, nativeCompiler = false }) {
   return {
     name: 'prnext-pages-compatibility',
     setup(esbuild) {
@@ -107,8 +111,13 @@ function compatibilityPlugin({ browser, pageFiles, projectRoot, documentFile, se
         // loaders. Keep that entire graph original: an uppercase JSX utility
         // may be called normally there, outside a React render. Browser render
         // graphs receive memoization before instrumentation and JSX lowering.
-        const compiled=browser && reactCompiler && args.path!==documentFile && !serverOnlyFiles.has(args.path) ? await reactCompiler(original,args.path,{loaderOutput:args.prnextSource!==undefined}) : original;
-        const source = await fonts.transform(locations?await locations(compiled,args.path):compiled, args.path);
+        const compile = browser && reactCompiler && args.path!==documentFile && !serverOnlyFiles.has(args.path);
+        // Oxc can hoist static JSX without a source-map position. Attach the
+        // same original inspector attributes as SSR before that transformation.
+        const locateFirst = !!(compile && nativeCompiler && locations);
+        const input = locateFirst ? await locations(original,args.path) : original;
+        const compiled = compile ? await reactCompiler(input,args.path,{loaderOutput:args.prnextSource!==undefined}) : input;
+        const source = await fonts.transform(locations && !locateFirst ? await locations(compiled,args.path) : compiled, args.path);
         assertSupportedSource(source, args.path);
         const dynamicSource = transformDynamicImports(source, args.path, { projectRoot, mode: browser ? 'browser' : 'server' });
         let contents = browser && pageFiles.has(args.path) ? stripServerCode(dynamicSource, args.path) : dynamicSource;
@@ -154,7 +163,12 @@ let buildQueue = Promise.resolve();
 let developmentModulesLoaded = false;
 /** Disposing shared compiler contexts must not interrupt another queued build. */
 export function disposeBuildSession(root){
-  const task=buildQueue.then(async()=>{const {closeIncrementalCompiler}=await import('./incremental.mjs');await closeIncrementalCompiler(root);});
+  const task=buildQueue.then(async()=>{
+    const canonicalRoot=root===undefined?undefined:await realpath(root).catch(error=>{if(error.code==='ENOENT'||error.code==='ENOTDIR')return path.resolve(root);throw error;});
+    forgetLazyBuildContext(canonicalRoot);
+    const {closeIncrementalCompiler}=await import('./incremental.mjs');
+    await closeIncrementalCompiler(canonicalRoot);
+  });
   buildQueue=task.catch(()=>{});return task;
 }
 /** Isolate process.env between programmatic builds, including simultaneous calls. */
@@ -173,8 +187,9 @@ export function build(projectRoot, options = {}) {
     const envMode = options.envMode || (process.env.NODE_ENV === 'test' ? 'test' : options.dev ? 'development' : 'production');
     process.env.NODE_ENV = options.dev ? 'development' : 'production';
     try { return await withBuildLock(projectRoot, async root => {
+      await reclaimBuildStages(root);
       const started=performance.now();
-      const result=await withPersistentTransforms(root,{dev:!!options.dev},()=>withCompilation(() => buildProject(root, { ...options, envMode })));
+      const result=await withCompilationStorage(root,()=>withPersistentTransforms(root,{dev:!!options.dev},()=>withCompilation(() => buildProject(root, { ...options, envMode }))));
       return {...result,durationMs:Math.round(performance.now()-started)};
     }); }
     finally { restore(); }
@@ -184,12 +199,18 @@ export function build(projectRoot, options = {}) {
 }
 
 /** Compile Pages Router and App Router projects. A failed build preserves .prnext. */
-async function buildProject(projectRoot, { dev = false, envMode, incremental = false, devInputs, devRoutes, devSequence, devSession, devTools,devForceRefresh=false,devAffectedModules } = {}) {
+async function buildProject(projectRoot, { dev = false, envMode, incremental = false, devInputs, devRoutes, devSequence, devSession, devActionSecret, devTools,devForceRefresh=false,devAffectedModules,devLazyRequest,devLazyBase,devLazyActivated=[] } = {}) {
   const started = performance.now();
+  if (dev && devLazyRequest && devLazyBase) {
+    const deferred = await tryBuildLazyGraph(projectRoot,{base:devLazyBase,request:devLazyRequest,
+      devInputs,devSession,devActionSecret,incremental});
+    if (deferred) return deferred;
+  }
   const config = await loadProjectConfig(projectRoot, { dev, envMode, devInputs });
+  configureCompilationStorage(config.compilationCache);
   const tsconfig = config.typescript ? await projectTsconfig(projectRoot, config) : undefined;
   const environment = defineEnvironment(config);
-  const publicPaths = { trailingSlash: config.trailingSlash, skipTrailingSlashRedirect: config.skipTrailingSlashRedirect, basePath: config.basePath, assetPrefix: config.assetPrefix, assetBase: publicAssetBase(config) };
+  const publicPaths = { server: config.server, trailingSlash: config.trailingSlash, skipTrailingSlashRedirect: config.skipTrailingSlashRedirect, basePath: config.basePath, assetPrefix: config.assetPrefix, assetBase: publicAssetBase(config) };
   const customRoutes = await compileCustomRoutes(config);
   const buildId = await generateBuildId(config, { dev });
   const scanOptions={basePath:config.basePath,pageExtensions:config.pageExtensions,i18n:config.i18n};
@@ -201,17 +222,24 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     deferredRoutes=discovery.routes.filter(route=>!devRoutes.includes(route.pattern)&&!route.internal&&!route.errorStatus);
     project.routes=project.routes.filter(route=>devRoutes.includes(route.pattern)||route.internal||route.errorStatus);
   } else project=await scanProject(projectRoot,scanOptions);
+  if(dev&&config.experimental.lazyDynamicImports){
+    if(project.routes.some(route=>route.router!=='app'&&!route.internal))throw Error('experimental.lazyDynamicImports currently requires an App Router-only application.');
+    if(config.webpack||Object.keys(config.turbopack?.rules||{}).length)throw Error('experimental.lazyDynamicImports currently requires the native compiler without webpack hooks or custom loaders.');
+    if(/^https?:\/\//.test(config.assetPrefix))throw Error('experimental.lazyDynamicImports requires same-origin development assets.');
+  }
   if(!dev&&config.htmlOnly.length)selectHtmlOnlyRoutes(project.routes,config.htmlOnly,config);
   if(!dev || !Array.isArray(devRoutes))await writeTypedRoutes(projectRoot,project,config);
   const stage = path.join(project.root, `.prnext-build-${randomUUID()}`);
   const destination = await prepareBuildDirectory(project.root, config.distDir);
   const backup = path.join(project.root, `.prnext-backup-${randomUUID()}`);
+  const recovery=await trackBuildStage(project.root,{stage,backup}).catch(()=>null);
+  try {
   await mkdir(path.join(stage, '.entries'), { recursive: true });
   await mkdir(path.join(stage, 'static'), { recursive: true });
   await addBuiltinPagesErrors(project, stage);
   const manifest = { version: 1, dev, buildId, cacheId: randomUUID(), previewModeId: randomUUID().replaceAll('-', ''), previewModeEncryptionKey: randomBytes(32).toString('hex'),
     ...(dev && Array.isArray(devRoutes) ? {devOnDemand:true} : {}), ...(dev && devSession ? {devSequence,devSession} : {}), ...(dev ? {devForceRefresh,devAffectedModules,devIndicators:config.devIndicators,...(devTools?{devTools}:{})} : {}),
-    config: { i18n: config.i18n, skipMiddlewareUrlNormalize: config.skipMiddlewareUrlNormalize, compress: config.compress, poweredByHeader: config.poweredByHeader, reactStrictMode: config.reactStrictMode, cacheComponents: config.cacheComponents, partialPrefetching: config.partialPrefetching, navigationCache: config.navigationCache, cacheLife: config.cacheLife, htmlOnly:config.htmlOnly, images: config.images, ...publicPaths }, customRoutes, routes: [], prerendered: [],
+    config: { i18n: config.i18n, skipMiddlewareUrlNormalize: config.skipMiddlewareUrlNormalize, compress: config.compress, poweredByHeader: config.poweredByHeader, reactStrictMode: config.reactStrictMode, cacheComponents: config.cacheComponents, partialPrefetching: config.partialPrefetching, navigationCache: config.navigationCache, cacheLife: config.cacheLife, htmlOnly:config.htmlOnly, images: config.images, streamingRequestBodies: config.experimental.streamingRequestBodies, nativePprShell: config.experimental.nativePprShell, ...publicPaths }, customRoutes, routes: [], prerendered: [],
     ...(project.pagesErrors ? { pagesErrors: project.pagesErrors } : {}) };
   // Its build-unique name is known before bundling and avoids a hash cycle
   // between page entry URLs and the manifest that lists those entries.
@@ -234,7 +262,6 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     // Runtime copies must work even when dotenv is nested beneath the PRNext
     // package instead of hoisted beside the application's dependencies.
     await bundle({ entryPoints: [path.join(packageRoot, 'runtime/env.mjs')], outfile: path.join(stage, 'runtime/env.mjs'), bundle: true, platform: 'node', format: 'esm', target: 'node22', logLevel: 'silent', banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" } });
-    await prepareImageResponse(stage);
     manifest.config.serverActions = config.experimental.serverActions;
     if(config.workerMemory && !dev)manifest.config.workerMemory=config.workerMemory;
     if (config.workerRetirement) manifest.config.workerRetirement = config.workerRetirement;
@@ -279,7 +306,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
       }
     }
     if (Object.keys(clientEntries).length) {
-      const browser = await bundle({ ...common, entryPoints: clientEntries, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', chunkNames: 'chunk-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], splitting: true, minify: !dev, sourcemap: dev || config.productionBrowserSourceMaps, define: { 'process.env': '{}', ...common.define }, plugins: [moduleResolutionPlugin(config.turbopack, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: true, pageFiles, projectRoot: project.root, documentFile: project.document, serverOnlyFiles, fonts, refresh, locations, reactCompiler }), cssModules.plugin(true)] });
+      const browser = await bundle({ ...common, entryPoints: clientEntries, outdir: path.join(stage, 'assets'), entryNames: '[name]-[hash]', chunkNames: 'chunk-[hash]', platform: 'browser', format: 'esm', target: ['es2022'], splitting: true, minify: !dev, sourcemap: dev || config.productionBrowserSourceMaps, define: { 'process.env': '{}', ...common.define }, plugins: [moduleResolutionPlugin(config.turbopack, project.root), ...(dev ? [devSingletonsPlugin()] : []), images.plugin(), fonts.plugin(), compatibilityPlugin({ browser: true, pageFiles, projectRoot: project.root, documentFile: project.document, serverOnlyFiles, fonts, refresh, locations, reactCompiler, nativeCompiler: config.reactCompiler?.backend === 'oxc' }), cssModules.plugin(true)] });
       fonts.record(browser.metafile);
       const byEntry = new Map(Object.entries(clientEntries).map(([id, file]) => [path.resolve(file), id]));
       for (const [output, metadata] of Object.entries(browser.metafile.outputs)) {
@@ -296,7 +323,18 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     await compileMiddleware({ project, stage, manifest, dev, moduleResolution: config.turbopack, defineEnvironment: environment });
     if (manifest.middleware) manifest.middleware.bodySizeLimit = config.experimental.proxyClientMaxBodySize;
     await prepareMetadataRoutes(project, stage);
-    await compileApp({ project, stage, manifest, reactCompiler: config.reactCompiler, moduleResolution: config.turbopack, cssModules, fonts, images, dev, defineEnvironment: environment, productionBrowserSourceMaps: config.productionBrowserSourceMaps, serverExternalPackages: config.serverExternalPackages });
+    await compileApp({ project, stage, manifest, reactCompiler: config.reactCompiler, moduleResolution: config.turbopack, cssModules, fonts, images, dev, devActionSecret:dev?devActionSecret:undefined, defineEnvironment: environment, productionBrowserSourceMaps: config.productionBrowserSourceMaps, serverExternalPackages: config.serverExternalPackages, lazyDynamicImports:dev&&config.experimental.lazyDynamicImports,devLazyRequest,devLazyActivated, parallelBuilds: !dev && config.experimental.parallelBuilds && await cssModules.parallelSafe() ? config.experimental.parallelBuilds : false });
+    if(manifest.devLazy){
+      const css=Object.values(manifest.devLazy.outputs).flatMap(module=>module.css);
+      for(const route of manifest.routes)if(route.router==='app'&&route.kind==='page'){
+        route.css=[...new Set([...route.css,...css])];
+        if(css.length&&Array.isArray(route.cssScopes)){
+          const root=route.cssScopes.find(scope=>scope.kind==='layout'&&!scope.path);
+          if(root)root.css=[...new Set([...root.css,...css])];
+          else route.cssScopes.push({kind:'layout',path:'',css:[...new Set(css)]});
+        }
+      }
+    }
     if(manifest.config.workerPreload)for(const pattern of config.workerPreload.routes){
       const selected=manifest.routes.find(route=>!route.internal&&route.pattern===pattern);
       if(!selected||selected.cacheConfig?.runtime==='edge'||selected.handlerConfig?.runtime==='edge')throw new Error(`workerPreload route ${pattern} must be an existing Node route.`);
@@ -311,14 +349,18 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
     await checkTypeScript(project.root, config, { dev, tsconfig });
     fonts.attach(manifest);
     expandLocales(manifest);
+    const imageResponse = await imageResponseRequirement(stage, {dev, manifest});
+    if (imageResponse.included) await prepareImageResponse(stage);
+    else await rm(path.join(stage, 'compat/og.cjs'), {force: true});
     // All runtime preparation must finish before its shared modules are built;
     // no staged renderer has been imported before this production-only point.
-    if (!dev) await bundleRuntime(stage,{projectRoot:project.root,sourceDirectory:path.join(packageRoot,'runtime')});
+    if (!dev) await bundleRuntime(stage,{projectRoot:project.root,sourceDirectory:path.join(packageRoot,'runtime'),imageResponse:imageResponse.included});
     // Node caches CJS React by filename, not NODE_ENV. Once development metadata
     // imports load it, subsequent production renders need a clean process too.
     if(dev) developmentModulesLoaded = true;
     if(!dev) Object.assign(manifest,await (incremental || developmentModulesLoaded ? isolatedPrerender : prerenderProduction)(project.root,stage,manifest,{prerender:config.prerender}));
     else {await prerender(stage, manifest, dev);await prerenderApp(stage, manifest, dev);}
+    if (!dev) await prepareNativePprShells(stage, manifest);
     const pages = manifest.routes.filter(route => route.kind === 'page' && route.router !== 'app' && !route.internal && !route.devDeferred);
     const publicPage = route => ({ ...(route.locale ? {locale:route.locale,originalPattern:route.originalPattern} : {}), id: route.id, pattern: route.pattern, client: route.client, css: route.css, ...(route.fonts ? { fonts: route.fonts } : {}), ssg: !!route.ssg, ssp: !!route.ssp, gip: !!route.gip, appGip: !!route.appGip });
     if (pages.length || manifest.pagesErrors) {
@@ -353,6 +395,7 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
       }
       const appRoute = manifest.routes.find(route => route.router === 'app' && route.kind === 'page' && route.client);
       await writeFile(path.join(stage, 'assets', path.basename(manifest.devClient)), JSON.stringify({ buildId,
+        ...(manifest.devLazy?{lazy:Object.values(manifest.devLazy.outputs)}:{}),
         pages: manifest.routes.filter(route => route.router !== 'app' && route.client).map(publicPage),
         ...(appRoute ? { app: { client: appRoute.client, css: appRoute.css, routes: manifest.routes.filter(route=>route.router==='app'&&route.kind==='page'&&route.client).map(({id,pattern,css,cssScopes})=>({id,pattern,css,cssScopes:cssScopes||[]})) } } : {}),
       }));
@@ -392,11 +435,14 @@ async function buildProject(projectRoot, { dev = false, envMode, incremental = f
       throw error;
     } finally { await rm(pointerTemporary, {force:true}); }
     await exported?.commit();
-    if (hadDestination) await rm(backup, { recursive: true, force: true });
+    await recovery?.committed().catch(()=>{});
+    if(!recovery&&hadDestination)await rm(backup,{recursive:true,force:true});
+    if(dev&&!devLazyRequest)rememberLazyBuildContext(project.root,{manifest,config,environment,tsconfig,envMode});
     return { ...manifest, outputDirectory: destination, durationMs: Math.round(performance.now() - started),reactCompilerReport:compilerReport,compilationCache };
   } catch (error) {
-    await rm(stage, { recursive: true, force: true });
+    if(!recovery)await rm(stage, { recursive: true, force: true });
     if (error.errors) error.message = error.errors.map(item => `${item.location ? `${item.location.file}:${item.location.line}: ` : ''}${item.text}`).join('\n');
     throw error;
   }
+  }finally{await recovery?.cleanup();}
 }

package/build/lazy-dynamic-imports.mjs

@@ -0,0 +1,137 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {createHash} from 'node:crypto';
+import {readFile,writeFile} from 'node:fs/promises';
+import {parse} from '@babel/parser';
+import traverseModule from '@babel/traverse';
+import generateModule from '@babel/generator';
+import * as t from '@babel/types';
+import {generateMapped} from './source-maps.mjs';
+
+const traverse=traverseModule.default||traverseModule;
+const generate=generateModule.default||generateModule;
+const packageRoot=fileURLToPath(new URL('../',import.meta.url));
+const client=fileURLToPath(new URL('../runtime/lazy-import-client.mjs',import.meta.url));
+export const LAZY_IMPORT_LIMIT=128;
+export const LAZY_BRIDGE_LIMIT=4096;
+const javascript=/\.(?:[cm]?[jt]s|[jt]sx)$/;
+// esbuild exposes JSON as an ESM entry with a shared default object and named
+// exports. Give it the same native URL identity as JavaScript export bridges.
+const bridgeable=file=>javascript.test(file)||file.endsWith('.json');
+const digest=value=>createHash('sha256').update(value).digest('hex').slice(0,24);
+const suffixError=()=>({errors:[{text:'lazyDynamicImports cannot safely defer a module with a query or fragment suffix. Disable experimental.lazyDynamicImports to compile this graph normally.'}]});
+
+/** Development-only graph boundaries. No source path is sent to the browser. */
+export function createLazyDynamicImports({root,stage,manifest,request,activated=[]}){
+  const modules=new Map(),bridges=new Map(),shared=new Set(),existingShared=new Set(),entries=new Map(),targetFiles=new Map(),nativeOutputs=new Map(),outputs={};
+  const active=new Set(activated);
+  if(active.size>LAZY_IMPORT_LIMIT)throw Error(`lazyDynamicImports supports at most ${LAZY_IMPORT_LIMIT} active imports`);
+  if(request){
+    if(!/^[a-f0-9]{24}$/.test(request.id)||!Array.isArray(request.modules)||request.modules.length>LAZY_IMPORT_LIMIT||!Array.isArray(request.bridges)||request.bridges.length>LAZY_BRIDGE_LIMIT||!Array.isArray(request.shared)||request.shared.length>LAZY_BRIDGE_LIMIT)throw Error('Invalid deferred import compiler descriptor');
+    for(const item of request.modules){
+      const file=path.resolve(root,item.importer);
+      if(!file.startsWith(root+path.sep)||file.includes(`${path.sep}node_modules${path.sep}`)||!javascript.test(file)||typeof item.request!=='string'||item.request.length>4096||item.id!==digest(item.importer+'\0'+item.request))throw Error('Invalid deferred import registration');
+      modules.set(item.id,item);
+    }
+    if(!modules.has(request.id))throw Error('Unknown deferred import identifier');
+    for(const item of request.bridges){
+      if(typeof item.file!=='string'||typeof item.url!=='string'||!item.url.startsWith(manifest.config.assetBase+'/')||/[\r\n\0]/.test(item.url))throw Error('Invalid deferred module bridge');
+      bridges.set(path.resolve(root,item.file),item.url);
+    }
+    for(const file of request.shared){const absolute=path.resolve(root,file);shared.add(absolute);existingShared.add(absolute);}
+    active.clear();active.add(request.id);
+  }
+  const sourceAst=(source,file)=>parse(source,{sourceType:'unambiguous',sourceFilename:file,plugins:['jsx',...(/\.[cm]?tsx?$/.test(file)?['typescript']:[])]});
+  const eligible=file=>file.startsWith(root+path.sep)&&!file.includes(`${path.sep}node_modules${path.sep}`)&&!file.includes(`${path.sep}.prnext-build-`);
+  function transform(source,file){
+    if(!eligible(file)||!source.includes('import'))return source;
+    const ast=sourceAst(source,file);let binding,changed=false;
+    const replace=node=>{
+      const value=t.isStringLiteral(node)?node.value:t.isTemplateLiteral(node)&&!node.expressions.length?node.quasis[0].value.cooked:undefined;
+      // Suffixes are part of ESM identity; path-only export bridges cannot
+      // represent them. Keep explicit suffixes in the ordinary compiler graph.
+      if(!value||value.length>4096||/[?#]/.test(value)||/^(?:[a-z]+:|\/\/)/i.test(value))return;
+      const importer=path.relative(root,file).split(path.sep).join('/'),id=digest(importer+'\0'+value);
+      if(!modules.has(id)&&modules.size>=LAZY_IMPORT_LIMIT)throw Error(`lazyDynamicImports supports at most ${LAZY_IMPORT_LIMIT} registered imports per generation`);
+      modules.set(id,{id,importer,request:value});
+      changed=true;return id;
+    };
+    traverse(ast,{Program(p){binding=p.scope.generateUidIdentifier('prnextLazyImport');},CallExpression(p){
+      if(!t.isImport(p.node.callee)||p.node.arguments.length!==1)return;
+      const id=replace(p.node.arguments[0]);if(id)p.replaceWith(t.callExpression(t.cloneNode(binding),[t.stringLiteral(id),t.stringLiteral(manifest.config.basePath||'')]));
+    },ImportExpression(p){if(p.node.options)return;const id=replace(p.node.source);if(id)p.replaceWith(t.callExpression(t.cloneNode(binding),[t.stringLiteral(id),t.stringLiteral(manifest.config.basePath||'')]));}});
+    if(!changed)return source;
+    ast.program.body.unshift(t.importDeclaration([t.importSpecifier(t.cloneNode(binding),t.identifier('lazyImport'))],t.stringLiteral(client)));
+    return generateMapped(generate,ast,{comments:true},source,file);
+  }
+  async function discover(metafile){
+    for(const input of Object.keys(metafile.inputs)){
+      const file=path.resolve(root,input);
+      if(!bridgeable(file)||input.startsWith('prnext-')||file.startsWith(packageRoot)||file.startsWith(stage+path.sep)||/\/node_modules\/(?:react|react-dom|react-refresh|react-server-dom-webpack)\//.test(file.split(path.sep).join('/'))||shared.has(file))continue;
+      if(shared.size>=LAZY_BRIDGE_LIMIT)throw Error(`lazyDynamicImports supports at most ${LAZY_BRIDGE_LIMIT} static JavaScript modules`);
+      shared.add(file);
+      // Real ESM entries expose live bindings. CommonJS named exports cannot be
+      // approximated with snapshots: a deferred graph sharing one is rejected.
+      if(file.endsWith('.json')||sourceAst(await readFile(file,'utf8'),file).program.sourceType==='module')bridges.set(file,undefined);
+    }
+  }
+  async function targetEntries(){
+    const result={};
+    for(const id of active){
+      if(!modules.has(id))continue;
+      const name='lazy-'+id,file=path.join(stage,'.entries',name+'.mjs');
+      await writeFile(file,`import * as namespace from ${JSON.stringify('prnext-lazy-entry:'+id)};export {namespace as __prnextLazyModule};`);
+      entries.set(file,{kind:'target',id});result[name]=file;
+    }
+    return result;
+  }
+  function bridgeEntries(){
+    const result=Object.fromEntries([...bridges].filter(([,url])=>!url).map(([file])=>{entries.set(file,{kind:'bridge',file});return ['lazy-bridge-'+digest(file),file];}));
+    for(const file of targetFiles.values())if(!bridges.has(file)&&bridgeable(file)){
+      entries.set(file,{kind:'native',file});result['lazy-native-'+digest(file)]=file;
+    }
+    return result;
+  }
+  function plugin(){return {name:'prnext-lazy-dynamic-boundaries',setup(builder){
+    builder.onResolve({filter:/^prnext-lazy-entry:/},async args=>{
+      const item=modules.get(args.path.slice('prnext-lazy-entry:'.length));
+      if(!item)return {errors:[{text:'Unknown deferred module entry'}]};
+      const result=await builder.resolve(item.request,{resolveDir:path.dirname(path.resolve(root,item.importer)),kind:'dynamic-import',pluginData:{prnextLazyEntry:true}});
+      if(!result.errors.length&&result.suffix)return suffixError();
+      const file=path.resolve(result.path||root),url=bridges.get(file);
+      if(!result.errors.length&&result.namespace==='file')targetFiles.set(item.id,file);
+      if(existingShared.has(file)&&!url)return {errors:[{text:`lazyDynamicImports cannot safely reuse the shared CommonJS module ${path.relative(root,file)}. Convert it to ESM or disable experimental.lazyDynamicImports.`}]};
+      return url?{path:url,external:true}:result;
+    });
+    if(request)builder.onResolve({filter:/.*/},async args=>{
+      if(args.pluginData?.prnextLazyResolving||args.pluginData?.prnextLazyEntry||args.kind==='entry-point'||args.namespace&&args.namespace!=='file')return;
+      const result=await builder.resolve(args.path,{resolveDir:args.resolveDir,importer:args.importer,kind:args.kind,with:args.with,pluginData:{...args.pluginData,prnextLazyResolving:true}});
+      // Aliases and transitive imports may introduce a suffix even when the
+      // registered literal had none. Reject it before looking up a bare bridge.
+      if(!result.errors.length&&result.suffix)return suffixError();
+      if(result.errors.length||result.external||result.namespace!=='file')return;
+      const file=path.resolve(result.path);
+      if(bridges.get(file))return {path:bridges.get(file),external:true};
+      if(existingShared.has(file))return {errors:[{text:`lazyDynamicImports cannot safely reuse the shared CommonJS module ${path.relative(root,file)}. Convert it to ESM or disable experimental.lazyDynamicImports.`}]};
+    });
+  }};}
+  function record(metadata,output){
+    const entry=entries.get(path.resolve(root,metadata.entryPoint||''));
+    if(!entry||!output.endsWith('.js'))return false;
+    const url=manifest.config.assetBase+'/'+path.basename(output);
+    if(entry.kind==='bridge'||entry.kind==='native'){
+      if(entry.kind==='bridge')bridges.set(entry.file,url);
+      nativeOutputs.set(entry.file,{url,css:metadata.cssBundle?[manifest.config.assetBase+'/'+path.basename(metadata.cssBundle)]:[]});
+    }
+    else outputs[entry.id]={url,css:metadata.cssBundle?[manifest.config.assetBase+'/'+path.basename(metadata.cssBundle)]:[]};
+    return true;
+  }
+  function finish(){
+    for(const [id,file]of targetFiles){
+      const native=nativeOutputs.get(file),url=native?.url||bridges.get(file);
+      if(url&&outputs[id])outputs[id]={url,native:true,css:[...new Set([...outputs[id].css,...(native?.css||[])])]};
+    }
+    manifest.devLazy={modules:[...modules.values()],bridges:[...bridges].filter(([,url])=>url).map(([file,url])=>({file:path.relative(root,file).split(path.sep).join('/'),url})),shared:[...shared].map(file=>path.relative(root,file).split(path.sep).join('/')),outputs};
+  }
+  return {transform,discover,targetEntries,bridgeEntries,plugin,record,finish};
+}

package/build/migrate.mjs

@@ -19,18 +19,18 @@ export function parseMigrationArgs(args) {
     const arg = args[index];
     if (arg === '--dry-run') options.dryRun = true;
     else if (arg === '--check') options.check = true;
-    else if (['--against', '--candidate', '--routes', '--timeout'].includes(arg)) {
+    else if (['--against', '--candidate', '--routes', '--timeout', '--browser-scenarios'].includes(arg)) {
       const value = args[++index];
       if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value.`);
-      options[arg.slice(2)] = arg === '--timeout' ? Number(value) : value;
+      options[arg === '--browser-scenarios' ? 'browserScenarios' : arg.slice(2)] = arg === '--timeout' ? Number(value) : value;
     }
     else if (arg === '--no-install') options.install = false;
     else if (arg === '--json') options.json = true;
-    else if (arg.startsWith('-')) throw new Error(`Unknown migrate option: ${arg}. Use --check, --dry-run, --no-install or --json.`);
+    else if (arg.startsWith('-')) throw new Error(`Unknown migrate option: ${arg}. Use --check, --dry-run, --no-install, --browser-scenarios or --json.`);
     else if (directory === undefined) directory = arg;
     else throw new Error('migrate accepts a single project directory.');
   }
-  if ((options.against || options.candidate || options.routes || options.timeout !== undefined) && (!options.check || !options.against || !options.candidate)) throw new Error('Server comparison requires --check, --against and --candidate.');
+  if ((options.against || options.candidate || options.routes || options.timeout !== undefined || options.browserScenarios) && (!options.check || !options.against || !options.candidate)) throw new Error('Server comparison or browser execution requires --check, --against and --candidate.');
   return { directory: path.resolve(directory || '.'), options };
 }