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

package/build/server-config.mjs

@@ -0,0 +1,35 @@
+import { isIP } from 'node:net';
+
+export function validateServerConfig(value) {
+  if (value === undefined) return { trustedProxies: [] };
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !['publicOrigin', 'trustedProxies'].includes(key))) {
+    throw new TypeError('server must be an object with publicOrigin and trustedProxies.');
+  }
+  let publicOrigin;
+  if (value.publicOrigin !== undefined) {
+    const source = value.publicOrigin;
+    let url;
+    try { url = new URL(source); } catch { /* validated below */ }
+    if (typeof source !== 'string' || /[\s\\\u0000-\u001f\u007f]/.test(source) || !url || !['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.pathname !== '/' || url.search || url.hash || source.includes('?') || source.includes('#')) {
+      throw new TypeError('server.publicOrigin must be an HTTP(S) origin without credentials, path, query or fragment, for example https://example.com.');
+    }
+    publicOrigin = url.origin;
+  }
+  const ranges = value.trustedProxies ?? [];
+  if (!Array.isArray(ranges) || ranges.length > 32 || ranges.some(range => {
+    if (typeof range !== 'string' || range.length > 64) return true;
+    const [address, bits, ...extra] = range.split('/');
+    const family = isIP(address);
+    return !family || extra.length || bits !== undefined && (!/^(0|[1-9]\d*)$/.test(bits) || Number(bits) > (family === 4 ? 32 : 128));
+  })) throw new TypeError('server.trustedProxies must contain at most 32 explicit IP addresses or CIDR ranges.');
+  const normalized = ranges.map(range => {
+    const [address, bits] = range.split('/');
+    if (isIP(address) !== 6) return range;
+    const mapped = /^\[::ffff:([\da-f]+):([\da-f]+)\]$/i.exec(new URL(`http://[${address}]`).hostname);
+    if (!mapped) return range;
+    if (bits !== undefined && Number(bits) < 96) throw new TypeError('Mapped IPv4 proxy CIDR ranges need a prefix of at least 96 bits.');
+    const high = parseInt(mapped[1], 16), low = parseInt(mapped[2], 16);
+    return `${high >>> 8}.${high & 255}.${low >>> 8}.${low & 255}${bits === undefined ? '' : '/' + (Number(bits) - 96)}`;
+  });
+  return { ...(publicOrigin ? { publicOrigin } : {}), trustedProxies: [...new Set(normalized)] };
+}

package/build/source-analysis.mjs

@@ -6,31 +6,81 @@ import {createHash} from 'node:crypto';
 const cache=new Map();
 let bytes=0,hits=0,misses=0;
 export const sourceAnalysisStats=()=>({entries:cache.size,bytes,hits,misses});
