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

package/build/bundle-runtime.mjs

@@ -1,6 +1,9 @@
 import { build } from 'esbuild';
-import { lstat, realpath, readdir, writeFile, unlink } from 'node:fs/promises';
+import { lstat, realpath, readdir, writeFile, unlink,readFile } from 'node:fs/promises';
 import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {version as esbuildVersion} from 'esbuild';
+import {privateCacheDirectory,readCacheRecord,writeCacheRecord} from './persistent-cache.mjs';
 
 // Paths used by the native worker, generated application modules, prerender,
 // standalone tracing, compatibility modules and the runtime lifecycle contract.
@@ -12,7 +15,7 @@ export const runtimeEntryNames = Object.freeze([
 ].sort());
 
 /** Run once, after compiling application/Edge graphs and before any prerender. */
-export async function bundleRuntime(stage) {
+export async function bundleRuntime(stage,{projectRoot,sourceDirectory}={}) {
   const resolvedStage = path.resolve(stage);
   if (!path.basename(resolvedStage).startsWith('.prnext-build-')) {
     throw new Error('Runtime bundling requires an unpublished PRNext build stage.');
@@ -26,23 +29,44 @@ export async function bundleRuntime(stage) {
   if (path.relative(canonicalStage, canonicalRuntime) !== 'runtime') {
     throw new Error('Runtime bundling escaped the build stage.');
   }
-  const entries = await readdir(runtime, { withFileTypes: true });
-  const originals = entries.filter(entry => entry.name.endsWith('.mjs'));
+  const input=sourceDirectory?await realpath(sourceDirectory):runtime;
+  const entries = await readdir(input, { withFileTypes: true });
+  const originals = entries.filter(entry => entry.name.endsWith('.mjs')&&!entry.name.endsWith('.test.mjs'));
   if (originals.some(entry => !entry.isFile() || entry.isSymbolicLink())) {
     throw new Error('Runtime source modules must be ordinary files.');
   }
   for (const name of runtimeEntryNames) {
     if (!originals.some(entry => entry.name === `${name}.mjs`)) throw new Error(`Missing runtime entry ${name}.mjs`);
   }
+  const sources=new Map();
+  // Production compiles the installed sources directly. Only generated stage
+  // overrides (currently the bundled env loader) replace an installed module.
+  // Hash and compile the same captured bytes; do not trust mtimes or skip app
+  // graph callbacks. This avoids copying hundreds of modules into every stage.
+  for(const entry of originals){
+    let file=path.join(input,entry.name);
+    if(sourceDirectory){const override=path.join(runtime,entry.name);const info=await lstat(override).catch(e=>{if(e.code!=='ENOENT')throw e;});if(info){if(!info.isFile()||info.isSymbolicLink())throw Error('Runtime overrides must be ordinary files');file=override;}}
+    sources.set(path.join(input,entry.name),await readFile(file));
+  }
+  let directory,key,cached;
+  if(projectRoot){
+    directory=await privateCacheDirectory(projectRoot,'runtime-bundle-v2');
+    if(directory){
+      const hash=createHash('sha256').update(esbuildVersion).update(JSON.stringify(runtimeEntryNames)).update(await readFile(new URL('./bundle-runtime.mjs',import.meta.url)));
+      for(const entry of [...originals].sort((a,b)=>a.name.localeCompare(b.name)))hash.update(JSON.stringify([entry.name,createHash('sha256').update(sources.get(path.join(input,entry.name))).digest('hex')]));
+      key=hash.digest('hex');cached=await readCacheRecord(directory,key);
+    }
+  }
   // write:false makes compilation atomic with respect to the source runtime:
   // no files change if parsing or resolution fails. The virtual output is a
   // sibling so all relative paths have the same depth as the final runtime.
   const virtualOutput = path.join(resolvedStage, '.runtime-bundle');
-  const result = await build({
-    absWorkingDir: runtime,
-    entryPoints: runtimeEntryNames.map(name => path.join(runtime, `${name}.mjs`)),
+  const validCache=cached&&Array.isArray(cached.files)&&cached.files.length<=128&&cached.files.every(item=>Array.isArray(item)&&item.length===2&&/^[\w-]+\.mjs$/.test(item[0])&&typeof item[1]==='string')&&new Set(cached.files.map(([name])=>name)).size===cached.files.length&&runtimeEntryNames.every(name=>cached.files.some(([file])=>file===name+'.mjs'));
+  const result = validCache?null:await build({
+    absWorkingDir: input,
+    entryPoints: runtimeEntryNames.map(name => path.join(input, `${name}.mjs`)),
     outdir: virtualOutput,
-    outbase: runtime,
+    outbase: input,
     entryNames: '[name]',
     chunkNames: '_shared-[hash]',
     outExtension: { '.js': '.mjs' },
@@ -60,23 +84,27 @@ export async function bundleRuntime(stage) {
     metafile: true,
     write: false,
     logLevel: 'silent',
+    plugins:[{name:'prnext-runtime-snapshot',setup(build){build.onLoad({filter:/\.mjs$/},args=>sources.has(args.path)?{contents:sources.get(args.path),loader:'js',resolveDir:path.dirname(args.path)}:undefined);}}],
   });
   const emitted = new Map();
-  for (const file of result.outputFiles) {
+  if(validCache)for(const [name,contents]of cached.files)emitted.set(name,Buffer.from(contents));
+  for (const file of result?.outputFiles||[]) {
     if (path.dirname(file.path) !== virtualOutput || !file.path.endsWith('.mjs')) {
       throw new Error('Runtime bundler emitted a file outside its flat output directory.');
     }
     emitted.set(path.basename(file.path), file.contents);
   }
   if (runtimeEntryNames.some(name => !emitted.has(`${name}.mjs`))) throw new Error('Runtime bundle omitted a required entry.');
+  if(directory&&!validCache)await writeCacheRecord(directory,key,{files:[...emitted].map(([name,bytes])=>[name,Buffer.from(bytes).toString()])});
   // This is an unpublished, disposable stage. On any write failure buildProject
   // discards the stage and preserves the previous published build unchanged.
   for (const [name, contents] of emitted) await writeFile(path.join(runtime, name), contents);
-  for (const entry of originals) {
+  for (const entry of await readdir(runtime,{withFileTypes:true})) {
+    if(!entry.name.endsWith('.mjs')||!entry.isFile())continue;
     if (!emitted.has(entry.name)) await unlink(path.join(runtime, entry.name));
   }
   // JSON, CJS, license files and the OG assets directory are never traversed or
   // removed. The caller writes the normal runtime contract after prerender.
-  return { entryCount: runtimeEntryNames.length, moduleCount: emitted.size,
+  return { entryCount: runtimeEntryNames.length, moduleCount: emitted.size,cached:!!validCache,
     bytes: [...emitted.values()].reduce((sum, contents) => sum + contents.length, 0) };
 }

package/build/cache-components.mjs

@@ -15,7 +15,7 @@ export function transformCacheComponents(source, file, { enabled, projectRoot, m
   return cachedTransform('cache-components',source,[file,enabled,projectRoot,mode,buildId,configuredSegment,handlers],()=>transformUncached(source,file,{enabled,projectRoot,mode,buildId,configuredSegment,handlers}));
 }
 function transformUncached(source,file,{enabled,projectRoot,mode,buildId,configuredSegment,handlers}) {
-  const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: file, plugins: ['jsx', ...(/\.tsx?$/.test(file) ? ['typescript'] : [])] });
+  const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: file, plugins: ['jsx', ...(/\.[cm]?tsx?$/.test(file) ? ['typescript'] : [])] });
   let program;
   traverse(ast, { Program(value) { program = value; value.stop(); } });
   const moduleDirective = ast.program.directives.find(cacheDirective);

package/build/cache-handlers.mjs

@@ -47,7 +47,7 @@ export async function prepareCacheHandlers({ config, projectRoot, stage, environ
       platform: 'node', target: 'node22', format: 'esm', packages: 'external', logLevel: 'silent', define: environment,
       banner: { js: "import {createRequire as __prnextCreateRequire} from 'node:module';const require=__prnextCreateRequire(import.meta.url);" },
       plugins: [{ name: 'cache-handler-compatibility', setup(builder) {
-        builder.onResolve({ filter: /^(?:next|prnext|@thomas\.f\/prnext)\/(cache|headers|server)(?:\.js)?$/ }, ({ path: specifier }) => ({ path: `../compat/${frameworkImportName(specifier)}.cjs`, external: true }));
+        builder.onResolve({ filter: /^(?:next|prnext|@thomas\.f\/prnext)\/(cache(?:\/redis)?|headers|server)(?:\.js)?$/ }, ({ path: specifier }) => ({ path: `../compat/${frameworkImportName(specifier)}.cjs`, external: true }));
       } }],
     });
     result[name] = output;

package/build/check.mjs

@@ -7,34 +7,79 @@ import { scanProject } from './scan.mjs';
 import { compileCustomRoutes } from './custom-routes.mjs';
 import { validateReactVersions } from './app.mjs';
 import { snapshotEnvConfig } from '../runtime/env.mjs';
+import { environmentDiagnostics } from '../native/diagnostics.mjs';
+import { packageManifest } from '../native/resolve.mjs';
+import { projectTsconfig } from './typescript.mjs';
 
 /** Preflight an existing project without rewriting sources, dependencies or build output. */
-export async function checkProject(directory, { dev = false, validateDependencies = true } = {}) {
+export async function checkProject(directory, { dev = false, validateDependencies = true, validateEnvironment = validateDependencies } = {}, services = {}) {
   const root = path.resolve(directory);
-  const report = { root, ok: false, routes: [], versions: {}, errors: [], notes: [
+  const report = { root, ok: false, routes: [], versions: {}, errors: [], diagnostics: [], notes: [
     'Preflight validates configuration, route conventions and installed React versions. A successful production build and browser tests are still required.',
     'Webpack plugin hooks are validated during compilation; preflight only validates plugin shape and translated configuration.',
     'Rust handles HTTP, routing, static files, images and persistent caches. React and npm JavaScript execute on Node/V8.',
   ] };
+  const diagnostic = (id, error, action) => {
+    const item = { id, severity: 'error', message: error.message, action };
+    report.diagnostics.push(item);
+    report.errors.push(item.message);
+  };
   const restore = snapshotEnvConfig();
   try {
-    const config = await loadProjectConfig(root, {dev});
-    if (config.onDemandEntries) report.notes.push('onDemandEntries is accepted for Next plugin compatibility. PRNext compiles all development routes and does not use Next\'s in-memory page eviction queue; these retention settings do not change its memory limits.');
-    await compileCustomRoutes(config);
-    const project = await scanProject(root, {basePath:config.basePath,pageExtensions:config.pageExtensions,i18n:config.i18n});
-    await validateCompilerConfig(config,root,{dev,edge:project.middleware?.runtime==='edge'||project.routes.some(route=>route.cacheConfig?.runtime==='edge'||route.handlerConfig?.runtime==='edge')});
+    let config, project;
+    try { config = await loadProjectConfig(root, {dev}); }
+    catch (error) { diagnostic('config', error, 'Correct the project configuration and run check again.'); }
+    if (config) {
+    if (config.onDemandEntries) report.notes.push('Development compiles requested routes and retains open browser routes. onDemandEntries controls inactive route retention; middleware, rewrites and parallel/intercepting routing use the complete graph.');
+    try { await compileCustomRoutes(config); }
+    catch (error) { diagnostic('custom-routes', error, 'Correct redirects, headers or rewrites in the configuration.'); }
+    try { project = await scanProject(root, {basePath:config.basePath,pageExtensions:config.pageExtensions,i18n:config.i18n}); }
+    catch (error) { diagnostic('routes', error, 'Correct the conflicting route files or route conventions.'); }
+    try { await validateCompilerConfig(config,root,{dev,edge:project?.middleware?.runtime==='edge'||project?.routes.some(route=>route.cacheConfig?.runtime==='edge'||route.handlerConfig?.runtime==='edge')}); }
+    catch (error) { diagnostic('compiler', error, 'Correct the compiler options or install the required compiler plugins.'); }
+    try {
+      const tsconfig = await projectTsconfig(root, config);
+      if (tsconfig) {
+        let ts;
+        try { ts = createRequire(path.join(root, 'package.json'))('typescript'); }
+        catch {
+          const required = config.typedRoutes || config.typescript && !config.typescript.ignoreBuildErrors;
+          const item = { id: 'typescript', severity: required ? 'error' : 'warning', message: 'TypeScript configuration exists, but TypeScript is not installed in the application.', action: 'Install typescript as an application dev dependency.' };
+          report.diagnostics.push(item); if (required) report.errors.push(item.message);
+        }
+        if (ts) {
+          const parsed = ts.getParsedCommandLineOfConfigFile(tsconfig, { noEmit: true }, { ...ts.sys, onUnRecoverableConfigFileDiagnostic: value => { throw new Error(ts.flattenDiagnosticMessageText(value.messageText, '\n')); } });
+          if (!parsed || parsed.errors.length) throw new Error(parsed ? ts.formatDiagnostics(parsed.errors, { getCanonicalFileName: name => name, getCurrentDirectory: () => root, getNewLine: () => '\n' }) : 'TypeScript configuration could not be parsed.');
+          report.versions.typescript = ts.version;
+          report.diagnostics.push({ id: 'typescript', severity: 'info', message: `TypeScript ${ts.version} configuration is valid. Semantic errors require prnext typecheck.` });
+        }
+      } else if (config.typedRoutes || config.typescript && !config.typescript.ignoreBuildErrors) throw new Error('TypeScript is enabled, but tsconfig.json does not exist.');
+    } catch (error) { diagnostic('typescript', error, 'Correct typescript.tsconfigPath or the selected TypeScript configuration.'); }
+    }
+    if (project) {
     report.routes = project.routes.filter(route=>!route.internal).map(({pattern,kind,router})=>({pattern,kind,router:router||'pages'}));
+    }
     const resolve = createRequire(path.join(root,'package.json'));
     for (const name of ['next','react','react-dom','react-server-dom-webpack']) {
       try { report.versions[name] = JSON.parse(await readFile(resolve.resolve(`${name}/package.json`),'utf8')).version; }
       catch { report.versions[name] = null; }
     }
     if (validateDependencies) {
-      if (project.routes.some(route=>route.router==='app')) await validateReactVersions(resolve);
-      else if (!report.versions.react || !report.versions['react-dom']) throw new Error('Install react and react-dom in the project before building Pages routes.');
+      try {
+        if (project?.routes.some(route=>route.router==='app')) await validateReactVersions(resolve);
+        else {
+          const names = ['react', 'react-dom'];
+          if (names.some(name => report.versions[name] !== packageManifest.peerDependencies[name])) throw new Error(`Pages routes require the declared React peer versions. Resolved ${names.map(name => `${name}@${report.versions[name] || 'missing'}`).join(', ')}. Install ${names.map(name => `${name}@${packageManifest.peerDependencies[name]}`).join(' ')} in the application.`);
+        }
+      } catch (error) { diagnostic('react', error, 'Install the matching React protocol packages shown in this error.'); }
     } else report.notes.push('Installed React versions have not been validated yet; migration checks them after dependency installation.');
-    report.ok = true;
-  } catch (error) { report.errors.push(error.message); }
+    if (validateEnvironment) {
+      const diagnostics = await (services.environmentDiagnostics || environmentDiagnostics)();
+      report.diagnostics.push(...diagnostics);
+      report.errors.push(...diagnostics.filter(item => item.severity === 'error').map(item => item.message));
+    }
+    report.ok = report.errors.length === 0;
+  } catch (error) { diagnostic('preflight', error, 'Resolve the reported file or installation error and retry.'); }
   finally { restore(); }
   return report;
 }

package/build/compact-css.mjs

@@ -0,0 +1,53 @@
+import postcss from 'postcss';
+import selectors from 'postcss-selector-parser';
+import values from 'postcss-value-parser';
+import { createHash } from 'node:crypto';
+
+// Names are independent of compilation order and of which routes are built.
+// A collision fails the build instead of changing one of two published maps.
+export function compactCssModule(css, exports, {globals = new Set(), hash = name => 'p' + createHash('sha256').update(name).digest('base64url').slice(0, 10)} = {}) {
+  const names = new Map(), reverse = new Map();
+  for (const list of Object.values(exports)) for (const name of list.split(/\s+/).filter(Boolean)) {
+    if (names.has(name) || globals.has(name)) continue;
+    const short = hash(name);
+    if (!/^[a-zA-Z_][\w-]*$/.test(short) || globals.has(short) && short!==name || reverse.has(short) && reverse.get(short) !== name) throw new Error('CSS Module compact-name collision.');
+    names.set(name, short); reverse.set(short, name);
+  }
+  const root = postcss.parse(css);
+  root.walkRules(rule => {
+    rule.selector = selectors(ast => ast.walkClasses(node => {
+      if (names.has(node.value)) node.value = names.get(node.value);
+    })).processSync(rule.selector);
+  });
+  root.walkAtRules(/^(?:-webkit-)?keyframes$/i, rule => {
+    const parsed = values(rule.params);
+    parsed.walk(node => { if (node.type === 'word' && names.has(node.value)) node.value = names.get(node.value); });
+    rule.params = parsed.toString();
+  });
+  root.walkDecls(/^(?:-webkit-)?animation(?:-name)?$/i, declaration => {
+    const parsed = values(declaration.value);
+    parsed.walk(node => { if (node.type === 'word' && names.has(node.value)) node.value = names.get(node.value); });
+    declaration.value = parsed.toString();
+  });
+  return { css: root.toString(), names:[...names], mapping: Object.fromEntries(Object.entries(exports).map(([key, list]) => [key, list.split(/\s+/).map(name => names.get(name) || name).join(' ')])) };
+}
+
+export function globalCssNames(css, {local = true} = {}, result = new Set()) {
+  const root = postcss.parse(css);
+  root.walkRules(rule => {
+    selectors(ast => ast.each(selector => {
+      let global = !local;
+      selector.each(node => {
+        if (node.type === 'pseudo' && [':global',':local'].includes(node.value)) {
+          if (node.nodes?.length) { if (node.value === ':global') node.walkClasses(item=>result.add(item.value)); }
+          else global = node.value === ':global';
+        } else if (global) { if(node.type==='class') result.add(node.value); node.walkClasses?.(item=>result.add(item.value)); }
+      });
+    })).processSync(rule.selector);
+  });
+  root.walkDecls(/^composes$/i, declaration => {
+    const words = values(declaration.value).nodes.filter(node=>node.type==='word').map(node=>node.value);
+    if (words.at(-1)==='global' && words.at(-2)==='from') for(const name of words.slice(0,-2)) result.add(name);
+  });
+  return result;
+}

package/build/compilation-cache.mjs

@@ -0,0 +1,269 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { lstat, readFile, opendir, realpath, readlink, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { version as esbuildVersion } from 'esbuild';
+import { buildCacheIdentity, cacheHash, privateCacheDirectory, readCacheRecord, writeCacheRecord } from './persistent-cache.mjs';
+import {mapConcurrent} from './concurrent.mjs';
+import { readCompilationRecord, writeCompilationRecord } from './compilation-store.mjs';
+
+// Graph outputs have a narrower contract than source transforms. In particular,
+// application graph callbacks discover actions, boundaries and font assets. They
+// must run on every generation and are never skipped by this cache.
+const reports = new AsyncLocalStorage();
+const MAX_FILES = 4096, MAX_DIRECTORIES = 8192, MAX_NAMES = 32768;
+const MAX_FILE_BYTES = 16 * 1024 * 1024, MAX_BYTES = 48 * 1024 * 1024;
+const RECORD_LIMIT = 64 * 1024 * 1024;
+const SHA = /^[a-f0-9]{64}$/;
+const frameworkDirectory=name=>['.git','.prnext-cache','.prnext','.prnext-incremental-stage'].includes(name)||/^\.prnext-(?:build|backup|config|postcss)-/.test(name);
+const frameworkPointer=name=>/^\.prnext-output(?:\.json|-.+\.tmp)$/.test(name);
+const ignored = entry => entry.isDirectory() && (entry.name==='node_modules'||frameworkDirectory(entry.name)) || frameworkPointer(entry.name);
+const safePath = file => typeof file === 'string' && file.length < 32768 && path.isAbsolute(file) && !file.includes('\0');
+const inside = (root, file) => { const relative = path.relative(root, file); return relative === '' || !path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep); };
+export const withCompilationGraphCacheReporting = run => reports.run({ kinds: new Map(), identities:new Map(), listings:new Map(),listingNames:0 }, run);
+export function compilationGraphCacheReport() {
+  const kinds = [...(reports.getStore()?.kinds || [])].map(([kind, value]) => ({ kind, ...value, reasons: { ...value.reasons } }));
+  return { version: 1, scope: 'eligible-production-compilation-graphs', kinds,
+    hits: kinds.reduce((sum, item) => sum + item.hits, 0), misses: kinds.reduce((sum, item) => sum + item.misses, 0),
+    bypasses: kinds.reduce((sum, item) => sum + item.bypasses, 0), reusedBytes: kinds.reduce((sum, item) => sum + item.reusedBytes, 0) };
+}
+function record(kind, outcome, reason, bytes = 0) {
+  const state = reports.getStore(); if (!state) return;
+  if (!state.kinds.has(kind)) state.kinds.set(kind, { hits: 0, misses: 0, bypasses: 0, writes: 0, reusedBytes: 0, reasons: {} });
+  const item = state.kinds.get(kind); item[outcome]++; item.reusedBytes += bytes;
+  if (reason) item.reasons[reason] = (item.reasons[reason] || 0) + 1;
+}
+function serializable(value) {
+  if (value === null || ['string', 'number', 'boolean'].includes(typeof value)) return true;
+  if (Array.isArray(value)) return value.every(serializable);
+  return value && Object.getPrototypeOf(value) === Object.prototype && Object.values(value).every(item => item === undefined || serializable(item));
+}
+const directorySignature=info=>[info.dev,info.ino,info.mode,info.mtimeNs,info.ctimeNs].join(':');
+async function directoryEntries(directory,budget){
+  const state=reports.getStore(),before=await lstat(directory,{bigint:true});
+  if(!before.isDirectory()||before.isSymbolicLink())throw Error('unstable-resolution');
+  const signature=directorySignature(before),saved=state?.listings.get(directory);
+  if(saved?.signature===signature){
+    const after=await lstat(directory,{bigint:true});
+    if(directorySignature(after)===signature){budget.names+=saved.entries.length;if(budget.names>MAX_NAMES)throw Error('resolution-limit');return {entries:saved.entries,info:after,stable:true};}
+  }
+  const entries=[];
+  for await(const entry of await opendir(directory)){if(++budget.names>MAX_NAMES)throw Error('resolution-limit');entries.push(entry);}
+  const after=await lstat(directory,{bigint:true}),stable=signature===directorySignature(after);
+  if(state&&stable){
+    if(state.listings.has(directory)){state.listingNames-=state.listings.get(directory).entries.length;state.listings.delete(directory);}
+    while(state.listings.size&&(state.listings.size>=MAX_DIRECTORIES||state.listingNames+entries.length>MAX_NAMES)){
+      const [oldest,value]=state.listings.entries().next().value;state.listings.delete(oldest);state.listingNames-=value.entries.length;
+    }
+    if(entries.length<=MAX_NAMES){state.listings.set(directory,{signature,entries});state.listingNames+=entries.length;}
+  }
+  return {entries,info:after,stable};
+}
+async function fileDigest(file, started = Infinity, budget = {bytes:0}) {
+  const before = await lstat(file);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_FILE_BYTES || before.mtimeMs > started || before.ctimeMs > started) throw Error('unstable-input');
+  budget.bytes+=before.size;if(budget.bytes>MAX_BYTES)throw Error('dependency-limit');
+  const bytes = await readFile(file), after = await lstat(file);
+  if (bytes.length !== before.size || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw Error('unstable-input');
+  return cacheHash(bytes);
+}
+async function directoryDigest(directory, budget, started = Infinity, lookup = false, excluded = []) {
+  let listing;
+  try{listing=await directoryEntries(directory,budget);}catch(error){if(error.code==='ENOENT')return 'missing';throw error;}
+  const {info}=listing;
+  if(started!==Infinity&&(Number(info.mtimeNs)/1e6>started||Number(info.ctimeNs)/1e6>started))throw Error('unstable-resolution');
+  const namesAt=async listing=>{
+    const entries=listing.entries.filter(entry=>lookup?['package.json','tsconfig.json','jsconfig.json','.browserslistrc','browserslist','node_modules'].includes(entry.name):!ignored(entry)&&!excluded.includes(path.join(directory,entry.name)));
+    entries.sort((a,b)=>a.name.localeCompare(b.name));
+    return mapConcurrent(entries,async entry=>[entry.name,entry.isDirectory()?'directory':entry.isSymbolicLink()?['link',await readlink(path.join(directory,entry.name))]:entry.isFile()?'file':'other']);
+  };
+  const names=await namesAt(listing),digest=cacheHash(JSON.stringify(names));
+  if(!listing.stable&&cacheHash(JSON.stringify(await namesAt(await directoryEntries(directory,budget))))!==digest)throw Error('unstable-resolution');
+  return digest;
+}
+async function snapshot(root, dependencies, { started = Infinity, imports = [], rejectTsconfig = false, styleTargets=false, baseline, excluded = [] } = {}) {
+  if (!Array.isArray(dependencies) || dependencies.length > MAX_FILES || dependencies.some(file => !safePath(file))) throw Error('dependency-limit');
+  const files = new Set(dependencies), directories = new Set(), trees = new Set([root]), fullDirectories = new Set();
+  if(dependencies.some(file=>path.dirname(file).split(path.sep).some(frameworkDirectory)||frameworkPointer(path.basename(file))||excluded.some(directory=>inside(directory,file))))throw Error('generated-input');
+  for(const name of ['package.json','package-lock.json','npm-shrinkwrap.json','pnpm-lock.yaml','yarn.lock','bun.lock','bun.lockb','.env','.env.local','.env.production','.env.production.local','.env.development','.env.development.local','.env.test','.env.test.local']){
+    const file=path.join(root,name);try{const info=await lstat(file);if(!info.isFile()||info.isSymbolicLink())throw Error('unsafe-config');files.add(file);}catch(error){if(error.code!=='ENOENT')throw error;}
+  }
+  const addParents = async file => {
+    let directory = path.dirname(file);
+    while (true) {
+      directories.add(directory);
+      // Node's package search includes missing nearer node_modules directories.
+      directories.add(path.join(directory, 'node_modules'));
+      for (const name of ['package.json', 'tsconfig.json', 'jsconfig.json', ...(styleTargets?['.browserslistrc','browserslist']:[])]) {
+        const candidate = path.join(directory, name);
+        try {
+          const info = await lstat(candidate);
+          if(name==='browserslist'&&info.isDirectory())continue;
+          if (rejectTsconfig && /^(?:ts|js)config\.json$/.test(name)) throw Error('untracked-tsconfig');
+          if (!info.isFile() || info.isSymbolicLink() || info.size>MAX_FILE_BYTES) throw Error('unsafe-config');
+          if(styleTargets&&(name==='.browserslistrc'||name==='browserslist'||name==='package.json')){
+            const source=await readFile(candidate,'utf8');
+            const targets=name==='package.json'?JSON.stringify(JSON.parse(source).browserslist):source;
+            if(typeof targets==='string'&&/\b(?:extends|stats)\b/i.test(targets))throw Error('custom-browser-targets');
+          }
+          files.add(candidate);
+        } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      }
+      const parent = path.dirname(directory); if (parent === directory) break; directory = parent;
+    }
+  };
+  for (const file of dependencies) {
+    await addParents(file);
+    // Package export/browser maps may choose an absent file anywhere inside the
+    // package. Directory names, including absence, participate in invalidation.
+    let directory = path.dirname(file);
+    while (true) {
+      try { if ((await lstat(path.join(directory, 'package.json'))).isFile()) { trees.add(directory); break; } }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+      const parent = path.dirname(directory); if (parent === directory) break; directory = parent;
+    }
+  }
+  for (const [importer, specifier] of imports) {
+    if (typeof specifier !== 'string' || /^(?:node:|[./\\]|[A-Za-z]:)/.test(specifier)) continue;
+    const parts = specifier.split('/'), name = parts.slice(0, specifier.startsWith('@') ? 2 : 1).join('/');
+    if (!name || name.includes('\0') || name.split('/').some(part => part === '..')) throw Error('unsafe-resolution');
+    let directory = path.dirname(importer);
+    while (true) {
+      const candidate = path.join(directory, 'node_modules', name);
+      try { const info = await lstat(candidate); if (info.isSymbolicLink()) throw Error('linked-package'); if (info.isDirectory()) trees.add(candidate); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+      const parent = path.dirname(directory); if (parent === directory) break; directory = parent;
+    }
+  }
+  const walked={names:0};
+  const walk = async (directory, depth = 0) => {
+    if (depth > 32 || directories.size > MAX_DIRECTORIES) throw Error('resolution-limit');
+    const listing=await directoryEntries(directory,walked);
+    directories.add(directory); fullDirectories.add(directory);
+    for (const entry of listing.entries) {
+      if (ignored(entry) || excluded.includes(path.join(directory,entry.name))) continue;
+      if (entry.isSymbolicLink()) throw Error('linked-input');
+      if (entry.isDirectory()) await walk(path.join(directory, entry.name), depth + 1);
+    }
+  };
+  for (const tree of trees) await walk(tree);
+  if (files.size > MAX_FILES || directories.size > MAX_DIRECTORIES) throw Error('dependency-limit');
+  const budget = { names: 0,bytes:0 };
+  const knownFiles = new Map(baseline?.files || []), knownDirectories = new Map((baseline?.directories || []).map(item => [item[0], item]));
+  const result = { excluded, files: await mapConcurrent([...files].sort(),async file => [file, await fileDigest(file, knownFiles.has(file) ? Infinity : started,budget)]),
+    directories: await mapConcurrent([...directories].sort(),async directory => {
+      const lookup = !fullDirectories.has(directory) && path.basename(directory) !== 'node_modules';
+      const known = knownDirectories.get(directory), comparable = known && known[2] === lookup;
+      return [directory, await directoryDigest(directory, budget, comparable ? Infinity : started, lookup, excluded), lookup];
+    }) };
+  for (const [file,digest] of result.files) if (knownFiles.has(file) && knownFiles.get(file) !== digest) throw Error('unstable-input');
+  for (const [directory,digest,lookup] of result.directories) {
+    const known = knownDirectories.get(directory);
+    if (known && known[2] === lookup && known[1] !== digest) throw Error('unstable-resolution');
+  }
+  return result;
+}
+async function validSnapshot(value) {
+  const pairs = (list, missing) => Array.isArray(list) && list.length <= (missing ? MAX_DIRECTORIES : MAX_FILES)
+    && new Set(list.map(item => item?.[0])).size === list.length
+    && list.every(item => Array.isArray(item) && item.length === (missing ? 3 : 2) && safePath(item[0]) && (SHA.test(item[1]) || missing && item[1] === 'missing') && (!missing || typeof item[2] === 'boolean'));
+  if (!value || !Array.isArray(value.excluded) || value.excluded.length>32 || !value.excluded.every(safePath) || !pairs(value.files, false) || !pairs(value.directories, true)) return false;
+  const budget = { names: 0,bytes:0 };
+  for (const [file, digest] of value.files) if (await fileDigest(file,Infinity,budget) !== digest) return false;
+  for (const [directory, digest, lookup] of value.directories) if (await directoryDigest(directory, budget, Infinity, lookup, value.excluded) !== digest) return false;
+  return true;
+}
+/** Framework-owned graph producers explicitly return dependencies and payloads. */
+export async function cachedCompilation({ root, kind, settings, inputs = [], excluded = [], enabled = true, reason, validate, produce, bytes = () => 0, rejectTsconfig = false,styleTargets=false, binary = false }) {
+  if (!enabled || process.env.PRNEXT_BUILD_CACHE === '0' || !serializable(settings)) {
+    record(kind, 'bypasses', process.env.PRNEXT_BUILD_CACHE === '0' ? 'disabled' : reason || 'unsupported-configuration'); return (await produce()).value;
+  }
+  let directory, key;
+  try {
+    root = await realpath(root); directory = await privateCacheDirectory(root, binary ? 'compilation-graphs-v2' : 'compilation-graphs-v1');
+    if(!directory)throw Error('unavailable');
+    // Only metadata for the same current environment is shared. Individual
+    // graph snapshots still re-hash source/config bytes and validate listings.
+    const state=reports.getStore(),environment=cacheHash(JSON.stringify(Object.entries(process.env).sort())),identityKey=root+'\0'+environment;
+    if(state&&!state.identities.has(identityKey)){
+      if(state.identities.size>=8)state.identities.delete(state.identities.keys().next().value);
+      state.identities.set(identityKey,buildCacheIdentity(root));
+    }
+    const identity = directory && await (state?.identities.get(identityKey)||buildCacheIdentity(root));
+    if (!identity) throw Error('unavailable');
+    if(excluded.length>32||!excluded.every(file=>safePath(file)&&inside(root,file)&&file!==root))throw Error('unsafe-output-directory');
+    key = cacheHash(JSON.stringify([identity, esbuildVersion, kind, settings, excluded]));
+    const cached = binary ? await readCompilationRecord(directory, key) : await readCacheRecord(directory, key, RECORD_LIMIT);
+    if (cached?.format === 1 && validate(cached.value) && await validSnapshot(cached.snapshot)) {
+      record(kind, 'hits', undefined, bytes(cached.value)); return cached.value;
+    }
+  } catch { /* Corrupt, excessive or unavailable caches are optional. */ }
+  record(kind, 'misses');
+  let baseline, baselineError;
+  if(directory && key)try{baseline=await snapshot(root,inputs,{rejectTsconfig,excluded,styleTargets});}catch(error){baselineError=error;}
+  const started = Date.now(), produced = await produce();
+  if (directory && key && validate(produced.value)) try {
+    if(!baseline)throw baselineError || Error('snapshot-unavailable');
+    const current = await snapshot(root, produced.dependencies, { started, imports: produced.imports, rejectTsconfig,styleTargets, baseline, excluded });
+    const saved = { format: 1, snapshot: current, value: produced.value };
+    if (await (binary ? writeCompilationRecord(directory, key, saved) : writeCacheRecord(directory, key, saved, RECORD_LIMIT,{maxFiles:1024}))) record(kind, 'writes');
+  } catch (error) { record(kind, 'bypasses', ['unstable-input', 'unstable-resolution', 'untracked-tsconfig', 'linked-package', 'linked-input', 'resolution-limit', 'dependency-limit','generated-input','custom-browser-targets'].includes(error.message) ? error.message : 'snapshot-unavailable'); }
+  else if(!validate(produced.value))record(kind,'bypasses','generation-specific-output');
+  return produced.value;
+}
+
+function validMetafile(value){
+  const object=value=>value&&typeof value==='object'&&!Array.isArray(value),text=value=>typeof value==='string'&&value.length<32768&&!value.includes('\0');
+  const count=value=>Number.isSafeInteger(value)&&value>=0;
+  const imports=value=>Array.isArray(value)&&value.length<=MAX_FILES&&value.every(item=>object(item)&&text(item.path)&&text(item.kind)&&(item.external===undefined||typeof item.external==='boolean'));
+  return object(value)&&object(value.inputs)&&object(value.outputs)&&Object.keys(value.inputs).length<=MAX_FILES&&Object.keys(value.outputs).length<=MAX_FILES
+    &&Object.entries(value.inputs).every(([file,input])=>text(file)&&object(input)&&count(input.bytes)&&imports(input.imports))
+    &&Object.entries(value.outputs).every(([file,output])=>text(file)&&object(output)&&count(output.bytes)&&imports(output.imports)
+      &&(output.entryPoint===undefined||text(output.entryPoint))&&(output.cssBundle===undefined||text(output.cssBundle))
+      &&Array.isArray(output.exports)&&output.exports.length<=MAX_FILES&&output.exports.every(text)&&object(output.inputs)
+      &&Object.keys(output.inputs).length<=MAX_FILES&&Object.entries(output.inputs).every(([file,input])=>text(file)&&object(input)&&count(input.bytesInOutput)));
+}
+function validGraph(value) {
+  return value && Array.isArray(value.files) && value.files.length > 0 && value.files.length <= MAX_FILES
+    && value.files.every(file => Array.isArray(file) && file.length === 3 && typeof file[0] === 'string' && !path.isAbsolute(file[0])
+      && !/[\0<>:"|?*]/.test(file[0]) && file[0].split(/[\\/]/).every(part => part && part !== '.' && part !== '..') && file[1] instanceof Uint8Array && file[1].byteLength <= MAX_FILE_BYTES && typeof file[2] === 'string')
+    && new Set(value.files.map(file => file[0])).size === value.files.length
+    && value.files.reduce((sum, file) => sum + file[1].byteLength, 0) <= MAX_BYTES
+    && validMetafile(value.metafile);
+}
+const deepMap = (value, convert) => typeof value === 'string' ? convert(value) : Array.isArray(value) ? value.map(item => deepMap(item, convert))
+  : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).map(([key, item]) => [convert(key), deepMap(item, convert)])) : value;
+/** Cache native esbuild graphs only; plugins and generated entries need replay. */
+export async function cachedGraphBuild(options, { root, stage, dev = false, config = {} }, compile) {
+  const output = options.outdir || options.outfile && path.dirname(options.outfile);
+  const permitted = !dev && !(options.plugins?.length) && options.bundle === true && output && stage && inside(stage, path.resolve(output))
+    && !options.stdin && !options.tsconfig && !options.tsconfigRaw && options.mangleCache===undefined && !config.webpack && !Object.keys(config.turbopack?.rules || {}).length;
+  if (!permitted) { record('javascript', 'bypasses', dev ? 'development' : options.plugins?.length ? 'graph-side-effects' : 'unsupported-configuration'); return compile(options); }
+  const token = '__PRNEXT_COMPILATION_STAGE__', toSaved = value => value.replaceAll(stage,()=>token).replaceAll(path.basename(stage),()=>token), fromSaved = value => value.replaceAll(token,()=>stage);
+  const rawSignature = { ...options, plugins: undefined, write: false, metafile: true };
+  if(!serializable(rawSignature)){record('javascript','bypasses','unsupported-configuration');return compile(options);}
+  const signature = deepMap(rawSignature, toSaved);
+  if (!serializable(signature)) { record('javascript', 'bypasses', 'unsupported-configuration'); return compile(options); }
+  let fresh;
+  const entries = Array.isArray(options.entryPoints) ? options.entryPoints.map(entry=>typeof entry==='string'?entry:entry.in) : Object.values(options.entryPoints || {});
+  const excluded = [path.resolve(root,config.distDir || '.prnext'),...(config.output==='export'?[path.join(root,'out')]:[])];
+  const saved = await cachedCompilation({ root, kind: 'javascript', settings: signature, inputs:entries.map(file=>path.resolve(options.absWorkingDir || process.cwd(),file)), excluded, validate: validGraph, rejectTsconfig: true, binary: true,
+    bytes: value => value.files.reduce((sum, file) => sum + file[1].byteLength, 0),
+    produce: async () => {
+      fresh = await compile({ ...options, write: false, metafile: true });
+      // Warnings may carry plugin details/locations; do not replay approximate diagnostics.
+      if (fresh.warnings?.length) return { value: null, dependencies: [] };
+      if(JSON.stringify(fresh.metafile).includes(token))return {value:null,dependencies:[]};
+      const dependencies = Object.keys(fresh.metafile.inputs).map(file => path.resolve(options.absWorkingDir || process.cwd(), file));
+      if (dependencies.some(file => inside(stage, file))) return { value: null, dependencies: [] };
+      const files = fresh.outputFiles.map(file => [path.relative(output, file.path), file.contents, file.hash]);
+      if (fresh.outputFiles.some(file => Buffer.from(file.contents).includes(Buffer.from(stage)) || Buffer.from(file.contents).includes(Buffer.from(path.basename(stage))))) return { value: null, dependencies: [] };
+      const imports = Object.entries(fresh.metafile.inputs).flatMap(([file, input]) => input.imports.filter(item => item.external).map(item => [path.resolve(options.absWorkingDir || process.cwd(), file), item.path]));
+      return { value: { files, metafile: deepMap(fresh.metafile, toSaved) }, dependencies, imports };
+    } });
+  const outputFiles = saved ? saved.files.map(([name, data, hash]) => ({ path: path.join(output, name), contents: Buffer.from(data.buffer, data.byteOffset, data.byteLength), hash, get text() { return this.contents.toString(); } })) : fresh.outputFiles;
+  if (options.write !== false) for (const file of outputFiles) { await mkdir(path.dirname(file.path), { recursive: true }); await writeFile(file.path, file.contents); }
+  return { ...(fresh || { errors: [], warnings: [] }), ...(options.metafile ? { metafile: saved ? deepMap(saved.metafile, fromSaved) : fresh.metafile } : { metafile: undefined }),
+    outputFiles: options.write === false ? outputFiles : undefined };
+}
+
+export const compilationCacheLimits = Object.freeze({ files: MAX_FILES, directories: MAX_DIRECTORIES, names: MAX_NAMES, fileBytes: MAX_FILE_BYTES, bytes: MAX_BYTES });