+const identifier=(node,name)=>node?.type==='Identifier'&&(name===undefined||node.name===name);
+const property=node=>node?.computed?node.property?.value:node?.property?.name;
+const moduleExports=node=>node?.type==='MemberExpression'&&identifier(node.object,'module')&&property(node)==='exports';
+function bindingNames(node,names){
+  if(!node)return;
+  if(identifier(node))names.add(node.name);
+  else if(node.type==='ObjectPattern')for(const item of node.properties)bindingNames(item.type==='RestElement'?item.argument:item.value,names);
+  else if(node.type==='ArrayPattern')for(const item of node.elements)bindingNames(item,names);
+  else if(node.type==='RestElement')bindingNames(node.argument,names);
+  else if(node.type==='AssignmentPattern')bindingNames(node.left,names);
+}
+function runtimeDeclaration(node,names){
+  if(!node||node.declare)return;
+  if(node.type==='VariableDeclaration')for(const item of node.declarations)bindingNames(item.id,names);
+  else if(['FunctionDeclaration','ClassDeclaration','TSEnumDeclaration','TSModuleDeclaration'].includes(node.type))bindingNames(node.id,names);
+}
 export function analyzeSource(source,file='source.js') {
   const key=file+'\0'+createHash('sha256').update(source).digest('hex');
   if(cache.has(key)){const hit=cache.get(key);cache.delete(key);cache.set(key,hit);hits++;return hit.value;}
   misses++;
-  const parsed=parseSync(file,source,{sourceType:'unambiguous',allowReturnOutsideFunction:true});
+  // Custom loaders also return JSX under their original asset filenames (for
+  // example .svg). Match the compiler's JSX fallback for non-TypeScript inputs,
+  // preserving TypeScript's extension rules, including angle assertions in .ts.
+  const parsed=parseSync(file,source,{sourceType:'unambiguous',allowReturnOutsideFunction:true,...(/\.(?:[cm]?ts|tsx)$/.test(file)?{}:{lang:'jsx'})});
   if(parsed.errors.length)throw new SyntaxError(`${file}: ${parsed.errors.map(error=>error.message).join('; ')}`);
   const program=parsed.program,directives=[];
   for(const node of program.body){if(!node.directive)break;directives.push(node.directive);}
-  const imports=[];
-  let computedRequire=false;
+  const imports=[],runtimeExports=new Set(),exportStars=[];
+  for(const node of program.body){
+    if(node.exportKind==='type')continue;
+    if(node.type==='ExportDefaultDeclaration'&&!node.declaration?.declare&&!['TSInterfaceDeclaration','TSTypeAliasDeclaration'].includes(node.declaration?.type))runtimeExports.add('default');
+    if(node.type==='ExportNamedDeclaration'){
+      runtimeDeclaration(node.declaration,runtimeExports);
+      for(const item of node.specifiers)if(item.exportKind!=='type')runtimeExports.add(item.exported.name??item.exported.value);
+    }
+    if(node.type==='ExportAllDeclaration'){
+      if(node.exported)runtimeExports.add(node.exported.name??node.exported.value);
+      else exportStars.push(node.source.value);
+    }
+  }
+  let computedRequire=false,hasServerDirective=false;
   const pending=[program];
   while(pending.length){
     const node=pending.pop();
+    if(node.directive==='use server')hasServerDirective=true;
     if(['ImportDeclaration','ExportNamedDeclaration','ExportAllDeclaration'].includes(node.type)&&node.source&&node.importKind!=='type'&&node.exportKind!=='type')imports.push({path:node.source.value,kind:'import-statement'});
     if(node.type==='ImportExpression'&&typeof node.source?.value==='string')imports.push({path:node.source.value,kind:'dynamic-import'});
     if(node.type==='CallExpression'&&node.callee?.type==='Identifier'&&node.callee.name==='require'){
       const argument=node.arguments[0];
       if(argument?.type==='Literal'&&typeof argument.value==='string')imports.push({path:argument.value,kind:'require-call'});else computedRequire=true;
     }
+    if(node.type==='CallExpression'&&node.callee?.type==='MemberExpression'&&identifier(node.callee.object,'Object')&&property(node.callee)==='defineProperty'&&identifier(node.arguments[0],'exports')&&typeof node.arguments[1]?.value==='string'&&node.arguments[1].value!=='__esModule'){
+      runtimeExports.add('default');runtimeExports.add(node.arguments[1].value);
+    }
+    if(node.type==='AssignmentExpression'&&node.left.type==='MemberExpression'){
+      const left=node.left;
+      if(moduleExports(left)){
+        runtimeExports.add('default');
+        if(node.right.type==='ObjectExpression')for(const item of node.right.properties){
+          const key=item.computed?item.key?.value:item.key?.name??item.key?.value;
+          if(typeof key==='string')runtimeExports.add(key);
+        }
+      }
+      if(identifier(left.object,'exports')||moduleExports(left.object)){
+        runtimeExports.add('default');if(typeof property(left)==='string')runtimeExports.add(property(left));
+      }
+    }
     for(const value of Object.values(node)){
       if(Array.isArray(value)){for(let i=value.length-1;i>=0;i--)if(value[i]?.type)pending.push(value[i]);}
       else if(value&&typeof value==='object'&&value.type)pending.push(value);
     }
   }
-  const value={program,directives,imports,computedRequire,frameworkBoundary:directives.some(item=>item==='use client'||item==='use server')};
+  runtimeExports.delete('__esModule');
+  const value=Object.freeze({program,directives:Object.freeze(directives),imports:Object.freeze(imports.map(Object.freeze)),computedRequire,hasServerDirective,
+    runtimeExports:Object.freeze([...runtimeExports]),exportStars:Object.freeze(exportStars),frameworkBoundary:directives.some(item=>item==='use client'||item==='use server')});
   // ASTs are substantially larger than source. Bound both count and estimated
   // retained size; large individual npm modules are analyzed without retention.
   const size=Buffer.byteLength(source)*16+Buffer.byteLength(file);

package/build/standalone.mjs

@@ -1,5 +1,6 @@
-import { nodeFileTrace } from '@vercel/nft';
-import resolver from '@vercel/nft/out/resolve-dependency.js';
+import { nodeFileTrace } from '../vendor/nft/out/index.js';
+import resolver from '../vendor/nft/out/resolve-dependency.js';
+import { CachedFileSystem } from '../vendor/nft/out/fs.js';
 import picomatch from 'picomatch';
 import { mkdir, readFile, writeFile, readdir, realpath, readlink, stat, lstat, copyFile, chmod, symlink, cp } from 'node:fs/promises';
 import path from 'node:path';
@@ -12,6 +13,10 @@ const within = (root, file) => file === root || file.startsWith(root + path.sep)
 const missing = error => error.code === 'ENOENT' || error.code === 'ENOTDIR';
 const maxFiles = 100_000;
 const maxBytes = 2 * 1024 ** 3;
+const linuxRuntimeProbes = new Set([
+  '/proc/self', '/proc/self/exe', '/usr/bin/ldd',
+  '/proc/version', '/proc/self/cgroup', '/.dockerenv', '/run/.containerenv',
+]);
 
 export async function resolveTraceDependency(...args) {
   const result = await resolver.default(...args);
@@ -75,6 +80,10 @@ export async function createStandalone({ projectRoot, stage, manifest, config })
   const warnings = new Set();
   let omittedWarnings = 0;
   const cache = {};
+  const traceFileSystem = new CachedFileSystem({ cache, fileIOConcurrency: 16 });
+  // libc and environment detectors read the running host, not application assets.
+  // Keep this exact and outside the tracing root; other external files still fail.
+  const systemProbe = file => process.platform === 'linux' && !within(tracingRoot, file) && linuxRuntimeProbes.has(file);
   const traceLocations = new Map();
   let traceReads = 0;
   let traceBytes = 0;
@@ -120,7 +129,16 @@ export async function createStandalone({ projectRoot, stage, manifest, config })
     for (const conditions of [['node'], ['node', 'react-server']]) {
       const result = await nodeFileTrace(entries, {
         base: path.parse(projectRoot).root, processCwd: projectRoot, conditions, cache, fileIOConcurrency: 16,
-        ignore(file) { const absolute = path.resolve(path.parse(projectRoot).root, file); return !within(stage, absolute) && (excluded.some(match => match(slash(absolute))) || /^\.env(?:\.|$)/.test(path.basename(absolute))); },
+        ignore(file) { const absolute = path.resolve(path.parse(projectRoot).root, file); return systemProbe(absolute) || !within(stage, absolute) && (excluded.some(match => match(slash(absolute))) || /^\.env(?:\.|$)/.test(path.basename(absolute))); },
+        // Share the metadata concurrency limit between stat and readlink.
+        stat: file => traceFileSystem.stat(file),
+        async readlink(file) {
+          // NFT follows symlinks before ignore(), so never follow these probes
+          // into /proc/<pid> or the build machine's Node executable.
+          if (systemProbe(file)) return null;
+          try { return await traceFileSystem.readlink(file); }
+          catch (error) { if (error.code === 'ENOTDIR') return null; throw error; }
+        },
         async readFile(file) {
           let info;
           try { info = await stat(file); } catch (error) { if (missing(error)) return null; throw error; }

package/build/static-adapter.mjs

@@ -7,6 +7,8 @@ import { OUTPUT_POINTER, prepareBuildDirectory, readBuildDirectory, validateDist
 import { writeBuildOutput } from './output-contract.mjs';
 import { precompressBuild } from './precompress.mjs';
 import { withBuildLock } from './build-lock.mjs';
+import {withCompilationStorage} from './compilation-storage.mjs';
+import {reclaimBuildStages,trackBuildStage} from './build-retention.mjs';
 import { plainStaticPath } from './static-input.mjs';
 
 const MAX_FILES = 20000, MAX_BYTES = 512 * 1024 * 1024;
@@ -15,7 +17,7 @@ const urlFor = file => '/' + file.split('/').map(encodeURIComponent).join('/');
 
 /** Import an already-built public directory. Never evaluate its config or code. */
 export async function buildStatic(directory, { from = 'dist', spa = false, distDir, dev = false } = {}) {
-  return withBuildLock(directory, root => importStatic(root, { from, spa, distDir, dev }));
+  return withBuildLock(directory, async root => {await reclaimBuildStages(root);return withCompilationStorage(root,()=>importStatic(root, { from, spa, distDir, dev }));});
 }
 
 async function importStatic(directory, { from, spa, distDir, dev }) {
@@ -41,6 +43,7 @@ async function importStatic(directory, { from, spa, distDir, dev }) {
 
   const id = randomUUID(), stage = path.join(root, `.prnext-build-${id}`);
   const backup = path.join(root, `.prnext-backup-${id}`), pointer = path.join(root, `.prnext-output-${id}.tmp`);
+  const recovery=await trackBuildStage(root,{stage,backup}).catch(()=>null);
   const manifest = { version: 1, buildId: id, config: { staticOnly: true, staticFallback: spa, compress: true, poweredByHeader: true }, routes: [], prerendered: [] };
   const paths = new Set();
   let count = 0, bytes = 0, previous = false, published = false;
@@ -99,10 +102,11 @@ async function importStatic(directory, { from, spa, distDir, dev }) {
       if (previous) await rename(backup, destination);
       throw error;
     }
-    if (previous) await rm(backup, { recursive: true, force: true });
+    await recovery?.committed().catch(()=>{});
+    if (!recovery&&previous) await rm(backup, { recursive: true, force: true });
     return { ...manifest, outputDirectory: destination, files: count, bytes };
   } finally {
     await rm(pointer, { force: true });
-    await rm(stage, { recursive: true, force: true });
+    if(recovery)await recovery.cleanup();else await rm(stage, { recursive: true, force: true });
   }
 }

package/build/transform.mjs

@@ -37,17 +37,49 @@ function relativeChunksUncached(source,chunks,prefix) {
   return source;
 }
 
+function rewriteChunkSource(source,map,file,chunks,publicPath){
+  const result=relativeServerChunkImports(inlineSourceMap(source,map),chunks,publicPath);
+  if(map){
+    const mapped=extractSourceMap(result);
+    return {source:mapped.code.replace(/\/\/[#@]\s*sourceMappingURL=[^\s]+/g,'')+'\n//# sourceMappingURL='+path.basename(file)+'.map\n',map:JSON.stringify({...mapped.map,file:path.basename(file)})};
+  }
+  return {source:result};
+}
+
+/** Rewrite before the first disk write, without modifying compiler/cache buffers. */
+export function rewriteServerChunkOutputFiles(files,chunks,publicPath,importers){
+  const outputs=new Map(files.map(file=>[path.resolve(file.path),file])),replacements=new Map();
+  const replace=(file,source)=>{
+    const contents=Buffer.from(source),metadata=Object.getOwnPropertyDescriptors(file);
+    // esbuild's hash describes the original buffer. Do not retain a stale hash.
+    // Reading/spreading esbuild's lazy text getter would decode the old buffer
+    // again and retain that string even though only the new bytes are needed.
+    delete metadata.hash;delete metadata.contents;delete metadata.text;
+    const output=Object.create(Object.getPrototypeOf(file),metadata);
+    Object.defineProperties(output,{contents:{value:contents,writable:true,enumerable:true,configurable:true},text:{get(){return this.contents.toString();},enumerable:true,configurable:true}});
+    replacements.set(file,output);
+  };
+  for(const file of files){
+    if(!file.path.endsWith('.mjs')||importers&&!importers.has(path.resolve(file.path)))continue;
+    const source=Buffer.from(file.contents.buffer,file.contents.byteOffset,file.contents.byteLength).toString();
+    if(!source.includes(publicPath.replace(/\/+$/,'')+'/'))continue;
+    const mapFile=sourceMapsEnabled()&&outputs.get(path.resolve(file.path+'.map'));
+    const map=mapFile?JSON.parse(Buffer.from(mapFile.contents).toString()):undefined;
+    const result=rewriteChunkSource(source,map,file.path,chunks,publicPath);
+    if(result.source!==source)replace(file,result.source);
+    if(mapFile)replace(mapFile,result.map);
+  }
+  return files.map(file=>replacements.get(file)||file);
+}
+
 export async function rewriteServerChunks(file,chunks,publicPath){
   const source=await readFile(file,'utf8');
   if(!source.includes(publicPath.replace(/\/+$/,'')+'/'))return;
   let map;
   if(sourceMapsEnabled())try{map=JSON.parse(await readFile(file+'.map','utf8'));}catch(error){if(error.code!=='ENOENT')throw error;}
-  const result=relativeServerChunkImports(inlineSourceMap(source,map),chunks,publicPath);
-  if(map){
-    const mapped=extractSourceMap(result);
-    await writeFile(file+'.map',JSON.stringify({...mapped.map,file:path.basename(file)}));
-    await writeFile(file,mapped.code.replace(/\/\/[#@]\s*sourceMappingURL=[^\s]+/g,'')+'\n//# sourceMappingURL='+path.basename(file)+'.map\n');
-  }else await writeFile(file,result);
+  const result=rewriteChunkSource(source,map,file,chunks,publicPath);
+  if(map)await writeFile(file+'.map',result.map);
+  await writeFile(file,result.source);
 }
 
 function parserOptions(filename) {

package/build/typescript-dev.mjs

@@ -3,7 +3,7 @@ import {access} from 'node:fs/promises';
 import {resolveTypeScript} from './typescript-toolchain.mjs';
 import path from 'node:path';
 import {privateCacheDirectory} from './persistent-cache.mjs';
-export async function startTypeChecker(root,config,notify,{fork:spawnChecker=fork,recheckDelayMs=3000}={}){
+export async function startTypeChecker(root,config,notify,{fork:spawnChecker=fork,recheckDelayMs=3000,onBeforeChild=()=>{},onChild=()=>{}}={}){
   const noop={inactive:true,async close(){}};
   if(config.typescript?.devChecks===false)return noop;
   const filename=path.resolve(root,config.typescript?.tsconfigPath||'tsconfig.json');try{await access(filename);}catch{return noop;}
@@ -13,7 +13,9 @@ export async function startTypeChecker(root,config,notify,{fork:spawnChecker=for
   function launch(){
     if(closed)return;
     const worker=toolchain.native?'./typescript-native-worker.mjs':'./typescript-dev-worker.mjs';
+    const ticket=onBeforeChild();
     child=spawnChecker(new URL(worker,import.meta.url),[toolchain.compiler,filename,toolchain.native?'watch':directory?path.join(directory,'project.tsbuildinfo'):''],{cwd:root,execArgv:['--max-old-space-size=512'],stdio:['ignore','ignore','pipe','ipc'],windowsHide:true});
+    onChild(child,ticket);
     const current=child;
     let details='',healthyAt=0;child.stderr.on('data',chunk=>{details=(details+chunk).slice(-2048);});
     child.on('message',message=>{

package/build/webpack-graph.mjs

@@ -77,6 +77,13 @@ function pluginIdentity(plugin,webpack){
 export const webpackCompilerStats=()=>({contexts:sessions.size,created,reused,limit:sessionLimit,buildLimit:sessionBuildLimit});
 function queued(callback){const task=graphQueue.then(callback);graphQueue=task.catch(()=>{});return task;}
 export function closeWebpackCompiler(root){return queued(async()=>{
+  if(root!==undefined){
+    try{root=await realpath(root);}
+    catch(error){
+      if(error.code!=='ENOENT'&&error.code!=='ENOTDIR')throw error;
+      root=path.resolve(root);
+    }
+  }
   const closing=[];for(const[key,session]of sessions)if(root===undefined||session.root===root){sessions.delete(key);closing.push(session.dispose());}
   const results=await Promise.allSettled(closing),errors=results.filter(result=>result.status==='rejected').map(result=>result.reason);
   if(errors.length)throw new AggregateError(errors,'Unable to dispose webpack compiler sessions');
@@ -84,6 +91,9 @@ export function closeWebpackCompiler(root){return queued(async()=>{
 
 async function compileGraph(resolver,loads,options,{state,config,target}){
   return queued(async()=>{
+    // Ownership uses one canonical identity for invalidation and disposal.
+    // Compiler paths and graph fingerprints retain the caller's lexical root.
+    const ownerRoot=await realpath(state.root);
     const webpack=(await import('webpack')).default;
     let reusable=state.dev&&state.incremental,identity;
     if(reusable){try{identity=await buildCacheIdentity(state.root);}catch{}if(!identity)reusable=false;}
@@ -97,17 +107,17 @@ async function compileGraph(resolver,loads,options,{state,config,target}){
     // Unknown data structures, safe mode and unavailable identities all keep
     // compilation correct through a one-shot compiler. Hidden mutable closure
     // state cannot be fingerprinted: replace the plugin instance when it changes.
-    if(state.dev&&!reusable)for(const[key,session]of sessions)if(session.root===state.root){sessions.delete(key);await session.dispose();}
+    if(state.dev&&!reusable)for(const[key,session]of sessions)if(session.root===ownerRoot){sessions.delete(key);await session.dispose();}
     let session=reusable&&sessions.get(key);
     if(session&&session.builds>=sessionBuildLimit){sessions.delete(key);await session.dispose();session=undefined;}
     if(reusable){
-      for(const[old,previous]of sessions)if(previous.root===state.root&&(previous.identity!==identity||previous.base===base&&old!==key)){sessions.delete(old);await previous.dispose();}
+      for(const[old,previous]of sessions)if(previous.root===ownerRoot&&(previous.identity!==identity||previous.base===base&&old!==key)){sessions.delete(old);await previous.dispose();}
     }
     if(session){sessions.delete(key);reused++;}
     else{
       if(reusable)while(sessions.size>=sessionLimit){const[old,previous]=sessions.entries().next().value;sessions.delete(old);await previous.dispose();}
       session=await createGraphSession(state.root,{webpack,reusable,stage:state.stage});created++;
-      Object.assign(session,{root:state.root,base,identity,builds:0});
+      Object.assign(session,{root:ownerRoot,base,identity,builds:0});
     }
     if(reusable)sessions.set(key,session);
     try{session.builds++;return await session.run(resolver,loads,options,{state,config,target});}

package/cli.mjs

@@ -38,12 +38,15 @@ Use prnext for portable scripts; prn is a shortcut on compatible shells.
   prnext docs --ai [topic]              Read the AI guide bundled with this version
   prnext docs --ai --init [directory]   Add a guide pointer to the project's AGENTS.md
   prnext routes [directory]             Display compiled routes
-  prnext check [directory] [--json]      Diagnose config, routes, Node, native and dependencies
+  prnext check [directory] [--production] [--json]  Check config, deployment and dependencies
   prnext typegen [directory] [--json]    Generate route types without building the app
   prnext typecheck [directory] [--json]  Generate types and check TypeScript without building
   prnext inspect [directory] [--json|--otlp] Explain routes, health and sampled timings
   prnext analyze [directory] [--json] [--max-js 150]  Browser bundles and budget (kB)
   prnext compiler [directory] [--json]  React Compiler results from the last successful build
+  prnext cache [directory] [--json]     Show compilation cache sizes and disk budget
+  prnext cache [directory] --prune [--dry-run] [--max-bytes N] [--json]
+                                       Reclaim regenerable compilation caches
   prnext host [prnext.host.json]         Host built apps by hostname; wake on demand
   prnext host [config] --check           Validate hosting configuration and builds
   prnext host [config] --status [--json]  Show memory, process and idle status
@@ -58,6 +61,8 @@ Migration options: --dry-run (preview), --no-install (prepare only), --json
   prnext migrate --check                Audit source compatibility without migrating
   prnext migrate --check --against URL --candidate URL [--routes paths.json]
                                        Compare GET responses before switching
+  prnext migrate --check --against URL --candidate URL --browser-scenarios ./scenarios.mjs
+                                       Run trusted application browser assertions
 Migration keeps Next.js and backs up package.json and existing lockfiles.
 Simple next dev/build/start scripts become prnext commands; custom shell scripts need a manual edit.
 Installation honors npm, pnpm, Yarn Classic/Berry and the workspace root.
@@ -107,6 +112,10 @@ function stop(child) {
 async function main() {
   if (['help', '--help', '-h'].includes(command)) { console.log(help); return; }
   if (['--version', '-v'].includes(command)) { console.log(packageManifest.version); return; }
+  if(command==='cache'){
+    const {cacheCommand}=await import('./build/cache-command.mjs');
+    await cacheCommand(argv);return;
+  }
   if (command === 'create') {
     const { createHelp, parseCreateArgs, createProject } = await import('./build/create.mjs');
     if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) { console.log(createHelp); return; }
@@ -191,13 +200,20 @@ async function main() {
         report.comparison = await compareServers({ ...options, routes });
         report.ok &&= report.comparison.ok;
       }
+      if (options.browserScenarios) {
+        const { runMigrationScenarios } = await import('./build/migration-scenarios.mjs');
+        report.browser = await runMigrationScenarios({ directory, ...options, scenarios: options.browserScenarios });
+        report.ok &&= report.browser.ok;
+      }
       if (options.json) console.log(JSON.stringify(report, null, 2));
       else {
         console.log(`PRNext migration check ${report.ok ? 'passed' : 'failed'}: ${directory}`);
         console.log(`${report.files} source files; ${report.routes.length} routes.`);
         for (const item of report.findings) console.log(`${item.severity.toUpperCase()} ${item.file || 'project'}${item.line ? ':' + item.line : ''}: ${item.message}\n  ${item.action}`);
         for (const result of report.comparison?.results || []) console.log(`${result.equal ? 'MATCH' : 'DIFFERENT'} ${result.route}: ${result.error || result.differences.join(', ') || 'responses match'}`);
-        for (const note of [...report.notes, ...(report.comparison ? [report.comparison.scope] : [])]) console.log(note);
+        for (const result of report.browser?.results || []) console.log(`BROWSER ${result.scenario} (${result.target}): ${result.status}${result.reason ? ' — ' + result.reason : ''}`);
+        if (report.browser?.reason) console.log(`BROWSER unknown: ${report.browser.reason}`);
+        for (const note of [...report.notes, ...(report.comparison ? [report.comparison.scope] : []), ...(report.browser ? [report.browser.scope] : [])]) console.log(note);
       }
       if (!report.ok) process.exitCode = 1;
       return;
@@ -304,12 +320,12 @@ async function main() {
     process.env.PWD = root;
   }
   if (command === 'check') {
-    if (args.some(arg => arg !== '--json')) throw new Error('check accepts only [directory] and --json');
+    if (args.some(arg => !['--json','--production'].includes(arg))||new Set(args).size!==args.length) throw new Error('check accepts [directory], --production and --json once each');
     const { checkProject } = await import('./build/check.mjs');
-    const report = await checkProject(root);
+    const report = await checkProject(root,{production:args.includes('--production')});
     if (args.includes('--json')) console.log(JSON.stringify(report, null, 2));
     else {
-      console.log(`PRNext preflight ${report.ok ? 'passed' : 'failed'}: ${root}`);
+      console.log(`PRNext ${report.mode==='production'?'production ':''}preflight ${report.ok ? 'passed' : 'failed'}: ${root}`);
       console.log(`${report.routes.length} routes. Installed versions: ${Object.entries(report.versions).map(([name,version])=>`${name}@${version||'missing'}`).join(', ')}`);
       for (const item of report.diagnostics) {
         const output = item.severity === 'error' ? console.error : console.log;
@@ -371,7 +387,9 @@ async function main() {
   const binary = await resolveNativeBinary();
   if(command==='dev') {const {develop}=await import('./runtime/development.mjs');await develop(root,args,binary);return;}
   const outputDirectory = await readBuildDirectory(root);
-  const serverEnvironment = {...process.env,NODE_ENV:process.env.NODE_ENV||'production'};
+  const serverEnvironment = command==='start'
+    ? (await import('./runtime/env.mjs')).productionEnvironment(root)
+    : {...process.env,NODE_ENV:process.env.NODE_ENV||'production'};
   if(command==='start'&&serverEnvironment.NODE_ENV!=='development'){
     if(replaceWithNative(binary,['start',root,'--worker',path.join(root,outputDirectory,'runtime/worker.mjs'),
       '--node',process.execPath,...args],serverEnvironment))return;

package/compat/app-dynamic.cjs

@@ -19,7 +19,18 @@ function dynamic(input, options) {
   if (!opts.ssr && typeof React.useEffect !== 'function') {
     throw new Error('ssr: false is not supported with next/dynamic in Server Components. Move it into a Client Component.');
   }
-  const Lazy = React.lazy(() => Promise.resolve().then(opts.loader).then(moduleOf));
+  let Lazy;
+  if(process.env.NODE_ENV==='development'&&typeof window!=='undefined'&&typeof opts.__prnextDevIdentity==='string'){
+    const registry=globalThis.__PRNEXT_DEV_DYNAMIC__||=new Map();
+    let entry=registry.get(opts.__prnextDevIdentity);
+    if(!entry||entry.failed){
+      entry={loader:opts.loader};
+      entry.lazy=React.lazy(()=>Promise.resolve().then(()=>entry.loader()).then(moduleOf,error=>{entry.failed=true;throw error;}));
+      if(registry.size>=2048)registry.delete(registry.keys().next().value);
+      registry.set(opts.__prnextDevIdentity,entry);
+    }else entry.loader=opts.loader;
+    Lazy=entry.lazy;
+  }else Lazy=React.lazy(() => Promise.resolve().then(opts.loader).then(moduleOf));
   function DynamicComponent(props) {
     const fallback = opts.loading ? React.createElement(opts.loading, { isLoading: true, pastDelay: true, error: null }) : null;
     const child = React.createElement(Lazy, props);

package/compat/app-layout-context.cjs

@@ -12,17 +12,21 @@ function ActivitySlot({ identity, children, authorizationKey }) {
   const router = React.useContext(AppRouterContext);
   const epoch = retention?.epoch ?? 0;
   const authorizationEpoch = retention?.authorizationEpoch ?? 0;
+  const flight = retention?.flight;
   const registrations = React.useRef(new Set());
   const serial = React.useRef(0);
   const [saved, setSaved] = React.useState(() => ({ epoch, authorizationEpoch, active: identity, entries: new Map() }));
   let entries = saved.entries;
   const current = entries.get(identity);
-  if (saved.epoch !== epoch || saved.authorizationEpoch !== authorizationEpoch || current?.children !== children || current?.router !== router || current?.authorizationKey !== authorizationKey) {
+  const incompleteInactive = [...entries].some(([key, entry]) => key !== identity && entry.flight?.complete === false);
+  if (saved.epoch !== epoch || saved.authorizationEpoch !== authorizationEpoch || current?.children !== children || current?.router !== router || current?.authorizationKey !== authorizationKey || current?.flight !== flight || incompleteInactive) {
     const sameAuthorization = saved.authorizationEpoch === authorizationEpoch && !(current?.authorizationKey && authorizationKey && current.authorizationKey !== authorizationKey);
-    entries = saved.epoch === epoch && sameAuthorization ? new Map(entries) : new Map();
+    // Aborted lazy Flight rows cannot remain in an inactive Activity. Restore
+    // complete siblings while keeping the current shared layout's React key.
+    entries = saved.epoch === epoch && sameAuthorization ? new Map([...entries].filter(([key, entry]) => key === identity || entry.flight?.complete !== false)) : new Map();
     const preserve = current && saved.authorizationEpoch === authorizationEpoch && (sameAuthorization && (saved.epoch === epoch || saved.active === identity)
       || !retention?.strictAuthorization && saved.active === identity);
-    entries.set(identity, { children, router, authorizationKey, token: preserve ? current.token : {}, reactKey: preserve ? current.reactKey : ++serial.current });
+    entries.set(identity, { children, router, authorizationKey, flight, token: preserve ? current.token : {}, reactKey: preserve ? current.reactKey : ++serial.current });
     setSaved({ epoch, authorizationEpoch, active: identity, entries });
   }
   React.useLayoutEffect(() => {

package/compat/cache-handlers.cjs

@@ -80,7 +80,9 @@ async function read(entry, context) {
       if (size > MAX_BYTES) throw new Error('CacheEntry exceeds 2 MiB');
       chunks.push(Buffer.from(value));
     }
-    return Buffer.concat(chunks, size);
+    // Buffer.from above owns each chunk even when a custom producer reuses its
+    // Uint8Array on the next pull. Keep that copy, but do not copy it twice.
+    return chunks.length===1?chunks[0]:Buffer.concat(chunks, size);
   } finally {
     if (!complete) void reader.cancel().catch(() => {});
     reader.releaseLock();

package/compat/flight-delta.cjs

@@ -3,7 +3,7 @@
 const WINDOW = 32, MAX_VALUE = 2 * 1024 * 1024, MAX_RESPONSE = 16 * 1024 * 1024;
 const TYPE = 'application/x-prnext-flight-delta';
 const MAGIC = new Uint8Array([80,82,68,49]);
-const BLOCK_BYTES = 32 * 1024, MAX_COMMANDS_PER_CHUNK = 256, MAX_COMMANDS = 2048;
+const BLOCK_BYTES = 32 * 1024, MAX_COMMANDS_PER_CHUNK = 256, MAX_COMMANDS = 2048, MAX_CAPTURE_PARTS = 2048;
 let POWER = 1; for(let n=1;n<WINDOW;n++) POWER = Math.imul(POWER,31) >>> 0;
 function hash(bytes,offset) { let result=0; for(let n=0;n<WINDOW;n++) result=(Math.imul(result,31)+bytes[offset+n])>>>0; return result; }
 function createIndex(base) {
@@ -44,22 +44,59 @@ function blocks(parts) {
   for(const part of parts)for(let offset=0;offset<part.length;){const n=Math.min(BLOCK_BYTES-size,part.length-offset);pending.push(part.subarray(offset,offset+n));size+=n;offset+=n;if(size===BLOCK_BYTES)flush();}
   flush();return output;
 }
-function collectStream(source,{onComplete,onCancel,onFinally,capture=true}={}) {
-  const reader=source.getReader(), parts=[];let size=0,complete=false,finished=false;
+// Only the worker bridge registers streams here. Their backing allocations
+// crossed a transfer boundary, have no producer aliases, and the framework's
+// outgoing transport does not mutate or transfer them again. Arbitrary React,
+// fetch and application streams retain the defensive per-chunk copy.
+// Even an owned partial view is copied: retaining its much larger backing
+// allocation would defeat the byte-based capture limit.
+const ownedStreams=new WeakSet();
+function ownFlightStream(source){ownedStreams.add(source);return source;}
+function collectStream(source,{onComplete,onEnd,onCancel,onFinally,capture=true}={}) {
+  const owned=ownedStreams.has(source);
+  const reader=source.getReader(), parts=[];let size=0,complete=false,finished=false,cancelled=false;
   const finish=()=>{if(!finished){finished=true;onFinally?.();}};
   return new ReadableStream({
-    async pull(controller) {try{const next=await reader.read();if(next.done){complete=true;if(capture&&size<=MAX_VALUE)onComplete?.(join(parts,size));parts.length=0;finish();controller.close();return;}if(!(next.value instanceof Uint8Array))throw new Error('Invalid Flight bytes');size+=next.value.length;if(size>MAX_RESPONSE)throw new Error('Flight exceeds transport budget');if(capture&&size<=MAX_VALUE)parts.push(next.value.slice());else parts.length=0;controller.enqueue(next.value);}catch(error){parts.length=0;finish();controller.error(error);await reader.cancel(error).catch(()=>{});}},
-    async cancel(reason){parts.length=0;finish();if(!complete)onCancel?.();await reader.cancel(reason);},
+    async pull(controller) {
+      try {
+        const next=await reader.read();
+        if(cancelled)return;
+        if(next.done){
+          complete=true;
+          if(capture)onComplete?.(join(parts,size));
+          parts.length=0;onEnd?.();finish();controller.close();return;
+        }
+        const value=next.value;
+        if(!(value instanceof Uint8Array))throw new Error('Invalid Flight bytes');
+        size+=value.length;
+        if(size>MAX_RESPONSE)throw new Error('Flight exceeds transport budget');
+        if(capture){
+          // Limits include the number of retained allocations, not just their
+          // payload bytes. An abandoned capture never interrupts the response.
+          if(size>MAX_VALUE||value.length&&parts.length>=MAX_CAPTURE_PARTS){capture=false;parts.length=0;}
+          else if(value.length){
+            const wholeOwned=owned&&value.buffer instanceof ArrayBuffer&&value.byteOffset===0&&value.byteLength===value.buffer.byteLength;
+            // Buffer.slice() aliases its producer's backing allocation. The
+            // plain Uint8Array constructor always copies just the visible bytes.
+            parts.push(wholeOwned?value:new Uint8Array(value));
+          }
+        }
+        controller.enqueue(value);
+      }catch(error){parts.length=0;finish();if(cancelled)return;controller.error(error);await reader.cancel(error).catch(()=>{});}
+    },
+    async cancel(reason){cancelled=true;parts.length=0;finish();if(!complete)onCancel?.();await reader.cancel(reason);},
   },{highWaterMark:0});
 }
 async function deltaStream(source,base,{assess}={}) {
   const reader=source.getReader(), first=await reader.read();
   if(first.done)return {delta:false,body:new ReadableStream({start(c){c.close();}})};
-  let index=base instanceof Uint8Array&&base.length<=MAX_VALUE?createIndex(base):null;
-  const profitable=(raw,frames,initial)=>frames&&frames.reduce((n,b)=>n+b.length,0)+(initial?5:1)<raw.length*0.9&&(!assess||assess(raw,join(initial?[MAGIC,...frames,new Uint8Array([2])]:frames,frames.reduce((n,b)=>n+b.length,0)+(initial?5:0)))===true);
+  // A short first chunk always selects ordinary Flight. Do not build a base
+  // index that this response cannot use, or wait for a later streaming chunk.
+  let index=first.value.length>=WINDOW&&base instanceof Uint8Array&&base.length<=MAX_VALUE?createIndex(base):null;
+  const profitable=async(raw,frames,initial)=>frames&&frames.reduce((n,b)=>n+b.length,0)+(initial?5:1)<raw.length*0.9&&(!assess||await assess(raw,join(initial?[MAGIC,...frames,new Uint8Array([2])]:frames,frames.reduce((n,b)=>n+b.length,0)+(initial?5:0)))===true);
   const firstFrames=index&&first.value.length>=WINDOW?encodeChunk(first.value,base,index):null;
   let useDelta;
-  try{useDelta=!!profitable(first.value,firstFrames,true);}catch(error){await reader.cancel(error).catch(()=>{});throw error;}
+  try{useDelta=!!(await profitable(first.value,firstFrames,true));}catch(error){await reader.cancel(error).catch(()=>{});throw error;}
   let pending=useDelta?blocks([MAGIC,...firstFrames]):[first.value], pendingAt=0,ended=false,tail=false,commands=firstFrames?.commands||0;
   if(!useDelta){base=undefined;index=undefined;}
   return {delta:!!useDelta,body:new ReadableStream({
@@ -67,7 +104,7 @@ async function deltaStream(source,base,{assess}={}) {
       if(pendingAt===pending.length&&!ended){pending=[];pendingAt=0;const next=await reader.read();
         if(next.done){ended=true;if(useDelta&&!tail)pending=[new Uint8Array([2])];}
         else if(useDelta&&!tail){const encoded=encodeChunk(next.value,base,index);commands+=encoded?.commands||0;
-          if(commands>MAX_COMMANDS||!profitable(next.value,encoded,false)){tail=true;index=undefined;base=undefined;pending=blocks([new Uint8Array([3]),next.value]);}
+          if(commands>MAX_COMMANDS||!await profitable(next.value,encoded,false)){tail=true;index=undefined;base=undefined;pending=blocks([new Uint8Array([3]),next.value]);}
           else pending=blocks(encoded);
         }else pending=[next.value];
       }
@@ -132,19 +169,19 @@ function createFlightTransport() {
   let current,serial=0;
   return {
     snapshot(){return current;},
-    async response(response,base) {
+    async response(response,base,{onEnd}={}) {
       const version=++serial;
       const token=response.headers.get('x-prnext-flight-token'), headers=new Headers(response.headers);
       let source=response.body;
-      if(!source)return response;
+      if(!source){onEnd?.();return response;}
       if(headers.get('content-type')?.startsWith(TYPE)) {
         if(!base||headers.get('x-prnext-flight-base')!==base.token){await source.cancel();throw new Error('Missing Flight delta base');}
         source=decodeStream(source,base.bytes);
       }
       headers.set('content-type','text/x-component; charset=utf-8');headers.delete('content-length');headers.delete('content-encoding');
-      return new Response(collectStream(source,{capture:!!token&&/^[a-f0-9]{48}$/.test(token),onComplete:bytes=>{if(version===serial&&token&&/^[a-f0-9]{48}$/.test(token))current={token,bytes};}}),{status:response.status,statusText:response.statusText,headers});
+      return new Response(collectStream(source,{capture:!!token&&/^[a-f0-9]{48}$/.test(token),onEnd,onComplete:bytes=>{if(version===serial&&token&&/^[a-f0-9]{48}$/.test(token))current={token,bytes};}}),{status:response.status,statusText:response.statusText,headers});
     },
     clear(){serial++;current=undefined;},
   };
 }
-module.exports={TYPE,MAX_VALUE,createIndex,encodeChunk,deltaStream,decodeStream,collectStream,createFlightTransport};
+module.exports={TYPE,MAX_VALUE,createIndex,encodeChunk,deltaStream,decodeStream,collectStream,createFlightTransport,ownFlightStream};